diff options
Diffstat (limited to 'doc/cephfs/mount-using-kernel-driver.rst')
| -rw-r--r-- | doc/cephfs/mount-using-kernel-driver.rst | 156 |
1 files changed, 93 insertions, 63 deletions
diff --git a/doc/cephfs/mount-using-kernel-driver.rst b/doc/cephfs/mount-using-kernel-driver.rst index 22ede055d0b..bf229099a19 100644 --- a/doc/cephfs/mount-using-kernel-driver.rst +++ b/doc/cephfs/mount-using-kernel-driver.rst @@ -4,32 +4,32 @@ Mount CephFS using Kernel Driver ================================= -The CephFS kernel driver is part of the Linux kernel. It allows mounting -CephFS as a regular file system with native kernel performance. It is the -client of choice for most use-cases. +The CephFS kernel driver is part of the Linux kernel. It makes possible the +mounting of CephFS as a regular file system with native kernel performance. It +is the client of choice for most use-cases. -.. note:: CephFS mount device string now uses a new (v2) syntax. The mount - helper (and the kernel) is backward compatible with the old syntax. - This means that the old syntax can still be used for mounting with - newer mount helpers and kernel. However, it is recommended to use - the new syntax whenever possible. +.. note:: The CephFS mount device string now uses a new syntax ("v2"). The + mount helper is backward compatible with the old syntax. The kernel is + backward-compatible with the old syntax. This means that the old syntax can + still be used for mounting with newer mount helpers and with the kernel. Prerequisites ============= Complete General Prerequisites ------------------------------ -Go through the prerequisites required by both, kernel as well as FUSE mounts, -in `Mount CephFS: Prerequisites`_ page. +Go through the prerequisites required by both kernel and FUSE mounts, +as described on the `Mount CephFS: Prerequisites`_ page. Is mount helper present? ------------------------ -``mount.ceph`` helper is installed by Ceph packages. The helper passes the +The ``mount.ceph`` helper is installed by Ceph packages. The helper passes the monitor address(es) and CephX user keyrings, saving the Ceph admin the effort of passing these details explicitly while mounting CephFS. If the helper is not present on the client machine, CephFS can still be mounted using the kernel -driver, but only by passing these details explicitly to the ``mount`` command. -To check whether ``mount.ceph`` is present on your system, run the following command: +driver but only by passing these details explicitly to the ``mount`` command. +To check whether ``mount.ceph`` is present on your system, run the following +command: .. prompt:: bash # @@ -38,70 +38,88 @@ To check whether ``mount.ceph`` is present on your system, run the following com Which Kernel Version? --------------------- -Because the kernel client is distributed as part of the linux kernel (not -as part of packaged ceph releases), you will need to consider which kernel +Because the kernel client is distributed as part of the Linux kernel (and not +as part of the packaged Ceph releases), you will need to consider which kernel version to use on your client nodes. Older kernels are known to include buggy -ceph clients, and may not support features that more recent Ceph clusters +Ceph clients and may not support features that more recent Ceph clusters support. -Remember that the "latest" kernel in a stable linux distribution is likely -to be years behind the latest upstream linux kernel where Ceph development +Remember that the "latest" kernel in a stable Linux distribution is likely +to be years behind the latest upstream Linux kernel where Ceph development takes place (including bug fixes). As a rough guide, as of Ceph 10.x (Jewel), you should be using a least a 4.x kernel. If you absolutely have to use an older kernel, you should use the fuse client instead of the kernel client. -This advice does not apply if you are using a linux distribution that -includes CephFS support, as in this case the distributor will be responsible -for backporting fixes to their stable kernel: check with your vendor. +This advice does not apply if you are using a Linux distribution that includes +CephFS support. In that case, the distributor is responsible for backporting +fixes to their stable kernel. Check with your vendor. Synopsis ======== -In general, the command to mount CephFS via kernel driver looks like this:: +This is the general form of the command for mounting CephFS via the kernel driver: - mount -t ceph {device-string}={path-to-mounted} {mount-point} -o {key-value-args} {other-args} +.. prompt:: bash # + + mount -t ceph {device-string}={path-to-mounted} {mount-point} -o {key-value-args} {other-args} Mounting CephFS =============== -On Ceph clusters, CephX is enabled by default. Use ``mount`` command to -mount CephFS with the kernel driver:: +CephX authentication is enabled by default in Ceph clusters. Use the ``mount`` +command to use the kernel driver to mount CephFS: + +.. prompt:: bash # - mkdir /mnt/mycephfs - mount -t ceph <name>@<fsid>.<fs_name>=/ /mnt/mycephfs + mkdir /mnt/mycephfs + mount -t ceph <name>@<fsid>.<fs_name>=/ /mnt/mycephfs -``name`` is the username of the CephX user we are using to mount CephFS. -``fsid`` is the FSID of the ceph cluster which can be found using -``ceph fsid`` command. ``fs_name`` is the file system to mount. The kernel -driver requires MON's socket and the secret key for the CephX user, e.g.:: +#. ``name`` is the username of the CephX user we are using to mount CephFS. +#. ``fsid`` is the FSID of the Ceph cluster, which can be found using the + ``ceph fsid`` command. ``fs_name`` is the file system to mount. The kernel + driver requires a ceph Monitor's address and the secret key of the CephX + user. For example: - mount -t ceph cephuser@b3acfc0d-575f-41d3-9c91-0e7ed3dbb3fa.cephfs=/ -o mon_addr=192.168.0.1:6789,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== + .. prompt:: bash # -When using the mount helper, monitor hosts and FSID are optional. ``mount.ceph`` -helper figures out these details automatically by finding and reading ceph conf -file, .e.g:: + mount -t ceph cephuser@b3acfc0d-575f-41d3-9c91-0e7ed3dbb3fa.cephfs=/ -o mon_addr=192.168.0.1:6789,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== - mount -t ceph cephuser@.cephfs=/ -o secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== +When using the mount helper, monitor hosts and FSID are optional. The +``mount.ceph`` helper discovers these details by finding and reading the ceph +conf file. For example: -.. note:: Note that the dot (``.``) still needs to be a part of the device string. +.. prompt:: bash # -A potential problem with the above command 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 cephuser@.cephfs=/ -o secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== - mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs -o secretfile=/etc/ceph/cephuser.secret +.. note:: Note that the dot (``.`` in the string ``cephuser@.cephfs``) must be + a part of the device string. -Ensure the permissions on the secret key file are appropriate (preferably, ``600``). +A weakness of this method is that it will leave the secret key in your shell's +command history. To avoid this, copy the secret key inside a file and pass the +file by using the option ``secretfile`` instead of ``secret``. For example: -Multiple monitor hosts can be passed by separating each address with a ``/``:: +.. prompt:: bash # - 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 + mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs -o secretfile=/etc/ceph/cephuser.secret -In case CephX is disabled, you can omit any credential related options:: +Ensure that the permissions on the secret key file are appropriate (preferably, +``600``). - mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs +Multiple monitor hosts can be passed by separating addresses with a ``/``: -.. note:: The ceph user name still needs to be passed as part of the device string. +.. prompt:: bash # + + 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 + +If CephX is disabled, omit any credential-related options. For example: + +.. prompt:: bash # + + mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs + +.. note:: The Ceph user name must be passed as part of the device string. To mount a subtree of the CephFS root, append the path to the device string:: @@ -111,29 +129,40 @@ Backward Compatibility ====================== The old syntax is supported for backward compatibility. -To mount CephFS with the kernel driver:: +To mount CephFS with the kernel driver, run the following commands: + +.. prompt:: bash # + + mkdir /mnt/mycephfs + mount -t ceph :/ /mnt/mycephfs -o name=admin - mkdir /mnt/mycephfs - mount -t ceph :/ /mnt/mycephfs -o name=admin +The key-value argument right after the option ``-o`` is the CephX credential. +``name`` is the username of the CephX user that is mounting CephFS. -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. +To mount a non-default FS (in this example, ``cephfs2``), run commands of the following form. These commands are to be used in cases in which the cluster +has multiple file systems: -To mount a non-default FS ``cephfs2``, in case the cluster has multiple FSs:: +.. prompt:: bash # + + mount -t ceph :/ /mnt/mycephfs -o name=admin,fs=cephfs2 - mount -t ceph :/ /mnt/mycephfs -o name=admin,fs=cephfs2 +or - or +.. prompt:: bash # - mount -t ceph :/ /mnt/mycephfs -o name=admin,mds_namespace=cephfs2 + mount -t ceph :/ /mnt/mycephfs -o name=admin,mds_namespace=cephfs2 -.. note:: The option ``mds_namespace`` is deprecated. Use ``fs=`` instead when using the old syntax for mounting. +.. note:: The option ``mds_namespace`` is deprecated. Use ``fs=`` instead when + using the old syntax for mounting. Unmounting CephFS ================= -To unmount the Ceph file system, use the ``umount`` command as usual:: +To unmount the Ceph file system, use the ``umount`` command, as in this +example: + +.. prompt:: bash # - umount /mnt/mycephfs + umount /mnt/mycephfs .. tip:: Ensure that you are not within the file system directories before executing this command. @@ -150,11 +179,12 @@ For example:: cephuser@.cephfs=/ /mnt/ceph ceph mon_addr=192.168.0.1:6789,noatime,_netdev 0 0 -If the ``secret`` or ``secretfile`` options are not specified then the mount helper -will attempt to find a secret for the given ``name`` in one of the configured keyrings. +If the ``secret`` or ``secretfile`` options are not specified, the mount +helper will attempt to find a secret for the given ``name`` in one of the +configured keyrings. -See `User Management`_ for details on CephX user management and mount.ceph_ -manual for more options it can take. For troubleshooting, see +See `User Management`_ for details on CephX user management and the mount.ceph_ +manual for a list of the options it recognizes. For troubleshooting, see :ref:`kernel_mount_debugging`. .. _fstab: ../fstab/#kernel-driver |