6d9d70f3ee
As discussed in the Liberty Design Summit "Moving apps to Python 3" cross-project workshop, the way forward in the near future is to switch to the pure-python PyMySQL library as a default. https://etherpad.openstack.org/p/liberty-cross-project-python3 This change handles only common files and Config Reference. Change-Id: I8d60ec2ca85c3099fc39c293ada0a78fffb28599
225 lines
8.3 KiB
XML
225 lines
8.3 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
version="5.0"
|
|
xml:id="config_format">
|
|
|
|
<?dbhtml stop-chunking?>
|
|
<title>Configuration file format</title>
|
|
|
|
<para>
|
|
OpenStack uses the <glossterm>INI</glossterm> file format for
|
|
configuration files. An INI file is a simple text file that
|
|
specifies options as <literal>key=value</literal> pairs,
|
|
grouped into sections. The <literal>DEFAULT</literal> section
|
|
contains most of the configuration options. Lines starting with a
|
|
hash sign (<literal>#</literal>) are comment lines. For example:
|
|
</para>
|
|
<programlisting language="ini">[DEFAULT]
|
|
# Print debugging output (set logging level to DEBUG instead
|
|
# of default WARNING level). (boolean value)
|
|
debug = true
|
|
# Print more verbose output (set logging level to INFO instead
|
|
# of default WARNING level). (boolean value)
|
|
verbose = true
|
|
|
|
[database]
|
|
# The SQLAlchemy connection string used to connect to the
|
|
# database (string value)
|
|
connection = mysql+pymysql://keystone:<replaceable>KEYSTONE_DBPASS</replaceable>@<replaceable>controller</replaceable>/keystone</programlisting>
|
|
|
|
|
|
<para>
|
|
Options can have different types for values. The comments in the
|
|
sample config files always mention these. The following types are
|
|
used by OpenStack:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>boolean value</term>
|
|
<listitem>
|
|
<para>
|
|
Enables or disables an option. The allowed values are
|
|
<literal>true</literal> and <literal>false</literal>.
|
|
</para>
|
|
<programlisting language="ini"># Enable the experimental use of database reconnect on
|
|
# connection lost (boolean value)
|
|
use_db_reconnect = false</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>floating point value</term>
|
|
<listitem>
|
|
<para>A floating point number like <literal>0.25</literal>
|
|
or <literal>1000</literal>.
|
|
</para>
|
|
<programlisting language="ini"># Sleep time in seconds for polling an ongoing async task
|
|
# (floating point value)
|
|
task_poll_interval = 0.5</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>integer value</term>
|
|
<listitem>
|
|
<para>
|
|
An integer number is a number without fractional components,
|
|
like <literal>0</literal> or <literal>42</literal>.
|
|
</para>
|
|
<programlisting language="ini"># The port which the OpenStack Compute service listens on.
|
|
# (integer value)
|
|
compute_port = 8774</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>list value</term>
|
|
<listitem>
|
|
<para>
|
|
Represents values of other types, separated by commas. As an
|
|
example, the following sets
|
|
<option>allowed_rpc_exception_modules</option> to a list
|
|
containing the four elements
|
|
<literal>oslo.messaging.exceptions</literal>,
|
|
<literal>nova.exception</literal>,
|
|
<literal>cinder.exception</literal>, and
|
|
<literal>exceptions</literal>:
|
|
</para>
|
|
<programlisting language="ini"># Modules of exceptions that are permitted to be recreated
|
|
# upon receiving exception data from an rpc call. (list value)
|
|
allowed_rpc_exception_modules = oslo.messaging.exceptions,nova.exception,cinder.exception,exceptions</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>multi valued</term>
|
|
<listitem>
|
|
<para>
|
|
A multi-valued option is a string value and can be given
|
|
more than once, all values will be used.
|
|
</para>
|
|
<programlisting language="ini"># Driver or drivers to handle sending notifications. (multi
|
|
# valued)
|
|
notification_driver = nova.openstack.common.notifier.rpc_notifier
|
|
notification_driver = ceilometer.compute.nova_notifier</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>string value</term>
|
|
<listitem>
|
|
<para>
|
|
Strings can be optionally enclosed with single or double
|
|
quotes.
|
|
</para>
|
|
<programlisting language="ini"># onready allows you to send a notification when the process
|
|
# is ready to serve. For example, to have it notify using
|
|
# systemd, one could set shell command: "onready = systemd-
|
|
# notify --ready" or a module with notify() method: "onready =
|
|
# keystone.common.systemd". (string value)
|
|
onready = systemd-notify --ready
|
|
|
|
# If an instance is passed with the log message, format it
|
|
# like this (string value)
|
|
instance_format = "[instance: %(uuid)s] "</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
|
|
<section xml:id="config_format_sections">
|
|
<title>Sections</title>
|
|
<para>
|
|
Configuration options are grouped by section. Most
|
|
configuration files support 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">
|
|
<title>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 a
|
|
<literal>$</literal>, like
|
|
<literal>$OPTION</literal>.
|
|
</para>
|
|
<para>
|
|
The following example uses the values of
|
|
<literal>rabbit_host</literal> and
|
|
<literal>rabbit_port</literal> to define the value of the
|
|
<literal>rabbit_hosts</literal> option, in this case as
|
|
<literal>controller:5672</literal>.
|
|
</para>
|
|
<programlisting language="ini"># The RabbitMQ broker address where a single node is used.
|
|
# (string value)
|
|
rabbit_host = controller
|
|
|
|
# The RabbitMQ broker port where a single node is used.
|
|
# (integer value)
|
|
rabbit_port = 5672
|
|
|
|
# RabbitMQ HA cluster host:port pairs. (list value)
|
|
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 <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>
|