From 52ad9fbcfea8f1c08a6034c0a6850e54ab38e45e Mon Sep 17 00:00:00 2001 From: Venky Shankar Date: Fri, 14 May 2021 00:38:19 -0400 Subject: [PATCH] doc, man: document new device syntax for kclient mount Fxies: http://tracker.ceph.com/issues/47277 Signed-off-by: Venky Shankar --- doc/cephfs/mount-using-kernel-driver.rst | 70 ++++++++------- doc/man/8/mount.ceph.rst | 107 ++++++++++------------- 2 files changed, 86 insertions(+), 91 deletions(-) diff --git a/doc/cephfs/mount-using-kernel-driver.rst b/doc/cephfs/mount-using-kernel-driver.rst index 5bd98dd51a7cb..2d41e38e62d5f 100644 --- a/doc/cephfs/mount-using-kernel-driver.rst +++ b/doc/cephfs/mount-using-kernel-driver.rst @@ -6,6 +6,12 @@ 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. +.. 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. + Prerequisites ============= @@ -50,51 +56,52 @@ Synopsis ======== In general, the command to mount CephFS via kernel driver looks like this:: - mount -t ceph {device-string}:{path-to-mounted} {mount-point} -o {key-value-args} {other-args} + 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:: - mkdir /mnt/mycephfs - mount -t ceph :/ /mnt/mycephfs -o name=foo + mkdir /mnt/mycephfs + mount -t ceph @.=/ /mnt/mycephfs -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. The -default value for ``name`` is ``guest``. +``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.:: -The kernel driver also requires MON's socket and the secret key for the CephX -user. In case of the above command, ``mount.ceph`` helper figures out these -details automatically by finding and reading Ceph conf file and keyring. In -case you don't have these files on the host where you're running mount -command, you can pass these details yourself too:: + mount -t ceph cephuser@b3acfc0d-575f-41d3-9c91-0e7ed3dbb3fa.cephfs=/ -o mon_addr=192.168.0.1:6789,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== - mount -t ceph 192.168.0.1:6789,192.168.0.2:6789:/ /mnt/mycephfs -o name=foo,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== +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:: -Passing a single MON socket in above command works too. A potential problem -with the command above 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 :/ /mnt/mycephfs -o name=foo,secretfile=/etc/ceph/foo.secret +.. note:: Note that the dot (``.``) still needs to be a part of the device string. -Ensure the permissions on the secret key file are appropriate (preferably, -``600``). +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``:: -In case CephX is disabled, you can omit ``-o`` and the list of key-value -arguments that follow it:: + mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs -o secretfile=/etc/ceph/cephuser.secret - mount -t ceph :/ /mnt/mycephfs +Ensure the permissions on the secret key file are appropriate (preferably, ``600``). -To mount a subtree of the CephFS root, append the path to the device string:: +Multiple monitor hosts can be passed by separating each address with a ``/``:: + + 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 :/subvolume/dir1/dir2 /mnt/mycephfs -o name=fs +In case CephX is disabled, you can omit any credential related options:: -If you have more than one file system on your Ceph cluster, you can mount the -non-default FS as follows:: + mount -t ceph cephuser@.cephfs=/ /mnt/mycephfs + +.. note:: The ceph user name still needs to be passed as part of the device string. + +To mount a subtree of the CephFS root, append the path to the device string:: - mount -t ceph :/ /mnt/mycephfs2 -o name=fs,fs=mycephfs2 + mount -t ceph cephuser@.cephfs=/subvolume/dir1/dir2 /mnt/mycephfs -o secretfile=/etc/ceph/cephuser.secret Unmounting CephFS ================= @@ -111,15 +118,14 @@ Persistent Mounts To mount CephFS in your file systems table as a kernel driver, add the following to ``/etc/fstab``:: - [{ipaddress}:{port}]:/ {mount}/{mountpoint} ceph [name=username,secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}] + {name}@.{fs_name}=/ {mount}/{mountpoint} ceph [mon_addr={ipaddress},secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}] {fs_freq} {fs_passno} For example:: - :/ /mnt/ceph ceph name=admin,noatime,_netdev 0 2 + cephuser@.cephfs=/ /mnt/ceph ceph mon_addr=192.168.0.1:6789,noatime,_netdev 0 0 -The default for the ``name=`` parameter is ``guest``. 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 then 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 diff --git a/doc/man/8/mount.ceph.rst b/doc/man/8/mount.ceph.rst index 14af04034202c..82294d017c28d 100644 --- a/doc/man/8/mount.ceph.rst +++ b/doc/man/8/mount.ceph.rst @@ -9,8 +9,7 @@ Synopsis ======== -| **mount.ceph** [*mon1_socket*\ ,\ *mon2_socket*\ ,...]:/[*subdir*] *dir* [ - -o *options* ] +| **mount.ceph** *name*@*fsid*.*fs_name*=/[*subdir*] *dir* [-o *options* ] Description @@ -19,31 +18,39 @@ Description **mount.ceph** is a helper for mounting the Ceph file system on a Linux host. It serves to resolve monitor hostname(s) into IP addresses and read authentication keys from disk; the Linux kernel client component does most of -the real work. In fact, it is possible to mount a non-authenticated Ceph file -system without mount.ceph by specifying monitor address(es) by IP:: - - mount -t ceph 1.2.3.4:/ /mnt/mycephfs - -The first argument is the device part of the mount command. It includes host's -socket and path within CephFS that will be mounted at the mount point. The -socket, obviously, takes the form ip_address[:port]. If the port is not -specified, the Ceph default of 6789 is assumed. Multiple monitor addresses can -be passed by separating them by commas. Only one monitor is needed to mount -successfully; the client will learn about all monitors from any responsive -monitor. However, it is a good idea to specify more than one in case the one -happens to be down at the time of mount. - -If the host portion of the device is left blank, then **mount.ceph** will -attempt to determine monitor addresses using local configuration files -and/or DNS SRV records. In similar way, if authentication is enabled on Ceph -cluster (which is done using CephX) and options ``secret`` and ``secretfile`` -are not specified in the command, the mount helper will spawn a child process -that will use the standard Ceph library routines to find a keyring and fetch -the secret from it. +the real work. To mount a Ceph file system use:: + + mount.ceph name@07fe3187-00d9-42a3-814b-72a4d5e7d5be.fs_name=/ /mnt/mycephfs -o mon_addr=1.2.3.4 + +Mount helper can fill in the cluster FSID by reading the ceph configuration file. +Its recommeded to call the mount helper via mount(8) as per:: + + mount -t ceph name@.fs_name=/ /mnt/mycephfs -o mon_addr=1.2.3.4 + +Note that the dot ``.`` still needs to be a part of the device string in this case. + +The first argument is the device part of the mount command. It includes the +RADOS user for authentication, the file system name and a path within CephFS +that will be mounted at the mount point. + +Monitor addresses can be passed using ``mon_addr`` mount option. Multiple monitor +addresses can be passed by separating addresses with a slash (`/`). Only one +monitor is needed to mount successfully; the client will learn about all monitors +from any responsive monitor. However, it is a good idea to specify more than one +in case the one happens to be down at the time of mount. Monitor addresses takes +the form ip_address[:port]. If the port is not specified, the Ceph default of 6789 +is assumed. + +If monitor addresses are not specified, then **mount.ceph** will attempt to determine +monitor addresses using local configuration files and/or DNS SRV records. In similar +way, if authentication is enabled on Ceph cluster (which is done using CephX) and +options ``secret`` and ``secretfile`` are not specified in the command, the mount +helper will spawn a child process that will use the standard Ceph library routines +to find a keyring and fetch the secret from it (including the monitor address and +FSID if those not specified). A sub-directory of the file system can be mounted by specifying the (absolute) -path to the sub-directory right after ":" after the socket in the device part -of the mount command. +path to the sub-directory right after "=" in the device part of the mount command. Mount helper application conventions dictate that the first two options are device to be mounted and the mountpoint for that device. Options must be @@ -61,13 +68,6 @@ Basic for autodiscovery of monitor addresses and auth secrets. The default is to use the standard search path for ceph.conf files. -:command: `fs=` - Specify the non-default file system to be mounted. Not passing this - option mounts the default file system. - -:command: `mds_namespace=` - A synonym of "fs=" and its use is deprecated. - :command:`mount_timeout` int (seconds), Default: 60 @@ -85,8 +85,11 @@ Basic - ``prefer-secure``: secure mode, if denied agree to crc mode -:command:`name` - RADOS user to authenticate as when using CephX. Default: guest +:command:`mon_addr` + Monitor address of the cluster in the form of ip_address[:port] + +:command:`fsid` + Cluster FSID. This can be found using `ceph fsid` command. :command:`secret` secret key for use with CephX. This option is insecure because it exposes @@ -192,50 +195,36 @@ Examples Mount the full file system:: - mount.ceph :/ /mnt/mycephfs - -Assuming mount.ceph is installed properly, it should be automatically invoked -by mount(8):: - - mount -t ceph :/ /mnt/mycephfs + mount -t ceph fs_user@.mycephfs2=/ /mnt/mycephfs Mount only part of the namespace/file system:: - mount.ceph :/some/directory/in/cephfs /mnt/mycephfs - -Mount non-default FS, in case cluster has multiple FSs:: - - mount -t ceph :/ /mnt/mycephfs2 -o fs=mycephfs2 - - or - - mount -t ceph :/ /mnt/mycephfs2 -o mds_namespace=mycephfs2 # This option name is deprecated. + mount.ceph fs_user@.mycephfs2=/some/directory/in/cephfs /mnt/mycephfs Pass the monitor host's IP address, optionally:: - mount.ceph 192.168.0.1:/ /mnt/mycephfs + mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1 Pass the port along with IP address if it's running on a non-standard port:: - mount.ceph 192.168.0.1:7000:/ /mnt/mycephfs - -If there are multiple monitors, passes addresses separated by a comma:: + mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1:7000 - mount.ceph 192.168.0.1,192.168.0.2,192.168.0.3:/ /mnt/mycephfs +If there are multiple monitors, pass each address separated by a `/`:: -If authentication is enabled on Ceph cluster:: - - mount.ceph :/ /mnt/mycephfs -o name=fs_username + mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o mon_addr=192.168.0.1/192.168.0.2/192.168.0.3 Pass secret key for CephX user optionally:: - mount.ceph :/ /mnt/mycephfs -o name=fs_username,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== + mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== Pass file containing secret key to avoid leaving secret key in shell's command history:: - mount.ceph :/ /mnt/mycephfs -o name=fs_username,secretfile=/etc/ceph/fs_username.secret + mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs -o secretfile=/etc/ceph/fs_username.secret + +If authentication is disabled on Ceph cluster, omit the credential related option:: + mount.ceph fs_user@.mycephfs2=/ /mnt/mycephfs Availability ============ -- 2.39.5