src/tools/openafs-tools-cmd.README

   1 ## OpenAFS Tools Documentation ##
   2 ## A collection of open source programs and interfaces designed ##
   3 ## to ease the configuration and maintenance of OpenAFS. ##
   4 ##
   5 ## Copyright 2001, International Business Machines Corporation and others.
   6 ## All Rights Reserved.
   7 ##
   8 ## This software has been released under the terms of the IBM Public
   9 ## License.  For details, see the LICENSE file in the top-level source
  10 ## directory or online at http://www.openafs.org/dl/license10.html
  11 ##
  12 ## openafs-tools, Version 1.2.2 ##
  13
  14 ####################### TABLE OF CONTENTS ###########################
  15
  16 1) Overview
  17 2) System configuration requirements
  18  a) OS
  19  b) OpenAFS
  20  c) OpenAFS Tools
  21 3) Usage
  22  a) OpenAFS Installation
  23  b) OpenAFS Uninstallation
  24 4) Implementation
  25  a) OpenAFS Installation
  26  b) OpenAFS Uninstallation
  27 5) Known Problems
  28 6) Future Expansion
  29
  30 ######################## 1) OVERVIEW ################################
  31
  32     The Tools use shell and Perl scripts.  So far, they has been tested
  33 only on Red Hat Linux 6.2 and 7.1 machines, running kernels 2.2 or 2.4.
  34     As of this version, OpenAFS Tools has two functions:
  35 installing OpenAFS, and uninstalling OpenAFS.
  36     We hope that you enjoy using and developing these tools, and
  37 that they enhance the popularity and use of OpenAFS.  If you have
  38 any questions, comments or suggestions, please send them to the
  39 OpenAFS mailing lists.
  40
  41 ############# 2) SYSTEM CONFIGURATION REQUIREMENTS ##################
  42
  43 a) OS
  44     OpenAFS Tools has been developed and tested on machines running
  45 Red Hat Linux 6.2 and 7.1, with kernel version 2.2 or 2.4.  It may
  46 or may not run well on other versions of Linux or other kernel
  47 versions -- use caution when using them with other setups.
  48
  49 b) OpenAFS
  50     Finally, you need to download and install the OpenAFS 1.2.2 RPMs
  51 for Red Hat Linux from http://www.openafs.org.  The files you need
  52 are:
  53     Red Hat 6.2:
  54       openafs-kernel-1.2.2-rh6.2.1.i386.rpm
  55       openafs-1.2.2-rh6.2.1.i386.rpm
  56       openafs-client-1.2.2-rh6.2.1.i386.rpm
  57       openafs-server-1.2.2-rh6.2.1.i386.rpm
  58     Red Hat 7.1:
  59       openafs-kernel-1.2.2-rh7.1.1.i386.rpm
  60       openafs-1.2.2-rh7.11..i386.rpm
  61       openafs-client-1.2.2-rh7.1.1.i386.rpm
  62       openafs-server-1.2.2-rh7.1.1.i386.rpm
  63 Once these are downloaded, install them (using an rpm -i or rpm -U
  64 command).
  65
  66 c) OpenAFS Tools
  67     Now all that's left to do is install the OpenAFS Tools rpm.  The
  68 file you need is openafs-tools-1.1.1-1.i386.rpm.  Install it using
  69 an rpm -i or rpm -U command.  This will create several directories
  70 and populate your system with necessary files.  The main directories
  71 created and populated is:
  72     /usr/afs/tools/install/
  73 Now you should be ready to get started.
  74
  75 ########################## 3) USAGE #################################
  76
  77 a) OpenAFS Installation
  78
  79     Execute the /usr/afs/tools/install/install_afs command.
  80 It can take a variety of arguments to specify how you would like
  81 to set the machine up.  If you do not specify needed arguments
  82 on the command line, you will be prompted for them interactively.
  83 To get a rundown on how to use install_afs, execute:
  84   /usr/afs/tools/install/install_afs help
  85 Once configured correctly, this machine will run the installation
  86 program (the same one run by the web interface), and restart your
  87 computer.
  88
  89 b) OpenAFS Uninstallation
  90
  91     The uninstallation program is very simple.  Just run
  92   /usr/afs/tools/install/afs_uninstall
  93 It does not accept any arguments and will not prompt you for
  94 anything.  Be forewarned, however: this will uninstall OpenAFS from
  95 your system and delete any information served from that machine in
  96 OpenAFS filespace.  You should also restart your machine after
  97 running the command, to avoid potential problems with future OpenAFS
  98 installations.
  99
 100 ##################### 4) IMPLEMENTATION #############################
 101
 102     This section will focus on the details of the implementation of
 103 OpenAFS tools.  It will outline the code and file structure of the
 104 package, and will document the choices made during implementation, so
 105 that someone working on the code can have a better understanding for
 106 what's there already.
 107
 108 a) OpenAFS Installation
 109
 110     The files involved in OpenAFS installation are:
 111
 112   - Possible AFS configuration files (/etc/sysconfig/afs):
 113     /usr/afs/tools/install/afsinit_both
 114     /usr/afs/tools/install/afsinit_server
 115     /usr/afs/tools/install/afsinit_client
 116   - Checking the state of OpenAFS on the system:
 117     /usr/afs/tools/install/.afs_state
 118   - Command line installation:
 119     /usr/afs/tools/install/install_afs
 120   - Perl scripts:
 121     /usr/afs/tools/install/check_udebug.pl
 122     /usr/afs/tools/install/write_fstab.pl
 123     /usr/afs/tools/install/write_pam.pl
 124
 125 What follows is a brief summary of the installation process.
 126   - Installation starts with the script install_afs.  The first thing
 127 it does is ensure that the files needed for setting up additional
 128 servers and/or clients exist in the appropriate places (see section
 129 3.a.i for a description of these files).  Then, after indicating to
 130 the state file that installation has begun, it begins installing
 131 OpenAFS.
 132   - For clients, it then enables Pam Login Authentication using
 133 the write_pam.pl program to change the /etc/pam.d/login file.
 134   - For servers, it will alter the /etc/fstab file via the
 135 write_fstab.pl program, mounting the user-specified hard drive to
 136 the /vicepa directory.
 137   - For additional servers, it now copies the required
 138 files from the /usr/afs/tools/install/afs directory to the
 139 /usr/afs/etc directory, and defines the upclient processes,
 140 which will periodically update the server's /usr/afs/bin and
 141 /usr/afs/etc directories based on those directories on the first
 142 server in the cell.
 143   - A first server must then briefly start up a bosserver with
 144 the noauth flag in order to create the keyfile and set the cell
 145 name.  It immediately shuts down the bosserver when this is down.
 146 Next, it uses a kaserver with noauth to initialize cell security.
 147 This involves creating two user accounts: afs and admin.  afs is an
 148 account for the server processes and will not be needed by the user.
 149 Currently we use the administrative password for the afs account
 150 password.  The admin account is now added to the bos server database
 151 and a pts entry is created as well.  Also, the afs account password
 152 is added as a key for the server. The kaserver proces is terminated.
 153 The pts database is then bootstrapped to add the administrator to it.
 154   - For first servers, a normal bosserver is started.  It then
 155 creates the database server processes (kaserver, buserver, ptserver,
 156 and vlserver).
 157   - The file server, volume server, and salvager processes are now
 158 started for servers.
 159   - Next the root.afs volume is created for first servers, and on
 160 additional servers the vldb is synced up.
 161   - On a first server, the upserver process is then defined.
 162   - Next the /usr/vice/etc/ThisCell file is created on a non-server
 163 machine, and for non-first-servers the /usr/vice/etc/CellServDB file
 164 is copied from its location at /usr/afs/tools/install/vice.
 165   - The correct AFS setup file is copied to /etc/sysconfig/.
 166   - Now the bosserver process is killed for server machines.
 167   - The next thing it does is initialize afs (/etc/rc.d/init.d/afs),
 168 and for servers it klogs in as admin.
 169   - Then it activates the OpenAFS initialization script by running
 170 /sbin/chkconfig --add afs.
 171   - Next a first server will configure the OpenAFS file space.
 172 Before doing this, however, it must first wait until a quorum has
 173 been elected.  After the check, the root.cell volume is created,
 174 it is mounted at /afs/<cell_name>, and the permissions are set
 175 on both it and /afs as read and lookup for any user.  A read-write
 176 version of root.cell is mounted at /afs/.<cell_name>.  Replication
 177 sites for both root.afs and root.cell are added.
 178   - If necessary, client functionality is removed.
 179   - Lastly, a done.txt file is written explaining what has been done
 180 and what comes next, for use by the web interface.  The state file
 181 is notified that installation is complete, and then the script ends.
 182
 183 b) OpenAFS Uninstallation
 184
 185     Uninstallation has only two files: the main script and the
 186 redirection script.
 187   /usr/afs/tools/install/afs_uninstall
 188 Here is a brief summary of what it does to uninstall OpenAFS:
 189   - First it indicates to the state file that uninstallation has
 190 begun.
 191   - Then it kills whatever bos server processes may be running.
 192   - Next, it deletes everything stored in an AFS partition directory
 193 ( i.e. vicep*).
 194   - It deletes the links to any initialization scripts in the startup
 195 directories (/etc/rc.d/rc*.d/*afs*)
 196   - It removes the PAM afs file, and reconfigures the PAM login file
 197 to not have integrated AFS logon.
 198   - It deletes the db, etc, local, and logs directories from
 199 /usr/afs.
 200   - Next it removes unnecessary files from /usr/vice/etc.
 201   - Then it deletes everything from the cache (/usr/vice/cache).
 202   - Finally, it informs the state file that uninstallation is
 203 complete.
 204
 205 ##################### 5) KNOWN PROBLEMS #############################
 206
 207     We have encountered a few problems along the way, and wanted to
 208 document them as such.
 209   - Be careful when installing something without client
 210 functionality.  This seems to require an extra reboot of the
 211 machine.  After installing OpenAFS, restart your machine again,
 212 and that should get it working properly.
 213     There very well be some other problems that we haven't
 214 yet encountered.  If you encounted such a problem, please send a
 215 description to openafs-devel@openafs.org
 216
 217 #################### 6) FUTURE EXPANSION ############################
 218
 219     There is a lot of room for developing this package into something
 220 very useful, and we would like to make a few suggestions for future
 221 additions/fixes to the code.
 222   - Allow ways to authenticate other than the kaserver, such as krb5.
 223   - Find a secure, automatic way to transfer files from a server
 224 machine to a machine that is to be set up as an additional server or
 225 a client, rather then require the manual tranferral of those files.
 226   - Agree on a standard way to set up the filespace of a cell, as in
 227 where to put the user volumes, etc., so that this can all be done
 228 automatically by the scripts.
 229   - Port this code to other operating systems to make it more
 230 widely useful.
 231   - Resolve all "Known Problems" (see section 5).
 232   - Test, test, test.