+import io
+from typing import Any, Dict, List, Union
+
+from docutils.parsers.rst import directives
+from docutils.parsers.rst import Directive
+
from sphinx.domains.python import PyField
from sphinx.locale import _
+from sphinx.util import logging, status_iterator
from sphinx.util.docfields import Field
+import jinja2
+import jinja2.filters
+import yaml
+
+
+logger = logging.getLogger(__name__)
+
+
+TEMPLATE = '''
+.. confval_option:: {{ opt.name }}
+{% if desc | length > 1 %}
+ {{ desc | wordwrap(70) | indent(3) }}
+{% endif %}
+ :type: ``{{opt.type}}``
+{%- if default %}
+ {%- if opt.type == 'size' %}
+ :default: ``{{ default | eval_size | filesizeformat(true) }}``
+ {%- elif opt.type == 'secs' %}
+ :default: ``{{ default | readable_duration(opt.type) }}``
+ {%- elif opt.type in ('uint', 'int', 'float') %}
+ :default: ``{{ default | readable_num(opt.type) }}``
+ {%- elif opt.type == 'millisecs' %}
+ :default: ``{{ default }}`` milliseconds
+ {%- elif opt.type == 'bool' %}
+ :default: ``{{ default | string | lower }}``
+ {%- else %}
+ :default: ``{{ default }}``
+ {%- endif -%}
+{%- endif %}
+'''
+
+
+def eval_size(value) -> int:
+ try:
+ return int(value)
+ except ValueError:
+ times = dict(_K=1 << 10,
+ _M=1 << 20,
+ _G=1 << 30,
+ _T=1 << 40)
+ for unit, m in times.items():
+ if value.endswith(unit):
+ return int(value[:-len(unit)]) * m
+ raise ValueError(f'unknown value: {value}')
+
+
+def readable_duration(value: str, typ: str) -> str:
+ try:
+ if typ == 'sec':
+ v = int(value)
+ postfix = 'second' if v == 1 else 'seconds'
+ return f'{v} {postfix}'
+ elif typ == 'float':
+ return str(float(value))
+ else:
+ return str(int(value))
+ except ValueError:
+ times = dict(_min=['minute', 'minutes'],
+ _hr=['hour', 'hours'],
+ _day=['day', 'days'])
+ for unit, readables in times.items():
+ if value.endswith(unit):
+ v = int(value[:-len(unit)])
+ postfix = readables[0 if v == 1 else 1]
+ return f'{v} {postfix}'
+ raise ValueError(f'unknown value: {value}')
+
+
+def do_plain_num(value: str, typ: str) -> str:
+ if typ == 'float':
+ return str(float(value))
+ else:
+ return str(int(value))
+
+
+def do_fileize_num(value: str, typ: str) -> str:
+ v = eval_size(value)
+ return jinja2.filters.do_filesizeformat(v)
-def setup(app):
+
+def readable_num(value: str, typ: str) -> str:
+ e = ValueError()
+ for eval_func in [do_plain_num,
+ readable_duration,
+ do_fileize_num]:
+ try:
+ return eval_func(value, typ)
+ except ValueError as ex:
+ e = ex
+ raise e
+
+
+def jinja_template() -> jinja2.Template:
+ env = jinja2.Environment()
+ env.filters['eval_size'] = eval_size
+ env.filters['readable_duration'] = readable_duration
+ env.filters['readable_num'] = readable_num
+ return env.from_string(TEMPLATE)
+
+
+FieldValueT = Union[bool, float, int, str]
+
+
+class CephOption(Directive):
+ """
+ emit option loaded from given command/options/<name>.yaml.in file
+ """
+ has_content = True
+ required_arguments = 1
+ optional_arguments = 0
+ final_argument_whitespace = False
+ option_spec = {'default': directives.unchanged}
+
+ template = jinja_template()
+ opts: Dict[str, Dict[str, FieldValueT]] = {}
+
+ def _load_yaml(self) -> Dict[str, Dict[str, FieldValueT]]:
+ if CephOption.opts:
+ return CephOption.opts
+ env = self.state.document.settings.env
+ opts = []
+ for fn in status_iterator(env.config.ceph_confval_imports,
+ 'loading options...', 'red',
+ len(env.config.ceph_confval_imports),
+ env.app.verbosity):
+ env.note_dependency(fn)
+ try:
+ with open(fn, 'r') as f:
+ yaml_in = io.StringIO()
+ for line in f:
+ if '@' not in line:
+ yaml_in.write(line)
+ yaml_in.seek(0)
+ opts += yaml.safe_load(yaml_in)['options']
+ except OSError as e:
+ message = f'Unable to open option file "{fn}": {e}'
+ raise self.error(message)
+ CephOption.opts = dict((opt['name'], opt) for opt in opts)
+ return CephOption.opts
+
+ def run(self) -> List[Any]:
+ name = self.arguments[0]
+ opt = self._load_yaml().get(name)
+ if opt is None:
+ raise self.error(f'Option "{name}" not found!')
+ desc = opt.get('fmt_desc') or opt.get('long_desc') or opt.get('desc')
+ opt_default = opt.get('default')
+ default = self.options.get('default', opt_default)
+ rendered = self.template.render(opt=opt, desc=desc, default=default)
+ lineno = self.lineno - self.state_machine.input_offset - 1
+ source = self.state_machine.input_lines.source(lineno)
+ self.state_machine.insert_input(rendered.split('\n'), source)
+ return []
+
+
+def setup(app) -> Dict[str, Any]:
+ app.add_config_value('ceph_confval_imports',
+ default=[],
+ rebuild='html',
+ types=[str])
+ app.add_directive('confval', CephOption)
app.add_object_type(
- 'confval',
- 'confval',
+ 'confval_option',
+ 'confval_option',
objname='configuration value',
indextemplate='pair: %s; configuration value',
doc_field_types=[
has_arg=False,
)]
)
+
return {
'version': 'builtin',
'parallel_read_safe': True,
openapi_logger = sphinx.util.logging.getLogger('sphinxcontrib.openapi.openapi30')
openapi_logger.setLevel(logging.WARNING)
+# ceph_confval
+ceph_confval_imports = [os.path.join(top_level,
+ 'src/common/options',
+ yaml + '.yaml.in')
+ for yaml in ['global',
+ 'immutable-object-cache',
+ 'mds',
+ 'mds-client',
+ 'rbd',
+ 'rbd-mirror',
+ 'rgw']]
+
# handles edit-on-github and old version warning display
def setup(app):
.. confval:: auth_cluster_required
-
- If enabled, the Ceph Storage Cluster daemons (i.e., ``ceph-mon``,
- ``ceph-osd``, ``ceph-mds`` and ``ceph-mgr``) must authenticate with
- each other. Valid settings are ``cephx`` or ``none``.
-
- :type: String
- :required: No
- :default: ``cephx``.
-
-
.. confval:: auth_service_required
-
- If enabled, the Ceph Storage Cluster daemons require Ceph Clients
- to authenticate with the Ceph Storage Cluster in order to access
- Ceph services. Valid settings are ``cephx`` or ``none``.
-
- :type: String
- :required: No
- :default: ``cephx``.
-
-
.. confval:: auth_client_required
- If enabled, the Ceph Client requires the Ceph Storage Cluster to
- authenticate with the Ceph Client. Valid settings are ``cephx``
- or ``none``.
-
- :type: String
- :required: No
- :default: ``cephx``.
-
-
.. index:: keys; keyring
Keys
You may specify the key itself in the Ceph configuration file using the ``key``
setting (not recommended), or a path to a keyfile using the ``keyfile`` setting.
-
.. confval:: keyring
-
- The path to the keyring file.
-
- :type: String
- :required: No
- :default: ``/etc/ceph/$cluster.$name.keyring,/etc/ceph/$cluster.keyring,/etc/ceph/keyring,/etc/ceph/keyring.bin``
-
-
+ :default: /etc/ceph/$cluster.$name.keyring,/etc/ceph/$cluster.keyring,/etc/ceph/keyring,/etc/ceph/keyring.bin
.. confval:: keyfile
-
- The path to a key file (i.e,. a file containing only the key).
-
- :type: String
- :required: No
- :default: None
-
-
.. confval:: key
- The key (i.e., the text string of the key itself). Not recommended.
-
- :type: String
- :required: No
- :default: None
-
-
Daemon Keyrings
---------------
flight.
.. confval:: cephx_require_signatures
-
- If set to ``true``, Ceph requires signatures on all message
- traffic between the Ceph Client and the Ceph Storage Cluster, and
- between daemons comprising the Ceph Storage Cluster.
-
- Ceph Argonaut and Linux kernel versions prior to 3.19 do
- not support signatures; if such clients are in use this
- option can be turned off to allow them to connect.
-
- :type: Boolean
- :required: No
- :default: ``false``
-
-
.. confval:: cephx_cluster_require_signatures
-
- If set to ``true``, Ceph requires signatures on all message
- traffic between Ceph daemons comprising the Ceph Storage Cluster.
-
- :type: Boolean
- :required: No
- :default: ``false``
-
-
.. confval:: cephx_service_require_signatures
-
- If set to ``true``, Ceph requires signatures on all message
- traffic between Ceph Clients and the Ceph Storage Cluster.
-
- :type: Boolean
- :required: No
- :default: ``false``
-
-
.. confval:: cephx_sign_messages
- If the Ceph version supports message signing, Ceph will sign
- all messages so they are more difficult to spoof.
-
- :type: Boolean
- :default: ``true``
-
-
Time to Live
------------
.. confval:: auth_service_ticket_ttl
- When the Ceph Storage Cluster sends a Ceph Client a ticket for
- authentication, the Ceph Storage Cluster assigns the ticket a
- time to live.
-
- :type: Double
- :default: ``60*60``
-
-
.. _Monitor Bootstrapping: ../../../install/manual-deployment#monitor-bootstrapping
.. _Operating a Cluster: ../../operations/operating
.. _Manual Deployment: ../../../install/manual-deployment
Ceph OSD Daemons recognize the following journal settings:
-
.. confval:: journal_dio
-
- Enables direct i/o to the journal. Requires ``journal block
- align`` set to ``true``.
-
- :type: Boolean
- :required: Yes when using ``aio``.
- :default: ``true``
-
-
-
.. confval:: journal_aio
-
- .. versionchanged:: 0.61 Cuttlefish
-
- Enables using ``libaio`` for asynchronous writes to the journal.
- Requires ``journal dio`` set to ``true``.
-
- :type: Boolean
- :required: No.
- :default: Version 0.61 and later, ``true``. Version 0.60 and earlier, ``false``.
-
-
.. confval:: journal_block_align
-
- Block aligns write operations. Required for ``dio`` and ``aio``.
-
- :type: Boolean
- :required: Yes when using ``dio`` and ``aio``.
- :default: ``true``
-
-
.. confval:: journal_max_write_bytes
-
- The maximum number of bytes the journal will write at
- any one time.
-
- :type: Integer
- :required: No
- :default: ``10 << 20``
-
-
.. confval:: journal_max_write_entries
-
- The maximum number of entries the journal will write at
- any one time.
-
- :type: Integer
- :required: No
- :default: ``100``
-
-
-.. confval:: journal_queue_max_ops
-
- The maximum number of operations allowed in the queue at
- any one time.
-
- :type: Integer
- :required: No
- :default: ``500``
-
-
-.. confval:: journal_queue_max_bytes
-
- The maximum number of bytes allowed in the queue at
- any one time.
-
- :type: Integer
- :required: No
- :default: ``10 << 20``
-
-
.. confval:: journal_align_min_size
-
- Align data payloads greater than the specified minimum.
-
- :type: Integer
- :required: No
- :default: ``64 << 10``
-
-
.. confval:: journal_zero_on_create
-
- Causes the file store to overwrite the entire journal with
- ``0``'s during ``mkfs``.
-
- :type: Boolean
- :required: No
- :default: ``false``
setting for a specific daemon.
.. confval:: public_network
-
- The IP address and netmask of the public (front-side) network
- (e.g., ``192.168.0.0/24``). Set in ``[global]``. You may specify
- comma-separated subnets.
-
- :type: ``{ip-address}/{netmask} [, {ip-address}/{netmask}]``
- :required: No
- :default: N/A
-
.. confval:: public_addr
- The IP address for the public (front-side) network.
- Set for each daemon.
-
- :type: IP Address
- :required: No
- :default: N/A
-
-
-
Cluster Network
---------------
.. confval:: cluster_network
-
- The IP address and netmask of the cluster (back-side) network
- (e.g., ``10.0.0.0/24``). Set in ``[global]``. You may specify
- comma-separated subnets.
-
- :type: ``{ip-address}/{netmask} [, {ip-address}/{netmask}]``
- :required: No
- :default: N/A
-
-
.. confval:: cluster_addr
- The IP address for the cluster (back-side) network.
- Set for each daemon.
-
- :type: Address
- :required: No
- :default: N/A
-
-
Bind
----
You may also enable Ceph daemons to bind to IPv6 addresses instead of IPv4
addresses.
-
.. confval:: ms_bind_port_min
-
- The minimum port number to which an OSD or MDS daemon will bind.
-
- :type: 32-bit Integer
- :default: ``6800``
- :required: No
-
.. confval:: ms_bind_port_max
-
- The maximum port number to which an OSD or MDS daemon will bind.
-
- :type: 32-bit Integer
- :default: ``7300``
- :required: No
-
.. confval:: ms_bind_ipv4
-
- Enables Ceph daemons to bind to IPv4 addresses.
-
- :type: Boolean
- :default: ``true``
- :Required: No
-
.. confval:: ms_bind_ipv6
-
- Enables Ceph daemons to bind to IPv6 addresses.
-
- :type: Boolean
- :default: ``false``
- :required: No
-
.. confval:: public_bind_addr
- In some dynamic deployments the Ceph MON daemon might bind
- to an IP address locally that is different from the ``public_addr``
- advertised to other peers in the network. The environment must ensure
- that routing rules are set correctly. If ``public_bind_addr`` is set
- the Ceph Monitor daemon will bind to it locally and use ``public_addr``
- in the monmaps to advertise its address to peers. This behavior is limited
- to the Monitor daemon.
-
- :type: IP Address
- :required: No
- :default: N/A
-
-
-
TCP
---
Ceph disables TCP buffering by default.
-
.. confval:: ms_tcp_nodelay
-
- Ceph enables ``ms_tcp_nodelay`` so that each request is sent
- immediately (no buffering). Disabling `Nagle's algorithm`_
- increases network traffic, which can introduce latency. If you
- experience large numbers of small packets, you may try
- disabling ``ms_tcp_nodelay``.
-
- :type: Boolean
- :required: No
- :default: ``true``
-
-
.. confval:: ms_tcp_rcvbuf
- The size of the socket buffer on the receiving end of a network
- connection. Disable by default.
-
- :type: 32-bit Integer
- :required: No
- :default: ``0``
-
-
.. _Scalability and High Availability: ../../../architecture#scalability-and-high-availability
.. _Hardware Recommendations - Networks: ../../../start/hardware-recommendations#networks
.. _hardware recommendations: ../../../start/hardware-recommendations
type: addr
level: basic
desc: public-facing address to bind to
+ fmt_desc: The IP address for the public (front-side) network.
+ Set for each daemon.
services:
- mon
- mds
- mon
flags:
- startup
+ fmt_desc: In some dynamic deployments the Ceph MON daemon might bind
+ to an IP address locally that is different from the ``public_addr``
+ advertised to other peers in the network. The environment must ensure
+ that routing rules are set correctly. If ``public_bind_addr`` is set
+ the Ceph Monitor daemon will bind to it locally and use ``public_addr``
+ in the monmaps to advertise its address to peers. This behavior is limited
+ to the Monitor daemon.
with_legacy: true
- name: cluster_addr
type: addr
level: basic
desc: cluster-facing address to bind to
+ fmt_desc: The IP address for the cluster (back-side) network.
+ Set for each daemon.
tags:
- network
services:
type: str
level: advanced
desc: Network(s) from which to choose a public address to bind to
+ fmt_desc: The IP address and netmask of the public (front-side) network
+ (e.g., ``192.168.0.0/24``). Set in ``[global]``. You may specify
+ comma-separated subnets. The format of it looks like
+ ``{ip-address}/{netmask} [, {ip-address}/{netmask}]``
tags:
- network
services:
type: str
level: advanced
desc: Network(s) from which to choose a cluster address to bind to
+ fmt_desc: The IP address and netmask of the cluster (back-side) network
+ (e.g., ``10.0.0.0/24``). Set in ``[global]``. You may specify
+ comma-separated subnets. The format of it looks like
+ ``{ip-address}/{netmask} [, {ip-address}/{netmask}]``
tags:
- network
services:
desc: Authentication key
long_desc: A CephX authentication key, base64 encoded. It normally looks something
like 'AQAtut9ZdMbNJBAAHz6yBAWyJyz2yYRyeMWDag=='.
+ fmt_desc: The key (i.e., the text string of the key itself). Not recommended.
see_also:
- keyfile
- keyring
desc: Path to a file containing a key
long_desc: The file should contain a CephX authentication key and optionally a trailing
newline, but nothing else.
+ fmt_desc: The path to a key file (i.e,. a file containing only the key).
see_also:
- key
flags:
long_desc: A keyring file is an INI-style formatted file where the section names
are client or daemon names (e.g., 'osd.0') and each section contains a 'key' property
with CephX authentication key as the value.
+ # please note, document are generated without accessing to the CMake
+ # variables, so please update the document manually with a representive
+ # default value using the ":default:" option of ".. confval::" directive.
default: @keyring_paths@
see_also:
- key
type: bool
level: advanced
desc: Disable Nagle's algorithm and send queued network traffic immediately
+ fmt_desc: Ceph enables ``ms_tcp_nodelay`` so that each request is sent
+ immediately (no buffering). Disabling `Nagle's algorithm`_
+ increases network traffic, which can introduce latency. If you
+ experience large numbers of small packets, you may try
+ disabling ``ms_tcp_nodelay``.
default: true
with_legacy: true
- name: ms_tcp_rcvbuf
type: size
level: advanced
desc: Size of TCP socket receive buffer
+ fmt_desc: The size of the socket buffer on the receiving end of a network
+ connection. Disable by default.
default: 0
with_legacy: true
- name: ms_tcp_prefetch_max_size
type: bool
level: advanced
desc: Bind servers to IPv4 address(es)
+ fmt_desc: Enables Ceph daemons to bind to IPv4 addresses.
default: true
see_also:
- ms_bind_ipv6
type: bool
level: advanced
desc: Bind servers to IPv6 address(es)
+ fmt_desc: Enables Ceph daemons to bind to IPv6 addresses.
default: false
see_also:
- ms_bind_ipv4
type: int
level: advanced
desc: Lowest port number to bind daemon(s) to
+ fmt_desc: The minimum port number to which an OSD or MDS daemon will bind.
default: 6800
with_legacy: true
- name: ms_bind_port_max
type: int
level: advanced
desc: Highest port number to bind daemon(s) to
+ fmt_desc: The maximum port number to which an OSD or MDS daemon will bind.
default: 7300
with_legacy: true
# FreeBSD does not use SO_REAUSEADDR so allow for a bit more time per default
type: str
level: advanced
desc: authentication methods required by the cluster
+ fmt_desc: If enabled, the Ceph Storage Cluster daemons (i.e., ``ceph-mon``,
+ ``ceph-osd``, ``ceph-mds`` and ``ceph-mgr``) must authenticate with
+ each other. Valid settings are ``cephx`` or ``none``.
default: cephx
with_legacy: true
# required by daemons of clients
type: str
level: advanced
desc: authentication methods required by service daemons
+ fmt_desc: If enabled, the Ceph Storage Cluster daemons require Ceph Clients
+ to authenticate with the Ceph Storage Cluster in order to access
+ Ceph services. Valid settings are ``cephx`` or ``none``.
default: cephx
with_legacy: true
# what clients require of daemons
type: str
level: advanced
desc: authentication methods allowed by clients
+ fmt_desc: If enabled, the Ceph Client requires the Ceph Storage Cluster to
+ authenticate with the Ceph Client. Valid settings are ``cephx``
+ or ``none``.
default: cephx, none
with_legacy: true
# deprecated; default value for above if they are not defined.
type: bool
level: advanced
default: false
+ fmt_desc: If set to ``true``, Ceph requires signatures on all message
+ traffic between the Ceph Client and the Ceph Storage Cluster, and
+ between daemons comprising the Ceph Storage Cluster.
+
+ Ceph Argonaut and Linux kernel versions prior to 3.19 do
+ not support signatures; if such clients are in use this
+ option can be turned off to allow them to connect.
with_legacy: true
- name: cephx_require_version
type: int
type: bool
level: advanced
default: false
+ fmt_desc: If set to ``true``, Ceph requires signatures on all message
+ traffic between Ceph daemons comprising the Ceph Storage Cluster.
with_legacy: true
- name: cephx_cluster_require_version
type: int
type: bool
level: advanced
default: false
+ fmt_desc: If set to ``true``, Ceph requires signatures on all message
+ traffic between Ceph Clients and the Ceph Storage Cluster.
with_legacy: true
- name: cephx_service_require_version
type: int
type: bool
level: advanced
default: true
+ fmt_desc: If the Ceph version supports message signing, Ceph will sign
+ all messages so they are more difficult to spoof.
with_legacy: true
- name: auth_mon_ticket_ttl
type: float
type: float
level: advanced
default: 1_hr
+ fmt_desc: When the Ceph Storage Cluster sends a Ceph Client a ticket for
+ authentication, the Ceph Storage Cluster assigns the ticket a
+ time to live.
with_legacy: true
- name: auth_allow_insecure_global_id_reclaim
type: bool
type: bool
level: dev
default: true
+ fmt_desc: Enables direct i/o to the journal. Requires ``journal block
+ align`` set to ``true``.
with_legacy: true
- name: journal_aio
type: bool
level: dev
default: true
+ fmt_desc: Enables using ``libaio`` for asynchronous writes to the journal.
+ Requires ``journal dio`` set to ``true``. Version 0.61 and later, ``true``.
+ Version 0.60 and earlier, ``false``.
with_legacy: true
- name: journal_force_aio
type: bool
type: bool
level: dev
default: true
+ fmt_desc: Block aligns write operations. Required for ``dio`` and ``aio``.
with_legacy: true
- name: journal_write_header_frequency
type: uint
type: size
level: advanced
desc: Max bytes in flight to journal
+ fmt_desc: The maximum number of bytes the journal will write at
+ any one time.
default: 10_M
with_legacy: true
- name: journal_max_write_entries
type: int
level: advanced
desc: Max IOs in flight to journal
+ fmt_desc: The maximum number of entries the journal will write at
+ any one time.
default: 100
with_legacy: true
# Target range for journal fullness
type: size
level: dev
default: 64_K
+ fmt_desc: Align data payloads greater than the specified minimum.
with_legacy: true
- name: journal_replay_from
type: int
type: bool
level: dev
default: false
+ fmt_desc: Causes the file store to overwrite the entire journal with
+ ``0``'s during ``mkfs``.
with_legacy: true
# assume journal is not corrupt
- name: journal_ignore_corruption
projects / ceph.git / commitdiff