$Id$
- Copyright (c) Andrew G. Morgan 1996-2001. All rights reserved.
+ Copyright (c) Andrew G. Morgan 1996-2002. All rights reserved.
Redistribution and use in source (sgml) and binary (derived) forms,
with or without modification, are permitted provided that the
<title>The Linux-PAM System Administrators' Guide
<author>Andrew G. Morgan, <tt>morgan@kernel.org</tt>
-<date>DRAFT v0.76 2001/12/08
+<date>DRAFT v0.77 2002/07/10
<abstract>
This manual documents what a system-administrator needs to know about
the <bf>Linux-PAM</bf> library. It covers the correct syntax of the
here for locating these files are those of the relevant RFC (RFC-86.0,
see <ref id="see-also-sec" name="bibliography">). If you are using a
distribution of Linux (or some other operating system) that supports
-PAM but chooses to distribute these files in a diferent way (Red Hat
-is one such distribution), you should be careful when copying examples
-directly from the text.
+PAM but chooses to distribute these files in a diferent way you should
+be careful when copying examples directly from the text.
<p>
As an example of the above, where it is explicit, the text assumes
be used, including RADIUS, NIS, NCP (which means that Novell
password databases can be used).
- o pppd has a PAMified version (available from RedHat) Now it is
+ o pppd has a PAMified version (available from Red Hat) Now it is
possible to use a series of databases to authenticate ppp users.
In addition to the normal Linux-based password databases (such
as /etc/passwd and /etc/shadow), you can use PAM modules to
the following form:
<tscreen>
<verb>
-service-name module-type control-flag module-path arguments
+service-name module-type control-flag module-path args
</verb>
</tscreen>
Below, we explain the meaning of each of these tokens. The second (and
The simpler (and historical) syntax for the control-flag is a single
keyword defined to indicate the severity of concern associated with
the success or failure of a specific module. There are four such
-keywords: <tt/required/, <tt/requisite/, <tt/sufficient/ and
-<tt/optional/.
+keywords: <tt/required/, <tt/requisite/, <tt/sufficient/,
+<tt/optional/ and <tt/include/.
<p>
The Linux-PAM library interprets these keywords in the following
of this latter case, is when the other modules return something like
<tt/PAM_IGNORE/.
+<item> <tt/include/; this tells PAM to include all lines of given type
+from the configuration file specified as an argument to this control.
+The whole idea is to create few "systemwide" pam configs and include
+parts of them in application pam configs.
+
+
</itemize>
<p>
start again with the next stacked module.
</itemize>
+<p>
+Each of the four keywords: <tt/required/; <tt/requisite/;
+<tt/sufficient/; and <tt/optional/, have an equivalent expression in
+terms of the <tt/[...]/ syntax. They are as follows:
+<itemize>
+<item><tt/required/ is equivalent to
+<tt/[success=ok new_authtok_reqd=ok ignore=ignore default=bad]/
+<item><tt/requisite/ is equivalent to
+<tt/[success=ok new_authtok_reqd=ok ignore=ignore default=die]/
+<item><tt/sufficient/ is equivalent to
+<tt/[success=done new_authtok_reqd=done default=ignore]/
+<item><tt/optional/ is equivalent to
+<tt/[success=ok new_authtok_reqd=ok default=ignore]/
+</itemize>
+
<p>
Just to get a feel for the power of this new syntax, here is a taste
of what you can do with it. With <bf/Linux-PAM-0.63/, the notion of
error to <tt/syslog(3)/. For a list of <em/generic/ options see the
next section.
+Note, if you wish to include spaces in an argument, you should
+surround that argument with square brackets. For example:
+<tscreen>
+<verb>
+squid auth required pam_mysql.so user=passwd_query passwd=mada \
+ db=eminence [query=select user_name from internet_service where \
+ user_name='%u' and password=PASSWORD('%p') and \
+ service='web_proxy']
+</verb>
+</tscreen>
+Note, when using this convention, you can include `<tt/[/' characters
+inside the string, and if you wish to include a `<tt/]/' character
+inside the string that will survive the argument parsing, you should
+use `<tt/\[/'. In other words:
+<tscreen>
+<verb>
+[..[..\]..] --> ..[..]..
+</verb>
+</tscreen>
+
</descrip>
<p>
configuration but not both. That is to say, if there is a
<tt>/etc/pam.d/</tt> directory then libpam only uses the files
contained in this directory. However, in the absence of the
-<tt>/etc/pam.d/</tt> directory the <tt>/etc/pam.conf</tt> file is
-used. The other mode (and the one currently supported by Red Hat 4.2
-and higher) is to use both <tt>/etc/pam.d/</tt> and
+<tt>/etc/pam.d/</tt> directory the <tt>/etc/pam.conf</tt> file is used
+(this is likely to be the mode your preferred distribution uses). The
+other mode is to use both <tt>/etc/pam.d/</tt> and
<tt>/etc/pam.conf</tt> in sequence. In this mode, entries in
<tt>/etc/pam.d/</tt> override those of <tt>/etc/pam.conf</tt>.
going, hopefully after you've tested it first on a machine
you don't care about screwing up. :/
-Some pointers (to make everything "right" with Red Hat...):
-
- Install the newest pam, pamconfig, and pwdb from the
- redhat current directory, and do it all on the same
- command line with rpm...
-
- rpm -Uvh [maybe --force too] pam-* pamconfig-* pwdb-*
-
- Then make sure you install (or reinstall) the newest
- version of libc, util-linux, wuftp, and NetKit. For
- kicks you might try installing the newest versions of
- the affected x apps, like xlock, but I haven't gotten
- those to work at all yet.
-
</verb>
<sect1>Avoid having a weak `other' configuration
<sect>Copyright information for this document
<p>
-Copyright (c) Andrew G. Morgan 1996-9. All rights reserved.
+Copyright (c) Andrew G. Morgan 1996-2002. All rights reserved.
<newline>
-Email: <tt><morgan@linux.kernel.org></tt>
+Email: <tt><morgan@kernel.org></tt>
<p>
Redistribution and use in source and binary forms, with or without