CephFS is the native file system provided by the Ceph distributed storage system. It allows you to mount a Ceph cluster as a traditional POSIX-compliant file system on Linux hosts, enabling applications to access objects stored in Ceph without modifying code.

How to use CephFS

1. Prerequisites

• Ensure you have a running Ceph cluster with the cephfs service enabled
• Confirm the CephFS metadata server (MDS) and data pool are configured
• Verify network connectivity between the client host and Ceph monitors

2. Install Ceph client tools

On your Linux client host, install the Ceph client package:

sudo apt install ceph-client  # Debian/Ubuntu
# or
sudo yum install ceph  # RHEL/CentOS

3. Retrieve Ceph configuration

Obtain the cluster's configuration file (typically /etc/ceph/ceph.conf):

sudo cp /etc/ceph/ceph.conf /etc/ceph/ceph.conf

4. Add the CephFS client keyring

Ensure the client has access to the CephFS keyring:

sudo ceph auth get client.admin
# If needed, copy the keyring to the client host
sudo cp /etc/ceph/ceph.client.admin /etc/ceph/ceph.client.admin

5. Mount the CephFS filesystem

Create a mount point and mount the CephFS:

sudo mkdir -p /mnt/cephfs
sudo mount -t cephfs cephfs /mnt/cephfs

• Replace cephfs with your actual CephFS namespace (if different)
• Use the cluster's monitor addresses if specified in ceph.conf

6. Verify the mount

Check that the filesystem is mounted correctly:

df -h /mnt/cephfs
ls -la /mnt/cephfs

7. Unmount when finished

sudo umount /mnt/cephfs

Common issues to check

• Ensure the cephfs service is running on the MDS nodes
• Verify the client has the correct keyring permissions
• Confirm network routing between client and Ceph monitors
• Check for firewall rules blocking Ceph ports (6789, 6800-6802)

Notes

  cephfs /mnt/cephfs cephfs _netdev,defaults 0 0

• CephFS supports standard Linux file operations (read, write, permissions)
• For persistent mounts, add an entry to /etc/fstab:
• Use ceph fs status to check CephFS service health
• Consult Ceph documentation for advanced configuration options

cephfs

CephFS is a distributed file system provided by the Ceph storage platform. It allows you to mount a POSIX‑compatible file system on client machines, enabling standard file operations across a highly scalable backend.

Getting started

1. Confirm prerequisites

• A running Ceph cluster with a CephFS service (MDS) configured.
• Network connectivity between the client host and the Ceph monitors.
• Appropriate permissions on the CephFS export (e.g., a client key with allow rwx for the desired namespace).

   # Debian/Ubuntu
   sudo apt install ceph-client

   # RHEL/CentOS
   sudo yum install ceph

1. Install Ceph client tools on the client host

1. Obtain the cluster configuration

• Copy the cluster’s ceph.conf file to the client, typically located at /etc/ceph/ceph.conf.
• Ensure the file contains the monitor addresses and the CephFS namespace details.

1. Add the client keyring

     sudo ceph auth get client.admin

     sudo cp /etc/ceph/ceph.client.admin /etc/ceph/ceph.client.admin

• Retrieve the key for the client that is allowed to access CephFS:
• If the key is not already present on the client, copy it:

   sudo mkdir -p /mnt/cephfs

1. Create a mount point

   sudo mount -t cephfs :/ /mnt/cephfs

1. Mount the CephFS export

• Replace with the hostname or IP of an MDS node.
• Replace with the CephFS namespace you wish to mount (e.g., myfs).

   df -h /mnt/cephfs
   ls -la /mnt/cephfs

1. Verify the mount

1. Persist the mount (optional)

     :/   /mnt/cephfs   cephfs   _netdev,defaults   0   0

• Add an entry to /etc/fstab for automatic mounting at boot:

Common troubleshooting steps

• Service health – Run ceph fs status to ensure the MDS service is healthy.
• Keyring permissions – Confirm the client key has allow rwx for the target namespace.
• Network – Verify that ports 6789 (monitor), 6800‑6802 (OSD), and the MDS port (usually 6803) are open between client and cluster.
• Firewall – Ensure local firewall rules do not block traffic to the MDS.
• Mount errors – Check dmesg or journalctl for kernel‑level messages related to the mount attempt.

Basic usage after mounting

Once the CephFS filesystem is mounted at /mnt/cephfs, you can treat it like any other Linux file system:

• Create directories: mkdir /mnt/cephfs/data
• Create files: echo "test" > /mnt/cephfs/data/file.txt
• Set permissions: chmod 644 /mnt/cephfs/data/file.txt
• List contents: ls -l /mnt/cephfs

All operations are performed over the Ceph backend, providing distributed performance and high availability.