## 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/<cell_name>, 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/.<cell_name>.  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.
