doc/cephfs: improve nfs.rst

Signed-off-by: Rishabh Dave <ridave@redhat.com>

diff --git a/doc/cephfs/nfs.rst b/doc/cephfs/nfs.rst
index 17bf4303eb13294465b7f7650ecf36ff2f093f0f..169894aeb73faa147d1366b456c27372a5f64a6d 100644 (file)
--- a/doc/cephfs/nfs.rst
+++ b/doc/cephfs/nfs.rst
@@ -3,43 +3,43 @@ NFS
 ===
 
 CephFS namespaces can be exported over NFS protocol using the
-`NFS-Ganesha NFS server <https://github.com/nfs-ganesha/nfs-ganesha/wiki>`_.
+`NFS-Ganesha NFS server`_.
 
 Requirements
 ============
 
--  Ceph file system (preferably latest stable luminous or higher versions)
--  In the NFS server host machine, 'libcephfs2' (preferably latest stable
-   luminous or higher), 'nfs-ganesha' and 'nfs-ganesha-ceph' packages (latest
-   ganesha v2.5 stable or higher versions)
+-  Ceph file system
+-  ``libcephfs2``, ``nfs-ganesha`` and ``nfs-ganesha-ceph`` packages on NFS
+   server host machine.
 -  NFS-Ganesha server host connected to the Ceph public network
 
+.. note::
+   Ceph packages should preferably be latest stable luminous or a higher
+   version and NFS-Ganesha packages must be v2.5 stable or higher versions.
+
 Configuring NFS-Ganesha to export CephFS
 ========================================
 
-NFS-Ganesha provides a File System Abstraction Layer (FSAL) to plug in different
-storage backends. `FSAL_CEPH <https://github.com/nfs-ganesha/nfs-ganesha/tree/next/src/FSAL/FSAL_CEPH>`_
-is the plugin FSAL for CephFS. For each NFS-Ganesha export, FSAL_CEPH uses a
-libcephfs client, user-space CephFS client, to mount the CephFS path that
-NFS-Ganesha exports.
+NFS-Ganesha provides a File System Abstraction Layer (FSAL) to plug in
+different storage backends. FSAL_CEPH_ is the plugin FSAL for CephFS. For
+each NFS-Ganesha export, FSAL_CEPH_ uses a libcephfs client to mount the
+CephFS path that NFS-Ganesha exports.
 
-Setting up NFS-Ganesha with CephFS, involves setting up NFS-Ganesha's
-configuration file, and also setting up a Ceph configuration file and cephx
-access credentials for the Ceph clients created by NFS-Ganesha to access
-CephFS.
+Setting up NFS-Ganesha with CephFS, involves setting up NFS-Ganesha's and
+Ceph's configuration file and CephX access credentials for the Ceph clients
+created by NFS-Ganesha to access CephFS.
 
 NFS-Ganesha configuration
 -------------------------
 
-A sample ganesha.conf configured with FSAL_CEPH can be found here,
-`<https://github.com/nfs-ganesha/nfs-ganesha/blob/next/src/config_samples/ceph.conf>`_.
-It is suitable for a standalone NFS-Ganesha server, or an active/passive
-configuration of NFS-Ganesha servers managed by some sort of clustering
-software (e.g., Pacemaker). Important details about the options are
-added as comments in the sample conf. There are options to do the following:
+Here's a `sample ganesha.conf`_ configured with FSAL_CEPH_. It is suitable
+for a standalone NFS-Ganesha server, or an active/passive configuration of
+NFS-Ganesha servers, to be managed by some sort of clustering software
+(e.g., Pacemaker). Important details about the options are added as comments
+in the sample conf. There are options to do the following:
 
 - minimize Ganesha caching wherever possible since the libcephfs clients
-  (of FSAL_CEPH) also cache aggressively
+  (of FSAL_CEPH_) also cache aggressively
 
 - read from Ganesha config files stored in RADOS objects
 
@@ -47,18 +47,18 @@ added as comments in the sample conf. There are options to do the following:
 
 - mandate NFSv4.1+ access
 
-- enable read delegations (need at least v13.0.1 'libcephfs2' package
-  and v2.6.0 stable 'nfs-ganesha' and 'nfs-ganesha-ceph' packages)
+- enable read delegations (need at least v13.0.1 ``libcephfs2`` package
+  and v2.6.0 stable ``nfs-ganesha`` and ``nfs-ganesha-ceph`` packages)
 
 Configuration for libcephfs clients
 -----------------------------------
 
-Required ceph.conf for libcephfs clients includes:
-
-* a [client] section with ``mon_host`` option set to let the clients connect
-  to the Ceph cluster's monitors, usually generated via ``ceph config generate-minimal-conf``, e.g., ::
+``ceph.conf`` for libcephfs clients includes a ``[client]`` section with
+``mon_host`` option set to let the clients connect to the Ceph cluster's
+monitors, usually generated via ``ceph config generate-minimal-conf``.
+For example::
 
-    [global]
+    [client]
             mon host = [v2:192.168.1.7:3300,v1:192.168.1.7:6789], [v2:192.168.1.8:3300,v1:192.168.1.8:6789], [v2:192.168.1.9:3300,v1:192.168.1.9:6789]
 
 Mount using NFSv4 clients
@@ -70,12 +70,17 @@ to get the benefit of sessions.
 Conventions for mounting NFS resources are platform-specific. The
 following conventions work on Linux and some Unix platforms:
 
-From the command line::
+.. code:: bash
 
-  mount -t nfs -o nfsvers=4.1,proto=tcp <ganesha-host-name>:<ganesha-pseudo-path> <mount-point>
+    mount -t nfs -o nfsvers=4.1,proto=tcp <ganesha-host-name>:<ganesha-pseudo-path> <mount-point>
 
 Current limitations
 ===================
 
-- Per running ganesha daemon, FSAL_CEPH can only export one Ceph file system
+- Per running ganesha daemon, FSAL_CEPH_ can only export one Ceph file system
   although multiple directories in a Ceph file system may be exported.
+
+
+.. _FSAL_CEPH: https://github.com/nfs-ganesha/nfs-ganesha/tree/next/src/FSAL/FSAL_CEPH
+.. _NFS-Ganesha NFS server: https://github.com/nfs-ganesha/nfs-ganesha/wiki
+.. _sample ganesha.conf: https://github.com/nfs-ganesha/nfs-ganesha/blob/next/src/config_samples/ceph.conf