From 740aeb96327f140e7dbc7f0f5e2c94d43be84858 Mon Sep 17 00:00:00 2001 From: Jeff Layton Date: Fri, 27 Sep 2019 11:01:45 -0400 Subject: [PATCH] doc: update documents on using kcephfs Overhaul the fstab.rst and kernel.rst files with more relevant examples now that the mount helper does autodiscovery. Add a preamble to kernel-features.rst and add a warning about the deprecation of inline data. Fixes: https://tracker.ceph.com/issues/42025 Signed-off-by: Jeff Layton --- doc/cephfs/fstab.rst | 4 +-- doc/cephfs/kernel-features.rst | 17 ++++++++---- doc/cephfs/kernel.rst | 48 ++++++++++++++++++++++------------ 3 files changed, 46 insertions(+), 23 deletions(-) diff --git a/doc/cephfs/fstab.rst b/doc/cephfs/fstab.rst index 6274d0a9695..7e1a7674fce 100644 --- a/doc/cephfs/fstab.rst +++ b/doc/cephfs/fstab.rst @@ -11,11 +11,11 @@ Kernel Driver To mount CephFS in your file systems table as a kernel driver, add the following to ``/etc/fstab``:: - {ipaddress}:{port}:/ {mount}/{mountpoint} {file-system-name} [name=username,secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}] + [{ipaddress}:{port}]:/ {mount}/{mountpoint} ceph [name=username,secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}] For example:: - 10.10.10.10:6789:/ /mnt/ceph ceph name=admin,noatime,_netdev 0 2 + :/ /mnt/ceph ceph name=admin,noatime,_netdev 0 2 The default for the ``name=`` parameter is ``guest``. If the ``secret`` or ``secretfile`` options are not specified then the mount helper will attempt to diff --git a/doc/cephfs/kernel-features.rst b/doc/cephfs/kernel-features.rst index d128b51a759..c025c7a52cb 100644 --- a/doc/cephfs/kernel-features.rst +++ b/doc/cephfs/kernel-features.rst @@ -1,13 +1,20 @@ -Supported Features of Kernel Driver +Supported Features of the Kernel Driver ======================================== +The kernel driver is developed separately from the core ceph code, and as +such it sometimes differs from the FUSE driver in feature implementation. +The following details the implementation status of various CephFS features +in the kernel driver. Inline data ----------- -Inline data was introduced by the Firefly release. Linux kernel clients >= 3.19 -can read inline data, can convert existing inline data to RADOS objects when -file data is modified. At present, Linux kernel clients do not store file data -as inline data. +Inline data was introduced by the Firefly release. This feature is being +deprecated in mainline CephFS, and may be removed from a future kernel +release. + +Linux kernel clients >= 3.19 can read inline data and convert existing +inline data to RADOS objects when file data is modified. At present, +Linux kernel clients do not store file data as inline data. See `Experimental Features`_ for more information. diff --git a/doc/cephfs/kernel.rst b/doc/cephfs/kernel.rst index 16702cbcab2..472f79486ba 100644 --- a/doc/cephfs/kernel.rst +++ b/doc/cephfs/kernel.rst @@ -2,36 +2,52 @@ Mount CephFS with the Kernel Driver ==================================== -To mount CephFS with the Kernel Driver you may use the ``mount`` command if you know the -monitor host IP address(es), or use the ``mount.ceph`` utility to resolve the -monitor host name(s) into IP address(es) for you. For example:: +It is recommended to install the ``/sbin/mount.ceph`` kernel mount +helper if working with the kernel cephfs driver. To mount CephFS with +the kernel driver you may use the ``mount`` command:: - sudo mkdir /mnt/mycephfs - sudo mount -t ceph 192.168.0.1:6789:/ /mnt/mycephfs + # mkdir /mnt/mycephfs + # mount -t ceph :/ /mnt/mycephfs -To mount the Ceph file system with ``cephx`` authentication enabled, the kernel -must authenticate with the cluster. The default ``name=`` option is ``guest``. -The mount.ceph helper will automatically attempt to find a secret key in the -keyring. +Omitting the monitor addresses will cue ``mount.ceph`` to look them up +in the local configuration file. If you know at least one of the monitor +addresses and ports you can specify them directly in a comma-separated +list, and the kernel will avoid looking them up:: -The secret can also be specified manually with the ``secret=`` option. :: + # mount -t ceph 192.168.0.1:6789,192.168.0.2:6789:/ /mnt/mycephfs - sudo mount -t ceph 192.168.0.1:6789:/ /mnt/mycephfs -o name=admin,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== +To mount a subtree of the cephfs root, append the path to the device +string :: -The foregoing usage leaves the secret in the Bash history. A more secure -approach reads the secret from a file. For example:: + # mount -t ceph :/subvolume/dir1/dir2 /mnt/mycephfs -o name=fs - sudo mount -t ceph 192.168.0.1:6789:/ /mnt/mycephfs -o name=admin,secretfile=/etc/ceph/admin.secret +To mount the Ceph file system with ``cephx`` authentication enabled, the +kernel must authenticate with the cluster. The default ``name=`` option +is ``guest``. The mount.ceph helper will automatically attempt to find +a secret key in a cephx keyring if it's not specified. For example, to +mount the filesystem as the cephx user ``fs``:: + + # mount -t ceph :/ /mnt/mycephfs -o name=fs + +The secret can also be specified manually with the ``secret=`` option.:: + + # mount -t ceph :/ /mnt/mycephfs -o name=fs,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== + +For legacy usage, mount.ceph can be told to read a lone secret from a +file. For example:: + + # mount -t ceph :/ /mnt/mycephfs -o name=fs,secretfile=/etc/ceph/admin.secret See `User Management`_ for details on cephx. If you have more than one file system, specify which one to mount using +the ``mds_namespace`` option, e.g.:: -the ``mds_namespace`` option, e.g. ``-o mds_namespace=myfs``. + # mount -t ceph :/ -o name=fs,mds_namespace=myfs To unmount the Ceph file system, you may use the ``umount`` command. For example:: - sudo umount /mnt/mycephfs + # umount /mnt/mycephfs .. tip:: Ensure that you are not within the file system directories before executing this command. -- 2.39.5