LU-7544 doc: improve setquota man page

Move 'lfs setquota' to a separate man page and change the man page to
use "K, M, G, T, P" suffixes for block limits.

Test-Parameters: trivial
Signed-off-by: Niu Yawei <yawei.niu@intel.com>
Change-Id: I8de81ebfed86151dbb1ac16690f3b4e377f95366
Reviewed-on: https://review.whamcloud.com/28163
Tested-by: Jenkins
Tested-by: Maloo <hpdd-maloo@intel.com>
Reviewed-by: Andreas Dilger <andreas.dilger@intel.com>
Reviewed-by: Fan Yong <fan.yong@intel.com>

diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am
index 11420c0..4089c5c 100644 (file)
--- a/lustre/doc/Makefile.am
+++ b/lustre/doc/Makefile.am
@@ -47,6 +47,7 @@ MANFILES =                                    \
        lfs-mkdir.1                             \
        lfs-setdirstripe.1                      \
        lfs-setstripe.1                         \
+       lfs-setquota.1                          \
        l_getidentity.8                         \
        lgss_sk.8                               \
        lhbadm.8                                \

diff --git a/lustre/doc/lfs-setquota.1 b/lustre/doc/lfs-setquota.1
new file mode 100644 (file)
index 0000000..1657801
--- /dev/null
+++ b/lustre/doc/lfs-setquota.1
@@ -0,0 +1,88 @@
+.TH LFS-SETQUOTA 1 2017-07-21 "Lustre" "Lustre Utilities"
+.SH NAME
+lfs setquota \- set quota limits or grace time for users, groups or projects.
+.SH SYNOPSIS
+.B lfs setquota {\fB-u|--user|-g|--group|-p|--projid\fR} <\fIuname|uid|gname|gid|projid\fR>
+       [\fB--block-softlimit|-b\fR <\fIblock-softlimit\fR>[kMGTPE]]
+       [\fB--block-hardlimit|-B\fR <\fIblock-hardlimit\fR>[kMGTPE]]
+       [\fB--inode-softlimit|-i\fR <\fIinode-softlimit\fR>[kMGTPE]]
+       [\fB--inode-hardlimit|-I\fR <\fIinode-hardlimit\fR>[kMGTPE]] <\fIfilesystem\fR>
+.br
+.B lfs setquota \fB-t\fR {\fB-u|-g|-p\fR}
+       [\fB--block-grace|-b\fR <\fIblock-grace\fR>]
+       [\fB--inode-grace|-i\fR <\fIinode-grace\fR>] <\fIfilesystem\fR>
+.br
+.SH DESCRIPTION
+.PP
+.BR "lfs setquota " {\fB-u|-g|-p\fR}
+.TP
+Command sets the filesystem quotas for users, groups or projects respectively. \
+Block limits unit is kilobyte (1024) by default and block limits are always \
+kilobyte-grained (even if specified in bytes), block limits can be specified \
+with a \
+.BR k "," M "," G "," T "," P ", or " E \
+suffixes which specify units of 2^10, 2^20, 2^30, 2^40, 2^50 and 2^60 \
+accordingly.
+.TP
+.B -u|--user <\fIuname|uid\fR>
+Set user quota for \fIuname\fR or \fIuid\fR.
+.TP
+.B -g|--group <\fIgname|gid\fR>
+Set group quota for name \fIgname\fR or \fIgid\fR.
+.TP
+.B -p|--project <\fIprojid\fR>
+Set project quota for \fIprojid\fR.
+.TP
+.B -b|--block-softlimit <\fIblock-softlimit\fR>
+Specify block softlimit, zero means unlimited.
+.TP
+.B -B|--block-hardlimit <\fIblock-hardlimit\fR>
+Specify block hardlimit, zero means unlimited. The block hardlimit should be \
+greater than block softlimit when it's being specified.
+.TP
+.B -i|--inode-softlimit <\fIinode-softlimit\fR>
+Specify inode softlimit, zero means unlimited.
+.TP
+.B -I|--inode-hardlimit <\fIinode-hardlimit\fR>
+Specify inode hardlimit, zero means unlimited. The inode hardlimit should be \
+greater than inode softlimit when it's being specified.
+.PP
+.BR "lfs setquota -t "
+.TP
+Command sets the filesystem quota grace time for users, groups, or projects. \
+This is a global value that indicates the amount of time, in seconds, that the \
+soft quota limit can be exceeded before users are prevented from creating \
+new files or consuming more space.  This is intended to allow users to exceed \
+the quota limit for a short time to complete their work, without having to \
+grant each user a larger hard quota limit.  The soft quota limit is reset once \
+the user, group, or project reduces their space usage below the soft quota \
+limit. Grace time is specified in "XXwXXdXXhXXmXXs" format or as an integer \
+seconds value.
+.TP
+.B -t
+Set quota grace times.
+.TP
+.B -u
+Set grace time for user.
+.TP
+.B -g
+Set grace time for group.
+.TP
+.B -p
+Set grace time for project.
+.TP
+.B -b|--block-grace <\fIblock-grace\fR>
+Specify grace time for block quota.
+.TP
+.B -i|--inode-grace <\fIindoe-grace\fR>
+Specify grace time for inode quota.
+.SH EXAMPLES
+.TP
+.B $ lfs setquota -u bob --block-softlimit 2000000 --block-hardlimit 1000000 /mnt/lustre
+Set quotas of user `bob': 1GB block quota hardlimit and 2 GB block quota softlimit
+.TP
+.B $ lfs setquota -t -u --block-grace 1000 --inode-grace 1w4d /mnt/lustre
+Set grace times for user quotas: 1000 seconds for block quotas, 1 week and 4 \
+days for inode quotas
+.SH SEE ALSO
+.BR lfs (1)

diff --git a/lustre/doc/lfs.1 b/lustre/doc/lfs.1
index 1187274..cf59e78 100644 (file)
--- a/lustre/doc/lfs.1
+++ b/lustre/doc/lfs.1
@@ -92,27 +92,6 @@ lfs \- Lustre utility to create a file with specific striping pattern, find the
 .br
 .B lfs quotaoff [-ug] <filesystem>
 .br
-.B lfs setquota <-u|--user|-g|--group|-p|--projid> <uname|uid|gname|gid|projid>
-             \fB[--block-softlimit <block-softlimit>]
-             \fB[--block-hardlimit <block-hardlimit>]
-             \fB[--inode-softlimit <inode-softlimit>]
-             \fB[--inode-hardlimit <inode-hardlimit>]
-             \fB<filesystem>\fR
-.br
-.B lfs setquota <-u|--user|-g|--group|-p|--projid> <uname|uid|gname|gid|projid>
-             \fB[-b <block-softlimit>] [-B <block-hardlimit>]
-             \fB[-i <inode-softlimit>] [-I <inode-hardlimit>]
-             \fB<filesystem>\fR
-.br
-.B lfs setquota -t <-u|-g|-p>
-             \fB[--block-grace <block-grace>]\fR
-             \fB[--inode-grace <inode-grace>]\fR
-             \fB<filesystem>\fR
-.br
-.B lfs setquota -t <-u|-g|-p>
-             \fB[-b <block-grace>] [-i <inode-grace>]\fR
-             \fB<filesystem>\fR
-.br
 .B lfs setstripe [--stripe-size|-S stripe_size] [--stripe-count|-c stripe_count]
         \fB[--stripe-index|-i start_ost_index] [--pool|-p <poolname>]
         \fB[--ost-list|-o <ost_indices>] <directory|filename>\fR
@@ -283,12 +262,6 @@ To turn filesystem quotas on. Options specify quota for users (-u) groups (-g) a
 .B quotaoff [-ugf] <filesystem> (deprecated as of 2.4.0)
 To turn filesystem quotas off.  Options specify quota for users (-u) groups (-g) and force (-f). Not used anymore in lustre 2.4.0 where quota enforcement can be turned off (for inode or block) by running the following command on the MGS: lctl conf_param ${FSNAME}.quota.<ost|mdt>=""
 .TP
-.B setquota  <-u|-g|-p> <uname>|<uid>|<gname>|<gid>|<projid> [--block-softlimit <block-softlimit>] [--block-hardlimit <block-hardlimit>] [--inode-softlimit <inode-softlimit>] [--inode-hardlimit <inode-hardlimit>] <filesystem>
-To set filesystem quotas for users, groups or project. Limits can be specified with -b, -k, -m, -g, -t, -p suffixes which specify units of 1, 2^10, 2^20, 2^30, 2^40 and 2^50 accordingly. Block limits unit is kilobyte (1024) by default and block limits are always kilobyte-grained (even if specified in bytes), see EXAMPLES
-.TP
-.B setquota -t [-u|-g|-p] [--block-grace <block-grace>] [--inode-grace <inode-grace>] <filesystem>
-To set filesystem quota grace times for users,groups or project. Grace time is specified in "XXwXXdXXhXXmXXs" format or as an integer seconds value, see EXAMPLES
-.TP
 .B swap_layouts <filename1> <filename2>
 Swap the data (layout and OST objects) of two regular files. The
 two files have to be in the same filesystem, owned by the same user,
@@ -389,12 +362,6 @@ Turn quotas of user and group on
 .TP
 .B $ lfs quotaoff -ug /mnt/lustre
 Turn quotas of user and group off
-.TP
-.B $ lfs setquota -u bob --block-softlimit 2000000 --block-hardlimit 1000000 /mnt/lustre
-Set quotas of user `bob': 1GB block quota hardlimit and 2 GB block quota softlimit
-.TP
-.B $ lfs setquota -t -u --block-grace 1000 --inode-grace 1w4d /mnt/lustre
-Set grace times for user quotas: 1000 seconds for block quotas, 1 week and 4 days for inode quotas
 .SH NOTES
 The usage of \fBlfs hsm_*\fR, \fBlfs setstripe\fR, \fBlfs migrate\fR, \fBlfs setdirstripe\fR,
 \fBlfs getdirstripe\fR and \fBlfs mkdir\fR are explained in separated man pages.
@@ -411,5 +378,6 @@ The lfs command is part of the Lustre filesystem.
 .BR lfs_migrate (1),
 .BR lfs-setstripe (1),
 .BR lfs-migrate (1),
+.BR lfs-setquota (1),
 .BR lctl (8),
 .BR lustre (7)