From b60d041efa4051989a83870e7672a417eed1c0c9 Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Sun, 28 Mar 2021 23:30:44 +0800 Subject: [PATCH] doc/rados/configuration: format confval with "confval" directive for better formatting Signed-off-by: Kefu Chai --- doc/rados/configuration/auth-config-ref.rst | 141 +++++++++-------- doc/rados/configuration/ceph-conf.rst | 103 ++++++------ doc/rados/configuration/journal-ref.rst | 111 ++++++------- .../configuration/network-config-ref.rst | 148 +++++++++--------- 4 files changed, 254 insertions(+), 249 deletions(-) diff --git a/doc/rados/configuration/auth-config-ref.rst b/doc/rados/configuration/auth-config-ref.rst index 4eeabea0d85a8..5e6c0285ca935 100644 --- a/doc/rados/configuration/auth-config-ref.rst +++ b/doc/rados/configuration/auth-config-ref.rst @@ -144,37 +144,37 @@ Enablement ---------- -``auth_cluster_required`` +.. confval:: auth_cluster_required -:Description: 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``. + 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``. + :type: String + :required: No + :default: ``cephx``. -``auth_service_required`` +.. confval:: auth_service_required -:Description: 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``. + 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``. + :type: String + :required: No + :default: ``cephx``. -``auth_client_required`` +.. confval:: auth_client_required -:Description: If enabled, the Ceph Client requires the Ceph Storage Cluster to - authenticate with the Ceph Client. Valid settings are ``cephx`` - or ``none``. + 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``. + :type: String + :required: No + :default: ``cephx``. .. index:: keys; keyring @@ -206,28 +206,31 @@ 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. -``keyring`` +.. confval:: keyring -:Description: 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`` + 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`` -``keyfile`` -:Description: The path to a key file (i.e,. a file containing only the key). -:Type: String -:Required: No -:Default: None +.. confval:: keyfile + The path to a key file (i.e,. a file containing only the key). -``key`` + :type: String + :required: No + :default: None -:Description: The key (i.e., the text string of the key itself). Not recommended. -: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 @@ -295,61 +298,61 @@ Ceph, and so you can enable/disable signatures for messages between Ceph daemons Note that even with signatures enabled data is not encrypted in flight. -``cephx_require_signatures`` +.. confval:: cephx_require_signatures -:Description: 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. + 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. + 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`` + :type: Boolean + :required: No + :default: ``false`` -``cephx_cluster_require_signatures`` +.. confval:: cephx_cluster_require_signatures -:Description: If set to ``true``, Ceph requires signatures on all message - traffic between Ceph daemons comprising the Ceph Storage Cluster. + 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`` + :type: Boolean + :required: No + :default: ``false`` -``cephx_service_require_signatures`` +.. confval:: cephx_service_require_signatures -:Description: If set to ``true``, Ceph requires signatures on all message - traffic between Ceph Clients and the Ceph Storage Cluster. + 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`` + :type: Boolean + :required: No + :default: ``false`` -``cephx_sign_messages`` +.. confval:: cephx_sign_messages -:Description: If the Ceph version supports message signing, Ceph will sign - all messages so they are more difficult to spoof. + If the Ceph version supports message signing, Ceph will sign + all messages so they are more difficult to spoof. -:Type: Boolean -:Default: ``true`` + :type: Boolean + :default: ``true`` Time to Live ------------ -``auth_service_ticket_ttl`` +.. confval:: auth_service_ticket_ttl -:Description: When the Ceph Storage Cluster sends a Ceph Client a ticket for - authentication, the Ceph Storage Cluster assigns the ticket a - time to live. + 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`` + :type: Double + :default: ``60*60`` .. _Monitor Bootstrapping: ../../../install/manual-deployment#monitor-bootstrapping diff --git a/doc/rados/configuration/ceph-conf.rst b/doc/rados/configuration/ceph-conf.rst index 07c84eddcc8e8..8d7119ef954ac 100644 --- a/doc/rados/configuration/ceph-conf.rst +++ b/doc/rados/configuration/ceph-conf.rst @@ -119,53 +119,52 @@ they apply to. These sections include: -``global`` +.. confval:: 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`` +.. confval:: 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`` +.. confval:: 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`` +.. confval:: 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`` +.. confval:: 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`` +.. confval:: 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, @@ -199,45 +198,43 @@ configuration value is used. Ceph metavariables are similar to variable expansio 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`` +.. confval:: $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``) +.. confval:: $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`` +.. confval:: $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`` +.. confval:: $host -``$host`` + Expands to the host name where the process is running. -:Description: Expands to the host name where the process is running. +.. confval:: $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`` +.. confval:: $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`` diff --git a/doc/rados/configuration/journal-ref.rst b/doc/rados/configuration/journal-ref.rst index 71c74c6065950..b4d2f30c4c45e 100644 --- a/doc/rados/configuration/journal-ref.rst +++ b/doc/rados/configuration/journal-ref.rst @@ -31,89 +31,92 @@ Filestore is preferred for new deployments. Ceph OSD Daemons recognize the following journal settings: -``journal_dio`` +.. confval:: journal_dio -:Description: Enables direct i/o to the journal. Requires ``journal block - align`` set to ``true``. - -:Type: Boolean -:Required: Yes when using ``aio``. -:Default: ``true`` + Enables direct i/o to the journal. Requires ``journal block + align`` set to ``true``. + :type: Boolean + :required: Yes when using ``aio``. + :default: ``true`` -``journal_aio`` -.. versionchanged:: 0.61 Cuttlefish +.. confval:: journal_aio -:Description: Enables using ``libaio`` for asynchronous writes to the journal. - Requires ``journal dio`` set to ``true``. + .. versionchanged:: 0.61 Cuttlefish -:Type: Boolean -:Required: No. -:Default: Version 0.61 and later, ``true``. Version 0.60 and earlier, ``false``. + 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``. -``journal_block_align`` -:Description: Block aligns write operations. Required for ``dio`` and ``aio``. -:Type: Boolean -:Required: Yes when using ``dio`` and ``aio``. -:Default: ``true`` +.. confval:: journal_block_align + Block aligns write operations. Required for ``dio`` and ``aio``. -``journal_max_write_bytes`` + :type: Boolean + :required: Yes when using ``dio`` and ``aio``. + :default: ``true`` -:Description: The maximum number of bytes the journal will write at - any one time. -:Type: Integer -:Required: No -:Default: ``10 << 20`` +.. confval:: journal_max_write_bytes + The maximum number of bytes the journal will write at + any one time. -``journal_max_write_entries`` + :type: Integer + :required: No + :default: ``10 << 20`` -:Description: The maximum number of entries the journal will write at - any one time. -:Type: Integer -:Required: No -:Default: ``100`` +.. confval:: journal_max_write_entries + The maximum number of entries the journal will write at + any one time. -``journal_queue_max_ops`` + :type: Integer + :required: No + :default: ``100`` -:Description: The maximum number of operations allowed in the queue at - any one time. -:Type: Integer -:Required: No -:Default: ``500`` +.. confval:: journal_queue_max_ops + The maximum number of operations allowed in the queue at + any one time. -``journal_queue_max_bytes`` + :type: Integer + :required: No + :default: ``500`` -:Description: The maximum number of bytes allowed in the queue at - any one time. -:Type: Integer -:Required: No -:Default: ``10 << 20`` +.. confval:: journal_queue_max_bytes + The maximum number of bytes allowed in the queue at + any one time. -``journal_align_min_size`` + :type: Integer + :required: No + :default: ``10 << 20`` -:Description: Align data payloads greater than the specified minimum. -:Type: Integer -:Required: No -:Default: ``64 << 10`` +.. confval:: journal_align_min_size -``journal_zero_on_create`` + Align data payloads greater than the specified minimum. -:Description: Causes the file store to overwrite the entire journal with - ``0``'s during ``mkfs``. -:Type: Boolean -:Required: No -:Default: ``false`` + :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`` diff --git a/doc/rados/configuration/network-config-ref.rst b/doc/rados/configuration/network-config-ref.rst index 6ad18e5e06db3..c31584d535d77 100644 --- a/doc/rados/configuration/network-config-ref.rst +++ b/doc/rados/configuration/network-config-ref.rst @@ -287,25 +287,24 @@ and subnets for the public network. You may specifically assign static IP addresses or override ``public_network`` settings using the ``public_addr`` setting for a specific daemon. -``public_network`` +.. confval:: public_network -:Description: 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 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 + :type: ``{ip-address}/{netmask} [, {ip-address}/{netmask}]`` + :required: No + :default: N/A +.. confval:: public_addr -``public_addr`` + The IP address for the public (front-side) network. + Set for each daemon. -:Description: The IP address for the public (front-side) network. - Set for each daemon. - -:Type: IP Address -:Required: No -:Default: N/A + :type: IP Address + :required: No + :default: N/A @@ -318,25 +317,25 @@ specifically assign static IP addresses or override ``cluster_network`` settings using the ``cluster_addr`` setting for specific OSD daemons. -``cluster_network`` +.. confval:: cluster_network -:Description: 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 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 + :type: ``{ip-address}/{netmask} [, {ip-address}/{netmask}]`` + :required: No + :default: N/A -``cluster_addr`` +.. confval:: cluster_addr -:Description: The IP address for the cluster (back-side) network. - Set for each daemon. + The IP address for the cluster (back-side) network. + Set for each daemon. -:Type: Address -:Required: No -:Default: N/A + :type: Address + :required: No + :default: N/A Bind @@ -350,48 +349,51 @@ You may also enable Ceph daemons to bind to IPv6 addresses instead of IPv4 addresses. -``ms_bind_port_min`` +.. 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 -:Description: The minimum port number to which an OSD or MDS daemon will bind. -:Type: 32-bit Integer -:Default: ``6800`` -:Required: No + The maximum port number to which an OSD or MDS daemon will bind. + :type: 32-bit Integer + :default: ``7300`` + :required: No -``ms_bind_port_max`` +.. confval:: ms_bind_ipv4 -:Description: The maximum port number to which an OSD or MDS daemon will bind. -:Type: 32-bit Integer -:Default: ``7300`` -:Required: No. + Enables Ceph daemons to bind to IPv4 addresses. -``ms_bind_ipv4`` + :type: Boolean + :default: ``true`` + :Required: No -:Description: Enables Ceph daemons to bind to IPv4 addresses. -:Type: Boolean -:Default: ``true`` -:Required: No +.. confval:: ms_bind_ipv6 -``ms_bind_ipv6`` + Enables Ceph daemons to bind to IPv6 addresses. -:Description: Enables Ceph daemons to bind to IPv6 addresses. -:Type: Boolean -:Default: ``false`` -:Required: No + :type: Boolean + :default: ``false`` + :required: No -``public_bind_addr`` +.. confval:: public_bind_addr -:Description: 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. + 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 + :type: IP Address + :required: No + :default: N/A @@ -401,27 +403,27 @@ TCP Ceph disables TCP buffering by default. -``ms_tcp_nodelay`` +.. confval:: ms_tcp_nodelay -:Description: 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``. + 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`` + :type: Boolean + :required: No + :default: ``true`` -``ms_tcp_rcvbuf`` +.. confval:: ms_tcp_rcvbuf -:Description: The size of the socket buffer on the receiving end of a network - connection. Disable by default. + 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`` + :type: 32-bit Integer + :required: No + :default: ``0`` .. _Scalability and High Availability: ../../../architecture#scalability-and-high-availability -- 2.39.5