fix Build-requires when image ISO is in SRPM
[ovirt-node-image.git] / README.krb5
blob50d31595117228669ef7a2673c643d5f523d1ea1
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.
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.
10 To start, you need a minimum of 3 machines here:
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.
20 With that initial part, let's get started:
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:
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
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.
41 On the ovirt machine:
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.
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:
51 [realms]
52  OVIRT.BOSTON.REDHAT.COM = {
53   kdc = freeipa:88
54   admin_server = freeipa:749
55  }
57 You'll need to replace "freeipa" with the fully qualified domain name of your
58 freeipa server.
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:
64 [domain_realm]
65  .ovirt.boston.redhat.com = OVIRT.BOSTON.REDHAT.COM
66  ovirt.boston.redhat.com = OVIRT.BOSTON.REDHAT.COM
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:
72 [libdefaults]
73  default_realm = OVIRT.BOSTON.REDHAT.COM
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".
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
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:
91 KRB5_KTNAME=/etc/libvirt/krb5.tab /root/libvirtd --listen --daemon
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
99 3)  Now you'll need to kinit to get an initial kerberos ticket for the realm.
100 In my case, I run:
102 # kinit admin@OVIRT.BOSTON.REDHAT.COM
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.
107 At this point, you should run:
109 # klist
111 and should see output similar to the following:
113 Ticket cache: FILE:/tmp/krb5cc_0
114 Default principal: admin@VIRT.BOSTON.REDHAT.COM
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
120 Kerberos 4 ticket cache: /tmp/tkt0
121 klist: You have no tickets cached
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:
126 # virsh --connect qemu+tcp://ovirt/system list --all
128 This should output something like:
130  Id Name                 State
131 ----------------------------------
132   - f8i386               shut off
133   - f8x86_64             shut off
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.
143 On the "freeipa" machine, you can look at /var/log/krb5kdc.log to get an idea
144 of what went wrong.
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.