-------------------------
AMQP 1.0 Protocol Support
-------------------------

.. currentmodule:: oslo_messaging

============
Introduction
============

This release of oslo.messaging includes an experimental driver that
provides support for version 1.0 of the Advanced Message Queuing
Protocol (AMQP 1.0, ISO/IEC 19464).

The current implementation of this driver is considered
*experimental*.  It is not recommended that this driver be used in
production systems.  Rather, this driver is being provided as a
*technical preview*, in hopes that it will encourage further testing
by the AMQP 1.0 community.

More detail regarding the driver's implementation is available from the `specification`_.

.. _specification: https://git.openstack.org/cgit/openstack/oslo-specs/tree/specs/juno/amqp10-driver-implementation.rst

=============
Prerequisites
=============

This driver uses the Apache QPID `Proton`_ AMQP 1.0 protocol engine.
This engine consists of a platform specific library and a python
binding.  The driver does not directly interface with the engine API,
as the API is a very low-level interface to the AMQP protocol.
Instead, the driver uses the pure python `Pyngus`_ client API, which
is layered on top of the protocol engine.

.. _Proton: http://qpid.apache.org/proton/index.html
.. _Pyngus: https://github.com/kgiusti/pyngus

In order to run the driver the Proton Python bindings, Proton
library, Proton header files, and Pyngus must be installed.

Pyngus is available via `Pypi`__.

.. __: https://pypi.python.org/pypi/pyngus

While the Proton Python bindings are available via `Pypi`__, it
includes a C extension that requires the Proton library and header
files be pre-installed in order for the binding to install properly.
If the target platform's distribution provides a pre-packaged version
of the Proton Python binding (see packages_ below), it is recommended
to use these pre-built packages instead of pulling them from Pypi.

.. __: https://pypi.python.org/pypi/python-qpid-proton

The driver also requires a *broker* that supports version 1.0 of the
AMQP protocol.

The driver has only been tested using `qpidd`_ in a `patched
devstack`_ environment.  The version of qpidd **must** be at least
0.26.  qpidd also uses the Proton engine for its AMQP 1.0 support, so
the Proton library must be installed on the system hosting the qpidd
daemon.

.. _qpidd: http://qpid.apache.org/components/cpp-broker/index.html
.. _patched devstack: https://review.openstack.org/#/c/109118/

At present, RabbitMQ does not work with this driver.  This driver
makes use of the *dynamic* flag on the link Source to automatically
provision a node at the peer.  RabbitMQ's AMQP 1.0 implementation has
yet to implement this feature.

See the `specification`_ for additional information regarding testing
done on the driver.

=============
Configuration
=============

driver
------

It is recommended to start with the default configuration options
supported by the driver.  The remaining configuration steps described
below assume that none of the driver's options have been manually
overridden.

 **Note Well:** The driver currently does **not** support the generic
 *amqp* options used by the existing drivers, such as
 *amqp_durable_queues* or *amqp_auto_delete*.  Support for these are
 TBD.

qpidd
-----

First, verify that the Proton library has been installed and is
imported by the qpidd broker.  This can checked by running::

    $ qpidd --help

and looking for the AMQP 1.0 options in the help text.  If no AMQP 1.0
options are listed, verify that the Proton libraries are installed and
that the version of qpidd is greater than or equal to 0.26.

Second, configure the address patterns used by the driver.  This is
done by adding the following to /etc/qpid/qpidd.conf::

    queue-patterns=exclusive
    queue-patterns=unicast
    topic-patterns=broadcast

These patterns, *exclusive*, *unicast*, and *broadcast* are the
default values used by the driver.  These can be overridden via the
driver configuration options if desired.  If manually overridden,
update the qpidd.conf values to match.

services
--------

The new driver is selected by specifying **amqp** as the transport
name.  For example::

  from oslo import messaging
  from oslo.config import cfg

  amqp_transport = messaging.get_transport(cfg.CONF,
                       "amqp://me:passwd@host:5672")


The new driver can be loaded and used by existing applications by
specifying *amqp* as the RPC backend in the service's configuration
file.  For example, in nova.conf::

    rpc_backend = amqp

.. _packages:

======================
Platforms and Packages
======================

Pyngus is available via Pypi.

Pre-built packages for the Proton library and qpidd are available for
some popular distributions:

RHEL and Fedora
---------------

Packages exist in EPEL for RHEL/Centos 7, and Fedora 19+.
Unfortunately, RHEL/Centos 6 base packages include a very old version
of qpidd that does not support AMQP 1.0.  EPEL's policy does not allow
a newer version of qpidd for RHEL/Centos 6.

The following packages must be installed on the system running the
qpidd daemon:

- qpid-cpp-server (version 0.26+)
- qpid-proton-c

The following packages must be installed on the systems running the
services that use the new driver:

- Proton libraries: qpid-proton-c-devel
- Proton python bindings: python-qpid-proton
- pyngus (via Pypi)

Debian and Ubuntu
-----------------

Packages for the Proton library, headers, and Python bindings are
available in the Debian/Testing repository.  Proton packages are not
yet available in the Ubuntu repository.  The version of qpidd on both
platforms is too old and does not support AMQP 1.0.

Until the proper package version arrive the latest packages can be
pulled from the `Apache Qpid PPA`_ on Launchpad::

    sudo add-apt-repository ppa:qpid/released

.. _Apache Qpid PPA: https://launchpad.net/~qpid/+archive/ubuntu/released

The following packages must be installed on the system running the
qpidd daemon:

- qpidd (version 0.26+)
- libqpid-proton2

The following packages must be installed on the systems running the
services that use the new driver:

- Proton libraries: libqpid-proton2-dev
- Proton python bindings: python-qpid-proton
- pyngus (via Pypi)
