Chapter 2. How Tos

Table of Contents

2.1. Add New Users
2.1.1. Available Password file formats
2.1.2. Dynamic changes to password files.
2.1.3. How password files and PrincipalDatabases relate to authentication mechanisms
2.2. Configuring ACLs
2.2.1. Enabling ACLs
2.2.2. Writing .acl files
2.2.3. Syntax
2.2.4. Worked Examples
2.3. Configure Java Qpid to use a SSL connection.
2.3.1. Using SSL connection with Qpid Java.
2.3.2. Setup
2.3.3. Performing the connection.
2.4. Configure Log4j CompositeRolling Appender
2.4.1. How to configure the CompositeRolling log4j Appender
2.5. Configure the Broker via config.xml
2.5.1. Broker config.xml Overview
2.5.2. Qpid Version
2.6. Configure the Virtual Hosts via virtualhosts.xml
2.6.1. virtualhosts.xml Overview
2.7. Debug using log4j
2.7.1. Debugging with log4j configurations
2.8. How to Tune M3 Java Broker Performance
2.8.1. Problem Statement
2.8.2. Successful Tuning Options
2.8.3. Next Steps
2.9. Qpid Java Build How To
2.9.1. Build Instructions - General
2.9.2. Build Instructions - Trunk
2.10. Use Priority Queues
2.10.1. General Information
2.10.2. Defining Priority Queues
2.10.3. Client configuration/messaging model for priority queues
2.11. Slow Consumer Disconnect - User Guide
2.11.1. Introduction
2.11.2. What can it do?
2.11.3. Frequency of SCD Checking
2.11.4. Client Exceptions
2.11.5. Disconnection Thresholds
2.11.6. Important Points To Note

2.1.  Add New Users

The Qpid Java Broker has a single reference source (???) that defines all the users in the system.

To add a new user to the broker the password file must be updated. The details about adding entries and when these updates take effect are dependent on the file format each of which are described below.

2.1.1.  Available Password file formats

There are currently two different file formats available for use depending on the PrincipalDatabase that is desired. In all cases the clients need not be aware of the type of PrincipalDatabase in use they only need support the SASL mechanisms they provide.

2.1.1.1.  Plain

The plain file has the following format:

# Plain password authentication file.
# default name : passwd
# Format <username>:<password>
#e.g.
martin:password

As the contents of the file are plain text and the password is taken to be everything to the right of the ':'(colon). The password, therefore, cannot contain a ':' colon, but this can be used to delimit the password.

Lines starting with a '#' are treated as comments.

2.1.1.2.  Where is the password file for my broker ?

The location of the password file in use for your broker is as configured in your config.xml file.

<principal-databases>
            <principal-database>
                <name>passwordfile</name>
                <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class>
                <attributes>
                    <attribute>
                        <name>passwordFile</name>
                        <value>${conf}/passwd</value>
                    </attribute>
                </attributes>
            </principal-database>
        </principal-databases>

So in the example config.xml file this password file lives in the directory specified as the conf directory (at the top of your config.xml file).

If you wish to use Base64 encoding for your password file, then in the <class> element above you should specify org.apache.qpid.server.security.auth.database.Base64MD5PasswordFilePrincipalDatabase

The default is:

 <conf>${prefix}/etc</conf>

2.1.1.3.  Base64MD5 Password File Format

This format can be used to ensure that SAs cannot read the plain text password values from your password file on disk.

The Base64MD5 file uses the following format:

# Base64MD5 password authentication file
# default name : qpid.passwd
# Format <username>:<Base64 Encoded MD5 hash of the users password>
#e.g.
martin:X03MO1qnZdYdgyfeuILPmQ==

As with the Plain format the line is delimited by a ':'(colon). The password field contains the MD5 Hash of the users password encoded in Base64.

This file is read on broker start-up and is not re-read.

2.1.1.4.  How can I update a Base64MD5 password file ?

To update the file there are two options:

  1. Edit the file by hand using the qpid-passwd tool that will generate the required lines. The output from the tool is the text that needs to be copied in to your active password file. This tool is located in the broker bin directory. Eventually it is planned for this tool to emulate the functionality of ??? for qpid passwd files. NOTE: For the changes to be seen by the broker you must either restart the broker or reload the data with the management tools (see Section 3.1.1.5, “ Qpid JMX Management Console User Guide ”)

  2. Use the management tools to create a new user. The changes will be made by the broker to the password file and the new user will be immediately available to the system (see Section 3.1.1.5, “ Qpid JMX Management Console User Guide ”).

2.1.2.  Dynamic changes to password files.

The Plain password file and the Base64MD5 format file are both only read once on start up.

To make changes dynamically there are two options, both require administrator access via the Management Console (see Section 3.1.1.5, “ Qpid JMX Management Console User Guide ”)

  1. You can replace the file and use the console to reload its contents.

  2. The management console provides an interface to create, delete and amend the users. These changes are written back to the active password file.

2.1.3.  How password files and PrincipalDatabases relate to authentication mechanisms

For each type of password file a PrincipalDatabase exists that parses the contents. These PrincipalDatabases load various SASL mechanism based on their supportability. e.g. the Base64MD5 file format can't support Plain authentication as the plain password is not available. Any client connecting need only be concerned about the SASL module they support and not the type of PrincipalDatabase. So I client that understands CRAM-MD5 will work correctly with a Plain and Base64MD5 PrincipalDatabase.

Table 2.1. File Format and Principal Database

FileFormat/PrincipalDatabase SASL
Plain AMQPLAIN PLAIN CRAM-MD5
Base64MD5 CRAM-MD5 CRAM-MD5-HASHED

For details of SASL support see ???