1.1.
Running a Qpid C++ Broker

1.1.1.
Building the
C++ Broker and Client Libraries

The root directory for the C++ distribution is named
qpidc-0.4. The README file in that directory gives
instructions for building the broker and client libraries. In
most cases you will do the following:

[qpidc-0.4]$ ./configure
[qpidc-0.4]$ make

1.1.2.
Running the C++ Broker

Once you have built the broker and client libraries, you can
start the broker from the command line:

[qpidc-0.4]$ src/qpidd

Use the --daemon option to run the broker as a daemon
process:

[qpidc-0.4]$ src/qpidd --daemon

You can stop a running daemon with the --quit option:

[qpidc-0.4]$ src/qpidd --quit

You can see all available options with the --help option

[qpidc-0.4]$ src/qpidd --help

1.1.3.
Most
common questions getting qpidd running

1.1.3.1.
Error
when starting broker: "no data directory"

The C++ Broker requires you to set a data directory or specify
--no-data-dir (see help for more details). The data
directory is used for the journal, so it is important when
reliability counts. Make sure your process has write permission
to the data directory.

The default location is

/lib/var/qpidd

An alternate location can be set with --data-dir

1.1.3.2.
Error
when starting broker: "that process is locked"

Note that when qpidd starts it creates a lock file is data
directory are being used. If you have a un-controlled exit,
please mail
the trace from the core to the dev@qpid.apache.org mailing list.
To clear the lock run

./qpidd -q

It should also be noted that multiple brokers can be run on the
same host. To do so set alternate data directories for each qpidd
instance.

1.1.3.3.
Using a configuration
file

Each option that can be specified on the command line can also be
specified in a configuration file. To see available options, use
--help on the command line:

./qpidd --help

A configuration file uses name/value pairs, one on each line. To
convert a command line option to a configuration file entry:

a.) remove the '--' from the beginning of the option.
b.) place a '=' between the option and the value (use
yes or true to enable options that take no
value when specified on the command line).
c.) place one option per line.

For instance, the --daemon option takes no value, the
--log-to-syslog option takes the values yes or
no. The following configuration file sets these two
options:

daemon=yes
log-to-syslog=yes

1.1.3.4.
Can I use
any Language client with the C++ Broker?

Yes, all the clients work with the C++ broker; it is written in
C+, but uses the AMQP wire protocol. Any broker can be used
with any client that uses the same AMQP version. When running the
C+ broker, it is highly recommended to run AMQP 0-10.

Note that JMS also works with the C++ broker.

1.1.4.
Authentication

1.1.4.1.
Linux

The PLAIN authentication is done on a username+password, which is
stored in the sasldb_path file. Usernames and passwords can be
added to the file using the command:

saslpasswd2 -f /var/lib/qpidd/qpidd.sasldb -u <REALM> <USER>

The REALM is important and should be the same as the
--auth-realm
option to the broker. This lets the broker properly find the user
in
the sasldb file.

Existing user accounts may be listed with:

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

NOTE: The sasldb file must be readable by the user running the
qpidd daemon, and should be readable only by that user.

1.1.4.2.
Windows

On Windows, the users are authenticated against the local
machine. You should add the appropriate users using the standard
Windows tools (Control Panel->User Accounts). To run many of
the examples, you will need to create a user "guest" with
password "guest".

If you cannot or do not want to create new users, you can run
without authentication by specifying the no-auth option to the
broker.

1.1.5.
Slightly more
complex configuration

The easiest way to get a full listing of the broker's options are
to use the --help command, run it locally for the latest set of
options. These options can then be set in the conf file for
convenience (see above)

1.1.6.
Loading extra modules

By default the broker will load all the modules in the module
directory, however it will NOT display options for modules that
are not loaded. So to see the options for extra modules loaded
you need to load the module and then add the help command like
this:

1.1.7. Timestamping Received Messages

The AMQP 0-10 specification defines a timestamp message delivery
property. The timestamp delivery property is a datetime value
that is written to each message that arrives at the broker. See the description of
"message.delivery-properties" in the "Command Classes" section of the AMQP 0-10
specification for more detail.

See the Programming in Apache Qpid documentation for
information regarding how clients may access the timestamp value in received
messages.

By default, this timestamping feature is disabled. To enable timestamping, use the
enable-timestamp broker configuration option. Setting the
enable-timestamp option to 'yes' will enable message timestamping:

./qpidd --enable-timestamp yes

Message timestamping can also be enabled (and disabled) without restarting the broker.
The QMF Broker management object defines two methods for accessing the timestamp
configuration:

1.1.8. Logging Options

The C++ Broker provides a rich set of logging options. To use logging effectively
a user must select a useful set of options to expose the log messages of interest.
This section introduces the logging options and how they are used in practice.

1.1.8.1. Logging Concepts

Log Level

The C++ Broker has a traditional set of log severity levels. The log levels
range from low frequency and high importance critical level
to high frequency and low importance trace level.

Table 1.2. C++ Broker Log Severity Levels

Name

Level

critical

high

error

warning

notice

info

debug

trace

low

Log Category

The C++ Broker groups log messages into categories. The log category
name may then be used to enable and disable groups of related messages
at varying log levels.

Table 1.3. C++ Broker Log Categories

Name

Security

Broker

Management

Protocol

System

HA

Messaging

Store

Network

Test

Client

Model

Unspecified

Generally speaking the log categories are groupings of messages from files
related by
thier placement in the source code directory structure. The
Model category is an exception. Debug log entries
identified by the Model category expose the creation, deletion, and usage
statistics for managed objects in the broker. Log messages in the Model
category are emitted by source files scattered throughout the source tree.

Log Statement Attributes

Every log statement in the C++ Broker has fixed attributes that may be
used in enabling or disabling log messages.

Table 1.4. C++ Broker Log Statement Attributes

Name

Description

Level

Severity level

Category

Category

Function

Namespace-qualified source function name

1.1.8.2. Enabling and Disabling Log Messages

The Qpid C++ Broker has hundreds of log message statements in the source
code. Under typical conditions
most of the messages are deselected and never emitted as actual logs.
However, under some circumstances debug and trace messages must be enabled
to analyze broker behavior. This section discusses how the broker enables
and disables log messages.

At startup the broker processes command line and option file '--log-enable RULE' and
'--log-disable RULE' options using the following rule format:

If PATTERN matches a Category name then the log option applies only
to log messages with the named category. Otherwise, the pattern is stored
as a function name match string.

As the options are procesed the results are aggregated into two pairs of tables.

Table 1.6. C++ Broker Log Enable/Disable Settings Tables

Name

Description

Function Table

A set of vectors of accumulated function name patterns.
There is a separate vector of name patterns for each log level.

Category Table

A simple two dimensional array of boolean values indexed by
[Level][Category] indicating
if all log statements are enabled for the Level and Category pair.

--log-enable statements and --log-disable statements are aggregated into dedicated
Function and Category tables. With this scheme multiple conflicting log enable and
disable commands may be processed in any order yet produce consistent patterns
of enabled broker log statements.

1.1.8.3. Determining if a Log Statement is Enabled

Function Table Lookups are simple string pattern matches where the searchable
text is the domain-name qualified function name from the log statement and the
search pattern is the set of Function Table entries for a given log level.

Category Table Lookups are boolean array queries where the Level and Category
indexes are from the log statement.

Each log statment sends its Level, Category, and FunctionName to the
Logger for evaluation. As a result the log statement is either visible or hidden.

Table 1.7. C++ Broker Log Statement Visibility Determination

Test

Description

Disabled Function

If the statement matches a Disabled Function pattern then the
statement is hidden.

Disabled Category

If the Disabled Category table for this [Level][Category] is true then the
statement is hidden.

Enabled Function

If the statement matches a Enabled Function pattern then the
statement is visible.

Enabled Category

If the Enabled Category table for this [Level][Category] is true then the
statement is visible.

Unreferenced

Log statements that are unreferenced by specific enable rules are by
default hidden.

1.1.8.4. Changing Log Enable/Disable Settings at Run Time

The C++ Broker provides QMF management methods that allow users to query and to set
the log enable and disable settings while the broker is running.

1.1.8.5. Discovering Log Sources

A common condition for a user is being swamped by log messages that are not
interesting for some debug situation. Conversely, a particular log entry
may be of interest all the time but enabling all log levels just to see a
single log entry is too much. How can a user find and specify a pattern
to single out logs of interest?

The easiest way to hide messages it to disable logs at log level and
category combinations. This may not always work since using only these
coarse controls the log messages of interest may also be hidden.
To discover a more precise filter to specify the messages you want
to show or to hide you may temporarily enable the
"--log-function=yes" option.
The following log entries show a typical log message without and
with the log function names enabled:

This log entry is emitted by function qpid::broker::Broker::run
and this is the function name pattern to be used in specific log enable and
disable rules.
For example, this log entry could be disabled with any of the following:

[2] Disables all messages at notice level in qpid:: name space. This is
very broad and disables many log messages.

[3] Disables the category [Broker] and is not specific
to the function. Category names supercede function name fragments in
log option processing

[4] Disables the function.

[5] Disables the function.

Remember that the log filter matching PATTERN strings are matched against the
domain-name qualified function names associated with the log statement
and not against the log message text itself. That is, in the previous example
log filters cannot be set on the log text Broker running