doc: update documents on using kcephfs

Overhaul the fstab.rst and kernel.rst files with more relevant examples
now that the mount helper does autodiscovery. Add a preamble to
kernel-features.rst and add a warning about the deprecation of inline
data.

Fixes: https://tracker.ceph.com/issues/42025
Signed-off-by: Jeff Layton <jlayton@redhat.com>

diff --git a/doc/cephfs/fstab.rst b/doc/cephfs/fstab.rst
index 6274d0a96957baee6f82b36fc4d4673f85f889fe..7e1a7674fce6e24164a06447530b262e7d42dea5 100644 (file)
--- a/doc/cephfs/fstab.rst
+++ b/doc/cephfs/fstab.rst
@@ -11,11 +11,11 @@ Kernel Driver
 To mount CephFS in your file systems table as a kernel driver, add the
 following to ``/etc/fstab``::
 
-       {ipaddress}:{port}:/ {mount}/{mountpoint} {file-system-name}    [name=username,secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}]
+       [{ipaddress}:{port}]:/ {mount}/{mountpoint} ceph [name=username,secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}]
 
 For example:: 
 
-       10.10.10.10:6789:/     /mnt/ceph    ceph    name=admin,noatime,_netdev    0       2
+       :/     /mnt/ceph    ceph    name=admin,noatime,_netdev    0       2
        
 The default for the ``name=`` parameter is ``guest``. If the ``secret`` or
 ``secretfile`` options are not specified then the mount helper will attempt to

diff --git a/doc/cephfs/kernel-features.rst b/doc/cephfs/kernel-features.rst
index d128b51a759338514a99d9593d9b9cf0b42acb9e..c025c7a52cb9eca5500f0b9651713658c7d9f1e2 100644 (file)
--- a/doc/cephfs/kernel-features.rst
+++ b/doc/cephfs/kernel-features.rst
@@ -1,13 +1,20 @@
 
-Supported Features of Kernel Driver
+Supported Features of the Kernel Driver
 ========================================
+The kernel driver is developed separately from the core ceph code, and as
+such it sometimes differs from the FUSE driver in feature implementation.
+The following details the implementation status of various CephFS features
+in the kernel driver.
 
 Inline data
 -----------
-Inline data was introduced by the Firefly release. Linux kernel clients >= 3.19
-can read inline data, can convert existing inline data to RADOS objects when
-file data is modified. At present, Linux kernel clients do not store file data
-as inline data.
+Inline data was introduced by the Firefly release. This feature is being
+deprecated in mainline CephFS, and may be removed from a future kernel
+release.
+
+Linux kernel clients >= 3.19 can read inline data and convert existing
+inline data to RADOS objects when file data is modified. At present,
+Linux kernel clients do not store file data as inline data.
 
 See `Experimental Features`_ for more information.
 

diff --git a/doc/cephfs/kernel.rst b/doc/cephfs/kernel.rst
index 16702cbcab282a63a246cba1fceecce8d060431c..472f79486bae1df56ed150183119d579e993cd8f 100644 (file)
--- a/doc/cephfs/kernel.rst
+++ b/doc/cephfs/kernel.rst
@@ -2,36 +2,52 @@
  Mount CephFS with the Kernel Driver
 ====================================
 
-To mount CephFS with the Kernel Driver you may use the ``mount`` command if you know the
-monitor host IP address(es), or use the ``mount.ceph`` utility to resolve the 
-monitor host name(s) into IP address(es) for you. For example:: 
+It is recommended to install the ``/sbin/mount.ceph`` kernel mount
+helper if working with the kernel cephfs driver. To mount CephFS with
+the kernel driver you may use the ``mount`` command::
 
-       sudo mkdir /mnt/mycephfs
-       sudo mount -t ceph 192.168.0.1:6789:/ /mnt/mycephfs
+       # mkdir /mnt/mycephfs
+       # mount -t ceph :/ /mnt/mycephfs
 
-To mount the Ceph file system with ``cephx`` authentication enabled, the kernel
-must authenticate with the cluster. The default ``name=`` option is ``guest``.
-The mount.ceph helper will automatically attempt to find a secret key in the
-keyring.
+Omitting the monitor addresses will cue ``mount.ceph`` to look them up
+in the local configuration file.  If you know at least one of the monitor
+addresses and ports you can specify them directly in a comma-separated
+list, and the kernel will avoid looking them up::
 
-The secret can also be specified manually with the ``secret=`` option. ::
+        # mount -t ceph 192.168.0.1:6789,192.168.0.2:6789:/ /mnt/mycephfs
 
-       sudo mount -t ceph 192.168.0.1:6789:/ /mnt/mycephfs -o name=admin,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
+To mount a subtree of the cephfs root, append the path to the device
+string ::
 
-The foregoing usage leaves the secret in the Bash history. A more secure
-approach reads the secret from a file. For example::
+        # mount -t ceph :/subvolume/dir1/dir2  /mnt/mycephfs -o name=fs
 
-       sudo mount -t ceph 192.168.0.1:6789:/ /mnt/mycephfs -o name=admin,secretfile=/etc/ceph/admin.secret
+To mount the Ceph file system with ``cephx`` authentication enabled, the
+kernel must authenticate with the cluster. The default ``name=`` option
+is ``guest``.  The mount.ceph helper will automatically attempt to find
+a secret key in a cephx keyring if it's not specified. For example, to
+mount the filesystem as the cephx user ``fs``::
+
+        # mount -t ceph :/ /mnt/mycephfs -o name=fs
+
+The secret can also be specified manually with the ``secret=`` option.::
+
+       # mount -t ceph :/ /mnt/mycephfs -o name=fs,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
+
+For legacy usage, mount.ceph can be told to read a lone secret from a
+file. For example::
+
+       # mount -t ceph :/ /mnt/mycephfs -o name=fs,secretfile=/etc/ceph/admin.secret
 
 See `User Management`_ for details on cephx.
 
 If you have more than one file system, specify which one to mount using
+the ``mds_namespace`` option, e.g.::
 
-the ``mds_namespace`` option, e.g. ``-o mds_namespace=myfs``.
+        # mount -t ceph :/ -o name=fs,mds_namespace=myfs
 
 To unmount the Ceph file system, you may use the ``umount`` command. For example:: 
 
-       sudo umount /mnt/mycephfs
+       # umount /mnt/mycephfs
 
 .. tip:: Ensure that you are not within the file system directories before
    executing this command.