ceph/doc/cephfs/fs-nfs-exports.rst

   1 =======================
   2 CephFS Exports over 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 -  Latest Ceph file system with mgr enabled
  12 -  'nfs-ganesha', 'nfs-ganesha-ceph', 'nfs-ganesha-rados-grace' and
  13    'nfs-ganesha-rados-urls' packages (version 3.3 and above)
  14
  15 Create NFS Ganesha Cluster
  16 ==========================
  17
  18 .. code:: bash
  19
  20     $ ceph nfs cluster create <type> <clusterid> [<placement>]
  21
  22 This creates a common recovery pool for all NFS Ganesha daemons, new user based on
  23 cluster_id, and a common NFS Ganesha config RADOS object.
  24
  25 NOTE: Since this command also brings up NFS Ganesha daemons using a ceph-mgr
  26 orchestrator module (see :doc:`/mgr/orchestrator`) such as "mgr/cephadm", at
  27 least one such module must be enabled for it to work.
  28
  29 <type> signifies the export type, which corresponds to the NFS Ganesha file
  30 system abstraction layer (FSAL). Permissible values are "cephfs" or "rgw", but
  31 currently only "cephfs" is supported.
  32
  33 <clusterid> is an arbitrary string by which this NFS Ganesha cluster will be
  34 known.
  35
  36 <placement> is an optional string signifying which hosts should have NFS Ganesha
  37 daemon containers running on them and, optionally, the total number of NFS
  38 Ganesha daemons the cluster (should you want to have more than one NFS Ganesha
  39 daemon running per node). For example, the following placement string means
  40 "deploy NFS Ganesha daemons on nodes host1 and host2 (one daemon per host):
  41
  42     "host1,host2"
  43
  44 and this placement specification says to deploy two NFS Ganesha daemons each
  45 on nodes host1 and host2 (for a total of four NFS Ganesha daemons in the
  46 cluster):
  47
  48     "4 host1,host2"
  49
  50 For more details on placement specification refer to the `orchestrator doc
  51 <https://docs.ceph.com/docs/master/mgr/orchestrator/#placement-specification>`_
  52 but keep in mind that specifying the placement via a YAML file is not supported.
  53
  54 Update NFS Ganesha Cluster
  55 ==========================
  56
  57 .. code:: bash
  58
  59     $ ceph nfs cluster update <clusterid> <placement>
  60
  61 This updates the deployed cluster according to the placement value.
  62
  63 Delete NFS Ganesha Cluster
  64 ==========================
  65
  66 .. code:: bash
  67
  68     $ ceph nfs cluster delete <clusterid>
  69
  70 This deletes the deployed cluster.
  71
  72 List NFS Ganesha Cluster
  73 ========================
  74
  75 .. code:: bash
  76
  77     $ ceph nfs cluster ls
  78
  79 This lists deployed clusters.
  80
  81 Show NFS Ganesha Cluster Information
  82 ====================================
  83
  84 .. code:: bash
  85
  86     $ ceph nfs cluster info [<clusterid>]
  87
  88 This displays ip and port of deployed cluster.
  89
  90 Set Customized NFS Ganesha Configuration
  91 ========================================
  92
  93 .. code:: bash
  94
  95     $ ceph nfs cluster config set <clusterid> -i <config_file>
  96
  97 With this the nfs cluster will use the specified config and it will have
  98 precedence over default config blocks.
  99
 100 Reset NFS Ganesha Configuration
 101 ===============================
 102
 103 .. code:: bash
 104
 105     $ ceph nfs cluster config reset <clusterid>
 106
 107 This removes the user defined configuration.
 108
 109 Create CephFS Export
 110 ====================
 111
 112 .. code:: bash
 113
 114     $ ceph nfs export create cephfs <fsname> <clusterid> <binding> [--readonly] [--path=/path/in/cephfs]
 115
 116 This creates export RADOS objects containing the export block, where
 117
 118 ``fsname`` is the name of the FS volume used by the NFS Ganesha cluster that will
 119 serve this export.
 120
 121 ``clusterid`` is the NFS Ganesha cluster ID.
 122
 123 ``binding`` is the pseudo root path (must be an absolute path).
 124
 125 Delete CephFS Export
 126 ====================
 127
 128 .. code:: bash
 129
 130     $ ceph nfs export delete <clusterid> <binding>
 131
 132 This deletes an export in an NFS Ganesha cluster, where:
 133
 134 ``clusterid`` is the NFS Ganesha cluster ID.
 135
 136 ``binding`` is the pseudo root path (must be an absolute path).
 137
 138 List CephFS Exports
 139 ===================
 140
 141 .. code:: bash
 142
 143     $ ceph nfs export ls <clusterid> [--detailed]
 144
 145 It lists exports for a cluster, where:
 146
 147 ``clusterid`` is the NFS Ganesha cluster ID.
 148
 149 With the ``--detailed`` option enabled it shows entire export block.
 150
 151 Get CephFS Export
 152 =================
 153
 154 .. code:: bash
 155
 156     $ ceph nfs export get <clusterid> <binding>
 157
 158 This displays export block for a cluster based on pseudo root name (binding),
 159 where:
 160
 161 ``clusterid`` is the NFS Ganesha cluster ID.
 162
 163 ``binding`` is the pseudo root path (must be an absolute path).
 164
 165 Configuring NFS Ganesha to export CephFS with vstart
 166 ====================================================
 167
 168 1) Using ``cephadm``
 169
 170     .. code:: bash
 171
 172         $ MDS=1 MON=1 OSD=3 NFS=1 ../src/vstart.sh -n -d --cephadm
 173
 174     This will deploy a single NFS Ganesha daemon using ``vstart.sh``, where:
 175
 176     The daemon will listen on the default NFS Ganesha port.
 177
 178 2) Using test orchestrator
 179
 180     .. code:: bash
 181
 182        $ MDS=1 MON=1 OSD=3 NFS=1 ../src/vstart.sh -n -d
 183
 184     This will deploy multiple NFS Ganesha daemons, each listening on a random
 185     port, where:
 186
 187     ``NFS`` is the number of NFS Ganesha clusters to be created.
 188
 189     NOTE: NFS Ganesha packages must be pre-installed for this to work.
 190
 191 Mount
 192 =====
 193
 194 After the exports are successfully created and NFS Ganesha daemons are no longer in
 195 grace period. The exports can be mounted by
 196
 197 .. code:: bash
 198
 199     $ mount -t nfs -o port=<ganesha-port> <ganesha-host-name>:<ganesha-pseudo-path> <mount-point>
 200
 201 .. note:: Only NFS v4.0+ is supported.