Add man pages for the plugins and the configuration file

3 files changed, 183 insertions, 0 deletions

diff --git a/debian/libnss-mapuser.manpages b/debian/libnss-mapuser.manpages
new file mode 100644
index 0000000..37b163c
--- /dev/null
+++ b/debian/libnss-mapuser.manpages
@@ -0,0 +1,2 @@
+mapuser_nss.5
+nss_mapuser.8
diff --git a/mapuser_nss.5 b/mapuser_nss.5
new file mode 100644
index 0000000..a12c0f8
--- /dev/null
+++ b/mapuser_nss.5
@@ -0,0 +1,67 @@
+.TH mapuser_nss 5
+.\" Copyright 2017 Cumulus Networks, Inc.  All rights reserved.
+.SH NAME
+mapuser_nss.conf \- NSS mapuser configuration file
+.SH DESCRIPTION
+This is the configuration file for the NSS mapuser plugins.
+See the
+.BR mapuser_nss (8)
+manpage for more general information on the plugin.
+This configuration file controls debug settings, the local account used
+for mapping users, and which usernames (accounts) and uids are skipped.
+.PP
+.TP
+.I debug=NUMBER
+Output lookup debugging information via syslog(3).
+.TP
+.I exclude_users=user1,user2...
+Usernames (accounts) comma separate list.  This is used by mapname NSS plugin getpwuid()
+entry point.  The account to be looked up is checked against this list.   If a match is
+found, an immediate NOTFOUND status is returned.  This reduces overhead for the standard
+local user accounts.
+.TP
+.I mapped_user=NAME
+This is the local account which mapping uses as a template.   It must be a local
+account (found in
+.IR /etc/passwd ).
+When a uid or name match is found, this account information is read from
+.I /etc/passwd
+and used as a template for the matching account.  The
+.B pw_name
+field (user account name)
+is replaced with the original (login) name, and the original name is
+inserted at the beginning of the
+.B pw_gecos
+field.  The
+.B pw_dir
+(home directory)
+field replaces the last component of the directory path with the original login
+name.
+.IP
+When changing this field to a different name than the default, be sure the account exists in
+.IR /etc/passwd ,
+and that the account was created as disabled or locked (does not have a legal password, so
+the
+.I NAME
+account can not be used for logins.  When using
+.IR adduser (8)
+to create these accounts, use the
+.B --disabled-login
+argument to disable login for the account.
+.TP
+.I min_uid=NUMBER
+UID's passed to the mapuid NSS plugin getpwuid() entry point that are below this value
+cause an immediate NOTFOUND status to be returned.  This reduces
+overhead for the standard local user accounts.
+.SH "SEE ALSO"
+.BR adduser (8),
+.BR pam_radius_auth (8),
+.BR mapuser_nss (8),
+.BR nsswitch.conf (5),
+.BR getpwuid (3),
+.BR getpwnam (3),
+.SH FILES
+.I /etc/nss_mapuser.conf
+- mapuser NSS plugin configuration parameters
+.SH AUTHOR
+Dave Olson <olson@cumulusnetworks.com>
diff --git a/nss_mapuser.8 b/nss_mapuser.8
new file mode 100644
index 0000000..6d10516
--- /dev/null
+++ b/nss_mapuser.8
@@ -0,0 +1,114 @@
+.TH mapuser_nss 8
+.\" Copyright 2017 Cumulus Networks, Inc.  All rights reserved.
+.SH NAME
+libnss_mapname.so.2 \- NSS mapuser plugin
+.br
+libnss_mapuid.so.2 \- NSS mapuid plugin
+.SH DESCRIPTION
+These are the NSS mapuser plugins.
+See the
+.BR mapuser_nss (5)
+manpage for information on configuration.
+These plugins are intended to be used with protocols such as RADIUS that do not
+provide enough information to define a linux account (uid, gid, home directory).
+The traditional method was to add all RADIUS users to the local
+.I /etc/passwd
+file, or to enable them via other means such as LDAP.
+These plugins allow RADIUS users to login with no configuration other than the
+initial setup of the RADIUS client, and these plugins.
+.PP
+The plugins work by mapping user accounts to a named account in a configuration
+file, and using the named account as a template for the requested account.
+.PP
+The named account (default is
+.I radius_user)
+must be present in
+.IR /etc/passwd .
+The
+.B pw_name
+field (user account name)
+is replaced with the account name that is being looked up, and the original name is
+inserted at the beginning of the
+.B pw_gecos
+field.  The
+.B pw_dir
+(home directory)
+field replaces the last component of the directory path with the original login
+name.
+For example, if the name being looked up is
+.B daveolson
+and the
+named account in the configuration file is
+.BR radius_user ,
+and that entry in
+.I /etc/passwd
+is
+.IP
+.B radius_user:x:1017:1002:radius user,,,:/home/radius_user:/bin/bash
+.PP
+then the matching line returned by
+.I getent passwd daveolson
+would be
+.IP
+.B daveolson:x:1017:1002:daveolson mapped user:/home/daveolson:/bin/bash
+.PP
+The matching lookup on the uid will only be successful if
+.B daveolson
+is logged in, because it checks a flat file database that is created when
+the mapped user logs in.
+.PP
+When multiple users are logged in at the same time,
+the uid lookup will return the first matching account name.
+This is similar to having to multiple accounts in the
+.I /etc/passwd
+file with the same UID.
+.PP
+There are two separate plugins,
+.B libnss_mapname
+for user account names
+.RI ( getpwnam() (3)),
+and
+.B libnss_mapuid
+for uid
+.RI ( getpwuid() (3)),
+Two separate plugins are required.
+.PP
+The name lookup
+.B mapuser
+must be the last method used (last plugin on the
+.B passwd
+database), because it will always produce a successful lookup on
+any user account name, unless there are configuration or other errors.
+.PP
+The uid lookup
+.B mapuid
+must be the first method used (first plugin on the
+.B passwd
+database), because the uid will always match a local account from
+.IR /etc/passwd ,
+any user account name, unless there are configuration or other errors.
+.PP
+The flat file database is created using the
+.B pam_script
+plugin.  In addition to creating and deleting files at session start and
+end, the open script will also create the home directory using
+.IR mkhomedir_helper .
+.SH "SEE ALSO"
+.BR adduser (8),
+.BR mkhomedir_helper (8),
+.BR pam_radius_auth (8),
+.BR pam_script (8),
+.BR mapuser_nss (5),
+.BR nsswitch.conf (5),
+.BR getpwuid (3),
+.BR getpwnam (3),
+.BR getent (1).
+.SH FILES
+.I /etc/nss_mapuser.conf
+- mapuser NSS plugin configuration parameters.
+.br
+.I /run/mapuser/SESSION_NUMBER
+- the files containing the original uid and username for the account with linux session
+.IR SESSION_NUMBER .
+.SH AUTHOR
+Dave Olson <olson@cumulusnetworks.com>