Updating TOSHARG files

(This used to be commit 2ada75f02f4ba7de548a56a14f1bb0281029e063)

1 files changed, 104 insertions, 30 deletions

diff --git a/docs/Samba3-HOWTO/TOSHARG-PAM.xml b/docs/Samba3-HOWTO/TOSHARG-PAM.xml
index dc405cd1a9..024a2f3ef8 100644
--- a/docs/Samba3-HOWTO/TOSHARG-PAM.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-PAM.xml
@@ -15,6 +15,10 @@
 <title>PAM-Based Distributed Authentication</title>
 
 <para>
+<indexterm><primary>PAM-enabled</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>Winbind-based authentication</primary></indexterm>
 This chapter should help you to deploy Winbind-based authentication on any PAM-enabled
 UNIX/Linux system. Winbind can be used to enable user-level application access authentication
 from any MS Windows NT domain, MS Windows 200x Active Directory-based
@@ -23,6 +27,8 @@ controls that are appropriate to your Samba configuration.
 </para>
 
 <para>
+<indexterm><primary>PAM management</primary></indexterm>
+<indexterm><primary>pam_smbpass.so</primary></indexterm>
 In addition to knowing how to configure Winbind into PAM, you will learn generic PAM management
 possibilities and in particular how to deploy tools like <filename>pam_smbpass.so</filename> to your advantage.
 </para>
@@ -36,6 +42,14 @@ Please refer to <link linkend="winbind">Winbind: Use of Domain Accounts</link>,
 <title>Features and Benefits</title>
 
 <para>
+<indexterm><primary>Sun Solaris</primary></indexterm>
+<indexterm><primary>xxxxBSD</primary></indexterm>
+<indexterm><primary>Linux</primary></indexterm>
+<indexterm><primary>Pluggable Authentication Modules</primary><see>PAM</see></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>login</primary></indexterm>
+<indexterm><primary>passwd</primary></indexterm>
+<indexterm><primary>chown</primary></indexterm>
 A number of UNIX systems (e.g., Sun Solaris), as well as the xxxxBSD family and Linux,
 now utilize the Pluggable Authentication Modules (PAM) facility to provide all authentication, 
 authorization, and resource control services. Prior to the introduction of PAM, a decision
@@ -46,6 +60,10 @@ Such a choice would involve provision of alternatives to programs such as <comma
 </para>
 
 <para>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>/etc/pam.conf</primary></indexterm>
+<indexterm><primary>Solaris</primary></indexterm>
+<indexterm><primary>/etc/pam.d</primary></indexterm>
 PAM provides a mechanism that disconnects these security programs from the underlying
 authentication/authorization infrastructure. PAM is configured by making appropriate modifications to one file,
 <filename>/etc/pam.conf</filename> (Solaris), or by editing individual control files that are
@@ -53,6 +71,8 @@ located in <filename>/etc/pam.d</filename>.
 </para>
 
 <para>
+<indexterm><primary>PAM-enabled</primary></indexterm>
+<indexterm><primary>dynamically loadable library modules</primary></indexterm>
 On PAM-enabled UNIX/Linux systems, it is an easy matter to configure the system to use any
 authentication backend so long as the appropriate dynamically loadable library modules
 are available for it. The backend may be local to the system or may be centralized on a
@@ -66,14 +86,25 @@ PAM support modules are available for:
 <variablelist>
 	<varlistentry><term><filename>/etc/passwd</filename></term><listitem>
 		<para>
-		There are several PAM modules that interact with this standard UNIX user
-		database. The most common are called <filename>pam_unix.so</filename>, <filename>pam_unix2.so</filename>, <filename>pam_pwdb.so</filename>
-		and <filename>pam_userdb.so</filename>.
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>PAM modules</primary></indexterm>
+<indexterm><primary>pam_unix.so</primary></indexterm>
+<indexterm><primary>pam_unix2.so</primary></indexterm>
+<indexterm><primary>pam_pwdb.so</primary></indexterm>
+<indexterm><primary>pam_userdb.so</primary></indexterm>
+		There are several PAM modules that interact with this standard UNIX user database. The most common are called
+		<filename>pam_unix.so</filename>, <filename>pam_unix2.so</filename>, <filename>pam_pwdb.so</filename> and
+		<filename>pam_userdb.so</filename>.
 		</para>
 	</listitem></varlistentry>
 
 	<varlistentry><term>Kerberos</term><listitem>
 		<para>
+<indexterm><primary>pam_krb5.so</primary></indexterm>
+<indexterm><primary>Kerberos</primary></indexterm>
+<indexterm><primary>Heimdal</primary></indexterm>
+<indexterm><primary>MIT Kerberos</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
 		The <filename>pam_krb5.so</filename> module allows the use of any Kerberos-compliant server.
 		This tool is used to access MIT Kerberos, Heimdal Kerberos, and potentially
 		Microsoft Active Directory (if enabled).
@@ -82,6 +113,12 @@ PAM support modules are available for:
 
 	<varlistentry><term>LDAP</term><listitem>
 		<para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>pam_ldap.so</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>Sun ONE iDentity server</primary></indexterm>
+<indexterm><primary>Novell eDirectory server</primary></indexterm>
+<indexterm><primary>Microsoft Active Directory</primary></indexterm>
 		The <filename>pam_ldap.so</filename> module allows the use of any LDAP v2- or v3-compatible backend
 		server. Commonly used LDAP backend servers include OpenLDAP v2.0 and v2.1,
 		Sun ONE iDentity server, Novell eDirectory server, and Microsoft Active Directory.
@@ -90,6 +127,10 @@ PAM support modules are available for:
 
 	<varlistentry><term>NetWare Bindery</term><listitem>
 		<para>
+<indexterm><primary>NetWare Bindery</primary></indexterm>
+<indexterm><primary>pam_ncp_auth.so</primary></indexterm>
+<indexterm><primary>bindery-enabled</primary></indexterm>
+<indexterm><primary>NetWare Core Protocol-based server</primary></indexterm>
 		The <filename>pam_ncp_auth.so</filename> module allows authentication off any bindery-enabled
 		NetWare Core Protocol-based server.
 		</para>
@@ -97,6 +138,9 @@ PAM support modules are available for:
 
 	<varlistentry><term>SMB Password</term><listitem>
 		<para>
+<indexterm><primary>SMB Password</primary></indexterm>
+<indexterm><primary>pam_smbpass.so</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
 		This module, called <filename>pam_smbpass.so</filename>, allows user authentication of
 		the passdb backend that is configured in the Samba &smb.conf; file.
 		</para>
@@ -104,6 +148,8 @@ PAM support modules are available for:
 
 	<varlistentry><term>SMB Server</term><listitem>
 		<para>
+<indexterm><primary>SMB Server</primary></indexterm>
+<indexterm><primary>pam_smb_auth.so</primary></indexterm>
 		The <filename>pam_smb_auth.so</filename> module is the original MS Windows networking authentication
 		tool. This module has been somewhat outdated by the Winbind module.
 		</para>
@@ -111,6 +157,10 @@ PAM support modules are available for:
 
 	<varlistentry><term>Winbind</term><listitem>
 		<para>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>pam_winbind.so</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
 		The <filename>pam_winbind.so</filename> module allows Samba to obtain authentication from any
 		MS Windows domain controller. It can just as easily be used to authenticate
 		users for access to any PAM-enabled application.
@@ -119,6 +169,7 @@ PAM support modules are available for:
 
 	<varlistentry><term>RADIUS</term><listitem>
 		<para>
+<indexterm><primary>Remote Access Dial-In User Service</primary><see>RADIUS</see></indexterm>
 		There is a PAM RADIUS (Remote Access Dial-In User Service) authentication
 		module. In most cases, administrators need to locate the source code
 		for this tool and compile and install it themselves. RADIUS protocols are
@@ -128,10 +179,17 @@ PAM support modules are available for:
 </variablelist>
 
 <para>
-Of the modules listed, Samba provides the <filename>pam_smbpasswd.so</filename> and the <filename>pam_winbind.so</filename> modules alone.
+<indexterm><primary>pam_smbpasswd.so</primary></indexterm>
+<indexterm><primary>pam_winbind.so</primary></indexterm>
+Of the modules listed, Samba provides the <filename>pam_smbpasswd.so</filename> and the
+<filename>pam_winbind.so</filename> modules alone.
 </para>
 
 <para>
+<indexterm><primary>wide-area network bandwidth</primary></indexterm>
+<indexterm><primary>efficient authentication</primary></indexterm>
+<indexterm><primary>PAM-capable</primary></indexterm>
+<indexterm><primary>centrally managed</primary></indexterm>
 Once configured, these permit a remarkable level of flexibility in the location and use
 of distributed Samba domain controllers that can provide wide-area network bandwidth,
 efficient authentication services for PAM-capable systems. In effect, this allows the
@@ -145,6 +203,10 @@ single-user account database.
 <title>Technical Discussion</title>
 
 <para>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>privilege-granting applications</primary></indexterm>
+<indexterm><primary>/etc/pam.conf</primary></indexterm>
+<indexterm><primary>/etc/pam.d/</primary></indexterm>
 PAM is designed to provide system administrators with a great deal of flexibility in
 configuration of the privilege-granting applications of their system. The local
 configuration of system security controlled by PAM is contained in one of two places:
@@ -156,11 +218,12 @@ either the single system file <filename>/etc/pam.conf</filename> or the
 <title>PAM Configuration Syntax</title>
 
 <para>
+<indexterm><primary>PAM-specific tokens</primary></indexterm>
+<indexterm><primary>case sensitivity</primary></indexterm>
 In this section we discuss the correct syntax of and generic options respected by entries to these files.
 PAM-specific tokens in the configuration file are case insensitive. The module paths, however, are case
-sensitive, since they indicate a file's name and reflect the case
-dependence of typical file systems.
-The case sensitivity of the arguments to any given module is defined for each module in turn.
+sensitive, since they indicate a file's name and reflect the case dependence of typical file systems.  The
+case sensitivity of the arguments to any given module is defined for each module in turn.
 </para>
 
 <para>
@@ -170,13 +233,12 @@ module specification lines may be extended with a <quote>\</quote>-escaped newli
 </para>
 
 <para>
+<indexterm><primary>PAM authentication module</primary></indexterm>
+<indexterm><primary>/lib/security</primary></indexterm>
 If the PAM authentication module (loadable link library file) is located in the
 default location, then it is not necessary to specify the path. In the case of
 Linux, the default location is <filename>/lib/security</filename>. If the module
 is located outside the default, then the path must be specified as:
-</para>
-
-<para>
 <programlisting>
 auth  required  /other_path/pam_strange_module.so
 </programlisting>
@@ -192,10 +254,8 @@ project. For more information on PAM, see
 </para>
 
 <para>
+<indexterm><primary>/etc/pam.conf</primary></indexterm>
 A general configuration line of the <filename>/etc/pam.conf</filename> file has the following form:
-</para>
-
-<para>
 <programlisting>
 service-name   module-type   control-flag   module-path   args
 </programlisting>
@@ -210,6 +270,9 @@ Once we have explained the meaning of the tokens, we describe this method.
 <variablelist>
 	<varlistentry><term>service-name</term><listitem>
 		<para>
+<indexterm><primary>ftpd</primary></indexterm>
+<indexterm><primary>rlogind</primary></indexterm>
+<indexterm><primary>su</primary></indexterm>
 		The name of the service associated with this entry. Frequently, the service-name is the conventional
 		name of the given application &smbmdash; for example, <command>ftpd</command>, <command>rlogind</command> and
 		<command>su</command>, and so on.
@@ -231,6 +294,8 @@ Once we have explained the meaning of the tokens, we describe this method.
 
 		<itemizedlist>
 			<listitem><para>
+<indexterm><primary>auth</primary></indexterm>
+<indexterm><primary>/etc/groups</primary></indexterm>
 			<parameter>auth:</parameter> This module type provides two aspects of authenticating the user.
 			It establishes that the user is who he or she claims to be by instructing the application
 			to prompt the user for a password or other means of identification. Second, the module can
@@ -239,6 +304,8 @@ Once we have explained the meaning of the tokens, we describe this method.
 			</para></listitem>
 
 			<listitem><para>
+<indexterm><primary>account</primary></indexterm>
+<indexterm><primary>non-authentication-based account management</primary></indexterm>
 			<parameter>account:</parameter> This module performs non-authentication-based account management.
 			It is typically used to restrict/permit access to a service based on the time of day, currently
 		 	available system resources (maximum number of users), or perhaps the location of the user 
@@ -246,6 +313,7 @@ Once we have explained the meaning of the tokens, we describe this method.
 			</para></listitem>
 
 			<listitem><para>
+<indexterm><primary>session</primary></indexterm>
 			<parameter>session:</parameter> Primarily, this module is associated with doing things that need
 			to be done for the user before and after he or she can be given service. Such things include logging
 			information concerning the opening and closing of some data exchange with a user, mounting
@@ -253,6 +321,7 @@ Once we have explained the meaning of the tokens, we describe this method.
 			</para></listitem>
 
 			<listitem><para>
+<indexterm><primary>password</primary></indexterm>
 			<parameter>password:</parameter> This last module type is required for updating the authentication
 			token associated with the user. Typically, there is one module for each
 			<quote>challenge/response</quote>-based authentication <parameter>(auth)</parameter> module type.
@@ -262,7 +331,7 @@ Once we have explained the meaning of the tokens, we describe this method.
 	</varlistentry>
 
 	<varlistentry><term>control-flag</term><listitem>
-                <para>
+		<para>
 		The control-flag is used to indicate how the PAM library will react to the success or failure of the
 		module it is associated with. Since modules can be stacked (modules of the same type execute in series,
 		one after another), the control-flags determine the relative importance of each module. The application
@@ -274,6 +343,10 @@ Once we have explained the meaning of the tokens, we describe this method.
 		</para>
 
 		<para>
+<indexterm><primary>required</primary></indexterm>
+<indexterm><primary>requisite</primary></indexterm>
+<indexterm><primary>sufficient</primary></indexterm>
+<indexterm><primary>optional</primary></indexterm>
 		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: <parameter>required</parameter>, <parameter>requisite</parameter>,
@@ -301,16 +374,16 @@ Once we have explained the meaning of the tokens, we describe this method.
 			password in a hostile environment.
 			</para></listitem>
 
-                        <listitem><para>
-                        <parameter>sufficient:</parameter> The success of this module is deemed <parameter>sufficient</parameter> to satisfy
+			<listitem><para>
+			<parameter>sufficient:</parameter> The success of this module is deemed <parameter>sufficient</parameter> to satisfy
 			the Linux-PAM library that this module-type has succeeded in its purpose. In the event that no
 			previous required module has failed, no more <quote>stacked</quote> modules of this type are invoked.
 			(In this case, subsequent required modules are not invoked). A failure of this module is not deemed
 			as fatal to satisfying the application that this module-type has succeeded.
 			</para></listitem>
 
-                        <listitem><para>
-                        <parameter>optional:</parameter> As its name suggests, this control-flag marks the module as not
+            <listitem><para>
+            <parameter>optional:</parameter> As its name suggests, this control-flag marks the module as not
 			being critical to the success or failure of the user's application for service. In general,
 			Linux-PAM ignores such a module when determining if the module stack will succeed or fail.
 			However, in the absence of any definite successes or failures of previous or subsequent stacked
@@ -363,38 +436,39 @@ Once we have explained the meaning of the tokens, we describe this method.
 			</para></listitem>
 
 			<listitem><para>
-                        <parameter>bad:</parameter> This action indicates that the return code should be thought of as indicative
+            <parameter>bad:</parameter> This action indicates that the return code should be thought of as indicative
 			of the module failing. If this module is the first in the stack to fail, its status value will be used
 			for that of the whole stack.
 			</para></listitem>
 
-                        <listitem><para>
-                        <parameter>die:</parameter> Equivalent to bad with the side effect of terminating the module stack and
+            <listitem><para>
+            <parameter>die:</parameter> Equivalent to bad with the side effect of terminating the module stack and
 			PAM immediately returning to the application.
 			</para></listitem>
 
-                        <listitem><para>
-                        <parameter>ok:</parameter> This tells PAM that the administrator thinks this return code should
+           <listitem><para>
+           <parameter>ok:</parameter> This tells PAM that the administrator thinks this return code should
 			contribute directly to the return code of the full stack of modules. In other words, if the former
 			state of the stack would lead to a return of PAM_SUCCESS, the module's return code will override
 			this value. Note, if the former state of the stack holds some value that is indicative of a module's
 			failure, this <parameter>ok</parameter> value will not be used to override that value.
 			</para></listitem>
 
-                        <listitem><para>
-                        <parameter>done:</parameter> Equivalent to <parameter>ok</parameter> with the side effect of terminating the module stack and
+            <listitem><para>
+            <parameter>done:</parameter> Equivalent to <parameter>ok</parameter> with the side effect of terminating the module stack and
 			PAM immediately returning to the application.
                         </para></listitem>
 
-                        <listitem><para>
-                        <parameter>reset:</parameter> Clears all memory of the state of the module stack and starts again with
+           <listitem><para>
+           <parameter>reset:</parameter> Clears all memory of the state of the module stack and starts again with
 			the next stacked module.
 			</para></listitem>
 		</itemizedlist>
 
 		<para>
-		Each of the four keywords, <parameter>required</parameter>; <parameter>requisite</parameter>; <parameter>sufficient</parameter>; and <parameter>optional</parameter>,
-		have an equivalent expression in terms of the [...] syntax. They are as follows:
+		Each of the four keywords, <parameter>required</parameter>; <parameter>requisite</parameter>;
+		<parameter>sufficient</parameter>; and <parameter>optional</parameter>, have an equivalent expression in terms
+		of the [...] syntax. They are as follows:
 		</para>
 
 		<para>
@@ -408,7 +482,7 @@ Once we have explained the meaning of the tokens, we describe this method.
 			</para></listitem>
 
 			<listitem><para>
-					<parameter>sufficient</parameter> is equivalent to <parameter>[success=done new_authtok_reqd=done<?latex \linebreak ?> default=ignore]</parameter>.
+			<parameter>sufficient</parameter> is equivalent to <parameter>[success=done new_authtok_reqd=done default=ignore]</parameter>.
 			</para></listitem>
 
 			<listitem><para>