706 lines
39 KiB
XML
706 lines
39 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!-- ============================================================================= -->
|
||
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
|
||
<!-- -->
|
||
<!-- The text of and illustrations in this document are licensed by Red Hat under -->
|
||
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
|
||
<!-- -->
|
||
<!-- An explanation of CC-BY-SA is available at -->
|
||
<!-- -->
|
||
<!-- http://creativecommons.org/licenses/by-sa/3.0/. -->
|
||
<!-- -->
|
||
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
|
||
<!-- of it, you must provide the URL for the original version. -->
|
||
<!-- -->
|
||
<!-- Red Hat, as the licensor of this document, waives the right to enforce, -->
|
||
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
|
||
<!-- permitted by applicable law. a -->
|
||
<!-- ============================================================================= -->
|
||
|
||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||
<!ENTITY % BOOK_ENTITIES SYSTEM "ActiveMQ_User_Manual.ent">
|
||
%BOOK_ENTITIES;
|
||
]>
|
||
<chapter id="configuration-index">
|
||
<title>Configuration Reference</title>
|
||
<para>This section is a quick index for looking up configuration. Click on the element name to
|
||
go to the specific chapter.</para>
|
||
<section id="server.configuration">
|
||
<title>Server Configuration</title>
|
||
<section>
|
||
<title>activemq-configuration.xml</title>
|
||
<para>This is the main core server configuration file.</para>
|
||
<table frame="topbot" border="2">
|
||
<title>Server Configuration</title>
|
||
<tgroup cols="4">
|
||
<colspec colname="c1" colnum="1"/>
|
||
<colspec colname="c2" colnum="2"/>
|
||
<colspec colname="c3" colnum="3"/>
|
||
<colspec colname="c4" colnum="4"/>
|
||
<thead>
|
||
<row>
|
||
<entry>Element Name</entry>
|
||
<entry>Element Type</entry>
|
||
<entry>Description</entry>
|
||
<entry>Default</entry>
|
||
</row>
|
||
</thead>
|
||
<!-- The options reference is generated from the schema. If something is wrong
|
||
in the reference, it must be fixed in the annotations present in the
|
||
schema. -->
|
||
<xi:include href="../target/generated-resources/xml/xslt/activemq-configuration.xml"
|
||
xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
||
</tgroup>
|
||
</table>
|
||
</section>
|
||
<section>
|
||
<title>activemq-jms.xml</title>
|
||
<para>This is the configuration file used by the server side JMS service to load JMS
|
||
Queues, Topics and Connection Factories.</para>
|
||
<table frame="topbot" border="2">
|
||
<title>JMS Server Configuration</title>
|
||
<tgroup cols="4">
|
||
<colspec colname="c1" colnum="1"/>
|
||
<colspec colname="c2" colnum="2"/>
|
||
<colspec colname="c3" colnum="3"/>
|
||
<colspec colname="c4" colnum="4"/>
|
||
<thead>
|
||
<row>
|
||
<entry>Element Name</entry>
|
||
<entry>Element Type</entry>
|
||
<entry>Description</entry>
|
||
<entry>Default</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry>
|
||
<link linkend="using-jms.server.configuration">connection-factory</link>
|
||
</entry>
|
||
<entry>ConnectionFactory</entry>
|
||
<entry>a list of connection factories to create and add to JNDI</entry>
|
||
<entry/>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
<para></para>
|
||
<para></para>
|
||
<para>Continued..</para>
|
||
<informaltable frame="topbot">
|
||
<tgroup cols="4">
|
||
<colspec colname="c1" colnum="1"/>
|
||
<colspec colname="c2" colnum="2"/>
|
||
<colspec colname="c3" colnum="3"/>
|
||
<colspec colname="c4" colnum="4"/>
|
||
<tbody>
|
||
<row>
|
||
<entry id="configuration.connection-factory.signature">
|
||
<link linkend="using-jms.configure.factory.types">connection-factory.signature (attribute)</link>
|
||
</entry>
|
||
<entry>String</entry>
|
||
<entry>Type of connection factory</entry>
|
||
<entry>generic</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.signature.xa">
|
||
<link linkend="using-jms.configure.factory.types">connection-factory.xa</link>
|
||
</entry>
|
||
<entry>Boolean</entry>
|
||
<entry>If it is a XA connection factory</entry>
|
||
<entry>false</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.auto-group">
|
||
<link linkend="message-grouping.jmsconfigure">connection-factory.auto-group</link>
|
||
</entry>
|
||
<entry>Boolean</entry>
|
||
<entry>whether or not message grouping is automatically used</entry>
|
||
<entry>false</entry>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="clusters">connection-factory.connectors</link>
|
||
</entry>
|
||
<entry>String</entry>
|
||
<entry>A list of connectors used by the connection factory</entry>
|
||
<entry />
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="clusters"
|
||
>connection-factory.connectors.connector-ref.connector-name (attribute)</link>
|
||
</entry>
|
||
<entry>String</entry>
|
||
<entry>Name of the connector to connect to the live server</entry>
|
||
<entry />
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="clusters"
|
||
>connection-factory.discovery-group-ref.discovery-group-name (attribute)</link>
|
||
</entry>
|
||
<entry>String</entry>
|
||
<entry>Name of discovery group used by this connection factory</entry>
|
||
<entry />
|
||
</row>
|
||
<row>
|
||
<!-- FIXME documented but does not exist? -->
|
||
<entry id="configuration.connection-factory.discovery-initial-wait-timeout">
|
||
<link linkend="clusters"
|
||
>connection-factory.discovery-initial-wait-timeout</link>
|
||
</entry>
|
||
<entry>Long</entry>
|
||
<entry>the initial time to wait (in ms) for discovery groups to wait for
|
||
broadcasts</entry>
|
||
<entry>10000</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.block-on-acknowledge">
|
||
<link linkend="send-guarantees.nontrans.acks">connection-factory.block-on-acknowledge</link>
|
||
</entry>
|
||
<entry>Boolean</entry>
|
||
<entry>whether or not messages are acknowledged synchronously</entry>
|
||
<entry>false</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.block-on-non-durable-send">
|
||
<link linkend="non-transactional-sends">connection-factory.block-on-non-durable-send</link>
|
||
</entry>
|
||
<entry>Boolean</entry>
|
||
<entry>whether or not non-durable messages are sent synchronously</entry>
|
||
<entry>false</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.block-on-durable-send">
|
||
<link linkend="non-transactional-sends">connection-factory.block-on-durable-send</link>
|
||
</entry>
|
||
<entry>Boolean</entry>
|
||
<entry>whether or not durable messages are sent synchronously</entry>
|
||
<entry>true</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.call-timeout">connection-factory.call-timeout</entry>
|
||
<entry>Long</entry>
|
||
<entry>the timeout (in ms) for remote calls</entry>
|
||
<entry>30000</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.client-failure-check-period">
|
||
<link linkend="dead.connections">connection-factory.client-failure-check-period</link>
|
||
</entry>
|
||
<entry>Long</entry>
|
||
<entry>the period (in ms) after which the client will consider the
|
||
connection failed after not receiving packets from the
|
||
server</entry>
|
||
<entry>30000</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.client-id">
|
||
<link linkend="using-jms.clientid">connection-factory.client-id</link>
|
||
</entry>
|
||
<entry>String</entry>
|
||
<entry>the pre-configured client ID for the connection factory</entry>
|
||
<entry>null</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.connection-load-balancing-policy-class-name">
|
||
<link linkend="clusters">
|
||
connection-factory.connection-load-balancing-policy-class-name</link>
|
||
</entry>
|
||
<entry>String</entry>
|
||
<entry>the name of the load balancing class</entry>
|
||
<entry>org.apache.activemq.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.connection-ttl">
|
||
<link linkend="dead.connections">connection-factory.connection-ttl</link>
|
||
</entry>
|
||
<entry>Long</entry>
|
||
<entry>the time to live (in ms) for connections</entry>
|
||
<entry>1 * 60000</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.consumer-max-rate">
|
||
<link linkend="flow-control.rate.core.api">connection-factory.consumer-max-rate</link></entry>
|
||
<entry>Integer</entry>
|
||
<entry>the fastest rate a consumer may consume messages per
|
||
second</entry>
|
||
<entry>-1</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.consumer-window-size">
|
||
<link linkend="flow-control.core.api">connection-factory.consumer-window-size</link></entry>
|
||
<entry>Integer</entry>
|
||
<entry>the window size (in bytes) for consumer flow control</entry>
|
||
<entry>1024 * 1024</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.dups-ok-batch-size">
|
||
<link linkend="using-jms.dupsokbatchsize">connection-factory.dups-ok-batch-size</link></entry>
|
||
<entry>Integer</entry>
|
||
<entry>the batch size (in bytes) between acknowledgements when using
|
||
DUPS_OK_ACKNOWLEDGE mode</entry>
|
||
<entry>1024 * 1024</entry>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="ha.automatic.failover"
|
||
>connection-factory.failover-on-initial-connection</link></entry>
|
||
<entry>Boolean</entry>
|
||
<entry>whether or not to failover to backup on event that initial connection to live server fails</entry>
|
||
<entry>false</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.failover-on-server-shutdown">
|
||
<link linkend="ha.automatic.failover">connection-factory.failover-on-server-shutdown</link></entry>
|
||
<entry>Boolean</entry>
|
||
<entry>whether or not to failover on server shutdown</entry>
|
||
<entry>false</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.min-large-message-size">
|
||
<link linkend="large-messages.core.config">connection-factory.min-large-message-size</link></entry>
|
||
<entry>Integer</entry>
|
||
<entry>the size (in bytes) before a message is treated as large</entry>
|
||
<entry>100 * 1024</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.avoid-large-messages">
|
||
<link linkend="large.message.configuring">connection-factory.avoid-large-messages</link></entry>
|
||
<entry>Boolean</entry>
|
||
<entry>If compress large messages and send them as regular messages if possible</entry>
|
||
<entry>false</entry>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="clusters"
|
||
>connection-factory.cache-large-message-client</link></entry>
|
||
<entry>Boolean</entry>
|
||
<entry>If true clients using this connection factory will hold the large
|
||
message body on temporary files.</entry>
|
||
<entry>false</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.pre-acknowledge">
|
||
<link linkend="pre-acknowledge.configure">connection-factory.pre-acknowledge</link></entry>
|
||
<entry>Boolean</entry>
|
||
<entry>whether messages are pre acknowledged by the server before
|
||
sending</entry>
|
||
<entry>false</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.producer-max-rate">
|
||
<link linkend="flow-control.producer.rate.core.api">connection-factory.producer-max-rate</link></entry>
|
||
<entry>Integer</entry>
|
||
<entry>the maximum rate of messages per second that can be sent</entry>
|
||
<entry>-1</entry>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="client-reconnection"
|
||
>connection-factory.producer-window-size</link></entry>
|
||
<entry>Integer</entry>
|
||
<entry>the window size in bytes for producers sending messages</entry>
|
||
<entry>1024 * 1024</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.confirmation-window-size">
|
||
<link linkend="client-reconnection">connection-factory.confirmation-window-size</link>
|
||
</entry>
|
||
<entry>Integer</entry>
|
||
<entry>the window size (in bytes) for reattachment confirmations</entry>
|
||
<entry>1024 * 1024</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.reconnect-attempts">
|
||
<link linkend="client-reconnection">connection-factory.reconnect-attempts</link>
|
||
</entry>
|
||
<entry>Integer</entry>
|
||
<entry>maximum number of retry attempts, -1 signifies infinite</entry>
|
||
<entry>0</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.retry-interval">
|
||
<link linkend="client-reconnection">connection-factory.retry-interval</link>
|
||
</entry>
|
||
<entry>Long</entry>
|
||
<entry>the time (in ms) to retry a connection after failing</entry>
|
||
<entry>2000</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.retry-interval-multiplier">
|
||
<link linkend="client-reconnection">connection-factory.retry-interval-multiplier</link>
|
||
</entry>
|
||
<entry>Double</entry>
|
||
<entry>multiplier to apply to successive retry intervals</entry>
|
||
<entry>1.0</entry>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="client-reconnection"
|
||
>connection-factory.max-retry-interval</link></entry>
|
||
<entry>Integer</entry>
|
||
<entry>The maximum retry interval in the case a retry-interval-multiplier has been specified</entry>
|
||
<entry>2000</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.scheduled-thread-pool-max-size">
|
||
<link linkend="thread-pooling.client.side">connection-factory.scheduled-thread-pool-max-size</link>
|
||
</entry>
|
||
<entry>Integer</entry>
|
||
<entry>the size of the <emphasis>scheduled thread</emphasis> pool</entry>
|
||
<entry>5</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.thread-pool-max-size">
|
||
<link linkend="thread-pooling.client.side">connection-factory.thread-pool-max-size</link>
|
||
</entry>
|
||
<entry>Integer</entry>
|
||
<entry>the size of the thread pool</entry>
|
||
<entry>-1</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.transaction-batch-size">
|
||
<link linkend="using-jms.txbatchsize">
|
||
connection-factory.transaction-batch-size</link>
|
||
</entry>
|
||
<entry>Integer</entry>
|
||
<entry>the batch size (in bytes) between acknowledgements when using a
|
||
transactional session</entry>
|
||
<entry>1024 * 1024</entry>
|
||
</row>
|
||
<row>
|
||
<entry id="configuration.connection-factory.use-global-pools">
|
||
<link linkend="thread-pooling.client.side">connection-factory.use-global-pools</link>
|
||
</entry>
|
||
<entry>Boolean</entry>
|
||
<entry>whether or not to use a global thread pool for threads</entry>
|
||
<entry>true</entry>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="using-jms.server.configuration"
|
||
>queue</link></entry>
|
||
<entry>Queue</entry>
|
||
<entry>a queue to create and add to JNDI</entry>
|
||
<entry/>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="using-jms.server.configuration">queue.name
|
||
(attribute)</link></entry>
|
||
<entry>String</entry>
|
||
<entry>unique name of the queue</entry>
|
||
<entry/>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="using-jms.server.configuration"
|
||
>queue.entry</link></entry>
|
||
<entry>String</entry>
|
||
<entry>context where the queue will be bound in JNDI (there can be
|
||
many)</entry>
|
||
<entry/>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="using-jms.server.configuration"
|
||
>queue.durable</link></entry>
|
||
<entry>Boolean</entry>
|
||
<entry>is the queue durable?</entry>
|
||
<entry>true</entry>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="using-jms.server.configuration"
|
||
>queue.filter</link></entry>
|
||
<entry>String</entry>
|
||
<entry>optional filter expression for the queue</entry>
|
||
<entry/>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="using-jms.server.configuration"
|
||
>topic</link></entry>
|
||
<entry>Topic</entry>
|
||
<entry>a topic to create and add to JNDI</entry>
|
||
<entry/>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="using-jms.server.configuration">topic.name
|
||
(attribute)</link></entry>
|
||
<entry>String</entry>
|
||
<entry>unique name of the topic</entry>
|
||
<entry/>
|
||
</row>
|
||
<row>
|
||
<entry><link linkend="using-jms.server.configuration"
|
||
>topic.entry</link></entry>
|
||
<entry>String</entry>
|
||
<entry>context where the topic will be bound in JNDI (there can be
|
||
many)</entry>
|
||
<entry/>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
</section>
|
||
|
||
<section id="configuration.masked-password">
|
||
<title>Using Masked Passwords in Configuration Files</title>
|
||
<para>By default all passwords in ActiveMQ 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. </para>
|
||
|
||
<para>ActiveMQ 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 ActiveMQ loads a masked password, it uses a suitable 'decoder' to decode it into real password.</para>
|
||
|
||
<para>ActiveMQ provides a default password encoder and decoder. Optionally users can use or implement their own encoder and decoder for
|
||
masking the passwords.</para>
|
||
|
||
<section> <title>Password Masking in Server Configuration File</title>
|
||
|
||
<section> <title>The password masking property</title>
|
||
|
||
<para>The server configuration file has a property that defines the default masking behaviors over the entire file scope.</para>
|
||
|
||
<para><literal>mask-password</literal>: 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".</para>
|
||
</section>
|
||
|
||
<section> <title>Specific masking behaviors</title>
|
||
|
||
<section> <title>cluster-password</title>
|
||
|
||
<para>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.</para>
|
||
</section>
|
||
|
||
<section> <title>Passwords in connectors and acceptors</title>
|
||
|
||
<para>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.</para>
|
||
|
||
<para>When a Connector or Acceptor configuration is initialised, ActiveMQ will add the "mask-password" and
|
||
"password-codec" values to the Connector or Acceptors params using the keys <literal>activemq.usemaskedpassword</literal>
|
||
and <literal>activemq.passwordcodec</literal> 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.</para>
|
||
</section>
|
||
|
||
<section> <title>Passwords in Core Bridge configurations</title>
|
||
|
||
<para>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'.</para>
|
||
</section>
|
||
</section>
|
||
|
||
<section> <title>Examples</title>
|
||
|
||
<para>The following table summarizes the relations among the above-mentioned properties</para>
|
||
|
||
<table frame="topbot" border="2">
|
||
<tgroup cols="4">
|
||
<colspec colname="c1" colnum="1"/>
|
||
<colspec colname="c2" colnum="2"/>
|
||
<colspec colname="c3" colnum="3"/>
|
||
<colspec colname="c4" colnum="4"/>
|
||
<thead>
|
||
<row>
|
||
<entry>mask-password</entry>
|
||
<entry>cluster-password</entry>
|
||
<entry>acceptor/connector passwords</entry>
|
||
<entry>bridge password</entry>
|
||
</row>
|
||
</thead>
|
||
<tbody>
|
||
<row>
|
||
<entry>absent</entry>
|
||
<entry>plain text</entry>
|
||
<entry>plain text</entry>
|
||
<entry>plain text</entry>
|
||
</row>
|
||
<row>
|
||
<entry>false</entry>
|
||
<entry>plain text</entry>
|
||
<entry>plain text</entry>
|
||
<entry>plain text</entry>
|
||
</row>
|
||
<row>
|
||
<entry>true</entry>
|
||
<entry>masked</entry>
|
||
<entry>masked</entry>
|
||
<entry>masked</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</table>
|
||
|
||
<para>Examples</para>
|
||
|
||
<para>Note: In the following examples if related attributed or properties are absent, it means they are not specified in the configure file.</para>
|
||
|
||
<para>example 1</para>
|
||
|
||
<programlisting>
|
||
<cluster-password>bbc</cluster-password></programlisting>
|
||
|
||
<para>This indicates the cluster password is a plain text value ("bbc").</para>
|
||
|
||
<para>example 2</para>
|
||
|
||
<programlisting>
|
||
<mask-password>true</mask-password>
|
||
<cluster-password>80cf731af62c290</cluster-password></programlisting>
|
||
|
||
<para>This indicates the cluster password is a masked value and ActiveMQ 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.</para>
|
||
</section>
|
||
</section>
|
||
|
||
<section> <title>JMS Bridge password masking</title>
|
||
|
||
<para>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:</para>
|
||
|
||
<para><literal>useMaskedPassword</literal> -- If set to "true" the passwords are masked. Default is false.</para>
|
||
<para><literal>passwordCodec</literal> -- Class name and its parameters for the Decoder used to decode the masked password. Ignored if
|
||
<literal>useMaskedPassword</literal> 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:</para>
|
||
|
||
<literal>
|
||
<property name="useMaskedPassword">true</property>
|
||
</literal><para></para>
|
||
<literal>
|
||
<property name="passwordCodec">com.foo.FooDecoder;key=value</property>
|
||
</literal>
|
||
<para>ActiveMQ will load this property and initialize the class with a parameter map containing the "key"->"value" pair.
|
||
If <literal>passwordCodec</literal> is not specified, the built-in decoder is used.</para>
|
||
|
||
</section>
|
||
|
||
<section> <title>Masking passwords in ActiveMQ ResourceAdapters and MDB activation configurations</title>
|
||
|
||
<para>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:</para>
|
||
|
||
<para><literal>UseMaskedPassword</literal> -- If setting to "true" the passwords are masked. Default is false.</para>
|
||
<para><literal>PasswordCodec</literal> -- 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:</para>
|
||
|
||
<programlisting>
|
||
<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></programlisting>
|
||
|
||
<para>With this configuration, both passwords in ra.xml and all of its MDBs will have to be in masked form.</para>
|
||
|
||
</section>
|
||
|
||
<section> <title>Masking passwords in activemq-users.xml</title>
|
||
|
||
<para>ActiveMQ'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:</para>
|
||
|
||
<para> <literal>mask-password</literal> -- If set to "true" all the passwords are masked. Default is false.</para>
|
||
<para> <literal>password-codec</literal> -- Class name and its parameters for the Decoder used to decode the masked password.
|
||
Ignored if <literal>mask-password</literal> 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:</para>
|
||
|
||
<programlisting>
|
||
<mask-password>true</mask-password>
|
||
<password-codec>org.apache.activemq.utils.DefaultSensitiveStringCodec;key=hello world</password-codec></programlisting>
|
||
|
||
<para>When so configured, the ActiveMQ 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.</para>
|
||
|
||
</section>
|
||
|
||
<section> <title>Choosing a decoder for password masking</title>
|
||
|
||
<para>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.</para>
|
||
|
||
<para>For user's convenience ActiveMQ provides a default built-in Decoder. However a user can if they so wish implement their own.</para>
|
||
|
||
<section><title>The built-in Decoder</title>
|
||
|
||
<para>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.activemq.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:</para>
|
||
|
||
<programlisting>
|
||
java org.apache.activemq.utils.DefaultSensitiveStringCodec "your plaintext password"</programlisting>
|
||
|
||
<para>Make sure the classpath is correct. You'll get something like</para>
|
||
|
||
<programlisting>
|
||
Encoded password: 80cf731af62c290</programlisting>
|
||
|
||
<para>Just copy "80cf731af62c290" and replace your plaintext password with it.</para>
|
||
</section>
|
||
|
||
<section><title>Using a different decoder</title>
|
||
|
||
<para>It is possible to use a different decoder rather than the built-in one. Simply make sure the decoder
|
||
is in ActiveMQ's classpath and configure the server to use it as follows:</para>
|
||
|
||
<programlisting>
|
||
<password-codec>com.foo.SomeDecoder;key1=value1;key2=value2</password-codec></programlisting>
|
||
|
||
<para>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:</para>
|
||
|
||
<programlisting>
|
||
<password-codec>com.foo.NewDecoder;key-location=/some/url/to/keyfile</password-codec></programlisting>
|
||
|
||
<para>Then configure your cluster-password like this:</para>
|
||
|
||
<programlisting>
|
||
<mask-password>true</mask-password>
|
||
<cluster-password>masked_password</cluster-password></programlisting>
|
||
|
||
<para>When ActiveMQ 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.</para>
|
||
</section>
|
||
|
||
<section><title>Implementing your own codecs</title>
|
||
|
||
<para>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 <literal>org.apache.activemq.utils.SensitiveDataCodec<T></literal> interface:</para>
|
||
|
||
<programlisting>
|
||
public interface SensitiveDataCodec<T>
|
||
{
|
||
T decode(Object mask) throws Exception;
|
||
|
||
void init(Map<String, String> params);
|
||
}</programlisting>
|
||
|
||
<para>This is a generic type interface but normally for a password you just need String type.
|
||
So a new decoder would be defined like </para>
|
||
|
||
<programlisting>
|
||
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.
|
||
}
|
||
}</programlisting>
|
||
|
||
<para>Last but not least, once you get your own decoder, please add it to the classpath. Otherwise ActiveMQ will
|
||
fail to load it!</para>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
</chapter>
|