LU-12837 doc: add lfs-changelog* manpages

This patch moves the documentation for "lfs changelog" and "lfs
changelog_clear" utilities from "lfs.1" to the following manpages:
- lfs-changelog.1
- lfs-changelog_clear.1

Signed-off-by: Etienne AUJAMES <eaujames@ddn.com>
Test-Parameters: trivial
Change-Id: I6db2e687e506a6116fe4755358a9abbd5509c3bb
Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/49209
Reviewed-by: Andreas Dilger <adilger@whamcloud.com>
Reviewed-by: Sebastien Buisson <sbuisson@ddn.com>
Reviewed-by: Olaf Faaland <faaland1@llnl.gov>
Reviewed-by: Oleg Drokin <green@whamcloud.com>
Tested-by: jenkins <devops@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>

diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am
index 33e2b12..d98de39 100644 (file)
--- a/lustre/doc/Makefile.am
+++ b/lustre/doc/Makefile.am
@@ -43,6 +43,8 @@ MANFILES =                                    \
        ldev.8                                  \
        ldev.conf.5                             \
        lfs.1                                   \
+       lfs-changelog.1                         \
+       lfs-changelog_clear.1                   \
        lfs-df.1                                \
        lfs-fid2path.1                          \
        lfs-find.1                              \

diff --git a/lustre/doc/lfs-changelog.1 b/lustre/doc/lfs-changelog.1
new file mode 100644 (file)
index 0000000..c2c7374
--- /dev/null
+++ b/lustre/doc/lfs-changelog.1
@@ -0,0 +1,105 @@
+.TH lfs-changelog 1 "2022-11-22" Lustre "user utilities"
+.SH NAME
+lfs changelog, lfs changelog_clear \- client utility to read and clear Lustre changelogs
+.SH SYNOPSIS
+.br
+.B lfs changelog \fR[\fB--follow\fR] \fIMDTNAME\fR [\fISTARTREC \fR[\fIENDREC\fR]]
+.br
+.B lfs changelog_clear \fIMDTNAME\fR \fIID\fR \fIENDREC\fR
+.br
+.SH DESCRIPTION
+.TP
+.B lfs changelog
+Show the metadata changes on an MDT.  Start point
+.I STARTREC
+and end point
+.I ENDREC
+points are optional.
+The
+.B --follow
+option will block waiting for new changes.
+.TP
+.B lfs changelog_clear
+Indicate that changelog records previous to
+.I ENDREC
+are no longer of
+interest to a particular consumer
+.I ID
+, potentially allowing the MDT to
+free up disk space. An
+.I ENDREC
+of 0 indicates the current last record.
+.PP
+Changelog consumers must be registered on the
+MDT node using:
+.br
+.BI "lctl --device " MDT_NAME " changelog_register"
+.SH RETURN VALUES
+.PP
+Return 0 on success or a errno value on failure.
+.SH ERRORS
+.TP 15
+.SM EINVAL
+One or more invalid arguments are given.
+.TP
+.SM ENOENT
+MDT's changelog char device or changelog user not found.
+.TP
+.SM EACCES
+Not enough permissions to open the changelog char device. By default, the device
+is only accessible to the root user.
+.TP
+.SM EIO
+Failed to read the changelog record on the MDT.
+.SH EXAMPLE
+.TP
+Register 2 changelog consumers on the MDT0000
+.br
+[root@mds]: lctl --device lustrefs-MDT0000 changelog_register
+.br
+lustrefs-MDT0000: Registered changelog userid 'cl1'
+.br
+[root@mds]: lctl --device lustrefs-MDT0000 changelog_register
+.br
+lustrefs-MDT0000: Registered changelog userid 'cl2'
+.TP
+Set changelog mask to generate changelogs for file creations
+.br
+[root@mds]: lctl set_param mdd.lustrefs-MDT0000.changelog_mask=CREAT
+.br
+mdd.lustrefs-MDT0000.changelog_mask=CREAT
+.TP
+Generate changelogs by creating some files on the fs
+.br
+[root@client]: touch /mnt/lustrefs/test{1..101}
+.TP
+Read changelog from number 0 to 99 on MDT0000
+.br
+[root@client]: lfs changelog lustrefs-MDT0000 0 99
+.nf
+0 01CREAT 11:03:54.129724442 2022.11.22 ...  p=[0x200000007:0x1:0x0] test1
+ ....
+99 01CREAT 11:03:54.129724465 2022.11.22 ...  p=[0x200000007:0x1:0x0] test100
+.fi
+.TP
+Indicate to MDT0000 that the changelogs lower than 100 are not needed for cl1
+.br
+[root@client]: lfs changelog_clear  lustrefs-MDT0000 cl1 99
+.br
+.TP
+Indicate to MDT0000 that the changelogs lower than 100 are not needed for cl2
+.br
+[root@client]: lfs changelog_clear  lustrefs-MDT0000 cl2 99
+.br
+.TP
+The changelogs from 0 to 99 are cleared by the MDT:
+[root@client]: lfs changelog lustrefs-MDT0000 0
+.br
+100 01CREAT 11:03:54.129724492 2022.11.22  ...  p=[0x200000007:0x1:0x0] test101
+.SH SEE ALSO
+.BR lfs (1),
+.BR llapi_changelog_clear (3)
+.BR llapi_changelog_recv (3)
+.BR llapi_changelog_start (3)
+.BR lctl-changelog_register (8)
+.BR lctl-changelog_deregister (8)

diff --git a/lustre/doc/lfs-changelog_clear.1 b/lustre/doc/lfs-changelog_clear.1
new file mode 100644 (file)
index 0000000..1e9fc73
--- /dev/null
+++ b/lustre/doc/lfs-changelog_clear.1
@@ -0,0 +1 @@
+.so man1/lfs-changelog.1

diff --git a/lustre/doc/lfs.1 b/lustre/doc/lfs.1
index d550166..2af3c37 100644 (file)
--- a/lustre/doc/lfs.1
+++ b/lustre/doc/lfs.1
@@ -149,15 +149,6 @@ as listed in the
 .B SEE ALSO
 section at the end.
 .TP
-.B changelog
-Show the metadata changes on an MDT.  Start and end points are optional.  The --follow option will block on new changes; this option is only valid when run direclty on the MDT node.
-.TP
-.B changelog_clear
-Indicate that changelog records previous to <endrec> are no longer of
-interest to a particular consumer <id>, potentially allowing the MDT to
-free up disk space. An <endrec> of 0 indicates the current last record.
-Changelog consumers must be registered on the MDT node using \fBlctl\fR.
-.TP
 .B check <mgts|mdts|osts|all> [path]
 Display the status of the MGTs, MDTs or OSTs (as specified in the command) or
 all the servers (MGTs, MDTs and OSTs). If \fBpath\fR is provided, display
@@ -254,12 +245,15 @@ Turn quotas of user and group off
 .SH NOTES
 The usage of \fBlfs find\fR, \fBlfs getstripe\fR, \fBlfs hsm_*\fR,
 \fBlfs setstripe\fR, \fBlfs migrate\fR, \fBlfs getdirstripe\fR,
-\fBlfs setdirstripe\fR, \fBlfs mkdir\fR, \fBlfs flushctx\fR
+\fBlfs setdirstripe\fR, \fBlfs mkdir\fR, \fBlfs flushctx\fR,
+\fBlfs changelog\fR, \fBlfs changelog_clear\fR
 and \fBlfs project\fR are explained in separate man pages.
 .SH AUTHOR
 The lfs command is part of the Lustre filesystem.
 .SH SEE ALSO
 .BR lctl (8),
+.BR lfs-changelog (1),
+.BR lfs-changelog_clear (1),
 .BR lfs-df (1),
 .BR lfs-fid2path (1),
 .BR lfs-find (1),
@@ -268,14 +262,14 @@ The lfs command is part of the Lustre filesystem.
 .BR lfs-getname (1),
 .BR lfs-getstripe (1),
 .BR lfs-hsm (1),
-.BR lfs-mkdir (1),
-.BR lfs-migrate (1),
 .BR lfs_migrate (1),
-.BR lfs-project (1),
+.BR lfs-migrate (1),
+.BR lfs-mkdir (1),
 .BR lfs-path2fid (1),
+.BR lfs-pcc (1),
+.BR lfs-project (1),
 .BR lfs-quota (1),
 .BR lfs-setdirstripe (1),
 .BR lfs-setquota (1),
 .BR lfs-setstripe (1),
-.BR lfs-pcc (1),
 .BR lustre (7)