[PATCH] mount: (manpage) add CephFS kernel client mount options

[PATCH] mount: (manpage) add CephFS kernel client mount options

[Viacheslav Dubeyko]

From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>

Currently, manpage for generic mount tool doesn't contain
explanation of CephFS kernel client mount options. This patch
adds the description of CephFS mount options into
file system specific mount options section.

Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
---
 sys-utils/mount.8.adoc | 86 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc
index 4571bd2bfd16..191a3fabf501 100644
--- a/sys-utils/mount.8.adoc
+++ b/sys-utils/mount.8.adoc
@@ -853,6 +853,7 @@ This section lists options that are specific to particular filesystems. Where po
 |===
 |*Filesystem(s)* |*Manual page*
 |btrfs |*btrfs*(5)
+|cephfs |*mount.ceph*(8)
 |cifs |*mount.cifs*(8)
 |ext2, ext3, ext4 |*ext4*(5)
 |fuse |*fuse*(8)
@@ -913,6 +914,91 @@ Give blocksize. Allowed values are 512, 1024, 2048, 4096.
 **grpquota**|**noquota**|**quota**|*usrquota*::
 These options are accepted but ignored. (However, quota utilities may react to such strings in _/etc/fstab_.)
 
+=== Mount options for ceph
+
+CephFS is a POSIX-compliant distributed filesystem provided by Ceph. For more information, see the Linux kernel documentation at _Documentation/filesystems/ceph.rst_ or the Ceph documentation at _https://docs.ceph.com/_.
+
+**mon_addr=**__ip_address__[**:**__port__][**/**__ip_address__[**:**__port__]]::
+Monitor address(es) to bootstrap the connection to the Ceph cluster. Multiple monitor addresses can be specified, separated by forward slashes. If a port is not specified, the default port 6789 is used.
+
+**fsid=**__cluster-id__::
+The cluster FSID (unique identifier). This can be obtained via the *ceph fsid* command.
+
+**ip=**__A.B.C.D__[**:**__N__]::
+Specifies the local IP address and optionally the port that the client should bind to.
+
+**conf=**__path__::
+Path to a _ceph.conf_ configuration file. This can be used for auto-discovery of monitor addresses and authentication secrets.
+
+**secret=**__key__::
+The CephX secret key for authentication. This option is insecure because it exposes the secret on the command line. Use *secretfile* instead when possible.
+
+**secretfile=**__path__::
+Path to a file containing the CephX secret key. This is the preferred method for providing authentication credentials.
+
+**fs=**__name__ or **mds_namespace=**__name__::
+Specify a non-default Ceph filesystem to mount. The *mds_namespace* option is the older syntax.
+
+**mount_timeout=**__seconds__::
+Timeout value for mount operations in seconds. Default is 60 seconds.
+
+**wsize=**__bytes__::
+Maximum write size in bytes. Default is 67108864 (64 MB).
+
+**rsize=**__bytes__::
+Maximum read size in bytes. Default is 67108864 (64 MB).
+
+**rasize=**__bytes__::
+Maximum readahead size in bytes. Default is 8388608 (8 MB).
+
+**caps_max=**__number__::
+Maximum number of capabilities (caps) to retain. When this limit is exceeded, unused caps are released. Default is 0 (no limit).
+
+*rbytes*::
+When *stat*(2) is called on a directory, set the *st_size* field to 'rbytes', the summation of file sizes over all files nested beneath that directory. This is the default behavior.
+
+*norbytes*::
+When *stat*(2) is called on a directory, set the *st_size* field to the number of entries in that directory instead of the recursive byte count.
+
+*dcache*::
+Enable directory entry cache (dcache) for negative lookup caching and readdir operations. This is the default behavior.
+
+*nodcache*::
+Disable directory entry cache usage. This disables negative lookup caching and dcache-assisted readdir operations.
+
+*noasyncreaddir*::
+Disable asynchronous readdir operations that use the dcache.
+
+*nocrc*::
+Disable CRC32C calculation for data writes. If set, the storage nodes must rely on TCP's error correction to detect data corruption in the data payload.
+
+**snapdirname=**__name__::
+Sets the name of the hidden snapshots directory. Default is _.snap_.
+
+*dirstat*::
+Enable reading of directory stats via *cat* on the directory.
+
+*nodirstat*::
+Disable reading of directory stats via *cat* on the directory.
+
+*noquotadf*::
+Report overall filesystem usage in statfs instead of the quota for the root directory.
+
+*nocopyfrom*::
+Disable the use of RADOS copy-from operations in *copy_file_range*(2). The RADOS copy-from operation allows the copy to be performed server-side, which can be more efficient.
+
+**recover_session=**{**no**|*clean*}::
+Control the auto-reconnect behavior when the client has been blocklisted. The default is *no*, which prevents reconnection. The *clean* option (available since Linux kernel 5.4) reconnects automatically when blocklisted, but discards any dirty data and invalidates all caches. This can result in data loss.
+
+**ms_mode=**{**legacy**|**crc**|**secure**|**prefer-crc**|*prefer-secure*}::
+Select the connection transport protocol. *legacy* uses the v1 protocol. *crc* uses the v2 protocol without encryption. *secure* uses the v2 protocol with encryption. *prefer-crc* and *prefer-secure* indicate a preference but will fall back if the preferred mode is not available.
+
+*wsync*::
+Execute namespace operations (file/directory creations, deletions, etc.) synchronously.
+
+*nowsync*::
+Execute namespace operations asynchronously. This is the default behavior since Linux kernel 5.7.
+
 === Mount options for debugfs
 
 The debugfs filesystem is a pseudo filesystem, traditionally mounted on _/sys/kernel/debug_. As of kernel version 3.4, debugfs has the following options:
-- 
2.52.0

Re: [PATCH] mount: (manpage) add CephFS kernel client mount options

[Karel Zak]

On Mon, Jan 12, 2026 at 12:58:38PM -0800, Viacheslav Dubeyko wrote:
> From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
> 
> Currently, manpage for generic mount tool doesn't contain
> explanation of CephFS kernel client mount options. This patch
> adds the description of CephFS mount options into
> file system specific mount options section.
> 
> Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
> ---
>  sys-utils/mount.8.adoc | 86 ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 86 insertions(+)
> 
> diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc
> index 4571bd2bfd16..191a3fabf501 100644
> --- a/sys-utils/mount.8.adoc
> +++ b/sys-utils/mount.8.adoc
> @@ -853,6 +853,7 @@ This section lists options that are specific to particular filesystems. Where po
>  |===
>  |*Filesystem(s)* |*Manual page*
>  |btrfs |*btrfs*(5)
> +|cephfs |*mount.ceph*(8)

It seems that all we need is this change.

>  |cifs |*mount.cifs*(8)
>  |ext2, ext3, ext4 |*ext4*(5)
>  |fuse |*fuse*(8)
> @@ -913,6 +914,91 @@ Give blocksize. Allowed values are 512, 1024, 2048, 4096.
>  **grpquota**|**noquota**|**quota**|*usrquota*::
>  These options are accepted but ignored. (However, quota utilities may react to such strings in _/etc/fstab_.)
>  
> +=== Mount options for ceph

If mount.ceph(8) exists, we do not need to repeat the mount option in
mount(8). The ideal solution is to keep filesystem-specific mount
options in the filesystem-specific man page maintained by the
filesystem developer :-)  See btrfs, extN, XFS, etc.

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

RE: [PATCH] mount: (manpage) add CephFS kernel client mount options

[Viacheslav Dubeyko]

On Tue, 2026-01-13 at 20:14 +0100, Karel Zak wrote:
> On Mon, Jan 12, 2026 at 12:58:38PM -0800, Viacheslav Dubeyko wrote:
> > From: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
> > 
> > Currently, manpage for generic mount tool doesn't contain
> > explanation of CephFS kernel client mount options. This patch
> > adds the description of CephFS mount options into
> > file system specific mount options section.
> > 
> > Signed-off-by: Viacheslav Dubeyko <Slava.Dubeyko@ibm.com>
> > ---
> >  sys-utils/mount.8.adoc | 86 ++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 86 insertions(+)
> > 
> > diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc
> > index 4571bd2bfd16..191a3fabf501 100644
> > --- a/sys-utils/mount.8.adoc
> > +++ b/sys-utils/mount.8.adoc
> > @@ -853,6 +853,7 @@ This section lists options that are specific to particular filesystems. Where po
> >  |===
> >  |*Filesystem(s)* |*Manual page*
> >  |btrfs |*btrfs*(5)
> > +|cephfs |*mount.ceph*(8)
> 
> It seems that all we need is this change.
> 
> >  |cifs |*mount.cifs*(8)
> >  |ext2, ext3, ext4 |*ext4*(5)
> >  |fuse |*fuse*(8)
> > @@ -913,6 +914,91 @@ Give blocksize. Allowed values are 512, 1024, 2048, 4096.
> >  **grpquota**|**noquota**|**quota**|*usrquota*::
> >  These options are accepted but ignored. (However, quota utilities may react to such strings in _/etc/fstab_.)
> >  
> > +=== Mount options for ceph
> 
> If mount.ceph(8) exists, we do not need to repeat the mount option in
> mount(8). The ideal solution is to keep filesystem-specific mount
> options in the filesystem-specific man page maintained by the
> filesystem developer :-)  See btrfs, extN, XFS, etc.
> 

My assumption was that if other file systems have description of specific mount
options in this man page, then CephFS should have too. :) But if it is not right
strategy, then you are correct here.

Let me shrink my patch then.

Thanks,
Slava.

Re: [PATCH] mount: (manpage) add CephFS kernel client mount options

[Karel Zak]

On Tue, Jan 13, 2026 at 07:29:00PM +0000, Viacheslav Dubeyko wrote:
> My assumption was that if other file systems have description of specific mount
> options in this man page, then CephFS should have too. :) 

Unfortunately, some filesystems lack specific man pages, so mount.8
serves as a fallback solution for them. In an ideal world, mount.8
would not include filesystem-specific mount options.

I have added a link to mount.ceph in mount.8
https://github.com/util-linux/util-linux/commit/de7973f9906da09b86f221b030ec836c1e91fd22

Thank you for the suggestion!

 Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com