openstack/devstack
Code Issues Proposed changes

Clean up configuration documentation

Browse Source 
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
1 changed files with 178 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files

296
doc/source/configuration.rst
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,75 +146,37 @@ 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
later variables. It can be useful to set it even though it is not
changed from the default value. changed from the default value.
|
:: ::
DEST=/opt/stack DEST=/opt/stack
Libraries from Git Logging
------------------ -------
| *Default: ``LIBS_FROM_GIT=""``*
| By default devstack installs OpenStack server components from
git, however it installs client libraries from released versions
on pypi. This is appropriate if you are working on server
development, but if you want to see how an unreleased version of
the client affects the system you can have devstack install it
from upstream, or from local git trees.
| Multiple libraries can be specified as a comma separated list.
|
::
LIBS_FROM_GIT=python-keystoneclient,oslo.config
Virtual Environments
--------------------
| *Default: ``USE_VENV=False``*
| Enable the use of Python virtual environments by setting ``USE_VENV``
to ``True``. This will enable the creation of venvs for each project
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
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.
::
PROJECT_VENV["glance"]=${GLANCE_DIR}.venv
| *Default: ``ADDITIONAL_VENV_PACKAGES=""``*
| A comma-separated list of additional packages to be installed into each
venv. Often projects will not have certain packages listed in its
``requirements.txt`` file because they are 'optional' requirements,
i.e. only needed for certain configurations. By default, the enabled
databases will have their Python bindings added when they are enabled.
Enable Logging Enable Logging
-------------- ~~~~~~~~~~~~~~
| *Defaults: ``LOGFILE="" LOGDAYS=7 LOG_COLOR=True``* By default ``stack.sh`` output is only written to the console where it
| By default ``stack.sh`` output is only written to the console runs. It can be sent to a file in addition to the console by setting
where it runs. It can be sent to a file in addition to the console ``LOGFILE`` to the fully-qualified name of the destination log file. A
by setting ``LOGFILE`` to the fully-qualified name of the timestamp will be appended to the given filename for each run of
destination log file. A timestamp will be appended to the given ``stack.sh``.
filename for each run of ``stack.sh``.
|
:: ::
@@ -223,23 +189,21 @@ Enable Logging
LOGDAYS=1 LOGDAYS=1
The some of the project logs (Nova, Cinder, etc) will be colorized The some of the project logs (Nova, Cinder, etc) will be colorized by
by default (if ``SYSLOG`` is not set below); this can be turned off default (if ``SYSLOG`` is not set below); this can be turned off by
by setting ``LOG_COLOR`` False. setting ``LOG_COLOR`` to ``False``.
:: ::
LOG_COLOR=False LOG_COLOR=False
Logging the Service Output Logging the Service Output
-------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~
| *Default: ``LOGDIR=""``* DevStack will log the ``stdout`` output of the services it starts.
| DevStack will log the stdout output of the services it starts. When using ``screen`` this logs the output in the screen windows to a
When using ``screen`` this logs the output in the screen windows file. Without ``screen`` this simply redirects stdout of the service
to a file. Without ``screen`` this simply redirects stdout of process to a file in ``LOGDIR``.
the service process to a file in ``LOGDIR``.
|
:: ::
@@ -249,14 +213,12 @@ Logging the Service Output
is why we suggest setting it in ``local.conf``.* is why we suggest setting it in ``local.conf``.*
Enabling Syslog Enabling Syslog
--------------- ~~~~~~~~~~~~~~~
| *Default: ``SYSLOG=False SYSLOG_HOST=$HOST_IP SYSLOG_PORT=516``* Logging all services to a single syslog can be convenient. Enable
| Logging all services to a single syslog can be convenient. Enable
syslogging by setting ``SYSLOG`` to ``True``. If the destination log syslogging by setting ``SYSLOG`` to ``True``. If the destination log
host is not localhost ``SYSLOG_HOST`` and ``SYSLOG_PORT`` can be host is not localhost ``SYSLOG_HOST`` and ``SYSLOG_PORT`` can be used
used to direct the message stream to the log host. to direct the message stream to the log host. |
|
:: ::
@@ -264,15 +226,55 @@ Enabling Syslog
SYSLOG_HOST=$HOST_IP SYSLOG_HOST=$HOST_IP
SYSLOG_PORT=516 SYSLOG_PORT=516
Libraries from Git
------------------
By default devstack installs OpenStack server components from git,
however it installs client libraries from released versions on pypi.
This is appropriate if you are working on server development, but if
you want to see how an unreleased version of the client affects the
system you can have devstack install it from upstream, or from local
git trees by specifying it in ``LIBS_FROM_GIT``. Multiple libraries
can be specified as a comma separated list.
::
LIBS_FROM_GIT=python-keystoneclient,oslo.config
Virtual Environments
--------------------
Enable the use of Python virtual environments by setting ``USE_VENV``
to ``True``. This will enable the creation of venvs for each project
that is defined in the ``PROJECT_VENV`` array.
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
name. Multiple projects can use the same venv if desired.
::
PROJECT_VENV["glance"]=${GLANCE_DIR}.venv
``ADDITIONAL_VENV_PACKAGES`` is a comma-separated list of additional
packages to be installed into each venv. Often projects will not have
certain packages listed in its ``requirements.txt`` file because they
are 'optional' requirements, i.e. only needed for certain
configurations. By default, the enabled databases will have their
Python bindings added when they are enabled.
::
ADDITIONAL_VENV_PACKAGES="python-foo, python-bar"
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,26 +296,25 @@ 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
| 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 automatically disabled. Enable Swift by adding it services to
ENABLED_SERVICES: enable_service s-proxy s-object s-container ``ENABLED_SERVICES``
s-account
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:
enable_service s-proxy s-object s-container s-account
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.
:: ::
@@ -323,29 +322,28 @@ Swift
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``:
:: ::
@@ -357,13 +355,10 @@ Service Catalog Backend
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.
|
Service Version
~~~~~~~~~~~~~~~
DevStack can enable service operation over either IPv4 or IPv6 by
setting ``SERVICE_IP_VERSION`` to either ``SERVICE_IP_VERSION=4`` or
``SERVICE_IP_VERSION=6`` respectively.
When set to ``4`` devstack services will open listen sockets on
``0.0.0.0`` and service endpoints will be registered using ``HOST_IP``
as the address.
When set to ``6`` devstack services will open listen sockets on ``::``
and service endpoints will be registered using ``HOST_IPV6`` as the
address.
| Default: ``SERVICE_IP_VERSION=4``
| 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.
When set to ``4`` devstack services will open listen sockets on 0.0.0.0
and service endpoints will be registered using ``HOST_IP`` as the address.
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 The default value for this setting is ``4``. Dual-mode support, for
example ``4+6`` is not currently supported. example ``4+6`` is not currently supported. ``HOST_IPV6`` can
| The following optional variable can be used to alter the default IPv6 optionally be used to alter the default IPv6 address
address used:
|
:: ::