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 <kit.westneat@gmail.com>
Change-Id: Ia1350471a2878a8f4057d66a91141ad8dd132bc2
Reviewed-on: http://review.whamcloud.com/13478
Tested-by: Jenkins
Reviewed-by: Andreas Dilger <andreas.dilger@intel.com>
Tested-by: Andreas Dilger <andreas.dilger@intel.com>
Reviewed-by: Oleg Drokin <oleg.drokin@intel.com>

diff --git a/lustre/doc/lctl-nodemap-activate.8 b/lustre/doc/lctl-nodemap-activate.8
new file mode 100644 (file)
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 (file)
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 (file)
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
+<nidlist>      :== <nidrange> [ ' ' <nidrange> ]
+<nidrange>     :== <addrrange> '@' <net>
+<addrrange>    :== '*' |
+                       <ipaddr_range> |
+                       <numaddr_range>
+<ipaddr_range> :==
+       <numaddr_range>.<numaddr_range>.<numaddr_range>.<numaddr_range>
+<numaddr_range>        :== <number> |
+                       <expr_list>
+<expr_list>    :== '[' <range_expr> [ ',' <range_expr>] ']'
+<range_expr>   :== <number> |
+                       <number> '-' <number> |
+                       <number> '-' <number> '/' <number>
+<net>          :== <netname> | <netname><number>
+<netname>      :== "lo" | "tcp" | "o2ib" | "cib" | "openib" | "iib" |
+                       "vib" | "ra" | "elan" | "gm" | "mx" | "ptl"
+<number>       :== <nonnegative decimal> | <hexadecimal>
+.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 (file)
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 <name>
+.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 (file)
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 (file)
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 (file)
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 "<name>"
+.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 (file)
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 (file)
--- 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
 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
 .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) 
 filesystem package.
 .SH SEE ALSO

-.BR Lustre (7),
+.BR lustre (7),

 .BR mkfs.lustre (8),
 .BR mount.lustre (8),
 .BR lctl (8),
 .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 (file)
--- a/lustre/doc/lnetctl.8
+++ b/lustre/doc/lnetctl.8
@@ -622,5 +622,5 @@ peer:
 .br
 
 .SH SEE ALSO
 .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 (file)
--- 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
 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)
 .BR lctl (8),
 .BR lfs (1)

diff --git a/lustre/doc/mount.lustre.8 b/lustre/doc/mount.lustre.8
index 4b613cb..c68a45d 100644 (file)
--- 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) 
 filesystem package.
 .SH SEE ALSO

-.BR Lustre (7),
+.BR lustre (7),

 .BR mount (8),
 .BR mkfs.lustre (8),
 .BR tunefs.lustre (8),
 .BR mount (8),
 .BR mkfs.lustre (8),
 .BR tunefs.lustre (8),