From cd34b96e4d04f563e0c6e732fd9f954f8b37fa78 Mon Sep 17 00:00:00 2001 From: Rishabh Dave Date: Mon, 7 Oct 2019 12:57:29 +0530 Subject: [PATCH] doc: update and improve "mount using FUSE" doc Recommend keyring permission to be 600 instead of 644, show examples for `-k`, `-r`, `-m` and `--client_mds_namespace` options, move references to the bottom of the page, show how to unmount FUSE-mounted CephFS, copy the tip about unmounting from "mount using kernel" page to "mount using FUSE" page, correct commands for automating FUSE mounts, add sub-headings to the document and add how ceph-fuse command looks in general. Fixes: https://tracker.ceph.com/issues/42205 Signed-off-by: Rishabh Dave --- doc/cephfs/fuse.rst | 123 +++++++++++++++++++++++++++++++------------ doc/cephfs/index.rst | 2 +- 2 files changed, 89 insertions(+), 36 deletions(-) diff --git a/doc/cephfs/fuse.rst b/doc/cephfs/fuse.rst index 20fb614b30217..64c5b6a382ab0 100644 --- a/doc/cephfs/fuse.rst +++ b/doc/cephfs/fuse.rst @@ -1,54 +1,107 @@ -======================= -Mount CephFS using FUSE -======================= +======================== + Mount CephFS using FUSE +======================== -Before mounting Ceph via "Filesystem in USErspace" (FUSE), ensure that the client -host has a copy of the Ceph configuration file and a keyring with CAPS for the -Ceph metadata server. +Prerequisite +------------ +Before mounting CephFS, ensure that the client host (where CephFS has to be +mounted and used) has a copy of the Ceph configuration file (i.e. +``ceph.conf``) and a keyring of the CephX user that has CAPS for the Ceph MDS. +Both of these files must be present on the host where the Ceph MON resides. -#. From your client host, copy the Ceph configuration file from the monitor host - to the ``/etc/ceph`` directory. :: +#. Generate a minimal conf for the client host. The conf file should be + placed at ``/etc/ceph``:: - sudo mkdir -p /etc/ceph - sudo scp {user}@{server-machine}:/etc/ceph/ceph.conf /etc/ceph/ceph.conf + # on client host + mkdir /etc/ceph + ssh {user}@{mon-host} "sudo ceph config generate-minimal-conf" | sudo tee /etc/ceph/ceph.conf -#. From your client host, copy the Ceph keyring from the monitor host to - to the ``/etc/ceph`` directory. :: + Alternatively, you may copy the conf file. But the method which generates + the minimal config is usually sufficient. For more information, see + `boostrap options in ceph-conf page`_. - sudo scp {user}@{server-machine}:/etc/ceph/ceph.keyring /etc/ceph/ceph.keyring +#. Ensure that the conf has appropriate permissions:: -#. Ensure that the Ceph configuration file and the keyring have appropriate - permissions set on your client machine (e.g., ``chmod 644``). + chmod 644 /etc/ceph/ceph.conf -For additional details on ``cephx`` configuration, see -`CEPHX Config Reference`_. +#. Create the CephX user and get its secret key:: -To mount the Ceph file system as a FUSE, you may use the ``ceph-fuse`` command. -For example:: + ssh {user}@{mon-host} "sudo ceph fs authorize cephfs client.foo / rw" | sudo tee /etc/ceph/ceph.client.foo.keyring - sudo mkdir /home/username/cephfs - sudo ceph-fuse -m 192.168.0.1:6789 /home/username/cephfs + In above command, replace ``cephfs`` with the name of your CephFS, ``foo`` + by the name you want for your CephX user and ``/`` by the path within your + CephFS for which you want to allow access to the client host and ``rw`` + stands for both read and write permissions. Alternatively, you may copy the + Ceph keyring from the MON host to client host at ``/etc/ceph`` but creating + a keyring specific to the client host is better. While creating a CephX + keyring/client, using same client name across multiple machines is perfectly + fine. -If you have more than one file system, specify which one to mount using -the ``--client_mds_namespace`` command line argument, or add a -``client_mds_namespace`` setting to your ``ceph.conf``. +.. note:: If you get 2 prompts for password while running above any of 2 above + command, run ``sudo ls`` (or any other trivial command with sudo) + immediately before these commands. -See `ceph-fuse`_ for additional details. +#. Ensure that the keyring has appropriate permissions:: -To automate mounting ceph-fuse, you may add an entry to the system fstab_. -Additionally, ``ceph-fuse@.service`` and ``ceph-fuse.target`` systemd units are -available. As usual, these unit files declare the default dependencies and -recommended execution context for ``ceph-fuse``. An example ceph-fuse mount on -``/mnt`` would be:: + chmod 600 /etc/ceph/ceph.client.foo.keyring - sudo systemctl start ceph-fuse@/mnt.service +Synopsis +-------- +In general, the command to mount CephFS via FUSE looks like this:: -A persistent mount point can be setup via:: + ceph-fuse {mountpoint} {options} - sudo systemctl enable ceph-fuse@/mnt.service +Mounting CephFS +--------------- +To FUSE-mount the Ceph file system, use the ``ceph-fuse`` command:: -For troubleshooting, see :ref:`ceph_fuse_debugging`. + mkdir /mnt/mycephfs + ceph-fuse -id foo /mnt/mycephfs + +Option ``-id`` passes the name of the CephX user whose keyring we intend to +use for mounting CephFS. In the above command, it's ``foo``. You can also use +``-n`` instead, although ``--id`` is evidently easier:: + + ceph-fuse -n client.foo /mnt/mycephfs + +In case the keyring is not present in standard locations, you may pass it +too:: + + ceph-fuse --id foo -k /path/to/keyring /mnt/mycephfs + +You may pass the MON's socket too, although this is not mandatory:: + + ceph-fuse --id foo -m 192.168.0.1:6789 /mnt/mycephfs + +You can also mount a specific directory within CephFS instead of mounting +root of CephFS on your local FS:: + + ceph-fuse --id foo -r /path/to/dir /mnt/mycephfs + +If you have more than one FS on your Ceph cluster, use the option +``--client_mds_namespace`` to mount the non-default FS:: + + ceph-fuse --id foo --client_mds_namespace mycephfs2 /mnt/mycephfs2 + +You may also add a ``client_mds_namespace`` setting to your ``ceph.conf`` + +Unmounting CephFS +----------------- + +Use ``umount`` to unmount CephFS like any other FS:: + + umount /mnt/mycephfs + +.. tip:: Ensure that you are not within the file system directories before + executing this command. + +See fstab_ to find out how to make FUSE-mounted CephFS persist across reboots, +`User Management`_ for details on CephX user management and mount.ceph_ manual +for more options it can take. For troubleshooting, see +:ref:`kernel_mount_debugging`. .. _ceph-fuse: ../../man/8/ceph-fuse/ .. _fstab: ../fstab/#fuse -.. _CEPHX Config Reference: ../../rados/configuration/auth-config-ref +.. _User Management: ../../rados/operations/user-management/ +.. _mount.ceph: ../../man/8/mount.ceph/ +.. _boostrap options in ceph-conf page: ../../rados/configuration/ceph-conf/#bootstrap-options diff --git a/doc/cephfs/index.rst b/doc/cephfs/index.rst index d40cb08cde0e2..7bae92378e837 100644 --- a/doc/cephfs/index.rst +++ b/doc/cephfs/index.rst @@ -92,7 +92,7 @@ Mounting CephFS Create a CephFS file system Mount CephFS with the Kernel Driver - Mount CephFS as FUSE + Mount CephFS using FUSE Mount CephFS in fstab Use the CephFS Shell Supported Features of Kernel Driver -- 2.39.5