Title:   README for afs_install
Version: 1.6
Author:  Paul Blackburn <mpb@acm.org>
Written: 16th August 1993
Updated: 1998/03/06

0 Contents
----------
1 Introduction
2 Goals
3 Environment
4 Method
5 Summary of mk-afs-srv actions
6 Pre-requisites
7 List of afs_install file
8 Steps for installing your first AFS fileserver
9 Installing subsequent fileservers (mk-afs-srv++)
10 Conclusion
11 Bibliography
12 Notes about rs_aix43

1 Introduction
--------------
This file describes how to install your first AFS fileserver using
the afs_install scripts. 

You will also find it useful to refer to the Transarc AFS Installation
Guide [1].

The process of installing your first AFS fileserver may seem daunting.
It did to me when confronted with an entire manual on the subject.
I decided to try to simplify and automate the process as much as possible.

2 Goals
-------
I needed to achieve the following:

2.1) Be able to rapidly install AFS according to a set of configuration data.
2.2) Have a detailed record of the installation. This assists me to
     understand issues like space requirements and how long installation takes.
     It also helps my colleagues to understand the installation.
2.3) Have a reference for the install/configuration data which I would
     keep under SCCS control.
2.4) Have the capability of installing with minimal manual intervention.

3 Environment
-------------
The install scripts were developed for use on IBM RISC System/6000
running AIX 3.2 (rs_aix32), AIX 4.1 (rs_aix41), AIX 4.2 (rs_aix42),
and AIX 4.3 (rs_aix43).

These scripts do take advantage of several AIX system management
commands such as:

  crfs  to create a file system
  chfs  to re-size (extend) a file system

4 Method
--------
After going through the installation process several times I found
it was possible to complete the initial AFS fileserver install with
a single script which took about 30 minutes.

Installation parameters are defined in: /usr/local/etc/afs.install.cf
This file has the format:

    hostname:parameter=value

A single installation script, mk-afs-srv, is used to install AFS binaries
and configure the AFS setup.

5 Summary of mk-afs-srv actions
-------------------------------
Here is a summary of what the mk-afs-srv script does:

    Extend /usr for AFS binaries
    Create AFS installation image filesystem /vol/afs34a
    tftp AFS install images from image server to /vol/afs34a
    Create /usr/afs and /usr/afsws
    Create AFS fileserver partition filesystems
    Replace AIX fsck with AFS fsck
    Create /etc/rc.afs
    Update /etc/inittab to start off /etc/rc.afs
    Setup initial /usr/vice/etc/CellServDB
    Define AFS cell name
    Initialize Security Mechanisms
    Prompt for and set "afs" and "admin" passwords
    Start up authentication server in NOAUTH mode
    Start Protection Server
    Start Volume Location Server
    Start Backup Server
    Start File Server, Volume Server, and Salvager
    Start Server Portion of the Update Server
    Start Controller for NTPD
    Load AFS Client Files
    setup /usr/vice/etc/CellServDB
    Create AFS cache filesystem (/usr/vice/cache)
    Start Cache Manager
    Set Up Top Levels of the AFS tree
    Turn on authorization checking
    Set up volumes to house AFS binaries
    Load AFS binaries into a volume, link to local disk

Programs used at install time:

    /usr/local/sbin/mk-afs-cf         # defines config data
    /usr/local/sbin/mk-afs-srv        # installs AFS on 1st server
    /usr/local/sbin/mk-afs-boswait    # waits for Ubik quorum to be elected

6 Pre-requisites
----------------
Before you attempt to run mk-afs-srv, you need to have already run
    mk-afs-readtape
which reads the Transarc binary distribution tape and creates compressed
tar archives ready for network installing of AFS.

You also need to enable tftpd in /etc/inetd.conf of the machine you have
chosen to be your AFS network install server (afsimageserver).

7 List of afs_install files
---------------------------

These can be obtained using anonymous FTP from:
    ftp://ftp.transarc.com/pub/afs-contrib/tools/afs_install/afs_install.tar

    usr/local/etc/afs_install/README            # this file
    usr/local/etc/afs_install/README.client
    usr/local/etc/afs_install/README.html	# client installs
    usr/local/sbin/mk-afs-boswait
    usr/local/sbin/mk-afs-bundle    # create AFS install images from /usr/afsws
    usr/local/sbin/mk-afs-cells       # display list of cells from CellServDB
    usr/local/sbin/mk-afs-cf          # shared functions and variables
    usr/local/sbin/mk-afs-cf.sample   # example of an afs_install cf file
    usr/local/sbin/mk-afs-cli         # installs an AFS client
    usr/local/sbin/mk-afs-dbsm        # adds dbserver function to a fileserver
    usr/local/sbin/mk-afs-fcells      # mount foreign cells
    usr/local/sbin/mk-afs-inetd       # starts AFS aware inetd
    usr/local/sbin/mk-afs-login       # configures for either AIX of AFS login
    usr/local/sbin/mk-afs-odmfix-httpd    # fix AIX ODM to start auth'd httpd
    usr/local/sbin/mk-afs-odmfix-infod    # fix AIX ODM to start auth'd infod
    usr/local/sbin/mk-afs-odmfix-qdaemon  # fix AIX ODM to start auth'd qdaemon
    usr/local/sbin/mk-afs-odmfix-sendmail # fix AIX ODM to start auth'd sendmail
    usr/local/sbin/mk-afs-rc          # creates idempotent /etc/rc.afs
    usr/local/sbin/mk-afs-readtape    # create AFS install images from tape
    usr/local/sbin/mk-afs-sendmail    # wrapper: get AFS auth and start sendmail
    usr/local/sbin/mk-afs-srv         # installs first file and DB server
    usr/local/sbin/mk-afs-srv++       # installs subsequent fileservers
    usr/local/sbin/mk-afs-ssc         # example script to build a config file
    usr/local/sbin/mk-afs-sync-mounts # sync mounts from CellServDB file
    usr/local/sbin/mk-afs-syncCSDB    # sync CellServDB on client with master
    usr/local/sbin/mk-afs-systype     # display system type (rs_aix32 rs_aix41)
    usr/local/sbin/mk-afs-wrap-httpd  # authenticate & start httpd
    usr/local/sbin/mk-afs-wrap-infod  # start AFS auth'd infod
    usr/local/sbin/mk-afs-wrap-qdaemon  # authenticate & start qdaemon
    usr/local/sbin/mk-afs-wrap-sendmail # authenticate & start sendmail
    usr/local/sbin/mk-afs-wrapper     # wraps daemons: sharing re-auth tokens

8 Steps for installing your first AFS fileserver
------------------------------------------------

8.1) Plan your installation

Try to make your first AFS fileserver have the lowest IP address of
all your AFS fileservers.

Consider: cache size and location, AFS partitions: size/location/name
Record all this data in the mk-afs configuration file:

        /usr/local/etc/afs_install/cf

8.2) Define your AFS installation parameters

Here is a detailed list of the parameters that you can define in:
    /usr/local/etc/afs_install/cf:

8.2.1) What will be the name of your AFS cache filesystem?

        afscachename="/usr/vice/cache"

8.2.2) How large (in 4MB physical partitions) will the AFS cache be?

        afscachesize="16"

8.2.3) Which volume group will house the AFS cache?

        afscachevg="rootvg"

    Note that choosing rootvg is a good idea because when you make
    a mksysb backup the backup will contain the cache.

8.2.4) What is your AFS cell comment (/usr/vice/etc/CellServDB)?

        afscellcomment="IBM UK AIX Systems Support Centre"

8.2.5) What is your AFS cell name?

        afscellname="aixssc.uk.ibm.com"

8.2.6) Will this system also be an AFS client?

        afsclient="ariel"

    (Any non-null value will do, I chose the hostname)

8.2.7) What options will afsd use on startup?

        afsdoptions="-stat 300 -daemons 2 -volumes 50 -nosettime"

    (See the Transarc AFS Installation Guide [1] for details)
    NB: "-nosettime" for a server only, clients *do* need the afsd to set time.

8.2.8) What is the fully-qualified-domain-name of the server?

        afsfileserver="ariel.aixssc.uk.ibm.com"

8.2.9) Where do the (network-install) AFS compressed archive files live?

        afsimagedir="/vol/afs34/tapeimages/$sysname"

        ($sysname is evaluated using /usr/local/sbin/mk-afs-systype)

8.2.10) What is the name of the filesystem that stores the compressed AFS
        archive files?

        afsimagefs="/vol/afs34"

8.2.11) How large (in 4MB physical partitions) is $afsimagefs?

        afsimagefssize="4"

8.2.12) What is the fully-qualified-domain-name of the server which holds
        $afsimagefs?

        afsimageserver="afsimageserver.aixssc.uk.ibm.com"

        (mk-afs-srv mk-afs-cli use tftp to download the images)

8.2.13) Which volume group will house $afsimagefs?

        afsimagevg="rootvg"

8.2.14) What is my AFS licence number?

        afslicense="replace-with-your-licence-number"

8.2.15) Will memory caching be used?

        afsmemcache=""

8.2.16) What are the AFS partitions?

	afspartitions="rootvg:/vicepa:165 vg01:/vicepb:247"

        Format is: volume-group:filesystemname:size-in-PP

8.2.17) What is the name of the post-install script?

	afspostinstall=""

        This is executed near the end of mk-afs-srv and allows you to
        do your own config (eg create volumes) as you need.

8.2.18) Is the current host a server?

    If the answer is yes, then set like:

	afsserver="ariel"
    (Any non-null value will do, I chose the hostname)

    Otherwise, set like:

        afsserver=""

8.2.19) What is the name of the AFS System Control machine?

	afssystemcontrolmachine=""

        (this is used in mk-afs-srv++ for installing fileservers after the
         primary fileserver has been established)

8.2.20) What are the IP addresses of NTP timeservers?

	afstimeservers="9.66.4.41 129.33.10.13"

        (one or more IP addresses)

8.2.21) How much extra space (in 4MB PPs) is needed in /usr?

	afsusrbumpsize="9"

        (this is for files in /usr/afs)

8.2.22) What is the name of the (temporary) afsws filesystem?

	afswsfs="/vol/afsws"

8.2.23) How large (in 4MB PPs) is $afswsfs?

	afswsfssize="8"

8.2.24) Which volume group will house $afswsfs?

	afswsvg="rootvg"

8.2.25) How much space will you allocate to the AFS cache (/usr/vice/cache)?

	afscachesize="16"

        (size in 4MB Physical Partitions)

8.2.26) AFS server partitions

        afspartitions="rootvg:/vicepa:165 vg01:/vicepb:247"

        For each AFS partition:
           Which volume group does it reside in
           What is the partition name
           How big is the partition (in 4MB Physical Partitions)

8.3 Read in the Transarc binary distribution tape

Use mk-afs-readtape to read in the tape and create compressed tar
files of the AFS commands (see afsimagefs above).

For example:
With AFS 3.4, I created a filesystem "/vol/afs34" of 16 MBytes.
The contents of /vol/afs34:
    /vol/afs34/CellServDB.export
    /vol/afs34/tapeimages/rs_aix41
    /vol/afs34/tapeimages/rs_aix41/set1.tar.Z
    /vol/afs34/tapeimages/rs_aix41/set3.tar.Z
    /vol/afs34/tapeimages/rs_aix41/set4.tar.Z
    /vol/afs34/tapeimages/rs_aix41/set5.tar.Z

CellServDB.export is the "starting" CellServDB file copied to /usr/vice/etc
by install scripts: mk-afs-srv, mk-afs-cli

8.4 Check /usr/local/etc/afs_install/cf

Make sure that you have correctly defined the installation parameters.

8.5 Run /usr/local/sbin/mk-afs-srv

You will be prompted for two passwords for the AFS administrator accounts.

As mk-afs-srv runs it logs actions, stdout, and stderr into
/var/log/install/mk-afs-srv. In a second xterm, you may find it useful to 

    tail -f /var/log/install/mk-afs-srv

to see what is happening as the installation proceeds.

9 Installing subsequent fileservers (mk-afs-srv++)
--------------------------------------------------
After you have installed the first fileserver, it is simple to
add further fileservers to your cell using mk-afs-srv++:

9.1) On the new fileserver, install the afs_install scripts
     in /usr/local/sbin. For example:

     Use anonymous FTP to get the scripts:
       ftp://ftp.transarc.com/pub/afs-contrib/tools/afs_install/afs_install.tar
     into /tmp/afs_install.tar
     cd /; tar -xvf /tmp/afs_install.tar

9.2) On the new fileserver, create /usr/local/etc/afs_install/cf
     as in 8.1 (above).

9.3) On the first fileserver, edit ~root/.rhosts to allow
     rsh to work from root on the new fileserver. This will
     be used to copy /usr/afs/db files from the first server.
     (this can be disabled after the new server is configured.)

9.4) Execute /usr/local/sbin/mk-afs-srv++
     You will be prompted for the AFS "admin" password.
     Actions are logged to /var/log/install/mk-afs-srv++

Note, if you want the new server to also be a database server then
you should execute /usr/local/sbin/mk-afs-dbsm.

10 Conclusion
------------

"afs_install" has proved itself very useful because it has saved time
and enabled me to do automatic (hands free) installs of AFS fileservers.

I hope you also find this useful. In any event, please let me know what you
think (or even just say "hi"). I welcome comments and feedback.

The "afs_install" scripts continue to be improved and updated.
Please make sure your copy is current.

If you would like to be informed of updates to afs_install,
please send me an email note (mpb@acm.org).
--
paul                             http://acm.org/~mpb/homepage.html

11 Bibliography
---------------

  [1] "AFS Installation Guide",
        Transarc Corporation, FS-D20-00.02.7

  [2] "afs_install" webpage (client install)
      ftp://ftp.transarc.com/pub/afs-contrib/tools/afs_install/README.html

12 Notes about rs_aix43
-----------------------

On the 4th of March 1998, Transarc release a version of AFS 3.4a which
included support for AIX 4.3. 

Unusually (for their AIX releases), this version is a combined rs_aix42
and rs_aix43 version with the default "sysname" being rs_aix42.

It is possible to use this code on an AIX 4.3 system but you have to
set the sysname (using "fs sysname rs_aix43") somewhere in your boot
run commands (eg /etc/rc.afs).

Alternatively, it is possible to "binary patch" the AFS kernel extensions
(/usr/vice/etc/dkload/afs.ext and /usr/vice/etc/dkload/afs.ext.trans)
replacing the string "rs_aix42" by "rs_aix43" throughout.

However, "afs_install" scripts are written assuming a single set of
install images for a single sysname. So, at my site, I have made the
"binary patch" to afs.ext and afs.ext.trans and created a set "afs_install"
images specifically for rs_aix43 with "mk-afs-bundle".

There are several "binary editors" generally available. I used one
called "bpe" (Binary Patch Editor) to edit afs.ext and afs.ext.trans.
