<?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>
        <section xml:id="config-samples">
            <title>Messaging and Notifications Service configuration files samples</title>
            <para>This example shows the default zaqar.conf file:</para>
            <programlisting language="ini">
                <xi:include parse="text" href="http://git.openstack.org/cgit/openstack/zaqar/plain/etc/zaqar.conf.sample"/>
            </programlisting>
        </section>
    </chapter>
</book>