1 ========================
2 Mount CephFS using FUSE
3 ========================
5 `ceph-fuse`_ is an alternate way of mounting CephFS, although it mounts it
6 in userspace. Therefore, performance of FUSE can be relatively lower but FUSE
7 clients can be more manageable, especially while upgrading CephFS.
12 Go through the prerequisites required by both, kernel as well as FUSE mounts,
13 in `Mount CephFS: Prerequisites`_ page.
15 .. note:: Mounting CephFS using FUSE requires superuser privileges to trim dentries
16 by issuing a remount of itself.
20 In general, the command to mount CephFS via FUSE looks like this::
22 ceph-fuse {mountpoint} {options}
26 To FUSE-mount the Ceph file system, use the ``ceph-fuse`` command::
29 ceph-fuse --id foo /mnt/mycephfs
31 Option ``-id`` passes the name of the CephX user whose keyring we intend to
32 use for mounting CephFS. In the above command, it's ``foo``. You can also use
33 ``-n`` instead, although ``--id`` is evidently easier::
35 ceph-fuse -n client.foo /mnt/mycephfs
37 In case the keyring is not present in standard locations, you may pass it
40 ceph-fuse --id foo -k /path/to/keyring /mnt/mycephfs
42 You may pass the MON's socket too, although this is not mandatory::
44 ceph-fuse --id foo -m 192.168.0.1:6789 /mnt/mycephfs
46 You can also mount a specific directory within CephFS instead of mounting
47 root of CephFS on your local FS::
49 ceph-fuse --id foo -r /path/to/dir /mnt/mycephfs
51 If you have more than one FS on your Ceph cluster, use the option
52 ``--client_fs`` to mount the non-default FS::
54 ceph-fuse --id foo --client_fs mycephfs2 /mnt/mycephfs2
56 You may also add a ``client_fs`` setting to your ``ceph.conf``
61 Use ``umount`` to unmount CephFS like any other FS::
65 .. tip:: Ensure that you are not within the file system directories before
66 executing this command.
71 To mount CephFS as a file system in user space, add the following to ``/etc/fstab``::
73 #DEVICE PATH TYPE OPTIONS
74 none /mnt/mycephfs fuse.ceph ceph.id={user-ID}[,ceph.conf={path/to/conf.conf}],_netdev,defaults 0 0
78 none /mnt/mycephfs fuse.ceph ceph.id=myuser,_netdev,defaults 0 0
79 none /mnt/mycephfs fuse.ceph ceph.id=myuser,ceph.conf=/etc/ceph/foo.conf,_netdev,defaults 0 0
81 Ensure you use the ID (e.g., ``myuser``, not ``client.myuser``). You can pass
82 any valid ``ceph-fuse`` option to the command line this way.
84 To mount a subdirectory of the CephFS, add the following to ``/etc/fstab``::
86 none /mnt/mycephfs fuse.ceph ceph.id=myuser,ceph.client_mountpoint=/path/to/dir,_netdev,defaults 0 0
88 ``ceph-fuse@.service`` and ``ceph-fuse.target`` systemd units are available.
89 As usual, these unit files declare the default dependencies and recommended
90 execution context for ``ceph-fuse``. After making the fstab entry shown above,
91 run following commands::
93 systemctl start ceph-fuse@/mnt/mycephfs.service
94 systemctl enable ceph-fuse.target
95 systemctl enable ceph-fuse@-mnt-mycephfs.service
97 See :ref:`User Management <user-management>` for details on CephX user management and `ceph-fuse`_
98 manual for more options it can take. For troubleshooting, see
99 :ref:`ceph_fuse_debugging`.
101 .. _ceph-fuse: ../../man/8/ceph-fuse/#options
102 .. _Mount CephFS\: Prerequisites: ../mount-prerequisites