LU-16901 utils: l_getidentity with nss module support

[fs/lustre-release.git] / lustre / doc / l_getidentity.8

diff --git a/lustre/doc/l_getidentity.8 b/lustre/doc/l_getidentity.8
index 662bbd5..2dfab20 100644 (file)
--- a/lustre/doc/l_getidentity.8
+++ b/lustre/doc/l_getidentity.8
@@ -15,6 +15,74 @@ This command is normally run directly by the Lustre MDS service
 and specifies the
 .I mdtname
 argument for the MDT that should be updated.
+.br
+.SS "The permissions file"
+.PP
+.I /etc/lustre/perm.conf
+supports a flat file database of permissions in the format
+.br
+ UID<space>NID<space>perm1,perm2,...,permN
+.br
+
+.br
+where
+.B perm
+is one of:
+.I [no]setuid
+.I [no]setgid
+.I [no]setgrp
+.I [no]rmtacl
+.I [no]rmtown
+.br
+ 
+.br
+.BR nss (5)
+modules can be enabled for auth handling by adding a 
+.B lookup 
+command with a list of nss modules to the first line of
+.BR perm.conf
+.br
+At the time of writing, known 
+.BR nss (5)
+modules include:
+.BR lustre ", " nss_files ", " ldap ", " nis ", " sss ", and" systemd
+additional modules may be documented in
+.BR nsswitch.conf (5)
+or installed separately.
+.br
+ 
+.br
+.BR nss (5)
+modules are searched in order. Once an entry is found in
+the module no further modules are searched.
+.br
+ 
+.br
+A special
+.B lustre
+module is used to enable lustre specific password and group
+auth by way of
+.B /etc/lustre/passwd
+and
+.B /etc/lustre/group
+.br
+ 
+.br
+For historical reasons
+.B files
+was originally used instead in place of
+.B lustre
+to enable auth by lustre files. At the time of writing
+.B files
+is still widely used where
+.B lustre
+is intended. This alias will be officially deprecated in a future release.
+As an alternative
+.B nss_files
+can be specified for the
+.BR nss (5)
+.B files
+module.
 .SH OPTIONS
 .TP
 .B -d
@@ -27,7 +95,51 @@ instead of updating Lustre.
 The identity upcall command can be specified via:
 .br
 .RI "lctl set_param mdt." mdtname .identity_upcall= path_to_upcall
+.br
+ 
+.br
+Enable lustre auth and ldap
+.br
+ [/etc/lustre/perm.conf]
+.br
+.B lookup lustre ldap
+.br
+ 
+.br
+ [/etc/lustre/passwd]
+.br
+  root:x:0:0:root:/root:/bin/bash
+.br
+  ...
+.br
+ [/etc/lustre/group]
+.br
+  root:x:0:root
+.br
+  ...
+.br
+Lustre passwd and group files use the same format as the system 
+.BR passwd (5)
+and
+.BR group (5)
+files.
+.br
+In this configuration root is local to the cluster and all other perms are delegated to ldap.
+.br
+.SH LIMITS
+A maximum of 8 nss modules can be enabled.
+.b4
 .SH FILES
 .RI /{proc,sys}/fs/lustre/mdt/ mdt-service /identity_upcall
+.br
+.RI /etc/lustre/perm.conf
+.br
+.RI /etc/lustre/passwd
+.br
+.RI /etc/lustre/group
 .SH SEE ALSO
+.BR nss (5),
+.BR passwd (5),
+.BR group (5)
+.br
 Lustre Programming Interfaces section of Lustre Operations Manual.