Turn headings into actual links
[openafs-wiki.git] / 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