| 1 |
========================= |
| 2 |
Configuration file format |
| 3 |
========================= |
| 4 |
|
| 5 |
OpenStack uses the INI file format for configuration files. |
| 6 |
An INI file is a simple text file that specifies options as |
| 7 |
``key=value`` pairs, grouped into sections. |
| 8 |
The ``DEFAULT`` section contains most of the configuration options. |
| 9 |
Lines starting with a hash sign (``#``) are comment lines. |
| 10 |
For example: |
| 11 |
|
| 12 |
.. code-block:: ini |
| 13 |
|
| 14 |
[DEFAULT] |
| 15 |
# Print debugging output (set logging level to DEBUG instead |
| 16 |
# of default WARNING level). (boolean value) |
| 17 |
debug = true |
| 18 |
|
| 19 |
[database] |
| 20 |
# The SQLAlchemy connection string used to connect to the |
| 21 |
# database (string value) |
| 22 |
connection = mysql+pymysql://keystone:KEYSTONE_DBPASS@controller/keystone |
| 23 |
|
| 24 |
Options can have different types for values. |
| 25 |
The comments in the sample config files always mention these and the |
| 26 |
tables mention the ``Opt`` value as first item like ``(BoolOpt) Toggle...``. |
| 27 |
The following types are used by OpenStack: |
| 28 |
|
| 29 |
boolean value (``BoolOpt``) |
| 30 |
Enables or disables an option. The allowed values are ``true`` and ``false``. |
| 31 |
|
| 32 |
.. code-block:: ini |
| 33 |
|
| 34 |
# Enable the experimental use of database reconnect on |
| 35 |
# connection lost (boolean value) |
| 36 |
use_db_reconnect = false |
| 37 |
|
| 38 |
floating point value (``FloatOpt``) |
| 39 |
A floating point number like ``0.25`` or ``1000``. |
| 40 |
|
| 41 |
.. code-block:: ini |
| 42 |
|
| 43 |
# Sleep time in seconds for polling an ongoing async task |
| 44 |
# (floating point value) |
| 45 |
task_poll_interval = 0.5 |
| 46 |
|
| 47 |
integer value (``IntOpt``) |
| 48 |
An integer number is a number without fractional components, |
| 49 |
like ``0`` or ``42``. |
| 50 |
|
| 51 |
.. code-block:: ini |
| 52 |
|
| 53 |
# The port which the OpenStack Compute service listens on. |
| 54 |
# (integer value) |
| 55 |
compute_port = 8774 |
| 56 |
|
| 57 |
IP address (``IPOpt``) |
| 58 |
An IPv4 or IPv6 address. |
| 59 |
|
| 60 |
.. code-block:: ini |
| 61 |
|
| 62 |
# Address to bind the server. Useful when selecting a particular network |
| 63 |
# interface. (ip address value) |
| 64 |
bind_host = 0.0.0.0 |
| 65 |
|
| 66 |
key-value pairs (``DictOpt``) |
| 67 |
A key-value pairs, also known as a dictionary. The key value pairs are |
| 68 |
separated by commas and a colon is used to separate key and value. |
| 69 |
Example: ``key1:value1,key2:value2``. |
| 70 |
|
| 71 |
.. code-block:: ini |
| 72 |
|
| 73 |
# Parameter for l2_l3 workflow setup. (dict value) |
| 74 |
l2_l3_setup_params = data_ip_address:192.168.200.99, \ |
| 75 |
data_ip_mask:255.255.255.0,data_port:1,gateway:192.168.200.1,ha_port:2 |
| 76 |
|
| 77 |
list value (``ListOpt``) |
| 78 |
Represents values of other types, separated by commas. |
| 79 |
As an example, the following sets ``allowed_rpc_exception_modules`` |
| 80 |
to a list containing the four elements ``oslo.messaging.exceptions``, |
| 81 |
``nova.exception``, ``cinder.exception``, and ``exceptions``: |
| 82 |
|
| 83 |
.. code-block:: ini |
| 84 |
|
| 85 |
# Modules of exceptions that are permitted to be recreated |
| 86 |
# upon receiving exception data from an rpc call. (list value) |
| 87 |
allowed_rpc_exception_modules = oslo.messaging.exceptions,nova.exception |
| 88 |
|
| 89 |
multi valued (``MultiStrOpt``) |
| 90 |
A multi-valued option is a string value and can be given |
| 91 |
more than once, all values will be used. |
| 92 |
|
| 93 |
.. code-block:: ini |
| 94 |
|
| 95 |
# Driver or drivers to handle sending notifications. (multi valued) |
| 96 |
notification_driver = nova.openstack.common.notifier.rpc_notifier |
| 97 |
notification_driver = ceilometer.compute.nova_notifier |
| 98 |
|
| 99 |
port value (``PortOpt``) |
| 100 |
A TCP/IP port number. Ports can range from 1 to 65535. |
| 101 |
|
| 102 |
.. code-block:: ini |
| 103 |
|
| 104 |
# Port to which the UDP socket is bound. (port value) |
| 105 |
# Minimum value: 1 |
| 106 |
# Maximum value: 65535 |
| 107 |
udp_port = 4952 |
| 108 |
|
| 109 |
string value (``StrOpt``) |
| 110 |
Strings can be optionally enclosed with single or double quotes. |
| 111 |
|
| 112 |
.. code-block:: ini |
| 113 |
|
| 114 |
# The format for an instance that is passed with the log message. |
| 115 |
# (string value) |
| 116 |
instance_format = "[instance: %(uuid)s] " |
| 117 |
|
| 118 |
Sections |
| 119 |
~~~~~~~~ |
| 120 |
|
| 121 |
Configuration options are grouped by section. |
| 122 |
Most configuration files support at least the following sections: |
| 123 |
|
| 124 |
[DEFAULT] |
| 125 |
Contains most configuration options. |
| 126 |
If the documentation for a configuration option does not |
| 127 |
specify its section, assume that it appears in this section. |
| 128 |
|
| 129 |
[database] |
| 130 |
Configuration options for the database that stores |
| 131 |
the state of the OpenStack service. |
| 132 |
|
| 133 |
Substitution |
| 134 |
~~~~~~~~~~~~ |
| 135 |
|
| 136 |
The configuration file supports variable substitution. |
| 137 |
After you set a configuration option, it can be referenced |
| 138 |
in later configuration values when you precede it with |
| 139 |
a ``$``, like ``$OPTION``. |
| 140 |
|
| 141 |
The following example uses the values of ``rabbit_host`` and |
| 142 |
``rabbit_port`` to define the value of the ``rabbit_hosts`` |
| 143 |
option, in this case as ``controller:5672``. |
| 144 |
|
| 145 |
.. code-block:: ini |
| 146 |
|
| 147 |
# The RabbitMQ broker address where a single node is used. |
| 148 |
# (string value) |
| 149 |
rabbit_host = controller |
| 150 |
|
| 151 |
# The RabbitMQ broker port where a single node is used. |
| 152 |
# (integer value) |
| 153 |
rabbit_port = 5672 |
| 154 |
|
| 155 |
# RabbitMQ HA cluster host:port pairs. (list value) |
| 156 |
rabbit_hosts = $rabbit_host:$rabbit_port |
| 157 |
|
| 158 |
To avoid substitution, escape the ``$`` with ``$$`` or ``\$``. |
| 159 |
For example, if your LDAP DNS password is ``$xkj432``, specify it, as follows: |
| 160 |
|
| 161 |
.. code-block:: ini |
| 162 |
|
| 163 |
ldap_dns_password = $$xkj432 |
| 164 |
|
| 165 |
The code uses the Python ``string.Template.safe_substitute()`` |
| 166 |
method to implement variable substitution. |
| 167 |
For more details on how variable substitution is resolved, see |
| 168 |
https://docs.python.org/2/library/string.html#template-strings |
| 169 |
and `PEP 292 <https://www.python.org/dev/peps/pep-0292/>`_. |
| 170 |
|
| 171 |
Whitespace |
| 172 |
~~~~~~~~~~ |
| 173 |
|
| 174 |
To include whitespace in a configuration value, use a quoted string. |
| 175 |
For example: |
| 176 |
|
| 177 |
.. code-block:: ini |
| 178 |
|
| 179 |
ldap_dns_password='a password with spaces' |
| 180 |
|
| 181 |
Define an alternate location for a config file |
| 182 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 183 |
|
| 184 |
Most services and the ``*-manage`` command-line clients load |
| 185 |
the configuration file. |
| 186 |
To define an alternate location for the configuration file, |
| 187 |
pass the ``--config-file CONFIG_FILE`` parameter |
| 188 |
when you start a service or call a ``*-manage`` command. |