From 82e7ad348c77e5c164aa3e3155c9eb91872369d5 Mon Sep 17 00:00:00 2001 From: Etienne AUJAMES Date: Tue, 22 Nov 2022 13:39:25 +0100 Subject: [PATCH] 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 Test-Parameters: trivial Change-Id: I6db2e687e506a6116fe4755358a9abbd5509c3bb Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/49209 Reviewed-by: Andreas Dilger Reviewed-by: Sebastien Buisson Reviewed-by: Olaf Faaland Reviewed-by: Oleg Drokin Tested-by: jenkins Tested-by: Maloo --- lustre/doc/Makefile.am | 2 + lustre/doc/lfs-changelog.1 | 105 +++++++++++++++++++++++++++++++++++++++ lustre/doc/lfs-changelog_clear.1 | 1 + lustre/doc/lfs.1 | 22 +++----- 4 files changed, 116 insertions(+), 14 deletions(-) create mode 100644 lustre/doc/lfs-changelog.1 create mode 100644 lustre/doc/lfs-changelog_clear.1 diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am index 33e2b12..d98de39 100644 --- 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 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 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 --- 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 are no longer of -interest to a particular consumer , potentially allowing the MDT to -free up disk space. An of 0 indicates the current last record. -Changelog consumers must be registered on the MDT node using \fBlctl\fR. -.TP .B check [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) -- 1.8.3.1