From eceed56b95aff4b83926217e9f16bafa2bd09981 Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Wed, 26 Jun 2019 16:50:55 +0800 Subject: [PATCH] doc/rados/configuration: update to be in sync with ConfUtils changes Signed-off-by: Kefu Chai --- doc/rados/configuration/ceph-conf.rst | 74 +++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/doc/rados/configuration/ceph-conf.rst b/doc/rados/configuration/ceph-conf.rst index 5b7264a8c76..ef1b8713260 100644 --- a/doc/rados/configuration/ceph-conf.rst +++ b/doc/rados/configuration/ceph-conf.rst @@ -166,6 +166,9 @@ if the same option is specified in both ``global``, ``mon``, and ``mon.foo`` on the same source (i.e., in the same configurationfile), the ``mon.foo`` value will be used. +If multiple values of the same configuration option are specified in the same +section, the last value wins. + Note that values from the local configuration file always take precedence over values from the monitor configuration database, regardless of which section they appear in. @@ -277,6 +280,49 @@ surrounded by square brackets. For example, debug ms = 10 +Config file option values +------------------------- + +The value of a configuration option is a string. If it is too long to +fit in a single line, you can put a backslash (``\``) at the end of line +as the line continuation marker, so the value of the option will be +the string after ``=`` in current line combined with the string in the next +line:: + + [global] + foo = long long ago\ + long ago + +In the example above, the value of "``foo``" would be "``long long ago long ago``". + +Normally, the option value ends with a new line, or a comment, like + +.. code-block:: ini + + [global] + obscure one = difficult to explain # I will try harder in next release + simpler one = nothing to explain + +In the example above, the value of "``obscure one``" would be "``difficult to explain``"; +and the value of "``simpler one`` would be "``nothing to explain``". + +If an option value contains spaces, and we want to make it explicit, we +could quote the value using single or double quotes, like + +.. code-block:: ini + + [global] + line = "to be, or not to be" + +Certain characters are not allowed to be present in the option values directly. +They are ``=``, ``#``, ``;`` and ``[``. If we have to, we need to escape them, +like + +.. code-block:: ini + + [global] + secret = "i love \# and \[" + Monitor configuration database ============================== @@ -489,3 +535,31 @@ will report the value of a single option. +Changes since nautilus +====================== + +We changed the way the configuration file is parsed in Octopus. The changes are +listed as follows: + +- repeated configuration options are allowed, and no warnings will be printed. + The value of the last one wins. Before this change, we would print out warning + messages at seeing lines with duplicated values, like:: + + warning line 42: 'foo' in section 'bar' redefined +- invalid UTF-8 options are ignored with warning messages. But since Octopus, + they are treated as fatal errors. +- backslash ``\`` is used as the line continuation marker to combine the next + line with current one. Before Octopus, it was required to follow backslash with + non-empty line. But in Octopus, empty line following backslash is now allowed. +- In the configuration file, each line specifies an individual configuration + option. The option's name and its value are separated with ``=``. And the + value can be quoted using single or double quotes. But if an invalid + configuration is specified, we will treat it as an invalid configuration + file :: + + bad option ==== bad value +- Before Octopus, if no section name was specified in the configuration file, + all options would be grouped into the section of ``global``. But this is + discouraged now. Since Octopus, only a single option is allowed for + configuration files without a section name. + -- 2.39.5