zaqar/doc/source/configuration/configuring.rst

Basic Configuration

The zaqar.conf configuration file is an INI file format.

This file is located in /etc/zaqar. If there is a file zaqar.conf in ~/.zaqar directory, it is used instead of the one in /etc/zaqar directory. When you manually install the Message service, you must generate the zaqar.conf file using the config samples generator located inside Zaqar installation directory and customize it according to your preferences.

To generate the sample configuration file zaqar/etc/zaqar.conf.sample:

# pip install tox
$ cd zaqar
$ tox -e genconfig

Where {zaqar} is your Message service installation directory.

Then copy Message service configuration sample to the directory /etc/zaqar:

# cp etc/zaqar.conf.sample /etc/zaqar/zaqar.conf

For a list of configuration options, see the tables in this guide.

Important

Do not specify quotes around configuration options.

Message API configuration

The Message service has two APIs: the HTTP REST API for WSGI transport driver, and the Websocket API for Websocket transport driver. The Message service can use only one transport driver at the same time.

The functionality and behavior of the APIs are defined by API versions. For example, the Websocket API v2 acts the same as the HTTP REST API v2. For now there are v1, v1.1 and v2 versions of HTTP REST API and only v2 version of Websocket API.

Permission control options in each API version:

• The v1 does not have any permission options.
• The v1.1 has only admin_mode option which controls the global permission to access the pools and flavors functionality.
• The v2 has only:

  • RBAC policy options: policy_default_rule, policy_dirs, policy_file which controls the permissions to access each type of functionality for different types of users.

    Warning

    JSON formatted policy file is deprecated since Zaqar 12.0.0 (Wallaby). This oslopolicy-convert-json-to-yaml__ tool will migrate your existing JSON-formatted policy file to YAML in a backward-compatible way.

  • secret_key option which defines a secret key to use for signing special URLs. These are called pre-signed URLs and give temporary permissions to outsiders of the system.

Authentication and authorization

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.

Identity service authentication

To authenticate, an agent issues an authentication request to an Identity service endpoint. In response to valid credentials, Identity service responds with an authentication 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 Message service according to physical locations and performance/availability characteristics of different deployments.

Normally, Identity service middleware provides the X-Project-Id header based on the authentication token submitted by the Message service client.

For this to work, clients must specify a valid authentication token in the X-Auth-Token header for each request to the Message service API. The API validates authentication tokens against Identity service before servicing each request.

No authentication

If authentication is not enabled, clients must provide the X-Project-Id header themselves.

Notifications options

The notifications feature in the Message service can be enabled by adding zaqar.notification.notifier stage to the message storage layer pipeline. To do it, ensure that zaqar.notification.notifier is added to message_pipeline option in the [storage] section of zaqar.conf:

[storage]
message_pipeline = zaqar.notification.notifier

Pooling options

The Message service supports pooling.

Pooling aims to make the Message service highly scalable without losing any of its flexibility by allowing users to use multiple back ends.

Storage drivers options

Storage back ends

The Message service supports several different storage back ends (storage drivers) for storing management information, messages and their metadata. The recommended storage back end is MongoDB. For information on how to specify the storage back ends.

When the storage back end is chosen, the corresponding back-end options become active. For example, if Redis is chosen as the management storage back end, the options in [drivers:management_store:redis] section become active.

Storage layer pipelines

A pipeline is a set of stages needed to process a request. When a new request comes to the Message service, first it goes through the transport layer pipeline and then through one of the storage layer pipelines depending on the type of operation of each particular request. For example, if the Message service receives a request to make a queue-related operation, the storage layer pipeline will be queue pipeline. The Message service always has the actual storage controller as the final storage layer pipeline stage.

By setting the options in the [storage] section of zaqar.conf, you can add additional stages to these storage layer pipelines:

• Claim pipeline
• Message pipeline with built-in stage available to use:
  • zaqar.notification.notifier - sends notifications to the queue subscribers on each incoming message to the queue, in other words, enables notifications functionality.
• Queue pipeline
• Subscription pipeline

The storage layer pipelines options are empty by default, because additional stages can affect the performance of the Message service. Depending on the stages, the sequence in which the option values are listed does matter or not.

You can add external stages to the storage layer pipelines. For information how to write and add your own external stages, see Writing stages for the storage pipelines tutorial.

Messaging log files

The corresponding log file of each Messaging service is stored in the /var/log/zaqar/ directory of the host on which each service runs.

Log files used by Messaging services

Log filename	Service that logs to the file
server.log	Messaging service