How to create a CephFS snapshot

CephFS snapshots preserve a point-in-time view of a directory tree inside a mounted Ceph file system. They are useful before an application upgrade, bulk import, or risky data change because the snapshot path keeps the previous files readable without copying the whole tree into a separate location.

CephFS exposes snapshots through a hidden special directory named .snap below each snapshottable directory unless the client mount uses a custom snapshot directory name. Creating a subdirectory inside .snap asks the MDS metadata server to create a snapshot for that directory subtree, while the live directory keeps accepting normal writes outside the snapshot path.

The mounted client needs write and snapshot permission on the target path. A cluster created before snapshots were enabled by default, or one with snapshots disabled by policy, may need allow_new_snaps set once before clients can create new snapshot directories. After creation, the snapshot should appear as a named entry under .snap, and a known file should be readable through that snapshot path.

1. Enable snapshot creation on CephFS file systems when needed.

   $ ceph fs set cephfs allow_new_snaps true

   CephFS enables snapshot creation by default for new file systems. Run this from an admin shell only when cluster policy or an older file system has disabled new snapshots.

2. Confirm that the mounted client identity can create snapshots under the target path.

   $ ceph auth get client.app-snapshotter
   [client.app-snapshotter]
       caps mds = "allow rws path=/projects/app"
       caps mon = "allow r"
       caps osd = "allow rw tag cephfs data=cephfs"

   The s flag in the MDS cap allows snapshot creation. Omit secret key material from tickets, transcripts, and screenshots.

   Related: How to create a path-limited CephFS client key

3. Confirm that the target directory is on a CephFS mount.

   $ findmnt -T /mnt/cephfs/projects/app
   TARGET      SOURCE        FSTYPE       OPTIONS
   /mnt/cephfs ceph-fuse[/]  fuse.ceph-fuse rw,relatime,user_id=0,group_id=0,allow_other

   Replace /mnt/cephfs/projects/app with the directory that should be protected.
   Related: How to mount CephFS on Linux

4. Inspect a file that should be visible in the snapshot.

   $ ls -l /mnt/cephfs/projects/app
   total 8
   -rw-r--r-- 1 app app 19 Jun 29 09:12 release.txt
   drwxr-xr-x 2 app app  1 Jun 29 09:10 uploads

   The .snap directory is a special CephFS view and might not appear in a normal directory listing.

5. Create the snapshot directory below .snap.

   $ mkdir /mnt/cephfs/projects/app/.snap/pre-upgrade-2026-06-29

   Snapshot names share the directory's .snap namespace. Choose a name that will not collide with an existing snapshot and avoid creating snapshots inside a path that another administrator is actively pruning.

6. List the snapshots for the directory.

   $ ls /mnt/cephfs/projects/app/.snap
   pre-upgrade-2026-06-29

7. Read the known file through the snapshot path.

   $ cat /mnt/cephfs/projects/app/.snap/pre-upgrade-2026-06-29/release.txt
   release=2026.06.29

   If the live file changes later, the same snapshot path should continue showing the file content captured when the snapshot directory was created.