stackforge/libra
Code Issues Proposed changes

[DOCS] Update worker and common docs

Browse Source 
Updates the common configuration section to reflect the latest
change to switch to oslo config library. Also updates the worker
configuration section.

Change-Id: I9a411cbc04bfdd618d36c172a134f9b341950a46
This commit is contained in:
David Shrewsbury
2013-11-21 16:00:13 -05:00
parent 248323d872
commit 38e31a4087
3 changed files with 107 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
doc/config.rst
View File

@@ -7,114 +7,98 @@ Configuration
Configuration of Services
=========================
Options can be specified either via the command line, or with a configuration
file, or both. Options given on the command line will override any options
set in the configuration file.
Configuration File Format
-------------------------
The configuration file is in `INI format
<http://en.wikipedia.org/wiki/INI_file>`_. Options are expressed in one of
two forms::
Libra uses the `Oslo configuration library <https://wiki.openstack.org/wiki/Oslo/Config>`_
so its format is similar to other OpenStack programs.
key = value
key : value
DEFAULT Section
^^^^^^^^^^^^^^^
Some key points to note:
* Boolean options should be given either a value of `true` or `false`.
* Some options can contain multiple values (see 'server' option in the
``[worker]`` section).
* If an option has both a short-form and long-form (e.g., ``-d`` and
``--debug``), then you should use the long-form name in the configuration
file.
* Unknown sections are ignored. This allows all Libra utilities to share
the same configuration file, if desired.
Global Section
^^^^^^^^^^^^^^
The ``[global]`` section contains options common to the various Libra
utilities (worker, mgm, etc). This section is read before any other
section, so values may be overridden by the other sections:
The ``[DEFAULT]`` section contains generic options common to the various
Libra utilities (worker, mgm, etc).
.. code-block:: ini
[global]
verbose = true
nodaemon = false
syslog = true
syslog-socket = /dev/log
syslog-facility = local7
debug = true
pid = /var/run/libra_tool.pid
logfile = /var/log/libra/libra_tool.log
[DEFAULT]
daemon = true
user = libra
group = libra
The options listed above are common to all libra applications so can either
be used in the ``[global]`` section or in an application's individual
section.
Options supported in this section:
Common Command Line Options
---------------------------
These command line options are common to all libra utilities.
.. option:: daemon
.. option:: -c <FILE>, --config <FILE>
Run as a daemon. Default is 'true'.
Load options from the specified configuration file. Command line
options will take precedence over any options specified in the
configuration file.
.. option:: -d, --debug
Enable debugging output.
.. option:: --group <GROUP>
Specifies the group for the process when run in daemon mode.
.. option:: -h, --help
Show the help message and quit.
.. option:: -l <FILE>, --logfile <FILE>
Name of the log file. When not in daemon mode, the logs go by
default to STDOUT. As a daemon, the default log file is
*/var/run/libra/libra_name.log*, where "name" is the utility's
short name (like "api", "mgm", or "worker").
.. option:: -n, --nodaemon
Do not run as a daemon. This option is useful for debugging purposes
only as the worker is intended to be run as a daemon normally.
.. option:: -p <PID>, --pid <PID>
Name of the PID file to use. The default is
*/var/run/libra/libra_name.pid*, where "name" is the utility's
short name (like "api", "mgm", or "worker").
.. option:: --syslog
Send log events to syslog.
.. option:: --syslog-socket
Socket to use for the syslog connection. Default is */dev/log*.
.. option:: --syslog-facility
Syslog logging facility. Default is *LOCAL7*.
.. option:: --user <USER>
.. option:: user
Specifies the user for the process when in daemon mode. Default is the
current user.
.. option:: -v, --verbose
.. option:: group
Enable verbose output. Normally, only errors are logged. This enables
additional logging, but not as much as the :option:`-d` option.
Specifies the group for the process when run in daemon mode.
Gearman Section
^^^^^^^^^^^^^^^
The ``[gearman]`` section contains options specific to connecting to
a Gearman job server. All of the Libra utilities will read this section
since each connects to Gearman.
In order to support SSL connections, it is required that all three SSL
related options be supplied. Also, the user owning the process must be
able to read all SSL files.
.. code-block:: ini
[gearman]
servers = 10.0.0.1:4730, 10.0.0.2:4730
poll = 1
ssl_ca = /etc/ssl/gearman.ca
ssl_cert = /etc/ssl/gearman.cert
ssl_key = /etc/ssl/gearman.key
Options supported in this section:
.. option:: keepalive
Enable TCP KEEPALIVE pings. Default is 'false'.
.. option:: keepcnt
Max KEEPALIVE probes to send before killing connection.
.. option:: keepidle
Seconds of idle time before sending KEEPALIVE probes.
.. option:: keepintvl
Seconds between TCP KEEPALIVE probes.
.. option:: poll
Gearman worker polling timeout. Default is 1.
.. option:: reconnect_sleep
Seconds to sleep between job server reconnects. Default is 60.
.. option:: servers
Comma-separated list of Gearman job servers and port in HOST:PORT format.
.. option:: ssl_ca
Gearman SSL certificate authority.
.. option:: ssl_cert
Gearman SSL certificate.
.. option:: ssl_key
Gearman SSL key.

83
doc/worker/config.rst
View File

@@ -14,84 +14,27 @@ Configuration File
[worker]
driver = haproxy
reconnect_sleep = 60
server = 10.0.0.1:8080 10.0.0.2:8080
pid = /var/run/libra/libra_worker.pid
Command Line Options
--------------------
.. program:: libra_worker
Note that drivers supported by the worker may add additional subsections
to the configuration file for their configuration needs. See the
:doc:`haproxy driver documentation <drivers/haproxy>` for an example.
.. option:: --driver <DRIVER>
Options supported in this section:
.. option:: driver <DRIVER>
Load balancer driver to use. Valid driver options are:
* *haproxy* - `HAProxy <http://haproxy.1wt.eu>`_ software load balancer.
This is the default driver.
.. option:: --gearman_keepalive
.. option:: pid <FILE>
Use TCP KEEPALIVE to the Gearman job server. Not supported on all
systems.
Location for the process PID file.
.. option:: --gearman_keepcnt <COUNT>
Maximum number of TCP KEEPALIVE probes to send before killing the
connection to the Gearman job server.
.. option:: --gearman_keepidle <SECONDS>
Seconds of idle time on the Gearman job server connection before
sending TCP KEEPALIVE probes.
.. option:: --gearman_keepintvl <SECONDS>
Seconds between TCP KEEPALIVE probes.
.. option:: --gearman_ssl_ca <FILE>
Full path to the file with the CA public key to use when
connecting to an SSL-enabled Gearman job server. This is used
to validate the server key.
.. option:: --gearman_ssl_cert <FILE>
Full path to the file with the SSL public key to use when
connecting to an SSL-enabled Gearman job server.
.. option:: --gearman_ssl_key <FILE>
Full path to the file with the SSL private key to use when
connecting to an SSL-enabled Gearman job server.
.. option:: -s <SECONDS>, --reconnect_sleep <SECONDS>
The number of seconds to sleep between job server reconnect attempts
when no specified job servers are available. Default is 60 seconds.
.. option:: --server <HOST:PORT>
Used to specify the Gearman job server hostname and port. This option
can be used multiple times to specify multiple job servers.
.. option:: --stats-poll <SECONDS>
The number of seconds to sleep between statistics polling of the
load balancer driver. Default is 300 seconds.
.. option:: --gearman-poll <SECONDS>
The number of seconds gearman will poll before re-shuffling its
connections. Default is 1 second.
.. option:: --syslog
Send log events to syslog.
.. option:: --syslog-socket
Socket to use for the syslog connection. Default is */dev/log*.
.. option:: --syslog-facility
Syslog logging facility. Default is *LOCAL7*.
Command Line Options
--------------------
Some options can be specified via the command line. Run with the
-h or --help option for a full listing.

28
doc/worker/drivers/haproxy.rst
View File

@@ -4,23 +4,31 @@
HAProxy driver
==============
Configuration
-------------
Configuration File
------------------
.. option:: --haproxy_logfile <FILE>
The ``[worker:haproxy]`` section is read by the HAProxy driver.
Configure the path for where to put haproxy log.
.. code-block:: ini
.. note::
[worker:haproxy]
service = ubuntu
logfile = /var/log/haproxy.log
Options supported in this section:
.. option:: logfile
Path where haproxy will store its logs.
.. note::
See :ref:`libra-worker-driver-haproxy-archiving` for information on
archiving.
.. option:: --haproxy_service <service>
.. option:: service
The underlying OS Service implementation to use
Default: ubuntu
The underlying OS Service implementation to use. Default is 'ubuntu'.
.. _libra-worker-driver-haproxy-archiving:
@@ -42,4 +50,4 @@ the rsyslog feed from local0 to a dedicated file
local0.* -/var/log/haproxy.log;Haproxy
# don't log anywhere else
local0.* ~
EOF
EOF