Messaging and Notifications Configuration Reference API v1 Messaging and Notifications 2014-08-20 Copyright details are filled in by the build system. This document is intended for software developers interested in deploying the Messaging and Notifications service. 2014-08-10 Initial document for OpenStack incubation. Zaqar is a multi-tenant, fast, reliable, scalable cloud messaging and notification service. It allows developers to share data between distributed application components performing different tasks, without losing messages or requiring each component to be always available. The service features a ReST API, which developers can use to send messages between various components of their SaaS and mobile applications, by using a variety of communication patterns. Underlying this API is an efficient messaging engine designed with scalability and security in mind. The Messaging and Notifications service provides the following key features: Firewall-friendly, HTTP-based API with Keystone support Multi-tenant queues based on Keystone project IDs Support for several common patterns including event broadcasting, task distribution, and point-to-point messaging Component-based architecture with support for custom backends and message filters Efficient reference implementation with an eye toward low latency and high throughput (dependent on backend) Highly-available and horizontally scalable The Messaging and Notifications service contains the following components: Transport backend. The Messaging and Notifications service requires the selection of a transport specification responsible of the communication between the endpoints. In addition to the base driver implementation, the Messaging and Notifications service also provides the means to add support for other transport mechanisms. The default option is WSGI. Storage backend. The Messaging and Notifications service depends on a storage engine for message persistence. In addition to the base driver implementation, the Messaging and Notifications service also provides the means to add support for other storage solutions. The default storage option is MongoDB.

The zaqar.conf configuration file uses an INI file format as explained in the "Configuration file format" section of the OpenStack Configuration Reference. This file is located in /etc/zaqar within the Zaqar folder. When you manually install the Messaging and Notifications service, you must generate the zaqar.conf file using the config samples generator located in tools/config/generate_sample.sh and customize it according to your preferences. Example usage of the sample generator script: $ generate_sample.sh -b /opt/stack/zaqar -p zaqar -o /etc/zaqar Configuration options are grouped by section. The Message Queueing configuration file supports the following sections: [DEFAULT] Contains most configuration options. If the documentation for a configuration option does not specify its section, assume that it appears in this section. [drivers] Select drivers. [transport] Configures general transport options. [drivers:transport:wsgi] Configures the WSGI driver. [storage] Configures general storage options. [drivers:storage:mongodb] Configures the MongoDB driver. [keystone_authtoken] Configures the Keystone Identity Service endpoint.

The Messaging and Notifications service can be configured by changing the following parameters:

You can use the zaqar.conf file to configure where the Messaging and Notifications service logs events, the logging levels and log formats. To customize logging for the Messaging and Notifications service, use the following configuration settings in the [DEFAULT] section:

The transport and storage drivers used by the Messaging and Notifications service are determined by the following options:

The Messaging and Notifications service supports several different backends for storing messages and their metadata. The recommended storage backend is MongoDB. The following tables detail the available options:

The Messaging and Notifications service uses WSGI as the default transport mechanism. The following tables detail the available options:

All requests to the API may only be performed by an authenticated agent. The preferred authentication system is the OpenStack Identity service, code-named Keystone. To authenticate, an agent issues an authentication request to a Keystone Identity Service endpoint. In response to valid credentials, Keystone responds with an auth token and a service catalog that contains a list of all services and endpoints available for the given token. Multiple endpoints may be returned for Zaqar according to physical locations and performance/availability characteristics of different deployments. Normally, Keystone middleware provides the X-Project-Id header based on the auth token submitted by the Zaqar client. For this to work, clients must specify a valid auth token in the X-Auth-Token header for each request to the Zaqar API. The API validates auth tokens against Keystone before servicing each request If auth is not enabled, clients must provide the X-Project-Id header themselves. Configure the authentication and authorization strategy through these options:

The Messaging and Notifications service supports pooling. Pooling aims to make Zaqar highly scalable without losing any of its flexibility by allowing users to use multiple-backends. You can enable and configure pooling with the following options:

This example shows the default zaqar.conf file: