Talk about local.conf first
We bury the lead with all the historical notes about localrc; just
talk about what is important to somebody setting up a current
devstack, which is local.conf.
There are already inline examples of config-variables, etc. Remove
them, but add a small overview example for logging in its place.
Change-Id: I466252ffba66ef4ea180c9355f715a19eb4f8017
diff --git a/README.md b/README.md
index df0df91..ee7f0e7 100644
--- a/README.md
+++ b/README.md
@@ -77,30 +77,21 @@
of your hypervisor of choice to reduce testing cycle times. You might even save
enough time to write one more feature before the next feature freeze...
-``stack.sh`` needs to have root access for a lot of tasks, but uses ``sudo``
-for all of those tasks. However, it needs to be not-root for most of its
-work and for all of the OpenStack services. ``stack.sh`` specifically
-does not run if started as root.
+``stack.sh`` needs to have root access for a lot of tasks, but uses
+``sudo`` for all of those tasks. However, it needs to be not-root for
+most of its work and for all of the OpenStack services. ``stack.sh``
+specifically does not run if started as root.
-This is a recent change (Oct 2013) from the previous behaviour of
-automatically creating a ``stack`` user. Automatically creating
-user accounts is not the right response to running as root, so
-that bit is now an explicit step using ``tools/create-stack-user.sh``.
-Run that (as root!) or just check it out to see what DevStack's
-expectations are for the account it runs under. Many people simply
-use their usual login (the default 'ubuntu' login on a UEC image
-for example).
+DevStack will not automatically create the user, but provides a helper
+script in ``tools/create-stack-user.sh``. Run that (as root!) or just
+check it out to see what DevStack's expectations are for the account
+it runs under. Many people simply use their usual login (the default
+'ubuntu' login on a UEC image for example).
# Customizing
-You can override environment variables used in `stack.sh` by creating
-file name `local.conf` with a ``localrc`` section as shown below. It
-is likely that you will need to do this to tweak several settings for
-your environment.
-
- [[local|localrc]]
- VARIABLE=value
-
-Start by reading the [configuration
-guide](doc/source/configuration.rst) for details of the many available
-options.
\ No newline at end of file
+DevStack can be extensively configured via the configuration file
+`local.conf`. It is likely that you will need to provide and modify
+this file if you want anything other than the most basic setup. Start
+by reading the [configuration guide](doc/source/configuration.rst) for
+details of the configuration file and the many available options.
\ No newline at end of file
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index ed17924..fe23d6c 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -6,34 +6,15 @@
:local:
:depth: 1
-DevStack has always tried to be mostly-functional with a minimal amount
-of configuration. The number of options has ballooned as projects add
-features, new projects added and more combinations need to be tested.
-Historically DevStack obtained all local configuration and
-customizations from a ``localrc`` file. The number of configuration
-variables that are simply passed-through to the individual project
-configuration files is also increasing. The old mechanism for this
-(``EXTRAS_OPTS`` and friends) required specific code for each file and
-did not scale well.
-
-In Oct 2013 a new configuration method was introduced (in `review
-46768 <https://review.openstack.org/#/c/46768/>`__) to hopefully
-simplify this process and meet the following goals:
-
-- contain all non-default local configuration in a single file
-- be backward-compatible with ``localrc`` to smooth the transition
- process
-- allow settings in arbitrary configuration files to be changed
-
local.conf
==========
-The new configuration file is ``local.conf`` and should reside in the
-root Devstack directory. An example of such ``local.conf`` file
-is provided in the ``devstack/samples`` directory. Copy this file into
-the root Devstack directory and adapt it to your needs. It is a modified INI
-format file that introduces a meta-section header to carry additional
-information regarding the configuration files to be changed.
+DevStack configuration is modified via the file ``local.conf``. It is
+a modified INI format file that introduces a meta-section header to
+carry additional information regarding the configuration files to be
+changed.
+
+A sample is provided in ``devstack/samples``
The new header is similar to a normal INI section header but with double
brackets (``[[ ... ]]``) and two internal fields separated by a pipe
@@ -148,33 +129,14 @@
Setting it here also makes it available for ``openrc`` to set ``OS_AUTH_URL``.
``HOST_IPV6`` is not set by default.
-Examples
-========
+Historical Notes
+================
-- Eliminate a Cinder pass-through (``CINDER_PERIODIC_INTERVAL``):
-
- ::
-
- [[post-config|$CINDER_CONF]]
- [DEFAULT]
- periodic_interval = 60
-
-- Sample ``local.conf`` with screen logging enabled:
-
- ::
-
- [[local|localrc]]
- FIXED_RANGE=10.254.1.0/24
- NETWORK_GATEWAY=10.254.1.1
- LOGDAYS=1
- LOGDIR=$DEST/logs
- LOGFILE=$LOGDIR/stack.sh.log
- ADMIN_PASSWORD=quiet
- DATABASE_PASSWORD=$ADMIN_PASSWORD
- RABBIT_PASSWORD=$ADMIN_PASSWORD
- SERVICE_PASSWORD=$ADMIN_PASSWORD
- SERVICE_TOKEN=a682f596-76f3-11e3-b3b2-e716f9080d50
-
+Historically DevStack obtained all local configuration and
+customizations from a ``localrc`` file. In Oct 2013 the
+``local.conf`` configuration method was introduced (in `review 46768
+<https://review.openstack.org/#/c/46768/>`__) to simplify this
+process.
Configuration Notes
===================
@@ -257,6 +219,20 @@
SYSLOG_PORT=516
+Example Logging Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For example, non-interactive installs probably wish to save output to
+a file, keep service logs and disable color in the stored files.
+
+ ::
+
+ [[local|localrc]]
+ DEST=/opt/stack/
+ LOGDIR=$DEST/logs
+ LOGFILE=$LOGDIR/stack.sh.log
+ LOG_COLOR=False
+
Database Backend
----------------