path: root/nss_mapuser.8

.TH nss_mapuser 8
.\" Copyright 2017, 2018 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 nss_mapuser (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.
.P
These plugins allow RADIUS users to login with no configuration other than the
initial setup of the RADIUS client, and these plugins.
.P
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.
.P
The named accounts
must be present in
.IR /etc/passwd ,
and the groups set up correctly in
.IR /etc/group
for these plugins to work correctly.
.P
The default accounts are
.I radius_priv_user
for privileged logins with
the RADIUS VSA
.BR shell:priv-lvl=15 )
attribute, and
.I radius_user
for logins without that attribute, or with the privilege level 0-14.
The accounts are created when the debian package is installed.
.P
The mapname plugin also supplies NSS functions for the group file, in
order to map RADIUS logins into appropriate groups.   For this to work,
the two RADIUS accounts above are added to the
.BR sudo ,
.BR netshow ,
and
.B netedit
groups during the installation of the debian packge.  The privileged account
is made a member of the
.B sudo
and
.B netedit
groups, while the unprivileged account is made a member of the
.B netshow
group.   This can be verified after logging in by using the
.IR id (1),
or
.IR groups (1)
command to list the groups of which you are a member.
.P
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 dave
and the
named account in the configuration file is
.BR radius_user ,
and that entry in
.I /etc/passwd
is
.RS
.B radius_user:x:1017:1002:radius\~user:/home/radius_user:/bin/bash
.RE
then the matching line returned by
.I getent passwd dave
would be
.RS
.B dave:x:1017:1002:dave\~mapped\~user:/home/dave:/bin/bash
.RE
.PP
The matching lookup on the uid will only be successful if
.B dave
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
.RI ( getpwnam_r() (3)),
as well as
.RI ( getgrnam() (3),
.RI ( getpgram_r() (3)),
and
.RI ( getpgrent() (3)),
and
.B libnss_mapuid
for uid
.RI ( getpwuid() (3)
and
.RI ( getpwuid_r() (3)).
.P
Two separate plugins are required due to ordering requirements in
.IR /etc/nsswitch.conf .
.P
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 the name has has been excluded, or if
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 limited by the minimum uid configuration, or
if there are configuration or other errors.
.PP
The flat file database used by these plugins is created and removed by the
.B pam_radius_auth
plugin from the libpam-radius-auth package.
In addition to creating and deleting files at session start and end, the
.B pam_radius_auth
plugin will also create the home directory using the
.I mkhomedir_helper
program.
.SH "SEE ALSO"
.BR adduser (8),
.BR mkhomedir_helper (8),
.BR pam_radius_auth (8),
.BR nss_mapuser (5),
.BR nsswitch.conf (5),
.BR getpwuid (3),
.BR getpwnam (3),
.BR getent (1).
.SH FILES
.I /etc/nsswitch.conf
- configuration file for NSS plugins.  It is modified at package installation
.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>