Gitiles
Code Review Sign In
spfactory.storpool.com / devstack / 58f1405665f72ae482aa34e09049a2847be1570e / . / doc / source / configuration.html
blob: 88d7476becb487550bb2a8d8308ff4853f231f5b [file] [log] [blame]
Dean Troyer54b97322014-06-20 17:53:55 -0500[diff] [blame]1<!DOCTYPE html>
2<html lang="en">
3 <head>
4 <meta charset="utf-8">
5 <title>DevStack - Overview</title>
6 <meta name="description" content="">
7 <meta name="author" content="">
8
9 <!-- Le HTML5 shim, for IE6-8 support of HTML elements -->
10 <!--[if lt IE 9]>
11 <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
12 <![endif]-->
13
14 <!-- Le styles -->
15 <link href="assets/css/bootstrap.css" rel="stylesheet">
16 <link href="assets/css/local.css" rel="stylesheet">
17 <style type="text/css">
18 body { padding-top: 60px; }
19 dd { padding: 10px; }
20 </style>
21
22 <!-- Le javascripts -->
23 <script src="assets/js/jquery-1.7.1.min.js" type="text/javascript" charset="utf-8"></script>
24 <script src="assets/js/bootstrap.js" type="text/javascript" charset="utf-8"></script>
25 </head>
26
27 <body>
28
29 <div class="navbar navbar-fixed-top">
30 <div class="navbar-inner">
31 <div class="container">
32 <a class="brand" href="/">DevStack</a>
33 <ul class="nav pull-right">
34 <li><a href="overview.html">Overview</a></li>
35 <li><a href="changes.html">Changes</a></li>
36 <li><a href="faq.html">FAQ</a></li>
Adrien Cunineaff3e12014-10-21 13:46:54 +0200[diff] [blame]37 <li><a href="https://git.openstack.org/cgit/openstack-dev/devstack">git.openstack.org</a></li>
Dean Troyer54b97322014-06-20 17:53:55 -0500[diff] [blame]38 <li><a href="https://review.openstack.org/#/q/status:open+project:openstack-dev/devstack,n,z">Gerrit</a></li>
39 </ul>
40 </div>
41 </div>
42 </div>
43
44 <div class="container" id="home">
45
46 <section id="overview" class="span12">
47
48 <div class='row pull-left'>
49 <h2>Configuration <small>Making it go my way</small></h2>
50 <p>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 <code>localrc</code> 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 (<code>EXTRAS_OPTS</code> and friends) required specific code for each file and did not scale well.</p>
51 <p>In Oct 2013 a new configuration method was introduced (in <a href="https://review.openstack.org/#/c/46768/">review 46768</a>) to hopefully simplify this process and meet the following goals:</p>
52 <ul>
53 <li>contain all non-default local configuration in a single file</li>
54 <li>be backward-compatible with <code>localrc</code> to smooth the transition process</li>
55 <li>allow settings in arbitrary configuration files to be changed</li>
56 </ul>
57
58 <h3>local.conf</h3>
59 <p>The new configuration file is <code>local.conf</code> and resides in the root DevStack directory like the old <code>localrc</code> file. It is a modified INI format file that introduces a meta-section header to carry additional information regarding the configuration files to be changed.</p>
60
Dean Troyer1c425992014-07-28 17:51:13 -0500[diff] [blame]61 <p>The new header is similar to a normal INI section header but with double brackets (<code>[[ ... ]]</code>) and two internal fields separated by a pipe (<code>|</code>):</p>
Dean Troyer54b97322014-06-20 17:53:55 -0500[diff] [blame]62<pre>[[ &lt;phase&gt; | &lt;config-file-name&gt; ]]
63</pre>
64
65 <p>where <code>&lt;phase&gt;</code> is one of a set of phase names defined by <code>stack.sh</code> and <code>&lt;config-file-name&gt;</code> is the configuration filename. The filename is eval'ed in the <code>stack.sh</code> context so all environment variables are available and may be used. Using the project config file variables in the header is strongly suggested (see the <code>NOVA_CONF</code> example below). If the path of the config file does not exist it is skipped.</p>
66
67 <p>The defined phases are:</p>
68 <ul>
69 <li><strong>local</strong> - extracts <code>localrc</code> from <code>local.conf</code> before <code>stackrc</code> is sourced</li>
Dean Troyer1c425992014-07-28 17:51:13 -0500[diff] [blame]70 <li><strong>pre-install</strong> - runs after the system packages are installed but before any of the source repositories are installed</li>
71 <li><strong>install</strong> - runs immediately after the repo installations are complete</li>
Dean Troyer54b97322014-06-20 17:53:55 -0500[diff] [blame]72 <li><strong>post-config</strong> - runs after the layer 2 services are configured and before they are started</li>
73 <li><strong>extra</strong> - runs after services are started and before any files in <code>extra.d</code> are executed
74 </ul>
75
76 <p>The file is processed strictly in sequence; meta-sections may be specified more than once but if any settings are duplicated the last to appear in the file will be used.</p>
77<pre>[[post-config|$NOVA_CONF]]
78[DEFAULT]
79use_syslog = True
80
81[osapi_v3]
82enabled = False
83</pre>
84
85 <p>A specific meta-section <code>local|localrc</code> is used to
86 provide a default <code>localrc</code> file (actually
87 <code>.localrc.auto</code>). This allows all custom settings
88 for DevStack to be contained in a single file. If <code>localrc</code>
89 exists it will be used instead to preserve backward-compatibility. More
90 details on the <a href="localrc.html">contents of localrc</a> are available.</p>
91<pre>[[local|localrc]]
92FIXED_RANGE=10.254.1.0/24
93ADMIN_PASSWORD=speciale
94LOGFILE=$DEST/logs/stack.sh.log
95</pre>
96
97 <p>Note that <code>Q_PLUGIN_CONF_FILE</code> is unique in that it is assumed to <em>NOT</em> start with a <code>/</code> (slash) character. A slash will need to be added:</p>
98<pre>[[post-config|/$Q_PLUGIN_CONF_FILE]]
99</pre>
100
Dean Troyer1c425992014-07-28 17:51:13 -0500[diff] [blame]101 <p>Also note that the <code>localrc</code> section is sourced as a shell script fragment amd <string>MUST</strong> conform to the shell requirements, specifically no whitespace around <code>=</code> (equals).</p>
Dean Troyer54b97322014-06-20 17:53:55 -0500[diff] [blame]102
103 <a id="minimal"></a>
104 <h3>Minimal Configuration</h3>
105 <p>While <code>stack.sh</code> is happy to run without a <code>localrc</code> section in <code>local.conf</code>, devlife is better when there are a few minimal variables set. This is an example of a minimal configuration that touches the values that most often need to be set.</p>
106 <ul>
107 <li>no logging</li>
108 <li>pre-set the passwords to prevent interactive prompts</li>
109 <li>move network ranges away from the local network (<code>FIXED_RANGE</code> and <code>FLOATING_RANGE</code>, commented out below)</li>
110 <li>set the host IP if detection is unreliable (<code>HOST_IP</code>, commented out below)</li>
111 </ul>
112 <pre>[[local|localrc]]
113ADMIN_PASSWORD=secrete
114DATABASE_PASSWORD=$ADMIN_PASSWORD
115RABBIT_PASSWORD=$ADMIN_PASSWORD
116SERVICE_PASSWORD=$ADMIN_PASSWORD
117SERVICE_TOKEN=a682f596-76f3-11e3-b3b2-e716f9080d50
118#FIXED_RANGE=172.31.1.0/24
119#FLOATING_RANGE=192.168.20.0/25
120#HOST_IP=10.3.4.5</pre>
121 <p>If the <code>*_PASSWORD</code> variables are not set here you will be prompted to enter values for them by <code>stack.sh</code>.</p>
122 <p>The network ranges must not overlap with any networks in use on the host. Overlap is not uncommon as RFC-1918 'private' ranges are commonly used for both the local networking and Nova's fixed and floating ranges.</p>
123 <p><code>HOST_IP</code> is normally detected on the first run of <code>stack.sh</code> but often is indeterminate on later runs due to the IP being moved from an Ethernet integace to a bridge on the host. Setting it here also makes it available for <code>openrc</code> to set <code>OS_AUTH_URL</code>. <code>HOST_IP</code> is not set by default.</p>
124
125 <h3>Common Configuration Variables</h3>
126 <dl>
127 <dt>Set DevStack install directory</dt>
128 <dd><em>Default: <code>DEST=/opt/stack</code></em><br />
129 The DevStack install directory is set by the <code>DEST</code> variable. By setting it early in the <code>localrc</code> 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.
130 <pre>DEST=/opt/stack</pre></dd>
131
132 <dt>stack.sh logging</dt>
133 <dd><em>Defaults: <code>LOGFILE="" LOGDAYS=7 LOG_COLOR=True</code></em><br />
134 By default <code>stack.sh</code> output is only written to the console where is runs. It can be sent to a file in addition to the console by setting <code>LOGFILE</code> to the fully-qualified name of the destination log file. A timestamp will be appended to the given filename for each run of <code>stack.sh</code>.
135 <pre>LOGFILE=$DEST/logs/stack.sh.log</pre>
136 Old log files are cleaned automatically if <code>LOGDAYS</code> is set to the number of days of old log files to keep.
137 <pre>LOGDAYS=1</pre>
138 The some of the project logs (Nova, Cinder, etc) will be colorized by default (if <code>SYSLOG</code> is not set below); this can be turned off by setting <code>LOG_COLOR</code> False.
139 <pre>LOG_COLOR=False</pre></dd>
140
141 <dt>Screen logging</dt>
142 <dd><em>Default: <code>SCREEN_LOGDIR=""</code></em><br />
143 By default DevStack runs the OpenStack services using <code>screen</code> which is useful for watching log and debug output. However, in automated testing the interactive <code>screen</code> sessions may not be available after the fact; setting <code>SCREEN_LOGDIR</code> enables logging of the <code>screen</code> sessions in the specified diretory. There will be one file per <code>screen</code> session named for the session name and a timestamp.
144 <pre>SCREEN_LOGDIR=$DEST/logs/screen</pre>
145 <em>Note the use of <code>DEST</code> to locate the main install directory; this is why we suggest setting it in <code>local.conf</code>.</em></dd><br />
146
147 <dt>One syslog to bind them all</dt>
148 <dd><em>Default: <code>SYSLOG=False SYSLOG_HOST=$HOST_IP SYSLOG_PORT=516</code></em><br />
Davanum Srinivas690e3c22014-10-05 20:06:33 -0400[diff] [blame]149 Logging all services to a single syslog can be convenient. Enable syslogging by setting <code>SYSLOG</code> to <code>True</code>. If the destination log host is not localhost <code>SYSLOG_HOST</code> and <code>SYSLOG_PORT</code> can be used to direct the message stream to the log host.
Dean Troyer54b97322014-06-20 17:53:55 -0500[diff] [blame]150 <pre>SYSLOG=True
151SYSLOG_HOST=$HOST_IP
152SYSLOG_PORT=516</pre></dd>
153
154 <dt>A clean install every time</dt>
155 <dd><em>Default: <code>RECLONE=""</code></em><br />
156 By default <code>stack.sh</code> only clones the project repos if they do not exist in <code>$DEST</code>. <code>stack.sh</code> will freshen each repo on each run if <code>RECLONE</code> is set to <code>yes</code>. This avoids having to manually remove repos in order to get the current branch from <code>$GIT_BASE</code>.
157 <pre>RECLONE=yes</code></dd>
158
159 <dt>Swift</dt>
160 <dd><em>Default: <code>SWIFT_HASH="" SWIFT_REPLICAS=1 SWIFT_DATA_DIR=$DEST/data/swift</code></em><br />
161 Swift is now used as the back-end for the S3-like object store. When enabled Nova's objectstore (n-obj in <code>ENABLED_SERVICES</code>) is automatically disabled. Enable Swift by adding it services to <code>ENABLED_SERVICES</code>:
162 <pre>enable_service s-proxy s-object s-container s-account</pre>
163 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:
164 <pre>SWIFT_HASH=66a3d6b56c1f479c8b4e70ab5c2000f5</pre>
165 For development purposes the default number of replicas is set to <code>1</code> to reduce the overhead required. To better simulate a production deployment set this to <code>3</code> or more.
166 <pre>SWIFT_REPLICAS=3</pre>
167 The data for Swift is stored in the source tree by default
168 (in <code>$DEST/swift/data</code>) and can be moved by setting
169 <code>SWIFT_DATA_DIR</code>. The specified directory will be created if it does not exist.
170 <pre>SWIFT_DATA_DIR=$DEST/data/swift</pre>
171 <em>Note: Previously just enabling <code>swift</code> was sufficient to start the Swift services. That does not provide proper service granularity, particularly in multi-host configurations, and is considered deprecated. Some service combination tests now check for specific Swift services and the old blanket acceptance will longer work correctly.</em>
172 </dd>
173
174 <dt>Service Catalog Backend</dt>
175 <dd><em>Default: <code>KEYSTONE_CATALOG_BACKEND=sql</code></em><br />
176 DevStack uses Keystone's <code>sql</code> service catalog backend. An alternate <code>template</code> backend is also available. However, it does not support the <code>service-*</code> and <code>endpoint-*</code> commands of the <code>keystone</code> CLI. To
177 do so requires the <code>sql</code> backend be enabled:
178 <pre>KEYSTONE_CATALOG_BACKEND=template</pre>
179 DevStack's default configuration in <code>sql</code> mode is set in
180 <code>files/keystone_data.sh</code></dd>
181
182 <dt>Cinder</dt>
183 <dd><em>Default: <code>VOLUME_GROUP="stack-volumes" VOLUME_NAME_PREFIX="volume-" VOLUME_BACKING_FILE_SIZE=10250M</code></em><br />
184 The logical volume group used to hold the Cinder-managed volumes is set by <code>VOLUME_GROUP</code>, the logical volume name prefix is set with <code>VOLUME_NAME_PREFIX</code> and the size of the volume backing file is set with <code>VOLUME_BACKING_FILE_SIZE</code>.
185 <pre>VOLUME_GROUP="stack-volumes"
186VOLUME_NAME_PREFIX="volume-"
187VOLUME_BACKING_FILE_SIZE=10250M</pre></dd>
188
189 <dt>Multi-host DevStack</dt>
190 <dd><em>Default: <code>MULTI_HOST=False</code></em><br />
191 Running DevStack with multiple hosts requires a custom <code>local.conf</code> section for each host. The master is the same as a single host installation with <code>MULTI_HOST=True</code>. The slaves have fewer services enabled and a couple of host variables pointing to the master.
192 <br /><br />
193 <strong>Master</strong>
194 <pre>MULTI_HOST=True</pre>
195
196 <strong>Slave</strong>
197 <pre>MYSQL_HOST=w.x.y.z
198RABBIT_HOST=w.x.y.z
199GLANCE_HOSTPORT=w.x.y.z:9292
200ENABLED_SERVICES=n-vol,n-cpu,n-net,n-api</pre></dd>
201
202 <dt>API rate limits</dt>
203 <dd><em>Default: <code>API_RATE_LIMIT=True</code><br />
204 Integration tests such as Tempest will likely run afoul of the default rate limits configured for Nova. Turn off rate limiting during testing by setting <code>API_RATE_LIMIT=False</code>.
205 <pre>API_RATE_LIMIT=False</pre></dd>
206 </dl>
207
208 <h3>Examples</h3>
209 <ul>
Dean Troyer54b97322014-06-20 17:53:55 -0500[diff] [blame]210 <li>Eliminate a Cinder pass-through (<code>CINDER_PERIODIC_INTERVAL</code>):
211<pre>[[post-config|$CINDER_CONF]]
212[DEFAULT]
213periodic_interval = 60
214</pre></li>
215 <li>Sample <code>local.conf</code> with screen logging enabled:
216<pre>[[local|localrc]]
217FIXED_RANGE=10.254.1.0/24
218NETWORK_GATEWAY=10.254.1.1
219LOGDAYS=1
220LOGFILE=$DEST/logs/stack.sh.log
221SCREEN_LOGDIR=$DEST/logs/screen
222ADMIN_PASSWORD=quiet
223DATABASE_PASSWORD=$ADMIN_PASSWORD
224RABBIT_PASSWORD=$ADMIN_PASSWORD
225SERVICE_PASSWORD=$ADMIN_PASSWORD
226SERVICE_TOKEN=a682f596-76f3-11e3-b3b2-e716f9080d50</pre></li>
227 </ul>
228
229 </section>
230
231 <footer>
232 <p>&copy; Openstack Foundation 2011-2014 &mdash; An <a href="https://www.openstack.org/">OpenStack</a> <a href="https://wiki.openstack.org/wiki/Programs">program</a></p>
233 </footer>
234
235 </div> <!-- /container -->
236 </body>
237</html>