'\" t
.\"     Title: pam_alias
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 05/21/2025
.\"    Manual: Linux-PAM Manual
.\"    Source: Linux-PAM Manual
.\"  Language: English
.\"
.TH "PAM_ALIAS" "8" "05/21/2025" "Linux-PAM Manual" "Linux\-PAM Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pam_alias \- map user names using an arbitrary file
.SH "SYNOPSIS"
.HP \w'\fBpam_alias\&.so\fR\ 'u
\fBpam_alias\&.so\fR file=\fI/path/filename\fR [nomatch=[fail|ignore]] [debug]
.SH "DESCRIPTION"
.PP
pam_alias is a PAM module which provides a way to map user names using an arbitrary file\&.
.PP
The module looks up the user name (PAM_USER) in the file specified by
\fBfile=\fR\fB\fIfilename\fR\fR\&. Every line in
filename
contains a pair of user names, separated by whitespace; pam_alias will map from the first user name to the second\&. The mapping is done by changing the PAM_USER item, which is then typically used by other PAM modules\&.
.PP
If a matching user name is found,
\fIPAM_IGNORE\fR
is returned; if no match could be found, the behavior depends on the
\fBnomatch\fR
option\&. If
\fBnomatch=\fR\fB\fIfail\fR\fR, pam_alias will return
\fIPAM_AUTH_ERR\fR\&. If
\fBnomatch=\fR\fB\fIignore\fR\fR
(the default), pam_alias will return
\fIPAM_IGNORE\fR
as in the successful case; however, no replacement will have taken place\&.
.PP
If a configuration error is encountered (for example, if
filename
can not be opened, its access permissions seem unsafe, or if invalid arguments are passed to pam_alias), then
\fIPAM_SERVICE_ERR\fR
will be returned\&.
.PP
No credentials are awarded by this module\&.
.SH "OPTIONS"
.PP
.PP
\fBfile=\fR\fB\fI/path/filename\fR\fR
.RS 4
File containing a pair of user names per line, separated by whitespace\&. The first name specifies the user name to be matched, the second name the user name will be replaced with\&. The file may not be world writable\&.
.RE
.PP
\fBnomatch=[fail|ignore]\fR
.RS 4
What to do if no user name could be matched\&. Default is
\fIignore\fR\&.
.RE
.PP
\fBdebug\fR
.RS 4
Log additional debugging information\&.
.RE
.SH "MODULE TYPES PROVIDED"
.PP
All module types (\fBauth\fR,
\fBaccount\fR,
\fBpassword\fR
and
\fBsession\fR) are provided\&.
.SH "RETURN VALUES"
.PP
.PP
PAM_AUTH_ERR
.RS 4
Authentication failure\&.
.RE
.PP
PAM_IGNORE
.RS 4
Mapping was successful, or
\fBnomatch=\fR\fB\fIignore\fR\fR\&.
.RE
.PP
PAM_SERVICE_ERR
.RS 4
Error in service module\&.
.RE
.SH "EXAMPLES"
.PP
pam_alias was written for use in multidomain setups that intend to use PAM as authentication provider\&. Specifically, pam_alias is used to map ejabberd jids to local unix users for authentication\&. On top of
/etc/pam\&.d/ejabberd:
.sp
.if n \{\
.RS 4
.\}
.nf
#
# map specific ejabberd jids to local users
#
auth    required       pam_alias\&.so file=/etc/secure/jidmap
      
.fi
.if n \{\
.RE
.\}
.sp

/etc/secure/jidmap:
.sp
.if n \{\
.RS 4
.\}
.nf
# lines starting with hash are ignored
foo@sub\&.example\&.org    loclfoo
      
.fi
.if n \{\
.RE
.\}
.sp
This will map an authentication request for
\fIfoo@sub\&.example\&.org\fR
to the user name
\fIloclfoo\fR, which will then in turn be used by the subsequent PAM modules\&.
.SH "SEE ALSO"
.PP
\fBpam.conf\fR(5),
\fBpam.d\fR(5),
\fBpam_listfile\fR(8),
\fBpam\fR(8)
.SH "AUTHOR"
.PP
pam_alias was written by Simon Schubert <2@0x2c\&.org>\&.
