-
Language:
English
-
Language:
English
Managing and Monitoring a Broker
Administrative tasks made simple
Red Hat
Copyright © 2011-2017 Red Hat, Inc. and/or its affiliates.
Abstract
Chapter 1. Introduction
Abstract
Overview
Routine tasks
- installing SSL certificates
- starting the broker
- creating destinations
- stopping the broker
- maintaining the advisory topics
- monitoring the health of the broker
- monitoring the health of the destinations
Troubleshooting
- the broker's log file
- the advisory topics
- the broker's overall memory footprint
- the size of individual destination
- the total number of messages in the broker
- the size of the broker's persistent store
- a thread dump of the broker
Tools
- administration client—a command line tool that can be used to manage a broker and do rudimentary metric reporting
- console mode—a runtime mode that presents you with a custom console that provides a number of administrative options
- management console—a browser based console for viewing, monitoring, and deploying a group of distributed brokers
- JBoss Operations Network—an advanced monitoring and management tool that can provide detailed metrics and alerting.
- jconsole—a JMX tool that is shipped with the JDK
- VisualVM—a visual tool integrating several command line JDK tools and lightweight profiling capabilities
Chapter 2. Editing a Broker's Configuration
Abstract
2.1. Introduction to Broker Configuration
- an XML configuration file
- OSGi persistent identifier properties
- standalone—if a broker is deployed as a standalone entity and not a part of a fabric, you change the configuration using a combination of directly editing the broker's configuration template file and the console's config shell.
- in a fabric—if a broker is deployed into a fabric its configuration is managed by the Fabric Agent which draws all of the configuration from the fabric's registry. To modify the container of a broker running as part of a fabric, you need to modify the profile(s) deployed into it. You can do this by using either the fabric:profile-edit console command or the management console.
2.2. Understanding the Red Hat JBoss A-MQ Configuration Model
Abstract
Overview
Figure 2.1. Red Hat JBoss A-MQ Configuration System
Configuration templates
- configuration templates use property placeholders for settings that will be controlled via the OSGi Admin service
- configuration templates do not configure the broker's name
- configuration templates do not configure the location of the data directory
- configuration templates do not configure transport connectors
- configuration templates do not configure network connectors
- configuration templates do not control if a broker is a master or a slave node
- configuration templates can be used as a baseline for multiple brokers on the same machine
${propName}
and are resolved by matching properties in the broker's PID. In order to use property placeholder the configuration template must include the bean definition shown in Example 2.1, “Adding Property Placeholder Support to Red Hat JBoss A-MQ Configuration”.
Example 2.1. Adding Property Placeholder Support to Red Hat JBoss A-MQ Configuration
<!-- Allows us to use system properties and fabric as variables in this configuration file --> <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"> <property name="properties"> <bean class="io.fabric8.mq.fabric.ConfigurationProperties"/> </property> </bean> <broker ... > ... </broker>
Example 2.2. Configuration with Property Placeholders
<broker xmlns="http://activemq.apache.org/schema/core" brokerName="${broker-name}" dataDirectory="${data}" persistent="${persists}" start="false"> ... <persistenceAdapter> <jdbcPersistenceAdapter dataDirectory="${data}/derby" dataSource="#derby-ds" /> </persistenceAdapter> </broker>
OSGi PIDs
io.fabric8.mq.fabric.server
.
etc/
folder and use the .cfg
extension and are updated using the config shell. For broker's in a fabric the files are stored in the Fabric Ensemble and are edited using the fabric shell's profile management commands.
2.3. Editing a Standalone Broker's Configuration
Abstract
Overview
Editing the configuration template
etc/activemq.xml
. You can the location of the configuration template by changing the config property in the broker's etc/io.fabric8.mq.fabric.server-broker.cfg
file.
Splitting activemq.xml into multiple files
etc/activemq.xml
file into multiple XML files. You can do this using standard XML entities, declared in a DTD internal subset. For example, say you have an etc/activemq.xml
file with the following outline:
<beans ... > ... <broker xmlns="http://activemq.apache.org/schema/core" brokerName="${broker-name}" dataDirectory="${data}" start="false" restartAllowed="false"> <destinationPolicy> <policyMap> <policyEntries> <policyEntry topic=">" producerFlowControl="true"> <pendingMessageLimitStrategy> <constantPendingMessageLimitStrategy limit="1000"/> </pendingMessageLimitStrategy> </policyEntry> <policyEntry queue=">" producerFlowControl="true" memoryLimit="1mb"> </policyEntry> </policyEntries> </policyMap> </destinationPolicy> <!-- Rest of the broker configuration --> ... </broker> </beans>
destinationPolicy
element in a separate file. First of all, create a new file, etc/destination-policy.xml
, to store the destinationPolicy
element, with the following content:
<destinationPolicy> <policyMap> <policyEntries> <policyEntry topic=">" producerFlowControl="true"> <pendingMessageLimitStrategy> <constantPendingMessageLimitStrategy limit="1000"/> </pendingMessageLimitStrategy> </policyEntry> <policyEntry queue=">" producerFlowControl="true" memoryLimit="1mb"> </policyEntry> </policyEntries> </policyMap> </destinationPolicy>
etc/destination-policy.xml
file in your etc/activemq.xml
file by editing activemq.xml
, as follows:
<!DOCTYPE beans [ <!ENTITY destinationpolicy SYSTEM "file:etc/destination-policy.xml"> ]> <beans ... > ... <broker xmlns="http://activemq.apache.org/schema/core" brokerName="${broker-name}" dataDirectory="${data}" start="false" restartAllowed="false"> &destinationpolicy; <!-- Rest of the broker configuration --> ... </broker> </beans>
&destinationpolicy;
entity reference.
destination-policy.xml
file, use the URL format, file:///path/to/file
. For example, to reference the absolute location, /var/destination-policy.xml
, you would use the following DOCTYPE
declaration at the start of the file:
<!DOCTYPE beans [ <!ENTITY destinationpolicy SYSTEM "file:///var/destination-policy.xml"> ]> ...
Format of the DOCTYPE declaration
DOCTYPE
declaration to use with the etc/activemq.xml
file is as follows:
<!DOCTYPE RootElement [ <!ENTITY EntityName SYSTEM "URL"> ]> ...
RootElement
- This must always match the name of the root element in the current file. In the case of
activemq.xml
, the root element isbeans
. EntityName
- The name of the entity you are defining with this ENTITY declaration. In the main part of the current XML file, you can insert the contents of this entity using the entity reference,
&EntityName;
. URL
- To store the contents of the entity in a file, you must reference the file using the
file:
scheme. Because of the way that ActiveMQ processes the XML file, it is not guaranteed to work, if you leave out thefile:
prefix. Relative paths have the formatfile:path/to/file
and absolute paths have the formatfile:///path/to/file
.
Editing the OSGi properties
etc/io.fabric8.mq.fabric.server-broker.cfg
file. You can edit these values using the command console's config shell. The PID for these values are io.fabric8.mq.fabric.server.id
. The id is assigned by the container when the broker is started.
Config shell
- config:list—lists all of the runtime configuration files and the current values for their properties
- config:edit—opens an editing session for a configuration file
- config:propset—changes the value of a configuration property
- config:propdel—deletes a configuration property
- config:update—saves the changes to the configuration file being edited
2.4. Modifying a Running Standalone Broker's XML Configuration
Abstract
.xml
configuration file can be modified, saved, then applied while the broker is running. This dynamic runtime configuration feature is useful when you cannot disrupt the operation of existing producers or consumers with a broker restart.
Overview
.xml
configuration file (default is etc/activemq.xml
) directly using an external text or xml editor. Once the edits are saved, the runtime configuration plugin, which monitors the broker's .xml
configuration file, applies any detected runtime-supported changes to the running broker. These changes persist through broker restarts.
.xml
configuration file:
- network connectors—add a network connector to a broker or modify the attributes of an existing one
- virtual destinations—add a virtual destination to a broker or modify the attributes of an existing one
- destination policy—add a subset of <policyEntry> attributes
- authorization roles—add or modify roles that define read/write/admin access to queues and topics.
Prerequisites
- Disable configuration monitoring by the OSGi service factoryYou need to prevent the OSGi service factory from restarting the broker when it detects a change in the broker's configuration. To do so, you edit the installDir
/etc/io.fabric8.mq.fabric.server-broker.cfg
file to add the line config.check=false.ImportantIf you fail to disable the OSGi service factory, it will override theruntimeConfigurationPlugin
and restart the broker when it detects a change.If the broker is stopped, you can edit this file directly using an external text or xml editor. If the broker is running, you must use the appropriate config: shell commands to edit this file. - Enable dynamic runtime configurationTo enable dynamic runtime configuration, you must set two values in the broker's
.xml
configuration file:- In the
<broker.../>
element, addstart="false"
; for example:<broker xmlns="http://activemq.apache.org//schema/core" ... start="false".../>
This setting prevents Spring from starting the broker when the spring context is loaded. If Spring starts the broker, the broker will not know the location of the resource that created it, leaving the runtime configuration plugin with nothing to monitor. - In the <plugins> element, add
<runtimeConfigurationPlugin checkPeriod="1000">
to enable automated runtime configuration; for example:<plugins> <runtimeConfigurationPlugin checkPeriod="1000" /> </plugins>
The runtime configuration plugin monitors the broker's.xml
configuration file at intervals ofcheckPeriod
and applies only the runtime-supported changes that it detects to the running broker. Modifications made to the attributes of other properties in the broker's.xml
configuration file are ignored until the next broker restart.NoteThe unit of value forcheckPeriod
is milliseconds. The default is0
, which disables checking for changes. Using the default, you must manually trigger updates via JMX.
Dynamically updating network connectors
.xml
configuration file.
<networkConnectors> <networkConnector uri="static:(tcp://localhost:5555)" networkTTL="1" name="one" ... /> </networkConnectors>
Dynamically updating virtual destinations
.xml
configuration file.
<destinationInterceptors> <virtualDestinationInterceptor> <virtualDestinations> <virtualTopic name="B.>" selector="false" /> </virtualDestinations> </virtualDestinationInterceptor> </destinationInterceptors>
checkPeriod
interval.
.xml
configuration file. The first time you add a virtual destination, you must add the entire <destinationInterceptors> section to the broker's .xml
configuration file. Doing so replaces the broker's default <destinationInterceptors> configuration.
Dynamically updating the destination policy
.xml
configuration file.
<policyEntry>
element, which apply to queues and topics.
Table 2.1. Dynamically changeable <policyEntry> attributes
Attribute | Type | Queues | Topics |
---|---|---|---|
allConsumersBeforeDispatchStarts | boolean | Y | N |
alwaysRetroactive | boolean | Y | N |
advisoryForConsumed | boolean | Y | N |
advisoryForDelivery | boolean | Y | N |
advisoryForDiscardingMessages | boolean | Y | N |
advisoryForFastProducers | boolean | Y | N |
advisoryForSlowConsumers | boolean | Y | N |
advisoryWhenFull | boolean | Y | N |
blockedProducerWarningInterval | long | Y | N |
consumersBeforeDispatchStarts | int | Y | N |
cursorMemoryHighWaterMark | int | Y | N |
doOptimizeMessageStore | boolean | Y | N |
gcIsInactiveDestinations | boolean | Y | N |
gcWithNetworkConsumers | boolean | Y | N |
inactiveTimeoutBeforeGC | long | Y | N |
lazyDispatch | boolean | Y | Y |
maxBrowsePageSize | int | Y | N |
maxExpirePageSize | int | Y | N |
maxPageSize | int | Y | N |
memoryLimit | string | Y | Y |
minimumMessageSize | long | Y | N |
optimizedDispatch | boolean | Y | N |
optimizeMessageStoreInFlightLimit | int | Y | N |
producerFlowControl | boolean | Y | N |
reduceMemoryFootprint | boolean | Y | N |
sendAdvisoryIfNoConsumers | boolean | Y | N |
storeUsageHighWaterMark | int | Y | N |
strictOrderDispatch | boolean | Y | N |
timeBeforeDispatchStarts | int | Y | N |
useConsumerPriority | boolean | Y | N |
Destination policies to control paging
maxPageSize
- The maximum number of messages paged into memory for sending to a destination.
maxBrowsePageSize
- The maximum number of messages paged into memory for browsing a queue.NoteThe number of messages paged in for browsing cannot exceed the destination's
memoryLimit
setting. maxExpirePageSize
- The maximum number of messages paged into memory to check for expired messages.
Dynamically updating authorization roles
- add the authorization plugin to the
<plugins>
section of the broker's.xml
configuration file - configure the authorization plugin's
<map>
element
<plugins> <runtimeConfigurationPlugin checkPeriod="1000" /> <authorizationPlugin> <map> <authorizationMap> <authorizationEntries> <authorizationEntry queue=">" read="admins" write="admins" admin="admins" /> <authorizationEntry queue="USERS.>" read="users" write="users" admin="users" /> <authorizationEntry topic=">" read="admins" write="admins" admin="admins" /> <authorizationEntry topic="USERS.>" read="users" write="users" admin="users" /> ...
2.5. JVM Configuration Options.
Abstract
bin/setenv
file. The setenv
file is used as part of the start-up routine, so for any changes to be picked up they have to be made before JBoss A-MQ is started.
Setting Java Options
/bin/setenv
file. Use this file to set a number of Java Options, such as JAVA_MIN_MEM, JAVA_MAX_MEM, JAVA_PERM_MEM, JAVA_MAX_PERM_MEM. These are the default options. Other Java Options can be set using the EXTRA_JAVA_OPTS variable.
JAVA_MIN_MEM=512M # Minimum memory for the JVM. To set a Java option other than the defaults, use
EXTRA_JAVA_OPTS="Java option". For example,
EXTRA_JAVA_OPTS="-XX:+UseG1GC".
Chapter 3. Security Basics
Abstract
3.1. Security Overview
Overview
Ports exposed by the container
Figure 3.1. Ports Exposed by the Red Hat JBoss A-MQ Container
- Console port—enables remote control of a container instance, through Apache Karaf shell commands. This port is enabled by default and is secured both by JAAS authentication and by SSL.
- JMX port—enables management of the container through the JMX protocol. This port is enabled by default and is secured by JAAS authentication.
- Web console port—provides access to an embedded Jetty container that hosts the Fuse Management Console.
Authentication and authorization system
3.2. Basic Security Configuration
Overview
- configure access to the Fuse Management Console
- assign roles to each of the remote ports to limit access
- strengthen the credentials needed to access the remote console
Create a secure JAAS user
InstallDir/etc/users.properties
file and add a new user field, as follows:
Username=Password,Administrator
Username
and Password
are the new user credentials. The Administrator
role gives this user the privileges to access all administration and management functions of the container. For more details about JAAS, see section "JAAS Authentication" in "Security Guide".
JBossA-MQ:karaf@root>
echo 0123 123JBossA-MQ:karaf@root>
echo 00.123 0.123JBossA-MQ:karaf@root>
Role-based access control
Table 3.1. Standard Roles for Access Control
Roles | Description |
---|---|
Monitor , Operator , Maintainer | Grants read-only access to the container. |
Deployer , Auditor | Grants read-write access at the appropriate level for ordinary users, who want to deploy and run applications. But blocks access to sensitive container configuration settings. |
Administrator , SuperUser | Grants unrestricted access to the container. |
Strengthening security on the remote console port
- Make sure that the JAAS user credentials have strong passwords.
- Customize the X.509 certificate (replace the Java keystore file,
InstallDir/etc/host.key
, with a custom key pair).
3.3. Enable password encryption for non-fabric environment in A-MQ
users.properties
file so that it can be read only by administrators. To provide additional protection, you can also encrypt the stored passwords using a message digest algorithm.
- Edit the
InstallDir/etc/org.apache.karaf.jaas.cfg
file. - For example, the following settings would enable basic encryption using the MD5 message digest algorithm:
encryption.enabled = true encryption.name = basic encryption.prefix = {CRYPT} encryption.suffix = {CRYPT} encryption.algorithm = MD5 encryption.encoding = hexadecimal
org.apache.karaf.jaas.cfg
file are applied only to the default karaf realm in a standalone container.
3.4. Setting up SSL for A-MQ
SSL HTTP/1.1 Connector entry in conf/server.xml
.
conf
directory or delete the existing dummy key and trust stores so they do not interfere.
Starting the Broker with SSL
>javax.net.ssl.keyStore
and javax.net.ssl.keyStorePassword
system properties
- Set the SSL_OPTS environment variable so that it knows to use the broker keystore.
<export SSL_OPTS = -Djavax.net.ssl.keyStore=/path/to/broker.ks -Djavax.net.ssl.keyStorePassword=password
Alternately, you can set the system properties in the broker configuration file.
- In the
conf/activemq.xml
, edit the attributes in thesslContext
element. - Set the values for KeyStore, Key StorePassword, truststore, trustStorePassword.
<beans> <broker> <sslContext> <sslContext keyStore="file:${activemq.base}/conf/broker.ks" keyStorePassword="password" trustStore="file:${activemq.base}/conf/broker.ts" trustStorePassword="password"/> </sslContext> </broker> </beans>
- keyStore
- equivalent to setting
javax.net.ssl.keyStore
- keyStorePassword
- equivalent to setting
javax.net.ssl.keyStorePassword
- keyStoreType
- equivalent to setting
javax.net.ssl.keyStoreType
- keyStoreAlgorithm
- defaults to JKS
- trustStore
- equivalent to setting
javax.net.ssl.trustStore
- trustStorePassword
- equivalent to setting
javax.net.ssl.trustStorePassword
- trustStoreType
- equivalent to setting
javax.net.ssl.trustStoreType
Verifying Client Certificates
- Export the client's certificate to share it with the broker. keytool -export -alias client -keystore client.ks -file client_cert
- Create a truststore for the broker and import the client's certificate. This ensures that the broker trusts the client.
keytool -import -alias client -keystore broker.ts -file client_cert
- Add
javax.net.ssl.trustStore
system property toSSL_OPTS
Djavax.net.ssl.trustStore=/path/to/broker.ts
- Instruct ActiveMQ to require client authentication by setting the following in
activemq.xml
.<transportConnectors> <transportConnector name="ssl" uri="ssl://localhost:61617?needClientAuth=true"/> </transportConnectors>
3.5. Enable Broker-to-Broker Authentication in A-MQ
userName
attribute and the password attribute in the networkConnector
element.
- Assuming that Broker A is configured to connect to Broker B. Configure the Broker A's networkConnector element with username/password credentials as shown:
- For example, the following settings would enable basic encryption using the MD5 message digest algorithm:
<beans> <broker> <networkConnectors> <networkConnector name="BrokerABridge" userName="user" password="password" uri="static://(ssl://brokerA:61616)"/> </networkConnectors> </broker> </beans>
Here Broker A's authentication plug-in checks for Broker A's username. For example, if Broker A has its authentication configured by a simpleAuthenticationPlugin element, Broker A's username must appears in this element.
org.apache.karaf.jaas.cfg
file are applied only to the default karaf realm in a standalone container.
3.6. Disabling Broker Security
Overview
Standalone server
InstallDir/etc/activemq.xml
file using a text editor and look for the following lines:
...
<plugins>
<jaasAuthenticationPlugin configuration="karaf" />
</plugins>
...
jaasAuthenticationPlugin
element. The next time you start up the JBoss A-MQ container using the start script the broker will run with unsecured ports.
Chapter 4. Securing a Standalone Red Hat JBoss A-MQ Container
Abstract
4.1. Defining JAAS Realms
Overview
jaas:config
element for defining JAAS realms in a blueprint configuration file. The JAAS realms defined in this way are made available to all of the application bundles deployed in the container, making it possible to share the JAAS security infrastructure across the whole container.
Namespace
jaas:config
element is defined in the http://karaf.apache.org/xmlns/jaas/v1.0.0
namespace. When defining a JAAS realm you will need to include the line shown in Example 4.1, “JAAS Blueprint Namespace”.
Example 4.1. JAAS Blueprint Namespace
xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0"
Configuring a JAAS realm
jaas:config
element is shown in Example 4.2, “Defining a JAAS Realm in Blueprint XML”.
Example 4.2. Defining a JAAS Realm in Blueprint XML
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0"> <jaas:config name="JaasRealmName" [rank="IntegerRank"]> <jaas:module className="LoginModuleClassName" [flags="[required|requisite|sufficient|optional]"]> Property=Value ... </jaas:module> ... <!-- Can optionally define multiple modules --> ... </jaas:config> </blueprint>
jaas:config
- Defines the JAAS realm. It has the following attributes:
name
—specifies the name of the JAAS realm.rank
—specifies an optional rank for resolving naming conflicts between JAAS realms . When two or more JAAS realms are registered under the same name, the OSGi container always picks the realm instance with the highest rank. If you decide to override the default realm,karaf
, you should specify arank
of100
or more, so that it overrides all of the previously installedkaraf
realms (in the context of Fabric, you need to override the defaultZookeeperLoginModule
, which has a rank of99
).
jaas:module
- Defines a JAAS login module in the current realm.
jaas:module
has the following attributes:className
—the fully-qualified class name of a JAAS login module. The specified class must be available from the bundle classloader.flags
—determines what happens upon success or failure of the login operation. Table 4.1, “Flags for Defining a JAAS Module” describes the valid values.Table 4.1. Flags for Defining a JAAS Module
Value Description required
Authentication of this login module must succeed. Always proceed to the next login module in this entry, irrespective of success or failure. requisite
Authentication of this login module must succeed. If success, proceed to the next login module; if failure, return immediately without processing the remaining login modules. sufficient
Authentication of this login module is not required to succeed. If success, return immediately without processing the remaining login modules; if failure, proceed to the next login module. optional
Authentication of this login module is not required to succeed. Always proceed to the next login module in this entry, irrespective of success or failure.
The contents of ajaas:module
element is a space separated list of property settings, which are used to initialize the JAAS login module instance. The specific properties are determined by the JAAS login module and must be put into the proper format.NoteYou can define multiple login modules in a realm.
Converting standard JAAS login properties to XML
PropertiesLogin
realm using the Red Hat JBoss A-MQ properties login module class, PropertiesLoginModule
:
Example 4.3. Standard JAAS Properties
PropertiesLogin { org.apache.activemq.jaas.PropertiesLoginModule required org.apache.activemq.jaas.properties.user="users.properties" org.apache.activemq.jaas.properties.group="groups.properties"; };
jaas:config
element in a blueprint file, is shown in Example 4.4, “Blueprint JAAS Properties”.
Example 4.4. Blueprint JAAS Properties
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"> <jaas:config name="PropertiesLogin"> <jaas:module flags="required" className="org.apache.activemq.jaas.PropertiesLoginModule"> org.apache.activemq.jaas.properties.user=users.properties org.apache.activemq.jaas.properties.group=groups.properties </jaas:module> </jaas:config> </blueprint>
Example
LDAPLogin
realm to use Red Hat JBoss A-MQ's LDAPLoginModule
class, which connects to the LDAP server located at ldap://localhost:10389.
Example 4.5. Configuring a JAAS Realm
<?xml version="1.0" encoding="UTF-8"?> <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"> <jaas:config name="LDAPLogin" rank="200"> <jaas:module flags="required" className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule"> initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory connection.username=uid=admin,ou=system connection.password=secret connection.protocol= connection.url = ldap://localhost:10389 user.base.dn = ou=users,ou=system user.filter = (uid=%u) user.search.subtree = true role.base.dn = ou=users,ou=system role.filter = (uid=%u) role.name.attribute = ou role.search.subtree = true authentication = simple </jaas:module> </jaas:config> </blueprint>
4.2. Enable LDAP Authentication in the OSGi Container
Overview
References
- LDAP Tutorial—is provided in chapter "LDAP Authentication Tutorial" in "Security Guide".
- LDAPLoginModule options—are described in detail in section "JAAS LDAP Login Module" in "Security Guide".
- cachedLDAPAuthorizationMap options—are described in detail in section "Cached LDAP Authorization Plug-In" in "Security Guide".
4.3. Using Encrypted Property Placeholders
Overview
How to use encrypted property placeholders
- Download and install Jasypt, to gain access to the Jasypt
listAlgorithms.sh
,encrypt.sh
anddecrypt.sh
command-line tools.NoteWhen installing the Jasypt command-line tools, don't forget to enable execute permissions on the script files, by runningchmod u+x ScriptName.sh
. - Choose a master password and an encryption algorithm. To discover which algorithms are supported in your current Java environment, run the
listAlgorithms.sh
Jasypt command-line tool, as follows:./listAlgorithms.sh DIGEST ALGORITHMS: [MD2, MD5, SHA, SHA-256, SHA-384, SHA-512] PBE ALGORITHMS: [PBEWITHMD5ANDDES, PBEWITHMD5ANDTRIPLEDES, PBEWITHSHA1ANDDESEDE, PBEWITHSHA1ANDRC2_40]
On Windows platforms, the script islistAlgorithms.bat
. JBoss A-MQ usesPBEWithMD5AndDES
by default. - Use the Jasypt encrypt command-line tool to encrypt your sensitive configuration values (for example, passwords for use in configuration files). For example, the following command encrypts the
PlaintextVal
value, using the specified algorithm and master passwordMasterPass
:./encrypt.sh input="PlaintextVal" algorithm=PBEWithMD5AndDES password=MasterPass
- Create a properties file with encrypted values. For example, suppose you wanted to store some LDAP credentials. You could create a file,
etc/ldap.properties
, with the following contents:Example 4.6. Property File with an Encrypted Property
#ldap.properties ldap.password=ENC(amIsvdqno9iSwnd7kAlLYQ==) ldap.url=ldap://192.168.1.74:10389
The encrypted property values (as generated in the previous step) are identified by wrapping in theENC()
function. - (Blueprint XML only) Add the requisite namespaces to your Blueprint XML file:
- Aries extensions—
http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0
- Apache Karaf Jasypt—
http://karaf.apache.org/xmlns/jasypt/v1.0.0
Example 4.7, “Encrypted Property Namespaces” shows a Blueprint file with the requisite namespaces.Example 4.7. Encrypted Property Namespaces
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0" xmlns:enc="http://karaf.apache.org/xmlns/jasypt/v1.0.0"> ... </blueprint>
- Configure the location of the properties file for the property placeholder and configure the Jasypt encryption algorithm .
- Blueprint XMLExample 4.8, “Jasypt Blueprint Configuration” shows how to configure the
ext:property-placeholder
element to read properties from theetc/ldap.properties
file. Theenc:property-placeholder
element configures Jasypt to use thePBEWithMD5AndDES
encryption algorithm and to read the master password from theJASYPT_ENCRYPTION_PASSWORD
environment variable.Example 4.8. Jasypt Blueprint Configuration
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0" xmlns:enc="http://karaf.apache.org/xmlns/jasypt/v1.0.0"> <ext:property-placeholder> <location>file:etc/ldap.properties</location> </ext:property-placeholder> <enc:property-placeholder> <enc:encryptor class="org.jasypt.encryption.pbe.StandardPBEStringEncryptor"> <property name="config"> <bean class="org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig"> <property name="algorithm" value="PBEWithMD5AndDES" /> <property name="passwordEnvName" value="JASYPT_ENCRYPTION_PASSWORD" /> </bean> </property> </enc:encryptor> </enc:property-placeholder> ... </blueprint>
- Spring XMLExample 4.9, “Jasypt Spring Configuration” shows how to configure Jasypt to use the
PBEWithMD5AndDES
encryption algorithm and to read the master password from theJASYPT_ENCRYPTION_PASSWORD
environment variable.TheEncryptablePropertyPlaceholderConfigurer
bean is configured to read properties from theetc/ldap.properties
file and to read properties from theio.fabric8.mq.fabric.ConfigurationProperties
class (which defines thekaraf.base
property, for example).Example 4.9. Jasypt Spring Configuration
<bean id="environmentVariablesConfiguration" class="org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig"> <property name="algorithm" value="PBEWithMD5AndDES" /> <property name="passwordEnvName" value="JASYPT_ENCRYPTION_PASSWORD" /> </bean> <bean id="configurationEncryptor" class="org.jasypt.encryption.pbe.StandardPBEStringEncryptor"> <property name="config" ref="environmentVariablesConfiguration" /> </bean> <bean id="propertyConfigurer" class="org.jasypt.spring31.properties.EncryptablePropertyPlaceholderConfigurer"> <constructor-arg ref="configurationEncryptor" /> <property name="location" value="file:${karaf.base}/etc/ldap.properties"/> <property name="properties"> <bean class="io.fabric8.mq.fabric.ConfigurationProperties"/> </property> </bean>
- Use the placeholders in your configuration file. The placeholders you use for encrypted properties are the same as you use for regular properties. Use the syntax
${prop.name}
. - Make sure that the
jasypt-encryption
feature is installed in the container. If necessary, install thejasypt-encryption
feature with the following console command:JBossFuse:karaf@root> features:install jasypt-encryption
- Shut down the container, by entering the following command:
JBossFuse:karaf@root> shutdown
- Carefully restart the container and deploy your secure application, as follows:
- Open a command window (first command window) and enter the following commands to start the JBoss A-MQ container in the background:
export JASYPT_ENCRYPTION_PASSWORD="your super secret master pass phrase" ./bin/start
- Open a second command window and start the client utility, to connect to the container running in the background:
./bin/client -u Username -p Password
WhereUsername
andPassword
are valid JAAS user credentials for logging on to the container console. - In the second command window, use the console to install your secure application that uses encrypted property placeholders. Check that the application has launched successfully (for example, using the
osgi:list
command to check its status). - After the secure application has started up, go back to the first command window and unset the
JASYPT_ENCRYPTION_PASSWORD
environment variable.ImportantUnsetting theJASYPT_ENCRYPTION_PASSWORD
environment variable ensures there will be minimum risk of exposing the master password. The Jasypt library retains the master password in encrypted form in memory.
Blueprint XML example
Example 4.10. Jasypt Example in Blueprint XML
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0" xmlns:enc="http://karaf.apache.org/xmlns/jasypt/v1.0.0"> <ext:property-placeholder> <location>file:etc/ldap.properties</location> </ext:property-placeholder> <enc:property-placeholder> <enc:encryptor class="org.jasypt.encryption.pbe.StandardPBEStringEncryptor"> <property name="config"> <bean class="org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig"> <property name="algorithm" value="PBEWithMD5AndDES" /> <property name="passwordEnvName" value="JASYPT_ENCRYPTION_PASSWORD" /> </bean> </property> </enc:encryptor> </enc:property-placeholder> <jaas:config name="karaf" rank="200"> <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule" flags="required"> initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory debug=true connectionURL=${ldap.url} connectionUsername=cn=mqbroker,ou=Services,ou=system,dc=jbossfuse,dc=com connectionPassword=${ldap.password} connectionProtocol= authentication=simple userRoleName=cn userBase = ou=User,ou=ActiveMQ,ou=system,dc=jbossfuse,dc=com userSearchMatching=(uid={0}) userSearchSubtree=true roleBase = ou=Group,ou=ActiveMQ,ou=system,dc=jbossfuse,dc=com roleName=cn roleSearchMatching= (member:=uid={1}) roleSearchSubtree=true </jaas:module> </jaas:config> </blueprint>
${ldap.password}
placeholder is replaced with the decrypted value of the ldap.password
property from the etc/ldap.properties
properties file.
Chapter 5. Securing Fabric Containers
Abstract
Default authentication system
io.fabric8.jaas.ZookeeperLoginModule
). This system allows you to define user accounts and assign passwords and roles to the users. Out of the box, the user credentials are stored in the Fabric registry, unencrypted.
Managing users
jaas:*
family of console commands. First of all you need to attach the jaas:*
commands to the ZookeeperLoginModule
login module, as follows:
JBossFuse:karaf@root> jaas:realms Index Realm Module Class 1 karaf org.apache.karaf.jaas.modules.properties.PropertiesLoginModule 2 karaf org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule 3 karaf io.fabric8.jaas.ZookeeperLoginModule JBossFuse:karaf@root> jaas:manage --index 3
jaas:*
commands to the ZookeeperLoginModule
login module. You can then add users and roles, using the jaas:useradd
and jaas:roleadd
commands. Finally, when you are finished editing the user data, you must commit the changes by entering the jaas:update
command, as follows:
JBossFuse:karaf@root> jaas:update
jaas:cancel
.
Obfuscating stored passwords
ZookeeperLoginModule
stores passwords in plain text. You can provide additional protection to passwords by storing them in an obfuscated format. This can be done by adding the appropriate configuration properties to the io.fabric8.jaas
PID and ensuring that they are applied to all of the containers in the fabric.
Enabling LDAP authentication
LDAPLoginModule
), which you can enable by adding the requisite configuration to the default profile.
Chapter 6. Installing Red Hat JBoss A-MQ as a Service
Abstract
6.1. Overview
bin/contrib
directory.
6.2. Running JBoss A-MQ as a Service
- the init script
- the init configuration file
6.3. Customizing karaf-service.sh Utility
Table 6.1.
Command Line Option | Environment Variable | Description |
---|---|---|
-k | KARAF_SERVICE_PATH | Karaf installation path |
-d | KARAF_SERVICE_DATA | Karaf data path (default to \${KARAF_SERVICE_PATH}/data ) |
-c | KARAF_SERVICE_CONF | Karaf configuration file (default to \${KARAF_SERVICE_PATH/etc/\${KARAF_SERVICE_NAME}.conf ) |
-t | KARAF_SERVICE_ETC | Karaf etc path (default to \${KARAF_SERVICE_PATH/etc} ) |
-p | KARAF_SERVICE_PIDFILE | Karaf pid path (default to \${KARAF_SERVICE_DATA}/\${KARAF_SERVICE_NAME}.pid) ) |
-n | KARAF_SERVICE_NAME | Karaf service name (default karaf) |
-e | KARAF_ENV | Karaf environment variable |
-u | KARAF_SERVICE_USER | Karaf user |
-g | KARAF_SERVICE_GROUP | Karaf group (default \${KARAF_SERVICE_USER ) |
-l | KARAF_SERVICE_LOG | Karaf console log (default to \${KARAF_SERVICE_DATA}/log/\${KARAF_SERVICE_NAME}-console.log ) |
-f | KARAF_SERVICE_TEMPLATE | Template file to use |
-x | KARAF_SERVICE_EXECUTABLE | Karaf executable name (defaul karaf support daemon and stop commands) |
CONF_TEMPLATE="karaf-service-template.conf" SYSTEMD_TEMPLATE="karaf-service-template.systemd" SYSTEMD_TEMPLATE_INSTANCES="karaf-service-template.systemd-instances" INIT_TEMPLATE="karaf-service-template.init" INIT_REDHAT_TEMPLATE="karaf-service-template.init-redhat" INIT_DEBIAN_TEMPLATE="karaf-service-template.init-debian" SOLARIS_SMF_TEMPLATE="karaf-service-template.solaris-smf"
6.4. Systemd
karaf-service.sh
utility identifies Systemd, it generates three files:
- a systemd unit file to manage the root Apache Karaf container
- a systemd environment file with variables used by the root Apache Karaf container
- a systemd template unit file to manage Apache Karaf child containers
$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4 Writing service file "/opt/karaf-4/bin/contrib/karaf-4.service" Writing service configuration file "/opt/karaf-4/etc/karaf-4.conf" Writing service file "/opt/karaf-4/bin/contrib/karaf-4@.service" $ cp /opt/karaf-4/bin/contrib/karaf-4.service /etc/systemd/system $ cp /opt/karaf-4/bin/contrib/karaf-4@.service /etc/systemd/system $ systemctl enable karaf-4.service
6.5. SysV
karaf-service.sh
utility identifies a SysV system, it generates two files:
- an init script to manage the root Apache Karaf container
- an environment file with variables used by the root Apache Karaf container
$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4 Writing service file "/opt/karaf-4/bin/contrib/karaf-4" Writing service configuration file "/opt/karaf-4/etc/karaf-4.conf" $ ln -s /opt/karaf-4/bin/contrib/karaf-4 /etc/init.d/ $ chkconfig karaf-4 on
6.6. Solaris SMF
$ ./karaf-service.sh -k /opt/karaf-4 -n karaf-4 Writing service file "/opt/karaf-4/bin/contrib/karaf-4.xml" $ svccfg validate /opt/karaf-4/bin/contrib/karaf-4.xml $ svccfg import /opt/karaf-4/bin/contrib/karaf-4.xml
6.7. Windows
- Rename the
karaf-service-win.exe
file tokaraf-4.exe
file. - Rename the
karaf-service-win.xml
file tokaraf-4.xml
file. - Customize the service descriptor as per your requirements.
- Use the service executable to install, start and stop the service.
C:\opt\apache-karaf-4\bin\contrib> karaf-4.exe install C:\opt\apache-karaf-4\bin\contrib> karaf-4.exe start
Chapter 7. Starting a Broker
Abstract
Overview
- console mode—the broker starts up as a foreground process and presents the user with a command shell
- daemon mode—the broker starts up as a background process that can be manged using a remote console or the provided command line tools
InstallDir/etc/activemq.xml
configuration file. The configuration uses values loaded from the InstallDir/etc/system.properties
file and the InstallDir/etc/io.fabric8.mq.fabric.server-broker.cfg
file.
Starting in console mode
Table 7.1. Start up Commands for Console Mode
Windows | bin\amq.bat |
Linux/UNIX | bin/amq |
Example 7.1. Broker Console
_ ____ __ __ ____
| | _ \ /\ | \/ |/ __ \
| | |_) | ___ ___ ___ / \ ______| \ / | | | |
_ | | _ < / _ \/ __/ __| / /\ \______| |\/| | | | |
| |__| | |_) | (_) \__ \__ \ / ____ \ | | | | |__| |
\____/|____/ \___/|___/___/ /_/ \_\ |_| |_|\___\_\
JBoss A-MQ (6.3.0.redhat-187)
http://www.redhat.com/products/jbossenterprisemiddleware/amq/
Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Open a browser to http://localhost:8181 to access the management console
Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown JBoss A-MQ.
JBossA-MQ:karaf@root>
./bin/karaf
, which is executing the Karaf console; and the child process, which is executing the Karaf server in a java
JVM. The shutdown behaviour remains the same as before, however. That is, you can shut down the server from the console using either Ctrl-D or osgi:shutdown
, which kills both processes.
Starting in daemon mode
Table 7.2. Start up Commands for Daemon Mode
Windows | bin\start.bat |
Linux/UNIX | bin/start |
Starting a broker in a fabric
- using the console of one of the other broker's in the fabricIf one of the brokers in the fabric is running in console mode you an use the fabric:container-start command to start any of the other brokers in the fabric. The command requires that you supply the container name used when creating the broker in the fabric. For example to start a broker named
fabric-broker3
you woul duse the command shown in Example 7.2, “Starting a Broker in a Fabric”.Example 7.2. Starting a Broker in a Fabric
JBossA-MQ:karaf@root>
fabric:container-start fabric-broker3
- using the administration client of one of the broker's in the fabricIf none of the brokers are running in console mode, you can use the administration client on one of the brokers to execute the fabric:container-start command. The administration client is run using the client command in Red Hat JBoss A-MQ's
bin
folder. Example 7.3, “Starting a Broker in a Fabric with the Administration Client” shows how to use the remote client to start remote broker in the fabric.Example 7.3. Starting a Broker in a Fabric with the Administration Client
bin/client fabric:container-start fabric-broker3
- using the management consoleThe management console can start and stop any of the brokers in the fabric it manages from a Web based console.For more information see Using the Management Console.
Chapter 8. Sending Commands to the Broker
Abstract
Overview
- the JBoss A-MQ administration client that can be used to send any of the console commands to a broker running in daemon mode
- a broker running in console mode can connect to a remote broker and be used to manage the remote broker
- Red Hat JBoss A-MQ includes a vanilla Apache Karaf shell that can connect to a remote broker and be used to manage the remote broker
Running the administration client
InstallDir/bin
. Example 8.1, “Client Command” shows the syntax for the command.
Example 8.1. Client Command
client
[
--help
] [
-a port
] [
-h host
] [
-u user
] [
-p password
] [
-v
] [
-r attempts
] [
-d delay
] [
commands
]
Table 8.1. Administration Client Arguments
Argument | Description |
---|---|
--help | Displays the help message. |
-a | Specifies the remote host's port. |
-h | Specify the remote host's name. |
-u | Specifies user name used to log into the broker. |
-p | Specifies the password used to log into the broker. |
-v | Use verbose output. |
-r | Specifies the maximum number of attempts to establish a connection. |
-d | Specifies, in seconds, the delay between retries. The default is 2 seconds. |
commands | Specifies one or more commands to run. If no commands are specified, the client enters an interactive mode. |
Using the broker console
- console help—list all of the commands along with a brief summary of the commands function
- command help—a detailed description of a command and its arguments
Example 8.2. Console Help
JBossA-MQ:karaf@root>
help
COMMANDS activemq:browse activemq:bstat activemq:list activemq:purge activemq:query admin:change-opts Changes the Java options of an existing container instance. admin:change-rmi-registry-port Changes the RMI registry port (used by management layer) of an existing container instance.
...JBossA-MQ:karaf@root>
--help
option. As shown in Example 8.3, “Help for a Command”, entering admin:start --help
displays the help for that command.
Example 8.3. Help for a Command
JBossA-MQ:karaf@root>
admin:start --help
DESCRIPTION admin:start Starts an existing container instance. SYNTAX admin:start [options] name ARGUMENTS name The name of the container instance OPTIONS --help Display this help message -o, --java-opts Java options when launching the instance
JBossA-MQ:karaf@root>
Connecting a console to a remote broker
-p
flag. You can also specify a command to be executed by the remote console connection. If you do not specify a command, you are presented with a prompt that will pass commands to the remote broker's console.
Starting a basic console
Available commands
Chapter 9. Deploying a New Broker
Abstract
9.1. Type of Deployment
- as a collection of standalone brokers
- a fabric of brokers
9.2. Deploying a Standalone Broker
Abstract
Overview
Procedure
- Install JBoss A-MQ onto the target system as described in the Installation Guide.
- Modify the new installation's configuration for your environment as described in Chapter 2, Editing a Broker's Configuration.
More information
- Using Networks of Brokers
- Fault Tolerant Messaging
Chapter 10. ActiveMQ Brokers and Clusters
Abstract
fabric:mq-create
command to create and deploy clusters of brokers.
10.1. Creating a Single Broker Instance
MQ profiles
mq-base
- An abstract profile, which defines some important properties and resources for the broker, but should never be used directly to instantiate a broker.
mq-default
- A basic single broker, which inherits most of its properties from the
mq-base
profile.
fabric:profile-display
command, as follows:
JBossFuse:karaf@root> fabric:profile-display mq-default ... JBossFuse:karaf@root> fabric:profile-display mq-base ...
Creating a new broker instance
mq-default
profile.
mq-default
broker instance called broker1
, enter the following console command:
JBossFuse:karaf@root> fabric:container-create-child --profile mq-default root broker1 Creating new instance on SSH port 8102 and RMI ports 1100/44445 at: /Users/jdoe/Downloads/jboss-fuse-6.3.0-254/instances/broker1 The following containers have been created successfully: Container: broker1.
broker1
with a broker of the same name running on it.
fabric:mq-create command
fabric:mq-create
command provides a shortcut to creating a broker, but with more flexibility, because it also creates a new profile. To create a new broker instance called brokerx
using fabric:mq-create
, enter the following console command:
JBossFuse:karaf@root> fabric:mq-create --create-container broker --replicas 1 brokerx MQ profile mq-broker-default.brokerx ready
fabric:container-create-child
command, fabric:mq-create
creates a container called broker1
and runs a broker instance on it. There are some differences, however:
- The new
broker1
container is implicitly created as a child of the current container, - The new broker has its own profile,
mq-broker-default.brokerx
, which is based on themq-base
profile template, - It is possible to edit the
mq-broker-default.brokerx
profile, to customize the configuration of this new broker. - The
--replicas
option lets you specify the number of master/slave broker replicas (for more details, see Section 10.3.2, “Master-Slave Cluster”). In this example, we specify one replica (the default is two).
mq-broker-Group.BrokerName
by default. If you want the profile to have the same name as the broker (which was the default in JBoss A-MQ version 6.0), you can specify the profile name explicitly using the --profile
option.
Starting a broker on an existing container
fabric:mq-create
command can be used to deploy brokers on existing containers. Consider the following example, which creates a new Fuse MQ broker in two steps:
JBossFuse:karaf@root> fabric:container-create-child root broker1 Creating new instance on SSH port 8102 and RMI ports 1100/44445 at: /Users/jdoe/Downloads/jboss-fuse-6.3.0-254/instances/broker1 The following containers have been created successfully: broker1. JBossFuse:karaf@root> fabric:mq-create --assign-container broker1 brokerx MQ profile mq-broker-default.brokerx ready
mq-broker-default.brokerx
profile to the container, by invoking fabric:mq-create
with the --assign-container
option. Of course, instead of deploying to a local child container (as in this example), we could assign the broker to an SSH container.
Broker groups
fabric:mq-create
command are always registered with a specific broker group. If you do not specify the group name explicitly at the time you create the broker, the broker gets registered with the default
group by default.
--group
option of the fabric:mq-create
command. For example, to create a new broker that registers with the west-coast
group, enter the following console command:
JBossFuse:karaf@root> fabric:mq-create --create-container broker --replicas 1 --group west-coast brokery MQ profile mq-broker-west-coast.brokery ready
west-coast
group does not exist prior to running this command, it is automatically created by Fabric. Broker groups are important for defining clusters of brokers, providing the underlying mechanism for creating load-balancing clusters and master-slave clusters. For details, see Section 10.3, “Topologies”.
10.2. Connecting to a Broker
Overview
default
group.
Client URL
discovery:(fabric:GroupName)
default
group, the client would use the following URL:
discovery:(fabric:default)
10.3. Topologies
10.3.1. Load-Balancing Cluster
Overview
loadbal
, and with three brokers registered in the group: brokerx
, brokery
, and brokerz
. This topology is most useful in a scenario where producer is generating a heavy load but does not care if all the messages are delivered to the consumer. In this scenario non persistent messages are used. This topology does not have shared storage. For scenarios where better guarantees regarding delivery of messages is required it is best to combine networks and master slave as defined in subsequent sections.
Figure 10.1. Load-Balancing Cluster
Create brokers in a load-balancing cluster
- Choose a group name for the load-balancing cluster.
- Each broker in the cluster registers with the chosen group.
- Each broker must be identified by a unique broker name.
- Normally, each broker is deployed in a separate container.
loadbal
and the cluster consists of three broker instances with broker names: brokerx
, brokery
, and brokerz
.
- First of all create some containers:
JBossFuse:karaf@root> container-create-child root broker 3 Creating new instance on SSH port 8102 and RMI ports 1100/44445 at: /Users/jdoe/Downloads/jboss-fuse-6.3.0.redhat-254/instances/broker2 Creating new instance on SSH port 8104 and RMI ports 1102/44447 at: /Users/jdoe/Downloads/jboss-fuse-6.3.0.redhat-254/instances/broker3 Creating new instance on SSH port 8103 and RMI ports 1101/44446 at: /Users/jdoe/Downloads/jboss-fuse-6.3.0.redhat-254/instances/broker1 The following containers have been created successfully: Container: broker2. Container: broker3. Container: broker1.
- Wait until the containers are successfully provisioned. You can conveniently monitor them using the
watch
command, as follows:JBossFuse:karaf@root> watch container-list
- You can then assign broker profiles to each of the containers, using the
fabric:mq-create
command, as follows:JBossFuse:karaf@root> mq-create --group loadbal --assign-container broker1 brokerx MQ profile mq-broker-loadbal.brokerx ready JBossFuse:karaf@root> mq-create --group loadbal --assign-container broker2 brokery MQ profile mq-broker-loadbal.brokery ready JBossFuse:karaf@root> mq-create --group loadbal --assign-container broker3 brokerz MQ profile mq-broker-loadbal.brokerz ready
- You can use the
fabric:profile-list
command to see the new profiles created for these brokers:JBossFuse:karaf@root> profile-list --hidden [id] [# containers] [parents] ... mq-broker-loadbal.brokerx 1 mq-base mq-broker-loadbal.brokery 1 mq-base mq-broker-loadbal.brokerz 1 mq-base mq-client-loadbal ...
- You can use the
fabric:cluster-list
command to view the cluster configuration for this load balancing cluster:JBossFuse:karaf@root> cluster-list [cluster] [masters] [slaves] [services] ... amq/loadbal brokerx broker1 - tcp://MyLocalHost.61616 mqtt://MyLocalHost.61424 amqp://MyLocalHost.61426 stomp://MyLocalHost.61428 brokery broker2 - tcp://MyLocalHost.61437 mqtt://MyLocalHost.61439 amqp://MyLocalHost.61441 stomp://MyLocalHost.61443 brokerz broker3 - tcp://MyLocalHost.61453 mqtt://MyLocalHost.61455 amqp://MyLocalHost.61457 stomp://MyLocalHost.61459
Configure clients of a load-balancing cluster
discovery:(fabric:GroupName)
, which automatically load balances the client across the available brokers in the cluster. For example, to connect a client to the loadbal
cluster, you would use a URL like the following:
discovery:(fabric:loadbal)
mq-create
command automatically generates a profile named mq-client-GroupName
, which provides an ActiveMQConnectionFactory
instance in the registry. If you deploy this profile together with a Camel route that uses JMS endpoints, the Camel route will automatically find and use the ActiveMQConnectionFactory
instance to connect to the broker cluster.
10.3.2. Master-Slave Cluster
Overview
masterslave
, and three brokers that compete with each other to register as the broker, hq-broker
. A broker becomes the master by acquiring a lock (where the lock implementation is provided by the underlying ZooKeeper registry). The other two brokers that fail to acquire the lock remain as slaves (but they continue trying to acquire the lock, at regular time intervals).
Figure 10.2. Master-Slave Cluster
Create brokers in a master-slave cluster
- Choose a group name for the master-slave cluster.
- Each broker in the cluster registers with the chosen group.
- Each broker must be identified by the same virtual broker name.
- Normally, each broker is deployed in a separate container.
masterslave
and the cluster consists of three broker instances, each with the same broker name: hq-broker
. You can create this cluster by entering a single fabric:mq-create
command, as follows:
JBossFuse:karaf@root> mq-create --create-container broker --replicas 3 --group masterslave hq-broker
broker1
, broker2
and broker3
(possibly running on separate machines), you can deploy a cluster of three brokers to the containers by entering the following command:
JBossFuse:karaf@root> mq-create --assign-container broker1,broker2,broker3 --group masterslave hq-broker
Configure clients of a master-slave cluster
discovery:(fabric:GroupName)
, which automatically connects the client to the current master server. For example, to connect a client to the masterslave
cluster, you would use a URL like the following:
discovery:(fabric:masterslave)
mq-client-masterslave
, to create sample clients (by referencing the corresponding ActiveMQConnectionFactory
instance in the registry).
Locking mechanism
Re-using containers for multiple clusters
broker1
, broker2
, and broker3
, already running the hq-broker
cluster, it is possible to reuse the same containers for another highly available broker cluster, web-broker
. You can assign the web-broker
profile to the existing containers with the following command:
mq-create --assign-container broker1,broker2,broker3 web-broker
web-broker
profile to the same containers already running hq-broker
. Fabric automatically prevents two masters from running on the same container, so the master for hq-broker
will run on a different container from the master for web-broker
. This arrangement makes optimal use of the available resources.
Configuring persistent data
fabric:mq-create
command enables you to specify the location of the data directory, as follows:
mq-create --assign-container broker1 --data /var/activemq/hq-broker hq-broker
hq-broker
virtual broker, which uses the /var/activemq/hq-broker
directory for the data (and store) location. You can then mount some shared storage to this path and share the storage amongst the brokers in the master-slave cluster.
10.3.3. Broker Networks
Overview
Broker networks
Creating network connectors
--network
option to the fabric:mq-create
command.
Example broker network
Figure 10.3. Broker Network with Master-Slave Clusters
- The first cluster has the group name,
us-west
, and provides high-availability with a master-slave cluster of two brokers,us-west1
andus-west2
. - The second cluster has the group name,
us-east
, and provides high-availability with a master-slave cluster of two brokers,us-east1
andus-east2
.
us-east
group (consisting of the two containers us-east1
and us-east2
), you would log on to a root container running in the US East location and enter a command like the following:
mq-create --group us-east --network us-west --networks-username User --networks-password Pass --create-container us-east us-east
--network
option specifies the name of the broker group you want to connect to, and the User
and Pass
are the credentials required to log on to the us-west
broker cluster. By default, the fabric:mq-create
command creates a master/slave pair of brokers.
us-west
group (consisting of the two containers us-west1
and us-west2
), you would log on to a root container running in the US West location and enter a command like the following:
mq-create --group us-west --network us-east --networks-username User --networks-password Pass --create-container us-west us-west
User
and Pass
are the credentials required to log on to the us-east
broker cluster.
--assign-container
option in place of --create-container
.
Connecting to the example broker network
discovery:(fabric:us-east)
discovery:(fabric:us-west)
10.4. Alternative Master-Slave Cluster
Why use an alternative master-slave cluster?
Alternative locking mechanism
- Disable the default Zookeeper locking mechanism (which can be done by setting
standalone=true
in the broker'sio.fabric8.mq.fabric.server-BrokerName
PID). - Enable the shared file system master/slave locking mechanism in the KahaDB persistence layer (see section "Shared File System Master/Slave" in "Fault Tolerant Messaging").
standalone property
standalone
property belongs to the io.fabric8.mq.fabric.server-BrokerName
PID and is normally used for a non-Fabric broker deployment (for example, it is set to true
in the etc/io.fabric8.mq.fabric.server-broker.cfg
file). By setting this property to true
, you instruct the broker to stop using the discovery and coordination services provided by Fabric (but it is still possible to deploy the broker in a Fabric container). One consequence of this is that the broker stops using the Zookeeper locking mechanism. But this setting has other side effects as well.
Side effects of setting standalone=true
standalone=true
, on a broker deployed in Fabric has the following effects:
- Fabric no longer coordinates the locks for the brokers (hence, the broker's persistence adapter needs to be configured as shared file system master/slave instead).
- The broker no longer uses the
ZookeeperLoginModule
for authentication and falls back to using thePropertiesLoginModule
instead. This requires users to be stored in theetc/users.properties
file or added to thePropertiesLoginModule
JAAS Realm in the container where the broker is running for the brokers to continue to accept connections - Fabric discovery of brokers no longer works (which affects client configuration).
Configuring brokers in the cluster
- Set the property,
standalone=true
, in each broker'sio.fabric8.mq.fabric.server-BrokerName
PID. For example, given a broker with the broker name,brokerx
, which is configured by the profile,mq-broker-default.brokerx
, you could set thestandalone
property totrue
using the following console command:profile-edit --pid io.fabric8.mq.fabric.server-brokerx/standalone=true mq-broker-default.brokerx
- To customize the broker's configuration settings further, you need to create a unique copy of the broker configuration file in the broker's own profile (instead of inheriting the broker configuration file from the base profile,
mq-base
). If you have not already done so, follow the instructions in the section called “Customizing the broker configuration file” to create a custom broker configuration file for each of the broker's in the cluster. - Configure each broker's KahaDB persistence adapter to use the shared file system locking mechanism. For this you must customize each broker configuration file, adding or modifying (as appropriate) the following XML snippet:
<broker ... > ... <persistenceAdapter> <kahaDB directory="/sharedFileSystem/sharedBrokerData" lockKeepAlivePeriod="2000"> <locker> <shared-file-locker lockAcquireSleepInterval="10000" /> </locker> </kahaDB> </persistenceAdapter> ... </broker>
You can edit this profile resource either though the Fuse Management Console, through the Git configuration approach (see Section 10.5, “Broker Configuration”), or using thefabric:profile-edit
command.
Configuring authentication data
standalone=true
on a broker, it can no longer use the default ZookeeperLoginModule
authentication mechanism and falls back on the PropertiesLoginModule
. This implies that you must populate authentication data in the etc/users.properties
file on each of the hosts where a broker is running. Each line of this file takes an entry in the following format:
Username=Password,Role1,Role2,...
Username
and Password
credentials and a list of one or more roles, Role1, Role2,...
.
Configuring a client
failover:(tcp://broker1:61616,tcp://broker2:61616,tcp://broker3:61616)
10.5. Broker Configuration
Overview
Setting OSGi Config Admin properties
broker1
profile created by entering the following fabric:mq-create
command:
fabric:mq-create --create-container broker --replicas 1 --network us-west brokerx
mq-broker-default.brokerx
, and assigns this profile to the newly created broker1
container.
mq-broker-Group.BrokerName
by default. If you want the profile to have the same name as the broker (which was the default in JBoss A-MQ version 6.0), you can specify the profile name explicitly using the --profile
option.
mq-broker-default.brokerx
profile using the fabric:profile-display
command, as follows:
JBossFuse:karaf@root> profile-display mq-broker-default.brokerx Profile id: mq-broker-default.brokerx Version : 1.0 Attributes: parents: mq-base Containers: Container settings ---------------------------- Configuration details ---------------------------- PID: io.fabric8.mq.fabric.server-brokerx connectors openwire mqtt amqp stomp data ${runtime.data}brokerx standby.pool default keystore.file profile:keystore.jks kind MasterSlave keystore.password mca^e.Xg broker-name brokerx ssl true truststore.password mca^e.Xg keystore.cn localhost keystore.url profile:keystore.jks truststore.file profile:truststore.jks config profile:ssl-broker.xml group default network us-west Other resources ---------------------------- Resource: truststore.jks Resource: keystore.jks
io.fabric8.mq.fabric.server-brokerx
PID are a variety of property settings, such as network
and group
. You can now modify the existing properties or add more properties to this PID to customize the broker configuration.
Modifying basic configuration properties
io.fabric8.mq.fabric.server-brokerx
PID by invoking the fabric:profile-edit
command, with the appropriate syntax for modifying PID properties.
network
property to us-east
, enter the following console command:
profile-edit --pid io.fabric8.mq.fabric.server-brokerx/network=us-east mq-broker-default.brokerx
Customizing the SSL keystore.jks and truststore.jks file
mq-broker-default.brokerx
profile when SSL is enabled (which is the default case):
keystore.jks
- A Java keystore file containing this broker's own X.509 certificate. The broker uses this certificate to identify itself to other brokers in the network. The password for this file is stored in the
io.fabric8.mq.fabric.server-brokerx/keystore.password
property. truststore.jks
- A Java truststore file containing one or more Certificate Authority (CA) certificates or other certificates, which are used to verify the certificates presented by other brokers during the SSL handshake. The password for this file is stored in the
io.fabric8.mq.fabric.server-brokerx/truststore.password
property.
mq-broker-default.brokerx
profile, perform the following steps:
- If you have not done so already, clone the git repository that stores all of the profile data in your Fabric. Enter a command like the following:
git clone -b 1.0 http://Username:Password@localhost:8181/git/fabric cd fabric
WhereUsername
andPassword
are the credentials of a Fabric user withAdministrator
role and we assume that you are currently working with profiles in version1.0
(which corresponds to the git branch named1.0
).NoteIn this example, it is assumed that the fabric is set up to use the git cluster architecture (which is the default) and also that the Fabric server running onlocalhost
is currently the master instance of the git cluster. - The
keystore.jks
file and thetruststore.jks
file can be found at the following locations in the git repository:fabric/profiles/mq/broker/default.brokerx.profile/keystore.jks fabric/profiles/mq/broker/default.brokerx.profile/truststore.jks
Copy your custom versions of thekeystore.jks
file andtruststore.jks
file to these locations, over-writing the default versions of these files. - You also need to modify the corresponding passwords for the keystore and truststore. To modify the passwords, edit the following file in a text editor:
fabric/profiles/mq/broker/default.brokerx.profile/io.fabric8.mq.fabric.server-brokerx.properties
Modify thekeystore.password
andtruststore.password
settings in this file, to specify the correct password values for your custom JKS files. - When you are finished modifying the profile configuration, commit and push the changes back to the Fabric server using git, as follows:
git commit -a -m "Put a description of your changes here!" git push
- For these SSL configuration changes to take effect, a restart of the affected broker (or brokers) is required. For example, assuming that the modified profile is deployed on the
broker
container, you would restart thebroker
container as follows:fabric:container-stop broker fabric:container-start broker
Customizing the broker configuration file
ssl-broker.xml
, for an SSL-enabled broker; and broker.xml
, for a non-SSL-enabled broker.
mq-base
parent profile). The easiest way to make this kind of change is to use a git repository of profile data that has been cloned from a Fabric ensemble server.
mq-broker-default.brokerx
profile, perform the following steps:
- It is assumed that you have already cloned the git repository of profile data from the Fabric ensemble server (see the section called “Customizing the SSL keystore.jks and truststore.jks file”). Make sure that you have checked out the branch corresponding to the profile version that you want to edit (which is assumed to be
1.0
here). It is also a good idea to do a git pull to ensure that your local git repository is up-to-date. In your git repository, enter the following git commands:git checkout 1.0 git pull
- The default broker configuration files are stored at the following location in the git repository:
fabric/profiles/mq/base.profile/ssl-broker.xml fabric/profiles/mq/base.profile/broker.xml
Depending on whether your broker is configured with SSL or not, you should copy either thessl-broker.xml
file or thebroker.xml
file into your broker's profile. For example, assuming that your broker uses themq-broker-default.brokerx
profile and is configured to use SSL, you would copy the broker configuration as follows:cp fabric/profiles/mq/base.profile/ssl-broker.xml fabric/profiles/mq/broker/default.brokerx.profile/
- You can now edit the copy of the broker configuration file, customizing the broker's Spring XML configuration as required.
- When you are finished modifying the broker configuration, commit and push the changes back to the Fabric server using git, as follows:
git commit -a -m "Put a description of your changes here!" git push
- For the configuration changes to take effect, a restart of the affected broker (or brokers) is required. For example, assuming that the modified profile is deployed on the
broker
container, you would restart thebroker
container as follows:fabric:container-stop broker fabric:container-start broker
Additional broker configuration templates in mq-base
mq-base
profile, which can then be used as templates for creating new brokers with the fabric:mq-create
command. Additional template configurations must be added to the following location in the git repository:
fabric/profiles/mq/base.profile/
--config
option to the fabric:mq-create
command.
mybrokertemplate.xml
, has just been installed:
fabric/profiles/mq/base.profile/mybrokertemplate.xml
mybrokertemplate.xml
configuration template by invoking the fabric:mq-create
command with the --config
option, as follows:
fabric:mq-create --config mybrokertemplate.xml brokerx
--config
option assumes that the configuration file is stored in the current version of the mq-base
profile, so you need to specify only the file name (that is, the full ZooKeeper path is not required).
Setting network connector properties
network.NetworkPropName
. For example, to add the setting, network.bridgeTempDestinations=false
, to the PID for brokerx
(which has the profile name, mq-broker-default.brokerx
), enter the following console command:
profile-edit --pid io.fabric8.mq.fabric.server-brokerx/network.bridgeTempDestinations=false mq-broker-default.brokerx
Network connector properties by reflection
network.OptionName
can be used to set the corresponding OptionName
property on the org.apache.activemq.network.NetworkBridgeConfiguration
class. In particular, this implies you can set any of the following network.OptionName
properties:
Property | Default | Description |
---|---|---|
name | bridge | Name of the network - for more than one network connector between the same two brokers, use different names |
userName | None | Username for logging on to the remote broker port, if authentication is enabled. |
password | None | Password for logging on to the remote broker port, if authentication is enabled. |
dynamicOnly | false | If true , only activate a networked durable subscription when a corresponding durable subscription reactivates, by default they are activated on start-up. |
dispatchAsync | true | Determines how the network bridge sends messages to the local broker. If true , the network bridge sends messages asynchronously. |
decreaseNetworkConsumerPriority | false | If true , starting at priority -5 , decrease the priority for dispatching to a network Queue consumer the further away it is (in network hops) from the producer. If false , all network consumers use same default priority (that is, 0 ) as local consumers. |
consumerPriorityBase | -5 | Sets the starting priority for consumers. This base value will be decremented by the length of the broker path when decreaseNetworkConsumerPriority is set. |
networkTTL | 1 | The number of brokers in the network that messages and subscriptions can pass through (sets both messageTTL and consumerTTL ) |
messageTTL | 1 | The number of brokers in the network that messages can pass through. |
consumerTTL | 1 | The number of brokers in the network that subscriptions can pass through (keep to 1 in a mesh). |
conduitSubscriptions | true | Multiple consumers subscribing to the same destination are treated as one consumer by the network. |
duplex | false | If true , a network connection is used both to produce and to consume messages. This is useful for hub and spoke scenarios, when the hub is behind a firewall, and so on. |
prefetchSize | 1000 | Sets the prefetch size on the network connector's consumer. It must be greater than 0 , because network consumers do not poll for messages |
suppressDuplicateQueueSubscriptions | false | If true , duplicate subscriptions in the network that arise from network intermediaries are suppressed. For example, consider brokers A , B , and C , networked using multicast discovery. A consumer on A gives rise to a networked consumer on B and C . In addition, C networks to B (based on the network consumer from A ) and B networks to C . When true , the network bridges between C and B (being duplicates of their existing network subscriptions to A ) will be suppressed. Reducing the routing choices in this way provides determinism when producers or consumers migrate across the network as the potential for dead routes (stuck messages) are eliminated. The networkTTL value needs to match or exceed the broker count to require this intervention. |
suppressDuplicateTopicSubscriptions | true | If true , duplicate network topic subscriptions (in a cyclic network) are suppressed. |
bridgeTempDestinations | true |
Whether to broadcast advisory messages for temporary destinations created in the network of brokers. Temporary destinations are typically created for request-reply messages. Broadcasting the information about temp destinations is turned on by default, so that consumers of a request-reply message can be connected to another broker in the network and still send back the reply on the temporary destination specified in the
JMSReplyTo header. In an application scenario where most or all of the messages use the request-reply pattern, this generates additional traffic on the broker network, because every message typically sets a unique JMSReplyTo address (which causes a new temp destination to be created and broadcasted with an advisory message in the network of brokers).
If you disable this feature, this network traffic can be reduced, but in this case the producers and consumers of a request-reply message need to be connected to the same broker. Remote consumers (that is, connected through another broker in your network) will not be able to send the reply message, but instead will raise a
temp destination does not exist exception.
|
alwaysSyncSend | false | If true , non-persistent messages are sent to the remote broker using request/reply semantics instead of oneway message semantics. This setting affects both persistent and non-persistent messages the same way. |
staticBridge | false | If true , the broker does not respond dynamically to new consumers. It uses only staticallyIncludedDestinations to create demand subscriptions. |
useCompression | false | Compresses the message body when sending it over the network. |
advisoryForFailedForward | false | If true , send an advisory message when the broker fails to forward the message to the temporary destination across the bridge. |
useBrokerNamesAsIdSeed | true | Add the broker name as a prefix to connections and consumers created by the network bridge. It helps with visibility. |
gcDestinationViews | true | If true , remove any MBeans for destinations that have not been used for a while. |
gcSweepTime | 60000 | The period of inactivity in milliseconds, after which we remove MBeans. |
checkDuplicateMessagesOnDuplex | false | If true , check for duplicates on the duplex connection. |
Chapter 11. Shutting Down a Broker
Abstract
11.1. Shutting Down a Local Broker
Abstract
Overview
Stopping the broker from console mode
Example 11.1. Using the Console's Shutdown Command
JBossA-MQ:karaf@root>
shutdown -f
JBossA-MQ:karaf@root>
logout [Process completed]
Stopping a broker running in daemon mode
bin
folder.
11.2. Shutting Down a Broker Remotely
Abstract
Overview
- using the stop command—the stop command does not require starting an instance of the broker
- using a remote console connection—a broker's console can be used to remotely shutdown a broker on another machine
- using a fabric member's console—brokers that are part of a fabric can stop members of their fabric
- using the management console—brokers that are part of a fabric can be stopped using a management console connected to their fabricFor more information see Using the Management Console.
Using the stop command
InstallDir/bin
directory. The commands syntax is shown in Example 11.2, “Stop Command Syntax”.
Example 11.2. Stop Command Syntax
stop
[
-a port
] {
-h hostname
} {
-u username
} {
-p password
}
-a port
- Specifies the SSH port of the remote instance. The default is 8101.
-h hostname
- Specifies the hostname of the machine on which the remote instance is running.
-u username
- Specifies the username used to connect to the remote broker.NoteThe default username for a broker is
karaf
. -p password
- Specifies the password used to connect to the remote broker.NoteThe default password for a broker is
karaf
.
NEBrokerHost2
.
Example 11.3. Stopping a Remote Broker
bin/stop -u karaf -p karaf -h NEBrokerHost2
Using a remote console
NWBrokerHost
.
Example 11.4. Shutting Down a Broker using a Remote Console Connection
JBossA-MQ:karaf@root>
ssh -l username -P password 8101 HOSTNAME
_ ____ __ __ ____ | | _ \ /\ | \/ |/ __ \ | | |_) | ___ ___ ___ / \ ______| \ / | | | | _ | | _ < / _ \/ __/ __| / /\ \______| |\/| | | | | | |__| | |_) | (_) \__ \__ \ / ____ \ | | | | |__| | \____/|____/ \___/|___/___/ /_/ \_\ |_| |_|\___\_\ JBoss A-MQ (6.0.0.redhat-012) http://www.redhat.com/products/jbossenterprisemiddleware/amq/ Hit '<tab>' for a list of available commands and '[cmd] --help' for help on a specific command. Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown JBoss A-MQ.
JBossA-MQ:karaf@root>
osgi:shutdown
Confirm: shutdown instance root (yes/no):
yes
JBossA-MQ:karaf@root>
JBossA-MQ:karaf@root>
Shutting down remote brokers in a fabric
fabric-broker3
.
Example 11.5. Shutting Down a Broker in a Fabric
./bin/client fabric-broker3 fabric:container-stop
Chapter 12. Adding Client Connection Points
Abstract
12.1. Overview of Transport Connectors
- a
transportConnector
element in the XML configuration template that provides the details for the connection point - an entry in the broker's
io.fabric8.mq.fabric.server.id
PID's connectors property to activate the connection point
transportConnector
element provides all of the details needed to create the connection point. This includes the type of transport being used, the host and port for the connection, and any transport properties needed. The connectors property is a space delimited list that specifies which transport connectors to activate.
12.2. Adding a Transport Connector to a Standalone Broker
Adding a transport connector definition
- Open the broker's configuration template for editing.
- Locate the
transportConnectors
element. - Add a
transportConnector
element as a child of thetransportConnectors
element. - Add a
name
attribute to the newtransportConnector
element.Thename
attribute specifies a unique identifier for the transport connector. It is used in the connectors property to identify the transport to be activated. - Add a
uri
attribute to the newtransportConnector
element.Theuri
attribute specifies the connection details used to instantiate the connector. Clients will use a similar URI to access the broker using this connector. For a complete list of the URIs see the Connection Reference. - Save the changes to the configuration template.
Activating a connector
- Connect to the broker using a command console.
- Open the broker's
io.fabric8.mq.fabric.server.id
PID for editing using the config:editcommand.JBossAMQ:karaf>
config:edit io.fabric8.mq.fabric.server.098765NoteYou can use the config:list command to find the id for the broker. - Verify the value of the connectors property using the config:proplist command.
JBossAMQ:karaf>
config:proplist connector - Change the value of the connectors property using the config:propset command.
JBossAMQ:karaf>
config:propset connector "connector1 connector2..."connector1 specifies the name of a transport to activate. The value corresponds the value of thetransportConnector
element'sname
attribute. - Save the changes using the config:update command.
JBossAMQ:karaf>
config:update
Chapter 13. Adding a Queue or a Topic
Abstract
Automatic destination creation
Restricting destination creation
admin
role and not granting it to certain user groups, you can ensure that those user groups are unable to create new destinations on the fly.
admin
role vary, depending on which authorization plug-in the broker uses. For full details about how to configure broker authorization, please consult the Authorization chapter of the JBoss A-MQ Security Guide.
Chapter 14. Using Logging
Abstract
14.1. Overview of Logging
- Apache Log4j
- Apache Commons Logging
- SLF4J
- Java Util Logging
14.2. Logging Configuration
Abstract
Overview
etc/system.properties
—the configuration file that sets the logging level during the broker’s boot process. The file contains a single property, org.ops4j.pax.logging.DefaultServiceLog.level, that is set toERROR
by default.org.ops4j.pax.logging
—the PID used to configure the logging back end service. It sets the logging levels for all of the defined loggers and defines the appenders used to generate log output. It uses standard Log4j configuration. By default, it sets the root logger's level toINFO
and defines two appenders: one for the console and one for the log file.NoteThe console's appender is disabled by default. To enable it, addlog4j.appender.stdout.append=true
to the configuration For example, to enable the console appender in a broker, you would use the following commands:JBossA-MQ:karaf@root>
config:edit org.ops4j.pax.logging
JBossA-MQ:karaf@root>
config:propappend log4j.appender.stdout.append true
JBossA-MQ:karaf@root>
config:update
org.apache.karaf.log.cfg
—configures the output of the log console commands.
Changing the log levels
org.ops4j.pax.logging
PID's log4j.rootLogger
property so that the logging level is one of the following:
TRACE
DEBUG
INFO
WARN
ERROR
FATAL
NONE
Example 14.1. Changing Logging Levels
JBossA-MQ:karaf@root>
config:edit org.ops4j.pax.logging
JBossA-MQ:karaf@root>
config:propset log4j.rootLogger "DEBUG, out, osgi:VmLogAppender"
JBossA-MQ:karaf@root>
config:update
Changing the appenders' thresholds
log4j.appender.appenderName.threshold
property that controls what level of messages are written to the appender. The appender threshold values are the same as the log level values.
DEBUG
but limiting the information displayed on the console to WARN
.
Example 14.2. Changing the Log Information Displayed on the Console
JBossA-MQ:karaf@root>
config:edit org.ops4j.pax.logging
JBossA-MQ:karaf@root>
config:propset log4j.rootLogger "DEBUG, out, osgi:VmLogAppender"
JBossA-MQ:karaf@root>
config:propappend log4j.appender.stdout.threshold WARN
JBossA-MQ:karaf@root>
config:update
14.3. Viewing the Log
Abstract
Overview
- using a text editor
- using the broker's, or a remote broker's, console
- using the administration client
Viewing the log in a text editor
InstallDir/data/log
. The main log file is karaf.log
. If archiving is turned on, there may be archived log files also stored in the logging directory.
- the time of the entry
- the log level of the entry
- the thread that generated the entry
- the bundle that generated the entry
- an informational message about the cause of the entry
Viewing the log with the console
- log:display—displays the most recent log entriesBy default, the number of entries returned and the pattern of the output depends on the size and pattern properties in the
org.apache.karaf.log.cfg
file. You can override these using the-p
and-d
arguments. - log:display-exception—displays the most recently logged exception
- log:tail—continuously display log entries
Viewing the log with the administration client
client log:display
into a system terminal will display the most recent log entries for the local broker.
14.4. Change Logging Level at Runtime using JConsole
- Start activemq using ./bin/activemq start.
- Open JConsole and connect to activemq. To connect to activemq use the
activemq.jar start
listed in local processes if you have launched JConsole on same machine as activemq. For connecting remotely you need to configure activemq. Refer to http://activemq.apache.org/jmx.html. - In JConsole, click the MBeanstab.
- Navigate to
org.apache.activemq
-> Broker -> localhost -> Log4JConfiguarion -> RootLogLevel and set attribute value to DEBUG.
setLogLevel
on Log4JConfiguration MBean.
Chapter 15. Using JMX
Abstract
15.1. Introduction to JMX
15.2. Configuring JMX
Abstract
Overview
Enabling and disabling
broker
element's useJmx
attribute to false
. This will stop the broker from exposing itself via JMX.
Securing access to JMX
jmxRole
property to the etc/org.apache.karaf.management.cfg
file.
Advanced configuration
managementContext
child element to the broker's broker
element. The managementContext
element uses a managementContext
child to configure the broker. The attributes of the inner managementContext
element specify the broker's JMX configuration.
Table 15.1. Broker JMX Configuration Properties
Property | Default Value | Description |
---|---|---|
useMBeanServer | true | Specifies whether the broker will use the MBean server created by the JVM. When set to false , the broker will create an MBean server. |
jmxDomainName | org.apache.activemq | Specifies the JMX domain used by the broker's MBeans. |
createMBeanServer | true | Specifies whether the broker creates an MBean server if none is found. |
createConnector | true [a] | Specifies whether the broker creates a JMX connector for the MBean server. If this is set to false the broker will only be accessible using the JMX connector created by the JVM. |
connectorPort | 1099 | Specifies the port number used by the JMX connector created by the broker. |
connectorHost | localhost | Specifies the host used by the JMX connector and the RMI server. |
rmiServerPort | 0 | Specifies the RMI server port. This setting is useful if port usage needs to be restricted behind a firewall. |
connectorPath | /jmxrmi | Specifies the path under which the JMX connector will be registered. |
suppressMBean
| empty |
Specifies a comma-separated list of MBean name patterns to ignore. For example:
endpoint=dynamicProducer,endpoint=Consumer,connectionName=*,destinationName=ActiveMQ.Advisory.*
|
[a]
The default configuration template for the broker sets this property to false so that the broker uses the container's JMX connection.
|
Example 15.1. Configuring a Broker's JMX Connection
<broker ... > ... <managementContext> <managementContext createMBeanServer="false" createConnector="false" /> </managementContext> ... </broker>
15.3. Statistics Collected by JMX
Broker statistics
Table 15.2. Broker JMX Statistics
Destination statistics
Table 15.3. Destination JMX Statistics
Subscription statistics
Table 15.4. Connection JMX Statistics
15.4. Managing the Broker with JMX
Abstract
Overview
Broker actions
Table 15.5. Broker MBean Operations
Connector actions
Table 15.6. Connector MBean Operations
Network connector actions
Table 15.7. Network Connector MBean Operations
Queue actions
Table 15.8. Queue MBean Operations
Topic actions
Table 15.9. Topic MBean Operations
Subscription actions
Table 15.10. Subscription MBean Operations
Chapter 16. Applying Patches
Abstract
16.1. Introduction to Patching
- Customer Support sends you a patch.
- Customer Support sends you a link to download a patch.
- Download a patch directly from the Red Hat customer portal.
- Standalone—the broker's command console's patch shell has commands for managing the patching process
- Fabric—patching a fabric requires applying the patch to a profile and then applying the profile to a broker.
16.2. Finding the Right Patches to Apply
Abstract
Locate the patches on the customer portal
- Login to the Red Hat Customer Portal using your customer account. This account must be associated with an appropriate Red Hat software subscription, otherwise you will not be able to see the patch downloads for JBoss A-MQ.
- Navigate to the customer portal Software Downloads page.
- In the Product dropdown menu, select the appropriate product (for example, A-MQ or Fuse), and then select the version, 6.3, from the Version dropdown menu. A table of downloads now appears, which has three tabs: Releases, Patches, and Security Advisories.
- Click the Releases tab to view the GA product releases.
- Click the Patches tab the rollup patches, and the regular incremental patches (with no security-related fixes).
- Click the Security Advisories tab to view the incremental patches with security-related fixes.
Types of patch
- Rollup patches
- Incremental patches
Rollup patches
- Each rollup patch file is a complete new build of the official target distribution. This means you can unzip the rollup patch file to obtain a completely new installation of JBoss A-MQ, just as if it was a fresh download of the product (which, in fact, it is). See Section 16.3, “Installing a Rollup Patch as a New Installation”.
- You can also treat the rollup patch as a regular patch, using it to upgrade an existing installation. That is, you can provide the rollup patch file as an argument to the standalone patch console commands (for example,
patch:add
andpatch:install
) or the Fabric patch console command,patch:fabric-install
.
Incremental patches
Which patches are needed to update the GA product to the latest patch level?
- If the only patches released so far are patches with GA baseline (Patch 1, Patch 2, and so on), apply the latest of these patches directly to the GA product.
- If a rollup patch has been released and no patches have been released after the latest rollup patch, simply apply the latest rollup patch to the GA product.
- If the latest patch is a patch with a rollup baseline, you must apply two patches to the GA product, as follows:
- Apply the latest rollup patch, and then
- Apply the latest patch with a rollup baseline.
Which patches to apply, if you only want to install regression-tested patches?
16.3. Installing a Rollup Patch as a New Installation
A rollup patch is a new build
Installing the new build
- Identify which rollup patch you need to install and download it from the Customer Portal. For more details, see Section 16.2, “Finding the Right Patches to Apply”.
- Unzip the rollup patch file to a convenient location, just as you would with a regular GA distribution. This is your new installation of JBoss A-MQ.
Comparison with patch process
- This approach is only for creating a completely new installation of JBoss A-MQ. If your existing installation already has a lot of custom configuration, this might not be the most convenient approach to use.
- The new build includes only the artifacts and configuration for the new patch level. There is thus no concept of rolling back to the GA version.
- If you create a new fabric (using
fabric:create
), the default fabric profiles are already at the new patch level (same as the standalone container). It is therefore not necessary to patch the fabric.
16.4. Patching a Standalone Container
Abstract
Overview
Incremental patch
- Updates bundle JARs.
- Patches only the current container instance (under the
data/
directory). Hence, patches are not preserved after deleting a container instance. - Updates any feature dependencies installed in the current container instance, but does not update the feature files themselves.
- Might update some configuration files, but is not suitable for updating most configuration files.
- Supports patch rollback.
- After applying the patch, and creating a new fabric using
fabric:create
, the new Fabric reverts to the unpatched configuration.
etc/startup.properties
and etc/overrides.properties
files. With these files, the Karaf installation is able to persist the patch even after deleting the root container instance (that is, after removing the root container's data/
directory).
data/cache
directory uninstalls any bundles, features, or feature repositories that were installed into the container using Karaf console commands. However, any patches that have been applied will remain installed, as long as the etc/startup.properties
and etc/overrides.properties
files are preserved.
Rollup patch
etc/
directory). A rollup patch:
- Updates any files, including bundle JARs, configuration files, and any static files.
- Patches both the current container instance (under the
data/
directory) and the underlying installation. Hence, patches are preserved after deleting a container instance. - Updates all of the files related to Karaf features, including the features repository files and the features themselves. Hence, any features installed after the rollup patch will reference the correct patched dependencies.
- If necessary, updates configuration files (for example, files under
etc/
), automatically merging any configuration changes you have made with the configuration changes made by the patch. If merge conflicts occur, see the patch log for details of how they are handled. - Tracks all of the changes made to the installation (including to static files), so that it is possible to roll back the patch.NoteThe rollup patching mechanism uses an internal git repository (located under
patches/.management/history
) to track the changes made. - After applying the patch, and creating a new fabric using
fabric:create
, the new Fabric is created with the patched configuration.
Patching the patch mechanism
- Download the appropriate patch management package. From the JBoss A-MQ 6.3.0 Software Downloads page, select a package named Red Hat JBoss A-MQ 6.3.0 Rollup N on Karaf Update Installer, where N is the number of the particular rollup patch you are about to install.ImportantThe rollup number, N, of the downloaded patch management package must match the rollup number of the rollup patch you are about to install. For some rollup patches, there is no corresponding patch management package, in which case you can skip directly to the instructions for installing the rollup patch.
- Install the patch management package,
patch-management-for-amq-630-TargetVersion.zip
, on top of your 6.3.0 installation. Use an archive utility to extract the contents on top of the existing Karaf container installation (installing files under thesystem/
andpatches/
subdirectories).NoteIt does not matter whether the container is running or not when you extract these files. - Start the container, if it is not already running.
- Uninstall the existing patch commands from the container as follows. Remove the patch features as follows:
JBossFuse:karaf@root> features:uninstall patch patch-core
But this is not sufficient to remove all of the patch bundles. Check for any remaining patch bundles as follows:JBossFuse:karaf@root> list -t 0 -l | grep patch [ 1] [Active ] [ ] [ ] [ 2] mvn:io.fabric8.patch/patch-management/1.2.0.redhat-630187
You can remove this system bundle, as follows:JBossFuse:karaf@root> uninstall 1 You are about to access system bundle 1. Do you wish to continue (yes/no): yes JBossFuse:karaf@root> list -t 0 -l | grep patch
Finally, you should remove the features URL for the old patch mechanism version, as follows:JBossFuse:karaf@root> features:listurl | grep patch true mvn:io.fabric8.patch/patch-features/1.2.0.redhat-630187/xml/features JBossFuse:karaf@root> features:removeurl mvn:io.fabric8.patch/patch-features/1.2.0.redhat-630187/xml/features
Check the version ofpatch-features
that you have, because it might be different from1.2.0.redhat-630187
. - Install the new patch commands as follows. Add the features URL for the new patch commands, as follows:
JBossFuse:karaf@root> features:addurl mvn:io.fabric8.patch/patch-features/1.2.0.redhat-630xxx/xml/features
Where you must replace1.2.0.redhat-630xxx
with the actual build version of the patch commands you are installing (for example, the build versionxxx
can be taken from the last three digits of theTargetVersion
in the downloaded patch management package file name).Install the new patch features, as follows:JBossFuse:karaf@root> features:install patch-core patch
Check that the requisite patch bundles are now installed:JBossFuse:karaf@root> list -t 0 -l | grep patch [ 265] [Active ] [ ] [ ] [ 80] mvn:io.fabric8.patch/patch-core/1.2.0.redhat-630xxx [ 266] [Active ] [ ] [ ] [ 2] mvn:io.fabric8.patch/patch-management/1.2.0.redhat-630xxx [ 267] [Active ] [ ] [ ] [ 80] mvn:io.fabric8.patch/patch-commands/1.2.0.redhat-630xxx
- Restart the container (the
patch:add
command and the other patch commands will not be available in the console shell until you perform a restart).
Applying a patch
- Make a full backup of your JBoss A-MQ installation before attempting to apply the patch.
- (Rollup patch only) Before applying the rollup patch to your container, you must patch the patch mechanism, as described in the section called “Patching the patch mechanism”.
- (Rollup patch only) Remove the
lib/endorsed/org.apache.karaf.exception-2.4.0.redhat-630xxx.jar
file (where the build number,xxx
, depends on the build being patched). - (Incremental patch only) Before you proceed to install the patch, make sure to read the text of the
README
file that comes with the patch, as there might be additional manual steps required to install a particular patch. - Start the container, if it is not already running. If the container is running in the background (or remotely), connect to the container using the SSH console client,
/bin/client
. - Add the patch to the container's environment by invoking the patch:add command. For example, to add the
patch.zip
patch file:patch:add file://patch.zip
- Simulate installing the patch by invoking the patch:simulate command.This generates a log of the changes that will be made to the container when the patch is installed, but will not make any actual changes to the container. Review the simulation log to understand the changes that will be made to the container.
- Invoke the patch:list command to display a list of added patches. In this list, the entries under the
[name]
heading are patch IDs. For example:patch:list [name] [installed] [description] jboss-a-mq-6.3.0.redhat-329 false
Ensure that the container has fully started before you try to perform the next step. In some cases, the container must restart before you can apply a patch, for example, if static files are patched. In these cases, the container restarts automatically. - Apply a patch to the container by invoking the patch:install command and specifying the patch ID for the patch that you want to apply. For example:
patch:install jboss-a-mq-6.3.0.redhat-329
- Validate the patch, by searching for one of the patched artifacts. For example, if you had just upgraded JBoss A-MQ 6.2.1 to the patch with build number
621423
, you could search for bundles with this build number, as follows:JBoss A-MQ:karaf@root> osgi:list -s -t 0 | grep -i 630187 [ 6] [Active ] [ ] [ ] [ 10] org.apache.felix.configadmin (1.2.0.redhat-630187)
After applying a rollup patch, you also see the new version and build number in the Welcome banner when you restart the container.
Rolling back a patch
- Invoke the patch:list command to obtain the patch ID,
PatchID
, of the most recently installed patch. - Invoke the patch:rollback command, as follows:
patch:rollback PatchID
In some cases the container will need to restart to roll back the patch. In these cases, the container restarts automatically. Due to the highly dynamic nature of the OSGi runtime, during the restart you might see some occasional errors related to incompatible classes. These are related to OSGi services that have just started or stopped. These errors can be safely ignored.
Adding features to an incrementally patched container
16.5. Patching Standalone Apache ActiveMQ
Abstract
InstallDir/extras
directory. Patching the standalone Apache ActiveMQ is a manual process, requiring you to copy some library files.
Patch files
Apache ActiveMQ install directory
extras/apache-activemq-5.11.0.redhat-630187.zip
file and installed standalone Apache ActiveMQ into the ApacheActiveMQInstall
directory.
How to apply a patch to standalone Apache ActiveMQ
- After determining which patches to apply, download the relevant patches from the Customer Portal, as described in Section 16.2, “Finding the Right Patches to Apply”.
- Stop the ActiveMQ broker, if it is running.
- Make a backup copy of the original standalone Apache ActiveMQ
lib
directory,ApacheActiveMQInstall/lib
- Starting with the first patch file, use an archive utility to open the downloaded patch (
.zip
) file, and extract the patch to a convenient temporary location,ExtractedPatch
. - The patched library files for the standalone Apache ActiveMQ instance are located in the following subdirectory of the patch:
ExtractedPatch/apache-activemq-5.11.0.redhat-630187/lib
Copy the complete contents of this directory to the standalone Apache ActiveMQlib
directory,ApacheActiveMQInstall/lib
. - Delete the older versions of the patched library files in
ApacheActiveMQInstall/lib
. Only one version of each library should be present in the lib directory, and it should be the patched version.For example, if you found two versions of theactivemq-broker
JAR file present in thelib
directory after copying the patch libraries:activemq-broker-5.9.0.redhat-610379.jar activemq-broker-5.9.0.redhat-611423.jar
You would delete the older version,activemq-broker-5.9.0.redhat-610379.jar
. - If you need to install a second patch on top of the first, repeat steps 4, 5, and 6, for the second patch.
- Restart the ActiveMQ broker.
16.6. Patching a Fabric Container with a Rollup Patch
Abstract
Overview
- Distribution of patched artifacts
- Profiles
- Configuration of the underlying container
Root container
patch:*
commands from the console of the root container. If you are planning to distribute patch artifacts through the Maven proxy, it is convenient to choose the root container to be the ensemble container that is currently the master of the Maven proxy cluster (see ???). This would ensure that patch artifacts can immediately be downloaded by other containers in the cluster.
Distribution of patch artifacts
- Through the Maven proxy (default approach)—when you add a rollup patch to your root container (using the
patch:add
command), the patch artifacts are installed into the root container'ssystem/
directory, whose directory structure is laid out like a Maven repository. The root container can then serve up these patch artifacts to remote containers by behaving as a Maven proxy, enabling remote containers to download the required Maven artifacts (this process is managed by the Fabric agent running on each Fabric container). Alternatively, if you have installed the rollup patch to a container that is not hosting the Maven proxy, you can ensure that the patch artifacts are uploaded to the Maven proxy by invoking thepatch:fabric-install
command with the--upload
option.There is a limitation to the Maven proxy approach, however, if the Fabric ensemble consists of multiple containers. In this case, it can happen that the Maven proxy fails over to a different ensemble container (not the original root container). This can result in the patch artifacts suddenly becoming unavailable to other containers in the fabric. If this occurs during the patching procedure, it will cause problems.NoteContainers that are added to an ensemble do not automatically deploy the Maven proxy. To enable the Maven proxy, make sure that thefabric
profile is deployed in the container.For more details, see chapter "Fabric Maven Proxies" in "Fabric Guide". - Through a local repository (recommended approach)—to overcome the limitations of the Maven proxy approach, we recommend that you make the patch artifacts available directly to all of the containers in the Fabric by setting up a local repository on the file system. Assuming that you have a networked file system, all containers will be able to access the patch artifacts directly.For example, you might set up a local repository of patch artifacts, as follows:
- Given a rollup patch file, extract the contents of the
system/
directory from the rollup patch file into therepositories/
subdirectory of a local Maven repository (which could be~/.m2/repositories
or any other location). - Configure the Fabric agent and the Maven proxy to pick up artifacts from the local repository by editing the current version of the
default
profile, as follows:profile-edit --append --pid io.fabric8.agent/org.ops4j.pax.url.mvn.defaultRepositories="file:///PathToRepository" default
ReplacePathToRepository
by the actual location of the local repository on your file system.NoteMake sure that you make the edits to thedefault
profile for all relevant profile versions. If some of your containers are using a non-default profile version, repeat theprofile-edit
commands while specifying the profile version explicitly as the last parameter.
Profiles
default
, fabric
, karaf
, and so on), the patching mechanism attempts to merge your changes with the changes introduced by the patch.
default
profile).
Configuration of the underlying container
etc/
, lib/
, and so on). When a Fabric container is upgraded to a patched version (for example, using the fabric:container-upgrade
command), the container's Fabric agent checks whether the underlying container must be patched. If yes, the Fabric agent triggers the patching mechanism to update the underlying container. Moreover, if certain critical files are updated (for example, lib/karaf.jar
), the container status changes to requires full restart
after the container is upgraded. This status indicates that a full manual restart is required (an automatic restart is not possible in this case).
io.fabric.version in the default profile
io.fabric.version
resource in the default
profile plays a key role in the patching mechanism. This resource defines the version and build of JBoss A-MQ and of all of its main components. When upgrading (or rolling back) a Fabric container to a new version, the Fabric agent checks the version and build of JBoss A-MQ as defined in the io.fabric.version
resource. If the JBoss A-MQ version changes between the original profile version and the upgraded profile version, the Fabric agent knows that an upgrade of the underlying container is required when upgrading to this profile version.
Patching the patch mechanism
- Download the appropriate patch management package. From the JBoss A-MQ 6.3.0 Software Downloads page, select a package named Red Hat JBoss A-MQ 6.3.0 Rollup N on Karaf Update Installer, where N is the number of the particular rollup patch you are about to install.ImportantThe rollup number, N, of the downloaded patch management package must match the rollup number of the rollup patch you are about to install. For some rollup patches, there is no corresponding patch management package, in which case you can skip directly to the instructions for installing the rollup patch.
- Extract the contents of the patch management package,
patch-management-for-amq-630-TargetVersion.zip
, on top of the root container (that is, on top of the Fabric container that will be used to perform the remainder of the patching tasks). Use an archive utility to extract the contents on top of the root container installation, merging the contents of the archivesystem/
andpatches/
directories with the containersystem/
andpatches/
subdirectories.NoteIt does not matter whether the root container is running when you extract these files. - Start the root container, if it is not already running.
- Create a new version, using the
fabric:version-create
command (where we assume that the current profile version is1.0
):JBossFuse:karaf@root> fabric:version-create --parent 1.0 1.0.1 Created version: 1.0.1 as copy of: 1.0
ImportantVersion names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this:1.3 [.description]
. If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax. - Update the
patch
property in theio.fabric8.version
PID in the version1.0.1
of thedefault
profile, by entering the following Karaf console command:profile-edit --pid io.fabric8.version/patch=1.2.0.redhat-630xxx default 1.0.1
Where you must replace1.2.0.redhat-630xxx
with the actual build version of the patch commands you are installing (for example, the build versionxxx
can be taken from the last three digits of theTargetVersion
in the downloaded patch management package file name). - Upgrade the root container to use the new patching mechanism, as follows:
container-upgrade 1.0.1 root
- Likewise, for all other containers in your fabric that need to be patched (SSH, child, and so on), provision them with the new patching mechanism by upgrading them to profile version
1.0.1
. For example:container-upgrade 1.0.1 container1 container2 container3
-
After completing the container-upgrade, if
patch
commands are unavailable or if the console issues a prompt that a container restart is necessary, then restart the upgraded containers to complete the upgrade process.
Applying a rollup patch
- Before applying the rollup patch to your fabric, you must patch the patch mechanism, as described in the section called “Patching the patch mechanism”.
- For every top-level container (that is, any container that is not a child container), perform these steps, one container at a time:
- In the corresponding Karaf installation, remove the
lib/endorsed/org.apache.karaf.exception-2.4.0.redhat-630xxx.jar
file (where the build number,xxx
, depends on the build being patched). - Restart the container.
- Add the patch to the root container's environment using the patch:add command. For example, to add the
patch.zip
patch file:JBossFuse:karaf@root> patch:add file://patch.zip [name] [installed] [description] PatchID false Description
ImportantIf you have decided to use a local repository to distribute the patch artifacts (recommended), set up the local repository now—see the section called “Distribution of patch artifacts”. - Create a new version, using the
fabric:version-create
command:JBossFuse:karaf@root> fabric:version-create 1.1 Created version: 1.1 as copy of: 1.0.1
ImportantVersion names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this:1.3[.description]
. If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax. - Apply the patch to the new version, using the
patch:fabric-install
command. Note that in order to run this command you must provide the credentials,Username
andPassword
, of a user withAdministrator
privileges. For example, to apply thePatchID
patch to version1.1
:patch:fabric-install --username Username --password Password --upload --version 1.1 PatchID
NoteWhen you invoke thepatch:fabric-install
command with the--upload
option, Fabric looks up the ZooKeeper registry to discover the URL of the currently active Maven proxy, and uploads all of the patch artifacts to this URL. Using this approach it is possible to make the patch artifacts available through the Maven proxy, even if the container you are currently logged into is not hosting the Maven proxy. - Delete the old bundle overrides created by the old hot fix patch by modifying the parent profiles of the profile default and removing the old hot fix patch profile as being a parent of the default profile. For example,
JBossFuse:karaf@root> fabric:profile-display --version 1.X default Attributes: parents: acls patch-jboss-fuse-6.2.1.redhat-186-12-r7hf10 JBossFuse:karaf@root> fabric:profile-change-parents --version 1.X default acls
NoteThe parentpatch-jboss-fuse-6.2.1.redhat-186-12-r7hf10
is only visible if a hot fix patch was installed previously. The name of the parent patch is different based on the hot fix patch.The above commands shows that default profile has two parents:- acls - standard and must be present.
- patch-jboss-fuse-6.2.1.redhat-186-12-r7hf10 - a profile that represents hotfix patch.
- Synchronize the patch information across the fabric, to ensure that the profile changes in version
1.1
are propagated to all containers in the fabric (particularly remote SSH containers). Enter the following console command:patch:fabric-synchronize
- Upgrade each existing container in the fabric using the
fabric:container-upgrade
command (but leaving the root container, where you installed the patch, until last). For example, to upgrade a container namedremote
, enter the following command:JBossFuse:karaf@root> fabric:container-upgrade 1.1 remote Upgraded container remote from version 1.0.1 to 1.1
At this point, not only does the Fabric agent download and install the patched bundles into the specified container, but the agent also applies the patch to the underlying container (updating any static files in the container, if necessary). If necessary, the agent will then restart the target container automatically or set the container status torequires full restart
(if an automatic restart is not possible), so that any changes made to the static files are applied to the running container.ImportantIt is recommended that you upgrade only one or two containers to the patched profile version, to ensure that the patch does not introduce any new issues. - If the current status of the upgraded container is
requires full restart
, you must now use one of the standard mechanisms to stop and restart the container manually. In some cases, it will be possible to do this using Fabric commands from the console of the root container.For example, you could stop theremote
container as follows:fabric:container-stop remote
And restart theremote
container as follows:fabric:container-start remote
- Upgrade the root container last (that is, the container that you originally installed the patch on):
fabric:container-upgrade 1.1 root
- (Windows only) If the root container status has changed to
requires full restart
and it is running on a Windows operating system, you must first shut down all of the root container's child containers (if any) before manually restarting the root container.For example, if the root container has three child containers,child1
,child2
, andchild3
, you would first shut them down, as follows:fabric:container-stop child1 child2 child3
You can then shut down the root container with theshutdown
command:shutdown
Rolling back a rollup patch
fabric:container-rollback
command. For example, assuming that 1.0
is an unpatched profile version, you can roll the remote
container back to the unpatched version 1.0
as follows:
fabric:container-rollback 1.0 remote
requires full restart
(if an automatic restart is not possible), so that any changes made to the static files are applied to the running container.
16.7. Patching a Fabric Container with an Incremental Patch
Abstract
Overview
- Distribution of patched artifacts through Maven proxy
- Profiles
Distribution of patched artifacts through Maven proxy
system/
directory, whose directory structure is laid out like a Maven repository. The local container distributes these patch artifacts to remote containers by behaving as a Maven proxy, enabling remote containers to upload bundle JARs as needed (this process is managed by the Fabric agent running on each Fabric container). For more details, see chapter "Fabric Maven Proxies" in "Fabric Guide".
Profiles
- The patch mechanism creates a new profile,
patch-PatchProfileID
, which defines bundle overrides for all of the patched bundles. - The new patch profile,
patch-PatchProfileID
, is inserted as the parent of thedefault
profile (at the base of the entire profile tree). - All of the profiles that inherit from default now use the bundle versions defined by the overrides in
patch-PatchProfileID
. The contents of the existing profiles themselves are not modified in any way.
Is it necessary to patch the underlying container?
fabric:create
command). Always read the patch README
file to find out whether there are any special steps required to install a particular patch. In these cases, however, it is more likely that the patch would be distributed in the form of a rollup patch, which has the capability to patch the underlying container automatically—see Section 16.6, “Patching a Fabric Container with a Rollup Patch”.
Applying an incremental patch
- Before you proceed to install the incremental patch, make sure to read the text of the
README
file that comes with the patch, as there might be additional manual steps required to install a particular incremental patch. - Create a new version, using the
fabric:version-create
command:JBossFuse:karaf@root> fabric:version-create 1.1 Created version: 1.1 as copy of: 1.0
ImportantVersion names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this:1.3 <.description >
.If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax. - Apply the patch to the new version, using the
fabric:patch-apply
command. For example, to apply theactivemq.zip
patch file to version1.1
:JBossFuse:karaf@root> fabric:patch-apply --version 1.1 file:///patches/activemq.zip
- Upgrade a container using the
fabric:container-upgrade
command, specifying which container you want to upgrade. For example, to upgrade thechild1
container, enter the following command:JBossFuse:karaf@root> fabric:container-upgrade 1.1 child1 Upgraded container child1 from version 1.0 to 1.1
ImportantIt is recommended that you upgrade only one or two containers to the patched profile version, to ensure that the patch does not introduce any new issues. Upgrade theroot
container (the one that you applied the patch to, using thefabric:patch-apply
command) last. - You can check that the new patch profile has been created using the
fabric:profile-list
command, as follows:BossFuse:karaf@root> fabric:profile-list --version 1.1 | grep patch default 0 patch-activemq-patch patch-activemq-patch
Where we presume that the patch was applied to profile version 1.1.NoteIf you want to avoid specifying the profile version (with--version
) every time you invoke a profile command, you can change the default profile version using thefabric:version-set-default Version
command.You can also check whether specific JARs are included in the patch, for example:JBossFuse:karaf@root> list | grep -i activemq [ 131] [Active ] [Created ] [ ] [ 50] activemq-osgi (5.9.0.redhat-61037X) [ 139] [Active ] [Created ] [ ] [ 50] activemq-karaf (5.9.0.redhat-61037X) [ 207] [Active ] [ ] [ ] [ 60] activemq-camel (5.9.0.redhat-61037X)
Rolling back an incremental patch
fabric:container-rollback
command. For example, assuming that 1.0
is an unpatched profile version, you can roll the child1
container back to the unpatched version 1.0
as follows:
fabric:container-rollback 1.0 child1
Appendix A. Required JARS
Overview
activemq-all.jar
file on the broker's CLASSPATH
. It contains all of the classes needed by a message broker. This is the default set up for a Red Hat JBoss A-MQ installation.
CLASSPATH
you can add the individual JARs. There are several JARs that are required. In addition, there are a few that are only needed when certain features are used.
Required JARs
CLASSPATH
:
activemq-broker.jar
activemq-client.jar
activeio-core.jar
slf4j-api.jar
JEE JARs
- the
jee.jar
from Oracle - your JEE container's installation
- the Geronimo specs JARs:
geronimo-spec-jms.jar
geronimo-spec-jta.jar
geronimo-spec-j2ee-management.jar
Persistent messaging JARs
CLASSPATH
for the desired persistence store. The JAR names follow the pattern activemq-store-store
. The following message stores are included:
activemq-amq-store.jar
activemq-jdbc-store.jar
activemq-kahadb-store.jar
activemq-leveldb-store.jar
- For KahaDB you will need
kahadb.jar
. - For JDBC you will need the JARs for your database's JDBC driver.
Index
A
- Active, Subscription statistics
- activemq.xml, Editing the configuration template
- administration client
- running, Running the administration client
- amq, Starting in console mode
- AverageEnqueueTime, Destination statistics
B
- BlockedProducerWarningInterval, Destination statistics
- broker
- addConnector, Broker actions
- addNetworkConnector, Broker actions
- addQueue, Broker actions
- addTopic, Broker actions
- createDurableSubscriber, Broker actions
- destroyDurableSubscriber, Broker actions
- disableStatistics, Broker actions
- enableStatistics, Broker actions
- gc, Broker actions
- reloadLog4jProperties, Broker actions
- removeConnector, Broker actions
- removeNetworkConnector, Broker actions
- removeQueue, Broker actions
- removeTopic, Broker actions
- resetStatistics, Broker actions
- start, Broker actions
- stop, Broker actions
- stopGracefully, Broker actions
- terminateJVM, Broker actions
- useJmx, Enabling and disabling
- BrokerId, Broker statistics
- BrokerName, Broker statistics
- BrokerVersion, Broker statistics
C
- client, Running the administration client
- command console
- getting help, Using the broker console
- remote access, Connecting a console to a remote broker
- config shell, Editing the OSGi properties
- config.properties, Overview
- configuration
- persistent identifier, OSGi PIDs
- PID, OSGi PIDs
- template, Configuration templates
- connector
- connectionCount, Connector actions
- disableStatistics, Connector actions
- enableStatistics, Connector actions
- resetStatistics, Connector actions
- start, Connector actions
- stop, Connector actions
- connectorHost, Advanced configuration
- connectorPath, Advanced configuration
- connectorPort, Advanced configuration
- connectors, Activating a connector
- console
- config shell, Editing the OSGi properties
- console mode
- starting, Starting in console mode
- stopping, Stopping the broker from console mode
- ConsumerCount, Destination statistics
- createConnector, Advanced configuration
- createMBeanServer, Advanced configuration
- CursorFull, Destination statistics
- CursorMemoryUsage, Destination statistics
- CursorPercentUsage, Destination statistics
D
- daemon mode
- starting, Starting in daemon mode
- stopping, Stopping a broker running in daemon mode
- DataDirectory, Broker statistics
- deploying
- standalone broker, Deploying a Standalone Broker
- DequeueCount, Destination statistics
- DequeueCounter, Subscription statistics
- DispatchCount, Destination statistics
- DispatchedCounter, Subscription statistics
- DispatchedQueueSize, Subscription statistics
E
- EnqueueCount, Destination statistics
- EnqueueCounter, Subscription statistics
- ExpiredCount, Destination statistics
F
- fabric
- starting a broker, Starting a broker in a fabric
- stopping a broker, Shutting down remote brokers in a fabric
- fabric:container-connect, Connecting a console to a remote broker
- fabric:container-start, Starting a broker in a fabric
- fabric:container-stop, Shutting down remote brokers in a fabric
- fabric:container-upgrade, Applying a rollup patch, Applying an incremental patch
I
- InFlightCount, Destination statistics
- io.fabric8.mq.fabric.server.*, Activating a connector
J
- JAAS
- configuration syntax, Configuring a JAAS realm
- converting to blueprint, Converting standard JAAS login properties to XML
- namespace, Namespace
- jaas:config, Configuring a JAAS realm
- jaas:module, Configuring a JAAS realm
- JBoss Operations Network, Tools
- jconsole, Tools
- JMX
- disabling, Enabling and disabling
- roles, Securing access to JMX
- jmxDomainName, Advanced configuration
L
- logging
- console commands, Viewing the log with the console, Viewing the log with the administration client
- viewing as text, Viewing the log in a text editor
- viewing in an editor, Viewing the log in a text editor
- viewing in the console, Viewing the log with the console
- viewing with the admin client, Viewing the log with the administration client
M
- management console, Tools
- managementContext, Advanced configuration
- connectorHost, Advanced configuration
- connectorPath, Advanced configuration
- connectorPort, Advanced configuration
- createConnector, Advanced configuration
- createMBeanServer, Advanced configuration
- jmxDomainName, Advanced configuration
- rmiServerPort, Advanced configuration
- useMBeanServer, Advanced configuration
- MaxEnqueueTime, Destination statistics
- MaximumPendingMessageLimit, Subscription statistics
- MaxPageSize, Destination statistics
- MemoryLimit, Broker statistics, Destination statistics
- MemoryPercentageUsed, Broker statistics, Destination statistics
- MemoryUsagePortion, Destination statistics
- MessageCountAwaitingAcknowledge, Subscription statistics
- MinEnqueueTime, Destination statistics
N
- network connector
- start, Network connector actions
- stop, Network connector actions
O
- org.apache.karaf.log, Overview
- org.ops4j.pax.logging, Overview
- org.ops4j.pax.logging.DefaultServiceLog.level, Overview
- osgi:shutdown, Using a remote console
P
- patch:add, Applying a patch
- patch:install, Applying a patch
- patch:list, Applying a patch, Rolling back a patch
- patch:rollback, Rolling back a patch
- patch:simulate, Applying a patch
- patching
- fabric
- command console, Applying a rollup patch, Applying an incremental patch
- standalone, Applying a patch
- rollback, Rolling back a patch
- PendingQueueSize, Subscription statistics
- persistent identifier, OSGi PIDs
- PID, OSGi PIDs
- PrefetchSize, Subscription statistics
- ProducerCount, Destination statistics
Q
- queue
- browse, Queue actions
- browseAsTable, Queue actions
- browseMessages, Queue actions
- copyMatchingMessagesTo, Queue actions
- copyMessageTo, Queue actions
- cursorSize, Queue actions
- doesCursorHaveMessagesBuffered, Queue actions
- doesCursorHaveSpace, Queue actions
- getMessage, Queue actions
- moveMatchingMessagesTo, Queue actions
- moveMessageTo, Queue actions
- purge, Queue actions
- removeMatchingMessages, Queue actions
- removeMessage, Queue actions
- resetStatistics, Queue actions
- retryMessage, Queue actions
- sendTextMessage, Queue actions
- QueueSize, Destination statistics
R
- rmiServerPort, Advanced configuration
- roles
- routine tasks, Routine tasks
S
- shell, Starting a basic console
- shutdown, Stopping the broker from console mode
- ssh:ssh, Connecting a console to a remote broker, Using a remote console
- standalone broker
- configuration template, Editing the configuration template
- deploying, Deploying a Standalone Broker
- runtime configuration, Editing the OSGi properties
- start, Starting in daemon mode
- stop, Stopping a broker running in daemon mode
- StoreLimit, Broker statistics
- StorePercentageUsed, Broker statistics
- subscription
- browse, Subscription actions
- browseAsTable, Subscription actions
- cursorSize, Subscription actions
- destory, Subscription actions
- doesCursorHaveMessagesBuffered, Subscription actions
- doesCursorHaveSpace, Subscription actions
- isMatchingQueue, Subscription actions
- isMatchingTopic, Subscription actions
T
- TempLimit, Broker statistics
- TempPercentageUsed, Broker statistics
- tooling, Tools
- topic
- browse, Topic actions
- browseAsTable, Topic actions
- browseMessages, Topic actions
- resetStatistics, Topic actions
- sendTextMessage, Topic actions
- TotalConsumerCount, Broker statistics
- TotalDequeueCount, Broker statistics
- TotalEnqueueCount, Broker statistics
- TotalMessageCount, Broker statistics
- TotalProducerCount, Broker statistics
- transportConnector, Adding a transport connector definition
- transportConnectors, Adding a transport connector definition
U
- useJmx, Enabling and disabling
- useMBeanServer, Advanced configuration
V
- VisualVM, Tools
Legal Notice
Trademark Disclaimer