LinuxAFSInstall/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.5 ##
  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.1.1.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.2.2-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
  86 If you are creating an additional server or not a server, OpenAFS
  87 Tools will ensure that you have all the required files on your
  88 system.  These are files needed by the OpenAFS installation program
  89 to connect you to cells that already exist.  You must get these files
  90 manually from an existing server, as we have not yet implemented
  91 a secure way of doing this automatically.  For additional servers,
  92 the files you need to copy are:
  93     - Copy the /usr/afs/etc/ThisCell file from the existing server
  94 to /usr/afs/tools/install/afs/ThisCell on your machine.
  95     - Copy the /usr/afs/etc/CellServDB file from the existing server
  96 to /usr/afs/tools/install/afs/CellServDB on your machine.
  97     - Copy the /usr/afs/etc/KeyFile file from the existing server
  98 to /usr/afs/tools/install/afs/KeyFile on your machine.
  99     - Copy the /usr/afs/etc/UserList file from the existing server
 100 to /usr/afs/tools/install/afs/UserList on your machine.
 101     - Copy the /usr/vice/etc/CellServDB file from the existing server
 102 to /usr/afs/tools/install/vice/CellServDB on your machine.
 103
 104     For client-only installation, you need the following file:
 105     - Copy the /usr/vice/etc/CellServDB file from the existing server
 106 to /usr/afs/tools/install/vice/CellServDB on your machine.
 107
 108 b) OpenAFS Uninstallation
 109
 110     The uninstallation program is very simple.  Just run
 111   /usr/afs/tools/install/afs_uninstall
 112 It does not accept any arguments and will not prompt you for
 113 anything.  Be forewarned, however: this will uninstall OpenAFS from
 114 your system and delete any information served from that machine in
 115 OpenAFS filespace.  You should also restart your machine after
 116 running the command, to avoid potential problems with future OpenAFS
 117 installations.
 118
 119 ##################### 4) IMPLEMENTATION #############################
 120
 121     This section will focus on the details of the implementation of
 122 OpenAFS tools.  It will outline the code and file structure of the
 123 package, and will document the choices made during implementation, so
 124 that someone working on the code can have a better understanding for
 125 what's there already.
 126
 127 a) OpenAFS Installation
 128
 129     The files involved in OpenAFS installation are:
 130
 131   - Possible AFS configuration files (/etc/sysconfig/afs):
 132     /usr/afs/tools/install/afsinit_both
 133     /usr/afs/tools/install/afsinit_server
 134     /usr/afs/tools/install/afsinit_client
 135   - Checking the state of OpenAFS on the system:
 136     /usr/afs/tools/install/.afs_state
 137   - Command line installation:
 138     /usr/afs/tools/install/install_afs
 139   - Perl scripts:
 140     /usr/afs/tools/install/check_udebug.pl
 141     /usr/afs/tools/install/write_fstab.pl
 142     /usr/afs/tools/install/write_pam.pl
 143
 144 What follows is a brief summary of the installation process.
 145   - Installation starts with the script install_afs.  The first thing
 146 it does is ensure that the files needed for setting up additional
 147 servers and/or clients exist in the appropriate places (see section
 148 3.a for a description of these files).  Then, after indicating to
 149 the state file that installation has begun, it begins installing
 150 OpenAFS.
 151   - For clients, it then enables Pam Login Authentication using
 152 the write_pam.pl program to change the /etc/pam.d/login file.
 153   - For servers, it will alter the /etc/fstab file via the
 154 write_fstab.pl program, mounting the user-specified hard drive to
 155 the /vicepa directory.
 156   - For additional servers, it now copies the required
 157 files from the /usr/afs/tools/install/afs directory to the
 158 /usr/afs/etc directory, and defines the upclient processes,
 159 which will periodically update the server's /usr/afs/bin and
 160 /usr/afs/etc directories based on those directories on the first
 161 server in the cell.
 162   - A first server must then briefly start up a bosserver with
 163 the noauth flag in order to create the keyfile and set the cell
 164 name.  It immediately shuts down the bosserver when this is down.
 165 Next, it uses a kaserver with noauth to initialize cell security.
 166 This involves creating two user accounts: afs and admin.  afs is an
 167 account for the server processes and will not be needed by the user.
 168 Currently we use the administrative password for the afs account
 169 password.  The admin account is now added to the bos server database
 170 and a pts entry is created as well.  Also, the afs account password
 171 is added as a key for the server. The kaserver process is terminated.
 172 The pts database is then bootstrapped to add the administrator to it.
 173   - For first servers, a normal bosserver is started.  It then
 174 creates the database server processes (kaserver, buserver, ptserver,
 175 and vlserver).
 176   - The file server, volume server, and salvager processes are now
 177 started for servers.
 178   - Next the root.afs volume is created for first servers, and on
 179 additional servers the vldb is synced up.
 180   - On a first server, the upserver process is then defined.
 181   - Next the /usr/vice/etc/ThisCell file is created on a non-server
 182 machine, and for non-first-servers the /usr/vice/etc/CellServDB file
 183 is copied from its location at /usr/afs/tools/install/vice.
 184   - The correct AFS setup file is copied to /etc/sysconfig/.
 185   - Now the bosserver process is killed for server machines.
 186   - The next thing it does is initialize afs (/etc/rc.d/init.d/afs),
 187 and for servers it klogs in as admin.
 188   - Then it activates the OpenAFS initialization script by running
 189 /sbin/chkconfig --add afs.
 190   - Next a first server will configure the OpenAFS file space.
 191 Before doing this, however, it must first wait until a quorum has
 192 been elected.  After the check, the root.cell volume is created,
 193 it is mounted at /afs/<cell_name>, and the permissions are set
 194 on both it and /afs as read and lookup for any user.  A read-write
 195 version of root.cell is mounted at /afs/.<cell_name>.  Replication
 196 sites for both root.afs and root.cell are added.
 197   - If necessary, client functionality is removed.
 198   - Lastly, a done.txt file is written explaining what has been done
 199 and what comes next, for use by the web interface.  The state file
 200 is notified that installation is complete, and then the script ends.
 201
 202 b) OpenAFS Uninstallation
 203
 204     Uninstallation has only one file:
 205   /usr/afs/tools/install/afs_uninstall
 206 Here is a brief summary of what it does to uninstall OpenAFS:
 207   - First it indicates to the state file that uninstallation has
 208 begun.
 209   - Then it kills whatever bos server processes may be running.
 210   - Next, it deletes everything stored in an AFS partition directory
 211 ( i.e. vicep*).
 212   - It deletes the links to any initialization scripts in the startup
 213 directories (/etc/rc.d/rc*.d/*afs*)
 214   - It removes the PAM afs file, and reconfigures the PAM login file
 215 to not have integrated AFS logon.
 216   - It deletes the db, etc, local, and logs directories from
 217 /usr/afs.
 218   - Next it removes unnecessary files from /usr/vice/etc.
 219   - Then it deletes everything from the cache (/usr/vice/cache).
 220   - Finally, it informs the state file that uninstallation is
 221 complete.
 222
 223 ##################### 5) KNOWN PROBLEMS #############################
 224
 225     We have encountered a few problems along the way, and wanted to
 226 document them as such.
 227   - Be careful when installing something without client
 228 functionality.  This seems to require an extra reboot of the
 229 machine.  After installing OpenAFS, restart your machine again,
 230 and that should get it working properly.
 231     There very well be some other problems that we haven't
 232 yet encountered.  If you encounted such a problem, please send a
 233 description to openafs-devel@openafs.org
 234
 235 #################### 6) FUTURE EXPANSION ############################
 236
 237     There is a lot of room for developing this package into something
 238 very useful, and we would like to make a few suggestions for future
 239 additions/fixes to the code.
 240   - Allow ways to authenticate other than the kaserver, such as krb5.
 241   - Find a secure, automatic way to transfer files from a server
 242 machine to a machine that is to be set up as an additional server or
 243 a client, rather then require the manual tranferral of those files.
 244   - Agree on a standard way to set up the filespace of a cell, as in
 245 where to put the user volumes, etc., so that this can all be done
 246 automatically by the scripts.
 247   - Port this code to other operating systems to make it more
 248 widely useful.
 249   - Resolve all "Known Problems" (see section 5).
 250   - Test, test, test.