250 lines
14 KiB
XML
250 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<book xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
version="5.0" xml:id="os-zaqar-configRef">
|
|
<title>Messaging and Notifications API v1 Configuration Reference</title>
|
|
<titleabbrev>Messaging and Notifications Configuration Reference</titleabbrev>
|
|
<info>
|
|
<!-- <copyright>
|
|
<year>2013</year>
|
|
<year>2014</year>
|
|
<holder>OpenStack Foundation</holder>
|
|
</copyright> -->
|
|
<releaseinfo>API v1</releaseinfo>
|
|
<productname>Messaging and Notifications</productname>
|
|
<pubdate>2014-08-20</pubdate>
|
|
<!--Note that the <productname> text matches the first few words of the title. The build system splits the title into productname + rest of title on the pdf cover.-->
|
|
<!--If you leave the <pubdate> element empty, the build system inserts today's date automatically. -->
|
|
<legalnotice role="apache2">
|
|
<annotation>
|
|
<remark>Copyright details are filled in by the build
|
|
system.
|
|
</remark>
|
|
</annotation>
|
|
</legalnotice>
|
|
<abstract>
|
|
<para>This document is intended for software developers interested in deploying
|
|
the Messaging and Notifications service.
|
|
</para>
|
|
</abstract>
|
|
<revhistory>
|
|
<revision>
|
|
<date>2014-08-10</date>
|
|
<revdescription>
|
|
<para>Initial document for OpenStack incubation.</para>
|
|
</revdescription>
|
|
</revision>
|
|
</revhistory>
|
|
</info>
|
|
<chapter xml:id="introduction">
|
|
<title>Introduction to the Messaging and Notifications service</title>
|
|
<para>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.</para>
|
|
<para>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.</para>
|
|
<para>Underlying this API is an efficient messaging engine designed with scalability and security in mind.</para>
|
|
<simplesect>
|
|
<title>Key features</title>
|
|
<para>The Messaging and Notifications service provides the following key features:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Firewall-friendly, HTTP-based API with Keystone support</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Multi-tenant queues based on Keystone project IDs</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Support for several common patterns including event broadcasting, task distribution, and point-to-point messaging</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Component-based architecture with support for custom backends and message filters</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Efficient reference implementation with an eye toward low latency and high throughput (dependent on backend)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Highly-available and horizontally scalable</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Components</title>
|
|
<para>The Messaging and Notifications service contains the following components:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Transport backend</emphasis>. 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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Storage backend</emphasis>. 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.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
</chapter>
|
|
<chapter xml:id="configuration">
|
|
<title>Configure the Messaging and Notifications service</title>
|
|
<section xml:id="configuration-overview">
|
|
<title>Overview of zaqar.conf</title>
|
|
<para>The <filename>zaqar.conf</filename>
|
|
configuration file uses an <link xlink:href="https://en.wikipedia.org/wiki/INI_file">INI file format</link>
|
|
as explained in the
|
|
<link xlink:href="http://docs.openstack.org/trunk/config-reference/content/config_format.html">"Configuration file format"</link>
|
|
section of the <link xlink:href="http://docs.openstack.org/trunk/config-reference">OpenStack Configuration Reference</link>.
|
|
</para>
|
|
<para>This file is located in <literal>/etc/zaqar</literal> 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 <literal>tools/config/generate_sample.sh</literal>
|
|
and customize it according to your preferences.</para>
|
|
<para>Example usage of the sample generator script:
|
|
<programlisting>
|
|
$ generate_sample.sh -b /opt/stack/zaqar -p zaqar -o /etc/zaqar
|
|
</programlisting>
|
|
</para>
|
|
<simplesect>
|
|
<title>Sections</title>
|
|
<para>Configuration options are grouped by section. The
|
|
Message Queueing configuration file supports the following sections:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>[DEFAULT]</literal>
|
|
</term>
|
|
<listitem>
|
|
<para>Contains most configuration options. If
|
|
the documentation for a configuration
|
|
option does not specify its section,
|
|
assume that it appears in this
|
|
section.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>[drivers]</literal>
|
|
</term>
|
|
<listitem>
|
|
<para>Select drivers.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>[transport]</literal>
|
|
</term>
|
|
<listitem>
|
|
<para>Configures general transport options.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>[drivers:transport:wsgi]</literal>
|
|
</term>
|
|
<listitem>
|
|
<para>Configures the WSGI driver.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>[storage]</literal>
|
|
</term>
|
|
<listitem>
|
|
<para>Configures general storage options.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>[drivers:storage:mongodb]</literal>
|
|
</term>
|
|
<listitem>
|
|
<para>Configures the MongoDB driver.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<literal>[keystone_authtoken]</literal>
|
|
</term>
|
|
<listitem>
|
|
<para>Configures the Keystone Identity Service endpoint.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</simplesect>
|
|
</section>
|
|
<section xml:id="config-api">
|
|
<title>API options</title>
|
|
<para>The Messaging and Notifications service can be configured by changing the following
|
|
parameters:
|
|
</para>
|
|
<xi:include href="common/tables/zaqar-api.xml"/>
|
|
</section>
|
|
<section xml:id="config-logging">
|
|
<title>Configure logging</title>
|
|
<para>You can use the zaqar.conf file to configure where the Messaging and Notifications service logs events,
|
|
the logging levels and log formats.</para>
|
|
<para>To customize logging for the Messaging and Notifications service, use the following configuration
|
|
settings in the [DEFAULT] section:</para>
|
|
<xi:include href="common/tables/zaqar-logging.xml"/>
|
|
</section>
|
|
<section xml:id="config-drivers">
|
|
<title>Configure drivers</title>
|
|
<para>The transport and storage drivers used by the Messaging and Notifications service
|
|
are determined by the following options:</para>
|
|
<xi:include href="common/tables/zaqar-drivers.xml"/>
|
|
</section>
|
|
<section xml:id="config-storage">
|
|
<title>Configure general storage driver options</title>
|
|
<para>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:</para>
|
|
<xi:include href="common/tables/zaqar-storage.xml"/>
|
|
<xi:include href="common/tables/zaqar-mongodb.xml"/>
|
|
</section>
|
|
<section xml:id="config-transport">
|
|
<title>Configure general transport driver options</title>
|
|
<para>The Messaging and Notifications service uses WSGI as the default transport mechanism.
|
|
The following tables detail the available options:</para>
|
|
<xi:include href="common/tables/zaqar-transport.xml"/>
|
|
<xi:include href="common/tables/zaqar-wsgi.xml"/>
|
|
</section>
|
|
<section xml:id="config-auth">
|
|
<title>Configure authentication and authorization</title>
|
|
<para>All requests to the API may only be performed by an authenticated agent.</para>
|
|
<para>The preferred authentication system is the OpenStack Identity service, code-named Keystone.</para>
|
|
<para>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.</para>
|
|
<para>Multiple endpoints may be returned for Zaqar according to physical locations
|
|
and performance/availability characteristics of different deployments.</para>
|
|
<para>Normally, Keystone middleware provides the <literal>X-Project-Id</literal> header based on the
|
|
auth token submitted by the Zaqar client.</para>
|
|
<para>For this to work, clients must specify a valid auth token in the <literal>X-Auth-Token</literal>
|
|
header for each request to the Zaqar API. The API validates auth tokens against Keystone before
|
|
servicing each request</para>
|
|
<para>If auth is not enabled, clients must provide the <literal>X-Project-Id</literal> header themselves.</para>
|
|
<para>Configure the authentication and authorization strategy through these options:</para>
|
|
<xi:include href="common/tables/zaqar-authentication.xml"/>
|
|
<xi:include href="common/tables/zaqar-auth_token.xml"/>
|
|
</section>
|
|
<section xml:id="config-pooling">
|
|
<title>Configure pooling</title>
|
|
<para>The Messaging and Notifications service supports pooling.</para>
|
|
<para>
|
|
Pooling aims to make Zaqar highly scalable without losing any of its flexibility
|
|
by allowing users to use multiple-backends.
|
|
</para>
|
|
<para>You can enable and configure pooling with the following options:</para>
|
|
<xi:include href="common/tables/zaqar-pooling.xml"/>
|
|
</section>
|
|
</chapter>
|
|
</book> |