Merge pull request #61240 from neesingh-rh/wip-68974

doc: add snapshots under cephfs concepts

Reviewed-by: Anthony D'Atri <anthony.datri@gmail.com>

2 files changed, 86 insertions, 0 deletions

diff --git a/doc/cephfs/index.rst b/doc/cephfs/index.rst
index a8a991b01b0..630d29f1956 100644
--- a/doc/cephfs/index.rst
+++ b/doc/cephfs/index.rst
@@ -148,6 +148,7 @@ CephFS Concepts
     LazyIO <lazyio>
     Directory fragmentation <dirfrags>
     Multiple active MDS daemons <multimds>
+    Snapshots <snapshots>
 
 
 .. raw:: html
diff --git a/doc/cephfs/snapshots.rst b/doc/cephfs/snapshots.rst
new file mode 100644
index 00000000000..a60be96ed53
--- /dev/null
+++ b/doc/cephfs/snapshots.rst
@@ -0,0 +1,85 @@
+================
+CephFS Snapshots
+================
+
+CephFS snapshots create an immutable view of the file system at the point
+in time they are taken. CephFS support snapshots which is managed in a 
+special hidden subdirectory named ``.snap`` .Snapshots are created using
+``mkdir`` inside this directory.
+
+Snapshots can be exposed with a different name by changing the following client configurations.
+
+- ``snapdirname`` which is a mount option for kernel clients
+- ``client_snapdir`` which is a mount option for ceph-fuse.
+
+Snapshot Creation
+==================
+
+CephFS snapshot feature is enabled by default on new file systems. To enable 
+it on existing file systems, use the command below.
+
+.. code-block:: bash
+    
+    $ ceph fs set <fs_name> allow_new_snaps true
+
+When snapshots are enabled, all directories in CephFS will have a special ``.snap``
+directory. (You may configure a different name with the client snapdir setting if 
+you wish.)
+To create a CephFS snapshot, create a subdirectory under ``.snap`` with a name of 
+your choice. 
+For example, to create a snapshot on directory ``/file1/``, invoke ``mkdir /file1/.snap/snapshot-name``
+
+.. code-block:: bash
+
+    $ touch file1
+    $ cd .snap
+    $ mkdir my_snapshot
+
+Using snapshot to recover data
+===============================
+
+Snapshots can also be used to recover some deleted files.
+
+- ``create a file1 and create snapshot snap1``
+
+.. code-block:: bash
+
+    $ touch /mnt/cephfs/file1
+    $ cd .snap
+    $ mkdir snap1
+
+- ``create a file2 and create snapshot snap2``
+
+.. code-block:: bash
+
+    $ touch /mnt/cephfs/file2
+    $ cd .snap
+    $ mkdir snap2
+
+- ``delete file1 and create a new snapshot snap3``
+
+.. code-block:: bash
+
+    $ rm /mnt/cephfs/file1
+    $ cd .snap
+    $ mkdir snap3
+
+- ``recover file1 using snapshot snap2 using cp command``
+
+.. code-block:: bash
+
+    $ cd .snap
+    $ cd snap2
+    $ cp file1 /mnt/cephfs/
+
+Snapshot Deletion
+==================
+
+Snapshots are deleted by invoking ``rmdir`` on the ``.snap`` directory they are
+rooted in. (Attempts to delete a directory which roots the snapshots will fail; 
+you must delete the snapshots first.)
+
+.. code-block:: bash
+
+    $ cd .snap
+    $ rmdir my_snapshot