doc: update and improve "mount using kernel driver" doc

Move the examples of mount command for Ceph cluster with CephX enabled
to the top of page, since it is enabled by default, improve explanation
around Ceph with multiple FSs, get rid of hash symbols before every
command (without them it's clear that the text is command and with them
the reader cannot use the commands directly), link fstab page, add how
mount in general looks, add prerequisites required for kernel mounts and
expand explanation wherever possible.

Fixes: https://tracker.ceph.com/issues/42220
Signed-off-by: Rishabh Dave <ridave@redhat.com>

2 files changed, 99 insertions, 36 deletions

diff --git a/doc/cephfs/index.rst b/doc/cephfs/index.rst
index 7bae92378e8..9f876422832 100644
--- a/doc/cephfs/index.rst
+++ b/doc/cephfs/index.rst
@@ -91,7 +91,7 @@ Mounting CephFS
    :hidden:
 
 	Create a CephFS file system <createfs>
-	Mount CephFS with the Kernel Driver <kernel>
+	Mount CephFS using Kernel Driver <kernel>
 	Mount CephFS using FUSE <fuse>
 	Mount CephFS in fstab <fstab>
 	Use the CephFS Shell <cephfs-shell>
diff --git a/doc/cephfs/kernel.rst b/doc/cephfs/kernel.rst
index 472f79486ba..c496415ca4c 100644
--- a/doc/cephfs/kernel.rst
+++ b/doc/cephfs/kernel.rst
@@ -1,58 +1,121 @@
-====================================
- Mount CephFS with the Kernel Driver
-====================================
+=================================
+ Mount CephFS using Kernel Driver
+=================================
 
-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::
+Prerequisite
+------------
+Before mounting CephFS, copy the Ceph configuration file and keyring for the
+CephX user that has CAPS to mount MDS to the client host (where CephFS will be
+mounted and used) from the host where Ceph Monitor resides. Please note that
+it's possible to mount CephFS without conf and keyring, but in that case, you
+would have to pass the MON's socket and CephX user's secret key manually to
+every mount command you run.
 
-	# mkdir /mnt/mycephfs
-	# mount -t ceph :/ /mnt/mycephfs
+#. Generate a minimal conf file for the client host and place it at a
+   standard location::
 
-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::
+    # on client host
+    mkdir /etc/ceph
+    ssh {user}@{mon-host} "sudo ceph config generate-minimal-conf" | sudo tee /etc/ceph/ceph.conf
 
-        # mount -t ceph 192.168.0.1:6789,192.168.0.2:6789:/ /mnt/mycephfs
+   Alternatively, you may copy the conf file. But the above method creates a
+   conf with minimum details which is better.
 
-To mount a subtree of the cephfs root, append the path to the device
-string ::
+#. Ensure that the conf file has appropriate permissions::
 
-        # mount -t ceph :/subvolume/dir1/dir2  /mnt/mycephfs -o name=fs
+    chmod 644 /etc/ceph/ceph.conf
 
-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``::
+#. Create a CephX user and get its secret key::
 
-        # mount -t ceph :/ /mnt/mycephfs -o name=fs
+    ssh {user}@{mon-host} "sudo ceph fs authorize cephfs client.foo / rw" | sudo tee /etc/ceph/ceph.client.foo.keyring
 
-The secret can also be specified manually with the ``secret=`` option.::
+   In above command, replace ``cephfs`` with the name of your CephFS, ``foo``
+   by the name you want for CephX user and ``/`` by the path within your
+   CephFS for which you want to allow access to the client and ``rw`` stands
+   for, both, read and write permissions. Alternatively, you may copy the Ceph
+   keyring from the MON host to client host at ``/etc/ceph`` but creating a
+   keyring specific to the client host is better.
 
-	# mount -t ceph :/ /mnt/mycephfs -o name=fs,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
+.. note:: If you get 2 prompts for password while running above any of 2 above
+   command, run ``sudo ls`` (or any other trivial command with sudo)
+   immediately before these commands.
 
-For legacy usage, mount.ceph can be told to read a lone secret from a
-file. For example::
+#. Ensure that the keyring has appropriate permissions::
 
-	# mount -t ceph :/ /mnt/mycephfs -o name=fs,secretfile=/etc/ceph/admin.secret
+    chmod 600 /etc/ceph/ceph.client.foo.keyring
 
-See `User Management`_ for details on cephx.
+#. ``mount.ceph`` helper is installed with Ceph packages. If for some reason
+   installing these packages is not feasible and/or ``mount.ceph`` is not
+   present on the system, you can still mount CephFS, but you'll need to
+   explicitly pass the monitor addreses and CephX user keyring. To verify that
+   it is installed, do::
 
-If you have more than one file system, specify which one to mount using
-the ``mds_namespace`` option, e.g.::
+    stat /sbin/mount.ceph
 
-        # mount -t ceph :/ -o name=fs,mds_namespace=myfs
+Synopsis
+--------
+In general, the command to mount CephFS via kernel driver looks like this::
 
-To unmount the Ceph file system, you may use the ``umount`` command. For example:: 
+    mount -t ceph {device-string}:{path-to-mounted} {mount-point} -o {key-value-args} {other-args}
 
-	# umount /mnt/mycephfs
+Mounting CephFS
+---------------
+On Ceph clusters, CephX is enabled by default. Use ``mount`` command to
+mount CephFS with the kernel driver::
+
+    mkdir /mnt/mycephfs
+    mount -t ceph :/ /mnt/mycephfs -o name=foo
+
+The key-value argument right after option ``-o`` is CephX credential;
+``name`` is the username of the CephX user we are using to mount CephFS. The
+default value for ``name`` is ``guest``.
+
+The kernel driver also requires MON's socket and the secret key for the CephX
+user. In case of the above command, ``mount.ceph`` helper figures out these
+details automatically by finding and reading Ceph conf file and keyring. In
+case you don't have these files on the host where you're running mount
+command, you can pass these details yourself too::
+
+    mount -t ceph 192.168.0.1:6789,192.168.0.2:6789:/ /mnt/mycephfs -o name=foo,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
+
+Passing a single MON socket in above command works too. A potential problem
+with the command above is that the secret key is left in your shell's command
+history. To prevent that you can copy the secret key inside a file and pass
+the file by using the option ``secretfile`` instead of ``secret``::
+
+    mount -t ceph :/ /mnt/mycephfs -o name=foo,secretfile=/etc/ceph/foo.secret
+
+Ensure the permissions on the secret key file are appropriate (preferably,
+``600``).
+
+In case CephX is disabled, you can omit ``-o`` and the list of key-value
+arguments that follow it::
+
+    mount -t ceph :/ /mnt/mycephfs
+
+To mount a subtree of the CephFS root, append the path to the device string::
+
+    mount -t ceph :/subvolume/dir1/dir2 /mnt/mycephfs -o name=fs
+
+If you have more than one file system on your Ceph cluster, you can mount the
+non-default FS on your local FS as follows::
+
+    mount -t ceph :/ /mnt/mycephfs2 -o name=fs,mds_namespace=mycephfs2
+
+Unmounting CephFS
+-----------------
+To unmount the Ceph file system, use the ``umount`` command as usual::
+
+    umount /mnt/mycephfs
 
 .. tip:: Ensure that you are not within the file system directories before
    executing this command.
 
-See `mount.ceph`_ for details. For troubleshooting, see :ref:`kernel_mount_debugging`.
+See fstab_ to find out how to make kernel mounted CephFS persist across
+reboots, `User Management`_ for details on CephX user management and
+mount.ceph_ manual for more options it can take. For troubleshooting, see
+:ref:`kernel_mount_debugging`.
 
-.. _mount.ceph: ../../man/8/mount.ceph/
+.. _fstab: ../fstab/#kernel-driver
 .. _User Management: ../../rados/operations/user-management/
+.. _mount.ceph: ../../man/8/mount.ceph/