## OpenAFS Tools Documentation ## ## A collection of open source programs and interfaces designed ## ## to ease the configuration and maintenance of OpenAFS. ## ## ## Copyright 2001, International Business Machines Corporation and others. ## All Rights Reserved. ## ## This software has been released under the terms of the IBM Public ## License. For details, see the LICENSE file in the top-level source ## directory or online at http://www.openafs.org/dl/license10.html ## ## openafs-tools, Version 1.2.5 ## ####################### TABLE OF CONTENTS ########################### 1) Overview 2) System configuration requirements a) OS b) OpenAFS c) OpenAFS Tools 3) Usage a) OpenAFS Installation b) OpenAFS Uninstallation 4) Implementation a) OpenAFS Installation b) OpenAFS Uninstallation 5) Known Problems 6) Future Expansion ######################## 1) OVERVIEW ################################ The Tools use shell and Perl scripts. So far, they has been tested only on Red Hat Linux 6.2 and 7.1 machines, running kernels 2.2 or 2.4. As of this version, OpenAFS Tools has two functions: installing OpenAFS, and uninstalling OpenAFS. We hope that you enjoy using and developing these tools, and that they enhance the popularity and use of OpenAFS. If you have any questions, comments or suggestions, please send them to the OpenAFS mailing lists. ############# 2) SYSTEM CONFIGURATION REQUIREMENTS ################## a) OS OpenAFS Tools has been developed and tested on machines running Red Hat Linux 6.2 and 7.1, with kernel version 2.2 or 2.4. It may or may not run well on other versions of Linux or other kernel versions -- use caution when using them with other setups. b) OpenAFS Finally, you need to download and install the OpenAFS 1.2.2 RPMs for Red Hat Linux from http://www.openafs.org. The files you need are: Red Hat 6.2: openafs-kernel-1.2.2-rh6.2.1.i386.rpm openafs-1.2.2-rh6.2.1.i386.rpm openafs-client-1.2.2-rh6.2.1.i386.rpm openafs-server-1.2.2-rh6.2.1.i386.rpm Red Hat 7.1: openafs-kernel-1.2.2-rh7.1.1.i386.rpm openafs-1.2.2-rh7.1.1.i386.rpm openafs-client-1.2.2-rh7.1.1.i386.rpm openafs-server-1.2.2-rh7.1.1.i386.rpm Once these are downloaded, install them (using an rpm -i or rpm -U command). c) OpenAFS Tools Now all that's left to do is install the OpenAFS Tools rpm. The file you need is openafs-tools-1.2.2-1.i386.rpm. Install it using an rpm -i or rpm -U command. This will create several directories and populate your system with necessary files. The main directories created and populated is: /usr/afs/tools/install/ Now you should be ready to get started. ########################## 3) USAGE ################################# a) OpenAFS Installation Execute the /usr/afs/tools/install/install_afs command. It can take a variety of arguments to specify how you would like to set the machine up. If you do not specify needed arguments on the command line, you will be prompted for them interactively. To get a rundown on how to use install_afs, execute: /usr/afs/tools/install/install_afs help If you are creating an additional server or not a server, OpenAFS Tools will ensure that you have all the required files on your system. These are files needed by the OpenAFS installation program to connect you to cells that already exist. You must get these files manually from an existing server, as we have not yet implemented a secure way of doing this automatically. For additional servers, the files you need to copy are: - Copy the /usr/afs/etc/ThisCell file from the existing server to /usr/afs/tools/install/afs/ThisCell on your machine. - Copy the /usr/afs/etc/CellServDB file from the existing server to /usr/afs/tools/install/afs/CellServDB on your machine. - Copy the /usr/afs/etc/KeyFile file from the existing server to /usr/afs/tools/install/afs/KeyFile on your machine. - Copy the /usr/afs/etc/UserList file from the existing server to /usr/afs/tools/install/afs/UserList on your machine. - Copy the /usr/vice/etc/CellServDB file from the existing server to /usr/afs/tools/install/vice/CellServDB on your machine. For client-only installation, you need the following file: - Copy the /usr/vice/etc/CellServDB file from the existing server to /usr/afs/tools/install/vice/CellServDB on your machine. b) OpenAFS Uninstallation The uninstallation program is very simple. Just run /usr/afs/tools/install/afs_uninstall It does not accept any arguments and will not prompt you for anything. Be forewarned, however: this will uninstall OpenAFS from your system and delete any information served from that machine in OpenAFS filespace. You should also restart your machine after running the command, to avoid potential problems with future OpenAFS installations. ##################### 4) IMPLEMENTATION ############################# This section will focus on the details of the implementation of OpenAFS tools. It will outline the code and file structure of the package, and will document the choices made during implementation, so that someone working on the code can have a better understanding for what's there already. a) OpenAFS Installation The files involved in OpenAFS installation are: - Possible AFS configuration files (/etc/sysconfig/afs): /usr/afs/tools/install/afsinit_both /usr/afs/tools/install/afsinit_server /usr/afs/tools/install/afsinit_client - Checking the state of OpenAFS on the system: /usr/afs/tools/install/.afs_state - Command line installation: /usr/afs/tools/install/install_afs - Perl scripts: /usr/afs/tools/install/check_udebug.pl /usr/afs/tools/install/write_fstab.pl /usr/afs/tools/install/write_pam.pl What follows is a brief summary of the installation process. - Installation starts with the script install_afs. The first thing it does is ensure that the files needed for setting up additional servers and/or clients exist in the appropriate places (see section 3.a for a description of these files). Then, after indicating to the state file that installation has begun, it begins installing OpenAFS. - For clients, it then enables Pam Login Authentication using the write_pam.pl program to change the /etc/pam.d/login file. - For servers, it will alter the /etc/fstab file via the write_fstab.pl program, mounting the user-specified hard drive to the /vicepa directory. - For additional servers, it now copies the required files from the /usr/afs/tools/install/afs directory to the /usr/afs/etc directory, and defines the upclient processes, which will periodically update the server's /usr/afs/bin and /usr/afs/etc directories based on those directories on the first server in the cell. - A first server must then briefly start up a bosserver with the noauth flag in order to create the keyfile and set the cell name. It immediately shuts down the bosserver when this is down. Next, it uses a kaserver with noauth to initialize cell security. This involves creating two user accounts: afs and admin. afs is an account for the server processes and will not be needed by the user. Currently we use the administrative password for the afs account password. The admin account is now added to the bos server database and a pts entry is created as well. Also, the afs account password is added as a key for the server. The kaserver process is terminated. The pts database is then bootstrapped to add the administrator to it. - For first servers, a normal bosserver is started. It then creates the database server processes (kaserver, buserver, ptserver, and vlserver). - The file server, volume server, and salvager processes are now started for servers. - Next the root.afs volume is created for first servers, and on additional servers the vldb is synced up. - On a first server, the upserver process is then defined. - Next the /usr/vice/etc/ThisCell file is created on a non-server machine, and for non-first-servers the /usr/vice/etc/CellServDB file is copied from its location at /usr/afs/tools/install/vice. - The correct AFS setup file is copied to /etc/sysconfig/. - Now the bosserver process is killed for server machines. - The next thing it does is initialize afs (/etc/rc.d/init.d/afs), and for servers it klogs in as admin. - Then it activates the OpenAFS initialization script by running /sbin/chkconfig --add afs. - Next a first server will configure the OpenAFS file space. Before doing this, however, it must first wait until a quorum has been elected. After the check, the root.cell volume is created, it is mounted at /afs/, and the permissions are set on both it and /afs as read and lookup for any user. A read-write version of root.cell is mounted at /afs/.. Replication sites for both root.afs and root.cell are added. - If necessary, client functionality is removed. - Lastly, a done.txt file is written explaining what has been done and what comes next, for use by the web interface. The state file is notified that installation is complete, and then the script ends. b) OpenAFS Uninstallation Uninstallation has only one file: /usr/afs/tools/install/afs_uninstall Here is a brief summary of what it does to uninstall OpenAFS: - First it indicates to the state file that uninstallation has begun. - Then it kills whatever bos server processes may be running. - Next, it deletes everything stored in an AFS partition directory ( i.e. vicep*). - It deletes the links to any initialization scripts in the startup directories (/etc/rc.d/rc*.d/*afs*) - It removes the PAM afs file, and reconfigures the PAM login file to not have integrated AFS logon. - It deletes the db, etc, local, and logs directories from /usr/afs. - Next it removes unnecessary files from /usr/vice/etc. - Then it deletes everything from the cache (/usr/vice/cache). - Finally, it informs the state file that uninstallation is complete. ##################### 5) KNOWN PROBLEMS ############################# We have encountered a few problems along the way, and wanted to document them as such. - Be careful when installing something without client functionality. This seems to require an extra reboot of the machine. After installing OpenAFS, restart your machine again, and that should get it working properly. There very well be some other problems that we haven't yet encountered. If you encounted such a problem, please send a description to openafs-devel@openafs.org #################### 6) FUTURE EXPANSION ############################ There is a lot of room for developing this package into something very useful, and we would like to make a few suggestions for future additions/fixes to the code. - Allow ways to authenticate other than the kaserver, such as krb5. - Find a secure, automatic way to transfer files from a server machine to a machine that is to be set up as an additional server or a client, rather then require the manual tranferral of those files. - Agree on a standard way to set up the filespace of a cell, as in where to put the user volumes, etc., so that this can all be done automatically by the scripts. - Port this code to other operating systems to make it more widely useful. - Resolve all "Known Problems" (see section 5). - Test, test, test.