AFSLore/KerberosAFSInstall.mdwn

   1 # <a name="Installing Kerberos  AFS"></a> Installing Kerberos &amp; AFS
   2
   3 AFS includes its own implementation of Kerberos, the KAServer. However, new installs of KAServer are not recommended as it is based on a draft version of the obsolete Kerberos 4 protocol. Even though AFS doesn't support [[KerberosV]] directly, it is highly recommended that you set up a [[KerberosV]] realm for your AFS cell and **not** install the KAServer. See [[KerberosV]] for the many advantages of using the latest Kerberos for your network authentication.
   4
   5 Note that this document is under development. Also, I don't try to explain the [[OpenAFS]] specific parts of the install -- This document describes only the changes that have to be made to create a new [[OpenAFS]] cell with [[KerberosV]] authentication. If you have followed these instructions and are still having problems please email the openafs-info mailing list.
   6
   7 ## <a name="Basics"></a> Basics
   8
   9 To continue, you need a working Kerberos realm. See [[SettingUpAuthentication]] for the implementation options, and refer to the documentation that comes with your particular version of Kerberos to establish your realm. It is easiest if your realm name is the caps version of your cell name, which in turn is the same as your site's domain name. For example if your site's domain is 'greekmythology.com', your Kerberos realm name should be 'GREEKMYTHOLOGY.COM' and your AFS cell name should be 'greekmythology.com'. See [[KerberosTerms]] if you are confused on what a "realm" is.
  10
  11 Once you have a working Kerberos realm, ie. you can "kinit" as yourself and receive valid Kerberos tickets, you are ready to continue on installing [[OpenAFS]]. (NOTE: If you are working on the Red Hat Linux platform, there is an RPM available that may ease your pain considerably. See [[LinuxAFSInstall]].)
  12
  13 ## <a name="OpenAFS"></a> [[OpenAFS]]
  14
  15 ### <a name="Starting the Install"></a> Starting the Install
  16
  17 Now we will begin the [[OpenAFS]] installation. The relevant part of the [[OpenAFS]] documentation can be found at [OpenAFS installation documentation](http://www.openafs.org/pages/doc/QuickStartUnix/auqbg005.htm#HDRWQ17). Follow the instructions in [Creating AFS Directories](http://www.openafs.org/pages/doc/QuickStartUnix/auqbg005.htm#Header_32) and begin the [Platform Specific Procedures](http://www.openafs.org/pages/doc/QuickStartUnix/auqbg005.htm#HDRWQ20) as appropriate for your operating system. **SKIP** the "Enabling AFS Login" section of your operating system's instructions. Also note that you may need to reboot during this procedure (particularly on Solaris).
  18
  19 Now you are ready to continue on to [Starting the BOS Server](http://www.openafs.org/pages/doc/QuickStartUnix/auqbg005.htm#HDRWQ50) (... someone want to chime in here and explain how one can use pt\_util etc to do this part without running in -noauth??). Proceed to [Defining Cell Name](http://www.openafs.org/pages/doc/QuickStartUnix/auqbg005.htm#HDRWQ51). During the [Starting Database Servers](http://www.openafs.org/pages/doc/QuickStartUnix/auqbg005.htm#HDRWQ52) section, **do not** issue the <code>**bos create**</code> command to add the kaserver.
  20
  21 ### <a name="Create AFS Keys and Administrato"></a> Create AFS Keys and Administrators
  22
  23 First you will need to create a principal "afs" or "afs/greekmythology.com" in your [[KerberosV]] database. The latter is the preferred alternative, especially if you will support more than one [[AFSCell]] with a single [[KerberosRealm]]. In case you have [[KerberosIV]], create afs or afs.greekmythology.com respectively.
  24
  25 Your [[KerberosV]] realm must support krb524 for aklog to work, typically. In other words, it has to be able to respond to your version 4 requests (as AFS is based on [[KerberosIV]] protocol).
  26
  27 Next we will create an AFS [[KeyFile]] and an administrator principal in the Kerberos database. The procedure for creating an AFS [[KeyFile]] depends on which Kerberos implementation you have chosen to use, but the logic is the same.
  28
  29 Things to remember about AFS [[KeyFile]]: they must contain a key using the des-cbc-crc encryption type and the key must have exactly same kvno as the afs/greekmythology.com@GREEKMYTHOLOGY.COM in the Kerberos database. If cell is same as lowercased GREEKMYTHOLOGY.COM name, you can create <afs@GREEKMYTHOLOGY.COM> instead of afs/cell@GREEKMYTHOLOGY.COM.
  30
  31 [[KerberosVMIT]]:
  32
  33 - set up krb524d. You will need to make sure your krb524d server host includes something like this in krb5.conf. Only one of the 2 entries should be needed for a realm, depending on how you did the setup in your [[KerberosV]] database.
  34
  35     [appdefaults]
  36     afs_krb5 = {
  37           REALM.NAME = {
  38                     afs = false
  39                     afs/cell.name = false
  40           }
  41     }
  42
  43 [[HeimdalKTH]] from <http://www.pdc.kth.se/heimdal>:
  44
  45 - kdc will service krb524 requests
  46 - edit /etc/krb5.conf similar to to example below
  47
  48     [logging]
  49     default = FILE:/var/log/krb5libs.log
  50     kdc = FILE:/var/log/krb5kdc.log
  51     admin_server = FILE:/var/log/kadmind.log
  52
  53     [ktutil]
  54             dns_lookup_realm = false
  55             dns_lookup_kdc = false
  56
  57     [libdefaults]
  58             dns_lookup_realm = false
  59             dns_lookup_kdc = false
  60             ktype_is_etype = true
  61             encrypt = yes
  62             forward = yes
  63             srv_lookup = no
  64             srv_try_txt = no
  65             srv_try_rfc2052 = no
  66             default_realm = GREEKMYTHOLOGY.COM
  67             clockskew = 300
  68             kdc = 127.0.0.1
  69             v4_instance_resolve = true
  70             krb4_get_tickets = yes
  71             forwardable = true
  72             v4_name_convert = {
  73                     host = {
  74                             rcmd = host
  75                             ftp = ftp
  76                     }
  77                     plain = {
  78                             something = something-else
  79                     }
  80             }
  81
  82     [realms]
  83             GSF.DE = {
  84                     kdc = 127.0.0.1
  85                     admin_server = 127.0.0.1
  86                     krb525_server = 127.0.0.1
  87                     v4_name_convert = {
  88                             ftp = ftp
  89                             pop = pop
  90                             rcmd = host
  91                     }
  92                     v4_instance_convert = true
  93                     default_domain = greekmythology.com
  94             }
  95
  96     [domain_realm]
  97             .greekmythology.com = GREEKMYTHOLOGY.COM
  98             greekmythology.com = GREEKMYTHOLOGY.COM
  99
 100     [kadmin]
 101     kdc =
 102     # you can disable fallback DNS queries, if don't have registered name like kerberos.yourdomain
 103     dns_lookup_realm = false
 104     dns_lookup_kdc = false
 105     default_keys = v4 v5 afs3
 106     afs-cell = greekmythology.com
 107     v4-realm = GREEKMYTHOLOGY.COM
 108
 109     [kdc]
 110             enable-kerberos4 = true
 111             afs-cell =
 112             enable-524 = true
 113             v4-realm = GREEKMYTHOLOGY.COM
 114
 115 Someone wrote a nice pages at: <http://www.cs.cmu.edu/afs/andrew.cmu.edu/usr/shadow/www/afs/afs-with-kerberos.html> <http://www.contrib.andrew.cmu.edu/~shadow/afs/afs-with-kerberos.html>
 116
 117 [[KerberosIV]], like KTH Kerberos4 from <http://www.pdc.kth.se/kth-krb> :
 118
 119 Create afs principal entry in kerberos database:
 120
 121 If you have afs key already created using "kadmin add", you had to specify password on interactively. That's quite weak password. Much better is to do <code>**kadmin get**</code>. <code>**kadmin**</code> will try to download the key from KDC, and if it's not present, it will create one, using random key. That's what we want.
 122
 123 ksrvutil(1) does similar and doesn't require from you to have kadmind(1) running on your machine. The "get" command does same: downloads or (in our case) creates new afs principal using random password. The next example expects that joe.admin is you and you know the proper password to get full access to you kerberos database:
 124
 125        mv /etc/srvtab /etc/srvtab.orig
 126        /usr/athena/sbin/ksrvutil -p joe.admin get
 127        Name [rcmd]: afs
 128        Instance [hostname]: greekmythology.com
 129        Realm [GREEKMYTHOLOGY.COM]: GREEKMYTHOLOGY.COM
 130        Is this correct? (y,n) [y]
 131        Add more keys? (y,n) [n]
 132        Password for joe.admin@GREEKMYTHOLOGY.COM
 133        # list keys in /etc/srvtab, look for the AFS key and it's kvno
 134        ksrvutil list
 135        mv /etc/srvtab /etc/srvtab.afskey
 136        mv /etc/srvtab.orig /etc/srvtab
 137
 138 If you want to make the above more complicated, you will need <code>**/usr/athena/sbin/ext\_srvtab**</code> utility to extract already existing key from Kerberos KDC and save it into /etc/srvtab. It will ask you for your master kerberos password (but if you installed kerberos in the "proper" way, you've used random password which you don't know at all), so better use <code>**ksrvutil**</code> as described above and forget <code>**ext\_srvtab**</code>.
 139
 140 Now you should have the afs key in /etc/srvtab.afskey.
 141
 142 Import this AFS key from Kerberos keyfile (/etc/srvtab format) into AFS /usr/afs/etc/KeyFile using <code>**asetkey**</code> utility, which is I think from /afs/transarc.com/public/afs-contrib
 143
 144         asetkey add 0 /etc/srvtab.afskey afs.greekmythology\.com@GREEKMYTHOLOGY.COM
 145
 146 This [[KeyFile]] with the AFS-key you can just always re-copy to new AFS machines. Be sure that the key version number KVNO is always same in this [[KeyFile]] and in Kerberos database. On all these machines you of course need afs.hostname.REALM key loaded into their <code>**/etc/srvtab**</code> (create them with <code>**'/ust/athena/bin/ksrvutil get'**</code>).
 147
 148 You can test if you have same keys in kerberos and AFS like this:
 149
 150       kauth username
 151       tokens
 152
 153 If you have some tokens now, then it works and you can now shutdown kaserver. Users, which you have created under kaserver are stored in /usr/afs/db/kaserver.\*, but you can just forget them. Create these users again in Kerberos. With [[KerberosIV]] from KTH they get stored under /var/kerberos, when using Heimdal under /var/heimdal/.
 154
 155 [[KerberosVMIT]]:
 156
 157 - The AFS-Kerberos5 migration kit includes a program <code>**asetkey**</code>
 158
 159 Save the AFS key from kerberos KDC to a file, possibly using kadmin(see KTH [[KerberosIV]] section above), and the use either <code>**asetkey**</code> or use <code>**ktutil**</code> (see [[HeimdalKTH]] section below) to convert the format and save into [[KeyFile]].
 160
 161            asetkey add 0 /etc/srvtab.afskey afs.cell@REALM
 162
 163 The \`0' above means kvno (key version number 0). Use ktutils list or similar like <code>**kadmin get**</code> command to see, what kvno has the afs key in Kerberos database. Use exactly same number when running <code>**asetkey**</code>. There's
 164
 165 [[HeimdalKTH]]:
 166
 167 - The [[HeimdalKTH]] distribution's <code>**ktutil**</code> can copy directly into an AFS [[KeyFile]]
 168
 169            kadmin --admin-server=my_kdc_server
 170            kadmin> add --random-key afs/cell
 171            kadmin> del_enctype afs/cell@REALM des3-cbc-sha1
 172            kadmin> get afs/cell@REALM
 173            kadmin> list *
 174            kadmin> ext -k /etc/afskeytabfile.krb5
 175            kadmin> quit
 176            ktutil -k /etc/afskeytabfile.krb5 list
 177            ktutil copy FILE:/etc/afskeytabfile.krb5 AFSKEYFILE:/usr/afs/etc/KeyFile
 178
 179 After you have a working [[KeyFile]] installed in the appropriate directory (/usr/afs/etc/KeyFile for transarc-paths, ???? otherwise) and with the appropriate permissions (0600, owner root), we can create administrative users for AFS. This is a two step process as we first create an authentication principal in the Kerberos database then add the admin user in the authorization ("protection") database in the AFS server.
 180
 181 Create a user ("joe/admin" in this example) using the appropriate kadmin utility with your [[KerberosV]] distribution. Set a secure password, and note that setting Kerberos admin rights for this user does **not** affect his AFS rights. Please note, that "joe/admin@REALM" is [[KerberosV]] notation and that [[KerberosIV]] is using "joe.admin@REALM". As AFS is based on [[KerberosIV]], you should specify "joe.admin@REALM" or just "joe.admin". (I did this mistake recently and for days was hunting for an explanation, why while having valid tickets, valid AFS tokens with proper kvno (key version number as the one in Kerberos KDC) fileserver, ptserver and bosserver complain about my AFS token being invalid. Yes, I had in the /usr/(afs|vice)/etc/UserList file "joe/admin@REALM"). In [[OpenAFS]]-1.2.8, you can possibly enable Kerbero5 syntax for usernames (See [this message](https://lists.openafs.org/pipermail/openafs-devel/2002-December/003632.html) to openafs-devel)
 182
 183 Now we will use the <code>**pts**</code> command in [[OpenAFS]] to add this joe.admin user to the AFS administrators group named system:administrators. The username could be just "joe" or "admin", but it's a good habit to have .admin appended to it (it is called instance):
 184
 185        pts createuser -name joe.admin -cell greekmythology.com -noauth
 186        pts adduser joe.admin system:administrators -cell  -noauth
 187
 188 where greekmythology.com is the name of your local cell. After your complete this step, you can continue on to...
 189
 190 ### <a name="Finishing _OpenAFS installation"></a> Finishing [[OpenAFS]] installation
 191
 192 First, activate the new AFS [[KeyFile]] by executing:
 193
 194        bos restart <machine name> -all -cell <cell name> -noauth
 195
 196 After this restart, try using kinit to get Kerberos tickets for admin then (if necessary) use aklog to get an AFS token or use afslog if afsd client cache is already running. Basically ensure that the AFS [[KeyFile]] is valid:
 197
 198        /usr/heimdal/sbin/ktutil copy AFSKEYFILE:/usr/afs/etc/KeyFile FILE:/etc/afskeytabfile.krb5
 199        /usr/heimdal/bin/kinit -k -t /etc/afskeytabfile.krb5 afs/greekmythology.com
 200        # you should be able to autenticate against KDC using the /etc/afskeytabfile.krb5
 201        #    where is saved your afs key in keytab form recognizable by Kerberos5
 202        /usr/heimdal/klist
 203        # you should see you have afs/greekmythology.com ticket having some expiration time etc.
 204
 205 Proceed to the [Starting File Server](http://www.openafs.org/pages/doc/QuickStartUnix/auqbg005.htm#HDRWQ60) section of the [[OpenAFS]] documentation. The rest of the documentation can be completed without any changes. (What about replacing NTP with something recent, though...? See FAQ [[3.22|Main/AdminFAQ#NTP]] and [[[NTP|Main/FurtherReading#NTP]]])
 206
 207 ## <a name="Setting up Transparent Login"></a> Setting up Transparent Login
 208
 209 In its current state, you have to manually log into your AFS cell through kinit and possibly aklog (explain aklog..., debugging using "tokens" etc). There are several methods to enable transparent login to both local resources (the machine itself) and AFS through a single password. See [[KerberosV]] and [[SettingUpAuthentication]] for some information.
 210
 211 -- [[JasonGarman]] - 05 Feb 2002 -- [[DerrickBrashear]] - 26 Nov 2002