src/ceph/doc/dev/config.rst

   1 =================================
   2  Configuration Management System
   3 =================================
   4
   5 The configuration management system exists to provide every daemon with the
   6 proper configuration information. The configuration can be viewed as a set of
   7 key-value pairs.
   8
   9 How can the configuration be set? Well, there are several sources:
  10  - the ceph configuration file, usually named ceph.conf
  11  - command line arguments::
  12     --debug-ms=1
  13     --debug-pg=10
  14     etc.
  15  - arguments injected at runtime by using injectargs
  16
  17
  18 The Configuration File
  19 ======================
  20
  21 Most configuration settings originate in the Ceph configuration file.
  22
  23 How do we find the configuration file? Well, in order, we check:
  24  - the default locations
  25  - the environment variable CEPH_CONF
  26  - the command line argument -c
  27
  28 Each stanza of the configuration file describes the key-value pairs that will be in
  29 effect for a particular subset of the daemons. The "global" stanza applies to
  30 everything. The "mon", "osd", and "mds" stanzas specify settings to take effect
  31 for all monitors, all OSDs, and all mds servers, respectively.  A stanza of the
  32 form mon.$name, osd.$name, or mds.$name gives settings for the monitor, OSD, or
  33 MDS of that name, respectively. Configuration values that appear later in the
  34 file win over earlier ones.
  35
  36 A sample configuration file can be found in src/sample.ceph.conf.
  37
  38
  39 Metavariables
  40 =============
  41
  42 The configuration system allows any configuration value to be
  43 substituted into another value using the ``$varname`` syntax, similar
  44 to how bash shell expansion works.
  45
  46 A few additional special metavariables are also defined:
  47  - $host: expands to the current hostname
  48  - $type: expands to one of "mds", "osd", "mon", or "client"
  49  - $id: expands to the daemon identifier. For ``osd.0``, this would be ``0``; for ``mds.a``, it would be ``a``; for ``client.admin``, it would be ``admin``.
  50  - $num: same as $id
  51  - $name: expands to $type.$id
  52
  53
  54 Reading configuration values
  55 ====================================================
  56
  57 There are two ways for Ceph code to get configuration values. One way is to
  58 read it directly from a variable named "g_conf," or equivalently,
  59 "g_ceph_ctx->_conf." The other is to register an observer that will be called
  60 every time the relevant configuration values changes. This observer will be
  61 called soon after the initial configuration is read, and every time after that
  62 when one of the relevant values changes. Each observer tracks a set of keys
  63 and is invoked only when one of the relevant keys changes.
  64
  65 The interface to implement is found in common/config_obs.h.
  66
  67 The observer method should be preferred in new code because
  68  - It is more flexible, allowing the code to do whatever reinitialization needs
  69    to be done to implement the new configuration value.
  70  - It is the only way to create a std::string configuration variable that can
  71    be changed by injectargs.
  72  - Even for int-valued configuration options, changing the values in one thread
  73    while another thread is reading them can lead to subtle and
  74    impossible-to-diagnose bugs.
  75
  76 For these reasons, reading directly from g_conf should be considered deprecated
  77 and not done in new code.  Do not ever alter g_conf.
  78
  79 Changing configuration values
  80 ====================================================
  81
  82 Configuration values can be changed by calling g_conf->set_val. After changing
  83 the configuration, you should call g_conf->apply_changes to re-run all the
  84 affected configuration observers. For convenience, you can call
  85 g_conf->set_val_or_die to make a configuration change which you think should
  86 never fail.
  87
  88 Injectargs, parse_argv, and parse_env are three other functions which modify
  89 the configuration. Just like with set_val, you should call apply_changes after
  90 calling these functions to make sure your changes get applied.
  91
  92
  93 Defining config options
  94 =======================
  95
  96 New-style config options are defined in common/options.cc. All new config
  97 options should go here (and not into legacy_config_opts.h).
  98
  99 Levels
 100 ------
 101
 102 The Option constructor takes a "level" value:
 103
 104 * *LEVEL_BASIC* is for basic config options that a normal operator is likely to adjust.
 105 * *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.
 106 * *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.
 107
 108 Description and long description
 109 --------------------------------
 110
 111 Short description of the option. Sentence fragment. e.g.::
 112
 113   .set_description("Default checksum algorithm to use")
 114
 115 The long description is complete sentences, perhaps even multiple
 116 paragraphs, and may include other detailed information or notes.::
 117
 118   .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.")
 119
 120 Default values
 121 --------------
 122
 123 There is a default value for every config option. In some cases, there may
 124 also be a *daemon default* that only applies to code that declares itself
 125 as a daemon (in thise case, the regular default only applies to non-daemons).
 126
 127 Safety
 128 ------
 129
 130 If an option can be safely changed at runtime::
 131
 132   .set_safe()
 133
 134 Service
 135 -------
 136
 137 Service is a component name, like "common", "osd", "rgw", "mds", etc. It may
 138 be a list of components, like::
 139
 140   .add_service("mon mds osd mgr")
 141
 142 For example, the rocksdb options affect both the osd and mon.
 143
 144 Tags
 145 ----
 146
 147 Tags identify options across services that relate in some way. Example include;
 148
 149   - network -- options affecting network configuration
 150   - mkfs -- options that only matter at mkfs time
 151
 152 Enums
 153 -----
 154
 155 For options with a defined set of allowed values::
 156
 157   .set_enum_allowed({"none", "crc32c", "crc32c_16", "crc32c_8", "xxhash32", "xxhash64"})