Debian Codegraph @

doc/source/configuration/format.rst

raw
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.