From e31f8e1253d0c96a9412aef004ab0f1e001ae02e Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Wed, 18 Aug 2021 17:33:26 +0800 Subject: [PATCH] doc/dev/config: update to in sync with latest .yaml.in changes we migrated to a build process which translate the options from .yaml.in files. so update the document to reflect this change. Signed-off-by: Kefu Chai --- doc/dev/config.rst | 197 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 154 insertions(+), 43 deletions(-) diff --git a/doc/dev/config.rst b/doc/dev/config.rst index f54d30eb002fe..46ee66280478e 100644 --- a/doc/dev/config.rst +++ b/doc/dev/config.rst @@ -15,7 +15,7 @@ How can the configuration be set? Well, there are several sources: --debug-pg=10 etc. - - arguments injected at runtime using "injectargs" or "config set" + - arguments injected at runtime using ``injectargs`` or ``config set`` The Configuration File @@ -26,14 +26,14 @@ Most configuration settings originate in the Ceph configuration file. How do we find the configuration file? Well, in order, we check: - the default locations - - the environment variable CEPH_CONF - - the command line argument -c + - the environment variable ``CEPH_CONF`` + - the command line argument ``-c`` Each stanza of the configuration file describes the key-value pairs that will be in effect for a particular subset of the daemons. The "global" stanza applies to everything. The "mon", "osd", and "mds" stanzas specify settings to take effect for all monitors, all OSDs, and all mds servers, respectively. A stanza of the -form mon.$name, osd.$name, or mds.$name gives settings for the monitor, OSD, or +form ``mon.$name``, ``osd.$name``, or ``mds.$name`` gives settings for the monitor, OSD, or MDS of that name, respectively. Configuration values that appear later in the file win over earlier ones. @@ -60,14 +60,14 @@ Reading configuration values ==================================================== There are two ways for Ceph code to get configuration values. One way is to -read it directly from a variable named "g_conf," or equivalently, -"g_ceph_ctx->_conf." The other is to register an observer that will be called +read it directly from a variable named ``g_conf``, or equivalently, +``g_ceph_ctx->_conf``. The other is to register an observer that will be called every time the relevant configuration values changes. This observer will be called soon after the initial configuration is read, and every time after that when one of the relevant values changes. Each observer tracks a set of keys and is invoked only when one of the relevant keys changes. -The interface to implement is found in common/config_obs.h. +The interface to implement is found in ``common/config_obs.h``. The observer method should be preferred in new code because @@ -79,8 +79,8 @@ The observer method should be preferred in new code because while another thread is reading them can lead to subtle and impossible-to-diagnose bugs. -For these reasons, reading directly from g_conf should be considered deprecated -and not done in new code. Do not ever alter g_conf. +For these reasons, reading directly from ``g_conf`` should be considered deprecated +and not done in new code. Do not ever alter ``g_conf``. Changing configuration values ==================================================== @@ -91,7 +91,7 @@ affected configuration observers. For convenience, you can call ``g_conf()->set_val_or_die`` to make a configuration change which you think should never fail. -Injectargs, parse_argv, and parse_env are three other functions which modify +``injectargs``, ``parse_argv``, and ``parse_env`` are three other functions which modify the configuration. Just like with set_val, you should call apply_changes after calling these functions to make sure your changes get applied. @@ -99,74 +99,185 @@ calling these functions to make sure your changes get applied. Defining config options ======================= -New-style config options are defined in common/options.cc. All new config -options should go here (and not into legacy_config_opts.h). +Config options are defined in ``common/options/*.yaml.in``. The options are categorized +by their consumers. If an option is only used by ceph-osd, it should go to +``osd.yaml.in``. All the ``.yaml.in`` files are translated into ``.cc`` and ``.h`` files +at build time by ``y2c.py``. + +Each option is represented using a YAML mapping (dictionary). A typical option looks like + +.. code-block:: yaml + + - name: public_addr + type: addr + level: basic + desc: public-facing address to bind to + long_desc: The IP address for the public (front-side) network. + Set for each daemon. + services: + - mon + - mds + - osd + - mgr + flags: + - startup + with_legacy: true + +In which, following keys are allowed: + +level +----- + +The ``level`` property of an option is an indicator for the probability the +option is adjusted by an operator or a developer: + +.. describe:: basic + + for basic config options that a normal operator is likely to adjust. + +.. describe:: advanced + + for options that an operator *can* adjust, but should not touch unless they + understand what they are doing. Adjusting advanced options poorly can lead to + problems (performance or even data loss) if done incorrectly. + +.. describe:: dev + + for options in place for use by developers only, either for testing purposes, + or to describe constants that no user should adjust but we prefer not to compile + into the code. -Levels ------- +``desc``, ``long_desc`` and ``fmt_desc`` +---------------------------------------- -The Option constructor takes a "level" value: +.. describe:: desc -* *LEVEL_BASIC* is for basic config options that a normal operator is likely to adjust. -* *LEVEL_ADVANCED* is for options that an operator *can* adjust, but should not touch unless they understand what they are doing. Adjusting advanced options poorly can lead to problems (performance or even data loss) if done incorrectly. -* *LEVEL_DEV* is for options in place for use by developers only, either for testing purposes, or to describe constants that no user should adjust but we prefer not to compile into the code. + Short description of the option. Sentence fragment. e.g. -Description and long description --------------------------------- + .. code-block:: yaml -Short description of the option. Sentence fragment. e.g.:: + desc: Default checksum algorithm to use - .set_description("Default checksum algorithm to use") +.. describe:: long_desc -The long description is complete sentences, perhaps even multiple -paragraphs, and may include other detailed information or notes.:: + The long description is complete sentences, perhaps even multiple + paragraphs, and may include other detailed information or notes. e.g. - .set_long_description("crc32c, xxhash32, and xxhash64 are available. The _16 and _8 variants use only a subset of the bits for more compact (but less reliable) checksumming.") + .. code-block:: yaml + + long_desc: crc32c, xxhash32, and xxhash64 are available. The _16 and _8 variants use + only a subset of the bits for more compact (but less reliable) checksumming. + +.. describe:: fmt_desc + + The description formatted using reStructuredText. This property is + only used by the ``confval`` directive to render an option in the + document. e.g.: + + .. code-block:: yaml + + fmt_desc: The interval for "deep" scrubbing (fully reading all data). The + ``osd_scrub_load_threshold`` does not affect this setting. Default values -------------- There is a default value for every config option. In some cases, there may also be a *daemon default* that only applies to code that declares itself -as a daemon (in this case, the regular default only applies to non-daemons). +as a daemon (in this case, the regular default only applies to non-daemons). Like: + +.. code-block:: yaml + + default: crc32c -Safety ------- +Some literal postfixes are allowed when options with type of ``float``, ``size`` +and ``secs``, like: -If an option can be safely changed at runtime:: +.. code-block:: yaml - .set_safe() + - name: mon_scrub_interval + type: secs + default: 1_day + - name: osd_journal_size + type: size + default: 5_K + +For better readability, it is encouraged to use these literal postfixes when +adding or updating the default value for an option. Service ------- Service is a component name, like "common", "osd", "rgw", "mds", etc. It may -be a list of components, like:: +be a list of components, like: + +.. code-block:: yaml - .add_service("mon mds osd mgr") + services: + - mon + - mds + - osd + - mgr -For example, the rocksdb options affect both the osd and mon. +For example, the rocksdb options affect both the osd and mon. If an option is put +into a service specific ``.yaml.in`` file, the corresponding service is added to +its ``services`` property automatically. For instance, ``osd_scrub_begin_hour`` +option is located in ``osd.yaml.in``, even its ``services`` is not specified +explicitly in this file, this property still contains ``osd``. Tags ---- -Tags identify options across services that relate in some way. Example include; +Tags identify options across services that relate in some way. For example: + +network + options affecting network configuration +mkfs + options that only matter at mkfs time + +Like: - - network -- options affecting network configuration - - mkfs -- options that only matter at mkfs time +.. code-block:: yaml + + tags: + - network Enums ----- -For options with a defined set of allowed values:: +For options with a defined set of allowed values: + +.. code-block:: yaml - .set_enum_allowed({"none", "crc32c", "crc32c_16", "crc32c_8", "xxhash32", "xxhash64"}) + enum_values: + - none + - crc32c + - crc32c_16 + - crc32c_8 + - xxhash32 + - xxhash64 Flags ----- -* **RUNTIME**: the value can be updated at runtime -* **NO_MON_UPDATE**: Daemons/clients do not pull this value from the monitor config database. We disallow setting this option via 'ceph config set ...'. This option should be configured via ceph.conf or via the command line. -* **STARTUP**: option takes effect only during daemon startup -* **CLUSTER_CREATE**: option only affects cluster creation -* **CREATE**: option only affects daemon creation +.. describe:: runtime + + the value can be updated at runtime + +.. describe:: no_mon_update + + Daemons/clients do not pull this value from the monitor config database. We + disallow setting this option via ``ceph config set ...``. This option should + be configured via ``ceph.conf`` or via the command line. + +.. describe:: startup + + option takes effect only during daemon startup + +.. describe:: cluster_create + + option only affects cluster creation + +.. describe:: create + + option only affects daemon creation -- 2.39.5