Clean up configuration documentation

The current format is just copy-paste after auto-conversion and very
inconsistent.  Move discussion of each option into a section and
reword some slightly so they read more clearly.  Group some together
into a section+sub-sections, such as the logging and ip-version option
discussions.

Add a top table-of-contents for the major sections, and then a
separate toc for each of the configuration options that are discussed
in detail.

Change-Id: Iddd27cb54f1d9f062b9c47ff9ad6a2bef3650d6b
This commit is contained in:
Ian Wienand 2015-08-06 10:25:45 +10:00
parent 5751017ae3
commit 815db16c20

View File

@ -2,6 +2,10 @@
Configuration Configuration
============= =============
.. contents::
:local:
:depth: 1
DevStack has always tried to be mostly-functional with a minimal amount DevStack has always tried to be mostly-functional with a minimal amount
of configuration. The number of options has ballooned as projects add of configuration. The number of options has ballooned as projects add
features, new projects added and more combinations need to be tested. features, new projects added and more combinations need to be tested.
@ -142,36 +146,96 @@ will not be set if there is no IPv6 address on the default Ethernet interface.
Setting it here also makes it available for ``openrc`` to set ``OS_AUTH_URL``. Setting it here also makes it available for ``openrc`` to set ``OS_AUTH_URL``.
``HOST_IPV6`` is not set by default. ``HOST_IPV6`` is not set by default.
Common Configuration Variables Configuration Notes
============================== ===================
.. contents::
:local:
Installation Directory Installation Directory
---------------------- ----------------------
| *Default: ``DEST=/opt/stack``* The DevStack install directory is set by the ``DEST`` variable. By
| The DevStack install directory is set by the ``DEST`` variable. default it is ``/opt/stack``.
| By setting it early in the ``localrc`` section you can reference it
in later variables. It can be useful to set it even though it is not By setting it early in the ``localrc`` section you can reference it in
changed from the default value. later variables. It can be useful to set it even though it is not
| changed from the default value.
:: ::
DEST=/opt/stack DEST=/opt/stack
Logging
-------
Enable Logging
~~~~~~~~~~~~~~
By default ``stack.sh`` output is only written to the console where it
runs. It can be sent to a file in addition to the console by setting
``LOGFILE`` to the fully-qualified name of the destination log file. A
timestamp will be appended to the given filename for each run of
``stack.sh``.
::
LOGFILE=$DEST/logs/stack.sh.log
Old log files are cleaned automatically if ``LOGDAYS`` is set to the
number of days of old log files to keep.
::
LOGDAYS=1
The some of the project logs (Nova, Cinder, etc) will be colorized by
default (if ``SYSLOG`` is not set below); this can be turned off by
setting ``LOG_COLOR`` to ``False``.
::
LOG_COLOR=False
Logging the Service Output
~~~~~~~~~~~~~~~~~~~~~~~~~~
DevStack will log the ``stdout`` output of the services it starts.
When using ``screen`` this logs the output in the screen windows to a
file. Without ``screen`` this simply redirects stdout of the service
process to a file in ``LOGDIR``.
::
LOGDIR=$DEST/logs
*Note the use of ``DEST`` to locate the main install directory; this
is why we suggest setting it in ``local.conf``.*
Enabling Syslog
~~~~~~~~~~~~~~~
Logging all services to a single syslog can be convenient. Enable
syslogging by setting ``SYSLOG`` to ``True``. If the destination log
host is not localhost ``SYSLOG_HOST`` and ``SYSLOG_PORT`` can be used
to direct the message stream to the log host. |
::
SYSLOG=True
SYSLOG_HOST=$HOST_IP
SYSLOG_PORT=516
Libraries from Git Libraries from Git
------------------ ------------------
| *Default: ``LIBS_FROM_GIT=""``* By default devstack installs OpenStack server components from git,
however it installs client libraries from released versions on pypi.
| By default devstack installs OpenStack server components from This is appropriate if you are working on server development, but if
git, however it installs client libraries from released versions you want to see how an unreleased version of the client affects the
on pypi. This is appropriate if you are working on server system you can have devstack install it from upstream, or from local
development, but if you want to see how an unreleased version of git trees by specifying it in ``LIBS_FROM_GIT``. Multiple libraries
the client affects the system you can have devstack install it can be specified as a comma separated list.
from upstream, or from local git trees.
| Multiple libraries can be specified as a comma separated list.
|
:: ::
@ -180,99 +244,37 @@ Libraries from Git
Virtual Environments Virtual Environments
-------------------- --------------------
| *Default: ``USE_VENV=False``* Enable the use of Python virtual environments by setting ``USE_VENV``
| Enable the use of Python virtual environments by setting ``USE_VENV`` to ``True``. This will enable the creation of venvs for each project
to ``True``. This will enable the creation of venvs for each project that is defined in the ``PROJECT_VENV`` array.
that is defined in the ``PROJECT_VENV`` array.
| *Default: ``PROJECT_VENV['<project>']='<project-dir>.venv'* Each entry in the ``PROJECT_VENV`` array contains the directory name
| Each entry in the ``PROJECT_VENV`` array contains the directory name of a venv to be used for the project. The array index is the project
of a venv to be used for the project. The array index is the project name. Multiple projects can use the same venv if desired.
name. Multiple projects can use the same venv if desired.
:: ::
PROJECT_VENV["glance"]=${GLANCE_DIR}.venv PROJECT_VENV["glance"]=${GLANCE_DIR}.venv
| *Default: ``ADDITIONAL_VENV_PACKAGES=""``* ``ADDITIONAL_VENV_PACKAGES`` is a comma-separated list of additional
| A comma-separated list of additional packages to be installed into each packages to be installed into each venv. Often projects will not have
venv. Often projects will not have certain packages listed in its certain packages listed in its ``requirements.txt`` file because they
``requirements.txt`` file because they are 'optional' requirements, are 'optional' requirements, i.e. only needed for certain
i.e. only needed for certain configurations. By default, the enabled configurations. By default, the enabled databases will have their
databases will have their Python bindings added when they are enabled. Python bindings added when they are enabled.
Enable Logging ::
--------------
| *Defaults: ``LOGFILE="" LOGDAYS=7 LOG_COLOR=True``* ADDITIONAL_VENV_PACKAGES="python-foo, python-bar"
| By default ``stack.sh`` output is only written to the console
where it runs. It can be sent to a file in addition to the console
by setting ``LOGFILE`` to the fully-qualified name of the
destination log file. A timestamp will be appended to the given
filename for each run of ``stack.sh``.
|
::
LOGFILE=$DEST/logs/stack.sh.log
Old log files are cleaned automatically if ``LOGDAYS`` is set to the
number of days of old log files to keep.
::
LOGDAYS=1
The some of the project logs (Nova, Cinder, etc) will be colorized
by default (if ``SYSLOG`` is not set below); this can be turned off
by setting ``LOG_COLOR`` False.
::
LOG_COLOR=False
Logging the Service Output
--------------------------
| *Default: ``LOGDIR=""``*
| DevStack will log the stdout output of the services it starts.
When using ``screen`` this logs the output in the screen windows
to a file. Without ``screen`` this simply redirects stdout of
the service process to a file in ``LOGDIR``.
|
::
LOGDIR=$DEST/logs
*Note the use of ``DEST`` to locate the main install directory; this
is why we suggest setting it in ``local.conf``.*
Enabling Syslog
---------------
| *Default: ``SYSLOG=False SYSLOG_HOST=$HOST_IP SYSLOG_PORT=516``*
| Logging all services to a single syslog can be convenient. Enable
syslogging by setting ``SYSLOG`` to ``True``. If the destination log
host is not localhost ``SYSLOG_HOST`` and ``SYSLOG_PORT`` can be
used to direct the message stream to the log host.
|
::
SYSLOG=True
SYSLOG_HOST=$HOST_IP
SYSLOG_PORT=516
A clean install every time A clean install every time
-------------------------- --------------------------
| *Default: ``RECLONE=""``* By default ``stack.sh`` only clones the project repos if they do not
| By default ``stack.sh`` only clones the project repos if they do exist in ``$DEST``. ``stack.sh`` will freshen each repo on each run if
not exist in ``$DEST``. ``stack.sh`` will freshen each repo on each ``RECLONE`` is set to ``yes``. This avoids having to manually remove
run if ``RECLONE`` is set to ``yes``. This avoids having to manually repos in order to get the current branch from ``$GIT_BASE``.
remove repos in order to get the current branch from ``$GIT_BASE``.
|
:: ::
@ -281,13 +283,11 @@ A clean install every time
Upgrade packages installed by pip Upgrade packages installed by pip
--------------------------------- ---------------------------------
| *Default: ``PIP_UPGRADE=""``* By default ``stack.sh`` only installs Python packages if no version is
| By default ``stack.sh`` only installs Python packages if no version currently installed or the current version does not match a specified
is currently installed or the current version does not match a specified requirement. If ``PIP_UPGRADE`` is set to ``True`` then existing
requirement. If ``PIP_UPGRADE`` is set to ``True`` then existing required required Python packages will be upgraded to the most recent version
Python packages will be upgraded to the most recent version that that matches requirements.
matches requirements.
|
:: ::
@ -296,74 +296,69 @@ Upgrade packages installed by pip
Swift Swift
----- -----
| Default: SWIFT_HASH="" Swift is now used as the back-end for the S3-like object store. When
| SWIFT_REPLICAS=1 enabled Nova's objectstore (``n-obj`` in ``ENABLED_SERVICES``) is
| SWIFT_DATA_DIR=$DEST/data/swift automatically disabled. Enable Swift by adding it services to
``ENABLED_SERVICES``
| Swift is now used as the back-end for the S3-like object store. ::
When enabled Nova's objectstore (n-obj in ENABLED_SERVICES) is
automatically disabled. Enable Swift by adding it services to
ENABLED_SERVICES: enable_service s-proxy s-object s-container
s-account
Setting Swift's hash value is required and you will be prompted for enable_service s-proxy s-object s-container s-account
it if Swift is enabled so just set it to something already:
Setting Swift's hash value is required and you will be prompted for it
if Swift is enabled so just set it to something already:
:: ::
SWIFT_HASH=66a3d6b56c1f479c8b4e70ab5c2000f5 SWIFT_HASH=66a3d6b56c1f479c8b4e70ab5c2000f5
For development purposes the default number of replicas is set to For development purposes the default number of replicas is set to
``1`` to reduce the overhead required. To better simulate a ``1`` to reduce the overhead required. To better simulate a production
production deployment set this to ``3`` or more. deployment set this to ``3`` or more.
:: ::
SWIFT_REPLICAS=3 SWIFT_REPLICAS=3
The data for Swift is stored in the source tree by default (in The data for Swift is stored in the source tree by default (in
``$DEST/swift/data``) and can be moved by setting ``$DEST/swift/data``) and can be moved by setting
``SWIFT_DATA_DIR``. The specified directory will be created if it ``SWIFT_DATA_DIR``. The specified directory will be created if it does
does not exist. not exist.
:: ::
SWIFT_DATA_DIR=$DEST/data/swift SWIFT_DATA_DIR=$DEST/data/swift
*Note: Previously just enabling ``swift`` was sufficient to start *Note*: Previously just enabling ``swift`` was sufficient to start the
the Swift services. That does not provide proper service Swift services. That does not provide proper service granularity,
granularity, particularly in multi-host configurations, and is particularly in multi-host configurations, and is considered
considered deprecated. Some service combination tests now check for deprecated. Some service combination tests now check for specific
specific Swift services and the old blanket acceptance will longer Swift services and the old blanket acceptance will longer work
work correctly.* correctly.
Service Catalog Backend Service Catalog Backend
----------------------- -----------------------
| *Default: ``KEYSTONE_CATALOG_BACKEND=sql``* By default DevStack uses Keystone's ``sql`` service catalog backend.
| DevStack uses Keystone's ``sql`` service catalog backend. An An alternate ``template`` backend is also available, however, it does
alternate ``template`` backend is also available. However, it does not support the ``service-*`` and ``endpoint-*`` commands of the
not support the ``service-*`` and ``endpoint-*`` commands of the ``keystone`` CLI. To do so requires the ``sql`` backend be enabled
``keystone`` CLI. To do so requires the ``sql`` backend be enabled: with ``KEYSTONE_CATALOG_BACKEND``:
|
:: ::
KEYSTONE_CATALOG_BACKEND=template KEYSTONE_CATALOG_BACKEND=template
DevStack's default configuration in ``sql`` mode is set in DevStack's default configuration in ``sql`` mode is set in
``files/keystone_data.sh`` ``files/keystone_data.sh``
Cinder Cinder
------ ------
| Default: The logical volume group used to hold the Cinder-managed volumes is
| VOLUME_GROUP="stack-volumes" VOLUME_NAME_PREFIX="volume-" VOLUME_BACKING_FILE_SIZE=10250M set by ``VOLUME_GROUP``, the logical volume name prefix is set with
| The logical volume group used to hold the Cinder-managed volumes ``VOLUME_NAME_PREFIX`` and the size of the volume backing file is set
is set by ``VOLUME_GROUP``, the logical volume name prefix is set with ``VOLUME_BACKING_FILE_SIZE``.
with ``VOLUME_NAME_PREFIX`` and the size of the volume backing file
is set with ``VOLUME_BACKING_FILE_SIZE``.
|
:: ::
@ -374,19 +369,23 @@ Cinder
Multi-host DevStack Multi-host DevStack
------------------- -------------------
| *Default: ``MULTI_HOST=False``* Running DevStack with multiple hosts requires a custom ``local.conf``
| Running DevStack with multiple hosts requires a custom section for each host. The master is the same as a single host
``local.conf`` section for each host. The master is the same as a installation with ``MULTI_HOST=True``. The slaves have fewer services
single host installation with ``MULTI_HOST=True``. The slaves have enabled and a couple of host variables pointing to the master.
fewer services enabled and a couple of host variables pointing to
the master.
| **Master**
Master
~~~~~~
Set ``MULTI_HOST`` to true
:: ::
MULTI_HOST=True MULTI_HOST=True
**Slave** Slave
~~~~~
Set the following options to point to the master
:: ::
@ -398,22 +397,19 @@ Multi-host DevStack
IP Version IP Version
---------- ----------
| Default: ``IP_VERSION=4+6`` ``IP_VERSION`` can be used to configure DevStack to create either an
| This setting can be used to configure DevStack to create either an IPv4, IPv4, IPv6, or dual-stack tenant data-network by with either
IPv6, or dual stack tenant data network by setting ``IP_VERSION`` to ``IP_VERSION=4``, ``IP_VERSION=6``, or ``IP_VERSION=4+6``
either ``IP_VERSION=4``, ``IP_VERSION=6``, or ``IP_VERSION=4+6`` respectively. This functionality requires that the Neutron networking
respectively. This functionality requires that the Neutron networking service is enabled by setting the following options:
service is enabled by setting the following options:
|
:: ::
disable_service n-net disable_service n-net
enable_service q-svc q-agt q-dhcp q-l3 enable_service q-svc q-agt q-dhcp q-l3
| The following optional variables can be used to alter the default IPv6 The following optional variables can be used to alter the default IPv6
behavior: behavior:
|
:: ::
@ -422,24 +418,28 @@ IP Version
FIXED_RANGE_V6=fd$IPV6_GLOBAL_ID::/64 FIXED_RANGE_V6=fd$IPV6_GLOBAL_ID::/64
IPV6_PRIVATE_NETWORK_GATEWAY=fd$IPV6_GLOBAL_ID::1 IPV6_PRIVATE_NETWORK_GATEWAY=fd$IPV6_GLOBAL_ID::1
| *Note: ``FIXED_RANGE_V6`` and ``IPV6_PRIVATE_NETWORK_GATEWAY`` *Note*: ``FIXED_RANGE_V6`` and ``IPV6_PRIVATE_NETWORK_GATEWAY`` can be
can be configured with any valid IPv6 prefix. The default values make configured with any valid IPv6 prefix. The default values make use of
use of an auto-generated ``IPV6_GLOBAL_ID`` to comply with RFC 4193.* an auto-generated ``IPV6_GLOBAL_ID`` to comply with RFC4193.
|
| Default: ``SERVICE_IP_VERSION=4`` Service Version
| This setting can be used to configure DevStack to enable services to ~~~~~~~~~~~~~~~
operate over either IPv4 or IPv6, by setting ``SERVICE_IP_VERSION`` to
either ``SERVICE_IP_VERSION=4`` or ``SERVICE_IP_VERSION=6`` respectively. DevStack can enable service operation over either IPv4 or IPv6 by
When set to ``4`` devstack services will open listen sockets on 0.0.0.0 setting ``SERVICE_IP_VERSION`` to either ``SERVICE_IP_VERSION=4`` or
and service endpoints will be registered using ``HOST_IP`` as the address. ``SERVICE_IP_VERSION=6`` respectively.
When set to ``6`` devstack services will open listen sockets on :: and
service endpoints will be registered using ``HOST_IPV6`` as the address. When set to ``4`` devstack services will open listen sockets on
The default value for this setting is ``4``. Dual-mode support, for ``0.0.0.0`` and service endpoints will be registered using ``HOST_IP``
example ``4+6`` is not currently supported. as the address.
| The following optional variable can be used to alter the default IPv6
address used: When set to ``6`` devstack services will open listen sockets on ``::``
| and service endpoints will be registered using ``HOST_IPV6`` as the
address.
The default value for this setting is ``4``. Dual-mode support, for
example ``4+6`` is not currently supported. ``HOST_IPV6`` can
optionally be used to alter the default IPv6 address
:: ::