aboutsummaryrefslogtreecommitdiff
path: root/doc/pam_regex.8
diff options
context:
space:
mode:
Diffstat (limited to 'doc/pam_regex.8')
-rw-r--r--doc/pam_regex.8181
1 files changed, 181 insertions, 0 deletions
diff --git a/doc/pam_regex.8 b/doc/pam_regex.8
new file mode 100644
index 0000000..6033feb
--- /dev/null
+++ b/doc/pam_regex.8
@@ -0,0 +1,181 @@
+.\" 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 auditing information.
+.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:
+

Return to:

Send suggestions and report system problems to the System administrator.