This is just a rough sketch for now; we will expand it soon.

These steps are listed in approximately the order in which they should be performed; please try to maintain that.

=== Out Of Band Access ===

All machines owned by hcoop should, if possible, have some out-of-band mechanism for:

 1. Keyboard access
 2. Screen access
 3. Power-cycling

Functions 1+2 are typically provided by kvm.hcoop.net; assuming you plan on going with that, you should connect the server's keyboard and video to the kvm switch.

Each server has its own solution for 3, usually in the form of a "service processor".  You should investigate and document the appropriate service processor settings.  If the service processor requires its own IP address, you should name it {{{foo-sp.hcoop.net}}} where {{{foo.hcoop.net}}} is the name of the server.

=== Add a DNS entry for the server ===

Straightforward.

=== Install Debian ===

We use Debian.  Install it.

=== Kernel Compilation ===

It is generally a good idea for hcoop to compile its own kernels.  Regarding statically-compiled kernels, see StaticallyCompiledKernels for some opinions.

=== AFS Client ===

You should install the {{{openafs-client}}}, {{{openafs-krb5}}}, {{{openafs-modules-source}}}, {{{openafs-dbg}}}, {{{openafs-doc}}}, {{{libopenafs-dev}}},  packages from {{{/afs/hcoop.net/common/debian/}}}.  Here is a block of commands to cut and paste if you are lazy:

{{{
  apt-get install krb5-user libkrb5-dev
  mkdir -p /tmp/openafs-packages
  cd /tmp/openafs-packages
  scp ssh.hcoop.net:/afs/hcoop.net/common/debian/openafs/1.4.6/\*.deb      ./
  scp ssh.hcoop.net:/afs/hcoop.net/common/debian/libpam-afs-session/\*.deb ./
  dpkg -i \
    openafs-client*.deb         \
    openafs-krb5*.deb           \
    openafs-modules-source*.deb \
    openafs-dbg*.deb            \
    openafs-doc*.deb            \
    libopenafs-dev*.deb         
  cd /tmp
  rm -rf /tmp/openafs-packages
}}}

Also be sure to

{{{
  apt-get install module-assistant build-essential module-init-tools
}}}

Once these packages are installed, you will want to run

{{{
  module-assistant a-i -t openafs-modules
}}}

... assuming you compiled your own kernel and the compiled kernel tree resides in /usr/src/linux.  If this is not the case, you are on your own.

If the command above completes, it will have created and installed a .deb containing the kernel module.  You may need to run

{{{
  /etc/init.d/module-init-tools start
}}}

to refresh whatever module wonkery linux maintains in obscure locations.  Once this is figured out (if all else fails, reboot) you should be able to

{{{
  /etc/init.d/openafs-client start
}}}

Do this and check that /afs shows up.

=== Install AFS Extras ===

Now that afs is up, you can easily:

{{{
  dpkg -i /afs/hcoop.net/common/debian/libnss-ptdb/*.deb
  dpkg -i /afs/hcoop.net/common/debian/libpam-afs-session/*.deb
  dpkg -i /afs/hcoop.net/common/debian/libpam-krb5/*.deb
  dpkg -i /afs/hcoop.net/common/debian/fsr/*.deb
}}}

The first three packages are explained below; the last one is the {{fsr}} command (recursive "{{{fs}}}").

=== runit ===

The runit package is useful for launching and monitoring daemons with '''clean process state'''.  This is often important when dealing with tokens and pags.

=== dnscache ===

You can install the dnscache package to make the server self-sufficient for dns resolution purposes (it acts as a tiny dns server just for localhost).  This improves the reliability of the overall infrastructure.

There is a copy of this package in /afs/megacz.com/debian/; the author of the software recently changed its license, so it will be a standard package in the next release of debian (it may even be in etch-backports already).

Starting dnscache via runit is often a good idea; this ensures that it starts early in the boot process and that it is restarted if it dies for any reason.

=== /etc/krb5.conf ===

You should copy /etc/krb5.conf from deleuze to the new server.  This is VERY IMPORTANT.  What is NOT in this file is also almost as important as what IS in this file, so think three times before adding or removing anything.

=== configuring libnss-ptdb ===

The {{{libnss-ptdb}}} package lets linux use the AFS {{{ptserver}}} (protection server) as a name service.  The {{{ptserver}}} keeps track of all the users in AFS.  A "name service" is Linux's mechanism for answering these four queries:

 1. the userid for a given username
 2. the username for a userid
 3. the home directory for a user
 4. the shell for a user
 5. what groups a user is in

To make {{{ptserver}}} our primary choice for name service, edit {{{/etc/nsswitch.conf}}} and change the following three lines to look like this:

{{{
passwd:         ptdb   files
group:          afspag files
shadow:                files 
}}}

=== configuring pam ===

PAM is the mechanism used by Linux to do the following:

 1. decide if somebody is who they say they are (authentication; in our case via kerberos)
 2. set up ''sessions'' (in the case of AFS, this means creating PAGs)
 3. change passwords (in our case, changing the password in the KDC)

FIXME

Mostly this consists of copying mire's /etc/pam.d/*, although it would be a good idea to state precisely which parts of that need to be copied.

=== configuring ssh to get tokens+tickets ===

You will need to create a "host principal" for the new server; if you are setting up {{{server.hcoop.net}}}, then it must have the name

{{{
   host/server.hcoop.net@HCOOP.NET
}}}

Add this principal to the KDC like this (execute these commands on the new server, as root, while holding admin tokens):

{{{
   kadmin -r HCOOP.NET
     ank -randkey host/server.hcoop.net@HCOOP.NET
     ktadd -k /etc/krb5.keytab
     quit
   chown root:root /etc/krb5.keytab
   chmod go-rwx /etc/krb5.keytab
}}}

Then these lines to /etc/ssh/sshd_config:

{{{
  GssapiKeyExchange yes
  GssapiAuthentication yes
  GSSAPICleanupCredentials no
  UsePAM yes
}}}