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

This is the main core server configuration file. Element Name Element Type Description Default

This is the configuration file used by the server side JMS service to load JMS Queues, Topics and Connection Factories. 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.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 30000 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.apache.activemq6.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.avoid-large-messages Boolean If compress large messages and send them as regular messages if possible false 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)

By default all passwords in HornetQ server's configuration files are in plain text 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.

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".

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.

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.

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'.

The following table summarizes the relations among the above-mentioned properties 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 plain text value ("bbc"). example 2 <mask-password>true</mask-password> <cluster-password>80cf731af62c290</cluster-password> This indicates the cluster password is a masked value and HornetQ 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.

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.

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.

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.apache.activemq6.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.

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 clear text 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.

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.apache.activemq6.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.apache.activemq6.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.

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.

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.apache.activemq6.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 clear text password 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!