LinuxAFSInstall/K5_README

   1 6/27/02
   2
   3 This is a brief description of how to use the OpenAFS Tools to create a cell
   4 that uses Kerberos 5 authentication, rather than the kaserver program that
   5 comes with OpenAFS.
   6
   7 *** INTRODUCTION ***
   8
   9 Kerberos 5 is an authentication protocol that is widely used by many
  10 applications.  If you have an OpenAFS environment that is K5-aware, your
  11 users will not have to obtain authenticate separately with OpenAFS -- they
  12 can use their Kerberos tickets instead.  For more information about the
  13 benefits of K5 over AFS authentication, see the following webpage:
  14
  15 http://www.mathematik.uni-karlsruhe.de/~iwrmm/Persons/Schulz/Unix/afs/afs-krb5.html
  16
  17 You should also check out AFSLore (http://grand.central.org/twiki/).
  18
  19 Also, refer to the OpenAFS Tools README for a much more complete set
  20 of requirements and instructions.  This document contains only things that
  21 are specific to the process of using Kerberos; it assumes you are already
  22 familiar with the other OpenAFS Tools requirements.
  23
  24 *** REQUIREMENTS ***
  25
  26 There are two major implementations of K5 -- MIT, and Heimdal.  From what
  27 I can gather, one is not significantly better than the other.  Unfortunately,
  28 their command line interfaces differ slightly, so for these tools I had to
  29 choose one with which to be compatible.  I chose the MIT version.  It is
  30 available at http://web.mit.edu/kerberos/www/index.html.  You should download,
  31 compile, and install this if you haven't already.
  32
  33 If you have an existing Kerberos realm that you plan to use, you only need to
  34 configure your soon-to-be OpenAFS server as a Kerberos client.  If you're
  35 making a new realm, you're going to have to create a master KDC (which can
  36 be the same as your OpenAFS server if you want, but that's not advised), and
  37 also configure your OpenAFS server to be a client.  The aforementioned MIT
  38 website has all the information you'll need on how to create or connect to
  39 a K5 realm.  IMPORTANT NOTE: If you're creating a new realm, keep in mind
  40 that the OpenAFS cell you will be creating later must have the same name as
  41 the realm, except the name of the realm must be in all caps.
  42
  43 The next step is to install the OpenAFS RPMs, available at
  44 http://www.openafs.org/.  You'll need to get the openafs, openafs-kernel,
  45 openafs-client, openafs-server, and openafs-krb5 packages, and install
  46 them all.
  47
  48 *** INSTALLATION ***
  49
  50 Installation is pretty easy.  Just do a normal install_afs command (as
  51 described in the OpenAFS Tools README), but specify the "-k" option.  This
  52 informs the program that you are going to be using Kerberos for authentication.
  53 During the installation process, it will ask for a Kerberos administration
  54 password; this is the password for the admin/admin principal in your
  55 Kerberos realm.  If it is not correct, the installation will not work!
  56
  57 IMPORTANT NOTE: As far as I can tell, the name of your cell must be THE SAME
  58 as the name of the Kerberos realm you are using, except in should be in lower
  59 case letters instead of upper case.  Supposedly there are ways to get around
  60 this, but I have not found them.  Currently, the OpenAFS Tools supports only
  61 same-name integration.
  62
  63 *** USE ***
  64
  65 After the install_afs program completes, you should be ready to go.  To test
  66 it out, execute the following commands.
  67
  68   kinit admin
  69   aklog
  70   vos create <machine_name> <partition_name> test.vol
  71
  72 This will create a test volume in your AFS cell.  If you see any error
  73 messages about authentication, then something's not working.
  74
  75 If everything works, you can start using your AFS cell.  When you want to make
  76 new users, make them a Kerberos account, and then give them a PTS entry in
  77 your OpenAFS cell.  That should be it!
  78
  79 *** COMMON PROBLEMS ***
  80
  81 Here are some solutions to problems I've encountered:
  82
  83 - Some KDC in your Kerberos realm must be running the following programs
  84 before you run the OpenAFS installation program:
  85   kadmind
  86   krb5kdc
  87   krb524d -m
  88 - The name of your OpenAFS cell and Kerberos realm must be the same, except
  89 for differences in capitalization.
  90 - Make sure, after uninstalling OpenAFS, to delete the 'admin' and 'afs'
  91 principals from the Kerberos database.
  92
  93 *** Future Work ***
  94
  95 These tools should support both MIT and Heimdal implementations, and any
  96 others that may exist.  Unfortunately, the only reasonable way to do this
  97 that I can see is to use the actual Kerberos 5 API.  This would require
  98 writing a C program or two and integrating them into the OpenAFS
  99 installation script.  While certainly possible, this would probably take
 100 some work.
 101
 102 Removing the same name dependency between the OpenAFS cell and the Kerberos
 103 realm would be fantastic.
 104