ceph/doc/cephfs/mount-using-kernel-driver.rst

   1 =================================
   2  Mount CephFS using Kernel Driver
   3 =================================
   4
   5 The CephFS kernel driver is part of the Linux kernel. It allows mounting
   6 CephFS as a regular file system with native kernel performance. It is the
   7 client of choice for most use-cases.
   8
   9 .. note:: CephFS mount device string now uses a new (v2) syntax. The mount
  10           helper (and the kernel) is backward compatible with the old syntax.
  11           This means that the old syntax can still be used for mounting with
  12           newer mount helpers and kernel. However, it is recommended to use
  13           the new syntax whenever possible.
  14
  15 Prerequisites
  16 =============
  17
  18 Complete General Prerequisites
  19 ------------------------------
  20 Go through the prerequisites required by both, kernel as well as FUSE mounts,
  21 in `Mount CephFS: Prerequisites`_ page.
  22
  23 Is mount helper is present?
  24 ---------------------------
  25 ``mount.ceph`` helper is installed by Ceph packages. The helper passes the
  26 monitor address(es) and CephX user keyrings automatically saving the Ceph
  27 admin the effort to pass these details explicitly while mounting CephFS. In
  28 case the helper is not present on the client machine, CephFS can still be
  29 mounted using kernel but by passing these details explicitly to the ``mount``
  30 command. To check whether it is present on your system, do::
  31
  32     stat /sbin/mount.ceph
  33
  34 Which Kernel Version?
  35 ---------------------
  36
  37 Because the kernel client is distributed as part of the linux kernel (not
  38 as part of packaged ceph releases), you will need to consider which kernel
  39 version to use on your client nodes. Older kernels are known to include buggy
  40 ceph clients, and may not support features that more recent Ceph clusters
  41 support.
  42
  43 Remember that the "latest" kernel in a stable linux distribution is likely
  44 to be years behind the latest upstream linux kernel where Ceph development
  45 takes place (including bug fixes).
  46
  47 As a rough guide, as of Ceph 10.x (Jewel), you should be using a least a 4.x
  48 kernel. If you absolutely have to use an older kernel, you should use the
  49 fuse client instead of the kernel client.
  50
  51 This advice does not apply if you are using a linux distribution that
  52 includes CephFS support, as in this case the distributor will be responsible
  53 for backporting fixes to their stable kernel: check with your vendor.
  54
  55 Synopsis
  56 ========
  57 In general, the command to mount CephFS via kernel driver looks like this::
  58
  59   mount -t ceph {device-string}={path-to-mounted} {mount-point} -o {key-value-args} {other-args}
  60
  61 Mounting CephFS
  62 ===============
  63 On Ceph clusters, CephX is enabled by default. Use ``mount`` command to
  64 mount CephFS with the kernel driver::
  65
  66   mkdir /mnt/mycephfs
  67   mount -t ceph <name>@<fsid>.<fs_name>=/ /mnt/mycephfs
  68
  69 ``name`` is the username of the CephX user we are using to mount CephFS.
  70 ``fsid`` is the FSID of the ceph cluster which can be found using
  71 ``ceph fsid`` command. ``fs_name`` is the file system to mount. The kernel
  72 driver requires MON's socket and the secret key for the CephX user, e.g.::
  73
  74   mount -t ceph cephuser@b3acfc0d-575f-41d3-9c91-0e7ed3dbb3fa.cephfs=/ -o mon_addr=192.168.0.1:6789,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
  75
  76 When using the mount helper, monitor hosts and FSID are optional. ``mount.ceph``
  77 helper figures out these details automatically by finding and reading ceph conf
  78 file, .e.g::
  79
  80   mount -t ceph cephuser@.cephfs=/ -o secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ==
  81
  82 .. note:: Note that the dot (``.``) still needs to be a part of the device string.
  83
  84 A potential problem with the above command is that the secret key is left in your
  85 shell's command history. To prevent that you can copy the secret key inside a file
  86 and pass the file by using the option ``secretfile`` instead of ``secret``::
  87
  88   mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs -o secretfile=/etc/ceph/cephuser.secret
  89
  90 Ensure the permissions on the secret key file are appropriate (preferably, ``600``).
  91
  92 Multiple monitor hosts can be passed by separating each address with a ``/``::
  93
  94   mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs -o mon_addr=192.168.0.1:6789/192.168.0.2:6789,secretfile=/etc/ceph/cephuser.secret
  95
  96 In case CephX is disabled, you can omit any credential related options::
  97
  98   mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs
  99
 100 .. note:: The ceph user name still needs to be passed as part of the device string.
 101
 102 To mount a subtree of the CephFS root, append the path to the device string::
 103
 104   mount -t ceph cephuser@.cephfs=/subvolume/dir1/dir2 /mnt/mycephfs -o secretfile=/etc/ceph/cephuser.secret
 105
 106 Unmounting CephFS
 107 =================
 108 To unmount the Ceph file system, use the ``umount`` command as usual::
 109
 110     umount /mnt/mycephfs
 111
 112 .. tip:: Ensure that you are not within the file system directories before
 113    executing this command.
 114
 115 Persistent Mounts
 116 ==================
 117
 118 To mount CephFS in your file systems table as a kernel driver, add the
 119 following to ``/etc/fstab``::
 120
 121   {name}@.{fs_name}=/ {mount}/{mountpoint} ceph [mon_addr={ipaddress},secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}]  {fs_freq}  {fs_passno}
 122
 123 For example::
 124
 125   cephuser@.cephfs=/     /mnt/ceph    ceph    mon_addr=192.168.0.1:6789,noatime,_netdev    0       0
 126
 127 If the ``secret`` or ``secretfile`` options are not specified then the mount helper
 128 will attempt to find a secret for the given ``name`` in one of the configured keyrings.
 129
 130 See `User Management`_ for details on CephX user management and mount.ceph_
 131 manual for more options it can take. For troubleshooting, see
 132 :ref:`kernel_mount_debugging`.
 133
 134 .. _fstab: ../fstab/#kernel-driver
 135 .. _Mount CephFS\: Prerequisites: ../mount-prerequisites
 136 .. _mount.ceph: ../../man/8/mount.ceph/
 137 .. _User Management: ../../rados/operations/user-management/