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.

Steps to mount CephFS on Linux with the kernel client:

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.

Create the local Ceph configuration directory.
```
$ sudo install -d -m 755 /etc/ceph
```
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.
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

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.

Create the local mount point.
```
$ sudo mkdir -p /mnt/cephfs
```
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.

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

Write a small file through the mounted path.

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

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

Remove the temporary smoke-test file.

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