openstack/openstack-manuals
Code Issues Proposed changes

Cleanup section_nova-conf.xml

Browse Source 
With the addition of section_config_format, we can now remove
section_nova-conf.xml. It was the only section in the guide that
documented the INI format.

Move some content from section_nova-conf.xml to
section_config_format.xml and update both as appropriate.

Also, update section_config_format.xml to use spaces around "=" and to
not chunk the sections.

Change-Id: I41f6e919bf996cb28a6f1ca4425752a653a3f81f
This commit is contained in:
Andreas Jaeger 2014-04-29 19:42:39 +02:00
parent ceca7877d8
commit 59c11ea6a8
2 changed files with 98 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
doc/common/section_config_format.xml
View File

@ -4,6 +4,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<?dbhtml stop-chunking?>
<title>Configuration file format</title> <title>Configuration file format</title>
<para> <para>
@ -17,10 +18,16 @@
<programlisting language="ini">[DEFAULT] <programlisting language="ini">[DEFAULT]
# Print debugging output (set logging level to DEBUG instead # Print debugging output (set logging level to DEBUG instead
# of default WARNING level). (boolean value) # of default WARNING level). (boolean value)
debug=true debug = true
# Print more verbose output (set logging level to INFO instead # Print more verbose output (set logging level to INFO instead
# of default WARNING level). (boolean value) # of default WARNING level). (boolean value)
verbose=true</programlisting> verbose = true
[database]
# The SQLAlchemy connection string used to connect to the
# database (string value)
connection = mysql://keystone:<replaceable>KEYSTONE_DBPASS</replaceable>@<replaceable>controller</replaceable>/keystone</programlisting>
<para> <para>
Options can have different type for values. The comments in the Options can have different type for values. The comments in the
@ -37,7 +44,7 @@ verbose=true</programlisting>
</para> </para>
<programlisting language="ini"># Enable the experimental use of database reconnect on <programlisting language="ini"># Enable the experimental use of database reconnect on
# connection lost (boolean value) # connection lost (boolean value)
use_db_reconnect=false</programlisting> use_db_reconnect = false</programlisting>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
@ -48,7 +55,7 @@ use_db_reconnect=false</programlisting>
</para> </para>
<programlisting language="ini"># Sleep time in seconds for polling an ongoing async task <programlisting language="ini"># Sleep time in seconds for polling an ongoing async task
# (floating point value) # (floating point value)
task_poll_interval=0.5</programlisting> task_poll_interval = 0.5</programlisting>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
@ -60,7 +67,7 @@ task_poll_interval=0.5</programlisting>
</para> </para>
<programlisting language="ini"># The port which the OpenStack Compute service listens on. <programlisting language="ini"># The port which the OpenStack Compute service listens on.
# (integer value) # (integer value)
compute_port=8774</programlisting> compute_port = 8774</programlisting>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
@ -78,7 +85,7 @@ compute_port=8774</programlisting>
</para> </para>
<programlisting language="ini"># Modules of exceptions that are permitted to be recreated <programlisting language="ini"># Modules of exceptions that are permitted to be recreated
# upon receiving exception data from an rpc call. (list value) # upon receiving exception data from an rpc call. (list value)
allowed_rpc_exception_modules=oslo.messaging.exceptions,nova.exception,cinder.exception,exceptions</programlisting> allowed_rpc_exception_modules = oslo.messaging.exceptions,nova.exception,cinder.exception,exceptions</programlisting>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
@ -106,26 +113,56 @@ notification_driver = ceilometer.compute.nova_notifier</programlisting>
# systemd, one could set shell command: "onready = systemd- # systemd, one could set shell command: "onready = systemd-
# notify --ready" or a module with notify() method: "onready = # notify --ready" or a module with notify() method: "onready =
# keystone.common.systemd". (string value) # keystone.common.systemd". (string value)
onready=systemd-notify --ready onready = systemd-notify --ready
# If an instance is passed with the log message, format it # If an instance is passed with the log message, format it
# like this (string value) # like this (string value)
instance_format="[instance: %(uuid)s] "</programlisting> instance_format = "[instance: %(uuid)s] "</programlisting>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
<section xml:id="config_format_sections">
<title>Sections</title>
<para>
Configuration options are grouped by section. Most
configuration file supports at least the following sections:
<variablelist>
<varlistentry>
<term><literal>[DEFAULT]</literal></term>
<listitem>
<para>
Contains most configuration options. If the
documentation for a configuration option does not
specify its section, assume that it appears in this
section.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>[database]</literal></term>
<listitem>
<para>
Configuration options for the database that stores
the state of the OpenStack service.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<section xml:id="config_format_substitution"> <section xml:id="config_format_substitution">
<title>Substitution</title> <title>Substitution</title>
<para> <para>
Option values may reference other values using <link The configuration file supports variable substitution. After
xlink:href="http://legacy.python.org/dev/peps/pep-0292/">PEP you set a configuration option, it can be referenced in later
292</link> string substitution. An option can be referenced by configuration values when you precede it with a
adding a <literal>$</literal> in front of its name, like <literal>$</literal>, like
<literal>$OPTION</literal>. To avoid substitution, use <literal>$OPTION</literal>.
<literal>$$</literal>, it is replaced by a single
<literal>$</literal>.
</para> </para>
<para> <para>
The following example uses the values of The following example uses the values of
@ -136,15 +173,51 @@ instance_format="[instance: %(uuid)s] "</programlisting>
</para> </para>
<programlisting language="ini"># The RabbitMQ broker address where a single node is used. <programlisting language="ini"># The RabbitMQ broker address where a single node is used.
# (string value) # (string value)
rabbit_host=controller rabbit_host = controller
# The RabbitMQ broker port where a single node is used. # The RabbitMQ broker port where a single node is used.
# (integer value) # (integer value)
rabbit_port=5672 rabbit_port = 5672
# RabbitMQ HA cluster host:port pairs. (list value) # RabbitMQ HA cluster host:port pairs. (list value)
rabbit_hosts=$rabbit_host:$rabbit_port</programlisting> rabbit_hosts = $rabbit_host:$rabbit_port</programlisting>
<para>
To avoid substitution, use <literal>$$</literal>, it is replaced
by a single <literal>$</literal>. For example, if your LDAP DNS
password is <literal>$xkj432</literal>, specify it, as follows:
<programlisting language="ini">ldap_dns_password = $$xkj432</programlisting>
</para>
<para>
The code uses the Python
<literal>string.Template.safe_substitute()</literal> method to
implement variable substitution. For more details on how
variable substitution is resolved, see <link
xlink:href="http://docs.python.org/2/library/string.html#template-strings"
>http://docs.python.org/2/library/string.html#template-strings</link>
and <link xlink:href="http://www.python.org/dev/peps/pep-0292/"
>PEP 292</link>.
</para>
</section>
<section xml:id="config_format_whitespace">
<title>Whitespace</title>
<para>
To include whitespace in a configuration value, use a quoted
string. For example:</para>
<programlisting language="ini">ldap_dns_passsword='a password with spaces'</programlisting>
</section>
<section xml:id="config_format_alternate_location">
<title>Define an alternate location for a config file</title>
<para>
Most services and the and the <command>*-manage</command>
command-line clients load the configuration file. To define
an alternate location for the configuration file, pass the
<parameter>--config-file
<replaceable>CONFIG_FILE</replaceable></parameter> parameter
when you start a service or call a
<command>*-manage</command> command.
</para>
</section> </section>
</section> </section>

126
doc/config-reference/compute/section_nova-conf.xml
View File

@ -4,96 +4,29 @@
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Overview of nova.conf</title> <title>Overview of nova.conf</title>
<para>The <filename>nova.conf</filename> configuration file is <para>The <filename>nova.conf</filename> configuration file is
an <link xlink:href="https://en.wikipedia.org/wiki/INI_file" an <link xlink:href="https://en.wikipedia.org/wiki/INI_file"
>INI file format</link> file that specifies options as >INI file format</link> as explained in <xref
<literal>key=value</literal> pairs, which are grouped into linkend="config_format"/>.</para>
sections. The <literal>DEFAULT</literal> section contains most
of the configuration options. For example:</para>
<programlisting language="ini">[DEFAULT]
debug=true
verbose=true
[trusted_computing]
server=10.3.4.2</programlisting>
<para>You can use a particular configuration option file by using <para>You can use a particular configuration option file by using
the <literal>option</literal> (<filename>nova.conf</filename>) the <literal>option</literal> (<filename>nova.conf</filename>)
parameter when you run one of the <literal>nova-*</literal> parameter when you run one of the <literal>nova-*</literal>
services. This parameter inserts configuration option services. This parameter inserts configuration option
definitions from the specified configuration file name, which definitions from the specified configuration file name, which
might be useful for debugging or performance tuning.</para> might be useful for debugging or performance tuning.</para>
<para>To place comments in the <filename>nova.conf</filename> <para>For a list of configuration options, see the tables in this
file, start a new line that begins with the pound guide.</para>
(<literal>#</literal>) character. For a list of
configuration options, see the tables in this guide.</para>
<para>To learn more about the <filename>nova.conf</filename> <para>To learn more about the <filename>nova.conf</filename>
configuration file, review the general purpose configuration configuration file, review the general purpose configuration
options documented in <xref linkend="config_table_nova_common"/>.</para> options documented in <xref linkend="config_table_nova_common"/>.</para>
<simplesect>
<title>Types of configuration options</title>
<para>Each configuration option has an associated data type.
The supported data types for configuration options
are:</para>
<variablelist>
<varlistentry>
<term>BoolOpt</term>
<listitem>
<para>Boolean option. Value must be either
<literal>true</literal> or
<literal>false</literal> .
Example:<programlisting language="ini">debug=false</programlisting></para>
</listitem>
</varlistentry>
<varlistentry>
<term>StrOpt</term>
<listitem>
<para>String option. Value is an arbitrary string.
Example:<programlisting language="ini">my_ip=10.0.0.1</programlisting></para>
</listitem>
</varlistentry>
<varlistentry>
<term>IntOption</term>
<listitem>
<para>Integer option. Value must be an integer.
Example:
<programlisting language="ini">glance_port=9292</programlisting></para>
</listitem>
</varlistentry>
<varlistentry>
<term>MultiStrOpt</term>
<listitem>
<para>String option. Same as StrOpt, except that
it can be declared multiple times to indicate
multiple values. Example:</para>
<programlisting language="ini">ldap_dns_servers=dns1.example.org
ldap_dns_servers=dns2.example.org</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>ListOpt</term>
<listitem>
<para>List option. Value is a list of arbitrary
strings separated by commas. Example:</para>
<programlisting language="ini">enabled_apis=ec2,osapi_compute,metadata</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>FloatOpt</term>
<listitem>
<para>Floating-point option. Value must be a
floating-point number. Example:</para>
<programlisting language="ini">ram_allocation_ratio=1.5</programlisting>
</listitem>
</varlistentry>
</variablelist>
<important> <important>
<para>Do not specify quotes around Nova options.</para> <para>Do not specify quotes around Nova options.</para>
</important> </important>
</simplesect>
<simplesect> <simplesect>
<title>Sections</title> <title>Sections</title>
<para>Configuration options are grouped by section. The <para>Configuration options are grouped by section. The
Compute configuration file supports the following sections:<variablelist> Compute configuration file supports the following sections:
<variablelist>
<varlistentry> <varlistentry>
<term><literal>[DEFAULT]</literal></term> <term><literal>[DEFAULT]</literal></term>
<listitem> <listitem>
@ -141,49 +74,4 @@ ldap_dns_servers=dns2.example.org</programlisting>
</varlistentry> </varlistentry>
</variablelist></para> </variablelist></para>
</simplesect> </simplesect>
<simplesect>
<title>Variable substitution</title>
<para>The configuration file supports variable substitution.
After you set a configuration option, it can be referenced
in later configuration values when you precede it with
<literal>$</literal>. This example defines
<literal>my_ip</literal> and then uses
<literal>$my_ip</literal> as a
variable:<programlisting language="ini">my_ip=10.2.3.4
glance_host=$my_ip
metadata_host=$my_ip</programlisting></para>
<para>If a value must contain the <literal>$</literal>
character, escape it with <literal>$$</literal>. For
example, if your LDAP DNS password is
<literal>$xkj432</literal>, specify it, as
follows:<programlisting language="ini">ldap_dns_password=$$xkj432</programlisting></para>
<para>The Compute code uses the Python
<literal>string.Template.safe_substitute()</literal>
method to implement variable substitution. For more
details on how variable substitution is resolved, see
<link
xlink:href="http://docs.python.org/2/library/string.html#template-strings"
>http://docs.python.org/2/library/string.html#template-strings</link>
and <link
xlink:href="http://www.python.org/dev/peps/pep-0292/"
>http://www.python.org/dev/peps/pep-0292/</link>.</para>
</simplesect>
<simplesect>
<title>Whitespace</title>
<para>To include whitespace in a configuration value, use a
quoted string. For example:</para>
<programlisting language="ini">ldap_dns_passsword='a password with spaces'</programlisting>
</simplesect>
<simplesect>
<title>Define an alternate location for nova.conf</title>
<para>All <systemitem class="service">nova-*</systemitem>
services and the <command>nova-manage</command>
command-line client load the configuration file. To define
an alternate location for the configuration file, pass the
<parameter>--config-file
<replaceable>/path/to/nova.conf</replaceable></parameter>
parameter when you start a <systemitem class="service"
>nova-*</systemitem> service or call a
<command>nova-manage</command> command.</para>
</simplesect>
</section> </section>