-=======================
-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
projects / ceph.git / commitdiff