.\" This file is part of PAM-Modules -*- nroff -*-
.\" Copyright (C) 2001-2014 Sergey Poznyakoff
.\"
.\" PAM-Modules is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" PAM-Modules is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with PAM-Modules.  If not, see <http://www.gnu.org/licenses/>.
.TH PAM_REGEX 8 "March 28, 2014" "PAM-MODULES" "Pam-Modules User Reference"
.SH NAME
pam_regex \- authentication using regular expressions
.SH SYNOPSIS
.nh
.na
\fBpam_regex\fR [\fBsense=\fISENSE\fR]\
 [\fBuser=\fINAME\fR]\
 [\fBregex=\fIEXPRESSION\fR]\
 [\fBbasic\fR|\fBextended\fR] [\fBcase\fR|\fBignore\-case\fR|\fBicase\fR]\
 [\fBtransform=\fIS-EXPR\fR]\
 [\fBdebug\fR[\fB=\fINUMBER\fR]]\
 [\fBwaitdebug\fR]\
 [\fBaudit\fR]
.ad
.hy
.SH DESCRIPTION
A general-purpose tool for authentication using regular expressions.
It can be used to control access depending on whether the user name
matches a given regular expression or to modify user name as per
a sed-like expression, so that subsequent modules see the modified
name.
.SH OPTIONS
.TP
\fBregex=\fIEXPRESSION\fR
Compare user name with \fIEXPRESSION\fR.  By default the argument is
treated as an extended regular expression with case-sensitive
matching.  

When this option is used, \fBpam_regex\fR allows only login
attempts with user names that match the given expression.  See the
\fBsensed\fR option to revert that behavior.
.TP
\fBsense=allow\fR|\fBdeny\fR
What to do if the user name matches the expression given by the
\fBregex\fR option.  The value \fBallow\fR (the default) instructs the
module to return \fBPAM_SUCCESS\fR, the \fBdeny\fR instructs it to
return \fBPAM_AUTH_ERR\fR.
.TP
\fBtransform=\fIS-EXPR\fR
Transform the user name using a sed-like expression.  The argument
should have the following form:
.RS
.EX
s/\fIregexp\fR/\fIrepl\fR/[\fIflags\fR]
.EE
.RE

See
.BR sed (1),
for a detailed description.  Supported \fIflags\fR are:
\fBg\fR, to apply the replacement to all matches, not
just the first, \fBi\fR, to use case-insensitive matching,
and \fBx\fR, which indicates that \fIregexp\fR is an extended
POSIX regular expression.  A decimal number in the \fIflags\fR field
indicates the ordinal number of the match to be replaced.  Using it
together with \fBg\fR results in undefined behavior.

Any delimiter can be used in lieue of the slash, the only requirement being
that it be used consistently throughout the expression. 
.TP
\fBbasic\fR
Use basic regular expressions.
.TP
\fBcase\fR
Use case-sensitive regular expressions (default).
.TP
\fBextended\fR
Use extended regular expressions (default).
.TP
\fBignore-case\fR or \fBicase\fR
Use case-insensitive regular expressions.
.TP
\fBuser=\fINAME\fR
Upon successful matching, set \fBPAM\fR user name to \fBSTRING\fR.
.TP
\fBdebug\fR[\fB=\fINUMBER\fR]
Set debugging level (0 <= \fINUMBER\fR <= 100).
.TP
\fBaudit\fR
Log full debugging information (equivalent to \fBdebug=100\fR).
.TP
\fBwaitdebug=\fIN\fR
Wait for \fIN\fR seconds before starting up.  This option is intended
to facilitate attaching to the module with
.BR gdb (1).
It is available only if the package was configured with
the \fB\-\-enable\-debug\fR option.
.SH MODULE TYPES PROVIDED
.B auth
.SH RETURN VALUES
.TP
.B PAM_SUCCESS
Successful return.
.TP
.B PAM_AUTH_ERR
Authentication failed.
.TP
.B PAM_AUTHINFO_UNAVAIL
The input information is not sufficient.
.SH EXAMPLES
.nr step 1 1
.IP \n[step].
Deny access to users with login name containig the \fB@\fR sign.
.PP
.EX
auth  required  pam_regex.so sense=deny regex=.*@.*
.EE
.IP \n+[step].
Convert the user name to lower case and remove anything starting from
the \fB@\fR character:
.PP
.EX
auth  required  pam_regex.so extended transform=s/.*/\\L&/g;s/@.*// 
.EE
.SH NOTE
This manpage is a short description of \fBpam_regex\fR.  For a detailed
discussion, including examples and usage recommendations, refer to the
\fBPAM-modules Manual\fR available in texinfo format.  If the \fBinfo\fR
reader and the tar documentation are properly installed on your
system, the command
.PP
.RS +4
.B info pam-modules
.RE
.PP
should give you access to the complete manual.
.PP
You can also view the manual using the info mode in
.BR emacs (1),
or find it in various formats online at
.PP
.RS +4
.B http://www.gnu.org.ua/software/pam-modules/manual
.RE
.PP
If any discrepancies occur between this manpage and the
\fBPAM-modules Manual\fR, the later shall be considered the authoritative
source.
.SH "SEE ALSO"
.BR pam.conf (5),
.BR pam.d (5),
.BR pam (8),
.BR regex (7),
.BR sed (1).
.SH AUTHORS
Sergey Poznyakoff <gray@gnu.org>
.SH "BUG REPORTS"
Report bugs to <bug\-pam\-modules@gnu.org.ua>.
.SH COPYRIGHT
Copyright \(co 2001-2014 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end: