= AsimovSetupAfsServer =

This AsimovSetup sub-guide documents the step necessary to make the computer an [http://en.wikipedia.org/wiki/OpenAFS OpenAFS] server.


== Debian Documentation ==

The Debian documentation for OpenAFS is an excellent source of information for OpenAFS.  Once the AFS packages have been installed, they can be found in the various `/usr/share/doc/openafs-*` folders.  It is '''strongly''' recommended that you read through these.

To unzip the documentation `.gz` files, run a command like the following:
{{{
# gunzip /usr/share/doc/openafs-dbserver/*.gz
}}}


== Install OpenAFS Client ==

Just as a bit of a primer, it makes sense to first install the OpenAFS client.  Follow these steps:
 1. First build and install the OpenAFS kernel module:
{{{
# apt-get install openafs-modules-source openafs-doc module-assistant build-essential linux-headers-server
# module-assistant prepare openafs-modules
# module-assistant auto-build openafs-modules
# dpkg -i /usr/src/openafs-modules-<version>.deb
}}}
 1. Install the rest of the client:
{{{
apt-get install openafs-client
}}}
 1. When prompted, enter/select the following options:
    1. AFS cell this workstation belongs to: `davisonlinehome.name`
    1. Size of AFS cache in kB: `500000`
    1. DB server host names for your home cell: `eddings.davisonlinehome.name`
    1. Run Openafs client now and at boot?: ''Yes''
 1. To verify that the client is working, run the following command, which should list some folders:
{{{
$ ls /afs/davisonlinehome.name
}}}
 1. Install the tools required to authenticate to Kerberos and OpenAFS:
{{{
# apt-get install krb5-user openafs-krb5
}}}
 1. Edit `/etc/krb5.conf` to add the DAVISONLINEHOME.NAME realm:
{{{
[libdefaults]
	default_realm = DAVISONLINEHOME.NAME
...
[realms]
	DAVISONLINEHOME.NAME = {
		kdc = lewis.davisonlinehome.name
		admin_server = lewis.davisonlinehome.name
		default_domain = davisonlinehome.name
	}
...
[domain_realm]
	.davisonlinehome.name = DAVISONLINEHOME.NAME
	davisonlinehome.name = DAVISONLINEHOME.NAME
...
}}}
 1. Test to ensure everything is working (these commands should not generate any errors):
{{{
$ kinit <username>
$ aklog
}}}


== Install OpenAFS Server ==

With the client working, follow the next steps to install the server:
 1. Install the server packages:
{{{
# apt-get install openafs-dbserver openafs-fileserver
}}}

Stop here for a bit and actually read the Debian documentation for OpenAFS.  It should be considered required reading before following any of the next steps.  In particular, the "Adding Additional Servers" section of `/usr/share/doc/openafs-*/README.servers` describes (more-or-less) everything in this section in far greater detail than here.

Continue on with the installation:
 1. Copy the configuration files from `/etc/openafs/server` on an existing server to the same location on the new server (replace `user` and `*server` with the appropriate usernames and hostnames):
{{{
user@oldserver# scp -pr /etc/openafs/server/ user@newserver:/home/user
user@newserver# cp -a /home/user/server /etc/openafs/
user@newserver# chown -R root:root /etc/openafs/server
}}}
 1. Setup a fileserver service on the new server:
{{{
# bos create <host> fs fs -cmd "/usr/lib/openafs/fileserver \
              -p 23 -busyat 600 -rxpck 400 -s 1200 -l 1200 -cb 65535 -b 240 -vc 1200" \
              -cmd /usr/lib/openafs/volserver \
              -cmd /usr/lib/openafs/salvager -localauth
}}}
 1. Add the new server as a DB server on each server, including all old DB servers and the new one.  Run the following command on each server, replacing "`<server>` and `<new-server>`, as appropriate):
{{{
# bos addhost <server> <new-server> -localauth

e.g.:
user@oldserver# bos addhost oldserver.domain newserver.domain -localauth
user@newserver# bos addhost newserver.domain newserver.domain -localauth
}}}
 1. Restart the protection and volume services on each pre-existing server (wait a few seconds before moving on to the next server):
{{{
# bos restart <server> ptserver -localauth
# bos restart <server> vlserver -localauth
}}}
 1. Create the protection and volume service instances on the new server:
{{{
# bos create <host> ptserver simple /usr/lib/openafs/ptserver -localauth
# bos create <host> vlserver simple /usr/lib/openafs/vlserver -localauth
}}}

Since this server will be an off-site backup server for disaster recovery, it's best that none of the clients know of it.  OpenAFS clients will always go to the server with the lowest or closest IP (I can't recall which); there's no way beyond that to control which servers they access first.  However, if clients should be accessing this server (e.g. if it should be available to clients for when the other servers are down), this new server should have an `AFSDB` DNS entry created for it and/or be added to each client's `CellServDB` file.

To confirm that the installation went correctly, run the following commands:
 1. Authenticate to AFS:
{{{
$ kinit <afs-admin-username>
$ aklog
}}}
 1. Check the services' state on the new server:
{{{
$ bos status -server <server>
}}}


== Creating OpenAFS "vice" partitions ==

OpenAFS stores volumes in one or many "vice" partitions on each volume server: `/vicepa`, `/vicepb`, etc.  To resize the existing partitions and create a new vice partition, the server will have to be rebooted into a Live CD environment with access to `gparted`.

After booting into the Live CD environment, start the `gparted` tool and create a new `ext2` partition.  Once done, reboot back into the server's normal operating system.

Mount the new partition as `vicepa`:
 1. Run the following command to list all of the drives and partitions:
{{{
# fdisk -l
}}}
 1. Make note of the device node for the vice partition, e.g. /dev/sdb1. In the following steps, replace any occurrences of "/dev/sdxn" with the correct device node.
 1. Run the following command and make a note of the partition's UUID, e.g. "`293b2dcf-966b-461c-b220-8f9dd9e0ea35`":
{{{
# vol_id -u /dev/sdxn
}}}
 1. Create the mount point:
{{{
# mkdir /vicepa
}}}
 1. Edit the `/etc/fstab` file and add an entry similar to the following (replace the device node and UUID with the values noted earlier):
{{{
# /dev/sdxn <-> /vicepa
UUID=<partition-uuid-from-vol_id-command> /vicepa         ext2    defaults 0       2
}}}
 1. Mount all of the fstab entries:
{{{
# mount -a
}}}
 1. Ensure that the new partition was mounted correctly (should see at least a `lost+found` folder):
{{{
$ ls /vicepa
}}}


== AFS Administration ==

All of these commands require AFS administrator authentication, as follows:
{{{
$ kinit karl/admin
$ aklog
}}}

Alternatively, many of the commands can be run with the "`-localauth`" flag as `root` (or via `sudo`).  For example:
{{{
user@afsserver$ sudo bos restart -server afsserver -instance ptserver -localauth
}}}


=== Volume Management ===

To list all of the volumes in the database:
{{{
$ vos listvldb
}}}

To move a volume, "`somevol`", from `server1` to `server2`:
{{{
$ vos move -id somevol -fromserver server1 -frompartition a -toserver server2 -topartition a
}}}