From bc585c90cfbb973b1753198d88f33859c51056a0 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Mon, 7 May 2007 20:16:02 +0000 Subject: [PATCH] quickstart-pam-docs-20070507 Flesh out the PAM installation documentation for Linux and Solaris (and a bit of reformatting in the HP-UX section). --- doc/xml/QuickStartUnix/auqbg005.xml | 252 +++++++++++++++++++++++++----------- 1 file changed, 180 insertions(+), 72 deletions(-) diff --git a/doc/xml/QuickStartUnix/auqbg005.xml b/doc/xml/QuickStartUnix/auqbg005.xml index bfcde0c..dafd53a 100644 --- a/doc/xml/QuickStartUnix/auqbg005.xml +++ b/doc/xml/QuickStartUnix/auqbg005.xml @@ -739,10 +739,13 @@ Getting Started on HP-UX Systems - Begin by building AFS modifications into a new kernel; HP-UX does not support dynamic loading. Then create partitions for - storing AFS volumes, and install and configure the AFS-modified fsck program to run on AFS - server partitions. If the machine is to remain an AFS client machine, incorporate AFS into the machine's Pluggable - Authentication Module (PAM) scheme. + Begin by building AFS modifications into a new kernel; HP-UX + does not support dynamic loading. Then create partitions for storing + AFS volumes, and install and configure the AFS-modified fsck program to run on AFS server + partitions. If the machine is to remain an AFS client machine, + incorporate AFS into the machine's Pluggable Authentication Module + (PAM) scheme. incorporating AFS kernel extensions first AFS machine @@ -1119,30 +1122,33 @@ If you plan to remove client functionality from this machine after completing the installation, skip this section and proceed to Starting the BOS Server. - At this point you incorporate AFS into the operating system's Pluggable Authentication Module (PAM) scheme. PAM - integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for - authenticated access to and from the machine. + At this point you incorporate AFS into the operating system's + Pluggable Authentication Module (PAM) scheme. PAM integrates all + authentication mechanisms on the machine, including login, to + provide the security infrastructure for authenticated access to and + from the machine. In modern AFS installations, you should be using Kerberos v5 - for user login, and obtaining AFS tokens subsequent to this authentication - step. OpenAFS does not currently distribute a PAM module allowing AFS - tokens to be automatically gained at login. Whilst there are a number of - third party modules providing this functionality, it is not know if these - have been tested with HP/UX. + for user login, and obtaining AFS tokens subsequent to this + authentication step. OpenAFS does not currently distribute a PAM + module allowing AFS tokens to be automatically gained at + login. Whilst there are a number of third party modules providing + this functionality, it is not know if these have been tested with + HP/UX. - Following login, users can - obtain tokens by running the aklog - command - - Sites which still require kaserver - or external Kerberos v4 authentication should consult - Enabling kaserver based AFS login on HP-UX systems - for details of how to enable HP-UX login. - - Proceed to Starting the BOS Server - (or if referring to these instructions while installing an additional - file server machine, return to Starting Server - Programs). + Following login, users can obtain tokens by running the + aklog command + + Sites which still require kaserver or external Kerberos v4 + authentication should consult Enabling + kaserver based AFS login on HP-UX systems for details of how + to enable HP-UX login. + + Proceed to Starting the BOS + Server (or if referring to these instructions while + installing an additional file server machine, return to Starting Server Programs). @@ -1671,10 +1677,13 @@ RedHat Enterprise Linux packages distributed by OpenAFS. Additional instructions are provided for those building from source. - Begin by running the AFS client startup scripts, which call the modprobe program, which - dynamically loads AFS modifications into the kernel. Then create partitions for storing AFS volumes. You do not need to replace - the Linux fsck program. If the machine is to remain an AFS client machine, incorporate AFS into - the machine's Pluggable Authentication Module (PAM) scheme. + Begin by running the AFS client startup scripts, which call the + modprobe program, which dynamically + loads AFS modifications into the kernel. Then create partitions for + storing AFS volumes. You do not need to replace the Linux fsck program. If the machine is to remain an + AFS client machine, incorporate AFS into the machine's Pluggable + Authentication Module (PAM) scheme. incorporating AFS kernel extensions first AFS machine @@ -1933,30 +1942,92 @@ Enabling AFS Login on Linux Systems - If you plan to remove client functionality from this machine after completing the installation, skip this section and - proceed to Starting the BOS Server. + If you plan to remove client functionality from this machine + after completing the installation, skip this section and proceed + to Starting the BOS Server. - At this point you incorporate AFS into the operating system's Pluggable Authentication Module (PAM) scheme. PAM - integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for - authenticated access to and from the machine. - - At this time, we recommend that new sites requiring AFS credentials - to be gained as part of PAM authentication use Russ Alberry's - pam_afs_session, rather than utilising the bundled pam_afs2 module. - A typical PAM stack should authenticate the user using an external - Kerberos V service, and then use the AFS PAM module to obtain AFS - credentials in the session section - - Sites which still require kaserver - or external Kerberos v4 authentication should consult - Enabling kaserver based AFS Login on Linux Systems - for details of how to enable AFS login on Linux. + At this point you incorporate AFS into the operating system's + Pluggable Authentication Module (PAM) scheme. PAM integrates all + authentication mechanisms on the machine, including login, to provide + the security infrastructure for authenticated access to and from the + machine. + + You should first configure your system to obtain Kerberos v5 + tickets as part of the authentication process, and then run an AFS PAM + module to obtain tokens from those tickets after authentication. Many + Linux distributions come with a Kerberos v5 PAM module (usually called + pam-krb5 or pam_krb5), or you can download and install Russ Allbery's + Kerberos v5 PAM module, which is tested regularly with AFS. + See the instructions of whatever PAM module you use for how to + configure it. + + Some Kerberos v5 PAM modules do come with native AFS support + (usually requiring the Heimdal Kerberos implementation rather than the + MIT Kerberos implementation). If you are using one of those PAM + modules, you can configure it to obtain AFS tokens. It's more common, + however, to separate the AFS token acquisition into a separate PAM + module. + + The recommended AFS PAM module is Russ + Allbery's pam-afs-session module. It should work with any of + the Kerberos v5 PAM modules. To add it to the PAM configuration, you + often only need to add configuration to the session group: + + + PAM session example + session required pam_afs_session.so + + + If you also want to obtain AFS tokens for scp + and similar commands that don't open a session, you will also need to + add the AFS PAM module to the auth group so that the PAM + setcred call will obtain tokens. The + pam_afs_session module will always return success + for authentication so that it can be added to the auth group only for + setcred, so make sure that it's not marked as + sufficient. + + + PAM auth example +auth [success=ok default=1] pam_krb5.so +auth [default=done] pam_afs_session.so +auth required pam_unix.so try_first_pass + + + This example will work if you want to try Kerberos v5 first and + then fall back to regular Unix authentication. + success=ok for the Kerberos PAM module followed by + default=done for the AFS PAM module will cause a + successful Kerberos login to run the AFS PAM module and then skip the + Unix authentication module. default=1 on the + Kerberos PAM module causes failure of that module to skip the next + module (the AFS PAM module) and fall back to the Unix module. If you + want to try Unix authentication first and rearrange the order, be sure + to use default=die instead. + + The PAM configuration is stored in different places in different + Linux distributions. On Red Hat, look in + /etc/pam.d/system-auth. On Debian and + derivatives, look in /etc/pam.d/common-session + and /etc/pam.d/common-auth. + + For additional configuration examples and the configuration + options of the AFS PAM module, see its documentation. For more + details on the available options for the PAM configuration, see the + Linux PAM documentation. + + Sites which still require kaserver or + external Kerberos v4 authentication should consult Enabling kaserver based AFS Login on Linux + Systems for details of how to enable AFS login on Linux. - Proceed to Starting the BOS Server - (or if referring to these instructions while installing an additional - file server machine, return to Starting Server - Programs). + Proceed to Starting the BOS + Server (or if referring to these instructions while installing + an additional file server machine, return to Starting Server Programs). @@ -2351,30 +2422,67 @@ proceed to Starting the BOS Server. - At this point you incorporate AFS into the operating system's Pluggable Authentication Module (PAM) scheme. PAM - integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for - authenticated access to and from the machine. - - Explaining PAM is beyond the scope of this document. It is assumed that you understand the syntax and meanings of - settings in the PAM configuration file (for example, how the other entry works, the effect of - marking an entry as required, optional, or + At this point you incorporate AFS into the operating system's + Pluggable Authentication Module (PAM) scheme. PAM integrates all + authentication mechanisms on the machine, including login, to provide + the security infrastructure for authenticated access to and from the + machine. + + Explaining PAM is beyond the scope of this document. It is + assumed that you understand the syntax and meanings of settings in the + PAM configuration file (for example, how the + other entry works, the effect of + marking an entry as required, + optional, or sufficient, and so on). - In modern AFS installations, you should be using Kerberos v5 - for user login, and obtaining AFS tokens subsequent to this authentication - step. OpenAFS does not currently distribute a PAM module allowing AFS - tokens to be automatically gained at login. Whilst there are a number of - third party modules providing this functionality, it is not know if these - have been tested with HP/UX. - - Following login, users can - obtain tokens by running the aklog - command - - Sites which still require kaserver - or external Kerberos v4 authentication should consult - Enabling kaserver based AFS Login on Solaris Systems" - for details of how to enable AIX login. + You should first configure your system to obtain Kerberos v5 + tickets as part of the authentication process, and then run an AFS PAM + module to obtain tokens from those tickets after authentication. + Current versions of Solaris come with a Kerberos v5 PAM module that + will work, or you can download and install Russ Allbery's + Kerberos v5 PAM module, which is tested regularly with AFS. + See the instructions of whatever PAM module you use for how to + configure it. + + Some Kerberos v5 PAM modules do come with native AFS support + (usually requiring the Heimdal Kerberos implementation rather than the + MIT Kerberos implementation). If you are using one of those PAM + modules, you can configure it to obtain AFS tokens. It's more common, + however, to separate the AFS token acquisition into a separate PAM + module. + + The recommended AFS PAM module is Russ + Allbery's pam-afs-session module. It should work with any of + the Kerberos v5 PAM modules. To add it to the PAM configuration, you + often only need to add configuration to the session group in + pam.conf: + + + PAM session example +login session required pam_afs_session.so + + + This example enables PAM authentication only for console login. + You may want to add a similar line for the ssh service and for any + other login service that you use, including possibly the + other service (which serves as a catch-all). You + may also want to add options to the AFS PAM session module + (particularly retain_after_close, which is + necessary for some versions of Solaris. + + For additional configuration examples and the configuration + options of the AFS PAM module, see its documentation. For more + details on the available options for the PAM configuration, see the + pam.conf manual page. + + Sites which still require kaserver or external Kerberos v4 authentication + should consult Enabling kaserver based AFS + Login on Solaris Systems" for details of how to enable AFS + login on Solaris. Proceed to Editing the File Systems Clean-up Script on Solaris Systems -- 1.9.4