Notice
This document is for a development version of Ceph.
Mount CephFS using FUSE
ceph-fuse can be used as an alternative to the CephFS kernel driver to mount CephFS file systems. ceph-fuse mounts are made in userspace. This means that ceph-fuse mounts are less performant than kernel driver mounts, but they are easier to manage and easier to upgrade.
Prerequisites
Ensure that you have all the prerequisites required by both kernel and FUSE mounts, as listed on the Mount CephFS: Prerequisites page.
Note
Mounting CephFS using FUSE requires superuser privileges (sudo/root).
The libfuse interface does not provide a mechanism to trim cache entries in
the kernel so a remount (mount(2)
) system call is required to force the
kernel to drop the cached metadata. ceph-fuse
issues these remount
system calls periodically in response to cache pressure in the MDS or due to
metadata cache revocations.
Synopsis
This is the general form of the command for mounting CephFS via FUSE:
ceph-fuse {mount point} {options}
Mounting CephFS
To FUSE-mount the Ceph file system, use the ceph-fuse
command:
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_fs
to mount the non-default FS:
ceph-fuse --id foo --client_fs mycephfs2 /mnt/mycephfs2
You may also add a client_fs
setting to your ceph.conf
. Alternatively, the option
--client_mds_namespace
is supported for backward compatibility.
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.
Persistent Mounts
To mount CephFS as a file system in user space, add the following to /etc/fstab
:
#DEVICE PATH TYPE OPTIONS
none /mnt/mycephfs fuse.ceph ceph.id={user-ID}[,ceph.conf={path/to/conf.conf}],_netdev,defaults 0 0
For example:
none /mnt/mycephfs fuse.ceph ceph.id=myuser,_netdev,defaults 0 0
none /mnt/mycephfs fuse.ceph ceph.id=myuser,ceph.conf=/etc/ceph/foo.conf,_netdev,defaults 0 0
Ensure you use the ID (e.g., myuser
, not client.myuser
). You can pass
any valid ceph-fuse
option to the command line this way.
To mount a subdirectory of the CephFS, add the following to /etc/fstab
:
none /mnt/mycephfs fuse.ceph ceph.id=myuser,ceph.client_mountpoint=/path/to/dir,_netdev,defaults 0 0
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
. After making the fstab entry shown above,
run following commands:
systemctl start ceph-fuse@/mnt/mycephfs.service
systemctl enable ceph-fuse.target
systemctl enable ceph-fuse@-mnt-mycephfs.service
See User Management for details on CephX user management and ceph-fuse manual for more options it can take. For troubleshooting, see ceph-fuse debugging.
Brought to you by the Ceph Foundation
The Ceph Documentation is a community resource funded and hosted by the non-profit Ceph Foundation. If you would like to support this and our other efforts, please consider joining now.