Modified: websites/production/activemq/content/security.html
==============================================================================
--- websites/production/activemq/content/security.html (original)
+++ websites/production/activemq/content/security.html Fri Aug 25 08:24:11 2017
@@ -32,17 +32,6 @@
</style>
<![endif]-->
- <link
href='http://activemq.apache.org/styles/highlighter/styles/shCore.css'
rel='stylesheet' type='text/css' />
- <link
href='http://activemq.apache.org/styles/highlighter/styles/shThemeEclipse.css'
rel='stylesheet' type='text/css' />
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shCore.js'
type='text/javascript'></script>
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shBrushPlain.js'
type='text/javascript'></script>
-
- <script type="text/javascript">
- SyntaxHighlighter.defaults['toolbar'] = false;
- SyntaxHighlighter.all();
- </script>
<title>
Apache ActiveMQ ™ -- Security
@@ -82,16 +71,13 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><p>ActiveMQ 4.x and greater provides
pluggable security through various different providers.</p><p>The most common
providers are</p><ul><li><a shape="rect" class="external-link"
href="http://java.sun.com/products/jaas/"; rel="nofollow">JAAS</a> for
authentication</li><li>a default authorization mechanism using a simple XML
configuration file.</li></ul><h3
id="Security-Authentication">Authentication</h3><p>The default <a shape="rect"
class="external-link" href="http://java.sun.com/products/jaas/";
rel="nofollow">JAAS</a> plugin relies on the standard JAAS mechanism for
authentication. Refer to the <a shape="rect" class="external-link"
href="http://java.sun.com/products/jaas/reference/docs/index.html";
rel="nofollow">documentation</a> for more detail.</p><p>Typically you configure
JAAS using a config file like <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/resources/login.config
">this one</a> and set the <strong>java.security.auth.login.config</strong>
system property to point to it. If no system property is specified then by
default the ActiveMQ JAAS plugin will look for <strong>login.config</strong> on
the classpath and use that.</p><h4
id="Security-AuthenticationExample">Authentication Example</h4><p>Here is an
example <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/resources/login.config";>login.config</a>
which then points to these files</p><ul><li><a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/resources/org/apache/activemq/security/users.properties";>users.properties</a></li><li><a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/resources/org/apache/activemq/security/groups.properties";>groups.properties</a></li></ul><p><strong>Note:</strong>
Until version 5.11.1, these property files got reloaded on every
authentication request by default. So updates to users, password and groups
were loaded immediately. From 5.12 onward they only get reloaded if reload=true
is set in your LoginModule configuration, e.g.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">activemq {
+<div class="wiki-content maincontent"><p>ActiveMQ 4.x and greater provides
pluggable security through various different providers.</p><p>The most common
providers are</p><ul><li><a shape="rect" class="external-link"
href="http://java.sun.com/products/jaas/"; rel="nofollow">JAAS</a> for
authentication</li><li>a default authorization mechanism using a simple XML
configuration file.</li></ul><h3
id="Security-Authentication">Authentication</h3><p>The default <a shape="rect"
class="external-link" href="http://java.sun.com/products/jaas/";
rel="nofollow">JAAS</a> plugin relies on the standard JAAS mechanism for
authentication. Refer to the <a shape="rect" class="external-link"
href="http://java.sun.com/products/jaas/reference/docs/index.html";
rel="nofollow">documentation</a> for more detail.</p><p>Typically you configure
JAAS using a config file like <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/resources/login.config
">this one</a> and set the <strong>java.security.auth.login.config</strong>
system property to point to it. If no system property is specified then by
default the ActiveMQ JAAS plugin will look for <strong>login.config</strong> on
the classpath and use that.</p><h4
id="Security-AuthenticationExample">Authentication Example</h4><p>Here is an
example <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/resources/login.config";>login.config</a>
which then points to these files</p><ul><li><a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/resources/org/apache/activemq/security/users.properties";>users.properties</a></li><li><a
shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/resources/org/apache/activemq/security/groups.properties";>groups.properties</a></li></ul><p><strong>Note:</strong>
Until version 5.11.1, these property files got reloaded on every
authentication request by default. So updates to users, password and groups
were loaded immediately. From 5.12 onward they only get reloaded if reload=true
is set in your LoginModule configuration, e.g.</p><plain-text-body>activemq {
org.apache.activemq.jaas.PropertiesLoginModule required
org.apache.activemq.jaas.properties.user="users.properties"
org.apache.activemq.jaas.properties.group="groups.properties"
reload=true;
};
-</pre>
-</div></div><p>If reload=true is not set, these property files get loaded on
broker startup only!! See AMQ-5876 for details.</p><h4
id="Security-SimpleAuthenticationPlugin">Simple Authentication Plugin</h4><p>If
you have modest authentication requirements (or just want to quickly set up
your testing environment) you can use SimpleAuthenticationPlugin. With this
plugin you can define users and groups directly in the broker's XML
configuration. Take a look at the following snippet for example:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><simpleAuthenticationPlugin>
+</plain-text-body><p>If reload=true is not set, these property files get
loaded on broker startup only!! See AMQ-5876 for details.</p><h4
id="Security-SimpleAuthenticationPlugin">Simple Authentication Plugin</h4><p>If
you have modest authentication requirements (or just want to quickly set up
your testing environment) you can use SimpleAuthenticationPlugin. With this
plugin you can define users and groups directly in the broker's XML
configuration. Take a look at the following snippet for example:</p><parameter
ac:name="">xml</parameter><plain-text-body><simpleAuthenticationPlugin>
<users>
<authenticationUser username="system" password="manager"
groups="users,admins"/>
@@ -100,9 +86,7 @@
<authenticationUser username="guest" password="password"
groups="guests"/>
</users>
</simpleAuthenticationPlugin>
-</pre>
-</div></div><p>Users and groups defined in this way can be later used with the
appropriate authorization plugin.</p><h5
id="Security-Anonymousaccess">Anonymous access</h5><p>From version 5.4.0
onwards, you can configure simple authentication plugin to allow anonymous
access to the broker.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><simpleAuthenticationPlugin
anonymousAccessAllowed="true">
+</plain-text-body><p>Users and groups defined in this way can be later used
with the appropriate authorization plugin.</p><h5
id="Security-Anonymousaccess">Anonymous access</h5><p>From version 5.4.0
onwards, you can configure simple authentication plugin to allow anonymous
access to the broker.</p><parameter
ac:name="">xml</parameter><plain-text-body><simpleAuthenticationPlugin
anonymousAccessAllowed="true">
<users>
<authenticationUser username="system" password="manager"
groups="users,admins"/>
@@ -111,17 +95,13 @@
<authenticationUser username="guest" password="password"
groups="guests"/>
</users>
</simpleAuthenticationPlugin>
-</pre>
-</div></div><p>To allow anonymous access to the broker, use
<code>anonymousAccessAllowed</code> attribute and set it to <code>true</code>
as shown above. Now, when the client connects without username and password
provided, a default username (<code>anonymous</code>) and group
(<code>anonymous</code>) will be assigned to its security context. You can use
this username and password to authorize client's access to appropriate broker
resources (see the next section). You can also change username and group that
will be assigned to <em>anonymous</em> users by using
<code>anonymousUser</code> and <code>anonymousGroup</code> attributes.</p><h3
id="Security-Authorization">Authorization</h3><p>In ActiveMQ we use a number of
operations which you can associate with user roles and either individual queues
or topics or you can use wildcards to attach to hierarchies of topics and
queues.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="conflu
enceTh"><p>Operation</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>read</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>You can browse and consume from the
destination</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>write</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>You can send messages to the
destination</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>admin</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>You can lazily create the destination if it does not
yet exist. This allows you fine grained control over which new destinations can
be dynamically created in what part of the queue/topic
hierarchy</p></td></tr></tbody></table></div><p>Queues/Topics can specified
using the ActiveMQ <a shape="rect" href="wildcards.html">Wildcards</a>
syntax.</p><h4 id="Security-AuthorizationExample">Authorization Example</h4>
<p>The following <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/resources/org/apache/activemq/security/jaas-broker.xml";>example</a>
shows these 2 plugins in operation. Though note its very easy to write your
own plugin.</p><div class="error"><span class="error">Error formatting macro:
snippet: java.lang.IndexOutOfBoundsException: Index: 20, Size: 20</span>
</div><strong>Note</strong> that full access rights should generally be given
to the ActiveMQ.Advisory destinations because by default an ActiveMQConnection
uses destination advisories to get early knowledge of temp destination creation
and deletion. In addition, dynamic network connectors use advisories to
determine consumer demand.<br clear="none"> If necessary, the use of advisories
in this manner can be disabled via the <em>watchTopicAdvisories</em> boolean
attribute of ActiveMQConnectionFactory and for a networkConnector, via the
network connector <em>st
aticBridge</em>(5.6) boolean attribute.<h3
id="Security-Broker-to-BrokerAuthenticationandAuthorization">Broker-to-Broker
Authentication and Authorization</h3><p>If you have enabled authentication for
a particular message broker, then other brokers that wish to connect to that
broker must provide the proper authentication credentials via their
<networkConnector> element. For example, suppose that we have a network
of brokers with the following configuration:</p><ul class="alternate"><li>The
network of brokers comprises two brokers (BrokerA and
BrokerB)</li><li>Authentication for BrokerA has been enabled via the example
<simpleAuthenticationPlugin> element.</li><li>Authentication for BrokerB
has not been enabled.</li><li>BrokerA only listens for connections. In other
words, BrokerA has a <transportConnector> element, but no
<networkConnector> elements.</li></ul><p>In order for BrokerB to connect
to BrokerA, the corresponding <networkConnector> element in
BrokerB's XML configuration file must be set up as follows.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><networkConnectors>
+</plain-text-body><p>To allow anonymous access to the broker, use
<code>anonymousAccessAllowed</code> attribute and set it to <code>true</code>
as shown above. Now, when the client connects without username and password
provided, a default username (<code>anonymous</code>) and group
(<code>anonymous</code>) will be assigned to its security context. You can use
this username and password to authorize client's access to appropriate broker
resources (see the next section). You can also change username and group that
will be assigned to <em>anonymous</em> users by using
<code>anonymousUser</code> and <code>anonymousGroup</code> attributes.</p><h3
id="Security-Authorization">Authorization</h3><p>In ActiveMQ we use a number of
operations which you can associate with user roles and either individual queues
or topics or you can use wildcards to attach to hierarchies of topics and
queues.</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="
confluenceTh"><p>Operation</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>read</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>You can browse and consume from the
destination</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>write</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>You can send messages to the
destination</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>admin</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>You can lazily create the destination if it does not
yet exist. This allows you fine grained control over which new destinations can
be dynamically created in what part of the queue/topic
hierarchy</p></td></tr></tbody></table></div><p>Queues/Topics can specified
using the ActiveMQ <a shape="rect" href="wildcards.html">Wildcards</a>
syntax.</p><h4 id="Security-AuthorizationExample">Authorization Exampl
e</h4><p>The following <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/activemq-unit-tests/src/test/resources/org/apache/activemq/security/jaas-broker.xml";>example</a>
shows these 2 plugins in operation. Though note its very easy to write your
own
plugin.<plain-text-body>{snippet:id=example|lang=xml|url=activemq/trunk/activemq-unit-tests/src/test/resources/org/apache/activemq/security/jaas-broker.xml}</plain-text-body><strong>Note</strong>
that full access rights should generally be given to the ActiveMQ.Advisory
destinations because by default an ActiveMQConnection uses destination
advisories to get early knowledge of temp destination creation and deletion. In
addition, dynamic network connectors use advisories to determine consumer
demand.<br clear="none"> If necessary, the use of advisories in this manner can
be disabled via the <em>watchTopicAdvisories</em> boolean attribute of
ActiveMQConnectionFactory and for a networkConnector, via t
he network connector <em>staticBridge</em>(5.6) boolean attribute.</p><h3
id="Security-Broker-to-BrokerAuthenticationandAuthorization">Broker-to-Broker
Authentication and Authorization</h3><p>If you have enabled authentication for
a particular message broker, then other brokers that wish to connect to that
broker must provide the proper authentication credentials via their
<networkConnector> element. For example, suppose that we have a network
of brokers with the following configuration:</p><ul class="alternate"><li>The
network of brokers comprises two brokers (BrokerA and
BrokerB)</li><li>Authentication for BrokerA has been enabled via the example
<simpleAuthenticationPlugin> element.</li><li>Authentication for BrokerB
has not been enabled.</li><li>BrokerA only listens for connections. In other
words, BrokerA has a <transportConnector> element, but no
<networkConnector> elements.</li></ul><p>In order for BrokerB to connect
to BrokerA, the corresponding <n
etworkConnector> element in BrokerB's XML configuration file must be set up
as follows.</p><parameter
ac:name="">xml</parameter><plain-text-body><networkConnectors>
<networkConnector name="brokerAbridge"
userName="user"
password="password"
uri="static://(tcp://brokerA:61616)"/>
</networkConnectors>
-</pre>
-</div></div><p>Note how BrokerB's <networkConnector> element must
provide the proper credentials in order to connect to BrokerA. If authorization
has been enabled on BrokerA, then the userName assigned to the
<networkConnector> element must also have the proper authorization
credentials. Messages cannot be forwarded from BrokerB to BrokerA if BrokerA
has authorization enabled and BrokerB's corresponding <networkConnector>
element's userName has not been given the proper authorization
credentials.</p><p>Also, if BrokerA is given a <networkConnector> element
so that it can initiate a connection to BrokerB, then that
<networkConnector> must be given a userName/password combination that is
defined in the <simpleAuthenticationPlugin> element; this is required
even though BrokerB does not have authentication services enabled.</p><h3
id="Security-ControllingAccessToTemporaryDestinations">Controlling Access To
Temporary Destinations</h3><p>To control acce
ss to temporary destinations, you will need to add a
<tempDestinationAuthorizationEntry> element to the authorizationMap.
Through this element, you control access to all temporary destinations. If this
element is not present, read, write, and admin privileges for temporary
destinations will be granted to all. In the example below, read, write, and
admin privileges for temporary destinations are only granted to those clients
that have been assigned to the 'admin' group.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><broker>
+</plain-text-body><p>Note how BrokerB's <networkConnector> element must
provide the proper credentials in order to connect to BrokerA. If authorization
has been enabled on BrokerA, then the userName assigned to the
<networkConnector> element must also have the proper authorization
credentials. Messages cannot be forwarded from BrokerB to BrokerA if BrokerA
has authorization enabled and BrokerB's corresponding <networkConnector>
element's userName has not been given the proper authorization
credentials.</p><p>Also, if BrokerA is given a <networkConnector> element
so that it can initiate a connection to BrokerB, then that
<networkConnector> must be given a userName/password combination that is
defined in the <simpleAuthenticationPlugin> element; this is required
even though BrokerB does not have authentication services enabled.</p><h3
id="Security-ControllingAccessToTemporaryDestinations">Controlling Access To
Temporary Destinations</h3><p>To contro
l access to temporary destinations, you will need to add a
<tempDestinationAuthorizationEntry> element to the authorizationMap.
Through this element, you control access to all temporary destinations. If this
element is not present, read, write, and admin privileges for temporary
destinations will be granted to all. In the example below, read, write, and
admin privileges for temporary destinations are only granted to those clients
that have been assigned to the 'admin' group.</p><parameter
ac:name="">xml</parameter><plain-text-body><broker>
..
<plugins>
..
@@ -142,9 +122,7 @@
</plugins>
..
</broker>
-</pre>
-</div></div><h3 id="Security-LDAPAuthenticationUsingtheJAASPlugin">LDAP
Authentication Using the JAAS Plugin</h3><div
class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>A new/better ldap authorization
module is available since 5.6. See <a shape="rect"
href="cached-ldap-authorization-module.html">Cached LDAP Authorization
Module</a> for more info.</p></div></div><p>1. Configure the JAAS
LDAPLoginModule and the LDAPAuthorizationMap in activemq.xml:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <plugins>
+</plain-text-body><h3 id="Security-LDAPAuthenticationUsingtheJAASPlugin">LDAP
Authentication Using the JAAS Plugin</h3><parameter ac:name="">New
module</parameter><rich-text-body><p>A new/better ldap authorization module is
available since 5.6. See <a shape="rect"
href="cached-ldap-authorization-module.html">Cached LDAP Authorization
Module</a> for more info.</p></rich-text-body><p>1. Configure the JAAS
LDAPLoginModule and the LDAPAuthorizationMap in activemq.xml:</p><parameter
ac:name="">xml</parameter><plain-text-body> <plugins>
<!-- use JAAS to authenticate using the login.config file on the
classpath to configure JAAS -->
<jaasAuthenticationPlugin configuration="LdapConfiguration" />
<!-- lets configure a destination based role/group authorization
mechanism -->
@@ -175,9 +153,7 @@
</map>
</authorizationPlugin>
</plugins>
-</pre>
-</div></div><p>2. Configure the JAAS login.config (I haven't de-duplicated the
config yet):</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
+</plain-text-body><p>2. Configure the JAAS login.config (I haven't
de-duplicated the config yet):</p><plain-text-body>
LdapConfiguration {
org.apache.activemq.jaas.LDAPLoginModule required
debug=true
@@ -197,9 +173,7 @@ LdapConfiguration {
roleSearchSubtree=true
;
};
-</pre>
-</div></div><p>3. Import the following LDIF file into the LDAP server:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">version: 1
+</plain-text-body><p>3. Import the following LDIF file into the LDAP
server:</p><plain-text-body>version: 1
#
# Sample LDIF for ActiveMQ LDAP authentication and authorisation
@@ -368,9 +342,7 @@ userPassword: {SSHA}j0NpveEO0YD5rgI5kY8O
objectClass: account
objectClass: simpleSecurityObject
objectClass: top
-</pre>
-</div></div><p>4. Start up ActiveMQ</p><p>5. Test it out</p><h3
id="Security-SecurityandActiveMQComponents">Security and ActiveMQ
Components</h3><p>Along with the message broker, you can optionally execute
several additional "components", such as Camel and/or the Web console. These
components establish connections with the broker; therefore, if you have
secured your broker (i.e., enabled authentication), you will have to configure
these components in order to have them provide the required security
credentials (username, password) when they connect to the broker.</p><h4
id="Security-Camel">Camel</h4><p>You may have the following Camel context
defined in your broker's XML configuration file.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><!--
+</plain-text-body><p>4. Start up ActiveMQ</p><p>5. Test it out</p><h3
id="Security-SecurityandActiveMQComponents">Security and ActiveMQ
Components</h3><p>Along with the message broker, you can optionally execute
several additional "components", such as Camel and/or the Web console. These
components establish connections with the broker; therefore, if you have
secured your broker (i.e., enabled authentication), you will have to configure
these components in order to have them provide the required security
credentials (username, password) when they connect to the broker.</p><h4
id="Security-Camel">Camel</h4><p>You may have the following Camel context
defined in your broker's XML configuration file.</p><parameter
ac:name="">xml</parameter><plain-text-body><!--
** Lets deploy some Enterprise Integration Patterns inside the ActiveMQ
Message Broker
** For more details see
**
@@ -383,12 +355,8 @@ objectClass: top
<to uri="activemq:example.B"/>
</route>
</camelContext>
-</pre>
-</div></div><p>The above configuration is not set up to work within a secure
environment.</p><p>If the application is running in an OSGi container, add the
following line before the CamelContext definition:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><osgi:reference id="activemq"
interface="org.apache.camel.Component" />
-</pre>
-</div></div><p>This allows any pre-configured instance of the
ActiveMQComponent deployed in the container to take precedence on the default
ActiveMQComponent.</p><p>That is, with the above configuration, Camel will
establish a connection with ActiveMQ, but will not provide a username and
password. Therefore, when ActiveMQ security is enabled, the above configuration
results in a security exception. The exception will be thrown multiple times,
because Camel will continue to retry the connection. If you're not using Camel,
comment out the above XML code. If you are using Camel, add the following bean
definition to your broker's XML configuration:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><!-- configure the camel activemq component to use
the current broker -->
+</plain-text-body><p>The above configuration is not set up to work within a
secure environment.</p><p>If the application is running in an OSGi container,
add the following line before the CamelContext definition:</p><parameter
ac:name="">xml</parameter><plain-text-body><osgi:reference id="activemq"
interface="org.apache.camel.Component" />
+</plain-text-body><p>This allows any pre-configured instance of the
ActiveMQComponent deployed in the container to take precedence on the default
ActiveMQComponent.</p><p>That is, with the above configuration, Camel will
establish a connection with ActiveMQ, but will not provide a username and
password. Therefore, when ActiveMQ security is enabled, the above configuration
results in a security exception. The exception will be thrown multiple times,
because Camel will continue to retry the connection. If you're not using Camel,
comment out the above XML code. If you are using Camel, add the following bean
definition to your broker's XML configuration:</p><parameter
ac:name="">xml</parameter><plain-text-body><!-- configure the camel activemq
component to use the current broker -->
<bean id="activemq"
class="org.apache.activemq.camel.component.ActiveMQComponent" >
<property name="connectionFactory">
<bean class="org.apache.activemq.ActiveMQConnectionFactory">
@@ -398,31 +366,22 @@ objectClass: top
</bean>
</property>
</bean>
-</pre>
-</div></div><p>With the above bean definition, Camel will pass the specified
security credentials when it connects to the broker.</p><p>If the broker is
running in an OSGi container, add the following line after the
ActiveMQComponent bean definition:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><service ref="activemq"
interface="org.apache.camel.Component"/>
-</pre>
-</div></div><h4 id="Security-WebConsole">Web Console</h4><p>If you want to use
the Web Console with a secured broker, you have to change
<code>connectionFactory</code> bean in your
<code>webapps/admin/WEB-INF/webconsole-embeded.xml</code> to something like
this:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><bean id="connectionFactory"
class="org.apache.activemq.ActiveMQConnectionFactory">
+</plain-text-body><p>With the above bean definition, Camel will pass the
specified security credentials when it connects to the broker.</p><p>If the
broker is running in an OSGi container, add the following line after the
ActiveMQComponent bean definition:</p><parameter
ac:name="">xml</parameter><plain-text-body><service ref="activemq"
interface="org.apache.camel.Component"/>
+</plain-text-body><h4 id="Security-WebConsole">Web Console</h4><p>If you want
to use the Web Console with a secured broker, you have to change
<code>connectionFactory</code> bean in your
<code>webapps/admin/WEB-INF/webconsole-embeded.xml</code> to something like
this:</p><parameter ac:name="">xml</parameter><plain-text-body><bean
id="connectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
<property name="brokerURL" value="vm://localhost"/>
<property name="userName" value="system"/>
<property name="password" value="manager"/>
</bean>
-</pre>
-</div></div><h4 id="Security-DefaultCredentials">Default
Credentials</h4><p>Starting with version 5.3, all of the above configuration
details are included in the default ActiveMQ configuration. Also, there is a
central place where you can set credentials that these components will use to
connect to the broker. Just set your desired username and password in the
<code>conf/credentials.properties</code> file, which by default looks like
this:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">activemq.username=system
+</plain-text-body><h4 id="Security-DefaultCredentials">Default
Credentials</h4><p>Starting with version 5.3, all of the above configuration
details are included in the default ActiveMQ configuration. Also, there is a
central place where you can set credentials that these components will use to
connect to the broker. Just set your desired username and password in the
<code>conf/credentials.properties</code> file, which by default looks like
this:</p><plain-text-body>activemq.username=system
activemq.password=manager
-</pre>
-</div></div><h4 id="Security-EncryptedPasswords">Encrypted Passwords</h4><p>As
of version 5.4.1 you can also use <a shape="rect"
href="encrypted-passwords.html">Encrypted passwords</a> with your broker</p><h3
id="Security-MessagelevelAuthorization">Message level Authorization</h3><p>It's
also possible to authorize each single message using some content based
authorization policy of your choosing. In comparison to the other security
options described before, Message level Authorization requires a bit more than
just some configuration. You have to start with creating a new maven project
and add the <a shape="rect" class="external-link"
href="https://mvnrepository.com/artifact/org.apache.activemq/activemq-all";
rel="nofollow">activemq-all</a> maven dependency (in the same version as your
activemq installation) to the pom.xml of your new project.<br clear="none">In
the next step you have to create a new Java class and let it implement the
org.apache.activemq.security.MessageAuthoriz
ationPolicy interface. After that, simply add a method with
signature:</p><p>public boolean isAllowedToConsume(ConnectionContext context,
Message message){...}</p><p>to the new Java class. For usage of your own
Message level Authorization policy, the Java class has to be packaged as jar
and added to the /lib folder of ActiveMQ to make it available for ActiveMQ. In
the last step, it has to be configured on the broker directly by using the *
messageAuthorizationPolicy* property or add it to the XML as follows</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><broker>
+</plain-text-body><h4 id="Security-EncryptedPasswords">Encrypted
Passwords</h4><p>As of version 5.4.1 you can also use <a shape="rect"
href="encrypted-passwords.html">Encrypted passwords</a> with your broker</p><h3
id="Security-MessagelevelAuthorization">Message level Authorization</h3><p>It's
also possible to authorize each single message using some content based
authorization policy of your choosing. In comparison to the other security
options described before, Message level Authorization requires a bit more than
just some configuration. You have to start with creating a new maven project
and add the <a shape="rect" class="external-link"
href="https://mvnrepository.com/artifact/org.apache.activemq/activemq-all";
rel="nofollow">activemq-all</a> maven dependency (in the same version as your
activemq installation) to the pom.xml of your new project.<br clear="none">In
the next step you have to create a new Java class and let it implement the
org.apache.activemq.security.MessageAu
thorizationPolicy interface. After that, simply add a method with
signature:</p><p>public boolean isAllowedToConsume(ConnectionContext context,
Message message){...}</p><p>to the new Java class. For usage of your own
Message level Authorization policy, the Java class has to be packaged as jar
and added to the /lib folder of ActiveMQ to make it available for ActiveMQ. In
the last step, it has to be configured on the broker directly by using the *
messageAuthorizationPolicy* property or add it to the XML as
follows</p><parameter ac:name="">xml</parameter><plain-text-body><broker>
..
<messageAuthorizationPolicy>
<bean class="com.acme.MyMessageAuthorizationPolicy" xmlns=""/>
</messageAuthorizationPolicy>
..
</broker>
-</pre>
-</div></div><h2
id="Security-ImplementingyourowncustomSecurityPlugin">Implementing your own
custom Security Plugin</h2><p>All of the various security implementations are
implemented as <a shape="rect" href="interceptors.html">Interceptors</a> so its
very easy to add your own custom implementation. Its probably easier to start
with one of the <a shape="rect" class="external-link"
href="http://activemq.apache.org/maven/apidocs/org/apache/activemq/security/package-summary.html";>simple
implementations</a> though if you are using JAAS you could derive from the <a
shape="rect" class="external-link"
href="http://activemq.apache.org/maven/apidocs/org/apache/activemq/jaas/package-summary.html";>JAAS
implementation</a>.</p><h3 id="Security-ThirdPartyTools">Third Party
Tools</h3><ul><li><a shape="rect" class="external-link"
href="http://www.ttmsolutions.com/Apache_Software/ActiveMQ_LDAP_JDBC_Security_Plugins.php";
rel="nofollow">ActiveMQ LDAP and JDBC Security Plugins from TTM
Solutions</a></li>
</ul></div>
+</plain-text-body><h2
id="Security-ImplementingyourowncustomSecurityPlugin">Implementing your own
custom Security Plugin</h2><p>All of the various security implementations are
implemented as <a shape="rect" href="interceptors.html">Interceptors</a> so its
very easy to add your own custom implementation. Its probably easier to start
with one of the <a shape="rect" class="external-link"
href="http://activemq.apache.org/maven/apidocs/org/apache/activemq/security/package-summary.html";>simple
implementations</a> though if you are using JAAS you could derive from the <a
shape="rect" class="external-link"
href="http://activemq.apache.org/maven/apidocs/org/apache/activemq/jaas/package-summary.html";>JAAS
implementation</a>.</p><h3 id="Security-ThirdPartyTools">Third Party
Tools</h3><ul><li><a shape="rect" class="external-link"
href="http://www.ttmsolutions.com/Apache_Software/ActiveMQ_LDAP_JDBC_Security_Plugins.php";
rel="nofollow">ActiveMQ LDAP and JDBC Security Plugins from TTM Solutions</a
></li></ul></div>
</td>
<td valign="top">
<div class="navigation">
Modified: websites/production/activemq/content/siteindex.html
==============================================================================
--- websites/production/activemq/content/siteindex.html (original)
+++ websites/production/activemq/content/siteindex.html Fri Aug 25 08:24:11 2017
@@ -704,7 +704,7 @@
<div class="smalltext" style="margin: 0 0 0 36px">Quite possibly
. See the JDBC Support page for details of how to configure for your database
or how to let us know of a database which does not work. Also see
Persistence</div>
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> <a
shape="rect"
href="https://cwiki.apache.org/confluence/display/ACTIVEMQ/Download";>Download</a>
<br clear="none">
- <div class="smalltext" style="margin: 0 0 0 36px">Latest Releases
http://activemq.apache.org/activemq-500-release.data/activemq-5.x-box-reflection.png
The latest stable release is the ActiveMQ 5.15.0 Release Getting past releases
See the Download Archives for all time releases. In Progress Maven
Reposito</div>
+ <div class="smalltext" style="margin: 0 0 0 36px">Latest Releases
The latest stable release is the ActiveMQ 5.15.0 Release Getting past
releases See the Download Archives for all time releases. In Progress Maven
Repositories All ActiveMQ releases are available from the Maven central
repository https://</div>
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> <a
shape="rect"
href="https://cwiki.apache.org/confluence/display/ACTIVEMQ/Download+Archives";>Download
Archives</a>
<br clear="none">
<div class="smalltext" style="margin: 0 0 0 36px">Download
archives You can use the Apache Archives to download all the ActiveMQ releases.
http://archive.apache.org/dist/activemq/
http://archive.apache.org/dist/activemq/ - ActiveMQ releases
http://archive.apache.org/dist/activemq/apache-activemq/ http://</div>
Modified: websites/production/activemq/content/slow-consumer-handling.html
==============================================================================
--- websites/production/activemq/content/slow-consumer-handling.html (original)
+++ websites/production/activemq/content/slow-consumer-handling.html Fri Aug 25
08:24:11 2017
@@ -32,15 +32,6 @@
</style>
<![endif]-->
- <link
href='http://activemq.apache.org/styles/highlighter/styles/shCore.css'
rel='stylesheet' type='text/css' />
- <link
href='http://activemq.apache.org/styles/highlighter/styles/shThemeEclipse.css'
rel='stylesheet' type='text/css' />
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shCore.js'
type='text/javascript'></script>
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
-
- <script type="text/javascript">
- SyntaxHighlighter.defaults['toolbar'] = false;
- SyntaxHighlighter.all();
- </script>
<title>
Apache ActiveMQ ™ -- Slow Consumer Handling
@@ -80,23 +71,12 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><p><a shape="rect"
href="slow-consumers.html">Slow Consumers</a> can cause problems on non-durable
topics since they can force the broker to keep old messages in RAM which once
it fills up, forces the broker to slow down producers, causing the fast
consumers to be slowed down. One option we could implement in the future is
spooling to disk - but then spooling to disk could slow down the fast consumers
too.</p><p>Currently we have a strategy that lets you configure the maximum
number of matched messages the broker will keep around for a consumer in
addition to its prefetch buffer. Once this maximum is reached, as new messages
come in, older messages are discarded. This allows you to keep the RAM for
current messages and keep sending messages to a slow consumer but to discard
old messages.</p><h2
id="SlowConsumerHandling-PendingMessageLimitStrategy">Pending Message Limit
Strategy</h2><p>You can configure the <strong><code>PendingMessageLimitS
trategy</code></strong> implementation class on the destination map so that
different regions of your topic namespace can have different strategies for
dealing with slow consumers. For example you may want to use this strategy for
prices which are very high volume but for orders and trades which are lower
volume you might not wish to discard old messages.</p><p>The strategy
calculates the maximum number of pending messages to be kept in RAM for a
consumer (above its prefetch size). A value of zero means keep no messages
around other than the prefetch amount. A value greater than zero will keep up
to that amount of messages around, discarding the older messages as new
messages come in. A value of <strong><code>-1</code></strong> disables the
discarding of messages.</p><p>There are currently two different implementations
of the
strategy:</p><ul><li><strong><code>ConstantPendingMessageLimitStrategy</code></strong></li><li><strong><code>PrefetchRatePendingMessageLimitStrategy</code
></strong></li></ul><h3
>id="SlowConsumerHandling-ConstantPendingMessageLimitStrategy">ConstantPendingMessageLimitStrategy</h3><p>This
> strategy uses a constant limit for all consumers (above their prefetch
>size).</p><p>Example:</p><div class="code panel pdl" style="border-width:
>1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><constantPendingMessageLimitStrategy limit="50"/>
-</pre>
-</div></div><h3
id="SlowConsumerHandling-PrefetchRatePendingMessageLimitStrategy">PrefetchRatePendingMessageLimitStrategy</h3><p>This
strategy calculates the maximum number of pending messages using a multiplier
of the consumers prefetch size. So you could for example keep around 2.5 times
the prefetch count for each consumer.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><prefetchRatePendingMessageLimitStrategy
multiplier="2.5"/>
-</pre>
-</div></div><h3
id="SlowConsumerHandling-UsingthePrefetchPolicytoConfiguretheLimit">Using the
Prefetch Policy to Configure the Limit</h3><p>The JMS Client has a <a
shape="rect" href="what-is-the-prefetch-limit-for.html">prefetch policy</a> you
can use to configure the various prefetch limits for persistent and non
persistent queues and topics. The prefetch policy also allows you to specify
the <strong><code>maximumPendingMessageLimit</code></strong> on a per
connection/consumer basis. One minor difference with configuring this value; to
simplify operation with non-JMS clients such as with <a shape="rect"
href="openwire.html">OpenWire</a> the value of zero is ignored; so the lowest
value you can configure is <strong><code>1</code></strong>.</p><h3
id="SlowConsumerHandling-ConfiguringtheEvictionPolicy">Configuring the Eviction
Policy</h3><p>We have
a <strong><code>MessageEvictionStrategy</code></strong> which is used to
decide which message should be evicted on a slow consum
er. The default implementation is:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><oldestMessageEvictionStrategy/>
-</pre>
-</div></div><p>However, you can write your own to use some application
specific way of choosing messages for eviction. For example, if you are sending
market data price updates you may wish to find an older price value, which
might not be the oldest message.</p><p>Example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><uniquePropertyMessageEvictionStrategy
propertyName="STOCK"/>
-</pre>
-</div></div><p>where <strong><code>propertyName</code></strong> is the JMS
message property that specifies the price.</p><p>Another option could be to use
the oldest message with the lowest priority message. Therefore if you have some
high priority messages, evict the lower priority messages first even if they
are newer.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><oldestMessageWithLowestPriorityEvictionStrategy/>
-</pre>
-</div></div><h2 id="SlowConsumerHandling-Example">Example</h2><p>The following
example shows an ActiveMQ broker configuration file. Notice that for topics in
the <strong><code>PRICES.></code></strong> wildcard range
the <strong><code>pendingMessageLimitStrategy</code></strong> property is
set to only keep around <strong><code>10</code></strong> messages for each
consumer above their prefetch buffer size.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><beans
xmlns="http://www.springframework.org/schema/beans";
+<div class="wiki-content maincontent"><p><a shape="rect"
href="slow-consumers.html">Slow Consumers</a> can cause problems on non-durable
topics since they can force the broker to keep old messages in RAM which once
it fills up, forces the broker to slow down producers, causing the fast
consumers to be slowed down. One option we could implement in the future is
spooling to disk - but then spooling to disk could slow down the fast consumers
too.</p><p>Currently we have a strategy that lets you configure the maximum
number of matched messages the broker will keep around for a consumer in
addition to its prefetch buffer. Once this maximum is reached, as new messages
come in, older messages are discarded. This allows you to keep the RAM for
current messages and keep sending messages to a slow consumer but to discard
old messages.</p><h2
id="SlowConsumerHandling-PendingMessageLimitStrategy">Pending Message Limit
Strategy</h2><p>You can configure the <strong><code>PendingMessageLimitS
trategy</code></strong> implementation class on the destination map so that
different regions of your topic namespace can have different strategies for
dealing with slow consumers. For example you may want to use this strategy for
prices which are very high volume but for orders and trades which are lower
volume you might not wish to discard old messages.</p><p>The strategy
calculates the maximum number of pending messages to be kept in RAM for a
consumer (above its prefetch size). A value of zero means keep no messages
around other than the prefetch amount. A value greater than zero will keep up
to that amount of messages around, discarding the older messages as new
messages come in. A value of <strong><code>-1</code></strong> disables the
discarding of messages.</p><p>There are currently two different implementations
of the
strategy:</p><ul><li><strong><code>ConstantPendingMessageLimitStrategy</code></strong></li><li><strong><code>PrefetchRatePendingMessageLimitStrategy</code
></strong></li></ul><h3
>id="SlowConsumerHandling-ConstantPendingMessageLimitStrategy">ConstantPendingMessageLimitStrategy</h3><p>This
> strategy uses a constant limit for all consumers (above their prefetch
>size).</p><p>Example:</p><parameter
>ac:name="language">xml</parameter><plain-text-body><constantPendingMessageLimitStrategy
> limit="50"/>
+</plain-text-body><h3
id="SlowConsumerHandling-PrefetchRatePendingMessageLimitStrategy">PrefetchRatePendingMessageLimitStrategy</h3><p>This
strategy calculates the maximum number of pending messages using a multiplier
of the consumers prefetch size. So you could for example keep around 2.5 times
the prefetch count for each consumer.</p><parameter
ac:name="language">xml</parameter><plain-text-body><prefetchRatePendingMessageLimitStrategy
multiplier="2.5"/>
+</plain-text-body><h3
id="SlowConsumerHandling-UsingthePrefetchPolicytoConfiguretheLimit">Using the
Prefetch Policy to Configure the Limit</h3><p>The JMS Client has a <a
shape="rect" href="what-is-the-prefetch-limit-for.html">prefetch policy</a> you
can use to configure the various prefetch limits for persistent and non
persistent queues and topics. The prefetch policy also allows you to specify
the <strong><code>maximumPendingMessageLimit</code></strong> on a per
connection/consumer basis. One minor difference with configuring this value; to
simplify operation with non-JMS clients such as with <a shape="rect"
href="openwire.html">OpenWire</a> the value of zero is ignored; so the lowest
value you can configure is <strong><code>1</code></strong>.</p><h3
id="SlowConsumerHandling-ConfiguringtheEvictionPolicy">Configuring the Eviction
Policy</h3><p>We have
a <strong><code>MessageEvictionStrategy</code></strong> which is used to
decide which message should be evicted on a slow
consumer. The default implementation is:</p><parameter
ac:name="language">xml</parameter><plain-text-body><oldestMessageEvictionStrategy/>
+</plain-text-body><p>However, you can write your own to use some application
specific way of choosing messages for eviction. For example, if you are sending
market data price updates you may wish to find an older price value, which
might not be the oldest message.</p><p>Example:</p><parameter
ac:name="language">xml</parameter><plain-text-body><uniquePropertyMessageEvictionStrategy
propertyName="STOCK"/>
+</plain-text-body><p>where <strong><code>propertyName</code></strong> is the
JMS message property that specifies the price.</p><p>Another option could be to
use the oldest message with the lowest priority message. Therefore if you have
some high priority messages, evict the lower priority messages first even if
they are newer.</p><parameter
ac:name="language">xml</parameter><plain-text-body><oldestMessageWithLowestPriorityEvictionStrategy/>
+</plain-text-body><h2 id="SlowConsumerHandling-Example">Example</h2><p>The
following example shows an ActiveMQ broker configuration file. Notice that for
topics in the <strong><code>PRICES.></code></strong> wildcard range
the <strong><code>pendingMessageLimitStrategy</code></strong> property is
set to only keep around <strong><code>10</code></strong> messages for each
consumer above their prefetch buffer size.</p><parameter
ac:name="">xml</parameter><plain-text-body><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:amq="http://activemq.apache.org/schema/core";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://www.springframework.org/schema/beans
@@ -154,8 +134,7 @@
</policyMap>
</destinationPolicy>
</broker>
-</beans></pre>
-</div></div><h2 id="SlowConsumerHandling-UsageTips">Usage
Tips</h2><p> </p><div class="confluence-information-macro
confluence-information-macro-tip"><span class="aui-icon aui-icon-small
aui-iconfont-approve confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>It is advisable that if you know a
particular consumer is going to be slow then set its prefetch size to something
smaller than the fast consumers!</p><p>For example, if you know a particular
server is quite slow and you have very high message rates<em> and</em> you have
some very fast consumers then you might want to enable this feature and set the
prefetch on the slow servers to be a <em>little</em> lower than on the fast
servers.</p></div></div><h3
id="SlowConsumerHandling-MonitoringtheStatusofSlowConsumers">Monitoring the
Status of Slow Consumers</h3><p>You can also use a <a shape="rect"
href="jmx.html">JMX</a> Console to view the statistics of the active
subscriptions. This allo
ws you to view the following statistics on a
<strong><code>TopicSubscriptionViewMBean</code></strong>:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Statistic</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Definition</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>discarded</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The count of how many messages
have been discarded during the lifetime of the subscription due to it being a
slow consumer</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>matched</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The current number of messages matched and
to be dispatched to the subscription as soon as some capacity is available in
the prefetch buffer. So a non-zero value implies that the prefetch buffer is
full for this subscription</p></td></tr></tbody></table></div></div>
+</beans></plain-text-body><h2 id="SlowConsumerHandling-UsageTips">Usage
Tips</h2><p> </p><rich-text-body><p>It is advisable that if you know a
particular consumer is going to be slow then set its prefetch size to something
smaller than the fast consumers!</p><p>For example, if you know a particular
server is quite slow and you have very high message rates<em> and</em> you have
some very fast consumers then you might want to enable this feature and set the
prefetch on the slow servers to be a <em>little</em> lower than on the fast
servers.</p></rich-text-body><h3
id="SlowConsumerHandling-MonitoringtheStatusofSlowConsumers">Monitoring the
Status of Slow Consumers</h3><p>You can also use a <a shape="rect"
href="jmx.html">JMX</a> Console to view the statistics of the active
subscriptions. This allows you to view the following statistics on a
<strong><code>TopicSubscriptionViewMBean</code></strong>:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colsp
an="1" rowspan="1" class="confluenceTh"><p>Statistic</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Definition</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>discarded</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The count of how many messages
have been discarded during the lifetime of the subscription due to it being a
slow consumer</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>matched</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The current number of messages matched and
to be dispatched to the subscription as soon as some capacity is available in
the prefetch buffer. So a non-zero value implies that the prefetch buffer is
full for this subscription</p></td></tr></tbody></table></div></div>
</td>
<td valign="top">
<div class="navigation">
Modified: websites/production/activemq/content/version-5-xml-configuration.html
==============================================================================
--- websites/production/activemq/content/version-5-xml-configuration.html
(original)
+++ websites/production/activemq/content/version-5-xml-configuration.html Fri
Aug 25 08:24:11 2017
@@ -32,15 +32,6 @@
</style>
<![endif]-->
- <link
href='http://activemq.apache.org/styles/highlighter/styles/shCore.css'
rel='stylesheet' type='text/css' />
- <link
href='http://activemq.apache.org/styles/highlighter/styles/shThemeEclipse.css'
rel='stylesheet' type='text/css' />
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shCore.js'
type='text/javascript'></script>
- <script
src='http://activemq.apache.org/styles/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
-
- <script type="text/javascript">
- SyntaxHighlighter.defaults['toolbar'] = false;
- SyntaxHighlighter.all();
- </script>
<title>
Apache ActiveMQ ™ -- Version 5 XML Configuration
@@ -80,8 +71,7 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><ul><li>transport connectors which
consist of transport channels and wire formats TODO: add a link to a page
explaining what transport connectors are how to configure and use
them.</li><li>network connectors using network channels or discovery TODO: add
a link to a page explaining what network connectors are how to configure and
use them.</li><li>discovery agents TODO: add a link to a page explaining what
discovery agents are how to configure and use them.</li><li>persistence
providers & locations TODO: add a link to a page explaining what
persistence providers are how to configure and use them.</li><li>custom message
containers (such as last image caching etc)</li></ul><p>We use <a shape="rect"
class="external-link" href="http://xbean.org/"; rel="nofollow">XBean</a> to
perform the XML configuration.</p><p>For details of the XML see the <a
shape="rect" href="xml-reference.html">Xml Reference</a></p><div
class="confluence-information-macro con
fluence-information-macro-warning"><p class="title">Be careful with broker
names and URIs</p><span class="aui-icon aui-icon-small aui-iconfont-error
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Make sure you do not use any
strange characters in the names of brokers as they are converted to URIs which
<a shape="rect" class="external-link"
href="http://java.sun.com/j2se/1.4.2/docs/api/java/net/URI.html";
rel="nofollow">do not allow things like underscores</a> in them
etc.</p></div></div><h2
id="Version5XMLConfiguration-Examples">Examples</h2><p>The default ActiveMQ
configuration: <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/assembly/src/release/conf/activemq.xml";>current
default config</a>.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><beans
+<div class="wiki-content maincontent"><ul><li>transport connectors which
consist of transport channels and wire formats TODO: add a link to a page
explaining what transport connectors are how to configure and use
them.</li><li>network connectors using network channels or discovery TODO: add
a link to a page explaining what network connectors are how to configure and
use them.</li><li>discovery agents TODO: add a link to a page explaining what
discovery agents are how to configure and use them.</li><li>persistence
providers & locations TODO: add a link to a page explaining what
persistence providers are how to configure and use them.</li><li>custom message
containers (such as last image caching etc)</li></ul><p>We use <a shape="rect"
class="external-link" href="http://xbean.org/"; rel="nofollow">XBean</a> to
perform the XML configuration.</p><p>For details of the XML see the <a
shape="rect" href="xml-reference.html">Xml Reference</a></p><parameter
ac:name="title">Be careful with b
roker names and URIs</parameter><rich-text-body><p>Make sure you do not use
any strange characters in the names of brokers as they are converted to URIs
which <a shape="rect" class="external-link"
href="http://java.sun.com/j2se/1.4.2/docs/api/java/net/URI.html";
rel="nofollow">do not allow things like underscores</a> in them
etc.</p></rich-text-body><h2
id="Version5XMLConfiguration-Examples">Examples</h2><p>The default ActiveMQ
configuration: <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/assembly/src/release/conf/activemq.xml";>current
default config</a>.</p><parameter
ac:name="">xml</parameter><plain-text-body><beans
xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
@@ -180,8 +170,7 @@
Take a look at ${ACTIVEMQ_HOME}/conf/jetty.xml for more details
-->
<import resource="jetty.xml"/>
-</beans></pre>
-</div></div><p>From a binary distribution there is an <em>activemq</em> script
allowing you to run a Message Broker as a stand alone process from the command
line easily providing the $ACTIVEMQ_HOME/bin directory is on your PATH.</p><h2
id="Version5XMLConfiguration-Configuringembeddedbrokers">Configuring embedded
brokers</h2><p>You can also use the XML Configuration to configure <a
shape="rect" href="how-do-i-embed-a-broker-inside-a-connection.html">embedded
brokers</a>. For example using the JNDI configuration mechanism you can do the
following<br clear="none"> <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/assembly/src/test/java/org/apache/activemq/config/BrokerXmlConfigFromJNDITest.java";>BrokerXmlConfigFromJNDITest</a><br
clear="none"> Or of you want to explicitly configure the embedded broker via
Java code you can do the following<br clear="none"> <a shape="rect"
class="external-link" href="http://svn.apache.org/repos/asf/activemq/trun
k/assembly/src/test/java/org/apache/activemq/config/BrokerXmlConfigTest.java">BrokerXmlConfigTest</a></p><h2
id="Version5XMLConfiguration-UserSubmittedConfigurations">User Submitted
Configurations</h2><p>We have a page which allows users to submit details of
their configurations.</p><ul><li><a shape="rect"
href="user-submitted-configurations.html">User Submitted
Configurations</a></li></ul><h2
id="Version5XMLConfiguration-Background">Background</h2><p>Since ActiveMQ has
so many strategy pattern plugins for transports, wire formats, persistence and
many other things, we wanted to leave the configuration format open so that you
the developer can configure and extend ActiveMQ in any direction you
wish.</p><p>So we use the <a shape="rect" class="external-link"
href="http://static.springframework.org/spring/docs/2.5.x/reference/beans.html#beans-basics";
rel="nofollow">Spring XML</a> configuration file format, which allows any
beans / POJOs to be wired together and configured. However ofte
n Spring's XML can be kinda verbose at times, so we have implemented an
ActiveMQ extension to the Spring XML which knows about the common, standard
ActiveMQ things you're likely to do (e.g. tags like connector, wireFormat,
serverTransport, persistence) - but at any time you can fall back to the normal
Spring way of doing things (with tags like bean, property etc).</p><p>To see
documentation of the XML file we use or to get access to the XSD/DTD see the <a
shape="rect" href="xml-reference.html">Xml Reference</a></p></div>
+</beans></plain-text-body><p>From a binary distribution there is an
<em>activemq</em> script allowing you to run a Message Broker as a stand alone
process from the command line easily providing the $ACTIVEMQ_HOME/bin directory
is on your PATH.</p><h2
id="Version5XMLConfiguration-Configuringembeddedbrokers">Configuring embedded
brokers</h2><p>You can also use the XML Configuration to configure <a
shape="rect" href="how-do-i-embed-a-broker-inside-a-connection.html">embedded
brokers</a>. For example using the JNDI configuration mechanism you can do the
following<br clear="none"> <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/activemq/trunk/assembly/src/test/java/org/apache/activemq/config/BrokerXmlConfigFromJNDITest.java";>BrokerXmlConfigFromJNDITest</a><br
clear="none"> Or of you want to explicitly configure the embedded broker via
Java code you can do the following<br clear="none"> <a shape="rect"
class="external-link" href="http://svn.apache.org/rep
os/asf/activemq/trunk/assembly/src/test/java/org/apache/activemq/config/BrokerXmlConfigTest.java">BrokerXmlConfigTest</a></p><h2
id="Version5XMLConfiguration-UserSubmittedConfigurations">User Submitted
Configurations</h2><p>We have a page which allows users to submit details of
their configurations.</p><ul><li><a shape="rect"
href="user-submitted-configurations.html">User Submitted
Configurations</a></li></ul><h2
id="Version5XMLConfiguration-Background">Background</h2><p>Since ActiveMQ has
so many strategy pattern plugins for transports, wire formats, persistence and
many other things, we wanted to leave the configuration format open so that you
the developer can configure and extend ActiveMQ in any direction you
wish.</p><p>So we use the <a shape="rect" class="external-link"
href="http://static.springframework.org/spring/docs/2.5.x/reference/beans.html#beans-basics";
rel="nofollow">Spring XML</a> configuration file format, which allows any
beans / POJOs to be wired together and conf
igured. However often Spring's XML can be kinda verbose at times, so we have
implemented an ActiveMQ extension to the Spring XML which knows about the
common, standard ActiveMQ things you're likely to do (e.g. tags like connector,
wireFormat, serverTransport, persistence) - but at any time you can fall back
to the normal Spring way of doing things (with tags like bean, property
etc).</p><p>To see documentation of the XML file we use or to get access to the
XSD/DTD see the <a shape="rect" href="xml-reference.html">Xml
Reference</a></p></div>
</td>
<td valign="top">
<div class="navigation">
