Old uncommitted changes: improve the configuration section, and add

descriptions for more modules.
author: Dag-Erling Smørgrav <des@FreeBSD.org> 2003-12-10 16:26:44 +0000
committer: Dag-Erling Smørgrav <des@FreeBSD.org> 2003-12-10 16:26:44 +0000
commit: ec88e446c21cb6848ddf697cb34ddf586ee14bba (patch)
tree: 62616433bacdcc9cbfa6b88e4d241c4eb9750194
parent: e8ae5c0bd2e8d482cd23679a871354752126bca5 (diff)
1 files changed, 106 insertions, 72 deletions
diff --git a/en_US.ISO8859-1/articles/pam/article.sgml b/en_US.ISO8859-1/articles/pam/article.sgml
index 9f81155977..4f9da9604c 100644
--- a/en_US.ISO8859-1/articles/pam/article.sgml
+++ b/en_US.ISO8859-1/articles/pam/article.sgml
@@ -389,11 +389,13 @@ sshd	password	required	pam_permit.so</programlisting>
       </section>
     </section>
 
+<!--
     <section id="pam-conventions">
       <title id="pam-conventions.title">Conventions</title>
 
-      <para><!--XXX-->This section has not yet been written.</para>
+      <para>This section has not yet been written.</para>
     </section>
+-->
   </section>
 
   <section id="pam-essentials">
@@ -750,87 +752,99 @@ sshd	password	required	pam_permit.so</programlisting>
   <section id="pam-config">
     <title id="pam-config.title">PAM Configuration</title>
 
-    <section id="pam-config-file-locations">
-      <title id="pam-config-file-locations.title">Location of
-	configuration files</title>
+    <section id="pam-config-file">
+      <title id="pam-config-file.title">PAM policy files</title>
+
+      <section id="pam-config-pam.conf">
+	<title id="pam-config-pam.conf.title">The
+	  <filename>/etc/pam.conf</filename> file</title>
 
-      <para>The traditional PAM configuration file is
-	<filename>/etc/pam.conf</filename>.  This file contains all
-	the PAM policies for your system.  Each line of the file
-	describes one step in a chain, as shown below:</para>
+	<para>The traditional PAM policy file is
+	  <filename>/etc/pam.conf</filename>.  This file contains all
+	  the PAM policies for your system.  Each line of the file
+	  describes one step in a chain, as shown below:</para>
 
 <programlisting>login   auth    required        pam_nologin.so  no_warn</programlisting>
 
-      <para>The fields are, in order: service name, facility name,
-	control flag, module name, and module arguments.  Any
-	additional fields are interpreted as additional module
-	arguments.</para>
+	<para>The fields are, in order: service name, facility name,
+	  control flag, module name, and module arguments.  Any
+	  additional fields are interpreted as additional module
+	  arguments.</para>
+
+	<para>A separate chain is constructed for each service /
+	  facility pair, so while the order in which lines for the
+	  same service and facility appear is significant, the order
+	  in which the individual services and facilities are listed
+	  is not.  The examples in the original PAM paper grouped
+	  configuration lines by facility, and the &solaris; stock
+	  <filename>pam.conf</filename> still does that, but FreeBSD's
+	  stock configuration groups configuration lines by service.
+	  Either way is fine; either way makes equal sense.</para>
+      </section>
+
+      <section id="pam-config-pam.d">
+	<title id="pam-config-pam.d.title">The
+	  <filename>/etc/pam.d</filename> directory</title>
 
-      <para>A separate chain is constructed for each service /
-	facility pair, so while the order in which lines for the same
-	service and facility appear is significant, the order in which
-	the individual services and facilities are listed is
-	not&mdash;except that entries for the <literal>other</literal>
-	service, which serves as a fall-back, should come last.  The
-	examples in the original PAM paper grouped configuration lines
-	by facility, and the &solaris; stock <filename>pam.conf</filename>
-	still does that, but FreeBSD's stock configuration groups
-	configuration lines by service.  Either way is fine; either
-	way makes equal sense.</para>
+	<para>OpenPAM and Linux-PAM support an alternate configuration
+	  mechanism, which is the preferred mechanism in FreeBSD.  In
+	  this scheme, each policy is contained in a separate file
+	  bearing the name of the service it applies to.  These files
+	  are stored in <filename>/etc/pam.d/</filename>.</para>
 
-      <para>OpenPAM and Linux-PAM offer an alternate configuration
-	mechanism, where policies are contained in separate files,
-	named for the service they apply to, in
-	<filename>/etc/pam.d/</filename>, with only four fields
-	instead of five&mdash;the service name field is omitted.  This
-	is the preferred mechanism in FreeBSD 5.x.  Note, however,
-	that if <filename>/etc/pam.conf</filename> exists, and
-	contains configuration statements for services which do not
-	have a specific policy in <filename>/etc/pam.d/</filename>, it
-	will be used as a fall-back for these services.</para>
+	<para>These per-service policy files have only four fields
+	  instead of <filename>pam.conf</filename>'s five: the service
+	  name field is omitted.  Thus, instead of the sample
+	  <filename>pam.conf</filename> line from the previous
+	  section, one would have the following line in
+	  <filename>/etc/pam.d/login</filename>:</para>
 
-      <para>The great advantage of <filename>/etc/pam.d/</filename>
-	over <filename>/etc/pam.conf</filename> is that it is possible
-	to use the same policy for multiple services by linking each
-	service name to a same policy file.  For instance, to use the
-	same policy for the <literal>su</literal> and
-	<literal>sudo</literal> services, one could do as
-	follows:</para>
+<programlisting>auth    required        pam_nologin.so  no_warn</programlisting>
+
+	<para>As a consequence of this simplified syntax, it is
+	  possible to use the same policy for multiple services by
+	  linking each service name to a same policy file.  For
+	  instance, to use the same policy for the
+	  <literal>su</literal> and <literal>sudo</literal> services,
+	  one could do as follows:</para>
 
 <screen>&prompt.root; <userinput>cd /etc/pam.d</userinput>
 &prompt.root; <userinput>ln -s su sudo</userinput></screen>
 
-      <para>This works because the service name is determined from the
-	file name rather than specified in the policy file, so the
-	same file can be used for multiple differently-named
-	services.</para>
+	<para>This works because the service name is determined from
+	  the file name rather than specified in the policy file, so
+	  the same file can be used for multiple differently-named
+	  services.</para>
+
+	<para>Since each service's policy is stored in a separate
+	  file, the <filename>pam.d</filename> mechanism also makes it
+	  very easy to install additional policies for third-party
+	  software packages.</para>
+      </section>
 
-      <para>One other advantage is that third-party software can
-	easily install policies for their services without the need to
-	edit <filename>/etc/pam.conf</filename>.  True to the FreeBSD
-	tradition, OpenPAM will even look for policy files in
-	<filename>/usr/local/etc/pam.d/</filename> if no configuration
-	for the requested service is present in
-	<filename>/etc/pam.d/</filename> or
-	<filename>/etc/pam.conf</filename>.</para>
+      <section id="pam-config-file-order">
+	<title id="pam-config-file-order.title">The policy search
+	  order</title>
 
-      <para>Finally, whichever configuration mechanism you choose, the
-	<quote>magic</quote> policy <literal>other</literal> is used
-	as a fall-back for any service that does not have its own
-	policy.</para>
+	<para>As we have seen above, PAM policies can be found in a
+	  number of places.  What happens if policies for the same
+	  service exist in multiple places?</para>
+
+	<para>It is essential to understand that PAM's configuration
+	  system is centered on chains.<!-- XXX --></para>
+
+      </section>
     </section>
 
     <section id="pam-config-breakdown">
       <title id="pam-config-breakdown.title">Breakdown of a
 	configuration line</title>
 
-      <para>As explained in the <link
-	linkend="pam-config-file-locations"
-	endterm="pam-config-file-locations.title"></link> section,
-	each line in <filename>/etc/pam.conf</filename> consists of
-	four or more fields: the service name, the facility name, the
-	control flag, the module name, and zero or more module
-	arguments.</para>
+      <para>As explained in the <link linkend="pam-config-file"
+	endterm="pam-config-file.title"></link> section, each line in
+	<filename>/etc/pam.conf</filename> consists of four or more
+	fields: the service name, the facility name, the control flag,
+	the module name, and zero or more module arguments.</para>
 
       <para>The service name is generally (though not always) the name
 	of the application the statement applies to.  If you are
@@ -996,12 +1010,6 @@ sshd	password	required	pam_permit.so</programlisting>
 	time which mounts the user's home directory.</para>
     </section>
 
-    <section id="pam-modules-ftp">
-      <title id="pam-modules-ftp.title">&man.pam.ftp.8;</title>
-
-      <para>The &man.pam.ftp.8; module</para>
-    </section>
-
     <section id="pam-modules-ftpusers">
       <title id="pam-modules-ftpusers.title">&man.pam.ftpusers.8;</title>
 
@@ -1019,6 +1027,17 @@ sshd	password	required	pam_permit.so</programlisting>
 	certain groups of users from a particular service.</para>
     </section>
 
+    <section id="pam-modules-guest">
+      <title id="pam-modules-guest.title">&man.pam.guest.8;</title>
+
+      <para>The &man.pam.guest.8; module allows guest logins using
+	fixed login names.  Various requirements can be placed on the
+	password, but the default behaviour is to allow any password
+	as long as the login name is that of a guest account.  The
+	&man.pam.guest.8; module can easily be used to implement
+	anonymous FTP logins.</para>
+    </section>
+
     <section id="pam-modules-krb5">
       <title id="pam-modules-krb5.title">&man.pam.krb5.8;</title>
 
@@ -1040,13 +1059,19 @@ sshd	password	required	pam_permit.so</programlisting>
     <section id="pam-modules-login-access">
       <title id="pam-modules-login-access.title">&man.pam.login.access.8;</title>
 
-      <para>The &man.pam.login.access.8; module</para>
+      <para>The &man.pam.login.access.8; module provides an
+	implementation of the account management primitive which
+	enforces the login restrictions specified in the
+	&man.login.access.5; table.</para>
     </section>
 
     <section id="pam-modules-nologin">
       <title id="pam-modules-nologin.title">&man.pam.nologin.8;</title>
 
-      <para>The &man.pam.nologin.8; module</para>
+      <para>The &man.pam.nologin.8; module refuses non-root logins
+	when <filename>/var/run/nologin</filename> exists.  This file
+	is normally created by &man.shutdown.8; when less than five
+	minutes remain until the scheduled shutdown time.</para>
     </section>
 
     <section id="pam-modules-opie">
@@ -1139,7 +1164,16 @@ sshd	password	required	pam_permit.so</programlisting>
     <section id="pam-modules-ssh">
       <title id="pam-modules-ssh.title">&man.pam.ssh.8;</title>
 
-      <para>The &man.pam.ssh.8; module</para>
+      <para>The &man.pam.ssh.8; module provides both authentication
+	and session services.  The authentication service allows users
+	who have passphrase-protected SSH secret keys in their
+	<filename>~/.ssh</filename> directory to authenticate
+	themselves by typing their passphrase.  The session service
+	starts &man.ssh-agent.1; and preloads it with the keys that
+	were decrypted in the authentication phase.  This feature is
+	particularly useful for local logins, whether in X (using
+	&man.xdm.1; or another PAM-aware X login manager) or at the
+	console.</para>
     </section>
 
     <section id="pam-modules-tacplus">
author	Dag-Erling Smørgrav <des@FreeBSD.org>	2003-12-10 16:26:44 +0000
committer	Dag-Erling Smørgrav <des@FreeBSD.org>	2003-12-10 16:26:44 +0000
commit	ec88e446c21cb6848ddf697cb34ddf586ee14bba (patch)
tree	62616433bacdcc9cbfa6b88e4d241c4eb9750194
parent	e8ae5c0bd2e8d482cd23679a871354752126bca5 (diff)