1. Subscribe your system to the Red Hat MRG Messaging channel in Red Hat Network.
2. Install the MRG Messaging group using the yum command:

   yum groupinstall "MRG Messaging"

1. If you are using RHN classic management for your system, in addition to the base channel for Red Hat Enterprise Linux 6, subscribe your system to the following channel:
   • Additional Services Channels for Red Hat Enterprise Linux 6 / MRG Messaging v.2 (for RHEL-6 Server)
   • Release Channels for Red Hat Enterprise Linux 6 / RHEL Server High Availability
2. Install the MRG Messaging group using the yum command (as root):

   yum groupinstall "Messaging Client Support"
   yum groupinstall "MRG Messaging"
   yum install qpid-cpp-server-cluster

Procedure 2.1. Configuring the firewall for Message Broker traffic

1. Open the /etc/sysconfig/iptables file in a text editor.
2. Add an INPUT rule allowing incoming connections on port 5672 to the file. The new rule must appear before any INPUT rules that REJECT traffic.

   -A INPUT -p tcp -m tcp --dport 5672  -j ACCEPT

3. Save the changes to the /etc/sysconfig/iptables file.
4. Restart the iptables service for the firewall changes to take effect.

   # service iptables restart

• In production scenarios, Red Hat Enterprise Messaging is usually run as a service. To start the broker as a service, with root privileges run the command:

  service qpidd start

  The message broker starts with the message:

  Starting Qpid AMQP daemon:                                 [  OK  ]

• To check the status of a broker running as a service use the service status command. Stop the broker with the command service stop.

  # service qpidd status
  qpidd (pid PID) is running...
  
  # service qpidd stop
  Stopping Qpid AMQP daemon:                                 [  OK  ]
  

• Run the following command as root:

  chkconfig qpidd on

1. Select two available ports, for example 5555 and 5556.
2. Start each new broker, using the --data-dir command to specify a new data directory for each:

   $ qpidd -p 5555 --data-dir /tmp/qpid/store/1

   $ qpidd -p 5556 --data-dir /tmp/qpid/store/2

Procedure 7.1. Configure Infiniband on the Messaging Server

• Allocate lockable memory for Infiniband

  Edit /etc/security/limits.conf to allocate lockable memory for Infiniband.
  For example, if the user running the server is qpidd, and you wish to support 64 connections (64*8192=524288), add these entries:

  qpidd soft memlock 524288
  qpidd hard memlock 524288
  

Procedure 7.2. Configure Infiniband on a Messaging Client

• Allocate lockable memory for Infiniband

  Edit /etc/security/limits.conf to allocate lockable memory.
  To set a limit for all users, for example supporting 16 connections (16*8192=32768), add this entry:

  * soft memlock 32768
  

  If you want to set a limit for a particular user, use the UID for that user when setting the limits:

  andrew soft memlock 32768
  

Procedure 9.1. Configure SASL using a Local Password File

1. Add new users to the database by using the saslpasswd2 command. The User ID for authentication and ACL authorization uses the form user-id@domain.
   Ensure that the correct realm has been set for the broker. This can be done by editing the configuration file or using the -u option. The default realm for the broker is QPID.

   # saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u QPID new_user_name

2. Existing user accounts can be listed by using the -f option:

   # sasldblistusers2 -f /var/lib/qpidd/qpidd.sasldb
   

   Note

   The user database at /var/lib/qpidd/qpidd.sasldb is readable only by the qpidd user. If you start the broker from a user other than the qpidd user, you will need to either modify the configuration file, or turn authentication off.

   Note also that this file must be readable by the qpidd user. If you delete and recreate this file, make sure the qpidd user has read permissions, or authentication attempts will fail.
3. To switch authentication on or off, use the auth yes|no option when you start the broker:

   # /usr/sbin/qpidd --auth yes
   
   # /usr/sbin/qpidd --auth no
   

   You can also set authentication to be on or off by adding the appropriate line to to the /etc/qpidd.conf configuration file:

   auth=no
   
   auth=yes
   

   The SASL configuration file is in /etc/sasl2/qpidd.conf for Red Hat Enterprise Linux.

1. The ACL module is loaded by default. You can check that it is loaded by running the qpidd --help command and checking the output for ACL options:

   $ qpidd --help
   ...[output truncated]...
   ACL Options:
   --acl-file FILE (policy.acl)  The policy file to load from, loaded from data dir
   --connection-limit-per-user N (0)  The maximum number of connections allowed per user. 0 implies no limit.
   --connection-limit-per-ip N (0)    The maximum number of connections allowed per host IP address. 0 implies no limit.
   

2. To start using the ACL, specify the path and filename using the --acl-file command. The filename should have a .acl extension:

   $ qpidd --acl-file ./aclfilename.acl

3. Optionally, you can limit the number of active connections per user with the --connection-limit-per-user and --connection-limit-per-ip commands. These limits can only be enforced if the --acl-file command is specified.
4. You can now view the file with the cat command and edit it in your preferred text editor. If the path and filename is not found, qpidd will fail to start.

1. Install the Kerberos workstation software and Cyrus SASL GSSAPI on each machine that runs a qpidd broker or a qpidd messaging client:

   $ sudo yum install cyrus-sasl-gssapi krb5-workstation
   

2. Change the mech_list line in /etc/sasl2/qpidd.conf to:

   mech_list: GSSAPI

3. Add the following lines to /etc/qpidd.conf:

   auth=yes
   realm=QPID

4. Register the Qpid broker in the Kerberos database.
   Traditionally, a Kerberos principal is divided into three parts: the primary, the instance, and the realm. A typical Kerberos V5 has the format primary/instance@REALM. For a broker, the primary is qpidd, the instance is the fully qualified domain name, and the REALM is the Kerberos domain realm. By default, this realm is QPID, but a different realm can be specified in qpid.conf per the following example.

   realm=EXAMPLE.COM
   

   For instance, if the fully qualified domain name is dublduck.example.com and the Kerberos domain realm is EXAMPLE.COM, then the principal name is qpidd/dublduck.example.com@EXAMPLE.COM.

   FDQN=`hostname --fqdn`
   REALM="EXAMPLE.COM"
   kadmin -r $REALM  -q "addprinc -randkey -clearpolicy qpidd/$FQDN"
   

   Now create a Kerberos keytab file for the broker. The broker must have read access to the keytab file. The following script creates a keytab file and allows the broker read access:

   QPIDD_GROUP="qpidd"
   kadmin -r $REALM  -q "ktadd -k /etc/qpidd.keytab qpidd/$FQDN@$REALM"
   chmod g+r /etc/qpidd.keytab
   chgrp $QPIDD_GROUP /etc/qpidd.keytab
   

   The default location for the keytab file is /etc/krb5.keytab. If a different keytab file is used, the KRB5_KTNAME environment variable must contain the name of the file as the following example shows.

   export KRB5_KTNAME=/etc/qpidd.keytab
   

   If this is correctly configured, you can now enable Kerberos support on the broker by setting the auth and realm options in /etc/qpidd.conf:

   CDATA[# /etc/qpidd.conf
   auth=yes
   realm=EXAMPLE.COM

   Restart the broker to activate these settings.
5. Make sure that each Qpid user is registered in the Kerberos database, and that Kerberos is correctly configured on the client machine. The Qpid user is the account from which a Qpid messaging client is run. If it is correctly configured, the following command should succeed:

   $ kinit user@REALM.COM

6. Additional configuration for Java JMS clients

   Java JMS clients require a few additional steps.
   1. The Java JVM must be run with the following arguments:

      -Djavax.security.auth.useSubjectCredsOnly=false

      Forces the SASL GSSAPI client to obtain the Kerberos credentials explicitly instead of obtaining from the "subject" that owns the current thread.

      -Djava.security.auth.login.config=myjas.conf

      Specifies the jass configuration file. Here is a sample JASS configuration file:

      com.sun.security.jgss.initiate {
          com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
      };
      

      -Dsun.security.krb5.debug=true

      Enables detailed debug info for troubleshooting

   2. The client Connection URL must specify the following Kerberos-specific broker properties:
      • sasl_mechs must be set to GSSAPI.
      • sasl_protocol must be set to the principal for the qpidd broker, e.g. qpidd/
      • sasl_server must be set to the host for the SASL server, e.g. sasl.com.
      Here is a sample connection URL for a Kerberos connection:

      amqp://guest@clientid/testpath?brokerlist='tcp://localhost:5672?sasl_mechs='GSSAPI'&sasl_protocol='qpidd'&sasl_server='<server-host-name>''
      

1. You will need a certificate that has been signed by a Certification Authority (CA). This certificate will also need to be trusted by your client. If you require client authentication in addition to server authentication, the clients certificate will also need to be signed by a CA and trusted by the broker.
   In the broker, SSL is provided through the ssl.so module. This module is installed and loaded by default in MRG Messaging. To enable the module, you need to specify the location of the database containing the certificate and key to use. This is done using the ssl-cert-db option.
   The certificate database is created and managed by the Mozilla Network Security Services (NSS) certutil tool. Information on this utility can be found on the Mozilla website, including tutorials on setting up and testing SSL connections. The certificate database will generally be password protected. The safest way to specify the password is to place it in a protected file, use the password file when creating the database, and specify the password file with the ssl-cert-password-file option when starting the broker.
   The following script shows how to create a certificate database using certutil:

   mkdir ${CERT_DIR}
   certutil -N -d ${CERT_DIR} -f ${CERT_PW_FILE}
   certutil -S -d ${CERT_DIR} -n ${NICKNAME} -s "CN=${NICKNAME}" -t "CT,," -x -f ${CERT_PW_FILE} -z /usr/bin/certutil
   

   When starting the broker, set ssl-cert-password-file to the value of ${CERT_PW_FILE}, set ssl-cert-db to the value of ${CERT_DIR}, and set ssl-cert-name to the value of ${NICKNAME}.
2. The following SSL options can be used when starting the broker:

   --ssl-use-export-policy

   Use NSS export policy. When this option is specified, the server will conform with US export restrictions on encryption using the NSS export policy. When it is not specified, the server will use the domestic policy. Refer to the Mozilla SSL Export Policy Functions documentation for more details.

   --ssl-cert-password-file PATH

   Required. Plain-text file containing password to use for accessing certificate database.

   --ssl-cert-db PATH

   Required. Path to directory containing certificate database.

   --ssl-cert-name NAME

   Name of the certificate to use. Default is localhost.localdomain.

   --ssl-port NUMBER

   Port on which to listen for SSL connections. If no port is specified, port 5671 is used.

   If the SSL port chosen is the same as the port for non-SSL connections (i.e. if the --ssl-port and --port options are the same), both SSL encrypted and unencrypted connections can be established to the same port. However in this configuration there is no support for IPv6.

   --ssl-require-client-authentication

   Require SSL client authentication (i.e. verification of a client certificate) during the SSL handshake. This occurs before SASL authentication, and is independent of SASL.

   This option enables the EXTERNAL SASL mechanism for SSL connections. If the client chooses the EXTERNAL mechanism, the client's identity is taken from the validated SSL certificate, using the CN, and appending any DC's to create the domain. For instance, if the certificate contains the properties CN=bob, DC=acme, DC=com, the client's identity is bob@acme.com.

   If the client chooses a different SASL mechanism, the identity take from the client certificate will be replaced by that negotiated during the SASL handshake.

   --ssl-sasl-no-dict

   Do not accept SASL mechanisms that can be compromised by dictionary attacks. This prevents a weaker mechanism being selected instead of EXTERNAL, which is not vulnerable to dictionary attacks.

   --require-encryption

   This will cause qpidd to only accept encrypted connections. This means only clients with EXTERNAL SASL on the SSL-port, or with GSSAPI on the TCP port.

1. Start qpid-tool:

   $ qpid-tool admin/mysecretpassword@mybroker:5672
   Management Tool for QPID
   qpid:

2. Check the ACL list to obtain the object ID:

   qpid: list acl
   Object Summary:
       ID   Created   Destroyed  Index
       =================================
       103  12:57:41  -          116

3. Optionally, you can examine the ACL:

   qpid: show 103
   Object of type: org.apache.qpid.acl:acl:_data(23510fc1-dc51-a952-39c2-e18475c1677e)
       Attribute              103
       =================================================
       brokerRef              116
       policyFile             /tmp/reload.acl
       enforcingAcl           True
       transferAcl            False
       lastAclLoad            Tue Oct 30 12:57:41 2012
       maxConnectionsPerIp    0
       maxConnectionsPerUser  0
       maxQueuesPerUser       0
       aclDenyCount           0
       connectionDenyCount    0
       queueQuotaDenyCount    0

4. To reload the ACL, call the reload method of the ACL object:

   qpid: call 103 reloadACLFile
   qpid: OK (0) - {}

1. The user id in the ACL file is of the form <user-id>@<domain>. The Domain is configured via the SASL configuration for the broker, and the domain/realm for qpidd is set using --realm and default to 'QPID'.
2. Each line in an ACL file grants or denies specific rights to a user.
   1. If the last line in an ACL file is acl deny all all, the ACL uses deny mode, and only those rights that are explicitly allowed are granted:

      acl allow user@QPID all all
      acl deny all all
      

      On this server, deny mode is the default. user@QPID can perform any action, but nobody else can. In deny mode, denying rights to an action is redundant and has no effect.
   2. If the last line in an ACL file is acl allow all all, the ACL uses allow mode, and all rights are granted except those that are explicitly denied.

      acl deny user@QPID all all
      acl allow all all
      

      On this server, allow mode is the default. The ACL allows everyone else to perform any action, but denies user@QPID all permissions. In allow mode, allowing rights to an action is redundant and has no effect.
3. ACL processing ends when one of the following lines is encountered:

   acl allow all all
   

   acl deny all all
   

   Any lines after one of these statements will be ignored:

   acl allow all all
   acl deny user@QPID all all # This line is ignored !!!
   

4. ACL syntax allows fine-grained access rights for specific actions:

   acl allow carlt@QPID create exchange name=carl.*
   acl allow fred@QPID create all
   acl allow all consume queue
   acl allow all bind exchange
   acl deny all all
   

5. An ACL file can define user groups, and assign permissions to them:

   group admin ted@QPID martin@QPID
   acl allow admin create all
   acl deny all all
   

1. To create and delete queue routes, use the following syntax:

   qpid-route [OPTIONS] queue add <dest-broker> <src-broker> <dest-exchange> <src-queue>
   qpid-route [OPTIONS] queue del <dest-broker> <src-broker> <dest-exchange> <src-queue>
   

2. For example, use the following command to create a queue route that routes all messages from the queue named public on the source broker localhost:10002 to the amq.fanout exchange on the destination broker localhost:10001:

   $ qpid-route queue add localhost:10001 localhost:10002 amq.fanout public
   

3. Optionally, specify the -d option to persist the queue route. The queue route will be restored if one or both of the brokers is restarted:

   $ qpid-route -d queue add localhost:10001 localhost:10002 amq.fanout public
   

4. The del command takes the same arguments as the add command. Use the following command to delete the queue route described above:

   $ qpid-route queue del localhost:10001 localhost:10002 amq.fanout public
   

1. To create and delete exchange routes, use the following syntax:

   qpid-route [OPTIONS] route add <dest-broker> <src-broker> <exchange> <routing-key> 
   qpid-route [OPTIONS] route del <dest-broker> <src-broker> <exchange> <routing-key>
   qpid-route [OPTIONS] flush [<broker>]
   

2. For example, use the following command to create an exchange route that routes messages that match the binding key global.# from the amq.topic exchange on the source broker localhost:10002 to the amq.topic exchange on the destination broker localhost:10001:

   $ qpid-route route add localhost:10001 localhost:10002 amq.topic global.#
   

3. In many applications, messages published to the destination exchange must also be routed to the source exchange. Create a second exchange route, reversing the roles of the two exchanges:

   $ qpid-route route add localhost:10002 localhost:10001 amq.topic global.#
   

4. Specify the -d option to persist the exchange route. The exchange route will be restored if one or both of the brokers is restarted:

   $ qpid-route -d route add localhost:10001 localhost:10002 amq.fanout public
   

5. The del command takes the same arguments as the add command. Use the following command to delete the first exchange route described above:

   $ qpid-route route del localhost:10001 localhost:10002 amq.topic global.#
   

• Use the flush command to delete all routes for a given broker:

  qpid-route [OPTIONS] route flush [<broker>]
  

  For example, use the following command to delete all routes for the broker localhost:10001:

  $ qpid-route route flush localhost:10001
  

1. To create and delete dynamic exchange routes, use the following syntax:

   qpid-route [OPTIONS] dynamic add <dest-broker> <src-broker> <exchange> 
   qpid-route [OPTIONS] dynamic del <dest-broker> <src-broker> <exchange>
   

2. Create a new topic exchange on each of two brokers:

   $ qpid-config -a localhost:10003 add exchange topic fed.topic
   $ qpid-config -a localhost:10004 add exchange topic fed.topic
   

3. Create a dynamic exchange route that routes messages from the fed.topic exchange on the source broker localhost:10004 to the fed.topic exchange on the destination broker localhost:10003:

   $ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic
   

   Internally, this creates a private autodelete queue on the source broker, and binds that queue to the fed.topic exchange on the source broker, using each binding associated with the fed.topic exchange on the destination broker.
4. In many applications, messages published to the destination exchange must also be routed to the source exchange. Create a second dynamic exchange route, reversing the roles of the two exchanges:

   $ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic
   

5. Specify the -d option to persist the exchange route. The exchange route will be restored if one or both of the brokers is restarted:

   $ qpid-route -d dynamic add localhost:10004 localhost:10003 fed.topic
   

   When an exchange route is durable, the private queue used to store messages for the route on the source exchange is also durable. If the connection between the brokers is lost, messages for the destination exchange continue to accumulate until it can be restored.
6. The del command takes the same arguments as the add command. Delete the first exchange route described above:

   $ qpid-route dynamic del localhost:10004 localhost:10003 fed.topic
   

   Internally, this deletes the bindings on the source exchange for the private queues associated with the message route.

Procedure 11.1. Using the route list command

1. Create the following two routes:

   $ qpid-route dynamic add localhost:10003 localhost:10004 fed.topic
   $ qpid-route dynamic add localhost:10004 localhost:10003 fed.topic
   

2. Use the route list command to show the routes associated with the broker:

   $ qpid-route route list localhost:10003
   localhost:10003 localhost:10004 fed.topic <dynamic>
   

   Note that this shows only one of the two routes created, namely the route for which localhost:10003 is a destination.
3. To view the route for which localhost:10004 is a destination, run route list on localhost:10004:

   $ qpid-route route list localhost:10004
   localhost:10004 localhost:10003 fed.topic <dynamic>
   

Procedure 11.2. Using the route map command

1. The route map command shows all routes associated with a broker, and recursively displays all routes for brokers involved in federation relationships with the given broker. For example, run the route map command for the two brokers configured above:

   $ qpid-route route map localhost:10003
   
   Finding Linked Brokers:
       localhost:10003... Ok
       localhost:10004... Ok
   
   Dynamic Routes:
   
     Exchange fed.topic:
       localhost:10004 <=> localhost:10003
   
   Static Routes:
     none found
   

   Note that the two dynamic exchange links are displayed as though they were one bidirectional link. The route map command is helpful for larger, more complex networks.
2. Configure a network with 16 dynamic exchange routes:

   qpid-route dynamic add localhost:10001 localhost:10002 fed.topic
   qpid-route dynamic add localhost:10002 localhost:10001 fed.topic
   
   qpid-route dynamic add localhost:10003 localhost:10002 fed.topic
   qpid-route dynamic add localhost:10002 localhost:10003 fed.topic
   
   qpid-route dynamic add localhost:10004 localhost:10002 fed.topic
   qpid-route dynamic add localhost:10002 localhost:10004 fed.topic
   
   qpid-route dynamic add localhost:10002 localhost:10005 fed.topic
   qpid-route dynamic add localhost:10005 localhost:10002 fed.topic
   
   qpid-route dynamic add localhost:10005 localhost:10006 fed.topic
   qpid-route dynamic add localhost:10006 localhost:10005 fed.topic
   
   qpid-route dynamic add localhost:10006 localhost:10007 fed.topic
   qpid-route dynamic add localhost:10007 localhost:10006 fed.topic
   
   qpid-route dynamic add localhost:10006 localhost:10008 fed.topic
   qpid-route dynamic add localhost:10008 localhost:10006 fed.topic
   

3. Use the route map command starting with any one broker to see the entire network:

   $ qpid-route route map localhost:10001
   
   Finding Linked Brokers:
       localhost:10001... Ok
       localhost:10002... Ok
       localhost:10003... Ok
       localhost:10004... Ok
       localhost:10005... Ok
       localhost:10006... Ok
       localhost:10007... Ok
       localhost:10008... Ok
   
   Dynamic Routes:
   
     Exchange fed.topic:
       localhost:10002 <=> localhost:10001
       localhost:10003 <=> localhost:10002
       localhost:10004 <=> localhost:10002
       localhost:10005 <=> localhost:10002
       localhost:10006 <=> localhost:10005
       localhost:10007 <=> localhost:10006
       localhost:10008 <=> localhost:10006
   
   Static Routes:
     none found