Skip to main content
RunBook Academy

CephXLII · CephFS OperationsCephFS Operations

Mounting CephFS: kernel and FUSE

Intermediate⏱ ~17 minmountceph-fuse

What you'll learn

  • Mount CephFS with the kernel client and with ceph-fuse
  • Compare their characteristics
  • Configure persistent mounts safely
  • Diagnose mount failures for each

Prerequisites

None — start here.

Verified against Ceph Tentacle 20.2.x · Ceph Squid 19.2.x (supported previous) · cephadm matches the verified Ceph release · podman 4.x · csi-rbd and csi-cephfs current · RBD / CephFS / RGW current (matches Ceph release) · Linux kernel 5.15+ (5.10 minimum) · Ubuntu 24.04 LTS (Ceph host baseline) · Debian 12 (Bookworm) (Ceph host baseline) · Rocky Linux / RHEL / AlmaLinux 9.x (Ceph host baseline) · Proxmox VE 9.x (cross-course integration) · Kubernetes 1.31+ (cross-course integration) · 2026-08-18

Not yet marked complete on this device.

Why this matters in production

The two clients differ in ways that matter during an incident, and the kernel client — the faster and more common choice — is the one that can require a reboot to recover. Choosing per host rather than by default is worth the consideration.

Kernel mount

# the monitor addresses to mount against:
MONS=10.20.0.10:3300,10.20.0.11:3300,10.20.0.12:3300

mount -t ceph \
  "$MONS:/" \
  /mnt/cephfs \
  -o name=myapp,secretfile=/etc/ceph/myapp.secret,fs=cephfs

# a subtree
mount -t ceph "$MONS:/projects/alpha" /mnt/alpha \
  -o name=tenant-a,secretfile=/etc/ceph/tenant-a.secret

In /etc/fstab:

10.20.0.10:3300,10.20.0.11:3300:/  /mnt/cephfs  ceph  name=myapp,secretfile=/etc/ceph/myapp.secret,_netdev,noatime  0 0

_netdev is essential — without it, systemd attempts the mount before the network is up and boot fails or hangs.

FUSE mount

ceph-fuse /mnt/cephfs --id myapp --keyring /etc/ceph/ceph.client.myapp.keyring
ceph-fuse /mnt/alpha --id tenant-a -r /projects/alpha
none  /mnt/cephfs  fuse.ceph  ceph.id=myapp,_netdev,defaults  0 0

The comparison

Kernelceph-fuse
Performancesubstantially betterlower, userspace round trips
Feature supportkernel-version dependentalways current with Ceph
Quota enforcementmodern kernelsalways
Recovery from a hung clustermay need a rebootkill the process
Upgradekernel upgrade and rebootpackage update
Memorykernel page cacheprocess memory

Passing the secret

Never put the key inline in fstab, where it is world-readable:

ceph auth print-key client.myapp > /etc/ceph/myapp.secret
chmod 600 /etc/ceph/myapp.secret

Then use secretfile= rather than secret=.

Mount failure diagnostics

Kernel:

dmesg | tail -20
# libceph: mon0 ... socket error
# ceph: No mds server is up or the cluster is laggy

FUSE:

ceph-fuse /mnt/cephfs --id myapp -d      # foreground, verbose
journalctl -u ceph-fuse@*

The FUSE client’s foreground mode is a real advantage when diagnosing — it prints the failure directly rather than requiring a separate log.

Quiz

Knowledge check · 4 questions

  1. Q1. Why is `_netdev` required on a CephFS fstab entry?

  2. Q2. ceph-fuse feature support depends on the running kernel version.

  3. Q3. Choose a client for a host with a fixed kernel.

    A host running a vendor-certified kernel that cannot be changed needs CephFS access with quota enforcement, which its kernel version does not support. The workload is moderate and not performance-critical.

  4. Q4. Why should `secretfile=` be used rather than `secret=` in fstab?

Passing score: 75%. Answers are checked in this browser.

Production discipline

Put _netdev on every CephFS fstab entry and use secretfile= rather than an inline secret; both are single options that prevent a class of problem that is unpleasant to debug afterwards. Record which client each host uses, since the recovery procedure differs and the difference is not visible from the cluster.

Cross-course references

  • Kubernetes: CSI driver choice determines the same feature and recovery characteristics
  • Linux: NFS versus FUSE-based filesystems present the identical performance-versus-flexibility trade