From 7de756ca285614214a9f272338a5a2b3f731612a Mon Sep 17 00:00:00 2001 From: Simon Wilkinson Date: Wed, 11 Apr 2007 03:14:33 +0000 Subject: [PATCH] quickstart-update-20070410 FIXES 58896 update quickstart guide with new information --- doc/xml/QuickStartUnix/auqbg000.xml | 12 +- doc/xml/QuickStartUnix/auqbg003.xml | 7 +- doc/xml/QuickStartUnix/auqbg004.xml | 60 +- doc/xml/QuickStartUnix/auqbg005.xml | 1219 ++++++++++++--------------- 4 files changed, 608 insertions(+), 690 deletions(-) diff --git a/doc/xml/QuickStartUnix/auqbg000.xml b/doc/xml/QuickStartUnix/auqbg000.xml index aa5e1161b..fbd031748 100644 --- a/doc/xml/QuickStartUnix/auqbg000.xml +++ b/doc/xml/QuickStartUnix/auqbg000.xml @@ -17,8 +17,8 @@ Version 1.4.2 - 2000 - IBM Corporation. All Rights Reserved + 2000-2007 + IBM Corporation and other contributors. All Rights Reserved @@ -28,16 +28,16 @@ - 1.4.2 - December 2006 + 1.4.4 + March 2007 This document describes the initial setup of an OpenAFS cell and an OpenAFS client. It is currently being updated for OpenAFS - 1.4.2 and is still dated and incorrect in some details. This - edition applies to OpenAFS for UNIX, Version 1.4.2, and to all + 1.4.4 and is still dated and incorrect in some details. This + edition applies to OpenAFS for UNIX, Version 1.4.4, and to all subsequent releases and modifications until otherwise indicated in new editions. diff --git a/doc/xml/QuickStartUnix/auqbg003.xml b/doc/xml/QuickStartUnix/auqbg003.xml index f3996c5ce..4c360414c 100644 --- a/doc/xml/QuickStartUnix/auqbg003.xml +++ b/doc/xml/QuickStartUnix/auqbg003.xml @@ -8,13 +8,14 @@ Audience and Purpose - This guide explains how to install and configure AFS server and client machines. It + This guide explains how to install and configure OpenAFS + server and client machines. It assumes that the reader is familiar with UNIX system administration, but not AFS. - The instructions explain how to issue AFS commands in the + The instructions explain how to issue + AFS commands in the context of specific tasks, but do not describe a command's function or arguments in detail. Refer to the OpenAFS Administration Reference as necessary. diff --git a/doc/xml/QuickStartUnix/auqbg004.xml b/doc/xml/QuickStartUnix/auqbg004.xml index 0b482c1d0..9f5e0a617 100644 --- a/doc/xml/QuickStartUnix/auqbg004.xml +++ b/doc/xml/QuickStartUnix/auqbg004.xml @@ -40,8 +40,10 @@ Incorporating AFS Into the Kernel You must incorporate AFS modifications into the kernel of - every AFS file server and client machine. Depending on the - operating system, you either use a program for dynamic kernel + every client machine. On some operating systems you must also + incorporate these modifications into the kernels of server machines. + Depending on + the operating system, you either use a program for dynamic kernel loading, build a new static kernel, or can choose between the two. For your convenience, the instructions for incorporating AFS into the kernel appear in full in every chapter where you need to @@ -69,14 +71,13 @@ It acts as the system control - machine (if your AFS distribution includes the - required encryption files), distributing certain + machine, distributing certain configuration files to the other server machines in the cell - It acts as the binary distribution + It may act as the binary distribution machine for its system type, distributing AFS binaries to other server machines of its system type @@ -274,10 +275,20 @@ - You must have the AFS Binary Distribution for each system type you are installing. Unless otherwise noted, the - Binary Distribution includes software for both client and server machines. If you are using the CD-ROM version of the - distribution, the machine you are installing must be able to access the CD-ROMs, either through a local CD drive or via an - NFS(R) mount of a CD drive attached to a machine that is accessible by network. + You must have a Kerberos 5 realm running for your site, and + the ability to create new principals within that realm + + + + You must have a NTP, or similar, timeservice running. Each AFS + machine should derive its system time from this timeservice + + + + You must have an OpenAFS Binary Distribution for each system + type you are installing, or have built a binary from the supplied + source code. Unless otherwise noted, the Binary Distribution + includes software for both client and server machines. @@ -299,7 +310,7 @@ - No critical processes can be running on the machine you are installing, because you must reboot it during the + No critical processes can be running on the machine you are installing, because you may need to reboot it during the installation. @@ -331,6 +342,7 @@ The partition mounted on the /usr directory must have at least 18 MB of disk space + available for storing the AFS server binaries (stored by convention in the /usr/afs/bin directory). If the machine is also a client, there must be additional local disk space available, as specified in Client Machine Requirements. The complete set of AFS binaries requires yet more space, but they @@ -402,18 +414,17 @@ Supported System Types The OpenAFS Release Notes for each AFS release list the supported system types. Support for - subsequent revisions of an operating system often becomes available between AFS releases. The AFS Product Support group can - provide details. + subsequent revisions of an operating system often becomes available between AFS releases. The OpenAFS mailing lists can provide information regarding this interim support - It is the goal of the AFS Development and Product Support groups to support AFS on a wide range of popular system types. + It is the goal of OpenAFS to support AFS on a wide range of popular system types. Furthermore, each time an operating system vendor releases a new general availability version of a supported operating system, - it is a goal to certify and support AFS on it within a short time. Support can be delayed a bit longer if it is necessary to + it is a goal to support AFS on it within a short time. Support can be delayed a bit longer if it is necessary to generate completely new binaries. It is not always possible to support AFS on every intermediate version of an operating system or for certain processor types. In some cases, platform limitations make certain AFS functionality (such as file server or NFS/AFS translator functionality) unavailable on one or more platforms. For a list of limitations, see the OpenAFS Release - Notes or ask the AFS Product Support group. + Notes or ask on the OpenAFS mailing lists. operating system upgrades upgrading the operating system @@ -434,27 +445,29 @@ Whenever you upgrade an AFS machine to a different operating system, you must take several actions to maintain proper AFS functionality. These actions include, but are not necessarily limited to, the following. - Unmount the AFS server partitions (mounted at /vicepxx + On platforms running the inode fileserver, unmount the AFS server partitions (mounted at /vicepxx directories) on all file server machines, to prevent the vendor-supplied fsck program from running on them when you reboot the machine during installation of the new operating system. Before upgrading the operating system, it is prudent to comment out commands in the machine's initialization file that remount the server partitions, to prevent them from being remounted until you can replace the standard fsck program with the AFS-modified version. The instructions in this guide for installing AFS server machines explain how to - replace the fsck program. + replace the fsck program. If you are unsure if your platform uses the inode fileserver, it is worth following this advice for all platforms. Protect the AFS-modified versions of commands and configuration files from being overwritten by vendor-supplied - versions. These include vfsck (the AFS version of fsck), - binaries for the UNIX remote services such as inetd, and configuration files such as the + versions. These include vfsck (the AFS version of fsck), and configuration files such as the one for the Pluggable Authentication Module (PAM). After you have successfully installed the operating system, remember to move the AFS-modified commands and files back to the locations where they are accessed during normal functioning. + @@ -479,11 +492,12 @@ - The AFS Binary Distribution + The OpenAFS Binary Distribution + + Binary Distributions for supported systems may be downloaded from the OpenAFS website. The distributions are in the native packaging format for the system in question, and should generally be installed using your system's package management tools. + +For those distributions provided as tar files, or those built from source, the instructions in this guide specify how to copy out both binaries and configuration files - The AFS Binary Distribution includes a separate CD-ROM for each supported system type, containing all AFS binaries and - files for both server and client machines. The instructions in this guide specify when to mount the CD-ROM and which files or - directories to copy to the local disk or into an AFS volume. diff --git a/doc/xml/QuickStartUnix/auqbg005.xml b/doc/xml/QuickStartUnix/auqbg005.xml index b5654fe66..4bf58ec70 100644 --- a/doc/xml/QuickStartUnix/auqbg005.xml +++ b/doc/xml/QuickStartUnix/auqbg005.xml @@ -39,7 +39,8 @@ Requirements and Configuration Decisions - The instructions in this chapter assume that you meet the following requirements. + The instructions in this chapter assume that you meet the following requirements. + You are logged onto the machine's console as the local superuser root @@ -50,8 +51,18 @@ - You can access the data on the AFS CD-ROMs, either through a local CD drive or via an NFS mount of a CD drive - attached to a machine that is accessible by network + You have either installed the provided OpenAFS packages for + your system, have access to a binary distribution tarball, or have + successfully built OpenAFS from source + + + + You have a Kerberos v5 realm running for your site + + + + You have a NTP, or similar, time service deployed to ensure + rough clock syncronistation between your clients and servers. @@ -83,13 +94,6 @@ which to mount them - - Decide whether to use the standard AFS authentication and authorization software or Kerberos as obtained from - another source. On several system types, the decision determines how you incorporate AFS into the machine's authentication - system. If you wish to use Kerberos, contact the AFS Product Support group now to learn about how you must modify the - installation procedure. - - Decide how big to make the client cache @@ -143,7 +147,8 @@ Overview: Installing Server Functionality In the first phase of installing your cell's first AFS machine, you install file server and database server functionality - by performing the following procedures: + by performing the following procedures: + Choose which machine to install as the first AFS machine @@ -178,7 +183,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 (VL) Server @@ -195,10 +200,6 @@ Start the server portion of the Update Server - - Start the controller process (called runntp) for the Network Time Protocol Daemon, - which synchronizes machine clocks - @@ -222,34 +223,6 @@ Creating AFS Directories - - CD-ROM - - creating /cdrom directory - - first AFS machine - - - - cdrom directory - - first AFS machine - - - - first AFS machine - - /cdrom directory - - - - creating - - /cdrom directory - - first AFS machine - - usr/afs directory @@ -296,15 +269,23 @@ see alphabetized entries without initial slash - Create the /usr/afs and /usr/vice/etc directories on the - local disk, to house server and client files respectively. Subsequent instructions copy files from the AFS CD-ROM into them. - Create the /cdrom directory as a mount point for CD-ROMs, if it does not already exist. - - + If you are installing from packages (such as Debian .deb or + Fedora/SuSe .rpm files), you should now install all of the available + OpenAFS packages for your system type. Typically, these will include + packages for client and server functionality, and a seperate package + containing a suitable kernel module for your running kernel. Consult + the package lists on the OpenAFS website to determine the packages + appropriate for your system. + + If you are installing from a tarfile, or from a locally compiled + source tree you should create the /usr/afs + and /usr/vice/etc directories on the + local disk, to house server and client files respectively. Subsequent + instructions copy files from the distribution tarfile into them. + # mkdir /usr/afs # mkdir /usr/vice # mkdir /usr/vice/etc - # mkdir /cdrom @@ -336,8 +317,10 @@ Incorporate AFS modifications into the kernel. - The kernel on every AFS file server and client machine must incorporate AFS extensions. On machines that use a - dynamic kernel module loader, it is conventional to alter the machine's initialization script to load the AFS extensions + The kernel on every AFS client machine and, on some systems, + the AFS fileservers, must incorporate AFS extensions. On machines + that use a dynamic kernel module loader, it is conventional to + alter the machine's initialization script to load the AFS extensions at each reboot. AFS server partition @@ -405,7 +388,7 @@ If the machine is to remain an AFS client machine, 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 command). For further discussion of AFS + file system and then issue the aklog command). For further discussion of AFS authentication, see the chapter in the OpenAFS Administration Guide about cell configuration and administration issues. @@ -482,10 +465,14 @@ correctly initializes all AFS components, 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 @@ -641,6 +628,10 @@ Replacing the fsck Program Helper on AIX Systems + The AFS modified fsck program is not required on AIX 5.1 + systems, and the v3fshelper program + refered to below is not shipped for these systems. + In this section, you make modifications to guarantee that the appropriate fsck program runs on AFS server partitions. The fsck program provided with the operating system must never run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data, @@ -654,11 +645,11 @@ role="bold">/sbin/helpers/v3fshelper. 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. + the AFS distribution in its place. + # 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 @@ -716,7 +707,17 @@ proceed to Starting the BOS Server. - Follow the instructions in this section to incorporate AFS modifications into the AIX secondary authentication system. + 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 + + @@ -869,10 +853,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 @@ -1113,7 +1101,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/* . @@ -1202,10 +1190,7 @@ Enabling AFS Login on HP-UX Systems - - If you plan to remove client functionality from this machine after completing the installation, skip this section and - proceed to Starting the BOS Server. - + If you plan to remove client functionality from this machine after completing the installation, skip this section and proceed to Starting the BOS Server. At this point you incorporate AFS into the operating system's Pluggable Authentication Module (PAM) scheme. PAM integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for @@ -1216,20 +1201,28 @@ 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. - + 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 + + Proceed to Starting the BOS Server (or if referring to these instructions while installing an additional file server machine, return to Starting Server Programs). - - + @@ -1423,10 +1413,14 @@ 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 @@ -1815,6 +1809,18 @@ proceed to Starting the BOS Server. + 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. + + After taking any necessary action, proceed to Starting the BOS Server. @@ -1873,7 +1879,13 @@ fsck program replacement not necessary - Begin by running the AFS initialization script to call the insmod program, which + Since this guide was originally written, the procedure for starting + OpenAFS has diverged significantly between different Linux distributions. + The instructions that follow are appropriate for both the Fedora and + RedHat Enterprise Linux packages distributed by OpenAFS. Additional + instructions are provided for those building from source. + + Begin by running the AFS client startup scripts, which call the modprobe program, which dynamically loads AFS modifications into the kernel. Then create partitions for storing AFS volumes. You do not need to replace the Linux fsck program. If the machine is to remain an AFS client machine, incorporate AFS into the machine's Pluggable Authentication Module (PAM) scheme. @@ -1905,23 +1917,75 @@ 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 distribution'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 later sections you verify that the script correctly initializes all AFS components, then activate a configuration - variable, which results in the script being incorporated into the Linux startup and shutdown sequence. + 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 ship RPMS for all current Fedora and RHEL releases. + - 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 + Download and install the RPM set for your operating system. + RPMs are available from the OpenAFS web site. You will need the + openafs + openafs-client> + openafs-server 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 + + + Copy the AFS kernel library files to the local /usr/vice/etc/modload directory. The filenames for the libraries have the format + + configuring - + AFS server partition on first AFS machine Linux @@ -1980,6 +2048,7 @@ on first AFS machine + @@ -2091,125 +2160,20 @@ 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. - - 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 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. - - 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 - - - The following example illustrates the recommended configuration of the configuration file for the login service (/etc/pam.d/login) on a machine using the Red Hat - distribution. - - - #%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 - 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 required /lib/security/pam_pwdb.so - - + 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 + Proceed to Starting the BOS Server (or if referring to these instructions while installing an additional file server machine, return to Starting Server Programs). - + @@ -2260,10 +2224,14 @@ In later sections you verify that the script correctly initializes all AFS components, 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 @@ -2382,7 +2350,7 @@ Copy the vfsck binary to the newly created directory, changing the name as you do so. - # cp /cdrom/sun4x_56/root.server/etc/vfsck fsck + # cp /tmp/afsdist/sun4x_56/root.server/etc/vfsck fsck @@ -2632,6 +2600,18 @@ marking an entry as required, optional, or sufficient, and so on). + In modern AFS installations, you should be using Kerberos v5 + for user login, and obtaining AFS tokens subsequent to this authentication + step. OpenAFS does not currently distribute a PAM module allowing AFS + tokens to be automatically gained at login. Whilst there are a number of + third party modules providing this functionality, it is not know if these + have been tested with HP/UX. + + Following login, users can + obtain tokens by running the aklog + command + + + 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 @@ -2797,7 +2778,7 @@ installing an additional file server machine, return to Starting Server Programs). - + Basic OverSeer Server @@ -2846,13 +2827,15 @@ - Starting the BOS Server - You are now ready to start the AFS server processes on this machine. Begin by copying the AFS server binaries from the - CD-ROM to the conventional local disk location, the /usr/afs/bin directory. The following - instructions also create files in other subdirectories of the /usr/afs directory. + You are now ready to start the AFS server processes on this machine. + If you are not working from a packaged distribution, begin by copying the + AFS server binaries from the distribution to the conventional local disk + location, the /usr/afs/bin directory. The + following instructions also create files in other subdirectories of the + /usr/afs directory. Then issue the bosserver command to initialize the Basic OverSeer (BOS) Server, which monitors and controls other AFS server processes on its server machine. Include the -noauth @@ -2947,14 +2930,9 @@ role="bold">/usr/afs/etc directory; the links enable the command interpreters to retrieve the information they need. Later instructions for installing the client functionality replace the links with actual files. - 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. - - - - Copy files from the CD-ROM to the local /usr/afs directory. - # cd /cdrom/sysname/root.server/usr/afs + If you are not working from a packaged distribution, you may need to copy files from the distribution media to the local /usr/afs directory. + + # cd /tmp/afsdist/sysname/root.server/usr/afs # cp -rp * /usr/afs commands @@ -3127,9 +3105,9 @@ In the following and every instruction in this guide, for the machine name argument - substitute the fully-qualified hostname (such as fs1.abc.com) of the machine you are + substitute the fully-qualified hostname (such as fs1.example.com) of the machine you are installing. For the cell name argument substitute your cell's complete name (such as abc.com). + role="bold">example.com). @@ -3145,10 +3123,17 @@ + + If necessary, add the directory containing the bos command to your path. + + # export PATH=$PATH:/usr/afs/bin + + + + Issue the bos setcellname command to set the cell name. - # cd /usr/afs/bin - # ./bos setcellname <machine name> <cell name> bos setcellname <machine name> <cell name> -noauth @@ -3176,7 +3161,7 @@ Issue the bos listhosts command to verify that the machine you are installing is now registered as the cell's first database server machine. - # ./bos listhosts <machine name> -noauth + # bos listhosts <machine name> -noauth Cell name is cell_name Host 1 is machine_name @@ -3205,34 +3190,6 @@ first - - Authentication Server - - starting - - first AFS machine - - - - first AFS machine - - Authentication Server - - - - kaserver process - - Authentication Server - - - - starting - - Authentication Server - - first AFS machine - - Backup Server @@ -3363,13 +3320,9 @@ Starting the Database Server Processes - Next use the bos create command to create entries for the four database server processes - in the /usr/afs/local/BosConfig file and start them running. The four processes run on database + Next use the bos create command to create entries for the three database server processes + in the /usr/afs/local/BosConfig file and start them running. The three processes run on database server machines only: - - The Authentication Server (the kaserver process) maintains the Authentication - Database - The Backup Server (the buserver process) maintains the Backup Database @@ -3391,11 +3344,12 @@ - AFS's authentication and authorization software is based on algorithms and other procedures known as - Kerberos, as originally developed by Project Athena at the Massachusetts Institute of Technology. Some - cells choose to replace the AFS Authentication Server and other security-related protocols with Kerberos as obtained directly - from Project Athena or other sources. If you wish to do this, contact the AFS Product Support group now to learn about - necessary modifications to the installation. + AFS ships with an additional database server named 'kaserver', which + was historically used to provide authentication services to AFS cells. + 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. The remaining instructions in this chapter include the -cell argument on all applicable @@ -3409,18 +3363,6 @@ 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. - - Issue the bos create command to start the Backup Server. # ./bos create <machine name> buserver simple /usr/afs/bin/buserver \ @@ -3450,23 +3392,23 @@ - afs entry in Authentication Database + afs entry in Kerberos Database - Authentication Database + Kerberos Database creating - afs entry in Authentication Database + afs entry in Kerberos Database creating - admin account in Authentication Database + admin account in Kerberos Database @@ -3521,8 +3463,7 @@ Initializing Cell Security - Now initialize the cell's security mechanisms. Begin by creating the following two initial entries in the Authentication - Database: + 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 assign a different name, substitute it throughout the remainder of this document. @@ -3534,9 +3475,12 @@ - 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 + The entry for AFS server processes, called either + afs or + afs/cell. + No user logs in under this identity, but it is used to encrypt the + server tickets that granted 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.) @@ -3550,74 +3494,54 @@ 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 + chapter in the OpenAFS Administration Guide about configuring the Backup System. - kas (interactive) - - - - kas commands - - interactive mode, entering - - - - interactive mode for kas - - entering - + 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 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> + Enter kadmin interactive mode. + + # kadmin +Authenticating as principal you/admin@YOUR REALM with password +Password for you/admin@REALM: your_password - commands - - kas create - - kas commands - - create - server encryption key - in Authentication Database + in Kerberos Database creating server encryption key - Authentication Database + Kerberos 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 + Issue the + add_principal command to create + Kerberos Database entries called + admin and + afs/<cell name>. + + You should make the admin_passwd as + long and complex as possible, but keep in mind that administrators + need to enter it often. It must be at least six characters long. + Note that when creating the + afs/<cell name> + entry, the encryption types should be restricted to des-cbc-crc:v4. + For more details regarding encryption types, see the documentation + for your Kerberos installation. + + + kadmin: add_principal -randkey -e des-cbc-crc:v4 afs/<cell name> + Principal "afs/cell name@REALM" created. + kadmin: add_principal admin + Enter password for principal "admin@REALM": admin_password + Principal "admin@REALM" created. + commands @@ -3641,57 +3565,42 @@ - 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 kadmin + get_principal command to display the afs/<cell name> entry. + + kadmin: get_principal afs/<cell name> + Principal: afs/cell + [ ... ] + Key: vno 2, DES cbc mode with CRC-32, no salt + [ ... ] + + - - 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 + Extract the newly created key for afs/cell to a keytab on the local machine. We will use /etc/afs.keytab as the location for this keytab. - kas quit - - kas commands + The keytab contains the key material that ensures the security of your AFS cell. You should ensure that it is kept in a secure location at all times. - quit - - interactive mode for kas + + kadmin: ktadd -k /etc/afs.keytab -e des-cbc-crc:v4 afs/<cell name> +Entry for principal afs/<cell name> with kvno 3, encryption type DES cbc mode with CRC-32 added to keytab WRFILE:/etc/afs.keytab + + Make a note of the key version number (kvno) given in the + response, as you will need it to load the key into bos in a later + step - quitting - - + Note that each time you run + ktadd a new key is generated + for the item being extracted. This means that you cannot run ktadd + multiple times and end up with the same key material each time. + + - Issue the kas quit command to leave kas + Issue the kadmin quit command to leave kadmin interactive mode. - ka> quit + kadmin: quit commands @@ -3732,40 +3641,43 @@ role="bold">vos commands. # ./bos adduser <machine name> admin -cell <cell name> -noauth - + + commands - - bos addkey - - bos commands - - addkey - + asetkey + + 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. + Issue the + asetkey command to set the AFS + server encryption key in the + /usr/afs/etc/KeyFile file. This key + is created from the /etc/afs.keytab + file created earlier. - 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. + asetkey requires the key version number (or kvno) of the + afs/cell + key. You should have noted this down when creating the key earlier. + The key version number can also be found by running the + kvno command + + # kvno afs/<cell name> + - - # ./bos addkey <machine name> -kvno 0 -cell <cell name> -noauth - Input key: afs_passwd - Retype input key: afs_passwd + Once the kvno is known, the key can then be extracted using + asetkey + + # asetkey <kvno> /etc/afs.keytab afs/<cell name> @@ -3790,10 +3702,14 @@ - 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. + Issue the + bos listkeys command to verify that + the key version number for the new key in the + KeyFile file is the same as the key + version number in the Authentication Database's + afs/cell name + entry, which you displayed in Step 3. + # ./bos listkeys <machine name> -cell <cell name> -noauth key 0 has cksum checksum @@ -3802,6 +3718,7 @@ You can safely ignore any error messages indicating that bos failed to get tickets or that authentication failed. + commands @@ -3855,7 +3772,7 @@ to accept the default. - # ./pts createuser -name admin -cell <cell name> [pts createuser -name admin -cell <cell name> [-id <AFS UID>] -noauth User admin has id AFS UID @@ -3929,7 +3846,7 @@ role="bold">-noauth - + File Server @@ -4216,7 +4133,9 @@ Distributing the contents of its /usr/afs/bin directory to other server machines of its system type makes this machine a binary distribution machine. The other server machines of its system type run the upclientbin process (an instance of the client portion of the Update Server) to - retrieve the binaries. + retrieve the binaries. If your platform has a package management system, + such as 'rpm' or 'apt', running the Update Server to distribute binaries + may interfere with this system. The binaries in the /usr/afs/bin directory are not sensitive, so it is not necessary to encrypt them before transfer across the network. Include the -clear argument to the - - - runntp process - - first AFS machine - - - - starting - - runntp process - - first AFS machine - - - - first AFS machine - - runntp process - - - - NTPD - - first AFS machine - - - - time synchronization - - - - clock synchronization - @@ -4285,75 +4170,11 @@ Administration Guide about administering server machines explains how time skew can disturb Ubik's performance and cause service outages in your cell. - The AFS distribution includes a version of the Network Time Protocol Daemon (NTPD) for synchronizing the clocks on server - machines. If a time synchronization program is not already running on the machine, then in this section you start the runntp process to configure NTPD for use with AFS. - - - Do not run the runntp process if NTPD or another time synchronization protocol is - already running on the machine. Some versions of some operating systems run a time synchronization program by default, as - detailed in the OpenAFS Release Notes. - - Attempting to run multiple instances of the NTPD causes an error. Running NTPD together with another time - synchronization protocol is unnecessary and can cause instability in the clock setting. - - - If you run the runntp process and your cell has reliable network connectivity to machines - outside your cell, then it is conventional to configure the first AFS machine to refer to a time source outside the cell. When - you later install the runntp program on other server machines in the cell, it configures NTPD - to choose a time source at random from among the database server machines listed in the /usr/afs/etc/CellServDB file. Time synchronization therefore works in a chained manner: this database - server machine refers to a time source outside the cell, the database server machines refer to the machine among them that has - access to the most accurate time (NTPD itself includes code for determining this), and each non-database server machine refers - to a local database server machine chosen at random from the /usr/afs/etc/CellServDB file. If - you ever decide to remove database server functionality from this machine, it is best to transfer responsibility for consulting - an external time source to a remaining database server machine. - - If your cell does not have network connectivity to external machines, or if the connectivity is not reliable, include the - -localclock flag to the runntp command as indicated in the - following instructions. The flag tells NTPD to rely on the machine's internal clock when all external time sources are - inaccessible. The runntp command has other arguments that are possibly useful given your cell - configuration; see the OpenAFS Administration Reference. - - Choosing an appropriate external time source is important, but involves more considerations than can be discussed here. If - you need help in selecting a source, contact the AFS Product Support group. - - As the runntp process initializes NTPD, trace messages sometimes appear on the standard - output stream. You can ignore them, but they can be informative if you understand how NTPD works. - - Issue the bos create command to start the runntp - process. For the host argument, substitute the fully-qualified hostname or IP address of one or - more machines outside the cell that are to serve as time sources. Separate each name with a space. - - If your cell usually has reliable network connectivity to an external time source, use the following command: - - # ./bos create <machine name> runntp simple \ - "/usr/afs/bin/runntp <host>+" -cell <cell name> -noauth - - - - - If your cell does not have network connectivity to an external time source, use the following command: - - # ./bos create <machine name> runntp simple \ - "/usr/afs/bin/runntp -localclock" -cell <cell name> -noauth - - - - - If your cell has network connectivity to an external time source, but the network connection is frequently - interrupted, use the following command: - # ./bos create <machine name> runntp simple \ - "/usr/afs/bin/runntp -localclock <host>+" \ - -cell <cell name> -noauth - - - - - + Historically, AFS used to distribute its own version of the Network +Time Protocol Daemon. Whilst this is still provided for existing sites, we +recommend that you configure and install your time service independently of +AFS. A reliable timeservice will also be required by your Kerberos realm, +and so may already be available at your site. overview @@ -4381,8 +4202,10 @@ Overview: Installing Client Functionality - The machine you are installing is now an AFS file server machine, database server machine, system control machine, and - binary distribution machine. Now make it a client machine by completing the following tasks: + The machine you are installing is now an AFS file server machine, + database server machine, system control machine, and binary distribution + machine. Now make it a client machine by completing the following tasks: + Define the machine's cell membership for client processes @@ -4401,7 +4224,7 @@ - CD-ROM + Distribution copying client files from @@ -4428,12 +4251,19 @@ Copying Client Files to the Local Disk - Before installing and configuring the AFS client, copy the necessary files from the AFS CD-ROM to the local You need only undertake the steps in this section, if you are using + a tar file distribution, or one built from scratch. Packaged distributions, + such as RPMs or DEBs will already have installed the necessary files in + the correct locations. + + Before installing and configuring the AFS client, copy the necessary files from the tarball to the local /usr/vice/etc directory. - 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. @@ -4453,7 +4283,7 @@ role="bold">cp 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 @@ -4520,20 +4350,21 @@ Among other functions, the ThisCell file on a client machine determines the following: - The cell in which users authenticate when they log onto the machine, assuming it is using an AFS-modified login - utility + The cell in which users gain tokens when they log onto the + machine, assuming it is using an AFS-modified login utility - The cell in which users authenticate by default when they issue the klog - command + The cell in which users gain tokens by default when they issue + the aklog command - The cell membership of the AFS server processes that the AFS command interpreters on this machine contact by - default + The cell membership of the AFS server processes that the AFS + command interpreters on this machine contact by default - + + Change to the /usr/vice/etc directory and remove the symbolic link created in Starting the BOS Server. @@ -4621,16 +4452,18 @@ 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.sample, and you have already copied it - to the /usr/vice/etc directory. It includes an entry for all AFS cells that agreed to share - their database server machine information at the time your AFS CD-ROM was created. The AFS Product Support group also maintains - a copy of the file, updating it as necessary. If you are interested in participating in the global AFS namespace, it is a good - policy to consult the file occasionally for updates. Ask the AFS Product Support group for a pointer to its location. + 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 CellServDB.sample file can be a good basis for the client CellServDB file, because all of the entries in it use the correct format. You can add or remove cell - entries as you see fit. Later (in Enabling Access to Foreign Cells) you perform additional steps - that enable the Cache Manager actually to reach the cells. + The CellServDB.dist file can be a + good basis for the client CellServDB file, + because all of the entries in it use the correct format. You can add or + remove cell entries as you see fit. Depending on your cache manager + configuration, additional steps (as detailed in + Enabling Access to Foreign Cells) may be + required to enable the Cache Manager to actually reach the cells. In this section, you add an entry for the local cell to the local CellServDB file. The current working directory is still /usr/vice/etc. @@ -4658,9 +4491,9 @@ where cell_name is the cell's complete Internet domain name (for example, abc.com) and organization is an optional field that follows any + role="bold">example.com) and organization is an optional field that follows any number of spaces and the number sign (#). By convention it names the organization - to which the cell corresponds (for example, the ABC Corporation). + to which the cell corresponds (for example, the Example Corporation). @@ -4672,7 +4505,7 @@ where IP_address is the machine's IP address in dotted decimal format (for example, 192.12.105.3). Following any number of spaces and the number sign (#) is machine_name, the machine's fully-qualified hostname (for example, db1.abc.com). In this case, the number sign does not indicate a comment; + role="bold">db1.example.com). In this case, the number sign does not indicate a comment; machine_name is a required field. @@ -4686,10 +4519,10 @@ The following example shows entries for two cells, each of which has three database server machines: - >abc.com #ABC Corporation (home cell) - 192.12.105.3 #db1.abc.com - 192.12.105.4 #db2.abc.com - 192.12.105.55 #db3.abc.com + >example.com #Example Corporation (home cell) + 192.12.105.3 #db1.example.com + 192.12.105.4 #db2.example.com + 192.12.105.55 #db3.example.com >stateu.edu #State University cell 138.255.68.93 #serverA.stateu.edu 138.255.68.72 #serverB.stateu.edu @@ -4912,7 +4745,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 + 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: @@ -4978,7 +4811,19 @@ 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 initilization 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 + 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. @@ -4994,7 +4839,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 @@ -5017,8 +4862,12 @@ On IRIX systems, /etc/init.d/afs + + On Fedora and RHEL systems, /etc/sysconfg/openafs + + - On Linux systems, /etc/sysconfig/afs (the On non-package based Linux systems, /etc/sysconfig/afs (the afsd options file) @@ -5030,13 +4879,6 @@ Use one of the methods described in the introduction to this section 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 -nosettime flag, because this is a file server machine that is also a - client. The flag prevents the machine from picking a file server machine in the cell as its source for the correct - time, which client machines normally do. File server machines instead use NTPD (as controlled by the runntp process) or another protocol to synchronize their clocks. - - Add the -memcache flag if the machine is to use a memory cache. @@ -5047,7 +4889,19 @@ - + + In order to successfully complete the instructions in the + remainder of this guide, it is important that the machine does not have + 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 + -afsdb options from both the AFS + initialisation script and options file. If this functionality is + required it may be renabled as detailed in + Enabling Access to Foreign Cells. + + overview @@ -5152,8 +5006,9 @@ On system types that use a dynamic loader program, you must reboot the machine before running the initialization script, so that it can freshly load AFS modifications into the kernel. - If there are problems during the initialization, attempt to resolve them. The AFS Product Support group can provide - assistance if necessary. + If there are problems during the initialization, attempt to resolve them. The OpenAFS mailing lists can provide assistance if necessary. + + commands @@ -5327,8 +5182,10 @@ - Run the AFS initialization script. - # /etc/rc.d/init.d/afs start + Run the AFS initialization scripts. + + # /etc/rc.d/init.d/openafs-client start + # /etc/rc.d/init.d/openafs-server start @@ -5379,13 +5236,17 @@ initializations do not take nearly as long, because the Vn files already exist. - As a basic test of correct AFS functioning, issue the klog command to authenticate - as the admin user. Provide the password (admin_passwd) you + As a basic test of correct AFS functioning, issue the + kinit and + aklog commands to authenticate + as the admin user. + Provide the password (admin_passwd) you defined in Initializing Cell Security. - # /usr/afs/bin/klog admin + # kinit admin Password: admin_passwd + # aklog @@ -5400,14 +5261,14 @@ - Issue the tokens command to verify that the klog + Issue the tokens command to + verify that the aklog command worked correctly. If it did, the output looks similar to the following example for the abc.com cell, where admin's AFS UID is 1. If the output does not - seem correct, resolve the problem. Changes to the AFS initialization script are possibly necessary. The AFS Product - Support group can provide assistance as necessary. - # /usr/afs/bin/tokens + role="bold">example.com cell, where admin's AFS UID is 1. If the output does not + seem correct, resolve the problem. Changes to the AFS initialization script are possibly necessary. The OpenAFS mailing lists can provide assistance as necessary. + # tokens Tokens held by the Cache Manager: - User's (AFS ID 1) tokens for afs@abc.com [Expires May 22 11:52] + User's (AFS ID 1) tokens for afs@example.com [Expires May 22 11:52] --End of list-- @@ -5620,11 +5481,12 @@ - Issue the chkconfig command to activate the afs - configuration variable. Based on the instruction in the AFS initialization file that begins with the string + Issue the chkconfig command to activate the openafs-client and openafs-server + configuration variables. 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 afs + # /sbin/chkconfig --add openafs-client + # /sbin/chkconfig --add openafs-server @@ -6042,6 +5904,11 @@ Storing AFS Binaries in AFS + Sites with existing binary distribution mechanisms, including + those which use packaging systems such as RPM, may wish to skip this step, + and use tools native to their operating system to manage AFS configuration + information. + In the conventional configuration, you make AFS client binaries and configuration files available in the subdirectories of the /usr/afsws directory on client machines (afsws is an acronym for AFS work - Mount the AFS CD-ROM for this machine's system type on the local /cdrom directory, - 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 into the /tmp/afsdist directory, + if it is not already. copying AFS binaries into volume @@ -6177,41 +6043,19 @@ - Copy the contents of the indicated directories from the CD-ROM into the Copy the contents of the indicated directories from the + distribution into the /afs/cellname/sysname/usr/afsws directory. # cd /afs/.cellname/sysname/usr/afsws - # cp -rp /cdrom/sysname/bin . - # cp -rp /cdrom/sysname/etc . - # cp -rp /cdrom/sysname/include . - # cp -rp /cdrom/sysname/lib . - - requirements - - protecting binaries per AFS license - - licensing requirements - - - - - 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. - # cd /afs/.cellname/sysname/usr/afsws - # fs setacl -dir etc include lib -acl system:authuser rl \ - system:anyuser none - + # cp -rp /tmp/afsdist/sysname/bin . + # cp -rp /tmp/afsdist/sysname/etc . + # cp -rp /tmp/afsdist/sysname/include . + # cp -rp /tmp/afsdist/sysname/lib . + + creating symbolic link @@ -6309,8 +6153,13 @@ - The AFS CD-ROM for each system type has a top-level Documentation directory, with a - subdirectory for each document format provided. The different formats are suitable for online viewing, printing, or both. + OpenAFS Documentation is not currently provided with all + distributions, but may be downloaded separately from the OpenAFS + website + + The OpenAFS Documentation Distribution has a directory for each + document format provided. The different formats are suitable for online + viewing, printing, or both. This section explains how to create and mount a volume to house the documents, making them available to your users. The recommended mount point for the volume is /afs/cellname - Mount the AFS CD-ROM for any system type on the local /cdrom directory, if one is - not already. For instructions on mounting CD-ROMs (either locally or remotely via NFS), consult the operating system - documentation. + Unpack the OpenAFS documentation distribution into the + /tmp/afsdocs directory. You may use + a different directory, in which case the location you use should be + subsituted in the following examples. For instructions on unpacking + the distribution, consult the documentation for your operating + system's tar command. + copying - AFS documentation from CD-ROM + AFS documentation from distribution - CD-ROM + OpenAFS Distribution copying AFS documentation from @@ -6391,7 +6244,7 @@ copying - AFS documentation from CD-ROM + AFS documentation from OpenAFS distribution index.htm file @@ -6402,12 +6255,12 @@ - Copy the AFS documents in one or more formats from the CD-ROM into subdirectories of the Copy the AFS documents in one or more formats from the unpacked distribution into subdirectories of the /afs/cellname/afsdoc directory. Repeat the commands for each format. # mkdir format_name # cd format_name - # cp -rp /cdrom/Documentation/format . + # cp -rp /tmp/afsdocs/format . If you choose to store the HTML version of the documents in AFS, note that in addition to a subdirectory for each @@ -6680,7 +6533,42 @@ Enabling Access to Foreign Cells - + + With current OpenAFS releases, there exist a number of mechanisms for + providing access to foreign cells. You may add mount points in your AFS + filespace for each foreign cell you wish users to access, or you can + enable a 'synthetic' AFS root, which contains mountpoints for either all + AFS cells defined in the client machine's local + /usr/vice/etc/CellServDB, or for all cells + providing location information in the DNS. + + + + Enabling a Synthetic AFS root + + When a synthetic root is enabled, the client cache machine creates its + own root.afs volume, rather than using the one provided with your cell. This + allows clients to access all cells in the + CellServDB file and, optionally, all cells + registered in the DNS, without requiring system administrator action to + enable this access. Using a synthetic root has the additional advantage that + it allows a client to start its AFS service without a network available, as + it is no longer necessary to contact a fileserver to obtain the root volume. + + + OpenAFS supports two complimentary mechanisms for creating the + synthetic root. Starting the cache manager with the + -dynroot option adds all cells listed + in /usr/vice/etc/CellServDB to the client's + AFS root. Adding the -afsdb option in + 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. + + + Adding foreign cells to a conventional root volume</root> + <para>In this section you create a mount point in your AFS filespace for the <emphasis role="bold">root.cell</emphasis> 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, there must in addition be an entry for it in the client machine's local <emphasis @@ -6786,10 +6674,22 @@ </programlisting></para> </listitem> + <!-- XXX - Add stuff about registering your cell with + grand.central.org, and about configuring your DNS --> + + <listitem> + <para>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 <emphasis role="bold">CellServDB</emphasis> fragment + describing your cell to <!-- XXX - where does this get sent -->. If you intend + on deploying multiple database servers, please wait until you have installed + all of them before registering your cell.</para> + </listitem> <listitem> - <para>Please register your cell with the AFS Product Support group at this time. If you do not want to participate in the - global AFS namespace, they list your cell in a private <emphasis role="bold">CellServDB</emphasis> file that is not - available to other AFS cells.</para> + <para>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. <!-- XXX - detail what this is --> </listitem> </orderedlist></para> @@ -6868,13 +6768,16 @@ <replaceable>username</replaceable><emphasis role="bold">.admin</emphasis>. Administrators authenticate under these identities only when performing administrative tasks, and destroy the administrative tokens immediately after finishing the task (either by issuing the <emphasis role="bold">unlog</emphasis> command, or the <emphasis - role="bold">klog</emphasis> command to adopt their regular identity).</para> + role="bold">aklog</emphasis> command to adopt their regular identity).</para> </listitem> <listitem> - <para>Set a short ticket lifetime for administrator accounts (for example, 20 minutes) by using the <emphasis - role="bold">-lifetime</emphasis> argument to the <emphasis role="bold">kas setfields</emphasis> command, which is - described in the <emphasis>OpenAFS Administration Reference</emphasis>. Do not however, use a short lifetime for users + <para>Set a short ticket lifetime for administrator accounts (for example, 20 minutes) by using the + facilities of your KDC. For instance, with a MIT Kerberos KDC, this + can be performed using the + <emphasis role="bold">--max-ticket-life</emphasis> argument to + the <emphasis role="bold">kadmin modify_principal</emphasis> + command. Do not however, use a short lifetime for users who issue long-running <emphasis role="bold">backup</emphasis> commands.</para> </listitem> -- 2.39.5