How to mount CephFS on Linux

Linux clients can mount CephFS directly through the kernel client when an application host needs shared POSIX storage from a Ceph cluster. The mount uses a CephX client identity, a local cluster configuration file, and a mount point that maps a CephFS path into the local directory tree.

The kernel-client path uses mount.ceph from the ceph-common package. With /etc/ceph/ceph.conf and a matching keyring under /etc/ceph, the mount helper can find monitors and client credentials without placing the secret on the command line.

Use a client key scoped to the path the workload should see. A key limited to one subtree must request that same subtree in the device string; mounting the filesystem root with that key should fail.

1. Install the CephFS kernel mount helper on the client host.

   $ sudo apt install ceph-common
   Reading package lists... Done
   Building dependency tree... Done
   The following NEW packages will be installed:
     ceph-common
   ##### snipped #####
   Setting up ceph-common ...

   Debian and Ubuntu provide mount.ceph through ceph-common. On other Linux distributions, install the package that provides the mount.ceph helper.

2. Create the local Ceph configuration directory.

   $ sudo install -d -m 755 /etc/ceph

3. Add the minimal cluster configuration for the client.

   $ sudoedit /etc/ceph/ceph.conf

   /etc/ceph/ceph.conf

   [global]
       fsid = 11111111-2222-3333-4444-555555555555
       mon_host = 192.0.2.11,192.0.2.12,192.0.2.13

   Use the real cluster FSID and monitor addresses from the Ceph admin host. Keep production hostnames and internal addresses out of saved transcripts and screenshots.

4. Install the scoped client keyring on the client host.

   $ sudo install -m 600 ceph.client.app-web.keyring /etc/ceph/ceph.client.app-web.keyring

   The keyring should contain the client.app-web identity and MDS capabilities for the CephFS path being mounted.
   Related: How to create a path-limited CephFS client key

5. Confirm the client files are readable only where needed.

   $ sudo ls -l /etc/ceph/ceph.conf /etc/ceph/ceph.client.app-web.keyring
   -rw-r--r-- 1 root root 130 Jun 29 09:10 /etc/ceph/ceph.conf
   -rw------- 1 root root  72 Jun 29 09:11 /etc/ceph/ceph.client.app-web.keyring

   A world-readable keyring exposes the CephX secret to local users. Keep client keyrings at mode 600 unless a stricter host policy is in place.

6. Create the local mount point.

   $ sudo mkdir -p /mnt/cephfs

7. Mount the authorized CephFS path.

   $ sudo mount -t ceph app-web@.cephfs=/srv/app /mnt/cephfs

   The device string uses client.app-web, the cephfs file system, and the /srv/app subtree. Change the path after = only when the client key is authorized for that CephFS path.

8. Check that Linux sees the CephFS mount.

   $ findmnt /mnt/cephfs
   TARGET      SOURCE                    FSTYPE OPTIONS
   /mnt/cephfs app-web@.cephfs=/srv/app ceph   rw,relatime,name=app-web

9. Write a small file through the mounted path.

   $ sudo touch /mnt/cephfs/client-mount-test.txt

10. Confirm the file is visible through the CephFS mount.

    $ ls -l /mnt/cephfs/client-mount-test.txt
    -rw-r--r-- 1 root root 0 Jun 29 09:14 /mnt/cephfs/client-mount-test.txt

11. Remove the temporary smoke-test file.

    $ sudo rm /mnt/cephfs/client-mount-test.txt