README.krb5

   1 This README is a series of instructions for setting up kerberos for use with
   2 the libvirt stuff.  There are a lot of steps, it is fairly complicated, and
   3 the error reporting is pretty bad, so this is not for the faint of heart.
   4
   5 It really helps to have a basic understanding of kerberos, KDC, and other
   6 terminology when getting this up.  You *can* just follow the steps here, but
   7 when things go wrong (and they almost certainly will), you'll need more
   8 background knowledge.
   9
  10 To start, you need a minimum of 3 machines here:
  11
  12 1)  The FreeIPA server, where you install the freeipa software, and which acts
  13 as your KDC.  I'll refer to this one as "freeipa" throughout the document.
  14 2)  The host machine, that is, the one that is running ovirt and libvirtd.
  15 I'll refer to this one as "ovirt" throughout the document.
  16 3)  The client machine, that is, the one that you will be running
  17 virt-manager/virsh on, and connecting to the ovirt machine with.  I'll refer
  18 to this machine as "client" throughout the document.
  19
  20 With that initial part, let's get started:
  21
  22 On the freeipa machine:
  23 1)  Follow the directions on http://freeipa.org/page/QuickInstall to get the
  24 FreeIPA server up and running.  Note that if you are running on F8 or later,
  25 you'll need to pay particular attention to the mod_auth_kerb section.  During
  26 the FreeIPA setup, you can call your realm whatever you want; I'll use
  27 OVIRT.BOSTON.REDHAT.COM for the rest of the document.
  28 2)  Once you have freeipa installed somewhere, you'll need to add a principle
  29 for the libvirt service.  To do this, on the freeipa box, run:
  30
  31 # kadmin.local
  32 > addprinc -randkey libvirt/ovirt@OVIRT.BOSTON.REDHAT.COM
  33 > ktadd -k /tmp/ovirt-libvirt.tab libvirt/ovirt@OVIRT.BOSTON.REDHAT.COM
  34 > quit
  35
  36 This will add a new principle for libvirt for the "ovirt" machine, and export
  37 that principle to the /tmp/ovirt-libvirt.tab file.  Note that you'll need
  38 to replace "ovirt" and "OVIRT.BOSTON.REDHAT.COM" with the full DNS name and the
  39 realm you are using, respectively.
  40
  41 On the ovirt machine:
  42
  43 NOTE: if you use the scripts (i.e. ovirt-pxe.sh) to generate an oVirt Node
  44 image, all of the following is done for you.  These are just notes for doing
  45 it by hand.
  46
  47 1)  First, we need to edit the krb5.conf to point to the correct realm and
  48 KDC.  In /etc/krb5.conf, in the [realms] section, you'll want to add your
  49 realm name, along with it's kdc and admin server.  In my case, it looks like:
  50
  51 [realms]
  52  OVIRT.BOSTON.REDHAT.COM = {
  53   kdc = freeipa:88
  54   admin_server = freeipa:749
  55  }
  56
  57 You'll need to replace "freeipa" with the fully qualified domain name of your
  58 freeipa server.
  59
  60 Now, you'll need to associate that realm with DNS names.  So, you'll want to
  61 add 2 lines to the [domain_realm] section, which basically associates that
  62 realm with these names.  In my case, it looks like:
  63
  64 [domain_realm]
  65  .ovirt.boston.redhat.com = OVIRT.BOSTON.REDHAT.COM
  66  ovirt.boston.redhat.com = OVIRT.BOSTON.REDHAT.COM
  67
  68 Finally, we'll need to make sure that this realm is the default realm.  In
  69 the [libdefaults] section, you'll want to change the default_realm to point
  70 to your realm.  In my case, it looks like:
  71
  72 [libdefaults]
  73  default_realm = OVIRT.BOSTON.REDHAT.COM
  74
  75 2)  Now we need to make sure that libvirtd is configured properly.  In the
  76 simple case, libvirtd is using kerberos for authentication, and TCP for the
  77 transport.  We can also set it up to use kerberos for authentication and
  78 TLS for the transport, but that's not covered yet.  In any case, we need to
  79 open up the raw TCP field for our use.  Edit /etc/libvirt/libvirtd.conf, and
  80 uncomment "listen_tcp = 1".
  81
  82 3)  Next we need the keytable from the freeipa server.  You should be able
  83 to take the keytab you exported from the freeipa machine earlier (with the
  84 ktadd -k command), and install it on the ovirt machine.  Basically just copy
  85 that exported keytab to /etc/libvirt/krb5.tab
  86
  87 4)  Finally, we need to start the libvirtd daemon.  Of course, make sure this
  88 libvirtd has the GSSAPI/kerberos stuff compiled in :).  Assuming that is the
  89 case, you'll need to start it like:
  90
  91 KRB5_KTNAME=/etc/libvirt/krb5.tab /root/libvirtd --listen --daemon
  92
  93 On the client machine:
  94 1)  Setup up krb5.conf exactly the same as described in step 1 for the ovirt
  95 machine.
  96 2)  Edit /etc/sasl2/libvirt.conf, and add:
  97 mech_list: gssapi
  98
  99 3)  Now you'll need to kinit to get an initial kerberos ticket for the realm.
 100 In my case, I run:
 101
 102 # kinit admin@OVIRT.BOSTON.REDHAT.COM
 103
 104 and enter in the password to get a ticket.  You'll have to replace the username
 105 and the realm to suit your own setup.
 106
 107 At this point, you should run:
 108
 109 # klist
 110
 111 and should see output similar to the following:
 112
 113 Ticket cache: FILE:/tmp/krb5cc_0
 114 Default principal: admin@VIRT.BOSTON.REDHAT.COM
 115
 116 Valid starting     Expires            Service principal
 117 10/31/07 12:14:51  11/01/07 12:11:21  krbtgt/VIRT.BOSTON.REDHAT.COM@VIRT.BOSTON.REDHAT.COM
 118
 119
 120 Kerberos 4 ticket cache: /tmp/tkt0
 121 klist: You have no tickets cached
 122
 123 4)  Now we can attempt to connect to the remote hypervisor with virsh.  Of
 124 course, make sure your virsh has the GSSAPI/kerberos support compiled in:
 125
 126 # virsh --connect qemu+tcp://ovirt/system list --all
 127
 128 This should output something like:
 129
 130  Id Name                 State
 131 ----------------------------------
 132   - f8i386               shut off
 133   - f8x86_64             shut off
 134
 135
 136 Troubleshooting:
 137 Two main problems tend to trip people up on their first try: differences in
 138 time, and problems with DNS.  You have to make sure that all three machines
 139 in this example (freeipa, ovirt, client) are synced via NTP, and you have to
 140 make sure that all three machines can resolve each other's DNS name both
 141 forwards and backwards.  If either of those isn't true, it won't work.
 142
 143 On the "freeipa" machine, you can look at /var/log/krb5kdc.log to get an idea
 144 of what went wrong.
 145
 146 If you see an error like "Server not found in Kerberos database", either you
 147 didn't add the principle correctly in the first step here, or you have an
 148 alternate name for the server in /etc/hosts.  Remove any /etc/hosts aliases and
 149 try again.