From 393885c027793d27ec948fd4fccb47aa530d2bf8 Mon Sep 17 00:00:00 2001 From: Mikhail Pershin Date: Thu, 17 Jun 2021 17:11:51 +0300 Subject: [PATCH] LU-13055 doc: update changelog manpages Add lctl-changelog_register.8 and lctl-changelog_deregister.8 manpages and update lctl.8 manpage to refer to them. Fixes: 15305c3c3fe7 ("LU-12214 build: fix build without lustre_utils") Test-Parameters: trivial Signed-off-by: Mikhail Pershin Change-Id: Ie41db630c72f61a884cd8000e0a4aeeb42ca60eb Reviewed-on: https://review.whamcloud.com/44022 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Andreas Dilger Reviewed-by: John L. Hammond Reviewed-by: Oleg Drokin --- lustre/doc/Makefile.am | 37 +++++++-------- lustre/doc/lctl-changelog_deregister.8 | 54 ++++++++++++++++++++++ lustre/doc/lctl-changelog_register.8 | 84 ++++++++++++++++++++++++++++++++++ lustre/doc/lctl.8 | 41 +++++++++-------- 4 files changed, 177 insertions(+), 39 deletions(-) create mode 100644 lustre/doc/lctl-changelog_deregister.8 create mode 100644 lustre/doc/lctl-changelog_register.8 diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am index 70f3837..8792e28 100644 --- a/lustre/doc/Makefile.am +++ b/lustre/doc/Makefile.am @@ -37,8 +37,8 @@ MANFILES = \ lctl-list_param.8 \ lctl-network.8 \ lctl-pcc.8 \ - lctl-pool_add.8 \ - lctl-pool_new.8 \ + lctl-pool_add.8 \ + lctl-pool_new.8 \ lctl-set_param.8 \ ldev.8 \ ldev.conf.5 \ @@ -50,7 +50,7 @@ MANFILES = \ lfs-getdirstripe.1 \ lfs-getname.1 \ lfs-getsom.1 \ - lfs-getstripe.1 \ + lfs-getstripe.1 \ lfs-heat.1 \ lfs-hsm.1 \ lfs-ladvise.1 \ @@ -67,18 +67,17 @@ MANFILES = \ lfs-mirror-write.1 \ lfs-mkdir.1 \ lfs-path2fid.1 \ - lfs-pcc.1 \ lfs-pcc-detach.1 \ + lfs-pcc.1 \ lfs-project.1 \ lfs-quota.1 \ lfs-rmfid.1 \ lfs-setdirstripe.1 \ lfs-setquota.1 \ lfs-setstripe.1 \ + lgss_sk.8 \ lhbadm.8 \ ll_decode_linkea.8 \ - llobdstat.8 \ - llog_reader.8 \ llsom_sync.8 \ llstat.8 \ lnetctl.8 \ @@ -87,6 +86,7 @@ MANFILES = \ lustre_routes_config.8 \ lustre_routes_conversion.8 \ lustre_rsync.8 \ + mount.lustre.8 \ nids.5 \ plot-llstat.8 \ routerstat.8 @@ -181,7 +181,11 @@ LIBMAN = \ llapi_unlink_foreign.3 SERVER_MANFILES = \ + l_getidentity.8 \ + l_getsepol.8 \ lctl-barrier.8 \ + lctl-changelog_deregister.8 \ + lctl-changelog_register.8 \ lctl-lcfg.8 \ lctl-lfsck-query.8 \ lctl-lfsck-start.8 \ @@ -191,12 +195,12 @@ SERVER_MANFILES = \ lctl-llog_info.8 \ lctl-llog_print.8 \ lctl-nodemap-activate.8 \ - lctl-nodemap-add.8 \ lctl-nodemap-add-idmap.8 \ lctl-nodemap-add-range.8 \ - lctl-nodemap-del.8 \ + lctl-nodemap-add.8 \ lctl-nodemap-del-idmap.8 \ lctl-nodemap-del-range.8 \ + lctl-nodemap-del.8 \ lctl-nodemap-modify.8 \ lctl-nodemap-set-fileset.8 \ lctl-nodemap-set-sepol.8 \ @@ -207,22 +211,13 @@ SERVER_MANFILES = \ lctl-snapshot-mount.8 \ lctl-snapshot-umount.8 \ ll_decode_filter_fid.8 \ + llobdstat.8 \ + llog_reader.8 \ llverdev.8 \ lshowmount.8 \ mkfs.lustre.8 \ - l_getidentity.8 \ - l_getsepol.8 \ - lgss_sk.8 \ - tunefs.lustre.8 \ - ll_decode_linkea.8 \ - llobdstat.8 \ - llog_reader.8 \ - llsom_sync.8 \ - llstat.8 \ - lnetctl.8 \ - lst.8 \ - mount.lustre.8 \ - mount.lustre_tgt.8 + mount.lustre_tgt.8 \ + tunefs.lustre.8 if MANPAGES man_MANS = $(LIBMAN) diff --git a/lustre/doc/lctl-changelog_deregister.8 b/lustre/doc/lctl-changelog_deregister.8 new file mode 100644 index 0000000..93bfadc --- /dev/null +++ b/lustre/doc/lctl-changelog_deregister.8 @@ -0,0 +1,54 @@ +.TH LCTL-CHANGELOG_DEREGISTER 8 "2021-06-18" Lustre "configuration utilities" +.SH NAME +lctl-changelog_deregister \- deregister existing changelog user. +.SH SYNOPSIS +.B lctl changelog_deregister +.RI [ ID |cl ID ] +.RB [ --help | -h ] +.RB [ --user | -u +.IR USERNAME ] +.br +.SH DESCRIPTION +This command is used to deregister an existing changelog user on selected +device. User can be deregistered by its \fBID\fR or specific \fBusername\fR +used on registration. +.br +.SH OPTIONS +.TP +.BR --help | -h +Output brief command usage help. +.TP +.BR --user | -u \ \fIUSERNAME +Deregistration by username. If changelog user specified unique name during +registration then it can be deregistered by \fBusername\fR instead of \fBID\fR. +.SH EXAMPLES +.TP +Deregister changelog user on device \fBtestfs-MDT0000\fR by 'cl<\fBID\fR>': +.br +# lctl --device testfs-MDT0000 changelog_deregister cl1 +.br +testfs-MDT0000: Deregistered changelog user #1 +.TP +Deregister changelog user by pure \fBID\fR: +.br +# lctl --device testfs-MDT0000 changelog_deregister 1 +.br +testfs-MDT0000: Deregistered changelog user #1 +.TP +Deregister changelog user by its specific name \fBtestname\fR: +.br +# lctl --device testfs-MDT0000 changelog_deregister -u testname +.br +testfs-MDT0000: Deregistered changelog user #1 + +.SH AVAILABILITY +.B lctl changelog_deregister +is a subcommand of +.BR lctl (8) +and is distributed as part of the +.BR lustre (7) +filesystem package. +.SH SEE ALSO +.BR lctl (8), +.BR lctl-changelog_register (8) + diff --git a/lustre/doc/lctl-changelog_register.8 b/lustre/doc/lctl-changelog_register.8 new file mode 100644 index 0000000..52e9efc --- /dev/null +++ b/lustre/doc/lctl-changelog_register.8 @@ -0,0 +1,84 @@ +.TH LCTL-CHANGELOG_REGISTER 8 "2021-06-18" Lustre "configuration utilities" +.SH NAME +lctl-changelog_register \- register a new changelog user for particular device. +.SH SYNOPSIS +.B lctl changelog_register +.RB [ --help | -h ] +.RB [ --mask | -m +.IR MASK ] +.RB [ --nameonly | -n ] +.RB [ --user | -u +.IR USERNAME ] +.br +.SH DESCRIPTION +This command is used to register a new changelog user on selected device. New +user may set specific \fImask\fR and/or specific unique \fIusername\fR. +Changelog entries will not be purged beyond any registered users' set point. +See also \fBlfs changelog_clear\fR. +.br +.SH OPTIONS +.TP +.BR --help | -h +Output brief command usage help. +.TP +.BR --mask | -m\ \fI MASK +Sets per-user changelog \fImask\fR. Mask is specified as set of keywords +in form [+|-]\fImask1\fR[<,|+|->\fImask2\fR...]. Masks are separated by comma +or '+' to indicate a mask to be added and by '-' to indicate mask to be +removed. If mask list is started with '+' or '-' then masks are relative +to the default changelog mask, otherwise mask is absolute. Possible mask +keywords are: +.BR mark ", " creat ", " mkdir ", " hlink ", " slink ", " mknod ", " +.BR unlnk ", " rmdir ", " renme ", " rnmto ", " open ", " close ", " +.BR lyout ", " trunc ", " sattr ", " xattr ", " hsm ", " mtime ", " +.BR ctime ", " atime ", " migrt ", " flrw ", " resync ", " gxatr ", " nopen . +The default changelog mask consists of all masks excluding: +``atime, open, gxatr, nopen''. Both uppercase and lowercase are accepted for +keywords. +.TP +.BR --nameonly | -n +The output format modifier. If set then command outputs just changelog user +name in format 'cl<\fIID\fR>[-<\fIusername\fR>]. Where \fIID\fR stands for +assigned changelog user \fBID\fR. +.TP +.BR --user | -u \ \fI USERNAME +Specific username assigment. Unique name can be assigned to a new changelog +user. Name must start with a letter and consist of letters, digits, '-' and +\'_' symbols with total length limited by 15 symbols. +.SH EXAMPLES +.TP +Simple changelog user register on device \fBtestfs-MDT0000\fR: +.br +# lctl --device testfs-MDT0000 changelog_register +.br +testfs-MDT0000: Registered changelog userid 'cl1' +.TP +Register changelog user with specific name \fBtestname\fR: +.br +# lctl --device testfs-MDT0000 changelog_register -u testname +.br +lustre-MDT0000: Registered changelog userid 'cl1-testname' +.TP +Register changelog user with specific mask: +.br +# lctl --device testfs-MDT0000 changelog_register -m +open,atime,-hlink +.br +lustre-MDT0000: Registered changelog userid 'cl1' +.TP +Register changelog user with terse output: +.br +# lctl --device testfs-MDT0000 changelog_register -n +.br +cl1 + +.SH AVAILABILITY +.B lctl changelog_register +is a subcommand of +.BR lctl (8) +and is distributed as part of the +.BR lustre (7) +filesystem package. +.SH SEE ALSO +.BR lctl (8), +.BR lctl-changelog_deregister (8) + diff --git a/lustre/doc/lctl.8 b/lustre/doc/lctl.8 index 0801934..64d147c 100644 --- a/lustre/doc/lctl.8 +++ b/lustre/doc/lctl.8 @@ -160,18 +160,21 @@ communication with the failed OST. Abort the recovery process on a restarting MDT or OST device .PP .SS Changelogs -.TP -.BI changelog_register " [-n]" -Register a new changelog user for a particular device. Changelog entries -will not be purged beyond any registered users' set point. (See lfs changelog_clear.) -.br -.B -n -Print only the ID of the newly registered user. -.TP -.BI changelog_deregister " " -Unregister an existing changelog user. If the user's "clear" record number -is the minimum for the device, changelog records will be purged until the -next minimum. +Changelog user can be registered and deregistered on particular device. +Changelog starts logging when any user is registered. + +For more details see: + +.PP +\fBlctl-changelog_register\fR(8) +.RS 4 +Register a new changelog user on specified MDT device with specified parameters. +.RE +.PP +\fBlctl-changelog_deregister\fR(8) +.RS 4 +Deregister an existing changelog user on the specified MDT. + .PP .SS Nodemap An identity mapping feature that facilitates mapping of client UIDs and GIDs to @@ -432,13 +435,14 @@ is part of the .BR lustre (7) filesystem package. .SH SEE ALSO +.BR lfs (1) .BR lustre (7), -.BR mkfs.lustre (8), -.BR mount.lustre (8), .BR lctl (8), .BR lctl-barrier (8), -.BR lctl-lcfg (8), +.BR lctl-changelog_deregister (8), +.BR lctl-changelog_register (8), .BR lctl-get_param (8), +.BR lctl-lcfg (8), .BR lctl-lfsck-start (8), .BR lctl-lfsck-stop (8), .BR lctl-lfsck-query (8), @@ -455,12 +459,13 @@ filesystem package. .BR lctl-llog_print (8), .BR lctl-network (8), .BR lctl-nodemap-activate (8), +.BR lctl-nodemap-add (8), .BR lctl-nodemap-add-idmap (8), .BR lctl-nodemap-add-range (8), -.BR lctl-nodemap-add (8), +.BR lctl-nodemap-del (8), .BR lctl-nodemap-del-idmap (8), .BR lctl-nodemap-del-range (8), -.BR lctl-nodemap-del (8), .BR lctl-nodemap-modify (8), .BR lctl-pcc (8), -.BR lfs (1) +.BR mkfs.lustre (8), +.BR mount.lustre (8), -- 1.8.3.1