From f521ac0f603f56cd05d643f198d6a4b0fc56e539 Mon Sep 17 00:00:00 2001 From: Simon Wilkinson Date: Tue, 24 Apr 2007 04:37:52 +0000 Subject: [PATCH] quickstart-obsolete-appendices-20070423 FIXES 60137 commit updates to the docs for obsolete stuff ==================== This delta was composed from multiple commits as part of the CVS->Git migration. The checkin message with each commit was inconsistent. The following are the additional commit messages. ==================== also the appendix file --- doc/xml/QuickStartUnix/Makefile | 2 +- doc/xml/QuickStartUnix/appendix.xml | 1676 +++++++++++++++++++++++++++ doc/xml/QuickStartUnix/auqbg000.xml | 2 + doc/xml/QuickStartUnix/auqbg004.xml | 26 +- doc/xml/QuickStartUnix/auqbg005.xml | 656 +++-------- doc/xml/QuickStartUnix/auqbg006.xml | 503 +++++--- doc/xml/QuickStartUnix/auqbg007.xml | 1140 ++++++------------ 7 files changed, 2510 insertions(+), 1495 deletions(-) create mode 100644 doc/xml/QuickStartUnix/appendix.xml diff --git a/doc/xml/QuickStartUnix/Makefile b/doc/xml/QuickStartUnix/Makefile index 124aae304..e4ff69fb6 100644 --- a/doc/xml/QuickStartUnix/Makefile +++ b/doc/xml/QuickStartUnix/Makefile @@ -13,7 +13,7 @@ BOOK = auqbg000.xml IDX = auqbg009.xml SRCS = $(BOOK) auqbg003.xml auqbg004.xml auqbg005.xml auqbg006.xml \ - auqbg007.xml auqbg008.xml + auqbg007.xml auqbg008.xml appendix.xml FLAGS = -e no-idref all: pdf html diff --git a/doc/xml/QuickStartUnix/appendix.xml b/doc/xml/QuickStartUnix/appendix.xml new file mode 100644 index 000000000..a9c08af21 --- /dev/null +++ b/doc/xml/QuickStartUnix/appendix.xml @@ -0,0 +1,1676 @@ + + + Appendix B. Configuring Legacy Components + + This chapter describes how to configure a number of deprecated + components in OpenAFS. Whilst these components are not recommended for sites + performing new installations, it is recognised that there are a number of + installations which have not yet transitioned from using these, for whom + continued provision of installation instructions my be useful + + + kaserver and Legacy Kerberos 4 Authentication + + This section contains instructions for installing server and client + machines in sites which use either the deprecated AFS + kaserver or legacy Kerberos 4 + authentication systems + + This should be used in conjuction with the installation instructures + in earlier chapters, whose format it mirrors. + + + Background + + As detailed in the OpenAFS "No more DES" roadmap, OpenAFS is moving + away from the single DES based security models of both + kaserver and external Kerberos 4 KDCs, + in favour of using external, Kerberos 5 KDCs for authentication. + + AFS version 3 was designed and implemented during the late 80s and + early 90s when the state of the art in distributed computer + authentication and data security was Kerberos 4 and single DES. The + RXKAD security class was specified to use a single DES key and the kauth + authentication protocol is a derivative of MIT's Kerberos 4 protocol. + + + For the better part of the last decade there has been concern + regarding the cryptographic strength of the DES cipher when used as a + building block within systems intended to prove authentication and/or + data integrity and privacy. Kerberos 4 and RXKAD are not extensible and + cannot negotiate non-DES key types. As a result efforts to migrate away + from Kerberos 4 based authentication at higher risk organizations have + been underway since the mid to late 90s. Ken Hornstein issued the first + of his Kerberos 5 migration kits for AFS in May 1999. + + In March 2003, the continued use of single DES and kauth as the + basis for OpenAFS security became a real-world threat when a significant + Kerberos 4 crossrealm vulnerability was published. The OpenAFS community + was notified in security advisory OPENAFS-SA-2003-001 which can be + found at http://www.openafs.org/security. + + As a result of the mounting concerns regarding the strength of + DES, NIST announced in May 2003 the withdrawal of FIPS 43-3 + "Data Encryption Standard (DES)" as well as the associated FIPS 74 and + FIPS 81. In other words, NIST announced that DES and its derivatives + could no longer be used by the United States Government and should no + longer by those that trust its lead. + + In July 2003 MIT announced the end of life of the Kerberos 4 + protocol which is distributed for backward compatibility as part of the + MIT Kerberos 5 distribution. + + + Using this Appendix + + This appendix should be read in conjunction with the instructions + contained in the earlier chapters. It contains additions and in some + cases, modifications, to the directions contained in those + chapters. It is organised into 3 main sections, corresponding to the + topics of the earlier chapters. + + + Installing the First AFS Machine + + + Installing Additional Server Machines + + + Installing Additonal Client Machines + + + + There is an additional section on installing AFS login + functionality, which is relevant to all machines which are operating as + AFS clients + + In addition, some general substitions should be made + + + References to kinitand + aklog should be replaced with + a single call to klog + For example + + # kinit admin + Password: admin_passwd + # aklog + + becomes + + # kinit admin + Password: admin_passwd + + + + + + Installing the First AFS machine + + This section details changes to the installation procedure for the + first AFS machine which are required in order to use + kaserver for authentication. As + detailed above, new sites are strongly discouraged from deploying + kaserver. + + The structure of this section follows the structure of the + earlier chapter. + + + Overview: Installing Server Functionality + + In adddition to the items described, you must also create + the Authentication Server as a database server process. The procedure + for creating the initial security mechanisms is also changed. + + + + Starting the kaserver Database Server Process + + Authentication Server + starting + first AFS machine + + + first AFS machine + Authentication Server + + + kaserver process + Authentication Server + + + starting + Authentication Server + first AFS machine + + + In addition to the database server processes described, you + must also use the bos create command + to create an entry for the following process, which runs on database + server machines only: + + + The Authentication Server + (the kaserver process) maintains + the Authentication Database + + + + The following instructions include the + -cell argument on all applicable + commands. Provide the cell name you assigned in + Defining Cell Name and Membership for Server + Processes. If a command appears on multiple lines, it is + only for legibility. The following commands should run before any of + the bos create commands detailed in + Starting the Database Server Processes. + + + + + + + commands + bos create + + + bos commands + create + + Issue the bos create + command to start the Authentication Server. The current + working directory is still + /usr/afs/bin. + + # ./bos create <machine name> kaserver simple /usr/afs/bin/kaserver \ + -cell <cell name> -noauth + + + + You can safely ignore the messages that tell you to add + Kerberos to the /etc/services + file; AFS uses a default value that makes the addition + unnecessary. You can also ignore messages about the failure of + authentication. + + + Return to Starting the Database Server + Processes and follow the remaining instructions + + + + + Initialising Cell Security with kaserver + + + The following instructions should be followed in place of + those in Initializing Cell Security + + + + Begin by creating the following two initial entries in the + Authentication Database: + + + A generic administrative account, called + admin by convention. If you + choose to assign a different name, substitute it throughout the + remainder of this document. + + After you complete the installation of the first machine, + you can continue to have all administrators use the + admin account, or you can create + a separate administrative account for each of them. The latter + scheme implies somewhat more overhead, but provides a more + informative audit trail for administrative operations. + + + + The entry for AFS server processes, called + afs. No user logs in under this + identity, but the Authentication Server's Ticket Granting Service + (TGS) module uses the associated key to encrypt the server + tickets that it grants to AFS clients for presentation to server + processes during mutual authentication. (The chapter in the + OpenAFS Administration Guide about cell + configuration and administration describes the role of server + encryption keys in mutual authentication.) + + In Step 7, you also + place the initial AFS server encryption key into the /usr/afs/etc/KeyFile file. The AFS server + processes refer to this file to learn the server + encryption key when they need to decrypt server tickets. + + + + + You also issue several commands that enable the new + admin user to issue privileged + commands in all of the AFS suites. + + The following instructions do not configure all of the security + mechanisms related to the AFS Backup System. See the chapter in the + OpenAFS Administration Guide about configuring + the Backup System. + + + commands + kas (interactive) + + + + kas commands + interactive mode, entering + + + + interactive mode for kas + entering + + + + Enter kas interactive + mode. Because the machine is in no-authorization checking + mode, include the -noauth flag + to suppress the Authentication Server's usual prompt for a + password. + + # kas -cell <cell name> -noauth + ka> + + + commands + kas create + + + kas commands + create + + + server encryption key + in Authentication Database + + + creating + server encryption key + Authentication Database + + + + + + Issue the + kas create command to create + Authentication Database entries called + admin and + afs. + + Do not provide passwords on the command line. Instead + provide them as afs_passwd and + admin_passwd in response to the + kas command interpreter's + prompts as shown, so that they do not appear on the standard + output stream. + + You need to enter the afs_passwd + string only in this step and in Step + 7, so provide a value that + is as long and complex as possible, preferably including numerals, + punctuation characters, and both uppercase and lowercase letters. + Also make the admin_passwd as + long and complex as possible, but keep in mind that + administrators need to enter it often. Both passwords must be + at least six characters long. + + + ka> create afs + initial_password: afs_passwd + Verifying, please re-enter initial_password: afs_passwd + ka> create admin + initial_password: admin_passwd + Verifying, please re-enter initial_password: admin_passwd + + + + commands + kas examine + + + + kas commands + examine + + + + displaying + server encryption key + Authentication Database + + + + + Issue the + kas examine command to display + the afs entry. The output + includes a checksum generated by encrypting a constant with the + server encryption key derived from the + afs_passwd string. In + Step 8 you issue the + bos listkeys command to verify + that the checksum in its output matches the checksum in this + output. + + ka> examine afs + User data for afs + key (0) cksum is checksum . . . + + + commands + kas setfields + + + kas commands + setfields + + + admin account + setting ADMIN flag on Auth. DB entry + + + + + + Issue the + kas setfields command to turn + on the ADMIN flag in the + admin entry. This enables the + admin user to issue privileged + kas commands. Then issue + the kas examine command to verify + that the ADMIN flag + appears in parentheses on the first line of the output, as shown + in the example. + + ka> setfields admin -flags admin + ka> examine admin + User data for admin (ADMIN) . . . + + + commands + kas quit + + + kas commands + quit + + + interactive mode for kas + quitting + + + + + + Issue the kas quit + command to leave kas + interactive mode. + + ka> quit + + + commands + bos adduser + + + bos commands + adduser + + + usr/afs/etc/UserList + UserList file + + + UserList file + first AFS machine + + + files + UserList + + + creating + UserList file entry + + + admin account + adding + to UserList file + + + + + + Issue the + bos adduser command to add the + admin user to the + /usr/afs/etc/UserList file. + This enables the admin user to + issue privileged bos and + vos commands. + + # ./bos adduser <machine name> admin -cell <cell name> -noauth + + + commands + bos addkey + + + bos commands + addkey + + + creating + server encryption key + KeyFile file + + + server encryption key + in KeyFile file + + + + + + Issue the + bos addkey command to define + the AFS server encryption key in the + /usr/afs/etc/KeyFile file. + + + Do not provide the password on the command line. Instead + provide it as afs_passwd in + response to the bos command + interpreter's prompts, as shown. Provide the same string as + in Step 2. + + + # ./bos addkey <machine name> -kvno 0 -cell <cell name> -noauth + Input key: afs_passwd + Retype input key: afs_passwd + + + + commands + bos listkeys + + + + bos commands + listkeys + + + + displaying + server encryption key + KeyFile file + + + + + Issue the + bos listkeys command to verify + that the checksum for the new key in the + KeyFile file is the same as the + checksum for the key in the Authentication Database's + afs entry, which you displayed + in Step 3. + + # ./bos listkeys <machine name> -cell <ce +ll name> -noauth + key 0 has cksum checksum + + + You can safely ignore any error messages indicating that + bos failed to get tickets + or that authentication failed. + + If the keys are different, issue the following commands, + making sure that the afs_passwd + string is the same in each case. The + checksum strings reported by the + kas examine and + bos listkeys commands must + match; if they do not, repeat these instructions until they do, + using the -kvno argument to + increment the key version number each time. + + + # ./kas -cell <cell name> -noauth + ka> setpassword afs -kvno 1 + new_password: afs_passwd + Verifying, please re-enter initial_password: afs_passwd + ka> examine afs + User data for afs + key (1) cksum is checksum . . . + ka> quit + # ./bos addkey <machine name> -kvno 1 -cell <cell name> -noauth + Input key: afs_passwd + Retype input key: afs_passwd + # ./bos listkeys <machine name> -cell <cell name> -noauth + key 1 has cksum checksum + + + + Proceed to + Initializing the Protection Database + to continue with the installation process + + + + + + Installing Additional Server Machines + + + Starting the Authenticxation Service + + Authentication Server + starting + new db-server machine + + + starting + Authentication Server + new db-server machine + + In addition to the instructions in the main guide, you must + also start the Authentication Server on the new database machine, + as detailed below + + + + Start the Authentication Server + (the kaserver process). + + % bos create <machine name> kaserver simple /usr/afs/bin/kaserver + + + + + Return to starting the backup server + + + + + + + Enabling AFS login with kaserver + The authentication system of every machine should be modified so + that users obtain an AFS token as they log into the local file system. + Using AFS is simpler and more convenient for your users if you make the + modifications on all client machines. Otherwise users must perform a two + step login procedure (login to the local system, and then issue the + klog command. + + For convenience, the following sections group this procedure by + system type. Proceed to the appropriate section. + + + + Enabling AFS Login on AIX Systems + + + + + Enabling AFS Login on HP-UX Systems + + + + + Enabling AFS Login on IRIX Systems + + + + + Enabling AFS Login on Linux Systems + + + + + Enabling AFS login on Solaris Systems + + + + + + + Enabling kaserver based AFS login + + Now incorporate AFS into the AIX secondary authentication system. + + + Issue the ls command to + verify that the afs_dynamic_auth + and afs_dynamic_kerbauth + programs are installed in the local + /usr/vice/etc directory. + + # ls /usr/vice/etc + + + + If the files do not exist, unpack the + OpenAFS Binary Distribution for AIX (if it is not already), + change directory as indicated, and copy them. + + + # cd /tmp/afsdist/rs_aix42/root.client/usr/vice/etc + # cp -p afs_dynamic* /usr/vice/etc + + + + + Edit the local + /etc/security/user file, making + changes to the indicated stanzas: + + + In the default stanza, set the + registry attribute to + DCE (not to + AFS), as follows: + + registry = DCE + + + + + + In the default stanza, set the + SYSTEM attribute as + indicated. + + If the machine is an AFS client only, set the + following value: + + SYSTEM = "AFS OR (AFS[UNAVAIL] AND compat[SUCCESS])" + + + If the machine is both an AFS and a DCE client, + set the following value (it must appear on a single line in + the file): + + SYSTEM = "DCE OR DCE[UNAVAIL] OR AFS OR (AFS[UNAVAIL] \ + AND compat[SUCCESS])" + + + + + In the root + stanza, set the registry + attribute as follows. It enables the local superuser + root to log into the local + file system only, based on the password listed in the + local password file. + + root: + registry = files + + + + + + + + + Edit the local + /etc/security/login.cfg file, + creating or editing the indicated stanzas: + + + In the DCE stanza, + set the program + attribute as follows. + + If you use the AFS Authentication Server + (kaserver process): + + DCE: + program = /usr/vice/etc/afs_dynamic_auth + + + If you use a Kerberos v4 implementation of AFS + authentication: + + + DCE: + program = /usr/vice/etc/afs_dynamic_kerbauth + + + + + In the AFS stanza, + set the program + attribute as follows. + + If you use the AFS Authentication Server + (kaserver process): + + AFS: + program = /usr/vice/etc/afs_dynamic_auth + + + If you use a Kerberos v4 implementation of AFS + authentication: + + AFS: + program = /usr/vice/etc/afs_dynamic_kerbauth + + + + + + + Proceed to + Starting the BOS Server, + if you are installing your first file server machine; + Starting Server Programs, + if you are installing an additional file server machine; or + Loading and Creating Client Files + if you are installating a client + + + + + + Enabling kaserver based AFS Login on HP-UX systems + + 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). + + The following instructions explain how to alter the entries in + the PAM configuration file for each service for which you + wish to use AFS authentication. Other configurations possibly also + work, but the instructions specify the recommended and + tested configuration. + + + The instructions specify that you mark each entry as + optional. However, marking some + modules as optional can mean that they grant access to the + corresponding service even when the user does not meet all of the + module's requirements. In some operating system revisions, for + example, if you mark as optional the module that controls + login via a dial-up connection, it allows users to login without + providing a password. See the OpenAFS Release + Notes for a discussion of any limitations that apply to + this operating system. + + Also, with some operating system versions you must install + patches for PAM to interact correctly with certain + authentication programs. For details, see the + OpenAFS Release Notes. + + + The recommended AFS-related entries in the PAM configuration + file make use of one or more of the following three + attributes. + + + try_first_pass + + + This is a standard PAM attribute that can be included on + entries after the first one for a service; it directs + the module to use the password that was provided to the first + module. For the AFS module, it means that AFS + authentication succeeds if the password provided to the module + listed first is the user's correct AFS password. For + further discussion of this attribute and its alternatives, see + the operating system's PAM documentation. + + + + + ignore_root + + + This attribute, specific to the AFS PAM module, directs it + to ignore not only the local superuser root, but also any user with UID 0 + (zero). + + + + + setenv_password_expires + + + This attribute, specific to the AFS PAM module, sets the + environment variable PASSWORD_EXPIRES to the expiration + date of the user's AFS password, which is recorded in the + Authentication Database. + + + + + + Perform the following steps to enable AFS login. + + + Unpack the OpenAFS Binary Distribution for HP-UX into the + /tmp/afsdist directory, if it is + not already. + Then change directory as indicated. + + # cd /usr/lib/security + + + + + Copy the AFS authentication library file to the + /usr/lib/security directory. Then + create a symbolic link to it whose name does not mention the + version. Omitting the version eliminates the need to edit + the PAM configuration file if you later update the library + file. + + If you use the AFS Authentication Server + (kaserver process) in the cell: + + + # cp /tmp/afsdist/hp_ux110/lib/pam_afs.so.1 . + # ln -s pam_afs.so.1 pam_afs.so + + + If you use a Kerberos implementation of AFS authentication: + + + # cp /tmp/afsdist/hp_ux110/lib/pam_afs.krb.so.1 . + # ln -s pam_afs.krb.so.1 pam_afs.so + + + + + Edit the + Authentication management + section of the HP-UX PAM configuration file, + /etc/pam.conf by convention. The + entries in this section have the value + auth in their second field. + + First edit the standard entries, which refer to the + HP-UX PAM module (usually, the file /usr/lib/security/libpam_unix.1) in their + fourth field. For each service for which you want to + use AFS authentication, edit the third field of its entry to read + optional. The + pam.conf file in the HP-UX + distribution usually includes standard entries for the + login and + ftp services, for instance. + + If there are services for which you want to use AFS + authentication, but for which the pam.conf file does not already include a + standard entry, you must create that entry and place the + value optional in its third field. + For instance, the HP-UX pam.conf + file does not usually include standard entries for the remsh or + telnet services. + + Then create an AFS-related entry for each service, placing it + immediately below the standard entry. The following + example shows what the + Authentication Management section + looks like after you have you + edited or created entries for the services mentioned previously. + Note that the example AFS entries appear on two lines + only for legibility. + + + login auth optional /usr/lib/security/libpam_unix.1 + login auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root setenv_password_expires + ftp auth optional /usr/lib/security/libpam_unix.1 + ftp auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root + remsh auth optional /usr/lib/security/libpam_unix.1 + remsh auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root + telnet auth optional /usr/lib/security/libpam_unix.1 + telnet auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root setenv_password_expires + + + + + If you use the Common Desktop Environment (CDE) on the + machine and want users to obtain an AFS token as they log + in, also add or edit the following four entries in the + Authentication management + section. Note that the AFS-related entries appear on two lines + here only for legibility. + + dtlogin auth optional /usr/lib/security/libpam_unix.1 + dtlogin auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root + dtaction auth optional /usr/lib/security/libpam_unix.1 + dtaction auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root + + + + + Proceed to + Starting the BOS Server if you + are installing your first file server; + Starting Server Programs if you + are installing an additional file server machine; or + Loading and Creating Client Files. + if you are installing a client. + + + + + + Enabling kaserver based AFS Login on IRIX Systems + + The standard IRIX command-line + login program and the graphical + xdm login program both automatically + grant an AFS token when AFS is incorporated into the machine's + kernel. However, some IRIX distributions use another login utility by + default, and it does not necessarily incorporate the required AFS + modifications. If that is the case, you must disable the default + utility if you want AFS users to obtain AFS tokens at login. For + further discussion, see the + OpenAFS Release Notes. + + If you configure the machine to use an AFS-modified login + utility, then the afsauthlib.so and + afskauthlib.so files (included in the + AFS distribution) must reside in the + /usr/vice/etc directory. Issue the + ls command to verify. + + + # ls /usr/vice/etc + + + If the files do not exist, unpack the OpenAFS Binary Distribution + for IRIX (if it is not already), change directory as indicated, and copy + them. + + + # cd /tmp/afsdist/sgi_65/root.client/usr/vice/etc + # cp -p *authlib* /usr/vice/etc + + + After taking any necessary action, proceed to + Starting the BOS Server if you + are installing your first file server; + Starting Server Programs if you + are installing an additional file server machine; or + Loading and Creating Client Files + if you are installing a client. + + + Enabling kaserver based AFS Login on Linux Systems + + 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). + + The following instructions explain how to alter the entries in + the PAM configuration file for each service for which you + wish to use AFS authentication. Other configurations possibly also + work, but the instructions specify the recommended and + tested configuration. + + The recommended AFS-related entries in the PAM configuration + file make use of one or more of the following three + attributes. + + Authentication Management + + + try_first_pass + + + This is a standard PAM attribute that can be included on + entries after the first one for a service; it directs + the module to use the password that was provided to the first + module. For the AFS module, it means that AFS + authentication succeeds if the password provided to the module + listed first is the user's correct AFS password. For + further discussion of this attribute and its alternatives, see + the operating system's PAM documentation. + + + + + ignore_root + + + This attribute, specific to the AFS PAM module, directs it + to ignore not only the local superuser root, but also any user with UID + 0 (zero). + + + + + ignore_uid uid + + + This option is an extension of the "ignore_root" switch. + The additional parameter is a limit. Users with a uid + up to the given parameter are ignored by + pam_afs.so. Thus, a system administrator + still has the + opportunity to add local user accounts to his system by choosing + between "low" and "high" user ids. An example + /etc/passwd file for "ignore_uid 100" may have entries like these: + + . + . +afsuserone:x:99:100::/afs/afscell/u/afsuserone:/bin/bash +afsusertwo:x:100:100::/afs/afscell/u/afsusertwo:/bin/bash +localuserone:x:101:100::/home/localuserone:/bin/bash +localusertwo:x:102:100::/home/localusertwo:/bin/bash + . + . + + AFS accounts should be locked in the file /etc/shadow like this: + + . + . +afsuserone:!!:11500:0:99999:7::: +afsusertwo:!!:11500:0:99999:7::: +localuserone:<thelocaluserone'skey>:11500:0:99999:7::: +localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: + . + . + + There is no need to store a local key in this file since the AFS + password is sent and verfied at the AFS cell server! + + + + + setenv_password_expires + + + This attribute, specific to the AFS PAM module, sets the + environment variable PASSWORD_EXPIRES to the expiration + date of the user's AFS password, which is recorded in the + Authentication Database. + + + + + set_token + + + Some applications don't call + pam_setcred() in order to retrieve the + appropriate credentials (here the AFS token) for their session. + This switch sets the credentials already in + pam_sm_authenticate() obsoleting a call to + pam_setcred(). Caution: Don't use this switch for applications which + do call pam_setcred()! One + example for an application not calling + pam_setcred() are older versions of the + samba server. Nevertheless, using applications with + working pam session management is recommended as this setup + conforms better with the PAM definitions. + + + + + refresh_token + + + This options is identical to "set_token" except that no + new PAG is generated. This is necessary to handle + processes like xlock or xscreensaver. It is not enough to just + unlock the screen for a user who + reactivated his session by typing in the correct AFS password, but + one may also need fresh tokens with a full lifetime in + order to work on, and the new token must be refreshed in the + already existing PAG for the processes that have been + started. This is achieved using this option. + + + + + use_klog + + + Activating this switch causes authentication to be done by + calling the external program "klog". One program requiring + this is for example kdm of KDE 2.x. + + + + + dont_fork + + + Usually, the password verification and token establishment + is performed in a sub process. Using this option pam_afs does not + fork and performs all actions in a single process. + Only use this option in cases where you + notice serious problems caused by the sub process. + This option has been developed in respect to + the "mod_auth_pam"-project (see also + mod_auth_pam). + The mod_auth_pam module enables PAM authentication for the apache + http server package. + + + + + Session Management + + + no_unlog + + + Normally the tokens are deleted (in memory) after the + session ends. Using this option causes the tokens to be left + untouched. This behaviour was the default + in pam_afs until openafs-1.1.1! + + + + + remainlifetime sec + + + The tokens are kept active for sec + seconds before they are deleted. X display managers i.e. + are used to inform the applications started in the X session + before the logout and then end themselves. If the token + was deleted immediately the applications would have no chance + to write back their settings to i.e. the user's AFS home + space. This option may help to avoid the problem. + + + + + Perform the following steps to enable AFS login. + + + Unpack the OpenAFS Binary Distribution for Linux into the + /tmp/afsdist/ directory, if it is + not already. + Then change to the directory for PAM modules, which depends on which Linux distribution you are using. + + If you are using a Linux distribution from Red Hat Software: + + + # cd /lib/security + + + If you are using another Linux distribution: + + + # cd /usr/lib/security + + + + + Copy the appropriate AFS authentication library file to the + directory to which you changed in the previous step. + Create a symbolic link whose name does not mention the version. + Omitting the version eliminates the need to edit the PAM + configuration file if you later update the library file. + + If you use the AFS Authentication Server + (kaserver process): + + # cp /cdrom/i386_linux22/lib/pam_afs.so.1 . + # ln -s pam_afs.so.1 pam_afs.so + + + If you use a Kerberos implementation of AFS + authentication: + + # cp /cdrom/i386_linux22/lib/pam_afs.krb.so.1 . + # ln -s pam_afs.krb.so.1 pam_afs.so + + + + + For each service with which you want to use AFS + authentication, insert an entry for the AFS PAM module into the + auth section of the service's + PAM configuration file. (Linux uses a separate + configuration file for each service, unlike some other operating + systems which list all services in a single file.) Mark + the entry as sufficient in the + second field. + + Place the AFS entry below any entries that impose conditions + under which you want the service to fail for a user + who does not meet the entry's requirements. Mark these entries + required. Place the AFS + entry above any entries that need to execute only if AFS + authentication fails. + + Insert the following AFS entry if using the Red Hat + distribution: + + auth sufficient /lib/security/pam_afs.so try_first_pass ignore_root + + + Insert the following AFS entry if using another + distribution: + + + auth sufficient /usr/lib/security/pam_afs.so try_first_pass ignore_root + + + Check the PAM config files also for "session" entries. If + there are lines beginning with "session" then please + insert this line too: + + + session optional /lib/security/pam_afs.so + + + or + + + session optional /usr/lib/security/pam_afs.so + + + This guarantees that the user's tokens are deleted from + memory after his session ends so that no other user + coincidently gets those tokens without authorization! The + following examples illustrate the recommended configuration of + the configuration file for several services: + + Authentication Management + + + (/etc/pam.d/login) + + + + + #%PAM-1.0 + auth required /lib/security/pam_securetty.so + auth required /lib/security/pam_nologin.so + auth sufficient /lib/security/pam_afs.so try_first_pass ignore_root + # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + #This enables AFS authentication for every user but root + auth required /lib/security/pam_pwdb.so shadow nullok + account required /lib/security/pam_pwdb.so + password required /lib/security/pam_cracklib.so + password required /lib/security/pam_pwdb.so shadow nullok use_authtok + session optional /lib/security/pam_afs.so + #Make sure tokens are deleted after the user logs out + session required /lib/security/pam_pwdb.so + + + + + + + (/etc/pam.d/samba) + + + + + auth required /lib/security/pam_afs.so ignore_uid 100 set_token + # ^^^^^^^^^^^^^^^^^^^^^^^^ + #Here, users with uid>100 are considered to belong to the AFS and users + #with uid<=100 are ignored by pam_afs. The token is retrieved already in + #pam_sm_authenticate() (this is an example pam config for a samba version + #that does not call pam_setcred(), it also does no sense to include session + #entries here since they would be ignored by this version of samba ). + account required /lib/security/pam_pwdb.so + + + + + + + (/etc/pam.d/xscreensaver) + + + + + auth sufficient /lib/security/pam_afs.so ignore_uid 100 refresh_token + # ^^^^^^^^^^^^^ + #Avoid generating a new PAG for the new tokens, use the already existing PAG and + #establish a fresh token in it. + auth required /lib/security/pam_pwdb.so try_first_pass + + + + + + + (/etc/pam.d/httpd) + + + + + auth required /lib/security/pam_afs.so ignore_uid 100 dont_fork + # ^^^^^^^^^ + #Don't fork for the verification of the password. + + + + + + + Session Management + + + (/etc/pam.d/su) + + + + + auth sufficient /lib/security/pam_afs.so ignore_uid 100 + auth required /lib/security/pam_pwdb.so try_first_pass + account required /lib/security/pam_pwdb.so + password required /lib/security/pam_cracklib.so + password required /lib/security/pam_pwdb.so use_authtok + session required /lib/security/pam_pwdb.so + session optional /lib/security/pam_afs.so no_unlog + # ^^^^^^^^ + #Don't delete the token in this case, since the user may still + #need it (for example if somebody logs in and changes to root + #afterwards he may still want to access his home space in AFS). + session required /lib/security/pam_login_access.so + session optional /lib/security/pam_xauth.so + + + + + + + (/etc/pam.d/xdm) + + + + + auth required /lib/security/pam_nologin.so + auth required /lib/security/pam_login_access.so + auth sufficient /lib/security/pam_afs.so ignore_uid 100 use_klog + auth required /lib/security/pam_pwdb.so try_first_pass + account required /lib/security/pam_pwdb.so + password required /lib/security/pam_cracklib.so + password required /lib/security/pam_pwdb.so shadow nullok use_authtok + session optional /lib/security/pam_afs.so remainlifetime 10 + # ^^^^^^^^^^^^^^^^^ + #Wait 10 seconds before deleting the AFS tokens in order to give + #the programs of the X session some time to save their settings + #to AFS. + session required /lib/security/pam_pwdb.so + + + + + + + + After taking any necessary action, proceed to + Starting the BOS Server if you + are installing your first file server; + Starting Server Programs if you + are installing an additional file server machine; or + if you are installing a client. + + + + + + + Enabling kaserver based AFS Login on Solaris Systems + + 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). + + The following instructions explain how to alter the entries in the + PAM configuration file for each service for which you + wish to use AFS authentication. Other configurations possibly also + work, but the instructions specify the recommended and + tested configuration. + + + The instructions specify that you mark each entry as + optional. However, marking some + modules as optional can mean that they grant access to the + corresponding service even when the user does not meet all of the + module's requirements. In some operating system revisions, + for example, if you mark as optional the module that controls + login via a dial-up connection, it allows users to login without + providing a password. See the OpenAFS Release + Notes for a discussion of any limitations that apply to + this operating system. + + Also, with some operating system versions you must install + patches for PAM to interact correctly with certain + authentication programs. For details, see the + OpenAFS Release Notes. + + + The recommended AFS-related entries in the PAM configuration file + make use of one or more of the following three + attributes. + + Authentication Management + + + try_first_pass + + + This is a standard PAM attribute that can be included on + entries after the first one for a service; it directs + the module to use the password that was provided to the first + module. For the AFS module, it means that AFS + authentication succeeds if the password provided to the module + listed first is the user's correct AFS password. For + further discussion of this attribute and its alternatives, see + the operating system's PAM documentation. + + + + + ignore_root + + + This attribute, specific to the AFS PAM module, directs it + to ignore not only the local superuser root, but also any user with UID 0 + (zero). + + + + + setenv_password_expires + + + This attribute, specific to the AFS PAM module, sets the + environment variable PASSWORD_EXPIRES to the expiration + date of the user's AFS password, which is recorded in the + Authentication Database. + + + + + Perform the following steps to enable AFS login. + + Unpack the OpenAFS Binary Distribution for Solaris into the + /cdrom directory, if it is not + already. + Then change directory as indicated. + + # cd /usr/lib/security + + + + + Copy the AFS authentication library file to the + /usr/lib/security directory. Then + create a symbolic link to it whose name does not mention the + version. Omitting the version eliminates the need to edit + the PAM configuration file if you later update the library + file. + + If you use the AFS Authentication Server + (kaserver process): + + + # cp /tmp/afsdist/sun4x_56/lib/pam_afs.so.1 . + # ln -s pam_afs.so.1 pam_afs.so + + + If you use a Kerberos implementation of AFS authentication: + + + # cp /tmp/afsdist/sun4x_56/lib/pam_afs.krb.so.1 . + # ln -s pam_afs.krb.so.1 pam_afs.so + + + + + Edit the + Authentication management section + of the Solaris PAM configuration file, + /etc/pam.conf by convention. + The entries in this section have the value + auth in their second field. + + First edit the standard entries, which refer to the + Solaris PAM module (usually, the file /usr/lib/security/pam_unix.so.1) in their + fourth field. For each service for which you want to + use AFS authentication, edit the third field of its entry to read + optional. The + pam.conf file in the Solaris + distribution usually includes standard entries for the + login, + rlogin, and rsh services, for instance. + + If there are services for which you want to use AFS + authentication, but for which the pam.conf file does not already include a + standard entry, you must create that entry and place the + value optional in its third field. + For instance, the Solaris + pam.conf file does not usually + include standard entries for the + ftp or + telnet services. + + Then create an AFS-related entry for each service, placing it + immediately below the standard entry. The following + example shows what the + Authentication Management + section looks like after you have you edited or created entries + for the services mentioned previously. Note that the example AFS + entries appear on two lines + only for legibility. + + + login auth optional /usr/lib/security/pam_unix.so.1 + login auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root setenv_password_expires + rlogin auth optional /usr/lib/security/pam_unix.so.1 + rlogin auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root setenv_password_expires + rsh auth optional /usr/lib/security/pam_unix.so.1 + rsh auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root + ftp auth optional /usr/lib/security/pam_unix.so.1 + ftp auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root + telnet auth optional /usr/lib/security/pam_unix.so.1 + telnet auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root setenv_password_expires + + + + + If you use the Common Desktop Environment (CDE) on the + machine and want users to obtain an AFS token as they log + in, also add or edit the following four entries in the + Authentication management + section. Note that the AFS-related entries appear on two lines + here only for legibility. + + dtlogin auth optional /usr/lib/security/pam_unix.so.1 + dtlogin auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root + dtsession auth optional /usr/lib/security/pam_unix.so.1 + dtsession auth optional /usr/lib/security/pam_afs.so \ + try_first_pass ignore_root + + + + + Proceed to + Editing the File Systems Clean-up Script + on Solaris Systems in the server instructions if you are + installing your first file server; + Starting Server Programs if you + are installing an additional file server machine; or + Editing the File Systems Clean-up Script + on Solaris Systems in the client instructions if you are + installing a client. + + + + + + \ No newline at end of file diff --git a/doc/xml/QuickStartUnix/auqbg000.xml b/doc/xml/QuickStartUnix/auqbg000.xml index fbd031748..03f2d69e5 100644 --- a/doc/xml/QuickStartUnix/auqbg000.xml +++ b/doc/xml/QuickStartUnix/auqbg000.xml @@ -7,6 +7,7 @@ + ]> @@ -49,6 +50,7 @@ &chapter3; &chapter4; &appendixA; + &appendixB; &index; + Proceed to Starting the BOS Server + (or if referring to these instructions while installing an additional + file server machine, return to Starting Server + Programs). @@ -1196,11 +1123,6 @@ 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 @@ -1212,132 +1134,15 @@ obtain tokens by running the aklog command - - 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). @@ -1813,38 +1618,19 @@ login program and the graphical xdm login program both have the ability to grant AFS tokens, this ability relies upon the deprecated - kaserver authentication system. As this system is not recommended for - new installations, this is not documented here. + kaserver authentication system. Users who have been successfully authenticated via Kerberos 5 authentication may obtain AFS tokens following login by running the aklog command. - - - After taking any necessary action, proceed to Starting the BOS Server. + After taking any necessary action, proceed to + Starting the BOS Server. @@ -2155,11 +1941,6 @@ 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). - 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. @@ -2167,13 +1948,15 @@ Kerberos V service, and then use the AFS PAM module to obtain AFS credentials in the session section - - - Proceed to Starting the BOS Server (or if referring to these instructions while - installing an additional file server machine, return to Starting Server - Programs). - - + 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). @@ -2519,7 +2302,10 @@ proceed to Starting the BOS Server. + + + Enabling AFS Login on Solaris Systems enabling AFS login @@ -2560,32 +2346,6 @@ file server machine - - Solaris - - file systems clean-up script - - on file server machine - - - - file systems clean-up script (Solaris) - - file server machine - - - - scripts - - file systems clean-up (Solaris) - - file server machine - - - - - Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris 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. @@ -2611,137 +2371,39 @@ obtain tokens by running the aklog command - + Some Solaris distributions include a script that locates and removes unneeded files from various file systems. Its @@ -2853,7 +2515,7 @@ them. For a description of the contents and function of these directories and files, see the chapter in the OpenAFS Administration Guide about administering server machines. For further discussion of the mode bit settings, see Protecting Sensitive AFS Directories. - CD-ROM + Binary Distribution copying server files from @@ -3349,7 +3011,11 @@ kaserver was based on Kerberos v4, as such, it is not recommended for new cells. This guide assumes you have already configured a Kerberos v5 realm for your site, and details the procedures - required to use AFS with this realm. + required to use AFS with this realm. If you do wish to use + kaserver, please see the modifications + to these instructions detailed in + Starting the kaserver Database Server Process + The remaining instructions in this chapter include the -cell argument on all applicable @@ -3461,8 +3127,14 @@ - Initializing Cell Security + Initializing Cell Security + If you are working with an existing cell which uses + kaserver or Kerberos v4 for authentication, + please see + Initializing Cell Security with kaserver + for installation instructions which replace this section. + Now initialize the cell's security mechanisms. Begin by creating the following two entires in your site's Kerberos database: A generic administrative account, called admin by convention. If you choose to @@ -3496,9 +3168,11 @@ The following instructions do not configure all of the security mechanisms related to the AFS Backup System. See the chapter in the OpenAFS Administration Guide about configuring the Backup System. - The examples below assume you are using MIT Kerberos. Please refer to the documentation for your KDC's administrative interface if you are using a different vendor + The examples below assume you are using MIT Kerberos. Please refer + to the documentation for your KDC's administrative interface if you are + using a different vendor - + Enter kadmin interactive mode. @@ -3682,21 +3356,17 @@ Entry for principal afs/<cell name> with kvno 3 commands - bos listkeys bos commands - listkeys displaying - server encryption key - KeyFile file @@ -3717,50 +3387,32 @@ Entry for principal afs/<cell name> with kvno 3 You can safely ignore any error messages indicating that bos failed to get tickets or that authentication failed. - - + + + + + Initializing the Protection Database + + Now continue to configure your cell's security systems by + populating the Protection Database with the newly created + admin user, and permitting it + to issue priviledged commands on the AFS filesystem. + + + commands - pts createuser pts commands - createuser Protection Database - - - Issue the pts createuser command to create a Protection Database entry for the admin user. @@ -3779,13 +3431,11 @@ Entry for principal afs/<cell name> with kvno 3 commands - pts adduser pts commands - adduser @@ -3795,9 +3445,7 @@ Entry for principal afs/<cell name> with kvno 3 admin account - adding - to system:administrators group @@ -3816,25 +3464,18 @@ Entry for principal afs/<cell name> with kvno 3 system:administrators commands - bos restart - on first AFS machine bos commands - restart - on first AFS machine restarting server process - on first AFS machine server process - restarting - on first AFS machine @@ -4452,10 +4093,15 @@ and so may already be available at your site. fs newcell command to update the list in kernel memory directly; see the chapter in the OpenAFS Administration Guide about administering client machines. - The AFS distribution includes the file CellServDB.dist. It includes an entry for all AFS cells that agreed to share - their database server machine information at the time the distribution was - created. A copy of this file is maintained at grand.central.org, from where - updates may also be obtained. + The AFS distribution includes the file + CellServDB.dist. It includes an entry for + all AFS cells that agreed to share their database server machine + information at the time the distribution was + created. The definitive copy of this file is maintained at + grand.central.org, and updates may be obtained from + /afs/grand.central.org/service/CellServDB or + + http://grand.central.org/dl/cellservdb/CellServDB The CellServDB.dist file can be a good basis for the client CellServDB file, @@ -4815,7 +4461,7 @@ and so may already be available at your site. If you are running on a Fedora or RHEL based system, the - openafs-client initilization script behaves differently from that + openafs-client initialization script behaves differently from that described above. It sources /etc/sysconfig/openafs, in which the AFSD_ARGS variable may be set to contain any, or all, of the afsd options detailed. Note that this script does not support setting an OPTIONS @@ -4895,7 +4541,7 @@ and so may already be available at your site. a synthetic root (as discussed in Enabling Access to Foreign Cells). As some distributions ship with this enabled, it may be necessary to remove any occurences of the - -dynroot and + -dynroot and -afsdb options from both the AFS initialisation script and options file. If this functionality is required it may be renabled as detailed in @@ -5215,16 +4861,6 @@ and so may already be available at your site. - - - commands - - klog - - - - klog command - @@ -5235,7 +4871,26 @@ and so may already be available at your site. role="bold">Vn files in the cache directory. Subsequent Cache Manager initializations do not take nearly as long, because the Vn files already exist. + + + + + commands + aklog + + + aklog command + + + If you are working with an existing cell which uses + kaserver for authentication, + please recall the note in + Using this Appendix detailing the + substitution of kinit and + aklog with + klog. + As a basic test of correct AFS functioning, issue the kinit and aklog commands to authenticate @@ -6564,10 +6219,10 @@ and so may already be available at your site. addition to this enables DNS lookups for any cells that are not found in the client's CellServDB file. Both of these options are added to the AFS initialisation script, or options file, as detailed in - Configuring the Cache Manager. + Configuring the Cache Manager. - Adding foreign cells to a conventional root volume</root> + <title>Adding foreign cells to a conventional root volume In this section you create a mount point in your AFS filespace for the root.cell volume of each foreign cell that you want to enable your users to access. For users working on a client machine to access the cell, @@ -6673,25 +6328,35 @@ and so may already be available at your site. # ls /afs/foreign_cell - - If you wish to participate in the global AFS namespace, and only intend running one database server, please register your cell with grand.central.org at this time. To do so, email the CellServDB fragment - describing your cell to . If you intend - on deploying multiple database servers, please wait until you have installed - all of them before registering your cell. + describing your cell, together with a contact name and email address + for any queries, to cellservdb@grand.central.org. If you intend + on deploying multiple database servers, please wait until you have + installed all of them before registering your cell. If you wish to allow your cell to be located through DNS lookups, at this time you should also add the necessary configuration to your - DNS. + DNS. + + AFS database servers may be located by creating AFSDB records + in the DNS for the domain name corresponding to the name of your cell. + It's outside the scope of this guide to give an indepth description of + managing, or configuring, your site's DNS. You should consult the + documentation for your DNS server for further details on AFSDB + records. + + + + + Improving Cell Security cell @@ -6728,10 +6393,6 @@ and so may already be available at your site. controlling access by root superuser - - - - Improving Cell Security This section discusses ways to improve the security of AFS data in your cell. Also see the chapter in the OpenAFS @@ -6764,11 +6425,16 @@ and so may already be available at your site. Following are suggestions for managing AFS administrative privilege: - Create an administrative account for each administrator named something like - username.admin. Administrators authenticate under these - identities only when performing administrative tasks, and destroy the administrative tokens immediately after finishing - the task (either by issuing the unlog command, or the aklog command to adopt their regular identity). + Create an administrative account for each administrator named + something like + username.admin. + Administrators authenticate under these identities only when + performing administrative tasks, and destroy the administrative + tokens immediately after finishing the task (either by issuing the + unlog command, or the + kinit and + aklog commands to adopt their + regular identity). diff --git a/doc/xml/QuickStartUnix/auqbg006.xml b/doc/xml/QuickStartUnix/auqbg006.xml index 3b92d1028..392d623ff 100644 --- a/doc/xml/QuickStartUnix/auqbg006.xml +++ b/doc/xml/QuickStartUnix/auqbg006.xml @@ -54,8 +54,9 @@ - You can access the data on the AFS CD-ROMs, either through a local CD-ROM drive or via an NFS mount of a CD-ROM drive - attached to a machine that is accessible by network + You can access the data on the OpenAFS Binary Distribution for + your operating system, either on the local filesystem or via an NFS + mount of the distribution's contents. @@ -73,14 +74,25 @@ existing file server machine or is the first file server machine of its system type in your cell. The differences mostly concern the source for the needed binaries and files, and what portions of the Update Server you install: - On a new system type, you must load files and binaries from the AFS CD-ROM. You install the server portion of the - Update Server to make this machine the binary distribution machine for its system type. + On a new system type, you must load files and binaries from the + OpenAFS distribution. You may install the server portion of the + Update Server to make this machine the binary distribution machine + for its system type. - On an existing system type, you can copy files and binaries from a previously installed file server machine, rather - than from the CD-ROM. You install the client portion of the Update Server to accept updates of binaries, because a - previously installed machine of this type was installed as the binary distribution machine. + On an existing system type, you can copy files and binaries + from a previously installed file server machine, rather + than from the OpenAFS distribution. You may install the client + portion of the Update Server to accept updates of binaries, because a + previously installed machine of this type was installed as the binary + distribution machine. + + + On some system types, distribtution of the appropriate binaries + may be acheived using the system's own package management system. In + these cases, it is recommended that this system is used, rather than + installing the binaries by hand. @@ -93,7 +105,8 @@ To install a new file server machine, perform the following procedures: - Copy needed binaries and files onto this machine's local disk + Copy needed binaries and files onto this machine's local disk, + as required. @@ -114,42 +127,18 @@ - Start the appropriate portion of the Update Server + Start the appropriate portion of the Update Server, if + required Start the fs process, which incorporates three component processes: the File Server, Volume Server, and Salvager - - - Start the controller process (called runntp) for the Network Time Protocol Daemon, - which synchronizes clocks - After completing the instructions in this section, you can install database server functionality on the machine according to the instructions in Installing Database Server Functionality. - CD-ROM - - creating /cdrom directory - - server machine after first - - cdrom directory - - server machine after first - - file server machine, additional - - /cdrom directory - - creating - - /cdrom directory - - server machine after first - usr/afs directory server machine after first @@ -196,8 +185,12 @@ Creating AFS Directories and Performing Platform-Specific Procedures + If your operating systems AFS distribution is supplied as packages, + such as .rpms or .debs, you should just install those packages as detailed + in the previous chapter. + Create the /usr/afs and /usr/vice/etc directories on - the local disk. Subsequent instructions copy files from the AFS distribution CD-ROM into them, at the appropriate point for + the local disk. Subsequent instructions copy files from the AFS distribution into them, at the appropriate point for each system type. @@ -205,7 +198,7 @@ # mkdir /usr/afs/bin # mkdir /usr/vice # mkdir /usr/vice/etc - # mkdir /cdrom + # mkdir /tmp/afsdist As on the first file server machine, the initial procedures in installing an additional file server machine vary a good @@ -300,10 +293,14 @@ - Mount the AFS CD-ROM for AIX on the local /cdrom directory. For instructions on - mounting CD-ROMs (either locally or remotely via NFS), see your AIX documentation. Then change directory as indicated. - - # cd /cdrom/rs_aix42/root.client/usr/vice/etc + Unpack the distribution tarball. The examples below assume + that you have unpacked the files into the + /tmp/afsdist directory. If you + pick a different location, substitute this in all of the following + examples. Once you have unpacked the distribution, + change directory as indicated. + + # cd /tmp/afsdist/rs_aix42/root.client/usr/vice/etc @@ -426,12 +423,19 @@ - Move the AIX fsck program helper to a safe location and install the version - from the AFS distribution in its place. The AFS CD-ROM must still be mounted at the /cdrom directory. + On systems prior to AIX 5.1, move the AIX + fsck program helper to a safe + location and install the version from the AFS distribution in + its place. Note that on AIX 5.1, and later, systems this step is + not required, and the v3fshelper + program is not shipped for these systems. + + The AFS binary distribution must still be available in the + /tmp/afsdist directory. + # cd /sbin/helpers # mv v3fshelper v3fshelper.noafs - # cp -p /cdrom/rs_aix42/root.server/etc/v3fshelper v3fshelper + # cp -p /tmp/afsdist/rs_aix42/root.server/etc/v3fshelper v3fshelper @@ -454,7 +458,8 @@ If the machine's hardware and software configuration exactly matches another HP-UX machine on which AFS is already built into the kernel, you can copy the kernel from that machine to this one. In general, however, it is better to build AFS - modifications into the kernel on each machine according to the following instructions. + modifications into the kernel on each machine according to the following instructions. + incorporating AFS kernel extensions @@ -495,10 +500,14 @@ - Mount the AFS CD-ROM for HP-UX on the local /cdrom directory. For instructions - on mounting CD-ROMs (either locally or remotely via NFS), see your HP-UX documentation. Then change directory as - indicated. - # cd /cdrom/hp_ux110/root.client + Unpack the OpenAFS HP-UX distribution tarball. The examples + below assume that you have unpacked the files into the + /tmp/afsdist directory. If you + pick a different location, substitute this in all of the following + examples. Once you have unpacked the distribution, change + directory as indicated. + + # cd /tmp/afsdist/hp_ux110/root.client @@ -705,7 +714,7 @@ Copy the AFS-modified version of the fsck program (the vfsck binary) and related files from the distribution directory to the new AFS-specific command directory. - # cp -p /cdrom/hp_ux110/root.server/etc/* . + # cp -p /tmp/afsdist/hp_ux110/root.server/etc/* . @@ -796,10 +805,14 @@ Prepare for incorporating AFS into the kernel by performing the following procedures. - Mount the AFS CD-ROM for IRIX on the /cdrom directory. For instructions - on mounting CD-ROMs (either locally or remotely via NFS), see your IRIX documentation. Then change directory as - indicated. - # cd /cdrom/sgi_65/root.client + Unpack the OpenAFS IRIX distribution tarball. The + examples below assume that you have unpacked the files into + the /tmp/afsdist + directory. If you pick a different location, substitue this + in all of the following examples. Once you have unpacked + the distribution, change directory as indicated. + + # cd /tmp/afsdist/sgi_65/root.client @@ -1150,7 +1163,34 @@ Begin by running the AFS initialization script to call the insmod 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. + replace the Linux fsck program. + + The procedure for starting up OpenAFS depends upon your distribution + + + For Fedora and RedHat Enterprise Linux systems (or their + derivateds), download and install the RPM set for your operating system + from the OpenAFS distribution site. You will need the + openafs and + openafs-server packages, along + with an openafs-kernel package + matching your current, running, kernel. If you wish to install + client functionality, you will also require the + openafs-client package. + + You can find the version of your current kernel by running + + # uname -r +2.6.20-1.2933.fc6 + + + Once downloaded, the packages may be installed with the + rpm command + + # rpm -U openafs-* openafs-client-* openafs-server-* openafs-kernel-* + + + incorporating AFS kernel extensions @@ -1182,16 +1222,17 @@ on add'l server machine - - - Mount the AFS CD-ROM for Linux on the local /cdrom directory. For instructions - on mounting CD-ROMs (either locally or remotely via NFS), see your Linux documentation. Then change directory as - indicated. - # cd /cdrom/i386_linux22/root.client/usr/vice/etc + For systems which are provided as a tarball, or built from + source, unpack the distribution tarball. The examples below assume + that you have unpacked the files into the + /tmp/afsdistdirectory. If you + pick a different location, substitute this in all of the following + examples. Once you have unpacked the distribution, + change directory as indicated. + + # cd /tmp/afsdist/linux/root.client/usr/vice/etc - - Copy the AFS kernel library files to the local /usr/vice/etc/modload directory. The filenames for the libraries have the format libafs-version.o, where @@ -1200,21 +1241,15 @@ kernel. # cp -rp modload /usr/vice/etc - - - + Copy the AFS initialization script to the local directory for initialization files (by convention, /etc/rc.d/init.d on Linux machines). Note the removal of the .rc extension as you copy the script. # cp -p afs.rc /etc/rc.d/init.d/afs - - Run the AFS initialization script to load AFS extensions into the kernel. You can ignore any error messages - about the inability to start the BOS Server or the Cache Manager or AFS client. - # /etc/rc.d/init.d/afs start - + configuring AFS server partition on server machine after first @@ -1238,10 +1273,7 @@ AFS server partition on add'l server machine - - - - + Create a directory called /vicepxx for each AFS server partition you are configuring (there must be at least one). Repeat the command for each partition. @@ -1284,7 +1316,7 @@ Proceed to Starting Server Programs. - + @@ -1326,10 +1358,14 @@ - Mount the AFS CD-ROM for Solaris on the /cdrom directory. For instructions on - mounting CD-ROMs (either locally or remotely via NFS), see your Solaris documentation. Then change directory as - indicated. - # cd /cdrom/sun4x_56/root.client/usr/vice/etc + Unpack the OpenAFS Solaris distribution tarball. The examples + below assume that you have unpacked the files into the + /tmp/afsdist directory. If you + pick a diferent location, substitute this in all of the following + exmaples. Once you have unpacked the distribution, change directory + as indicated. + + # cd /tmp/afsdist/sun4x_56/root.client/usr/vice/etc @@ -1630,7 +1666,7 @@ - CD-ROM + Binary Distribution copying server files from @@ -1648,26 +1684,36 @@ Copy file server binaries to the local /usr/afs/bin directory. - On a machine of an existing system type, you can either load files from the AFS CD-ROM or use a remote file - transfer protocol to copy files from an existing server machine of the same system type. To load from the CD-ROM, - see the instructions just following for a machine of a new system type. If using a remote file transfer protocol, - copy the complete contents of the existing server machine's /usr/afs/bin + On a machine of an existing system type, you can either + copy files from the OpenAFS binary distribution or use a + remote file transfer protocol to copy files from an existing + server machine of the same system type. To load from the + binary distribution, see the instructions just following for + a machine of a new system type. If using a remote file + transfer protocol, copy the complete contents of the + existing server machine's + /usr/afs/bin directory. - On a machine of a new system type, you must use the following instructions to copy files from the AFS - CD-ROM. + If you are working from a tarball distribtion, rather + than one distributed in a packaged format, you must use the + following instructions to copy files from + the OpenAFS Binary Distribution. + - On the local /cdrom directory, mount the AFS CD-ROM for this - machine's system type, if it is not already. For instructions on mounting CD-ROMs (either locally or - remotely via NFS), consult the operating system documentation. + Unpack the distribution tarball. The examples + below assume that you have unpacked the files into the + /tmp/afsdist + directory. If you pick a different location, substitute + this in all of the following examples. - Copy files from the CD-ROM to the local /usr/afs directory. + Copy files from the distribution to the local /usr/afs directory. - # cd /cdrom/sysname/root.server/usr/afs + # cd /tmp/afsdist/sysname/root.server/usr/afs # cp -rp * /usr/afs @@ -1761,10 +1807,15 @@ - Copy the contents of the /usr/afs/etc directory from an existing file server - machine, using a remote file transfer protocol such as ftp or NFS. If you use a system - control machine, it is best to copy the contents of its /usr/afs/etc directory. If you - choose not to run a system control machine, copy the directory's contents from any existing file server machine. + Copy the contents of the + /usr/afs/etc directory from an + existing file server machine, using a remote file transfer protocol + such as sftp or + scp. If you use a system + control machine, it is best to copy the contents of its + /usr/afs/etc directory. If you + choose not to run a system control machine, copy the directory's + contents from any existing file server machine. BOS Server @@ -1878,8 +1929,16 @@ - Create an instance of the Update Server to handle distribution of the file server binaries - stored in the /usr/afs/bin directory. + Create an instance of the Update + Server to handle distribution of the file server binaries + stored in the /usr/afs/bin + directory. If your architecture using a package management system + such as 'rpm' or 'apt' to maintain its binaries, note that + distributing binaries via this system may interfere with your local + package management tools. + + + If this is the first file server machine of its AFS system type, create the upserver process as an instance of the server portion of the Update Server. It distributes @@ -1907,14 +1966,14 @@ By default, the Update Server performs updates every 300 seconds (five minutes). Use the -t argument to specify an different number of seconds. - + # ./bos create <machine name> upclientbin simple \ "/usr/afs/bin/upclient <binary distribution machine> \ [-t <time>] -clear /usr/afs/bin" -cell <cell name> -noauth - + runntp process @@ -1944,6 +2003,16 @@ + + + Historically, AFS provided its own version of the + Network Time Protocol Daemon. Whilst this is still provided for + existing sites, we recommend that you configure and run your + own timeservice independently of AFS. The instructions below are + provided for those sites still reliant upon OpenAFS's ntp system. + + + Start the runntp process, which configures the Network Time Protocol Daemon (NTPD) to choose a database server machine chosen randomly from the local /usr/afs/etc/CellServDB file as its time source. In the standard configuration, the first @@ -2076,7 +2145,7 @@ role="bold">/usr/afsws to the appropriate location in the AFS file tree) on this machine itself. If you also want to create AFS volumes to house UNIX system binaries for the new system type, see Storing System Binaries in AFS. - CD-ROM + Binary Distribution copying client files from @@ -2097,20 +2166,31 @@ Copy client binaries and files to the local disk. - On a machine of an existing system type, you can either load files from the AFS CD-ROM or use a remote file - transfer protocol to copy files from an existing server machine of the same system type. To load from the CD-ROM, - see the instructions just following for a machine of a new system type. If using a remote file transfer protocol, - copy the complete contents of the existing client machine's /usr/vice/etc + On a machine of an existing system type, you can either + load files from the OpenAFS Binary Distribution or use a + remote file transfer protocol to copy files from an existing + server machine of the same system type. To load from the + binary distribution, see the instructions just following + for a machine of a new system type. If using a remote file + transfer protocol, copy the complete contents of the existing + client machine's + /usr/vice/etc directory. - On a machine of a new system type, you must use the following instructions to copy files from the AFS - CD-ROM. + On a machine of a new system type, you must use the + following instructions to copy files from the OpenAFS + Binary Distribution. If your distribution is provided in + a packaged format, then simply installing the packages will + perform the necessary actions. + - On the local /cdrom directory, mount the AFS CD-ROM for this - machine's system type, if it is not already. For instructions on mounting CD-ROMs (either locally or - remotely via NFS), consult the operating system documentation. + Unpack the distribution tarball. The examples + below assume that you have unpacked the files into the + /tmp/afsdist + directory. If you pick a different location, substitute + this in all of the following examples. @@ -2132,7 +2212,7 @@ command. - # cd /cdrom/sysname/root.client/usr/vice/etc + # cd /tmp/afsdist/sysname/root.client/usr/vice/etc # cp -p * /usr/vice/etc # cp -rp C /usr/vice/etc @@ -2222,9 +2302,14 @@ - Create the /usr/vice/etc/CellServDB file. Use a network file transfer program - such as ftp or NFS to copy it from one of the following sources, which are listed in - decreasing order of preference: + Create the + /usr/vice/etc/CellServDB file. + Use a network file transfer program such as + sftp or + scp to copy it from + one of the following sources, which are listed in + decreasing order of preference: + Your cell's central CellServDB source file (the conventional location is /afs/cellname - The global CellServDB file maintained by the AFS Product Support - group + The global CellServDB + file maintained at grand.central.org @@ -2241,12 +2326,16 @@ - The CellServDB.sample file included in the - sysname/root.client/usr/vice/etc directory of each AFS - CD-ROM; add an entry for the local cell by following the instructions in Creating the - Client CellServDB File + The CellServDB.sample + file included in the + sysname/root.client/usr/vice/etc + directory of each OpenAFS distribution; add an entry for the + local cell by following the instructions in + Creating the Client CellServDB File + - + + cache @@ -2357,7 +2446,7 @@ - On Linux systems, copy the afsd options file from the On non-packaged Linux systems, copy the afsd options file from the /usr/vice/etc directory to the /etc/sysconfig directory, removing the .conf extension as you do so. # cp /usr/vice/etc/afs.conf /etc/sysconfig/afs @@ -2381,9 +2470,17 @@ - On Linux systems, /etc/sysconfig/afs (the On Fedora and RHEL systems, + /etc/sysconfig/openafs. + Note that this file has a different format from a standard + afsd options file. + + + + On non-packaged Linux systems, /etc/sysconfig/afs (the afsd options file) + On Solaris systems, /etc/init.d/afs @@ -2393,10 +2490,11 @@ Use one of the methods described in Configuring the Cache Manager to add the following flags to the afsd command line. If you intend for the machine to remain an AFS client, also set any performance-related arguments you wish. + Add the -memcache flag if the machine is to use a memory cache. @@ -2406,6 +2504,13 @@ Add the -verbose flag to display a trace of the Cache Manager's initialization on the standard output stream. + + Add the --dynroot or + --afsdb options if you + wish to have a synthetic AFS root, as discussed in + Enabling Access to Foreign Cells + + @@ -2681,6 +2786,42 @@ on add'l server machine + On Fedora or RHEL Linux systems: + + + Reboot the machine and log in again as the local superuser root. + + # cd / + # shutdown -r now + login: root + Password: root_password + + + + + Run the OpenAFS initialization scripts. + # /etc/rc.d/init.d/openafs-client start + # /etc/rc.d/init.d/openafs-server start + + + + + Issue the chkconfig + command to activate the + openafs-client and + openafs-server configuration + variables. Based on the instruction in the AFS initialization + files that begins with the string + #chkconfig, the command + automatically creates the symbolic links that incorporate the + script into the Linux startup and shutdown sequence. + + # /sbin/chkconfig --add openafs-client + # /sbin/chkconfig --add openafs-server + + + + On Linux systems: Reboot the machine and log in again as the local superuser root. @@ -2693,7 +2834,7 @@ - Run the AFS initialization script. + Run the OpenAFS initialization script. # /etc/rc.d/init.d/afs start @@ -2766,7 +2907,7 @@ (Optional) There are now copies of the AFS initialization file in both the /usr/vice/etc and /etc/init.d directories. If you want to avoid potential confusion by guaranteeing that they are always the same, create a link between them. - You can always retrieve the original script from the AFS CD-ROM if necessary. + You can always retrieve the original script from the OpenAFS Binary Distribution if necessary. # cd /usr/vice/etc # rm afs.rc # ln -s /etc/init.d/afs afs.rc @@ -2806,7 +2947,7 @@ Installing Database Server Functionality This section explains how to install database server functionality. Database server machines have two defining - characteristics. First, they run the Authentication Server, Protection Server, and Volume Location (VL) Server processes. They + characteristics. First, they run the Protection Server, and Volume Location (VL) Server processes. They also run the Backup Server if the cell uses the AFS Backup System, as is assumed in these instructions. Second, they appear in the CellServDB file of every machine in the cell (and of client machines in foreign cells, if they are to access files in this cell). @@ -2824,7 +2965,7 @@ Guide about maintaining server encryption keys. The instructions in this section assume that the machine on which you are installing database server functionality - is already a file server machine. Contact the AFS Product Support group to learn how to install database server + is already a file server machine. Contact the OpenAFS mailing list to learn how to install database server functionality on a non-file server machine. @@ -2898,7 +3039,7 @@ - Start the database server processes (Authentication Server, Backup Server, Protection Server, and Volume Location + Start the database server processes (Backup Server, Protection Server, and Volume Location Server) @@ -2907,8 +3048,15 @@ - Notify the AFS Product Support group that you have installed a new database server machine + If required, request that grand.central.org add details of + your new database server machine to the global CellServDB + + + If required, add details of your new database server to the + AFS database location records in your site's DNS + + @@ -2945,10 +3093,13 @@ You can perform the following instructions on either a server or client machine. Login as an AFS administrator who - is listed in the /usr/afs/etc/UserList file on all server machines. - % klog admin_user + is listed in the /usr/afs/etc/UserList file on all server machines. + + % kinit admin_user Password: admin_password - + % aklog + + @@ -3063,19 +3214,8 @@ option is to copy over the central update source (which you updated in Step 5), with or without using the package program. To update the machine's kernel memory list, you can either reboot after changing the CellServDB file or issue the fs - newcell command. - Authentication Server - - starting - - new db-server machine - - starting - - Authentication Server - - new db-server machine - + newcell command. + database server machine starting database server processes @@ -3093,27 +3233,25 @@ database server machine - + - Start the Authentication Server (the kaserver process). - - % bos create <machine name> kaserver simple /usr/afs/bin/kaserver - - Backup Server - - starting - - new db-server machine - - starting - - Backup Server - - new db-server machine - + If you are running a cell which still relies upon + kaserver see + Starting the Authentication Service + for an additional installation step. + + Backup Server + starting + new db-server machine + + starting + Backup Server + new db-server machine + + Start the Backup Server (the buserver process). You must perform other configuration procedures before actually using the AFS Backup System, as detailed in the OpenAFS Administration Guide. @@ -3218,12 +3356,15 @@ - Send the new database server machine's name and IP address to the AFS Product Support - group. - - If you wish to participate in the AFS global name space, your cell's entry appear in a CellServDB file that the AFS Product Support group makes available to all AFS sites. Otherwise, - they list your cell in a private file that they do not share with other AFS sites. + If you wish to participate in the AFS + global name space, send the new database server machine's name and + IP address to grand.central.org. Do so, by emailing an updated + CellServDB fragment for your cell + to cellservdb@grand.central.org + More details on the registration procedures for the + CellServDB maintained by grand.central.org are available from + + http://grand.central.org/csdb.html @@ -3267,7 +3408,9 @@ - Notify the AFS Product Support group that you are decommissioning a database server machine + If you participate in the global AFS namespace, notify + grand.central.org that you are decommissioning a database server + machine @@ -3307,9 +3450,11 @@ You can perform the following instructions on either a server or client machine. Login as an AFS administrator who - is listed in the /usr/afs/etc/UserList file on all server machines. - % klog admin_user + is listed in the /usr/afs/etc/UserList file on all server machines. + + % kinit admin_user Password: admin_password + % aklog @@ -3325,11 +3470,11 @@ - Send the revised list of your cell's database server machines to the AFS Product Support - group. + If your cell is included in the global + CellServDB, send the revised list of + your cell's database server machines to grand.central.org - This step is particularly important if your cell is included in the global CellServDB file. If the administrators in foreign cells do not learn about the change in your cell, + If the administrators in foreign cells do not learn about the change in your cell, they cannot update the CellServDB file on their client machines. Users in foreign cells continue to send database requests to the decommissioned machine, which creates needless network traffic and activity on the machine. Also, the users experience time-out delays while their request is forwarded to a valid database server @@ -3492,7 +3637,7 @@ delete command to remove the entries for database server processes from the BosConfig file. This step is unnecessary if you plan to restart the database server functionality on this machine in future. - % bos delete <machine name> kaserver buserver ptserver vlserver + % bos delete <machine name> buserver ptserver vlserver commands @@ -3520,7 +3665,7 @@ Issue the bos restart command on every database server - machine in the cell, to restart the Authentication, Backup, Protection, and VL Servers. This forces the election of a Ubik + machine in the cell, to restart the Backup, Protection, and VL Servers. This forces the election of a Ubik coordinator for each process, ensuring that the remaining database server processes recognize that the machine is no longer a database server. @@ -3531,7 +3676,7 @@ the lowest IP address. - % bos restart <machine name> kaserver buserver ptserver vlserver + % bos restart <machine name> buserver ptserver vlserver If an error occurs, restart all server processes on the database server machines again by using one of the following diff --git a/doc/xml/QuickStartUnix/auqbg007.xml b/doc/xml/QuickStartUnix/auqbg007.xml index 14097084b..c1f0ee185 100644 --- a/doc/xml/QuickStartUnix/auqbg007.xml +++ b/doc/xml/QuickStartUnix/auqbg007.xml @@ -64,15 +64,15 @@ - CD-ROM + Binary Distribution - creating /cdrom directory + creating /tmp/afsdist directory client machine - cdrom directory + afsdist directory client machine @@ -80,13 +80,13 @@ client machine - /cdrom directory + /tmp/afsdist directory creating - /cdrom directory + /tmp/afsdist directory client machine @@ -115,14 +115,14 @@ Creating AFS Directories on the Local Disk - Create the /usr/vice/etc directory on the local disk, to house client binaries and - configuration files. Subsequent instructions copy files from the AFS CD-ROM into them. Create the /cdrom directory as a mount point for the CD-ROM, if it does not already exist. + If you are not installing from a packaged distribution, create the /usr/vice/etc directory on the local disk, to house client binaries and + configuration files. Subsequent instructions copy files from the OpenAFS binary distribution into them. Create the /tmp/afsdist directory as a location to uncompress this distribution, if it does not already exist. # mkdir /usr/vice # mkdir /usr/vice/etc - # mkdir /cdrom + # mkdir /tmp/afsdist @@ -135,7 +135,7 @@ Also modify the machine's authentication system so that users obtain an AFS token as they log into the local file system. Using AFS is simpler and more convenient for your users if you make the modifications on all client machines. Otherwise, users - must perform a two-step login procedure (login to the local file system and then issue the klog + must perform a two or three step login procedure (login to the local system, obtain Kerberos credentials, and then issue the klog command). For further discussion of AFS authentication, see the chapter in the OpenAFS Administration Guide about cell configuration and administration issues. @@ -253,13 +253,16 @@ correctly initializes the Cache Manager, then configure the AIX inittab file so that the script runs automatically at reboot. - Mount the AFS CD-ROM for AIX on the local /cdrom directory. For instructions on - mounting CD-ROMs (either locally or remotely via NFS), see your AIX documentation. Then change directory as indicated. - - # cd /cdrom/rs_aix42/root.client/usr/vice/etc + Unpack the distribution tarball. The examples below assume + that you have unpacked the files into the + /tmp/afsdist directory. If you + pick a different location, substitute this in all of the following + examples. Once you have unpacked the distribution, + change directory as indicated. + + # cd /tmp/afsdist/rs_aix42/root.client/usr/vice/etc - Copy the AFS kernel library files to the local /usr/vice/etc/dkload directory, and the AFS initialization script to the /etc directory. @@ -302,105 +305,21 @@ Enabling AFS Login on AIX Systems - Now incorporate AFS into the AIX secondary authentication system. - - Issue the ls command to verify that the afs_dynamic_auth and afs_dynamic_kerbauth programs are installed - in the local /usr/vice/etc directory. - # ls /usr/vice/etc - + In modern AFS installations, you should be using Kerberos v5 + for user login, and obtaining AFS tokens following this authentication + step. + + There are currently no instructions available on configuring AIX to + automatically obtain AFS tokens at login. Following login, users can + obtain tokens by running the aklog + command - If the files do not exist, mount the AFS CD-ROM for AIX (if it is not already), change directory as indicated, and - copy them. - - - # cd /cdrom/rs_aix42/root.client/usr/vice/etc - # cp -p afs_dynamic* /usr/vice/etc - - - - - Edit the local /etc/security/user file, making changes to the indicated stanzas: - - - In the default stanza, set the registry attribute to DCE (not to AFS), as follows: - registry = DCE - - - - - In the default stanza, set the SYSTEM attribute as indicated. - - If the machine is an AFS client only, set the following value: - - - SYSTEM = "AFS OR (AFS[UNAVAIL] AND compat[SUCCESS])" - - - If the machine is both an AFS and a DCE client, set the following value (it must appear on a single line in - the file): - - - SYSTEM = "DCE OR DCE[UNAVAIL] OR AFS OR (AFS[UNAVAIL] \ - AND compat[SUCCESS])" - - - - - In the root stanza, set the registry - attribute as follows. It enables the local superuser root to log into the local - file system only, based on the password listed in the local password file. - root: - registry = files - - - - - - - Edit the local /etc/security/login.cfg file, creating or editing the indicated - stanzas: - - In the DCE stanza, set the program - attribute as follows. - - If you use the AFS Authentication Server (kaserver process): - - - DCE: - program = /usr/vice/etc/afs_dynamic_auth - - - If you use a Kerberos implementation of AFS authentication: - - - DCE: - program = /usr/vice/etc/afs_dynamic_kerbauth - - - - - In the AFS stanza, set the program - attribute as follows. - - If you use the AFS Authentication Server (kaserver process): - - - AFS: - program = /usr/vice/etc/afs_dynamic_auth - - - If you use a Kerberos implementation of AFS authentication: - - - AFS: - program = /usr/vice/etc/afs_dynamic_kerbauth - - - - + Sites which still require kaserver + or external Kerberos v4 authentication should consult + Enabling kaserver based AFS Login on AIX Systems + for details of how to enable AIX login. + Proceed to Loading and Creating Client Files. @@ -501,10 +420,14 @@ - Mount the AFS CD-ROM for HP-UX on the local /cdrom directory. For instructions on - mounting CD-ROMs (either locally or remotely via NFS), see your HP-UX documentation. Then change directory as indicated. + Unpack the OpenAFS HP-UX distribution tarball. The examples + below assume that you have unpacked the files into the + /tmp/afsdist directory. If you + pick a different location, substitute this in all of the following + examples. Once you have unpacked the distribution, change directory + as indicated. - # cd /cdrom/hp_ux110/root.client + # cd /tmp/afsdist/hp_ux110/root.client @@ -624,141 +547,28 @@ 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). - - The following instructions explain how to alter the entries in the PAM configuration file for each service for which you - wish to use AFS authentication. Other configurations possibly also work, but the instructions specify the recommended and - tested configuration. - - - The instructions specify that you mark each entry as optional. However, marking some - modules as optional can mean that they grant access to the corresponding service even when the user does not meet all of the - module's requirements. In some operating system revisions, for example, if you mark as optional the module that controls - login via a dial-up connection, it allows users to login without providing a password. See the OpenAFS Release - Notes for a discussion of any limitations that apply to this operating system. - - Also, with some operating system versions you must install patches for PAM to interact correctly with certain - authentication programs. For details, see the OpenAFS Release Notes. - - - The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three - attributes. - - try_first_pass - - - This is a standard PAM attribute that can be included on entries after the first one for a service; it directs - the module to use the password that was provided to the first module. For the AFS module, it means that AFS - authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For - further discussion of this attribute and its alternatives, see the operating system's PAM documentation. - - - - - ignore_root - - - This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser root, but also any user with UID 0 (zero). - - - - - setenv_password_expires - - - This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD_EXPIRES to the expiration - date of the user's AFS password, which is recorded in the Authentication Database. - - - - - Perform the following steps to enable AFS login. - - Mount the AFS CD-ROM for HP-UX on the /cdrom directory, if it is not already. - Then change directory as indicated. - # cd /usr/lib/security - - - - - Copy the AFS authentication library file to the /usr/lib/security directory. Then - create a symbolic link to it whose name does not mention the version. Omitting the version eliminates the need to edit - the PAM configuration file if you later update the library file. - - If you use the AFS Authentication Server (kaserver process) in the cell: - - - # cp /cdrom/hp_ux110/lib/pam_afs.so.1 . - # ln -s pam_afs.so.1 pam_afs.so - - - If you use a Kerberos implementation of AFS authentication: - - - # cp /cdrom/hp_ux110/lib/pam_afs.krb.so.1 . - # ln -s pam_afs.krb.so.1 pam_afs.so - - - - - Edit the Authentication management section of the HP-UX PAM configuration file, - /etc/pam.conf by convention. The entries in this section have the value - auth in their second field. - - First edit the standard entries, which refer to the HP-UX PAM module (usually, the file /usr/lib/security/libpam_unix.1) in their fourth field. For each service for which you want to - use AFS authentication, edit the third field of its entry to read optional. The - pam.conf file in the HP-UX distribution usually includes standard entries for the - login and ftp services, for instance. - - If there are services for which you want to use AFS authentication, but for which the pam.conf file does not already include a standard entry, you must create that entry and place the - value optional in its third field. For instance, the HP-UX pam.conf file does not usually include standard entries for the remsh or telnet services. - - Then create an AFS-related entry for each service, placing it immediately below the standard entry. The following - example shows what the Authentication Management section looks like after you have you - edited or created entries for the services mentioned previously. Note that the example AFS entries appear on two lines - only for legibility. - - - login auth optional /usr/lib/security/libpam_unix.1 - login auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root setenv_password_expires - ftp auth optional /usr/lib/security/libpam_unix.1 - ftp auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root - remsh auth optional /usr/lib/security/libpam_unix.1 - remsh auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root - telnet auth optional /usr/lib/security/libpam_unix.1 - telnet auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root setenv_password_expires - - - - - If you use the Common Desktop Environment (CDE) on the machine and want users to obtain an AFS token as they log - in, also add or edit the following four entries in the Authentication management - section. Note that the AFS-related entries appear on two lines here only for legibility. - dtlogin auth optional /usr/lib/security/libpam_unix.1 - dtlogin auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root - dtaction auth optional /usr/lib/security/libpam_unix.1 - dtaction auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root - - - + 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 + + If you are at a site which still requires + kaserver or external Kerberos v4 based + authentication, please consult + Enabling kaserver based AFS Login on HP-UX systems + for further installation instructions. + Proceed to Loading and Creating Client Files. - + + incorporating AFS kernel extensions @@ -805,13 +615,16 @@ In preparation for either dynamic loading or kernel building, perform the following procedures: - Mount the AFS CD-ROM for IRIX on the /cdrom directory. For instructions on mounting - CD-ROMs (either locally or remotely via NFS), see your IRIX documentation. Then change directory as indicated. - - # cd /cdrom/sgi_65/root.client + Unpack the OpenAFS IRIX distribution tarball. The examples + below assume that you have unpacked the files into the + /tmp/afsdist directory. If you + pick a different location, substitue this in all of the following + examples. Once you have unpacked the distribution, change directory + as indicated. + + # cd /tmp/afsdist/sgi_65/root.client - Copy the AFS initialization script to the local directory for initialization files (by convention, /etc/init.d on IRIX machines). Note the removal of the .rc @@ -892,7 +705,7 @@ The ml program is the dynamic kernel loader provided by SGI for IRIX systems. If you use it rather than building AFS modifications into a static kernel, then for AFS to function correctly the ml program must run each time the machine reboots. Therefore, the AFS initialization script (included - on the AFS CD-ROM) invokes it automatically when the afsml configuration variable is + in the OpenAFS Binary Distribution) invokes it automatically when the afsml configuration variable is activated. In this section you activate the variable and run the script. In a later section you verify that the script correctly initializes the Cache Manager, then create the links that @@ -1073,30 +886,24 @@ Enabling AFS Login on IRIX Systems - The standard IRIX command-line login program and the graphical xdm login program both automatically grant an AFS token when AFS is incorporated into the machine's - kernel. However, some IRIX distributions use another login utility by default, and it does not necessarily incorporate the - required AFS modifications. If that is the case, you must disable the default utility if you want AFS users to obtain AFS - tokens at login. For further discussion, see the OpenAFS Release Notes. - - If you configure the machine to use an AFS-modified login utility, then the afsauthlib.so and afskauthlib.so files (included in the AFS - distribution) must reside in the /usr/vice/etc directory. Issue the ls command to verify. - - - # ls /usr/vice/etc - - - If the files do not exist, mount the AFS CD-ROM for IRIX (if it is not already), change directory as indicated, and copy - them. - - - # cd /cdrom/sgi_65/root.client/usr/vice/etc - # cp -p *authlib* /usr/vice/etc - - - After taking any necessary action, proceed to Loading and Creating Client Files. + Whilst the standard IRIX command-line + login program and the + graphical xdm login program both have + the ability to grant AFS tokens, this ability relies upon the deprecated + kaserver authentication system. As this system is not recommended for + new installations, this is not documented here. + + Users who have been successfully authenticated via Kerberos 5 + authentication may obtain AFS tokens following login by running the + aklog command. + + If you are at a site which still requires + kaserver or external Kerberos v4 based + authentication, please consult + Enabling kaserver based AFS Login on Linux Systems + for further installation instructions. + + Proceed to Loading and Creating Client Files. incorporating AFS kernel extensions @@ -1164,21 +971,60 @@ Loading AFS into the Linux Kernel - The insmod program is the dynamic kernel loader for Linux. Linux does not support + The modprobe program is the dynamic kernel loader for Linux. Linux does not support incorporation of AFS modifications during a kernel build. - For AFS to function correctly, the insmod program must run each time the machine - reboots, so the AFS initialization script (included on the AFS CD-ROM) invokes it automatically. The script also includes + For AFS to function correctly, the modprobe program must run each time the machine + reboots, so your distributions's AFS initialization script invokes it automatically. The script also includes commands that select the appropriate AFS library file automatically. In this section you run the script. In a later section you also verify that the script correctly initializes the Cache Manager, then activate a - configuration variable, which results in the script being incorporated into the Linux startup and shutdown sequence. - - - Mount the AFS CD-ROM for Linux on the local /cdrom directory. For instructions on - mounting CD-ROMs (either locally or remotely via NFS), see your Linux documentation. Then change directory as indicated. - - # cd /cdrom/i386_linux22/root.client/usr/vice/etc + configuration variable, which results in the script being incorporated into the Linux startup and shutdown sequence. + + The procedure for starting up OpenAFS depends upon your distribution + + Fedora and RedHat Enterprise Linux + OpenAFS ships RPMS for all current Fedora and RHEL releases. + + + Download and install the RPM set for your operating system. + RPMs are available from the OpenAFS web site. You will need the + openafs and + openfs-client packages, along + with an openafs-kernel package + matching your current, running ,kernel. + + You can find the version of your current kernel by running + + # uname -r +2.6.20-1.2933.fc6 + + + Once downloaded, the packages may be installed with the + rpm command + + # rpm -U openafs-* openafs-client-* openafs-server-* openafs-kernel-* + + + + + + + Systems packaged as tar files + If you are running a system where the OpenAFS Binary Distribution + is provided as a tar file, or where you have built the system from + source yourself, you need to install the relevant components by hand + + + + Unpack the distribution tarball. The examples below assume + that you have unpacked the files into the + /tmp/afsdistdirectory. If you + pick a different location, substitute this in all of the following + examples. Once you have unpacked the distribution, + change directory as indicated. + + # cd /tmp/afsdist/linux/root.client/usr/vice/etc @@ -1201,13 +1047,16 @@ + + + @@ -1217,343 +1066,21 @@ 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). - - The following instructions explain how to alter the entries in the PAM configuration file for each service for which you - wish to use AFS authentication. Other configurations possibly also work, but the instructions specify the recommended and - tested configuration. - - The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three - attributes. - Authentication Management - - - try_first_pass - - - This is a standard PAM attribute that can be included on entries after the first one for a service; it directs - the module to use the password that was provided to the first module. For the AFS module, it means that AFS - authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For - further discussion of this attribute and its alternatives, see the operating system's PAM documentation. - - - - - ignore_root - - - This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser root, but also any user with UID 0 (zero). - - - - - ignore_uid uid - - - This option is an extension of the "ignore_root" switch. The additional parameter is a limit. Users with a uid - up to the given parameter are ignored by pam_afs.so. Thus, a system administrator still has the - opportunity to add local user accounts to his system by choosing between "low" and "high" user ids. An example - /etc/passwd file for "ignore_uid 100" may have entries like these: - . - . -afsuserone:x:99:100::/afs/afscell/u/afsuserone:/bin/bash -afsusertwo:x:100:100::/afs/afscell/u/afsusertwo:/bin/bash -localuserone:x:101:100::/home/localuserone:/bin/bash -localusertwo:x:102:100::/home/localusertwo:/bin/bash - . - . - AFS accounts should be locked in the file /etc/shadow like this: - . - . -afsuserone:!!:11500:0:99999:7::: -afsusertwo:!!:11500:0:99999:7::: -localuserone:<thelocaluserone'skey>:11500:0:99999:7::: -localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: - . - . - There is no need to store a local key in this file since the AFS password is sent and verfied at the AFS cell - server! - - - - - setenv_password_expires - - - This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD_EXPIRES to the expiration - date of the user's AFS password, which is recorded in the Authentication Database. - - - - - set_token - - - Some applications don't call pam_setcred() in order to retrieve the appropriate credentials - (here the AFS token) for their session. This switch sets the credentials already in - pam_sm_authenticate() obsoleting a call to pam_setcred(). Caution: Don't use this switch for applications which do call - pam_setcred()! One example for an application not calling - pam_setcred() are older versions of the samba server. Nevertheless, using applications with - working pam session management is recommended as this setup conforms better with the PAM definitions. - - - - - refresh_token - - - This options is identical to "set_token" except that no new PAG is generated. This is necessary to handle - processes like xlock or xscreensaver. It is not enough to give the screen and the keyboard free for the user who - reactivated his screen typing in the correct AFS password, but one may also need fresh tokens with full livetime in - order to work on, and the new token must be refreshed in the already existing PAG for the processes that have been - started. This is achieved using this option. - - - - - use_klog - - - Activating this switch the authentication is done by calling the external program "klog". One program requiring - this is for example kdm of KDE 2.x. - - - - - dont_fork - - - Usually, the password verification and the establishment of the token is performed in a sub process. Using this - option pam_afs does not fork and performs all actions in a single process. Only use this options - in case you notice serious problems caused by the sub process. This option has been developed in respect to - the "mod_auth_pam"-project (see also mod_auth_pam). The - mod_auth_pam module enables PAM authentication for the apache http server package. - - - - Session Management - - - no_unlog - - - Normally the tokens are deleted (in memory) after the session ends. Using this options the tokens are left - untouched. This behaviour has been the default in pam_afs until openafs-1.1.1! - - - - - remainlifetime sec - - - The tokens are kept active for sec seconds before they are deleted. X display managers i.e. - are used to inform the applications started in the X session before the logout and then end themselves. If the token - was deleted immediately the applications would have no chance to write back their settings to i.e. the user's AFS home - space. This option may help to avoid the problem. - - - - - Perform the following steps to enable AFS login. - - Mount the AFS CD-ROM for Linux on the /cdrom directory, if it is not already. - Then change to the directory for PAM modules, which depends on which Linux distribution you are using. - - If you are using a Linux distribution from Red Hat Software: - - - # cd /lib/security - - - If you are using another Linux distribution: - - - # cd /usr/lib/security - - - - - Copy the appropriate AFS authentication library file to the directory to which you changed in the previous step. - Create a symbolic link whose name does not mention the version. Omitting the version eliminates the need to edit the PAM - configuration file if you later update the library file. - - If you use the AFS Authentication Server (kaserver process): - - - # cp /cdrom/i386_linux22/lib/pam_afs.so.1 . - # ln -s pam_afs.so.1 pam_afs.so - - - If you use a Kerberos implementation of AFS authentication: - - - # cp /cdrom/i386_linux22/lib/pam_afs.krb.so.1 . - # ln -s pam_afs.krb.so.1 pam_afs.so - - - - - For each service with which you want to use AFS authentication, insert an entry for the AFS PAM module into the - auth section of the service's PAM configuration file. (Linux uses a separate - configuration file for each service, unlike some other operating systems which list all services in a single file.) Mark - the entry as sufficient in the second field. - - Place the AFS entry below any entries that impose conditions under which you want the service to fail for a user - who does not meet the entry's requirements. Mark these entries required. Place the AFS - entry above any entries that need to execute only if AFS authentication fails. + 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 - Insert the following AFS entry if using the Red Hat distribution: - - - auth sufficient /lib/security/pam_afs.so try_first_pass ignore_root - - - Insert the following AFS entry if using another distribution: - - - auth sufficient /usr/lib/security/pam_afs.so try_first_pass ignore_root - - - Check the PAM config files also for "session" entries. If there are lines beginning with "session" then please - insert this line too: - - - session optional /lib/security/pam_afs.so - - - or - - - session optional /usr/lib/security/pam_afs.so - - - This guarantees that the user's tokens are deleted from memory after his session ends so that no other user - coincidently gets those tokens without authorization! The following examples illustrate the recommended configuration of - the configuration file for several services: - Authentication Management - - - (/etc/pam.d/login) - - - - #%PAM-1.0 - auth required /lib/security/pam_securetty.so - auth required /lib/security/pam_nologin.so - auth sufficient /lib/security/pam_afs.so try_first_pass ignore_root - # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - #This enables AFS authentication for every user but root - auth required /lib/security/pam_pwdb.so shadow nullok - account required /lib/security/pam_pwdb.so - password required /lib/security/pam_cracklib.so - password required /lib/security/pam_pwdb.so shadow nullok use_authtok - session optional /lib/security/pam_afs.so - #Make sure tokens are deleted after the user logs out - session required /lib/security/pam_pwdb.so - - - - - - (/etc/pam.d/samba) - - - - auth required /lib/security/pam_afs.so ignore_uid 100 set_token - # ^^^^^^^^^^^^^^^^^^^^^^^^ - #Here, users with uid>100 are considered to belong to the AFS and users - #with uid<=100 are ignored by pam_afs. The token is retrieved already in - #pam_sm_authenticate() (this is an example pam config for a samba version - #that does not call pam_setcred(), it also does no sense to include session - #entries here since they would be ignored by this version of samba ). - account required /lib/security/pam_pwdb.so - - - - - - (/etc/pam.d/xscreensaver) - - - - auth sufficient /lib/security/pam_afs.so ignore_uid 100 refresh_token - # ^^^^^^^^^^^^^ - #Avoid generating a new PAG for the new tokens, use the already existing PAG and - #establish a fresh token in it. - auth required /lib/security/pam_pwdb.so try_first_pass - - - - - - (/etc/pam.d/httpd) - - - - auth required /lib/security/pam_afs.so ignore_uid 100 dont_fork - # ^^^^^^^^^ - #Don't fork for the verification of the password. - - - - - Session Management - - - (/etc/pam.d/su) - - - - auth sufficient /lib/security/pam_afs.so ignore_uid 100 - auth required /lib/security/pam_pwdb.so try_first_pass - account required /lib/security/pam_pwdb.so - password required /lib/security/pam_cracklib.so - password required /lib/security/pam_pwdb.so use_authtok - session required /lib/security/pam_pwdb.so - session optional /lib/security/pam_afs.so no_unlog - # ^^^^^^^^ - #Don't delete the token in this case, since the user may still - #need it (for example if somebody logs in and changes to root - #afterwards he may still want to access his home space in AFS). - session required /lib/security/pam_login_access.so - session optional /lib/security/pam_xauth.so - - - - - - (/etc/pam.d/xdm) - - - - auth required /lib/security/pam_nologin.so - auth required /lib/security/pam_login_access.so - auth sufficient /lib/security/pam_afs.so ignore_uid 100 use_klog - auth required /lib/security/pam_pwdb.so try_first_pass - account required /lib/security/pam_pwdb.so - password required /lib/security/pam_cracklib.so - password required /lib/security/pam_pwdb.so shadow nullok use_authtok - session optional /lib/security/pam_afs.so remainlifetime 10 - # ^^^^^^^^^^^^^^^^^ - #Wait 10 seconds before deleting the AFS tokens in order to give - #the programs of the X session some time to save their settings - #to AFS. - session required /lib/security/pam_pwdb.so - - - - - - - - Proceed to Loading and Creating Client Files. - - + If you are at a site which still requires + kaserver or external Kerberos v4 based + authentication, please consult + Enabling kaserver based AFS Login on Linux Systems + for further installation instructions. + + Proceed to + Loading and Creating Client Files. incorporating AFS kernel extensions @@ -1671,12 +1198,16 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: In a later section you verify that the script correctly initializes the Cache Manager, then create the links that incorporate AFS into the Solaris startup and shutdown sequence. - Mount the AFS CD-ROM for Solaris on the /cdrom directory. For instructions on - mounting CD-ROMs (either locally or remotely via NFS), see your Solaris documentation. Then change directory as - indicated. - # cd /cdrom/sun4x_56/root.client/usr/vice/etc + Unpack the OpenAFS Solaris distribution tarball. The examples + below assume that you have unpacked the files into the + /tmp/afsdist directory. If you + pick a diferent location, substitute this in all of the following + exmaples. Once you have unpacked the distribution, change directory + as indicated. + + # cd /tmp/afsdist/sun4x_56/root.client/usr/vice/etc - + Copy the AFS initialization script to the local directory for initialization files (by convention, - 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). - - The following instructions explain how to alter the entries in the PAM configuration file for each service for which you - wish to use AFS authentication. Other configurations possibly also work, but the instructions specify the recommended and - tested configuration. - - - The instructions specify that you mark each entry as optional. However, marking some - modules as optional can mean that they grant access to the corresponding service even when the user does not meet all of the - module's requirements. In some operating system revisions, for example, if you mark as optional the module that controls - login via a dial-up connection, it allows users to login without providing a password. See the OpenAFS Release - Notes for a discussion of any limitations that apply to this operating system. - - Also, with some operating system versions you must install patches for PAM to interact correctly with certain - authentication programs. For details, see the OpenAFS Release Notes. - - - The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three - attributes. - Authentication Management - - - try_first_pass - - - This is a standard PAM attribute that can be included on entries after the first one for a service; it directs - the module to use the password that was provided to the first module. For the AFS module, it means that AFS - authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For - further discussion of this attribute and its alternatives, see the operating system's PAM documentation. - - - - - ignore_root - - - This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser root, but also any user with UID 0 (zero). - - - - - setenv_password_expires - - - This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD_EXPIRES to the expiration - date of the user's AFS password, which is recorded in the Authentication Database. - - - - - Perform the following steps to enable AFS login. - - Mount the AFS CD-ROM for Solaris on the /cdrom directory, if it is not already. - Then change directory as indicated. - # cd /usr/lib/security - - - - - Copy the AFS authentication library file to the /usr/lib/security directory. Then - create a symbolic link to it whose name does not mention the version. Omitting the version eliminates the need to edit - the PAM configuration file if you later update the library file. - - If you use the AFS Authentication Server (kaserver process): - - - # cp /cdrom/sun4x_56/lib/pam_afs.so.1 . - # ln -s pam_afs.so.1 pam_afs.so - - - If you use a Kerberos implementation of AFS authentication: - - - # cp /cdrom/sun4x_56/lib/pam_afs.krb.so.1 . - # ln -s pam_afs.krb.so.1 pam_afs.so - - - - - Edit the Authentication management section of the Solaris PAM configuration file, - /etc/pam.conf by convention. The entries in this section have the value - auth in their second field. - - First edit the standard entries, which refer to the Solaris PAM module (usually, the file /usr/lib/security/pam_unix.so.1) in their fourth field. For each service for which you want to - use AFS authentication, edit the third field of its entry to read optional. The - pam.conf file in the Solaris distribution usually includes standard entries for the - login, rlogin, and rsh services, for instance. - - If there are services for which you want to use AFS authentication, but for which the pam.conf file does not already include a standard entry, you must create that entry and place the - value optional in its third field. For instance, the Solaris pam.conf file does not usually include standard entries for the ftp or telnet services. - - Then create an AFS-related entry for each service, placing it immediately below the standard entry. The following - example shows what the Authentication Management section looks like after you have you - edited or created entries for the services mentioned previously. Note that the example AFS entries appear on two lines - only for legibility. - - - login auth optional /usr/lib/security/pam_unix.so.1 - login auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root setenv_password_expires - rlogin auth optional /usr/lib/security/pam_unix.so.1 - rlogin auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root setenv_password_expires - rsh auth optional /usr/lib/security/pam_unix.so.1 - rsh auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root - ftp auth optional /usr/lib/security/pam_unix.so.1 - ftp auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root - telnet auth optional /usr/lib/security/pam_unix.so.1 - telnet auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root setenv_password_expires - - - - - If you use the Common Desktop Environment (CDE) on the machine and want users to obtain an AFS token as they log - in, also add or edit the following four entries in the Authentication management - section. Note that the AFS-related entries appear on two lines here only for legibility. - dtlogin auth optional /usr/lib/security/pam_unix.so.1 - dtlogin auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root - dtsession auth optional /usr/lib/security/pam_unix.so.1 - dtsession auth optional /usr/lib/security/pam_afs.so \ - try_first_pass ignore_root - - - - - Some Solaris distributions include a script that locates and removes unneeded files from various file systems. Its - conventional location is /usr/lib/fs/nfs/nfsfind. The script generally uses an argument - to the find command to define which file systems to search. In this step you modify the - command to exclude the /afs directory. Otherwise, the command traverses the AFS + 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 Solaris. + + If you are at a site which still requires + kaserver or external Kerberos v4 based + authentication, please consult + Enabling kaserver based AFS Login on Solaris Systems + for further installation instructions. + + + Editing the File Systems Clean-up Script on Solaris Systems + + + + Some Solaris distributions include a script that locates + and removes unneeded files from various file systems. Its + conventional location is + /usr/lib/fs/nfs/nfsfind. The + script generally uses an argument to the + find command to define which file + systems to search. In this step you modify the + command to exclude the /afs + directory. Otherwise, the command traverses the AFS filespace of every cell that is accessible from the machine, which can take many hours. The following alterations are possibilities, but you must verify that they are appropriate for your cell. @@ -1920,7 +1336,7 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: - CD-ROM + Binary Distribution copying client files from @@ -2012,8 +1428,11 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: Loading and Creating Client Files - Now copy files from the AFS CD-ROM to the /usr/vice/etc directory. On some platforms that - use a dynamic loader program to incorporate AFS modifications into the kernel, you have already copied over some the files. + If you are using a non-packaged distribution (that is, one provided as + a tarball) you should now copy files from the istribution to the + /usr/vice/etc directory. On some platforms + that use a dynamic loader program to incorporate AFS modifications into the + kernel, you have already copied over some the files. Copying them again does no harm. Every AFS client machine has a copy of the /usr/vice/etc/ThisCell file on its local disk @@ -2025,7 +1444,7 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: - The cell in which users authenticate by default when they issue the klog + The cell in which users authenticate by default when they issue the aklog command @@ -2049,9 +1468,11 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: Administration Guide about administering client machines for instructions on updating this file, with or without rebooting. - On the local /cdrom directory, mount the AFS CD-ROM for this machine's system type, - if it is not already. For instructions on mounting CD-ROMs (either locally or remotely via NFS), consult the operating - system documentation. + If you have not already done so, unpack the distribution + tarball for this machine's system type into a suitable location on + the filesystem, such as /tmp/afsdist. + If you use a different location, substitue that in the examples that + follow. @@ -2084,9 +1505,13 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: - Create the /usr/vice/etc/CellServDB file. Use a network file transfer program such - as ftp or NFS to copy it from one of the following sources, which are listed in - decreasing order of preference: + Create the + /usr/vice/etc/CellServDB file. Use a + network file transfer program such as + sftp or + scp to copy it from one of the + following sources, which are listed in decreasing order of + preference: Your cell's central CellServDB source file (the conventional location is /afs/cellname - The global CellServDB file maintained by the AFS Product Support group + The global CellServDB + file maintained at grand.central.org @@ -2102,10 +1528,13 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: - The CellServDB.sample file included in the - sysname/root.client/usr/vice/etc directory of each AFS - CD-ROM; add an entry for the local cell by following the instructions in Creating the Client - CellServDB File + The CellServDB.sample + file included in the + sysname/root.client/usr/vice/etc + directory of each OpenAFS distribution; add an entry for the + local cell by following the instructions in + Creating the Client CellServDB File + @@ -2527,8 +1956,12 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: default values. For a discussion of all of the afsd command's arguments, see its reference page in the OpenAFS Administration Reference. - The afsd command line in the AFS initialization script on each system type includes an - OPTIONS variable. You can use it to set nondefault values for the command's arguments, in one + On platforms using the standard 'afs' initialisation script (this does + not apply to Fedora or RHEL based distributions), the + afsd command line in the AFS + initialization script on each system type includes an + OPTIONS variable. You can use it to set + nondefault values for the command's arguments, in one of the following ways: You can create an afsd options file that sets values for @@ -2593,7 +2026,23 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: role="bold">afsd command line in the script, or set no arguments (and so accept default values for all Cache Manager parameters). - + + + + If you are running on a Fedora or RHEL based system, the + openafs-client initialization script behaves differently from that + described above. It sources + /etc/sysconfig/openafs, in which the + AFSD_ARGS variable may be set to contain any, or all, of the afsd + options detailed above. Note that this script does not support setting + an OPTIONS variable, or the + SMALL, + MEDIUM and + LARGE methods of defining cache size. + + + + Create the local directory on which to mount the AFS filespace, by convention /afs. If the directory already exists, verify that it is empty. @@ -2609,7 +2058,7 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: - On Linux systems, copy the afsd options file from the On non-package based Linux systems, copy the afsd options file from the /usr/vice/etc directory to the /etc/sysconfig directory, removing the .conf extension as you do so. # cp /usr/vice/etc/afs.conf /etc/sysconfig/afs @@ -2632,6 +2081,10 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: On IRIX systems, /etc/init.d/afs + + On Fedora and RHEL systems, /etc/sysconfig/openafs + + On Linux systems, /etc/sysconfig/afs (the afsd options file) @@ -2996,8 +2449,39 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: + + Running the Script on Fedora / RHEL Systems + + + + Reboot the machine and log in again as the local superuser root. + # cd / + # shutdown -r now + login: root + Password: root_password + + + + + Run the AFS initialization script. + + # /etc/rc.d/init.d/openafs-client start + + + + + Issue the chkconfig command to activate the openafs-client + configuration variable. Based on the instruction in the AFS initialization file that begins with the string + #chkconfig, the command automatically creates the symbolic links that incorporate the + script into the Linux startup and shutdown sequence. + # /sbin/chkconfig --add openafs-client + + + + + - Running the Script on Linux Systems + Running the Script on other Linux Systems @@ -3101,7 +2585,7 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: (Optional) There are now copies of the AFS initialization file in both the /usr/vice/etc and /etc/init.d directories. If you want to avoid potential confusion by guaranteeing that they are always the same, create a link between them. You can always - retrieve the original script from the AFS CD-ROM if necessary. + retrieve the original script from the OpenAFS Binary Distribution if necessary. # cd /usr/vice/etc # rm afs.rc # ln -s /etc/init.d/afs afs.rc @@ -3156,6 +2640,11 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: Setting Up Volumes and Loading Binaries into AFS + If you are using an operating system which uses packaged + binaries, such as .rpms or .debs, you should allow these package management + systems to maintain your AFS binaries, rather than following the + instructions in this section. + In this section, you link /usr/afsws on the local disk to the directory in AFS that houses AFS binaries for this system type. The conventional name for the AFS directory is /afs/cellnameIf this client machine is a new system type, you must create and mount volumes for its binaries before you can link the local /usr/afsws directory to an AFS directory. - To create and mount the volumes, you use the klog command to authenticate as an - administrator and then issue commands from the vos and fs - command suites. However, the command binaries are not yet available on this machine (by convention, they are accessible via - the /usr/afsws link that you are about to create). You have two choices: + To create and mount the volumes, you use the + kinit command to authenticate as an + administrator, followed by the aklog + command to gain tokens, and then issue commands from the + vos and + fs command suites. However, the + command binaries are not yet available on this machine (by convention, + they are accessible via the /usr/afsws + link that you are about to create). You have two choices: + Perform all steps except the last one (Step 10) on an existing AFS machine. On a - file server machine, the klog, fs and aklog, fs and vos binaries reside in the /usr/afs/bin directory. On client - machines, the klog and fs binaries reside in the + machines, the aklog and fs binaries reside in the /usr/afsws/bin directory and the vos binary in the /usr/afsws/etc directory. Depending on how your PATH environment variable is set, you possibly need to precede the command names with a pathname. @@ -3241,25 +2736,28 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: Perform the following steps to create a volume for housing AFS binaries. - Working either on the local machine or another AFS machine, mount the AFS CD-ROM for the new system type on the - /cdrom directory, if it is not already. For instructions on mounting CD-ROMs (either - locally or remotely via NFS), consult the operating system documentation. + Working either on the local machine or another AFS machine, + extract the Open AFS distribtion tarball onto a directory on that + machine. The following instructions assume that you are using the + /tmp/afsdist directory. If working on the local machine, copy the necessary binaries to a temporary location on the local disk. Substitute a different directory name for /tmp if you wish. - # cd /cdrom/new_sysname/root.server/usr/afs/bin - # cp -p klog /tmp + # cd /tmp/afsdist/new_sysname/root.server/usr/afs/bin + # cp -p aklog /tmp # cp -p fs /tmp # cp -p vos /tmp - Authenticate as the user admin. - # klog admin + Authenticate as the user admin. + + # kinit admin Password: admin_password + # aklog @@ -3324,8 +2822,9 @@ localusertwo:<thelocalusertwo'skey>:11500:0:99999:7::: - Copy the contents of the indicated directories from the CD-ROM into the /afs/cellnameCopy the contents of the indicated + directories from the OpenAFS binary distribution into the + /afs/cellname/sysname/usr/afsws directory. # cd /afs/.cellname/sysname - Issue the fs setacl command to set the ACL on each directory appropriately. To - comply with the terms of your AFS License agreement, you must prevent unauthorized users from accessing AFS software. To - enable access for locally authenticated users only, set the ACL on the etc, include, and lib subdirectories to grant the l and r permissions to the system:authuser group rather than the system:anyuser group. The - system:anyuser group must retain the l and r permissions on the bin subdirectory to enable unauthenticated - users to access the klog binary. To ensure that unauthorized users are not accessing - AFS software, check periodically that the ACLs on these directories are set properly. + Issue the fs setacl command + to set the ACL on each directory appropriately. If you wish to + enable access to the software for locally authenticated users only, + set the ACL on the etc, + include, and + lib subdirectories to grant the + l and + r permissions to the + system:authuser group rather than + the system:anyuser group. The + system:anyuser group must retain + the l and + r permissions on the + bin subdirectory to enable + unauthenticated users to access the + aklog binary. + # cd /afs/.cellname/sysname/usr/afsws # fs setacl -dir etc include lib -acl system:authuser rl \ -- 2.39.5