From d0dc93a22eb05f06272e8a104f1c1efeae1add25 Mon Sep 17 00:00:00 2001 From: Ville Ojamo <14869000+bluikko@users.noreply.github.com> Date: Wed, 8 Jul 2026 12:27:06 +0700 Subject: [PATCH] doc: fix Sphinx complaints and some rendering errors Fix 25 criticals, errors, and warnings from Sphinx. Some of the changes did not change rendering but most fixed unintended rendering, broken link etc. Change Mon to Monitor in ceph-secrets.rst. Signed-off-by: Ville Ojamo --- doc/cephadm/host-management.rst | 8 ++++---- doc/cephadm/upgrade.rst | 2 +- doc/dev/crimson/seastore_laddr.rst | 3 ++- doc/dev/osd_internals/erasure_coding/client_support.rst | 4 ++-- doc/dev/release-process.rst | 2 +- doc/man/8/cephadm.rst | 2 +- doc/mgr/ceph_secrets.rst | 9 +++------ doc/rados/troubleshooting/troubleshooting-mon.rst | 2 +- doc/radosgw/adminops.rst | 2 +- doc/radosgw/encryption.rst | 4 ++++ 10 files changed, 20 insertions(+), 18 deletions(-) diff --git a/doc/cephadm/host-management.rst b/doc/cephadm/host-management.rst index 0fd4f1284e0..9c65810fdb5 100644 --- a/doc/cephadm/host-management.rst +++ b/doc/cephadm/host-management.rst @@ -689,7 +689,7 @@ requires the bare host name when adding a host to the cluster: ``ceph orch host add ``. Sudo Hardening -============= +============== Cephadm supports sudo hardening to enhance security by restricting sudo privilege escalation for non-root SSH users. When sudo hardening is enabled, cephadm uses the @@ -697,7 +697,7 @@ escalation for non-root SSH users. When sudo hardening is enabled, cephadm uses privilege escalation. Enabling Sudo Hardening ----------------------- +----------------------- To enable sudo hardening for the entire cluster, use the following command: @@ -730,7 +730,7 @@ You can manually prepare a host for sudo hardening using: access will be used for ongoing operations. Sudo Hardening Workflow ----------------------- +----------------------- When sudo hardening is enabled, the following workflow is used: @@ -770,7 +770,7 @@ Sudo hardening provides the following security benefits: Disabling Sudo Hardening ------------------------ +------------------------ To disable sudo hardening: diff --git a/doc/cephadm/upgrade.rst b/doc/cephadm/upgrade.rst index 5d7d7e44b4a..54f2a304345 100644 --- a/doc/cephadm/upgrade.rst +++ b/doc/cephadm/upgrade.rst @@ -136,7 +136,7 @@ Requirements: (same shape as ``ceph_version_short`` in ``ceph osd metadata``). * If the Monitors indicate to cephadm that no OSDs in the selected CRUSH bucket are okay to upgrade, cephadm will log details and then retry the operation. -* If the bucket parameters for a ceph ``osd ok-to-upgrade`` upgrade are not provided, +* If the bucket parameters for a ceph ``osd ok-to-upgrade`` upgrade are not provided, cephadm will fall back to the default ceph osd ok-to-stop gate for OSD upgrades. * Bucket-scope upgrades apply only to OSDs. CRUSH buckets do not influence upgrades of other daemon types, for example Monitors, Managers, and MDSes. diff --git a/doc/dev/crimson/seastore_laddr.rst b/doc/dev/crimson/seastore_laddr.rst index 477aca7a865..ef228720b38 100644 --- a/doc/dev/crimson/seastore_laddr.rst +++ b/doc/dev/crimson/seastore_laddr.rst @@ -201,7 +201,8 @@ after the upgrade finishes. TODO: fsck/tooling must support scanning and migrating all mappings between upgrades. - //create tracker after PR merged/ready. + +//create tracker after PR merged/ready. Multi-push Recovery ------------------- diff --git a/doc/dev/osd_internals/erasure_coding/client_support.rst b/doc/dev/osd_internals/erasure_coding/client_support.rst index 96c84bd7432..5ce50348aec 100644 --- a/doc/dev/osd_internals/erasure_coding/client_support.rst +++ b/doc/dev/osd_internals/erasure_coding/client_support.rst @@ -466,7 +466,7 @@ These operations provide the same semantics as in replicated pools, ensuring compatibility with existing applications. Read Operation Flow -~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~ Read operations follow a simple flow: @@ -906,7 +906,7 @@ Required Settings To enable the new features, the following OSDMap pool settings are required: -- ``allows_ec_overwrites = true` +- ``allows_ec_overwrites = true`` - ``allows_ec_optimizations = true`` - ``supports_omap = true`` diff --git a/doc/dev/release-process.rst b/doc/dev/release-process.rst index 15ac516c23d..4dd13d09db1 100644 --- a/doc/dev/release-process.rst +++ b/doc/dev/release-process.rst @@ -88,7 +88,7 @@ Once QE has determined a stopping point in the working (e.g., ``squid``) branch, Notify the "Build Lead" that the release branch is ready. 2a. Starting the build -===================== +====================== We'll use a stable/regular 19.2.2 release of Squid as an example throughout this document. diff --git a/doc/man/8/cephadm.rst b/doc/man/8/cephadm.rst index 5843448d19d..a2030ff3c7e 100644 --- a/doc/man/8/cephadm.rst +++ b/doc/man/8/cephadm.rst @@ -458,7 +458,7 @@ Arguments: prepare-host-sudo-hardening --------------------------- +--------------------------- Prepare a host for sudo hardening by authorizing SSH keys, installing/upgrading the cephadm package, and setting up restricted sudoers permissions:: diff --git a/doc/mgr/ceph_secrets.rst b/doc/mgr/ceph_secrets.rst index 45675c002d2..dc8b7c6167c 100644 --- a/doc/mgr/ceph_secrets.rst +++ b/doc/mgr/ceph_secrets.rst @@ -25,7 +25,7 @@ service spec instead of the plaintext token. A cephadm integration can then resolve the URI at deploy time and write the token only into the daemon files that need it. -Secrets are stored in the Mon KV store under the ``secret_store/v1/`` prefix +Secrets are stored in the Monitor KV store under the ``secret_store/v1/`` prefix and are organised by namespace, scope, and name. Each secret is versioned and carries ``created``/``updated`` timestamps. A per-namespace epoch counter is incremented on every ``set`` and on any ``rm`` that actually removes a @@ -34,7 +34,7 @@ list. .. note:: - The ``mon`` backend stores secrets in the Mon KV store, which is not an + The ``mon`` backend stores secrets in the Monitor KV store, which is not an external KMS or vault. Users and MGR modules with sufficient Ceph permissions can still reveal or resolve stored secret values. Namespaces provide logical and storage isolation, not an authorisation boundary. @@ -429,9 +429,6 @@ Configuration .. mgr_module:: ceph_secrets .. confval:: secrets_backend - :type: str - :default: ``mon`` - - The storage backend used for secrets. Currently only the Mon KV store + The storage backend used for secrets. Currently only the Monitor KV store (``mon``) is supported. This option is reserved for future backends (e.g. HashiCorp Vault). diff --git a/doc/rados/troubleshooting/troubleshooting-mon.rst b/doc/rados/troubleshooting/troubleshooting-mon.rst index 791b8a7b53a..55e68be5e75 100644 --- a/doc/rados/troubleshooting/troubleshooting-mon.rst +++ b/doc/rados/troubleshooting/troubleshooting-mon.rst @@ -565,7 +565,7 @@ from a service shell), the restored ``kv_backend`` file and the rehydrated them. Restoring a multi-monitor cluster -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each monitor has its own Paxos state (rank, accepted proposal numbers, ``last_committed``), so backups are per-monitor: a backup taken from diff --git a/doc/radosgw/adminops.rst b/doc/radosgw/adminops.rst index 17da43773a0..20fce8a7894 100644 --- a/doc/radosgw/adminops.rst +++ b/doc/radosgw/adminops.rst @@ -2946,7 +2946,7 @@ CLI commands. To view dedup status, the user must have ``dedup=read`` capability. To control dedup operations, the user must have ``dedup=write`` capability. -See the `Admin Guide`_ for details. +See the :ref:`radosgw-admin-guide` for details. Get Dedup Stats ~~~~~~~~~~~~~~~ diff --git a/doc/radosgw/encryption.rst b/doc/radosgw/encryption.rst index df91e38de99..1bd07af26ff 100644 --- a/doc/radosgw/encryption.rst +++ b/doc/radosgw/encryption.rst @@ -160,6 +160,7 @@ Secrets are stored using the `Linux Kernel Key Retention Service`_ in the RGW processes' process keyring. This is subject to a global quota and must be set in accordance with the configured cache size. Depending on whether RGW runs as root, these quotas can be managed by adjusting: + - ``/proc/sys/kernel/keys/root_maxkeys`` and ``/proc/sys/kernel/keys/root_maxbytes`` - ``/proc/sys/kernel/keys/maxkeys`` and ``/proc/sys/kernel/keys/maxbytes`` @@ -167,6 +168,7 @@ Exceeding a quota will disable the cache, fail the request with an internal error, and log a failure message. Three different Cache Time-to-Live (TTL) values can be set: + - **Positive TTL**: How long a successfully retrieved secret remains in the cache. - **Negative TTL**: How long to remember that a key does not exist, @@ -178,6 +180,7 @@ Metrics --------- The cache exports metrics under the ``kms-cache`` collection. + - ``hit``: Hit counter - ``miss``: Miss counter - ``expired``: Number of TTL expired entries @@ -187,6 +190,7 @@ The cache exports metrics under the ``kms-cache`` collection. ``miss``, ``expired`` In addition the ``rgw`` collection has: + - ``kms_fetch_lat``: Average KMS fetch latency. Also includes a successful request counter. Each event results in a positive cache entry. -- 2.47.3