openstack-manuals/doc/common/section_config_format.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"># Enables or disables publication of error events. (boolean value)
publish_errors = false

# The format for an instance that is passed with the log message.
# (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>