ceph/doc/cephfs/nfs.rst

   1 ===
   2 NFS
   3 ===
   4
   5 CephFS namespaces can be exported over NFS protocol using the
   6 `NFS-Ganesha NFS server <https://github.com/nfs-ganesha/nfs-ganesha/wiki>`_.
   7
   8 Requirements
   9 ============
  10
  11 -  Ceph filesystem (preferably latest stable luminous or higher versions)
  12 -  In the NFS server host machine, 'libcephfs2' (preferably latest stable
  13    luminous or higher), 'nfs-ganesha' and 'nfs-ganesha-ceph' packages (latest
  14    ganesha v2.5 stable or higher versions)
  15 -  NFS-Ganesha server host connected to the Ceph public network
  16
  17 Configuring NFS-Ganesha to export CephFS
  18 ========================================
  19
  20 NFS-Ganesha provides a File System Abstraction Layer (FSAL) to plug in different
  21 storage backends. `FSAL_CEPH <https://github.com/nfs-ganesha/nfs-ganesha/tree/next/src/FSAL/FSAL_CEPH>`_
  22 is the plugin FSAL for CephFS. For each NFS-Ganesha export, FSAL_CEPH uses a
  23 libcephfs client, user-space CephFS client, to mount the CephFS path that
  24 NFS-Ganesha exports.
  25
  26 Setting up NFS-Ganesha with CephFS, involves setting up NFS-Ganesha's
  27 configuration file, and also setting up a Ceph configuration file and cephx
  28 access credentials for the Ceph clients created by NFS-Ganesha to access
  29 CephFS.
  30
  31 NFS-Ganesha configuration
  32 -------------------------
  33
  34 A sample ganesha.conf configured with FSAL_CEPH can be found here,
  35 `<https://github.com/nfs-ganesha/nfs-ganesha/blob/next/src/config_samples/ceph.conf>`_.
  36 It is suitable for a standalone NFS-Ganesha server, or an active/passive
  37 configuration of NFS-Ganesha servers managed by some sort of clustering
  38 software (e.g., Pacemaker). Important details about the options are
  39 added as comments in the sample conf. There are options to do the following:
  40
  41 - minimize Ganesha caching wherever possible since the libcephfs clients
  42   (of FSAL_CEPH) also cache aggressively
  43
  44 - read from Ganesha config files stored in RADOS objects
  45
  46 - store client recovery data in RADOS OMAP key-value interface
  47
  48 - mandate NFSv4.1+ access
  49
  50 - enable read delegations (need at least v13.0.1 'libcephfs2' package
  51   and v2.6.0 stable 'nfs-ganesha' and 'nfs-ganesha-ceph' packages)
  52
  53 Configuration for libcephfs clients
  54 -----------------------------------
  55
  56 Required ceph.conf for libcephfs clients includes:
  57
  58 * a [client] section with ``mon_host`` option set to let the clients connect
  59   to the Ceph cluster's monitors, e.g., ::
  60
  61     [client]
  62             mon host = 192.168.1.7:6789, 192.168.1.8:6789, 192.168.1.9:6789
  63
  64 Mount using NFSv4 clients
  65 =========================
  66
  67 It is preferred to mount the NFS-Ganesha exports using NFSv4.1+ protocols
  68 to get the benefit of sessions.
  69
  70 Conventions for mounting NFS resources are platform-specific. The
  71 following conventions work on Linux and some Unix platforms:
  72
  73 From the command line::
  74
  75   mount -t nfs -o nfsvers=4.1,proto=tcp <ganesha-host-name>:<ganesha-pseudo-path> <mount-point>
  76
  77 Current limitations
  78 ===================
  79
  80 - Per running ganesha daemon, FSAL_CEPH can only export one Ceph filesystem
  81   although multiple directories in a Ceph filesystem may be exported.