# Virtual Host XML configuration file

## Introduction

This chapter describes how to configure Virtual Hosts using an XML file.

This is no longer the preferred approach for defining a VirtualHost and will likely be removed in a future release, however it is currently neccessary to support certain use cases such as per-virtualhost attribute configuration, and specialised store configuration such as for the BDB HA Message Store

Each XML Virtual Host configuration file can hold configuration for a single Virtual Host or multiple Virtual Hosts. For an example file (with multiple VirtualHosts), see

## Configuring ACL

provides the details of ACL, rules, formats, etc.

To apply an ACL on a single virtualhost named test, add the following to the virtualhosts.xml:

    <virtualhost>
    ...
        <name>test</name>
        <test>
          ...
          <security>
            ...
            <acl>${conf}/vhost_test.acl</acl>
            ...
          </security>
          ...
        </test>
    </virtualhost>

A security section of configuration is used to declare the ACL

A path to an ACL file is configured (assuming that conf has been set to a suitable location such as ${QPID_HOME}/etc)

## Configuring MemoryMessageStore

An example of MemoryMessageStore configuration for a virtual host is shown below:

Configuring a VirtualHost to use the MemoryMessageStore

    <virtualhosts>
      <virtualhost>
        <name>vhostname</name>
        <vhostname>
          <store>
            <class>org.apache.qpid.server.store.MemoryMessageStore</class
          </store>
          ...
        </vhostname>
      </virtualhost>
    </virtualhosts>

## Configuring BDBMessageStore

In order to use the BDBMessageStore, you must configure it for each VirtualHost desired by updating the store element to specify the associated store class and provide a directory location for the data to be written, as shown below.

Configuring a VirtualHost to use the BDBMessageStore

    <virtualhosts>
      <virtualhost>
        <name>vhostname</name>
        <vhostname>
          <store>
            <class>org.apache.qpid.server.store.berkeleydb.BDBMessageStore</class>
            <environment-path>${QPID_WORK}/bdbstore/vhostname</environment-path>
          </store>
          ...
        </vhostname>
      </virtualhost>
    </virtualhosts>

## Configuring DerbyMessageStore

In order to use the DerbyMessageStore, you must configure it for each VirtualHost desired by updating the store element to specify the associated store class and provide a directory location for the data to be written, as shown below.

Configuring a VirtualHost to use the DerbyMessageStore

    <virtualhosts>
      <virtualhost>
        <name>vhostname</name>
        <vhostname>
          <store>
            <class>org.apache.qpid.server.store.DerbyMessageStore</class>
            <environment-path>${QPID_WORK}/derbystore/vhostname</environment-path>
          </store>
          ...
        </vhostname>
      </virtualhost>
    </virtualhosts>

## Configuring JDBCMessageStore

JDBCMessageStore can be configured on VirtualHost as in example shown below:

Configuring a VirtualHost to use the JDBCMessageStore

    <virtualhosts>
      <virtualhost>
        <name>vhostname</name>
        <vhostname>
          <store>
            <class>org.apache.qpid.server.store.jdbc.JDBCMessageStore</class>
            <connectionUrl>jdbc:oracle:thin:guest@guest//localhost:1521/orcl</connectionUrl>
          </store>
          ...
        </vhostname>
      </virtualhost>
    </virtualhosts>

## Configuring Exchanges

To declare Exchanges within Virtual Host configuration, add the appropriate xml to the virtualhost.xml configuration file within the `exchanges` element. An example of such declaration is shown below:

Configuring Exchanges on VirtualHost

    <virtualhosts>
      <virtualhost>
        <name>vhostname</name>
          ...
                <exchanges>
                    <exchange>
                        <type>direct</type>
                        <name>test.direct</name>
                        <durable>true</durable>
                    </exchange>
                    <exchange>
                        <type>topic</type>
                        <name>test.topic</name>
                    </exchange>
                </exchanges>
          ...
        </vhostname>
      </virtualhost>
    </virtualhosts>

## Configuring Queues

To create a priority, sorted or LVQ queue within configuration, add the appropriate xml to the virtualhost.xml configuration file within the `queues` element.

### Simple

For declaration of a simple queue define a queue entry in the virtual host configuration as in example below

Configuring a simple queue

    <queue>
        <name>my-simple-queue</name>
        <my-simple-queue>
            <exchange>amq.direct</exchange>
            <durable>true</durable>
        </my-simple-queue>
    </queue>

### Priority

To defining a priority queue, add a <priority>true</priority> element. By default the queue will have 10 distinct priorities.

Configuring a priority queue

    <queue>
        <name>myqueue</name>
        <myqueue>
            <exchange>amq.direct</exchange>
            <priority>true</priority>
        </myqueue>
    </queue>

If you require fewer priorities, it is possible to specify a `priorities` element (whose value is a integer value between 2 and 10 inclusive) which will give the queue that number of distinct priorities. When messages are sent to that queue, their effective priority will be calculated by partitioning the priority space. If the number of effective priorities is 2, then messages with priority 0-4 are treated the same as "lower priority" and messages with priority 5-9 are treated equivalently as "higher priority".

Configuring a priority queue with fewer priorities

    <queue>
        <name>myqueue</name>
        <myqueue>
            <exchange>amq.direct</exchange>
            <priority>true</priority>
            <priorities>4</priorities>
        </myqueue>
    </queue>

### Sorted

To define a sorted queue, add a `sortKey` element. The value of the `sortKey` element defines the message property to use the value of when sorting the messages put onto the queue.

Configuring a sorted queue

    <queue>
        <name>myqueue</name>
        <myqueue>
            <exchange>amq.direct</exchange>
            <sortKey>message-property-to-sort-by</sortKey>
        </myqueue>
    </queue>

### LVQ

To define a LVQ, add a `lvq` element with the value `true`. Without any further configuration this will define an LVQ which uses the JMS message property `qpid.LVQ_key` as the key for replacement.

Configuring a LVQ queue

    <queue>
        <name>myqueue</name>
        <myqueue>
            <exchange>amq.direct</exchange>
            <lvq>true</lvq>
        </myqueue>
    </queue>

If you wish to define your own property then you can do so using the `lvqKey` element.

Configuring a LVQ queue with custom message property name

    <queue>
        <name>myqueue</name>
        <myqueue>
            <exchange>amq.direct</exchange>
            <lvq>true</lvq>
            <lvqKey>ISIN</lvqKey>
        </myqueue>
    </queue>

## Configuring of Producer Flow Control

Flow control capacity and flow resume capacity are required to set on a queue or virtual host to enable Producer flow control.

Configuring a queue depth limit

    <queue>
        <name>test</name>
        <test>
            <exchange>amq.direct</exchange>

            <!-- set the queue capacity to 10Mb -->
            <capacity>10485760</capacity>

            <!-- set the resume capacity to 8Mb -->
            <flowResumeCapacity>8388608</flowResumeCapacity>
        </test>
    </queue>

The default for all queues on a virtual host can also be set

Configuring of default queue depth limit on virtualhost

    <virtualhosts>
        <virtualhost>
            <name>localhost</name>
            <localhost>

                <!-- set the queue capacity to 10Mb -->
                <capacity>10485760</capacity>

                <!-- set the resume capacity to 8Mb -->
                <flowResumeCapacity>8388608</flowResumeCapacity>
            </localhost>
        </virtualhost>
    </virtualhosts>

## Configuring of Disk Quota-based Flow Control

An example of quota configuration for the BDB message store is provided below.

Configuring a limit on a store

    <store>
       <class>org.apache.qpid.server.store.berkeleydb.BDBMessageStore</class>
       <environment-path>${work}/bdbstore/test</environment-path>
       <overfull-size>50000000</overfull-size>
       <underfull-size>45000000</underfull-size>
    </store>

## Configuring Transaction Timeouts

The JMS transaction timeouts are configured on each virtual host defined in the XML configuration files.

The default values for each of the parameters is 0, indicating that the particular check is disabled.

Any or all of the parameters can be set, using the desired value in milliseconds, and will be checked each time the housekeeping process runs, usually set to run every 30 seconds in standard configuration. The meaning of each property is as follows:

- openWarn - the time a transaction can be open for (with activity occurring on it) after which a warning alert will be issued.

- openClose - the time a transaction can be open for before the connection it is on is closed.

- idleWarn - the time a transaction can be idle for (with no activity occurring on it) after which a warning alert will be issued.

- idleClose - the time a transaction can be idle for before the connection it is on is closed.

The virtualhosts configuration is shown below, and must occur inside the //virtualhosts/virtualhost/name/ elements:

Configuring producer transaction timeout

    <transactionTimeout>
        <openWarn>10000</openWarn>
        <openClose>20000</openClose>
        <idleWarn>5000</idleWarn>
        <idleClose>15000</idleClose>
    </transactionTimeout>

## Configuring DLQs/Maximum Delivery Count

In the below configuration it can be seen that DLQs/Maximum Delivery Count are enabled at the virtual host "localhost" with maximum delivery count set to 5 and disable for virtual host "dev-only".

As 'dev-only-main-queue' has its own configuration specified, this value overrides all others and causes the features to be enabled for this queue. In contrast to this, 'dev-only-other-queue' does not specify its own value and picks up the false value specified for its parent virtualhost, causing the DLQ/Maximum Delivery Count features to be disabled for this queue. Any such queue in the 'dev-only' virtualhost which does not specify its own configuration value will have the DLQ/Maximum Delivery Count feature disabled.

The queue 'localhost-queue' has the DLQ/Maximum Delivery Count features disabled. Any other queue in the 'localhost' virtualhost which does not specify its own configuration value will have the features enabled (inherited from parent virtual host).

Enabling DLQs and maximum delivery count at virtualhost and queue level within virtualhosts.xml

    <virtualhosts>
     ...
     <virtualhost>
      <name>dev-only</name>
      <dev-only>
       <queues>
        <deadLetterQueues>false</deadLetterQueues>
        <maximumDeliveryCount>0</maximumDeliveryCount>
        <queue>
         <name>dev-only-main-queue</name>
         <dev-only-main-queue>
          <deadLetterQueues>true</deadLetterQueues>
          <maximumDeliveryCount>3</maximumDeliveryCount>
         </dev-only-main-queue>
        </queue>
        <queue>
         <name>dev-only-other-queue</name>
        </queue>
       </queues>
      </dev-only>
     </virtualhost>
     <virtualhost>
      <name>localhost</name>
      <localhost>
       <queues>
        <deadLetterQueues>true</deadLetterQueues>
        <maximumDeliveryCount>5</maximumDeliveryCount>
        <queue>
         <name>localhost-queue</name>
         <deadLetterQueues>false</deadLetterQueues>
        </queue>
       </queues>
      </localhost>
     </virtualhost>
     ...
    </virtualhosts>

## An example of virtual host configuration file

An example of virtual host configuration file

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <virtualhosts>
        <virtualhost>
            <name>localhost</name>
            <localhost>
                <store>
                    <class>org.apache.qpid.server.store.MemoryMessageStore</class>
                    <!--<class>org.apache.qpid.server.store.derby.DerbyMessageStore</class>
                    <environment-path>${QPID_WORK}/derbystore/localhost</environment-path>-->
                </store>

                <housekeeping>
                    <threadCount>2</threadCount>
                    <checkPeriod>20000</checkPeriod>
                </housekeeping>

                <exchanges>
                    <exchange>
                        <type>direct</type>
                        <name>test.direct</name>
                        <durable>true</durable>
                    </exchange>
                    <exchange>
                        <type>topic</type>
                        <name>test.topic</name>
                    </exchange>
                </exchanges>
                <queues>
                    <exchange>amq.direct</exchange>
                    <maximumQueueDepth>4235264</maximumQueueDepth>
                    <!-- 4Mb -->
                    <maximumMessageSize>2117632</maximumMessageSize>
                    <!-- 2Mb -->
                    <maximumMessageAge>600000</maximumMessageAge>
                    <!-- 10 mins -->
                    <maximumMessageCount>50</maximumMessageCount>
                    <!-- 50 messages -->

                    <queue>
                        <name>queue</name>
                    </queue>
                    <queue>
                        <name>ping</name>
                    </queue>
                    <queue>
                        <name>test-queue</name>
                        <test-queue>
                            <exchange>test.direct</exchange>
                            <durable>true</durable>
                        </test-queue>
                    </queue>
                    <queue>
                        <name>test-ping</name>
                        <test-ping>
                            <exchange>test.direct</exchange>
                        </test-ping>
                    </queue>

                </queues>
            </localhost>
        </virtualhost>

        <virtualhost>
            <name>development</name>
            <development>
                <store>
                    <class>org.apache.qpid.server.store.MemoryMessageStore</class>
                    <!--<class>org.apache.qpid.server.store.derby.DerbyMessageStore</class>
                    <environment-path>${QPID_WORK}/derbystore/development</environment-path>-->
                </store>

                <queues>
                    <minimumAlertRepeatGap>30000</minimumAlertRepeatGap>
                    <maximumMessageCount>50</maximumMessageCount>
                    <queue>
                        <name>queue</name>
                        <queue>
                            <exchange>amq.direct</exchange>
                            <maximumQueueDepth>4235264</maximumQueueDepth>
                            <!-- 4Mb -->
                            <maximumMessageSize>2117632</maximumMessageSize>
                            <!-- 2Mb -->
                            <maximumMessageAge>600000</maximumMessageAge>
                            <!-- 10 mins -->
                        </queue>
                    </queue>
                    <queue>
                        <name>ping</name>
                        <ping>
                            <exchange>amq.direct</exchange>
                            <maximumQueueDepth>4235264</maximumQueueDepth>
                            <!-- 4Mb -->
                            <maximumMessageSize>2117632</maximumMessageSize>
                            <!-- 2Mb -->
                            <maximumMessageAge>600000</maximumMessageAge>
                            <!-- 10 mins -->
                        </ping>
                    </queue>
                </queues>
            </development>
        </virtualhost>

        <virtualhost>
            <name>test</name>
            <test>
                <store>
                    <!--<class>org.apache.qpid.server.store.MemoryMessageStore</class>-->
                    <class>org.apache.qpid.server.store.derby.DerbyMessageStore</class>
                    <environment-path>${QPID_WORK}/derbystore/test</environment-path>
                </store>

                <queues>
                    <minimumAlertRepeatGap>30000</minimumAlertRepeatGap>
                    <maximumMessageCount>50</maximumMessageCount>
                    <queue>
                        <name>queue</name>
                        <queue>
                            <exchange>amq.direct</exchange>
                            <maximumQueueDepth>4235264</maximumQueueDepth>
                            <!-- 4Mb -->
                            <maximumMessageSize>2117632</maximumMessageSize>
                            <!-- 2Mb -->
                            <maximumMessageAge>600000</maximumMessageAge>
                            <!-- 10 mins -->
                        </queue>
                    </queue>
                    <queue>
                        <name>ping</name>
                        <ping>
                            <exchange>amq.direct</exchange>
                            <maximumQueueDepth>4235264</maximumQueueDepth>
                            <!-- 4Mb -->
                            <maximumMessageSize>2117632</maximumMessageSize>
                            <!-- 2Mb -->
                            <maximumMessageAge>600000</maximumMessageAge>
                            <!-- 10 mins -->
                        </ping>
                    </queue>
                </queues>
            </test>
        </virtualhost>
    </virtualhosts>