Bootstrap options
-----------------
-Because some configuration options affect the process's ability to
-contact the monitors, authenticate, and retrieve the cluster-stored
-configuration, they may need to be stored locally on the node and set
-in a local configuration file. These options include:
-
- - ``mon_host``, the list of monitors for the cluster
- - ``mon_host_override``, the list of monitors for the cluster to
- **initially** contact when beginning a new instance of communication with the
- Ceph cluster. This overrides the known monitor list derived from MonMap
- updates sent to older Ceph instances (like librados cluster handles). It is
- expected this option is primarily useful for debugging.
- - ``mon_dns_srv_name`` (default: `ceph-mon`), the name of the DNS
- SRV record to check to identify the cluster monitors via DNS
- - ``mon_data``, ``osd_data``, ``mds_data``, ``mgr_data``, and
- similar options that define which local directory the daemon
- stores its data in.
- - ``keyring``, ``keyfile``, and/or ``key``, which can be used to
- specify the authentication credential to use to authenticate with
- the monitor. Note that in most cases the default keyring location
- is in the data directory specified above.
-
-In the vast majority of cases the default values of these are
-appropriate, with the exception of the ``mon_host`` option that
-identifies the addresses of the cluster's monitors. When DNS is used
-to identify monitors a local ceph configuration file can be avoided
-entirely.
+Some configuration options affect the process's ability to contact the
+monitors, to authenticate, and to retrieve the cluster-stored configuration.
+For this reason, these options might need to be stored locally on the node, and
+set by means of a local configuration file. These options include the
+following:
+
+.. confval:: mon_host
+.. confval:: mon_host_override
+
+- :confval:`mon_dns_srv_name`
+- ``mon_data``, ``osd_data``, ``mds_data``, ``mgr_data``, and
+ similar options that define which local directory the daemon
+ stores its data in.
+- :confval:`keyring`, :confval:`keyfile`, and/or :confval:`key`, which can be used to
+ specify the authentication credential to use to authenticate with
+ the monitor. Note that in most cases the default keyring location
+ is in the data directory specified above.
+
+In most cases, the default values of these options are suitable. There is one
+exception to this: the :confval:`mon_host` option that identifies the addresses
+of the cluster's monitors. When DNS is used to identify monitors, a local Ceph
+configuration file can be avoided entirely.
Skipping monitor config
-----------------------
-Any process may be passed the option ``--no-mon-config`` to skip the
-step that retrieves configuration from the cluster monitors. This is
-useful in cases where configuration is managed entirely via
-configuration files or where the monitor cluster is currently down but
-some maintenance activity needs to be done.
+Pass the option ``--no-mon-config`` to any process to skip the step that
+retrieves configuration information from the cluster monitors. This is useful
+in cases where configuration is managed entirely via configuration files, or
+when the monitor cluster is down and some maintenance activity needs to be
+done.
.. _ceph-conf-file:
These sections include:
-``global``
+.. confsec:: global
-:Description: Settings under ``global`` affect all daemons and clients
- in a Ceph Storage Cluster.
+ Settings under ``global`` affect all daemons and clients
+ in a Ceph Storage Cluster.
-:Example: ``log_file = /var/log/ceph/$cluster-$type.$id.log``
+ :example: ``log_file = /var/log/ceph/$cluster-$type.$id.log``
-``mon``
+.. confsec:: mon
-:Description: Settings under ``mon`` affect all ``ceph-mon`` daemons in
- the Ceph Storage Cluster, and override the same setting in
- ``global``.
+ Settings under ``mon`` affect all ``ceph-mon`` daemons in
+ the Ceph Storage Cluster, and override the same setting in
+ ``global``.
-:Example: ``mon_cluster_log_to_syslog = true``
+ :example: ``mon_cluster_log_to_syslog = true``
+.. confsec:: mgr
-``mgr``
+ Settings in the ``mgr`` section affect all ``ceph-mgr`` daemons in
+ the Ceph Storage Cluster, and override the same setting in
+ ``global``.
-:Description: Settings in the ``mgr`` section affect all ``ceph-mgr`` daemons in
- the Ceph Storage Cluster, and override the same setting in
- ``global``.
+ :example: ``mgr_stats_period = 10``
-:Example: ``mgr_stats_period = 10``
+.. confsec:: osd
-``osd``
+ Settings under ``osd`` affect all ``ceph-osd`` daemons in
+ the Ceph Storage Cluster, and override the same setting in
+ ``global``.
-:Description: Settings under ``osd`` affect all ``ceph-osd`` daemons in
- the Ceph Storage Cluster, and override the same setting in
- ``global``.
+ :example: ``osd_op_queue = wpq``
-:Example: ``osd_op_queue = wpq``
+.. confsec:: mds
-``mds``
+ Settings in the ``mds`` section affect all ``ceph-mds`` daemons in
+ the Ceph Storage Cluster, and override the same setting in
+ ``global``.
-:Description: Settings in the ``mds`` section affect all ``ceph-mds`` daemons in
- the Ceph Storage Cluster, and override the same setting in
- ``global``.
+ :example: ``mds_cache_memory_limit = 10G``
-:Example: ``mds_cache_memory_limit = 10G``
+.. confsec:: client
-``client``
+ Settings under ``client`` affect all Ceph Clients
+ (e.g., mounted Ceph File Systems, mounted Ceph Block Devices,
+ etc.) as well as Rados Gateway (RGW) daemons.
-:Description: Settings under ``client`` affect all Ceph Clients
- (e.g., mounted Ceph File Systems, mounted Ceph Block Devices,
- etc.) as well as Rados Gateway (RGW) daemons.
-
-:Example: ``objecter_inflight_ops = 512``
+ :example: ``objecter_inflight_ops = 512``
Sections may also specify an individual daemon or client name. For example,
Any given daemon will draw its settings from the global section, the
daemon or client type section, and the section sharing its name.
Settings in the most-specific section take precedence, so for example
-if the same option is specified in both ``global``, ``mon``, and
+if the same option is specified in both :confsec:`global`, :confsec:`mon`, and
``mon.foo`` on the same source (i.e., in the same configurationfile),
the ``mon.foo`` value will be used.
Ceph supports the following metavariables:
-``$cluster``
-
-:Description: Expands to the Ceph Storage Cluster name. Useful when running
- multiple Ceph Storage Clusters on the same hardware.
-
-:Example: ``/etc/ceph/$cluster.keyring``
-:Default: ``ceph``
+.. describe:: $cluster
+ Expands to the Ceph Storage Cluster name. Useful when running
+ multiple Ceph Storage Clusters on the same hardware.
-``$type``
+ :example: ``/etc/ceph/$cluster.keyring``
+ :default: ``ceph``
-:Description: Expands to a daemon or process type (e.g., ``mds``, ``osd``, or ``mon``)
+.. describe:: $type
-:Example: ``/var/lib/ceph/$type``
+ Expands to a daemon or process type (e.g., ``mds``, ``osd``, or ``mon``)
+ :example: ``/var/lib/ceph/$type``
-``$id``
+.. describe:: $id
-:Description: Expands to the daemon or client identifier. For
- ``osd.0``, this would be ``0``; for ``mds.a``, it would
- be ``a``.
+ Expands to the daemon or client identifier. For
+ ``osd.0``, this would be ``0``; for ``mds.a``, it would
+ be ``a``.
-:Example: ``/var/lib/ceph/$type/$cluster-$id``
+ :example: ``/var/lib/ceph/$type/$cluster-$id``
+.. describe:: $host
-``$host``
+ Expands to the host name where the process is running.
-:Description: Expands to the host name where the process is running.
+.. describe:: $name
+ Expands to ``$type.$id``.
-``$name``
+ :example: ``/var/run/ceph/$cluster-$name.asok``
-:Description: Expands to ``$type.$id``.
-:Example: ``/var/run/ceph/$cluster-$name.asok``
+.. describe:: $pid
-``$pid``
+ Expands to daemon pid.
-:Description: Expands to daemon pid.
-:Example: ``/var/run/ceph/$cluster-$name-$pid.asok``
+ :example: ``/var/run/ceph/$cluster-$name-$pid.asok``
Every configuration option is typed with one of the types below:
-``int``
+.. describe:: int
+
+ 64-bit signed integer, Some SI prefixes are supported, like "K", "M", "G",
+ "T", "P", "E", meaning, respectively, 10\ :sup:`3`, 10\ :sup:`6`,
+ 10\ :sup:`9`, etc. And "B" is the only supported unit. So, "1K", "1M", "128B" and "-1" are all valid
+ option values. Some times, a negative value implies "unlimited" when it comes to
+ an option for threshold or limit.
+
+ :example: ``42``, ``-1``
+
+.. describe:: uint
-:Description: 64-bit signed integer, Some SI prefixes are supported, like "K", "M", "G",
- "T", "P", "E", meaning, respectively, 10\ :sup:`3`, 10\ :sup:`6`,
- 10\ :sup:`9`, etc. And "B" is the only supported unit. So, "1K", "1M", "128B" and "-1" are all valid
- option values. Some times, a negative value implies "unlimited" when it comes to
- an option for threshold or limit.
-:Example: ``42``, ``-1``
+ It is almost identical to ``integer``. But a negative value will be rejected.
-``uint``
+ :example: ``256``, ``0``
-:Description: It is almost identical to ``integer``. But a negative value will be rejected.
-:Example: ``256``, ``0``
+.. describe:: str
-``str``
+ Free style strings encoded in UTF-8, but some characters are not allowed. Please
+ reference the above notes for the details.
-:Description: Free style strings encoded in UTF-8, but some characters are not allowed. Please
- reference the above notes for the details.
-:Example: ``"hello world"``, ``"i love \#"``, ``yet-another-name``
+ :example: ``"hello world"``, ``"i love \#"``, ``yet-another-name``
-``boolean``
+.. describe:: boolean
-:Description: one of the two values ``true`` or ``false``. But an integer is also accepted,
- where "0" implies ``false``, and any non-zero values imply ``true``.
-:Example: ``true``, ``false``, ``1``, ``0``
+ one of the two values ``true`` or ``false``. But an integer is also accepted,
+ where "0" implies ``false``, and any non-zero values imply ``true``.
-``addr``
+ :example: ``true``, ``false``, ``1``, ``0``
-:Description: a single address optionally prefixed with ``v1``, ``v2`` or ``any`` for the messenger
- protocol. If the prefix is not specified, ``v2`` protocol is used. Please see
- :ref:`address_formats` for more details.
-:Example: ``v1:1.2.3.4:567``, ``v2:1.2.3.4:567``, ``1.2.3.4:567``, ``2409:8a1e:8fb6:aa20:1260:4bff:fe92:18f5::567``, ``[::1]:6789``
+.. describe:: addr
-``addrvec``
+ a single address optionally prefixed with ``v1``, ``v2`` or ``any`` for the messenger
+ protocol. If the prefix is not specified, ``v2`` protocol is used. Please see
+ :ref:`address_formats` for more details.
-:Description: a set of addresses separated by ",". The addresses can be optionally quoted with ``[`` and ``]``.
-:Example: ``[v1:1.2.3.4:567,v2:1.2.3.4:568]``, ``v1:1.2.3.4:567,v1:1.2.3.14:567`` ``[2409:8a1e:8fb6:aa20:1260:4bff:fe92:18f5::567], [2409:8a1e:8fb6:aa20:1260:4bff:fe92:18f5::568]``
+ :example: ``v1:1.2.3.4:567``, ``v2:1.2.3.4:567``, ``1.2.3.4:567``, ``2409:8a1e:8fb6:aa20:1260:4bff:fe92:18f5::567``, ``[::1]:6789``
-``uuid``
+.. describe:: addrvec
-:Description: the string format of a uuid defined by `RFC4122 <https://www.ietf.org/rfc/rfc4122.txt>`_.
- And some variants are also supported, for more details, see
- `Boost document <https://www.boost.org/doc/libs/1_74_0/libs/uuid/doc/uuid.html#String%20Generator>`_.
-:Example: ``f81d4fae-7dec-11d0-a765-00a0c91e6bf6``
+ a set of addresses separated by ",". The addresses can be optionally quoted with ``[`` and ``]``.
-``size``
+ :example: ``[v1:1.2.3.4:567,v2:1.2.3.4:568]``, ``v1:1.2.3.4:567,v1:1.2.3.14:567`` ``[2409:8a1e:8fb6:aa20:1260:4bff:fe92:18f5::567], [2409:8a1e:8fb6:aa20:1260:4bff:fe92:18f5::568]``
-:Description: denotes a 64-bit unsigned integer. Both SI prefixes and IEC prefixes are
- supported. And "B" is the only supported unit. A negative value will be
- rejected.
-:Example: ``1Ki``, ``1K``, ``1KiB`` and ``1B``.
+.. describe:: uuid
-``secs``
+ the string format of a uuid defined by `RFC4122 <https://www.ietf.org/rfc/rfc4122.txt>`_.
+ And some variants are also supported, for more details, see
+ `Boost document <https://www.boost.org/doc/libs/1_74_0/libs/uuid/doc/uuid.html#String%20Generator>`_.
-:Description: denotes a duration of time. By default the unit is second if not specified.
- Following units of time are supported:
+ :example: ``f81d4fae-7dec-11d0-a765-00a0c91e6bf6``
+
+.. describe:: size
+
+ denotes a 64-bit unsigned integer. Both SI prefixes and IEC prefixes are
+ supported. And "B" is the only supported unit. A negative value will be
+ rejected.
+
+ :example: ``1Ki``, ``1K``, ``1KiB`` and ``1B``.
+
+.. describe:: secs
+
+ denotes a duration of time. By default the unit is second if not specified.
+ Following units of time are supported:
* second: "s", "sec", "second", "seconds"
* minute: "m", "min", "minute", "minutes"
* week: "w", "wk", "week", "weeks"
* month: "mo", "month", "months"
* year: "y", "yr", "year", "years"
-:Example: ``1 m``, ``1m`` and ``1 week``
+
+ :example: ``1 m``, ``1m`` and ``1 week``
.. _ceph-conf-database:
bad option ==== bad value
- Before Octopus, if no section name was specified in the configuration file,
- all options would be set as though they were within the ``global`` section. This is
+ all options would be set as though they were within the :confsec:`global` section. This is
now discouraged. Since Octopus, only a single option is allowed for
configuration files without a section name.
projects / ceph.git / blobdiff