LU-11048 docs: adding missing pool man pages

Adding lctl-pool_destroy.8, lctl-pool_list.8 and lctl-pool_remove.8.

Test-Parameters: trivial
Signed-off-by: Frederick Dilger <fdilger@whamcloud.com>
Change-Id: I227a85b9703346a7bce4250670002c97c2d37cb8
Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/56303
Reviewed-by: Andreas Dilger <adilger@whamcloud.com>
Reviewed-by: Sergey Cheremencev <scherementsev@ddn.com>
Reviewed-by: Oleg Drokin <green@whamcloud.com>
Tested-by: jenkins <devops@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>

diff --git a/lustre/doc/lctl-pool_destroy.8 b/lustre/doc/lctl-pool_destroy.8
new file mode 100644 (file)
index 0000000..27e586a
--- /dev/null
+++ b/lustre/doc/lctl-pool_destroy.8
@@ -0,0 +1,58 @@
+.TH LCTL-POOL_DESTROY 8 2024-09-08 Lustre "Lustre Configuration Utilities"
+.SH Name
+lctl-pool_destroy \- delete an OST pool
+.SH SYNOPSIS
+.SY "lctl pool_destroy"
+.RB [ -n | --nowait ]
+.IR FSNAME . POOLNAME
+.YS
+.SH DESCRIPTION
+Delete an OST pool with the name
+.I POOLNAME
+in the filesystem named
+.IR FSNAME .
+The
+.B lctl pool_destroy
+command must be run on the MGS node and can only be used by the root user.
+.SH OPTIONS
+.TP
+.BR -n ", " --nowait
+Do not wait and check if pool is updated on a client.
+This is useful when calling a lot of
+.RB \(dq lctl \ pool_*\(dq
+in a row. This avoids revoking the clients "CONFIG" lock for each
+command (by default clients retake their lock and update their configurations
+in a delay between 5-10s).
+.SH NOTES
+After updating the MGS configuration,
+this command tries to wait and check if pools are updated on a client.
+If the MGS is on a separate node from the MDS, a Lustre client must
+be mounted on the MGS node while the
+.B lctl
+commands are being run for this. Otherwise, the client check is skipped.
+.SH EXAMPLES
+Delete a pool named
+.B local
+in the
+.B testfs
+filesystem.
+.RS
+.EX
+.B # lctl pool_destroy testfs.local
+.EE
+.RE
+.SH AVAILABILITY
+.B lctl pool_destroy
+is part of the
+.BR lustre (7)
+filesystem package since release 1.7.0
+.\" Added in commit 1.6.1-1578-g665e36b780
+.SH SEE ALSO
+.BR lfs-df (1),
+.BR lfs-find (1),
+.BR lfs-setstripe (1),
+.BR lustre (7),
+.BR lctl-pool_add (8),
+.BR lctl-pool_list (8),
+.BR lctl-pool_new (8),
+.BR lctl-pool_remove (8)

diff --git a/lustre/doc/lctl-pool_list.8 b/lustre/doc/lctl-pool_list.8
new file mode 100644 (file)
index 0000000..881579b
--- /dev/null
+++ b/lustre/doc/lctl-pool_list.8
@@ -0,0 +1,61 @@
+.TH LCTL-POOL_LIST 2024-09-08 Lustre "Lustre Configuration Utilities"
+.SH NAME
+lctl-pool_list \- list pools and pool members
+.SH SYNOPSIS
+.SY "lctl pool_list"
+.IR FSNAME [. POOLNAME ]
+|
+.I PATHNAME
+.YS
+.SH DESCRIPTION
+List all OSTs in the pool named
+.I POOLNAME
+in the filesystem
+.I FSNAME
+or list all pools that exist in the directory
+.I PATHNAME
+or in the filesystem
+.IR FSNAME .
+.SH OPTIONS
+.TP
+.I POOLNAME
+If specified, show the OSTs in the pool named
+.IR POOLNAME .
+.SH EXAMPLES
+List all OSTs in the pool
+.B local
+in the filesystem
+.B testfs
+.RS
+.EX
+.B # lctl pool_list testfs.local
+Pool: lustre.local
+testfs-OST0001_UUID
+.EE
+.RE
+.PP
+List all pools in the filesystem
+.B testfs
+.RS
+.EX
+.B # lctl pool_list testfs
+Pools from testfs:
+testfs.local
+testfs.remote
+.EE
+.RE
+.SH AVAILABILITY
+.B lctl pool_list
+is part of the
+.BR lustre (7)
+filesystem package since release 1.7.0
+.\" Added in commit 1.6.1-1578-g665e36b780
+.SH SEE ALSO
+.BR lfs-df (1),
+.BR lfs-find (1),
+.BR lfs-setstripe (1),
+.BR lustre (7),
+.BR lctl-pool_add (8),
+.BR lctl-pool_destroy (8),
+.BR lctl-pool_list (8),
+.BR lctl-pool_new (8)

diff --git a/lustre/doc/lctl-pool_remove.8 b/lustre/doc/lctl-pool_remove.8
new file mode 100644 (file)
index 0000000..8cd735d
--- /dev/null
+++ b/lustre/doc/lctl-pool_remove.8
@@ -0,0 +1,94 @@
+.TH LCTL-POOL_REMOVE 8 2024-08-30 Lustre "Lustre Configuration Utilities"
+.SH NAME
+lctl-pool_remove \- remove OST from a named pool
+.SH SYNOPSIS
+.SY "lctl pool_remove"
+.RB [ --nowait | -n ]
+.IB FSNAME . POOLNAME
+.I OSTNAME_INDEXED_LIST
+.YS
+.SH DESCRIPTION
+Remove one or more OSTs from the pool named
+.I POOLNAME
+in the filesystem named
+.IR FSNAME .
+There are several formats that the OSTs can be specified.
+Simplest is to just specify a list of
+.I OST_INDEX
+numbers or OST names. In this form the numbers must be proceeded by
+.B OST
+so that it is of the format
+.BI OST OST_INDEX .
+Where
+.I OST_INDEX
+is in hexadecimal format.
+It is also possible to specify an
+.I OST_RANGE
+expression of the form
+.BI OST[ START - END ]
+or
+.BI OST[ START - END / STEP ]
+that adds multiple OSTs with index numbers in the range from
+.I START
+to
+.I END
+(inclusive), optionally skipping every
+.I STEP
+index values.
+.SH OPTIONS
+.TP
+.BR -n ", " --nowait
+Do not wait and check if pool is updated on a client.
+This is useful when calling a lot of
+.RB \(dq "lctl pool_" *\(dq
+in a row. This avoids revoking the clients "CONFIG" lock for each
+command (by default clients retake their lock and update their configurations
+in a delay between 5-10s).
+.SH EXAMPLES
+Remove OSTs numbered 8, 9, and 10 from the
+.B testfs.local
+pool.
+.RS
+.EX
+.B # lctl pool_remove testfs.local OST0008 OST0009 OST000a
+OST lustre-OST0008_UUID removed from pool lustre.local
+OST lustre-OST0009_UUID removed from pool lustre.local
+OST lustre-OST000a_UUID removed from pool lustre.local
+or
+.B # lctl pool_remove testfs.local OST[8-a]
+OST lustre-OST0008_UUID removed from pool lustre.local
+OST lustre-OST0009_UUID removed from pool lustre.local
+OST lustre-OST000a_UUID removed from pool lustre.local
+.EE
+.RE
+.PP
+List of OSTs can be set with comma seperated values or a combined format
+.RS
+.EX
+.B # lctl pool_remove testfs.local OST[8,a]
+OST lustre-OST0008_UUID removed from pool lustre.local
+OST lustre-OST000a_UUID removed from pool lustre.local
+or
+.B # lctl pool_remove testfs.local OST[4-6,8,a]
+OST lustre-OST0004_UUID removed from pool lustre.local
+OST lustre-OST0005_UUID removed from pool lustre.local
+OST lustre-OST0006_UUID removed from pool lustre.local
+OST lustre-OST0008_UUID removed from pool lustre.local
+OST lustre-OST000a_UUID removed from pool lustre.local
+.EE
+.RE
+.SH AVAILABILITY
+.B lctl pool_remove
+is part of the
+.BR lustre (7)
+filesystem package since release 1.7.0
+.\" Added in commit 1.6.1-1578-g665e36b780
+.SH SEE ALSO
+.BR lfs-df (1),
+.BR lfs-find (1),
+.BR lfs-setstripe (1),
+.BR lustre (7),
+.BR lctl-pool_add (8),
+.BR lctl-pool_destroy (8),
+.BR lctl-pool_list (8),
+.BR lctl-pool_new (8)