From: Anthony D'Atri <anthonyeleven@users.noreply.github.com>
Date: Sun, 28 Jun 2026 19:20:36 +0000 (-0400)
Subject: doc: Improve src/common/options/mds-client.yaml.in
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F69793%2Fhead;p=ceph.git

doc: Improve src/common/options/mds-client.yaml.in

Signed-off-by: Anthony D'Atri <anthonyeleven@users.noreply.github.com>
---

diff --git a/src/common/options/mds-client.yaml.in b/src/common/options/mds-client.yaml.in
index 94d717dfbe9..3291d941529 100644
--- a/src/common/options/mds-client.yaml.in
+++ b/src/common/options/mds-client.yaml.in
@@ -24,7 +24,7 @@ options:
 - name: client_use_random_mds
   type: bool
   level: dev
-  desc: issue new requests to a random active MDS
+  desc: Issue new requests to a random active MDS
   fmt_desc: Choose random MDS for each request.
   default: false
   services:
@@ -34,7 +34,7 @@ options:
   type: secs
   level: advanced
   desc: timeout for mounting CephFS (seconds)
-  fmt_desc: Set the timeout for CephFS mount in seconds.
+  fmt_desc: Set the timeout in seconds for CephFS mounts.
   default: 5_min
   services:
   - mds_client
@@ -42,21 +42,21 @@ options:
   type: secs
   level: dev
   desc: seconds between client upkeep ticks
-  fmt_desc: Set the interval in seconds between capability renewal and other upkeep.
+  fmt_desc: Set the interval in seconds between capability renewal and other upkeep iterations.
   default: 1
   services:
   - mds_client
 - name: client_trace
   type: str
   level: dev
-  desc: file containing trace of client operations
+  desc: File containing a trace of client operations
   services:
   - mds_client
   with_legacy: true
 - name: client_readahead_min
   type: size
   level: advanced
-  desc: minimum bytes to readahead in a file
+  desc: Minimum bytes to read ahead in a file
   fmt_desc: Set the minimum number bytes that the client reads ahead.
   default: 128_K
   services:
@@ -65,7 +65,7 @@ options:
 - name: client_readahead_max_bytes
   type: size
   level: advanced
-  desc: maximum bytes to readahead in a file (zero is unlimited)
+  desc: Maximum bytes to read ahead in a file (zero is unlimited)
   fmt_desc: Set the maximum number of bytes that the client reads ahead for
     future read operations. Overridden by the ``client_readahead_max_periods``
     setting.
@@ -77,7 +77,7 @@ options:
 - name: client_readahead_max_periods
   type: int
   level: advanced
-  desc: maximum stripe periods to readahead in a file
+  desc: Maximum stripe periods to read ahead in a file
   fmt_desc: Set the number of file layout periods (object size * number of
     stripes) that the client reads ahead. Overrides the
     ``client_readahead_max_bytes`` setting.
@@ -88,14 +88,14 @@ options:
 - name: client_reconnect_stale
   type: bool
   level: advanced
-  desc: reconnect when the session becomes stale
+  desc: Reconnect when the session becomes stale
   default: false
   services:
   - mds_client
 - name: client_snapdir
   type: str
   level: advanced
-  desc: pseudo directory for snapshot access to a directory
+  desc: Subdirectory name for snapshot access (not a real subdirectory)
   fmt_desc: Set the snapshot directory name.
   default: .snap
   services:
@@ -104,8 +104,8 @@ options:
 - name: client_mountpoint
   type: str
   level: advanced
-  desc: default mount-point
-  fmt_desc: Directory to mount on the CephFS file system. An alternative to the
+  desc: Default mountpoint
+  fmt_desc: Directory on which to mount a the CephFS file system. An alternative to the
     ``-r`` option of the ``ceph-fuse`` command.
   default: /
   services:
@@ -113,7 +113,7 @@ options:
 - name: client_mount_uid
   type: int
   level: advanced
-  desc: uid to mount as
+  desc: UID as which to mount
   default: -1
   services:
   - mds_client
@@ -122,7 +122,7 @@ options:
 - name: client_mount_gid
   type: int
   level: advanced
-  desc: gid to mount as
+  desc: GID as which to mount
   fmt_desc: Set the group ID of CephFS mount.
   default: -1
   services:
@@ -149,7 +149,7 @@ options:
   services:
   - mds_client
   fmt_desc: Set the delay between capability releases in seconds. The delay
-    sets how many   seconds a client waits to release capabilities that it no
+    sets how many seconds a client waits to release capabilities that it no
     longer needs in case the capabilities are needed for another user space
     operation.
 - name: client_quota_df
@@ -164,7 +164,7 @@ options:
 - name: client_oc
   type: bool
   level: advanced
-  desc: enable object caching
+  desc: Enable object caching
   default: true
   services:
   - mds_client
@@ -172,8 +172,8 @@ options:
 - name: client_oc_size
   type: size
   level: advanced
-  desc: maximum size of object cache
-  fmt_desc: Set how many bytes of data will the client cache.
+  desc: Maximum size of object cache
+  fmt_desc: Set how many bytes of data the client may cache.
   default: 200_M
   services:
   - mds_client
@@ -184,7 +184,7 @@ options:
 - name: client_oc_max_dirty
   type: size
   level: advanced
-  desc: maximum size of dirty pages in object cache
+  desc: Maximum size of dirty pages in object cache
   fmt_desc: Set the maximum number of dirty bytes in the object cache.
   default: 100_M
   services:
@@ -196,7 +196,7 @@ options:
 - name: client_oc_target_dirty
   type: size
   level: advanced
-  desc: target size of dirty pages object cache
+  desc: Target size of dirty pages object cache
   fmt_desc: Set the target size of dirty data. We recommend to keep this number low.
   default: 8_M
   services:
@@ -207,7 +207,7 @@ options:
 - name: client_oc_max_dirty_age
   type: float
   level: advanced
-  desc: maximum age of dirty pages in object cache (seconds)
+  desc: Maximum age in seconds of dirty pages in the object cache
   fmt_desc: Set the maximum age in seconds of dirty data in the object cache
     before writeback.
   default: 5
@@ -219,7 +219,7 @@ options:
 - name: client_oc_max_objects
   type: int
   level: advanced
-  desc: maximum number of objects in cache
+  desc: Maximum number of objects in the cache
   fmt_desc: Set the maximum number of objects in the object cache.
   default: 1000
   services:
@@ -227,18 +227,18 @@ options:
   flags:
   - runtime
   with_legacy: true
-# check if MDS reply contains wanted caps
 - name: client_debug_getattr_caps
   type: bool
   level: dev
+  desc: Should the client check MDS replies for wanted capabiliites?
   default: false
   services:
   - mds_client
   with_legacy: true
-# always read synchronously (go to osds)
 - name: client_debug_force_sync_read
   type: bool
   level: dev
+  desc: Should the client bypass the local page cache?
   default: false
   services:
   - mds_client
@@ -263,24 +263,25 @@ options:
   type: size
   level: dev
   default: 4_K
+  desc: Maximum size of inlined data
   services:
   - mds_client
   fmt_desc: Set the maximum size of inlined data stored in a file inode rather
     than in a separate data object in RADOS. This setting only applies if the
     ``inline_data`` flag is set on the MDS map.
   with_legacy: true
-# synthetic client bug for testing
 - name: client_inject_release_failure
   type: bool
   level: dev
+  desc: Simulate a client inject release failure for testing purposes
   default: false
   services:
   - mds_client
   with_legacy: true
-# synthetic client bug for testing
 - name: client_inject_fixed_oldest_tid
   type: bool
   level: dev
+  desc: Simulate a specific client bug for testing purposes
   default: false
   services:
   - mds_client
@@ -288,7 +289,7 @@ options:
 - name: client_metadata
   type: str
   level: advanced
-  desc: metadata key=value comma-delimited pairs appended to session metadata
+  desc: Metadata key=value comma-delimited pairs to append to session metadata
   fmt_desc: Comma-delimited strings for client metadata sent to each MDS, in addition
     to the automatically generated version, host name, and other metadata.
   services:
@@ -307,7 +308,7 @@ options:
 - name: client_permissions
   type: bool
   level: advanced
-  desc: client-enforced permission checking
+  desc: Whether to enable client-enforced permission checking
   fmt_desc: Check client permissions on all I/O operations.
   default: true
   services:
@@ -317,9 +318,9 @@ options:
 - name: client_dirsize_rbytes
   type: bool
   level: advanced
-  desc: set the directory size as the number of file bytes recursively used
+  desc: Set the directory size as the number of file bytes recursively stored
   long_desc: This option enables a CephFS feature that stores the recursive directory
-    size (the bytes used by files in the directory and its descendents) in the st_size
+    size (the bytes stored in files in the directory and its descendents) in the st_size
     field of the stat structure. May confuse programs such as ``rsync``.
   default: true
   services:
@@ -330,6 +331,7 @@ options:
 - name: client_force_lazyio
   type: bool
   level: advanced
+  desc: Should the client force lazy IO?
   default: false
   services:
   - mds_client
@@ -338,14 +340,14 @@ options:
 - name: fuse_use_invalidate_cb
   type: bool
   level: advanced
-  desc: use fuse 2.8+ invalidate callback to keep page cache consistent
+  desc: Should the client use FUSE 2.8+ invalidate callback to keep page cache consistent?
   default: true
   services:
   - mds_client
 - name: fuse_disable_pagecache
   type: bool
   level: advanced
-  desc: disable page caching in the kernel for this FUSE mount
+  desc: Disable page caching in the kernel for this FUSE mount
   fmt_desc: If set to ``true``, kernel page cache is disabled for ``ceph-fuse``
     mounts. When multiple clients read/write to a file at the same
     time, readers may get stale data from page cache. Due to
@@ -356,14 +358,14 @@ options:
 - name: fuse_allow_other
   type: bool
   level: advanced
-  desc: pass allow_other to FUSE on mount
+  desc: Pass allow_other to FUSE on mount
   default: true
   services:
   - mds_client
 - name: fuse_default_permissions
   type: bool
   level: advanced
-  desc: pass default_permisions to FUSE on mount
+  desc: Pass default_permisions to FUSE on mount
   fmt_desc: When set to ``false``, ``ceph-fuse`` utility checks does its own
     permissions checking, instead of relying on the permissions enforcement in
     FUSE. Set to ``false`` together with the ``client acl type=posix_acl``
@@ -376,21 +378,21 @@ options:
 - name: fuse_splice_read
   type: bool
   level: advanced
-  desc: enable splice read to reduce the memory copies
+  desc: Enable splice read to reduce memory copies
   default: true
   services:
   - mds_client
 - name: fuse_splice_write
   type: bool
   level: advanced
-  desc: enable splice write to reduce the memory copies
+  desc: Enable splice write to reduce memory copies
   default: true
   services:
   - mds_client
 - name: fuse_splice_move
   type: bool
   level: advanced
-  desc: enable splice move to reduce the memory copies
+  desc: Enable splice move to reduce memory copies
   default: true
   services:
   - mds_client
@@ -404,7 +406,7 @@ options:
 - name: fuse_max_write
   type: size
   level: advanced
-  desc: set the maximum number of bytes in a single write operation
+  desc: Set the maximum number of bytes in a single write operation
   long_desc: Set the maximum number of bytes in a single write operation that may
     pass atomically through FUSE. The FUSE default is 128kB and may be indicated by
     setting this option to 0.
@@ -416,14 +418,14 @@ options:
 - name: fuse_atomic_o_trunc
   type: bool
   level: advanced
-  desc: pass atomic_o_trunc flag to FUSE on mount
+  desc: Pass the atomic_o_trunc flag to FUSE on mount
   default: true
   services:
   - mds_client
 - name: fuse_debug
   type: bool
   level: advanced
-  desc: enable debugging for the libfuse
+  desc: Enable debugging for libfuse
   default: false
   services:
   - mds_client
@@ -433,35 +435,36 @@ options:
 - name: fuse_multithreaded
   type: bool
   level: advanced
-  desc: allow parallel processing through FUSE library
+  desc: Allow parallel processing through the FUSE library
   default: true
   services:
   - mds_client
 - name: fuse_require_active_mds
   type: bool
   level: advanced
-  desc: require active MDSs in the file system when mounting
+  desc: Require active MDSes when mounting
   default: true
   services:
   - mds_client
 - name: fuse_syncfs_on_mksnap
   type: bool
   level: advanced
-  desc: synchronize all local metadata/file changes after snapshot
+  desc: Synchronize all local metadata/file changes after snapshot
   default: true
   services:
   - mds_client
 - name: fuse_set_user_groups
   type: bool
   level: advanced
-  desc: check for ceph-fuse to consider supplementary groups for permissions
+  desc: Should ceph-fuse consider supplementary groups for permissions?
   default: true
   services:
   - mds_client
-# the client should try to use dentry invalidation instead of remounting, on kernels it believes that will work for
 - name: client_try_dentry_invalidate
   type: bool
   level: dev
+  desc: Should the client try to use dentry invalidation instead of remounting, when it
+    believes this will work with the running kernel?
   default: false
   services:
   - mds_client
@@ -469,14 +472,15 @@ options:
 - name: client_max_retries_on_remount_failure
   type: uint
   level: advanced
-  desc: number of consecutive failed remount attempts for invalidating kernel dcache
-    after which client would abort.
+  desc: Number of consecutive failed remount attempts for invalidating kernel dcache
+    after which client will abort.
   default: 5
   services:
   - mds_client
 - name: client_die_on_failed_remount
   type: bool
   level: dev
+  desc: Should the client die on a failed remount?
   default: false
   services:
   - mds_client
@@ -494,7 +498,7 @@ options:
 - name: client_check_pool_perm
   type: bool
   level: advanced
-  desc: confirm access to inode's data pool/namespace described in file layout
+  desc: Confirm access to inode's data pool/namespace described in file layout
   default: true
   services:
   - mds_client
@@ -502,6 +506,7 @@ options:
 - name: client_use_faked_inos
   type: bool
   level: dev
+  desc: Should the client use fake inos?
   default: false
   services:
   - mds_client
@@ -558,7 +563,7 @@ options:
 - name: client_shutdown_timeout
   type: secs
   level: advanced
-  desc: timeout for shutting down CephFS
+  desc: Timeout for shutting down CephFS
   long_desc: Timeout for shutting down CephFS via unmount or shutdown.
   default: 30
   tags:
@@ -571,7 +576,7 @@ options:
 - name: client_collect_and_send_global_metrics
   type: bool
   level: advanced
-  desc: to enable and force collecting and sending the global metrics to MDS
+  desc: Whether to enable and force collecting and sending the global metrics to MDS
   long_desc: To be careful for this, when connecting to some old ceph clusters
     it may crash the MDS daemons while upgrading.
   default: false
@@ -605,7 +610,7 @@ options:
 - name: client_file_blockdiff_max_concurrent_object_scans
   type: uint
   level: advanced
-  desc: maximum number of concurrent object scans
+  desc: Maximum number of concurrent object scans
   long_desc: Maximum number of concurrent listsnaps operations sent to RADOS.
   default: 16
   services:
@@ -614,8 +619,11 @@ options:
 - name: client_inject_write_delay_secs
   type: secs
   level: dev
-  desc: induce delay in write operation for testing
-  long_desc: Inject a delay in write operation after grabbing required cap references (Fb caps in this case). This config is disabled by default (value of 0) and is to be used for the purpose of validating a race case bug with concurrent fsync.
+  desc: Induce delay in write operation for testing
+  long_desc: Inject a delay in write operation after grabbing required
+    cap references (Fb caps in this case). This config is disabled by
+    default (value of 0) and is to be used for the purpose of validating
+    a race case bug with concurrent fsync.
   default: 0
   services:
   - mds_client