JBoss.org Community Documentation

- Prev

## Chapter 48. Configuration Reference

This section is a quick index for looking up configuration. Click on the element name to go to the specific chapter.

## 48.1. Server Configuration

### 48.1.1. hornetq-configuration.xml

This is the main core server configuration file.

Table 48.1. Server Configuration

Element Name | Element Type | Description | Default
--- | --- | --- | ---
allow-failback | Boolean | Will this server automatically shutdown if the original live server comes back up | false
backup | Boolean | Is this server a backup server | false
bindings-directory | String | the directory to store the persisted bindings to | data/bindings
clustered | Boolean | true means that the server is clustered | false
connection-ttl-override | Long | if set, this will override how long (in ms) to keep a connection alive without receiving a ping. | -1
create-bindings-dir | Boolean | true means that the server will create the bindings directory on start up | true
create-journal-dir | Boolean | true means that the journal directory will be created | true

Continued..

file-deployment-enabled | Boolean | true means that the server will load configuration from the configuration files | true
failover-on-shutdown | Boolean | Will this backup server come live on a normal server shutdown | false
id-cache-size | Integer | the size of the cache for pre creating message id's | 2000
journal-buffer-size | Long | The size of the internal buffer on the journal. | 128 KiB
journal-buffer-timeout | Long | The timeout (in nanoseconds) used to flush internal buffers on the journal. | 20000
journal-compact-min-files | Integer | The minimal number of data files before we can start compacting | 10
journal-compact-percentage | Integer | The percentage of live data on which we consider compacting the journal | 30
journal-directory | String | the directory to store the journal files in | data/journal
journal-file-size | Long | the size (in bytes) of each journal file | 10 * 1024 * 1024 (10 MiB)
journal-max-io | Integer | the maximum number of write requests that can be in the AIO queue at any one time | 500
journal-min-files | Integer | how many journal files to pre-create | 2
journal-sync-transactional | Boolean | if true wait for transaction data to be synchronized to the journal before returning response to client | true
journal-sync-non-transactional | Boolean | if true wait for non transaction data to be synced to the journal before returning response to client. | true
journal-type | ASYNCIO|NIO | the type of journal to use | ASYNCIO
jmx-management-enabled | Boolean | true means that the management API is available via JMX | true
jmx-domain | String | the JMX domain used to registered HornetQ MBeans in the MBeanServer | org.hornetq
log-delegate-factory-class-name | String | todo | todo
large-messages-directory | String | the directory to store large messages | data/largemessages
management-address | String | the name of the management address to send management messages to | jms.queue.hornetq.management
cluster-user | String | the user used by cluster connections to communicate between the clustered nodes | HORNETQ.CLUSTER.ADMIN.USER
cluster-password | String | the password used by cluster connections to communicate between the clustered nodes | CHANGE ME!!
management-notification-address | String | the name of the address that consumers bind to receive management notifications | hornetq.notifications
message-counter-enabled | Boolean | true means that message counters are enabled | false
message-counter-max-day-history | Integer | how many days to keep message counter history | 10
message-counter-sample-period | Long | the sample period (in ms) to use for message counters | 10000
message-expiry-scan-period | Long | how often (in ms) to scan for expired messages | 30000
message-expiry-thread-priority | Integer | the priority of the thread expiring messages | 3
paging-directory | String | the directory to store paged messages in | data/paging
page-max-concurrent-io | integer | The maximum number of concurrent reads the system will do on the paging files | 5
persist-delivery-count-before-delivery | Boolean | true means that the delivery count is persisted before delivery. False means that this only happens after a message has been cancelled. | false
persistence-enabled | Boolean | true means that the server will use the file based journal for persistence. | true
persist-id-cache | Boolean | true means that id's are persisted to the journal | true
remoting-interceptors | todo | todo | todo
shared-store | Boolean | is this server using a shared store for failover | false
scheduled-thread-pool-max-size | Integer | the number of threads that the main scheduled thread pool has. | 5
security-enabled | Boolean | true means that security is enabled | true
security-invalidation-interval | Long | how long (in ms) to wait before invalidating the security cache | 10000
thread-pool-max-size | Integer | the number of threads that the main thread pool has. -1 means no limit | -1
async-connection-execution-enabled | Boolean | Should incoming packets on the server be handed off to a thread from the thread pool for processing or should they be handled on the remoting thread? | true
transaction-timeout | Long | how long (in ms) before a transaction can be removed from the resource manager after create time | 60000
transaction-timeout-scan-period | Long | how often (in ms) to scan for timeout transactions | 1000
wild-card-routing-enabled | Boolean | true means that the server supports wild card routing | true
memory-measure-interval | Long | frequency to sample JVM memory in ms (or -1 to disable memory sampling) | -1
memory-warning-threshold | Integer | Percentage of available memory which threshold a warning log | 25
connectors | Connector | a list of remoting connectors configurations to create |
connector.name (attribute) | String | Name of the connector - mandatory |
connector.factory-class | String | Name of the ConnectorFactory implementation - mandatory |
connector.param | A connector configuration parameter | A key-value pair used to configure the connector. A connector can have many param |
connector.param.key (attribute) | String | Key of a configuration parameter - mandatory |
connector.param.value (attribute) | String | Value of a configuration parameter - mandatory |
acceptors | Acceptor | a list of remoting acceptors to create |
acceptor.name (attribute) | String | Name of the acceptor - optional |
acceptor.factory-class | String | Name of the AcceptorFactory implementation - mandatory |
acceptor.param | An acceptor configuration parameter | A key-value pair used to configure the acceptor. An acceptor can have many param |
acceptor.param.key (attribute) | String | Key of a configuration parameter - mandatory |
acceptor.param.value (attribute) | String | Value of a configuration parameter - mandatory |
broadcast-groups | BroadcastGroup | a list of broadcast groups to create |
broadcast-group.name (attribute) | String | a unique name for the broadcast group - mandatory |
broadcast-group.local-bind-address | String | local bind address that the datagram socket is bound to | wildcard IP address chosen by the kernel
broadcast-group.local-bind-port | Integer | local port to which the datagram socket is bound to | -1 (anonymous port)
broadcast-group.group-address | String | multicast address to which the data will be broadcast - mandatory |
broadcast-group.group-port | Integer | UDP port number used for broadcasting - mandatory |
broadcast-group.broadcast-period | Long | period in milliseconds between consecutive broadcasts | 2000 (in milliseconds)
broadcast-group.connector-ref | A pair of connector | A pair connector and optional backup connector that will be broadcasted. A broadcast-group can have multiple connector-ref |
broadcast-group.connector-ref.connector-name (attribute) | String | Name of the live connector - mandatory |
broadcast-group.connector-ref.backup-connector-name (attribute) | String | Name of the backup connector - optional |
discovery-groups | DiscoveryGroup | a list of discovery groups to create |
discovery-group.name (attribute) | String | a unique name for the discovery group - mandatory |
discovery-group.local-bind-address | String | the discovery group will be bound only to this local address |
discovery-group.group-address | String | Multicast IP address of the group to listen on - mandatory |
discovery-group.group-port | Integer | UDP port of the multicast group - mandatory |
discovery-group.refresh-timeout | Integer | Period the discovery group waits after receiving the last broadcast from a particular server before removing that servers connector pair entry from its list. | 5000 (in milliseconds)
diverts | Divert | a list of diverts to use |
divert.name (attribute) | String | a unique name for the divert - mandatory |
divert.routing-name | String | the routing name for the divert - mandatory |
divert.address | String | the address this divert will divert from - mandatory |
divert.forwarding-address | String | the forwarding address for the divert - mandatory |
divert.exclusive | Boolean | is this divert exclusive? | false
divert.filter | String | an optional core filter expression | null
divert.transformer-class-name | String | an optional class name of a transformer |
queues | Queue | a list of pre configured queues to create |
queues.name (attribute) | String | unique name of this queue |
queues.address | String | address for this queue - mandatory |
queues.filter | String | optional core filter expression for this queue | null
queues.durable | Boolean | is this queue durable? | true
bridges | Bridge | a list of bridges to create |
bridges.name (attribute) | String | unique name for this bridge |
bridges.queue-name | String | name of queue that this bridge consumes from - mandatory |
bridges.forwarding-address | String | address to forward to. If omitted original address is used | null
bridges.filter | String | optional core filter expression | null
bridges.transformer-class-name | String | optional name of transformer class | null
bridges.retry-interval | Long | period (in ms) between successive retries | 2000 ms
bridges.retry-interval-multiplier | Double | multiplier to apply to successive retry intervals | 1.0
bridges.reconnect-attempts | Integer | maximum number of retry attempts, -1 signifies infinite | -1
bridges.failover-on-server-shutdown | Boolean | should failover be prompted if target server is cleanly shutdown? | false
bridges.use-duplicate-detection | Boolean | should duplicate detection headers be inserted in forwarded messages? | true
bridges.discovery-group-ref | String | name of discovery group used by this bridge | null
bridges.connector-ref.connector-name (attribute) | String | name of connector to use for live connection |
bridges.connector-ref.backup-connector-name (attribute) | String | optional name of connector to use for backup connection | null
cluster-connections | ClusterConnection | a list of cluster connections |
cluster-connections.name (attribute) | String | unique name for this cluster connection |
cluster-connections.address | String | name of address this cluster connection applies to |
cluster-connections.forward-when-no-consumers | Boolean | should messages be load balanced if there are no matching consumers on target? | false
cluster-connections.max-hops | Integer | maximum number of hops cluster topology is propagated | 1
cluster-connections.retry-interval | Long | period (in ms) between successive retries | 2000
cluster-connections.use-duplicate-detection | Boolean | should duplicate detection headers be inserted in forwarded messages? | true
cluster-connections.discovery-group-ref | String | name of discovery group used by this bridge | null
cluster-connections.connector-ref.connector-name (attribute) | String | name of connector to use for live connection |
cluster-connections.connector-ref.backup-connector-name (attribute) | String | optional name of connector to use for backup connection | null
security-settings | SecuritySetting | a list of security settings |
security-settings.match (attribute) | String | the string to use for matching security against an address |
security-settings.permission | Security Permission | a permision to add to the address |
security-settings.permission.type (attribute) | Permission Type | the type of permission |
security-settings.permission.roles (attribute) | Roles | a comma-separated list of roles to apply the permission to |
address-settings | AddressSetting | a list of address settings |
address-settings.dead-letter-address | String | the address to send dead messages to |
address-settings.max-delivery-attempts | Integer | how many times to attempt to deliver a message before sending to dead letter address | 10
address-settings.expiry-address | String | the address to send expired messages to |
address-settings.redelivery-delay | Long | the time (in ms) to wait before redelivering a cancelled message. | 0
address-settings.last-value-queue | boolean | whether to treat the queue as a last value queue | false
address-settings.page-size-bytes | Long | the page size (in bytes) to use for an address | 10 * 1024 * 1024
address-settings.max-size-bytes | Long | the maximum size (in bytes) to use in paging for an address | -1
address-settings.redistribution-delay | Long | how long (in ms) to wait after the last consumer is closed on a queue before redistributing messages. | -1

### 48.1.2. hornetq-jms.xml

This is the configuration file used by the server side JMS service to load JMS Queues, Topics and Connection Factories.

Table 48.2. JMS Server Configuration

Element Name | Element Type | Description | Default
--- | --- | --- | ---
connection-factory | ConnectionFactory | a list of connection factories to create and add to JNDI |

Continued..

connection-factory.signature (attribute) | String | Type of connection factory | generic
connection-factory.xa | Boolean | If it is a XA connection factory | false
connection-factory.auto-group | Boolean | whether or not message grouping is automatically used | false
connection-factory.connectors | String | A list of connectors used by the connection factory |
connection-factory.connectors.connector-ref.connector-name (attribute) | String | Name of the connector to connect to the live server |
connection-factory.connectors.connector-ref.backup-connector-name (attribute) | String | Name of the connector to connect to the backup server |
connection-factory.discovery-group-ref.discovery-group-name (attribute) | String | Name of discovery group used by this connection factory |
connection-factory.discovery-initial-wait-timeout | Long | the initial time to wait (in ms) for discovery groups to wait for broadcasts | 10000
connection-factory.block-on-acknowledge | Boolean | whether or not messages are acknowledged synchronously | false
connection-factory.block-on-non-durable-send | Boolean | whether or not non-durable messages are sent synchronously | false
connection-factory.block-on-durable-send | Boolean | whether or not durable messages are sent synchronously | true
connection-factory.call-timeout | Long | the timeout (in ms) for remote calls | 30000
connection-factory.client-failure-check-period | Long | the period (in ms) after which the client will consider the connection failed after not receiving packets from the server | 5000
connection-factory.client-id | String | the pre-configured client ID for the connection factory | null
connection-factory.connection-load-balancing-policy-class-name | String | the name of the load balancing class | org.hornetq.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy
connection-factory.connection-ttl | Long | the time to live (in ms) for connections | 1 * 60000
connection-factory.consumer-max-rate | Integer | the fastest rate a consumer may consume messages per second | -1
connection-factory.consumer-window-size | Integer | the window size (in bytes) for consumer flow control | 1024 * 1024
connection-factory.dups-ok-batch-size | Integer | the batch size (in bytes) between acknowledgements when using DUPS_OK_ACKNOWLEDGE mode | 1024 * 1024
connection-factory.failover-on-initial-connection | Boolean | whether or not to failover to backup on event that initial connection to live server fails | false
connection-factory.failover-on-server-shutdown | Boolean | whether or not to failover on server shutdown | false
connection-factory.min-large-message-size | Integer | the size (in bytes) before a message is treated as large | 100 * 1024
connection-factory.cache-large-message-client | Boolean | If true clients using this connection factory will hold the large message body on temporary files. | false
connection-factory.pre-acknowledge | Boolean | whether messages are pre acknowledged by the server before sending | false
connection-factory.producer-max-rate | Integer | the maximum rate of messages per second that can be sent | -1
connection-factory.producer-window-size | Integer | the window size in bytes for producers sending messages | 1024 * 1024
connection-factory.confirmation-window-size | Integer | the window size (in bytes) for reattachment confirmations | 1024 * 1024
connection-factory.reconnect-attempts | Integer | maximum number of retry attempts, -1 signifies infinite | 0
connection-factory.retry-interval | Long | the time (in ms) to retry a connection after failing | 2000
connection-factory.retry-interval-multiplier | Double | multiplier to apply to successive retry intervals | 1.0
connection-factory.max-retry-interval | Integer | The maximum retry interval in the case a retry-interval-multiplier has been specified | 2000
connection-factory.scheduled-thread-pool-max-size | Integer | the size of the scheduled thread pool | 5
connection-factory.thread-pool-max-size | Integer | the size of the thread pool | -1
connection-factory.transaction-batch-size | Integer | the batch size (in bytes) between acknowledgements when using a transactional session | 1024 * 1024
connection-factory.use-global-pools | Boolean | whether or not to use a global thread pool for threads | true
queue | Queue | a queue to create and add to JNDI |
queue.name (attribute) | String | unique name of the queue |
queue.entry | String | context where the queue will be bound in JNDI (there can be many) |
queue.durable | Boolean | is the queue durable? | true
queue.filter | String | optional filter expression for the queue |
topic | Topic | a topic to create and add to JNDI |
topic.name (attribute) | String | unique name of the topic |
topic.entry | String | context where the topic will be bound in JNDI (there can be many) |

### 48.1.3. Using Masked Passwords in Configuration Files

By default all passwords in HornetQ server's configuration files are in plaintext form. This usually poses no security issues as those files should be well protected from unauthorized accessing. However, in some circumstances a user doesn't want to expose its passwords to more eyes than necessary.

HornetQ can be configured to use 'masked' passwords in its configuration files. A masked password is an obscure string representation of a real password. To mask a password a user will use an 'encoder'. The encoder takes in the real password and outputs the masked version. A user can then replace the real password in the configuration files with the new masked password. When HornetQ loads a masked password, it uses a suitable 'decoder' to decode it into real password.

Hornetq provides a default password encoder and decoder. Optionally users can use or implement their own encoder and decoder for masking the passwords.

#### 48.1.3.1. Password Masking in Server Configuration File

##### 48.1.3.1.1. The password masking property

The server configuration file has a property that defines the default masking behaviors over the entire file scope.

`mask-password`: this boolean type property indicates if a password should be masked or not. Set it to "true" if you want your passwords masked. The default value is "false".

##### 48.1.3.1.2. Specific masking behaviors

###### 48.1.3.1.2.1. cluster-password

The nature of the value of cluster-password is subject to the value of property 'mask-password'. If it is true the cluster-password is masked.

###### 48.1.3.1.2.2. Passwords in connectors and acceptors

In the server configuration, Connectors and Acceptors sometimes needs to specify passwords. For example if a users wants to use an SSL-enabled NettyAcceptor, it can specify a key-store-password and a trust-store-password. Because Acceptors and Connectors are pluggable implementations, each transport will have different password masking needs.

When a Connector or Acceptor configuration is initialised, HornetQ will add the "mask-password" and "password-codec" values to the Connector or Acceptors params using the keys `hornetq.usemaskedpassword` and `hornetq.passwordcodec` respectively. The Netty and InVM implementations will use these as needed and any other implementations will have access to these to use if they so wish.

###### 48.1.3.1.2.3. Passwords in Core Bridge cofigurations

Core Bridges are configured in the server configuration file and so the masking of its 'password' properties follows the same rules as that of 'cluster-password'.

##### 48.1.3.1.3. Examples

The following table summarizes the relations among the above-mentioned properties

Table 48.3.

mask-password | cluster-password | acceptor/connector passwords | bridge password
--- | --- | --- | ---
absent | plain text | plain text | plain text
false | plain text | plain text | plain text
true | masked | masked | masked

Examples

Note: In the following examples if related attributed or properties are absent, it means they are not specified in the configure file.

example 1

    <cluster-password>bbc</cluster-password>

This indicates the cluster password is a plaintext value ("bbc").

example 2

    <mask-password>true</mask-password>
    <cluster-password>80cf731af62c290</cluster-password>

This indicates the cluster password is a masked value and HorentQ will use its built-in decoder to decode it. All other passwords in the configuration file, Connectors, Acceptors and Bridges, will also use masked passwords.

#### 48.1.3.2. JMS Bridge password masking

The JMS Bridges are configured and deployed as separate beans so they need separate configuration to control the password masking. A JMS Bridge has two password parameters in its constructor, SourcePassword and TargetPassword. It uses the following two optional properties to control their masking:

`useMaskedPassword` -- If set to "true" the passwords are masked. Default is false.

`passwordCodec` -- Class name and its parameters for the Decoder used to decode the masked password. Ignored if `useMaskedPassword` is false. The format of this property is a full qualified class name optionally followed by key/value pairs, separated by semi-colons. For example:

`<property name="useMaskedPassword">true</property>`

`<property name="passwordCodec">com.foo.FooDecoder;key=value</property>`

HornetQ will load this property and initialize the class with a parameter map containing the "key"->"value" pair. If `passwordCodec` is not specified, the built-in decoder is used.

#### 48.1.3.3. Masking passwords in HorentQ ResourceAdapters and MDB activation configurations

Both ra.xml and MDB activation configuration have a 'password' property that can be masked. They are controlled by the following two optional Resource Adapter properties in ra.xml:

`UseMaskedPassword` -- If setting to "true" the passwords are masked. Default is false.

`PasswordCodec` -- Class name and its parameters for the Decoder used to decode the masked password. Ignored if UseMaskedPassword is false. The format of this property is a full qualified class name optionally followed by key/value pairs. It is the same format as that for JMS Bridges. Example:

          <config-property>
            <config-property-name>UseMaskedPassword</config-property-name>
            <config-property-type>boolean</config-property-type>
            <config-property-value>true</config-property-value>
          </config-property>
          <config-property>
            <config-property-name>PasswordCodec</config-property-name>
            <config-property-type>java.lang.String</config-property-type>
            <config-property-value>com.foo.ADecoder;key=helloworld</config-property-value>
          </config-property>

With this configuration, both passwords in ra.xml and all of its MDBs will have to be in masked form.

#### 48.1.3.4. Masking passwords in hornetq-users.xml

HornetQ's built-in security manager uses plain configuration files where the user passwords are specified in plaintext forms by default. To mask those parameters the following two properties are needed:

`mask-password` -- If set to "true" all the passwords are masked. Default is false.

`password-codec` -- Class name and its parameters for the Decoder used to decode the masked password. Ignored if `mask-password` is false. The format of this property is a full qualified class name optionally followed by key/value pairs. It is the same format as that for JMS Bridges. Example:

    <mask-password>true</mask-password>
    <password-codec>org.hornetq.utils.DefaultSensitiveStringCodec;key=hello world</password-codec>

When so configured, the HornetQ security manager will initialize a DefaultSensitiveStringCodec with the parameters "key"->"hello world", then use it to decode all the masked passwords in this configuration file.

#### 48.1.3.5. Choosing a decoder for password masking

As described in the previous sections, all password masking requires a decoder. A decoder uses an algorithm to convert a masked password into its original cleartext form in order to be used in various security operations. The algorithm used for decoding must match that for encoding. Otherwise the decoding may not be successful.

For user's convenience HornetQ provides a default built-in Decoder. However a user can if they so wish implement their own.

##### 48.1.3.5.1. The built-in Decoder

Whenever no decoder is specified in the configuration file, the built-in decoder is used. The class name for the built-in decoder is org.hornetq.utils.DefaultSensitiveStringCodec. It has both encoding and decoding capabilities. It uses java.crypto.Cipher utilities to encrypt (encode) a plaintext password and decrypt a mask string using same algorithm. Using this decoder/encoder is pretty straightforward. To get a mask for a password, just run the following in command line:

    java org.hornetq.utils.DefaultSensitiveStringCodec "your plaintext password"

Make sure the classpath is correct. You'll get something like

    Encoded password: 80cf731af62c290

Just copy "80cf731af62c290" and replace your plaintext password with it.

##### 48.1.3.5.2. Using a different decoder

It is possible to use a different decoder rather than the built-in one. Simply make sure the decoder is in HornetQ's classpath and configure the server to use it as follows:

    <password-codec>com.foo.SomeDecoder;key1=value1;key2=value2</password-codec>

If your decoder needs params passed to it you can do this via key/value pairs when configuring. For instance if your decoder needs say a "key-location" parameter, you can define like so:

    <password-codec>com.foo.NewDecoder;key-location=/some/url/to/keyfile</password-codec>

Then configure your cluster-password like this:

    <mask-password>true</mask-password>
    <cluster-password>masked_password</cluster-password>

When HornetQ reads the cluster-password it will initialize the NewDecoder and use it to decode "mask_password". It also process all passwords using the new defined decoder.

##### 48.1.3.5.3. Implementing your own ocdecs

To use a different decoder than the built-in one, you either pick one from existing libraries or you implement it yourself. All decoders must implement the `org.hornetq.utils.SensitiveDataCodec<T>` interface:

    public interface SensitiveDataCodec<T>
    {
       T decode(Object mask) throws Exception;

       void init(Map<String, String> params);
    }

This is a generic type interface but normally for a password you just need String type. So a new decoder would be defined like

    public class MyNewDecoder implements SensitiveDataCodec<String>
    {
       public String decode(Object mask) throws Exception
       {
          //decode the mask into cleartext passord
          return "the password";
       }

       public void init(Map<String, String> params)
       {
          //initialization done here. It is called right after the decoder has been created.
       }
    }

Last but not least, once you get your own decoder, please add it to the classpath. Otherwise HornetQ will fail to load it!

- PrevChapter 47. Performance Tuning
- Top of page
- Front page