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
... | ... |
@@ -77,30 +77,21 @@ here, so run it in a VM. And take advantage of the snapshot capabilities |
77 | 77 |
of your hypervisor of choice to reduce testing cycle times. You might even save |
78 | 78 |
enough time to write one more feature before the next feature freeze... |
79 | 79 |
|
80 |
-``stack.sh`` needs to have root access for a lot of tasks, but uses ``sudo`` |
|
81 |
-for all of those tasks. However, it needs to be not-root for most of its |
|
82 |
-work and for all of the OpenStack services. ``stack.sh`` specifically |
|
83 |
-does not run if started as root. |
|
84 |
- |
|
85 |
-This is a recent change (Oct 2013) from the previous behaviour of |
|
86 |
-automatically creating a ``stack`` user. Automatically creating |
|
87 |
-user accounts is not the right response to running as root, so |
|
88 |
-that bit is now an explicit step using ``tools/create-stack-user.sh``. |
|
89 |
-Run that (as root!) or just check it out to see what DevStack's |
|
90 |
-expectations are for the account it runs under. Many people simply |
|
91 |
-use their usual login (the default 'ubuntu' login on a UEC image |
|
92 |
-for example). |
|
80 |
+``stack.sh`` needs to have root access for a lot of tasks, but uses |
|
81 |
+``sudo`` for all of those tasks. However, it needs to be not-root for |
|
82 |
+most of its work and for all of the OpenStack services. ``stack.sh`` |
|
83 |
+specifically does not run if started as root. |
|
93 | 84 |
|
94 |
-# Customizing |
|
95 |
- |
|
96 |
-You can override environment variables used in `stack.sh` by creating |
|
97 |
-file name `local.conf` with a ``localrc`` section as shown below. It |
|
98 |
-is likely that you will need to do this to tweak several settings for |
|
99 |
-your environment. |
|
85 |
+DevStack will not automatically create the user, but provides a helper |
|
86 |
+script in ``tools/create-stack-user.sh``. Run that (as root!) or just |
|
87 |
+check it out to see what DevStack's expectations are for the account |
|
88 |
+it runs under. Many people simply use their usual login (the default |
|
89 |
+'ubuntu' login on a UEC image for example). |
|
100 | 90 |
|
101 |
- [[local|localrc]] |
|
102 |
- VARIABLE=value |
|
91 |
+# Customizing |
|
103 | 92 |
|
104 |
-Start by reading the [configuration |
|
105 |
-guide](doc/source/configuration.rst) for details of the many available |
|
106 |
-options. |
|
107 | 93 |
\ No newline at end of file |
94 |
+DevStack can be extensively configured via the configuration file |
|
95 |
+`local.conf`. It is likely that you will need to provide and modify |
|
96 |
+this file if you want anything other than the most basic setup. Start |
|
97 |
+by reading the [configuration guide](doc/source/configuration.rst) for |
|
98 |
+details of the configuration file and the many available options. |
|
108 | 99 |
\ No newline at end of file |
... | ... |
@@ -6,34 +6,15 @@ Configuration |
6 | 6 |
:local: |
7 | 7 |
:depth: 1 |
8 | 8 |
|
9 |
-DevStack has always tried to be mostly-functional with a minimal amount |
|
10 |
-of configuration. The number of options has ballooned as projects add |
|
11 |
-features, new projects added and more combinations need to be tested. |
|
12 |
-Historically DevStack obtained all local configuration and |
|
13 |
-customizations from a ``localrc`` file. The number of configuration |
|
14 |
-variables that are simply passed-through to the individual project |
|
15 |
-configuration files is also increasing. The old mechanism for this |
|
16 |
-(``EXTRAS_OPTS`` and friends) required specific code for each file and |
|
17 |
-did not scale well. |
|
18 |
- |
|
19 |
-In Oct 2013 a new configuration method was introduced (in `review |
|
20 |
-46768 <https://review.openstack.org/#/c/46768/>`__) to hopefully |
|
21 |
-simplify this process and meet the following goals: |
|
22 |
- |
|
23 |
-- contain all non-default local configuration in a single file |
|
24 |
-- be backward-compatible with ``localrc`` to smooth the transition |
|
25 |
- process |
|
26 |
-- allow settings in arbitrary configuration files to be changed |
|
27 |
- |
|
28 | 9 |
local.conf |
29 | 10 |
========== |
30 | 11 |
|
31 |
-The new configuration file is ``local.conf`` and should reside in the |
|
32 |
-root Devstack directory. An example of such ``local.conf`` file |
|
33 |
-is provided in the ``devstack/samples`` directory. Copy this file into |
|
34 |
-the root Devstack directory and adapt it to your needs. It is a modified INI |
|
35 |
-format file that introduces a meta-section header to carry additional |
|
36 |
-information regarding the configuration files to be changed. |
|
12 |
+DevStack configuration is modified via the file ``local.conf``. It is |
|
13 |
+a modified INI format file that introduces a meta-section header to |
|
14 |
+carry additional information regarding the configuration files to be |
|
15 |
+changed. |
|
16 |
+ |
|
17 |
+A sample is provided in ``devstack/samples`` |
|
37 | 18 |
|
38 | 19 |
The new header is similar to a normal INI section header but with double |
39 | 20 |
brackets (``[[ ... ]]``) and two internal fields separated by a pipe |
... | ... |
@@ -148,33 +129,14 @@ will not be set if there is no IPv6 address on the default Ethernet interface. |
148 | 148 |
Setting it here also makes it available for ``openrc`` to set ``OS_AUTH_URL``. |
149 | 149 |
``HOST_IPV6`` is not set by default. |
150 | 150 |
|
151 |
-Examples |
|
152 |
-======== |
|
153 |
- |
|
154 |
-- Eliminate a Cinder pass-through (``CINDER_PERIODIC_INTERVAL``): |
|
155 |
- |
|
156 |
- :: |
|
157 |
- |
|
158 |
- [[post-config|$CINDER_CONF]] |
|
159 |
- [DEFAULT] |
|
160 |
- periodic_interval = 60 |
|
161 |
- |
|
162 |
-- Sample ``local.conf`` with screen logging enabled: |
|
163 |
- |
|
164 |
- :: |
|
165 |
- |
|
166 |
- [[local|localrc]] |
|
167 |
- FIXED_RANGE=10.254.1.0/24 |
|
168 |
- NETWORK_GATEWAY=10.254.1.1 |
|
169 |
- LOGDAYS=1 |
|
170 |
- LOGDIR=$DEST/logs |
|
171 |
- LOGFILE=$LOGDIR/stack.sh.log |
|
172 |
- ADMIN_PASSWORD=quiet |
|
173 |
- DATABASE_PASSWORD=$ADMIN_PASSWORD |
|
174 |
- RABBIT_PASSWORD=$ADMIN_PASSWORD |
|
175 |
- SERVICE_PASSWORD=$ADMIN_PASSWORD |
|
176 |
- SERVICE_TOKEN=a682f596-76f3-11e3-b3b2-e716f9080d50 |
|
151 |
+Historical Notes |
|
152 |
+================ |
|
177 | 153 |
|
154 |
+Historically DevStack obtained all local configuration and |
|
155 |
+customizations from a ``localrc`` file. In Oct 2013 the |
|
156 |
+``local.conf`` configuration method was introduced (in `review 46768 |
|
157 |
+<https://review.openstack.org/#/c/46768/>`__) to simplify this |
|
158 |
+process. |
|
178 | 159 |
|
179 | 160 |
Configuration Notes |
180 | 161 |
=================== |
... | ... |
@@ -257,6 +219,20 @@ to direct the message stream to the log host. | |
257 | 257 |
SYSLOG_PORT=516 |
258 | 258 |
|
259 | 259 |
|
260 |
+Example Logging Configuration |
|
261 |
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
262 |
+ |
|
263 |
+For example, non-interactive installs probably wish to save output to |
|
264 |
+a file, keep service logs and disable color in the stored files. |
|
265 |
+ |
|
266 |
+ :: |
|
267 |
+ |
|
268 |
+ [[local|localrc]] |
|
269 |
+ DEST=/opt/stack/ |
|
270 |
+ LOGDIR=$DEST/logs |
|
271 |
+ LOGFILE=$LOGDIR/stack.sh.log |
|
272 |
+ LOG_COLOR=False |
|
273 |
+ |
|
260 | 274 |
Database Backend |
261 | 275 |
---------------- |
262 | 276 |
|