From e477f21ed67bfb76aba2b7cede8f62cc0cbd2ff7 Mon Sep 17 00:00:00 2001 From: Kit Westneat Date: Tue, 20 Jan 2015 21:55:13 -0500 Subject: [PATCH] LU-4647 lctl: add nodemap man pages to lctl This patch adds separate man pages for the 8 lctl nodemap commands, and updates the lctl man page to point to them. Signed-off-by: Kit Westneat Change-Id: Ia1350471a2878a8f4057d66a91141ad8dd132bc2 Reviewed-on: http://review.whamcloud.com/13478 Tested-by: Jenkins Reviewed-by: Andreas Dilger Tested-by: Andreas Dilger Reviewed-by: Oleg Drokin --- lustre/doc/lctl-nodemap-activate.8 | 35 +++++++++++++++++++ lustre/doc/lctl-nodemap-add-idmap.8 | 47 +++++++++++++++++++++++++ lustre/doc/lctl-nodemap-add-range.8 | 64 ++++++++++++++++++++++++++++++++++ lustre/doc/lctl-nodemap-add.8 | 38 ++++++++++++++++++++ lustre/doc/lctl-nodemap-del-idmap.8 | 46 +++++++++++++++++++++++++ lustre/doc/lctl-nodemap-del-range.8 | 40 +++++++++++++++++++++ lustre/doc/lctl-nodemap-del.8 | 37 ++++++++++++++++++++ lustre/doc/lctl-nodemap-modify.8 | 69 +++++++++++++++++++++++++++++++++++++ lustre/doc/lctl.8 | 66 ++++++++++++++++++++++++++++++++++- lustre/doc/lnetctl.8 | 2 +- lustre/doc/lustre_rsync.8 | 2 +- lustre/doc/mount.lustre.8 | 2 +- 12 files changed, 444 insertions(+), 4 deletions(-) create mode 100644 lustre/doc/lctl-nodemap-activate.8 create mode 100644 lustre/doc/lctl-nodemap-add-idmap.8 create mode 100644 lustre/doc/lctl-nodemap-add-range.8 create mode 100644 lustre/doc/lctl-nodemap-add.8 create mode 100644 lustre/doc/lctl-nodemap-del-idmap.8 create mode 100644 lustre/doc/lctl-nodemap-del-range.8 create mode 100644 lustre/doc/lctl-nodemap-del.8 create mode 100644 lustre/doc/lctl-nodemap-modify.8 diff --git a/lustre/doc/lctl-nodemap-activate.8 b/lustre/doc/lctl-nodemap-activate.8 new file mode 100644 index 0000000..bbbd0fe --- /dev/null +++ b/lustre/doc/lctl-nodemap-activate.8 @@ -0,0 +1,35 @@ +.TH lctl-nodemap-activate 8 "2015 Jan 20" Lustre "configuration utilities" +.SH NAME +lctl-nodemap-activate \- Activate or deactivate the nodemap feature. +.SH SYNOPSIS +.br +.B lctl nodemap_activate "<0|1>" +.br +.SH DESCRIPTION +.B nodemap_activate +is used to activate or deactivate the nodemap feature. When nodemap is +active, all client operations are mapped based on rules created by the +administrator. + +.SH OPTIONS +Passing 0 disables the nodemap feature, while 1 activates the feature. + +.SH EXAMPLES +.nf +# lctl nodemap_activate 1 +.fi + +.SH AVAILABILITY +.B lctl +is part of the +.BR Lustre (7) +filesystem package. +.SH SEE ALSO +.BR lustre (7), +.BR lctl-nodemap-add (8), +.BR lctl-nodemap-del (8), +.BR lctl-nodemap-add-range (8), +.BR lctl-nodemap-del-range (8), +.BR lctl-nodemap-add-idmap (8), +.BR lctl-nodemap-del-idmap (8), +.BR lctl-nodemap-modify (8) diff --git a/lustre/doc/lctl-nodemap-add-idmap.8 b/lustre/doc/lctl-nodemap-add-idmap.8 new file mode 100644 index 0000000..a2b9f8c --- /dev/null +++ b/lustre/doc/lctl-nodemap-add-idmap.8 @@ -0,0 +1,47 @@ +.TH lctl-nodemap-add-idmap 8 "2015 Jan 20" Lustre "configuration utilities" +.SH NAME +lctl-nodemap-add-idmap \- Define a range of NIDs for a nodemap. + +.SH SYNOPSIS +.br +.B lctl nodemap_add_idmap <--name name> <--idtype {uid|gid}> +<--idmap clientid:fsid> +.br +.SH DESCRIPTION +.B nodemap_add_idmap adds an identity mapping to a nodemap. Clients that are +members of the given nodemap will have the identities of their users mapped +accordingly. + +.SH OPTIONS +.I name +is the name of the nodemap that this idmap should be added to. + +.I idtype +is either "uid" or "gid" depending on if it is a user ID or group ID that is to +be mapped. + +.I idmap +is the identity to map, and what it should be mapped to. The first digit is the +ID of the user or group as it is on the client, and the second number is the ID +that it should map to on the Lustre filesystem. + +.SH EXAMPLES +.nf +# lctl nodemap_add_idmap --name remotesite --idtype uid --idmap 2001:1001 +# lctl nodemap_add_idmap --name remotesite --idtype gid --idmap 2002:1002 +.fi + +.SH AVAILABILITY +.B lctl +is part of the +.BR Lustre (7) +filesystem package. +.SH SEE ALSO +.BR lustre (7), +.BR lctl-nodemap-activate (8), +.BR lctl-nodemap-add (8), +.BR lctl-nodemap-del (8), +.BR lctl-nodemap-add-range (8), +.BR lctl-nodemap-del-range (8), +.BR lctl-nodemap-del-idmap (8), +.BR lctl-nodemap-modify (8) diff --git a/lustre/doc/lctl-nodemap-add-range.8 b/lustre/doc/lctl-nodemap-add-range.8 new file mode 100644 index 0000000..ee2e26e --- /dev/null +++ b/lustre/doc/lctl-nodemap-add-range.8 @@ -0,0 +1,64 @@ +.TH lctl-nodemap-add-range 8 "2015 Jan 20" Lustre "configuration utilities" +.SH NAME +lctl-nodemap-add-range \- Define a range of NIDs for a nodemap. + +.SH SYNOPSIS +.br +.B lctl nodemap_add_range <--name name> <--range range> +.br +.SH DESCRIPTION +.B nodemap_add_range adds a range of NIDs to an existing nodemap. The NID range +cannot overlap with an existing NID range. Clients with NIDs that fall into the +new range will be moved into the given nodemap. + +.SH OPTIONS +.I name +is the name of the nodemap that this range should be added to. + +.I range +is the NID range that should be added to the nodemap. The syntax for the range +is the same as the rootsquash syntax, with the added constraint that the range +must be contiguous. + +.SH Formal LNET Range Definition + +.nf + :== [ ' ' ] + :== '@' + :== '*' | + | + + :== + ... + :== | + + :== '[' [ ',' ] ']' + :== | + '-' | + '-' '/' + :== | + :== "lo" | "tcp" | "o2ib" | "cib" | "openib" | "iib" | + "vib" | "ra" | "elan" | "gm" | "mx" | "ptl" + :== | +.fi + +.SH EXAMPLES +.nf +# lctl nodemap_add_range --name remotesite --range 192.168.1.[1-254]@tcp +# lctl nodemap_add_range --name otherremotesite --range 192.168.2.[1-254]@tcp +.fi + +.SH AVAILABILITY +.B lctl +is part of the +.BR Lustre (7) +filesystem package. +.SH SEE ALSO +.BR lustre (7), +.BR lctl-nodemap-activate (8), +.BR lctl-nodemap-add (8), +.BR lctl-nodemap-del (8), +.BR lctl-nodemap-del-range (8), +.BR lctl-nodemap-add-idmap (8), +.BR lctl-nodemap-del-idmap (8), +.BR lctl-nodemap-modify (8) diff --git a/lustre/doc/lctl-nodemap-add.8 b/lustre/doc/lctl-nodemap-add.8 new file mode 100644 index 0000000..58d2e37 --- /dev/null +++ b/lustre/doc/lctl-nodemap-add.8 @@ -0,0 +1,38 @@ +.TH lctl-nodemap-add 8 "2015 Jan 20" Lustre "configuration utilities" +.SH NAME +lctl-nodemap-add \- Add a new nodemap, to which NID ranges, identities, and +properties can be added. + +.SH SYNOPSIS +.br +.B lctl nodemap_add +.br +.SH DESCRIPTION +.B nodemap_add creates and names a new nodemap. The administrator can then add +NID ranges and identity mappings to the nodemap, as well as modify its +properties. + +.SH OPTIONS +.I name +is the name to give the new nodemap. It can be any string except "default". + +.SH EXAMPLES +.nf +# lctl nodemap_add remotesite +# lctl nodemap_add otherremotesite +.fi + +.SH AVAILABILITY +.B lctl +is part of the +.BR Lustre (7) +filesystem package. +.SH SEE ALSO +.BR lustre (7), +.BR lctl-nodemap-activate (8), +.BR lctl-nodemap-del (8), +.BR lctl-nodemap-add-range (8), +.BR lctl-nodemap-del-range (8), +.BR lctl-nodemap-add-idmap (8), +.BR lctl-nodemap-del-idmap (8), +.BR lctl-nodemap-modify (8) diff --git a/lustre/doc/lctl-nodemap-del-idmap.8 b/lustre/doc/lctl-nodemap-del-idmap.8 new file mode 100644 index 0000000..d5af221 --- /dev/null +++ b/lustre/doc/lctl-nodemap-del-idmap.8 @@ -0,0 +1,46 @@ +.TH lctl-nodemap-del-idmap 8 "2015 Jan 20" Lustre "configuration utilities" +.SH NAME +lctl-nodemap-del-idmap \- Delete an existing idmap from a nodemap. + +.SH SYNOPSIS +.br +.B lctl nodemap_del_idmap <--name name> <--idtype [uid|gid]> +<--idmap clientid:fsid> +.br +.SH DESCRIPTION +.B nodemap_del_idmap +deletes an idmap from a nodemap. Users or groups in the nodemap with that ID +will be squashed, if the trusted flag is not enabled. + +.SH OPTIONS +.I name +is the name of the nodemap that this idmap should be deleted from. + + +.I idtype +is either "uid" or "gid" depending on if it is a user or group mapping that is +to be removed. + +.I idmap +is the identity map to delete. + +.SH EXAMPLES +.nf +# lctl nodemap_del_idmap --name remotesite --idtype uid --idmap 2001:1001 +# lctl nodemap_del_idmap --name remotesite --idtype gid --idmap 2002:1002 +.fi + +.SH AVAILABILITY +.B lctl +is part of the +.BR Lustre (7) +filesystem package. +.SH SEE ALSO +.BR lustre (7), +.BR lctl-nodemap-activate (8), +.BR lctl-nodemap-add (8), +.BR lctl-nodemap-del (8), +.BR lctl-nodemap-add-range (8), +.BR lctl-nodemap-del-range (8), +.BR lctl-nodemap-add-idmap (8), +.BR lctl-nodemap-modify (8) diff --git a/lustre/doc/lctl-nodemap-del-range.8 b/lustre/doc/lctl-nodemap-del-range.8 new file mode 100644 index 0000000..1eec160 --- /dev/null +++ b/lustre/doc/lctl-nodemap-del-range.8 @@ -0,0 +1,40 @@ +.TH lctl-nodemap-del-range 8 "2015 Jan 20" Lustre "configuration utilities" +.SH NAME +lctl-nodemap-del-range \- Delete an existing NID range from a nodemap. + +.SH SYNOPSIS +.br +.B lctl nodemap_del_range "<--name name> <--range range>" +.br +.SH DESCRIPTION +.B nodemap_del_range +deletes a NID range from a nodemap. Clients will be moved to the default +nodemap. + +.SH OPTIONS +.I name +is the name of the nodemap that this range should be deleted from. + +.I range +is the NID range that should be deleted from the nodemap. + +.SH EXAMPLES +.nf +# lctl nodemap_del_range --name remotesite --range 192.168.1.[1-254]@tcp +# lctl nodemap_del_range --name otherremotesite --range 192.168.2.[1-254]@tcp +.fi + +.SH AVAILABILITY +.B lctl +is part of the +.BR Lustre (7) +filesystem package. +.SH SEE ALSO +.BR lustre (7), +.BR lctl-nodemap-activate (8), +.BR lctl-nodemap-add (8), +.BR lctl-nodemap-del (8), +.BR lctl-nodemap-add-range (8), +.BR lctl-nodemap-add-idmap (8), +.BR lctl-nodemap-del-idmap (8), +.BR lctl-nodemap-modify (8) diff --git a/lustre/doc/lctl-nodemap-del.8 b/lustre/doc/lctl-nodemap-del.8 new file mode 100644 index 0000000..fe6c44b --- /dev/null +++ b/lustre/doc/lctl-nodemap-del.8 @@ -0,0 +1,37 @@ +.TH lctl-nodemap-del 8 "2015 Jan 20" Lustre "configuration utilities" +.SH NAME +lctl-nodemap-del \- Delete an existing nodemap. + +.SH SYNOPSIS +.br +.B lctl nodemap_del "" +.br +.SH DESCRIPTION +.B nodemap_del deletes an existing nodemap. All of the associated mappings and +NID ranges will be removed as well, and existing clients will be moved to the +default nodemap. + +.SH OPTIONS +.I name +is the name of the nodemap to delete. The default nodemap cannot be deleted. + +.SH EXAMPLES +.nf +# lctl nodemap_del remotesite +# lctl nodemap_del otherremotesite +.fi + +.SH AVAILABILITY +.B lctl +is part of the +.BR Lustre (7) +filesystem package. +.SH SEE ALSO +.BR lustre (7), +.BR lctl-nodemap-activate (8), +.BR lctl-nodemap-add (8), +.BR lctl-nodemap-add-range (8), +.BR lctl-nodemap-del-range (8), +.BR lctl-nodemap-add-idmap (8), +.BR lctl-nodemap-del-idmap (8), +.BR lctl-nodemap-modify (8) diff --git a/lustre/doc/lctl-nodemap-modify.8 b/lustre/doc/lctl-nodemap-modify.8 new file mode 100644 index 0000000..8e01dea --- /dev/null +++ b/lustre/doc/lctl-nodemap-modify.8 @@ -0,0 +1,69 @@ +.TH lctl-nodemap-modify 8 "2015 Jan 20" Lustre "configuration utilities" +.SH NAME +lctl-nodemap-modify \- Modify a nodemap property. + +.SH SYNOPSIS +.br +.B lctl nodemap_modify <--name nodemap_name> <--property property_name> +<--value value> +.br +.SH DESCRIPTION +.B nodemap_modify +modifies a property of the given nodemap. + +.SH OPTIONS +.I nodemap_name +is the name of the nodemap to modify + + +.I property_name +is one of the following properties: +.PP +admin +.RS 4 +Defaults to off. If set to on, then root will NOT be squashed. By default, +the root user is mapped to the value of squash_uid. +.RE +.PP +trusted +.RS 4 +Defaults to off. If set to on, then user mapping will be disabled for all +non-root users. This means that the identities provided by the client will be +trusted to match the identities of the file system. By default, the client user +identities are mapped to the file system identities based on the nodemap rules. +.RE +.PP +squash_uid +.RS 4 +Defaults to 99. The user ID that unknown users (if not trusted) and root (if not admin) should be mapped to. +.RE +.PP +squash_gid +.RS 4 +Defaults to 99. The group ID that unknown groups (if not trusted) and root (if not admin) should be mapped to. +.RE + +.I value +is the value to set for the property. Should be 0 or 1 for admin and trusted. + +.SH EXAMPLES +.nf +# lctl nodemap_modify --name remotesite --property trusted --value 1 +# lctl nodemap_modify --name remotesite --property admin --value 1 +# lctl nodemap_modify --name otherremotesite --property squash_uid --value 101 +.fi + +.SH AVAILABILITY +.B lctl +is part of the +.BR Lustre (7) +filesystem package. +.SH SEE ALSO +.BR lustre (7), +.BR lctl-nodemap-activate (8), +.BR lctl-nodemap-add (8), +.BR lctl-nodemap-del (8), +.BR lctl-nodemap-add-range (8), +.BR lctl-nodemap-del-range (8), +.BR lctl-nodemap-add-idmap (8), +.BR lctl-nodemap-del-idmap (8), diff --git a/lustre/doc/lctl.8 b/lustre/doc/lctl.8 index 4cd0e09..ed79e6a 100644 --- a/lustre/doc/lctl.8 +++ b/lustre/doc/lctl.8 @@ -295,6 +295,70 @@ 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. .PP +.SS Nodemap +An identity mapping feature that facilitates mapping of client UIDs and GIDs to +local file system UIDs and GIDs, while maintaining POSIX ownership, permissions, +and quota. + +While the nodemap feature is enabled, all client file system access is subject +to the nodemap identity mapping policy, which consists of the 'default' catchall +nodemap, and any user-defined nodemaps. The 'default' nodemap maps all client +identities to 99:99 (nobody:nobody). Administrators can define nodemaps for a +range of client NIDs which map identities, and these nodemaps can be flagged as + 'trusted' so identities are accepted without translation, as well as flagged +as 'admin' meaning that root is not squashed for these nodes. + +Note: In the current phase of implementation, to use the nodemap functionality +you only need to enable and define nodemaps on the MDS. The MDSes must also be +in a nodemap with the admin and trusted flags set. To use quotas with nodemaps, +you must also use set_param to enable and define nodemaps on the OSS (matching +what is defined on the MDS). Nodemaps do not currently persist, unless you +define them with set_param and use the -P flag. Note that there is a hard limit +to the number of changes you can persist over the lifetime of the file system. + +See also: + +.PP +\fBlctl-nodemap-activate\fR(8) +.RS 4 +Activate/deactivate the nodemap feature. +.RE +.PP +\fBlctl-nodemap-add\fR(8) +.RS 4 +Add a new nodemap, to which NID ranges, identities, and properties can be added. +.RE +.PP +\fBlctl-nodemap-del\fR(8) +.RS 4 +Delete an existing nodemap. +.RE +.PP +\fBlctl-nodemap-add-range\fR(8) +.RS 4 +Define a range of NIDs for a nodemap. +.RE +.PP +\fBlctl-nodemap-del-range\fR(8) +.RS 4 +Delete an existing NID range from a nodemap. +.RE +.PP +\fBlctl-nodemap-add-idmap\fR(8) +.RS 4 +Add a UID or GID mapping to a nodemap. +.RE +.PP +\fBlctl-nodemap-del-idmap\fR(8) +.RS 4 +Delete an existing UID or GID mapping from a nodemap. +.RE +.PP +\fBlctl-nodemap-modify\fR(8) +.RS 4 +Modify a nodemap property. +.RE + .SS LFSCK An on-line Lustre consistency check and repair tool. .TP @@ -452,7 +516,7 @@ is part of the .BR Lustre (7) filesystem package. .SH SEE ALSO -.BR Lustre (7), +.BR lustre (7), .BR mkfs.lustre (8), .BR mount.lustre (8), .BR lctl (8), diff --git a/lustre/doc/lnetctl.8 b/lustre/doc/lnetctl.8 index 902d7cc..2dba6e2 100644 --- a/lustre/doc/lnetctl.8 +++ b/lustre/doc/lnetctl.8 @@ -622,5 +622,5 @@ peer: .br .SH SEE ALSO -.BR Lustre (7) +.BR lustre (7) diff --git a/lustre/doc/lustre_rsync.8 b/lustre/doc/lustre_rsync.8 index 8e90e4d..ffcb26f 100644 --- a/lustre/doc/lustre_rsync.8 +++ b/lustre/doc/lustre_rsync.8 @@ -176,6 +176,6 @@ $ lustre_rsync --source=/mnt/lustre \\ The lustre_rsync command is part of the Lustre filesystem. .SH SEE ALSO -.BR Lustre (7), +.BR lustre (7), .BR lctl (8), .BR lfs (1) diff --git a/lustre/doc/mount.lustre.8 b/lustre/doc/mount.lustre.8 index 4b613cb..c68a45d 100644 --- a/lustre/doc/mount.lustre.8 +++ b/lustre/doc/mount.lustre.8 @@ -156,7 +156,7 @@ is part of the .BR Lustre (7) filesystem package. .SH SEE ALSO -.BR Lustre (7), +.BR lustre (7), .BR mount (8), .BR mkfs.lustre (8), .BR tunefs.lustre (8), -- 1.8.3.1