diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder new file mode 100644 index 000000000..e69de29bb diff --git a/doc/source/conf.py b/doc/source/conf.py index f23b57bbc..6aa28c4a4 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -30,19 +30,29 @@ sys.path.insert(0, os.path.abspath('../../')) sys.path.insert(0, os.path.abspath('../')) sys.path.insert(0, os.path.abspath('./')) + # -- General configuration ---------------------------------------------------- # Add any Sphinx extension module names here, as strings. # They can be extensions coming with Sphinx (named 'sphinx.ext.*') # or your custom ones. -extensions = ['sphinx.ext.autodoc', - 'sphinx.ext.coverage', +extensions = ['sphinx.ext.coverage', 'sphinx.ext.ifconfig', 'sphinx.ext.graphviz', + 'stevedore.sphinxext', + 'oslo_config.sphinxext', + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'oslo_config.sphinxconfiggen', 'openstackdocstheme', ] +config_generator_config_file = [ + ('../../etc/oslo-config-generator/zaqar.conf', + '_static/zaqar'), +] + # autodoc generation is a bit aggressive and a nuisance # when doing heavy text edit cycles. Execute "export SPHINX_DEBUG=1" # in your terminal to disable @@ -153,7 +163,7 @@ html_theme_options = {} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] +html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/doc/source/configuration/configuring.rst b/doc/source/configuration/configuring.rst new file mode 100644 index 000000000..b0b6b3423 --- /dev/null +++ b/doc/source/configuration/configuring.rst @@ -0,0 +1,188 @@ +.. _basic-configuration: + +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``: + +.. code-block:: console + + # pip install tox + $ cd zaqar + $ tox -e genconfig + +Where :samp:`{zaqar}` is your Message service installation directory. + +Then copy Message service configuration sample to the directory ``/etc/zaqar``: + +.. code-block:: console + + # 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. + * ``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``: + +.. code-block:: ini + + [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. + +.. list-table:: Log files used by Messaging services + :widths: 35 35 + :header-rows: 1 + + * - Log filename + - Service that logs to the file + * - ``server.log`` + - Messaging service + diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 000000000..21df02567 --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,18 @@ +.. _configuring: + +=================== +Configuration Guide +=================== + +This section provides a list of all possible options for each +configuration file. Refer to :ref:`basic-configuration` for a +detailed guide in getting started with various option settings. + +Zaqar uses the following configuration files for its various services. + +.. toctree:: + :glob: + :maxdepth: 1 + + * + diff --git a/doc/source/configuration/sample-configuration.rst b/doc/source/configuration/sample-configuration.rst new file mode 100644 index 000000000..8b90e0e26 --- /dev/null +++ b/doc/source/configuration/sample-configuration.rst @@ -0,0 +1,18 @@ +.. _sample-configuration: + +========================== +Zaqar Sample Configuration +========================== + +The following are sample configuration files for all Zaqar services and +utilities. These are generated from code and reflect the current state of code +in the Zaqar repository. + + +Sample configuration for Zaqar API +---------------------------------- + +This sample configuration can also be viewed in `zaqar.conf.sample +<../_static/zaqar.conf.sample>`_. + +.. literalinclude:: ../_static/zaqar.conf.sample diff --git a/doc/source/configuration/zaqar.rst b/doc/source/configuration/zaqar.rst new file mode 100644 index 000000000..c080b7f5e --- /dev/null +++ b/doc/source/configuration/zaqar.rst @@ -0,0 +1,9 @@ +.. _zaqar.conf: + +---------- +zaqar.conf +---------- + +.. show-options:: + :config-file: etc/oslo-config-generator/zaqar.conf + diff --git a/doc/source/index.rst b/doc/source/index.rst index b39dc1901..fdab15bc4 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -92,6 +92,7 @@ Contents user/index admin/index install/index + configuration/index contributor/index .. toctree:: diff --git a/etc/oslo-config-generator/zaqar.conf b/etc/oslo-config-generator/zaqar.conf index a5caa8c04..0123ea44c 100644 --- a/etc/oslo-config-generator/zaqar.conf +++ b/etc/oslo-config-generator/zaqar.conf @@ -1,6 +1,6 @@ [DEFAULT] +wrap_width = 80 output_file = etc/zaqar.conf.sample -namespace = zaqar.bootstrap namespace = zaqar.common.auth namespace = zaqar.common.configs namespace = zaqar.storage.pipeline @@ -10,6 +10,7 @@ namespace = zaqar.storage.redis namespace = zaqar.storage.sqlalchemy namespace = zaqar.storage.swift namespace = zaqar.transport.wsgi +namespace = zaqar.transport.websocket namespace = zaqar.transport.base namespace = zaqar.transport.validation namespace = keystonemiddleware.auth_token