doc : man page for snapshot commands

This patch also contains few modifications in admin documentation.

Change-Id: I7bc2a88e6cbcfe81dcfafc2956f5b7c5524b0f0b
BUG: 1122399
Signed-off-by: Sachin Pandit <spandit@redhat.com>
Reviewed-on: http://review.gluster.org/8357
Reviewed-by: Avra Sengupta <asengupt@redhat.com>
Tested-by: Gluster Build System <jenkins@build.gluster.com>
Reviewed-by: Kaushal M <kaushal@redhat.com>

2 files changed, 96 insertions, 61 deletions

diff --git a/doc/admin-guide/en-US/markdown/admin_managing_snapshots.md b/doc/admin-guide/en-US/markdown/admin_managing_snapshots.md
index 4ae6e4e062b..66fdb76af7d 100644
--- a/doc/admin-guide/en-US/markdown/admin_managing_snapshots.md
+++ b/doc/admin-guide/en-US/markdown/admin_managing_snapshots.md
@@ -26,12 +26,12 @@ Syntax :
 *gluster snapshot create <snapname\> <volname\(s\)\> \[description <description\>\] \[force\]*
 
 Details :
-This command will create a snapshot of a GlusterFS volume.
-User can provide a snap-name and a description to identify the snap.
-The description cannot be more than 1024 characters.
+Creates a snapshot of a GlusterFS volume. User can provide a snap-name and a
+description to identify the snap. The description cannot be more than 1024
+characters.
 
-To be able to take a snapshot, Volume should be present and it should be
-in started state.
+NOTE : To be able to take a snapshot, volume should be present and it
+should be in started state.
 
 -----------------------------------------------------------------------------
 
@@ -41,11 +41,12 @@ Syntax :
 *gluster snapshot restore <snapname\>*
 
 Details :
-This command restores an already taken snapshot of a GlusterFS volume.
+Restores an already taken snapshot of a GlusterFS volume.
 Snapshot restore is an offline activity therefore if the volume is
 online (in started state) then the restore operation will fail.
 
-Once the snapshot is restored  it will be deleted from the list of snapshot.
+Once the snapshot is restored it will not be available in the
+list of snapshots.
 
 ---------------------------------------------------------------------------
 
@@ -55,7 +56,7 @@ Syntax :
 *gluster snapshot delete <snapname\>*
 
 Details :
-This command will delete the specified snapshot.
+Deletes the specified snapshot.
 
 --------------------------------------------------------------------------
 
@@ -65,9 +66,9 @@ Syntax:
 *gluster snapshot list \[volname\]*
 
 Details:
-This command is used to list all snapshots taken, or for a specified volume.
-If Volname is given, then the snaps belonging to that particular volume
-is displayed.
+Lists  all  snapshots  taken.
+If volname is provided, then only the snapshots belonging to
+that particular volume is listed.
 
 -------------------------------------------------------------------------
 
@@ -77,10 +78,10 @@ Syntax:
 *gluster snapshot info \[\(snapname | volume <volname\>\)\]*
 
 Details:
-This command gives out the information such as snapshot name, snapshot UUID,
+This command gives information such as snapshot name, snapshot UUID,
 time at which snapshot was created, and it lists down the snap-volume-name,
-Number of snaps taken for a particular volume, number of snaps available
-for that particular volume, and the state of snapshot.
+number of snapshots already taken and number of snapshots still available
+for that particular volume, and the state of the snapshot.
 
 ------------------------------------------------------------------------
 
@@ -90,61 +91,48 @@ Syntax:
 *gluster snapshot status \[\(snapname | volume <volname\>\)\]*
 
 Details:
-This command will give a detailed information about the snapshot.
-The details included in this will be Brick-patch of the snapshot bricks,
-Volume Group(LVM details) to which the taken snapshot belong to, Status
-of the snapshot bricks (whether its running or not), PID of the bricks,
-Data percentage filled for that partiuclar Volume Group to which the
-snapshots belong to, And total size of the Logical volume to which
-the snapshots belong to.
-
-If snapname is specified then details of the mentioned snapshot is displayed.
-If Volume name is specified then details of all the snaps belonging to
-the mentioned volume name is displayed.
-If both snapname and volume name is not specified then details of all
-the snaps present will be displayed.
+This  command  gives  status of the snapshot.
+The details included are snapshot brick path, volume group(LVM details),
+status of the snapshot bricks, PID of the bricks, data percentage  filled for
+that particular volume group to which the snapshots belong to, and total size
+of the logical volume.
+
+If snapname is specified then status of the mentioned snapshot is displayed.
+If volname  is specified then status of all snapshots belonging to that volume
+is displayed. If both snapname and volname is not specified then status of all
+the snapshots present in the system are displayed.
 
 ------------------------------------------------------------------------
+
 **Configuring the snapshot behavior**
 
 Syntax:
-*gluster snapshot config \[volname\]*
+*snapshot config \[volname\] \(\[snap-max-hard-limit <count\>\] \[snap-max-soft-limit <percent>\]\)
+                            | \(\[auto-delete <enable|disable\>\]\)*
 
 Details:
-This command will display existing config values for a volume. If volume name
-is not provided then config values of all the volume is displayed.
-System config is displayed irrespective of volume name.
+Displays and sets the snapshot config values.
 
+snapshot  config without any keywords displays the snapshot config values of
+all volumes in the system. If volname is provided, then the snapshot config
+values of that volume is  displayed.
 
-Syntax:
-*snapshot config \[volname\] \(\[snap-max-hard-limit <count\>\] \[snap-max-soft-limit <percent>\]\)
-                            | \(\[auto-delete <enable|disable\>\]\)*
+Snapshot  config command along with keywords can be used to change the existing
+config values. If volname is provided then config value of that volume is
+changed, else it  will set/change the system limit.
 
-Details:
-The above command can be used to change the existing config values.
-If volname is provided then config value of that volume is changed,
-else it will set/change the system limit.
-
-As of now, snap-max-soft-limit and auto-delete cannot be configured to
-individually volume. soft-limit and auto-delete is only applicable
-globally. Once that is set, all the volumes will inherit the global
-value.
-
-The system limit is the default value of the config for all the volume.
-Volume specific limit cannot cross the system limit.
-If a volume specific limit is not provided then system limit will be
-considered.
-
-When auto-delete feature is enabled, then as soon as the soft-limit
-is reached the oldest snapshot is deleted for every successful snapshot
-creation, With this it is ensured that number of snapshot created is
-not more than snap-max-hard-limit.
-
-When auto-delete feature is disabled, If the the soft-limit is
-reached then user is given a warning about exceeding soft-limit
-along with successful snapshot creation message (oldest snapshot is
-not deleted). And upon reaching hard-limit further snapshot creation
-is not allowed.
+snap-max-soft-limit  and auto-delete are global options, that will be
+inherited by all volumes in the system and cannot be set to individual volumes.
+
+The system limit takes precedence over the volume specific limit.
+
+When auto-delete feature is enabled, then upon reaching the soft-limit,
+with every successful snapshot creation, the oldest snapshot will be deleted.
+
+When  auto-delete  feature  is disabled, then upon reaching the soft-limit,
+the user gets a warning with every successful snapshot creation.
+
+Upon reaching the hard-limit, further snapshot creations will not be allowed.
 
 -------------------------------------------------------------------------
 
@@ -154,7 +142,7 @@ Syntax:
 *gluster snapshot activate <snapname\>*
 
 Details:
-This command will activate the mentioned snapshot.
+Activates the mentioned snapshot.
 
 Note : By default the snapshot is activated during snapshot creation.
 
@@ -166,6 +154,6 @@ Syntax:
 *gluster snapshot deactivate <snapname\>*
 
 Details:
-This command will de-activate the mentioned snapshot.
+Deactivates the mentioned snapshot.
 
 -------------------------------------------------------------------------
diff --git a/doc/gluster.8 b/doc/gluster.8
index 87b83956ce6..28811c5b3d4 100644
--- a/doc/gluster.8
+++ b/doc/gluster.8
@@ -105,6 +105,53 @@ Display the status of peers.
 .TP
 \fB\ peer help \fR
 Display help for the peer command.
+.SS "Snapshot Commands"
+.PP
+.TP
+\fB\ snapshot create <snapname> <volname> [description <description>] [force] \fR
+Creates a snapshot of a GlusterFS volume. User can provide a snap-name and a description to identify the snap. The description cannot be more than 1024 characters. To be able to take a snapshot, volume should be present and it should be in started state.
+.TP
+\fB\ snapshot restore <snapname> \fR
+Restores an already taken snapshot of a GlusterFS volume. Snapshot restore is an offline activity therefore if the volume is online (in started state) then the restore operation will fail. Once the snapshot is restored it will not be available in the list of snapshots.
+.TP
+\fB\ snapshot delete <snapname> \fR
+Deletes the specified snapshot.
+.TP
+\fB\ snapshot list [volname] \fR
+Lists all snapshots taken. If volname is provided, then only the snapshots belonging to that particular volume is listed.
+.TP
+\fB\ snapshot info [snapname | (volume <volname>)] \fR
+This command gives information such as snapshot name, snapshot UUID, time at which snapshot was created, and it lists down the snap-volume-name, number of snapshots already taken and number of snapshots still available for that particular volume, and the state of the snapshot.
+.TP
+\fB\ snapshot status [snapname | (volume <volname>)] \fR
+This command gives status of the snapshot. The details included are snapshot brick path, volume group(LVM details), status of the snapshot bricks, PID of the bricks, data percentage filled for that particular volume group to which the snapshots belong to, and total size of the logical volume.
+
+If snapname is specified then status of the mentioned snapshot is displayed. If volname is specified then status of all snapshots belonging to that volume is displayed. If both snapname and volname is not specified then status of all the snapshots present in the system are displayed.
+.TP
+\fB\ snapshot config [volname] ([snap-max-hard-limit <count>] [snap-max-soft-limit <percent>]) | ([auto-delete <enable|disable>])
+Displays and sets the snapshot config values.
+
+snapshot config without any keywords displays the snapshot config values of all volumes in the system. If volname is provided, then the snapshot config values of that volume is displayed.
+
+Snapshot config command along with keywords can be used to change the existing config values. If volname is provided then config value of that volume is changed, else it will set/change the system limit.
+
+snap-max-soft-limit and auto-delete are global options, that will be inherited by all volumes in the system and cannot be set to individual volumes.
+
+The system limit takes precedence over the volume specific limit.
+
+When auto-delete feature is enabled, then upon reaching the soft-limit, with every successful snapshot creation, the oldest snapshot will be deleted.
+
+When auto-delete feature is disabled, then upon reaching the soft-limit, the user gets a warning with every successful snapshot creation.
+
+Upon reaching the hard-limit, further snapshot creations will not be allowed.
+.TP
+\fB\ snapshot activate <snapname> \fR
+Activates the mentioned snapshot.
+
+Note : By default the snapshot is activated during snapshot creation.
+.TP
+\fB\ snapshot deactivate <snapname> \fR
+Deactivates the mentioned snapshot.
 .SS "Other Commands"
 .TP
 \fB\ help \fR