Troubleshoot a CephFS mount

This runbook covers Troubleshoot a CephFS mount on a Ceph Tentacle cluster.

When to use

• Active production scenario matching the impact (service-affecting)
• The prerequisites are met

Prerequisites

Before starting this runbook, verify each prerequisite has been met. If a prerequisite is not met, resolve it first or escalate.

• A CephFS mount is failing or slow
• Clients see stale file handles or metadata errors

Pre-checks

Collect evidence before taking action. Evidence is the proof the runbook worked.

# ceph mds stat reports the MDS state
# ceph fs ls shows the filesystem is healthy
# CephFS clients see specific error codes
# The kernel or FUSE client logs are readable

Procedure

Step 1

Try a fresh mount: umount /mnt/cephfs; mount -t ceph

Step 2

If FUSE: ceph-fuse -m <mon-ip> /mnt/cephfs -d

Step 3

Check the MDS journal size

Step 4

Check the data / metadata pool utilisation

Step 5

Check the cap revocation latency

Verification

After completing the procedure, verify the result:

# The mount succeeds
# I/O latency is acceptable
# No errors in the client log

Rollback

If the procedure does not produce the expected verification, roll back:

• If the MDS is the issue: see ceph-rb-recover-mds
• If the pool is full: see ceph-rb-investigate-nearfull
• If the client kernel is the issue: upgrade

Escalation

If you cannot roll back or the rollback fails, escalate:

• Storage team