4 When setting up Kerberos in a production environment, it is best to
5 have multiple slave KDCs alongside with a master KDC to ensure the
6 continued availability of the Kerberized services. Each KDC contains
7 a copy of the Kerberos database. The master KDC contains the writable
8 copy of the realm database, which it replicates to the slave KDCs at
9 regular intervals. All database changes (such as password changes)
10 are made on the master KDC. Slave KDCs provide Kerberos
11 ticket-granting services, but not database administration, when the
12 master KDC is unavailable. MIT recommends that you install all of
13 your KDCs to be able to function as either the master or one of the
14 slaves. This will enable you to easily switch your master KDC with
15 one of the slaves if necessary (see :ref:`switch_master_slave`). This
16 installation procedure is based on that recommendation.
20 - The Kerberos system relies on the availability of correct time
21 information. Ensure that the master and all slave KDCs have
22 properly synchronized clocks.
24 - It is best to install and run KDCs on secured and dedicated
25 hardware with limited access. If your KDC is also a file
26 server, FTP server, Web server, or even just a client machine,
27 someone who obtained root access through a security hole in any
28 of those areas could potentially gain access to the Kerberos
32 Install and configure the master KDC
33 ------------------------------------
35 Install Kerberos either from the OS-provided packages or from the
36 source (See :ref:`do_build`).
40 For the purpose of this document we will use the following
43 kerberos.mit.edu - master KDC
44 kerberos-1.mit.edu - slave KDC
45 ATHENA.MIT.EDU - realm name
46 .k5.ATHENA.MIT.EDU - stash file
47 admin/admin - admin principal
49 See :ref:`mitK5defaults` for the default names and locations
50 of the relevant to this topic files. Adjust the names and
51 paths to your system environment.
54 Edit KDC configuration files
55 ----------------------------
57 Modify the configuration files, :ref:`krb5.conf(5)` and
58 :ref:`kdc.conf(5)`, to reflect the correct information (such as
59 domain-realm mappings and Kerberos servers names) for your realm.
60 (See :ref:`mitK5defaults` for the recommended default locations for
63 Most of the tags in the configuration have default values that will
64 work well for most sites. There are some tags in the
65 :ref:`krb5.conf(5)` file whose values must be specified, and this
66 section will explain those.
68 If the locations for these configuration files differs from the
69 default ones, set **KRB5_CONFIG** and **KRB5_KDC_PROFILE** environment
70 variables to point to the krb5.conf and kdc.conf respectively. For
73 export KRB5_CONFIG=/yourdir/krb5.conf
74 export KRB5_KDC_PROFILE=/yourdir/kdc.conf
80 If you are not using DNS TXT records (see :ref:`mapping_hostnames`),
81 you must specify the **default_realm** in the :ref:`libdefaults`
82 section. If you are not using DNS URI or SRV records (see
83 :ref:`kdc_hostnames` and :ref:`kdc_discovery`), you must include the
84 **kdc** tag for each *realm* in the :ref:`realms` section. To
85 communicate with the kadmin server in each realm, the **admin_server**
86 tag must be set in the
87 :ref:`realms` section.
89 An example krb5.conf file::
92 default_realm = ATHENA.MIT.EDU
96 kdc = kerberos.mit.edu
97 kdc = kerberos-1.mit.edu
98 admin_server = kerberos.mit.edu
105 The kdc.conf file can be used to control the listening ports of the
106 KDC and kadmind, as well as realm-specific defaults, the database type
107 and location, and logging.
109 An example kdc.conf file::
119 max_renewable_life = 7d 0h 0m 0s
120 master_key_type = aes256-cts
121 supported_enctypes = aes256-cts:normal aes128-cts:normal
122 # If the default location does not suit your setup,
123 # explicitly configure the following values:
124 # database_name = /var/krb5kdc/principal
125 # key_stash_file = /var/krb5kdc/.k5.ATHENA.MIT.EDU
126 # acl_file = /var/krb5kdc/kadm5.acl
130 # By default, the KDC and kadmind will log output using
131 # syslog. You can instead send log output to files like this:
132 kdc = FILE:/var/log/krb5kdc.log
133 admin_server = FILE:/var/log/kadmin.log
134 default = FILE:/var/log/krb5lib.log
136 Replace ``ATHENA.MIT.EDU`` and ``kerberos.mit.edu`` with the name of
137 your Kerberos realm and server respectively.
141 You have to have write permission on the target directories
142 (these directories must exist) used by **database_name**,
143 **key_stash_file**, and **acl_file**.
148 Create the KDC database
149 -----------------------
151 You will use the :ref:`kdb5_util(8)` command on the master KDC to
152 create the Kerberos database and the optional :ref:`stash_definition`.
156 If you choose not to install a stash file, the KDC will
157 prompt you for the master key each time it starts up. This
158 means that the KDC will not be able to start automatically,
159 such as after a system reboot.
161 :ref:`kdb5_util(8)` will prompt you for the master password for the
162 Kerberos database. This password can be any string. A good password
163 is one you can remember, but that no one else can guess. Examples of
164 bad passwords are words that can be found in a dictionary, any common
165 or popular name, especially a famous person (or cartoon character),
166 your username in any form (e.g., forward, backward, repeated twice,
167 etc.), and any of the sample passwords that appear in this manual.
168 One example of a password which might be good if it did not appear in
169 this manual is "MITiys4K5!", which represents the sentence "MIT is
170 your source for Kerberos 5!" (It's the first letter of each word,
171 substituting the numeral "4" for the word "for", and includes the
172 punctuation mark at the end.)
174 The following is an example of how to create a Kerberos database and
175 stash file on the master KDC, using the :ref:`kdb5_util(8)` command.
176 Replace ``ATHENA.MIT.EDU`` with the name of your Kerberos realm::
178 shell% kdb5_util create -r ATHENA.MIT.EDU -s
180 Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
181 master key name 'K/M@ATHENA.MIT.EDU'
182 You will be prompted for the database Master Password.
183 It is important that you NOT FORGET this password.
184 Enter KDC database master key: <= Type the master password.
185 Re-enter KDC database master key to verify: <= Type it again.
188 This will create five files in |kdcdir| (or at the locations specified
189 in :ref:`kdc.conf(5)`):
191 * two Kerberos database files, ``principal``, and ``principal.ok``
192 * the Kerberos administrative database file, ``principal.kadm5``
193 * the administrative database lock file, ``principal.kadm5.lock``
194 * the stash file, in this example ``.k5.ATHENA.MIT.EDU``. If you do
195 not want a stash file, run the above command without the **-s**
198 For more information on administrating Kerberos database see
199 :ref:`db_operations`.
204 Add administrators to the ACL file
205 ----------------------------------
207 Next, you need create an Access Control List (ACL) file and put the
208 Kerberos principal of at least one of the administrators into it.
209 This file is used by the :ref:`kadmind(8)` daemon to control which
210 principals may view and make privileged modifications to the Kerberos
211 database files. The ACL filename is determined by the **acl_file**
212 variable in :ref:`kdc.conf(5)`; the default is |kdcdir|\
215 For more information on Kerberos ACL file see :ref:`kadm5.acl(5)`.
219 Add administrators to the Kerberos database
220 -------------------------------------------
222 Next you need to add administrative principals (i.e., principals who
223 are allowed to administer Kerberos database) to the Kerberos database.
224 You *must* add at least one principal now to allow communication
225 between the Kerberos administration daemon kadmind and the kadmin
226 program over the network for further administration. To do this, use
227 the kadmin.local utility on the master KDC. kadmin.local is designed
228 to be run on the master KDC host without using Kerberos authentication
229 to an admin server; instead, it must have read and write access to the
230 Kerberos database on the local filesystem.
232 The administrative principals you create should be the ones you added
233 to the ACL file (see :ref:`admin_acl`).
235 In the following example, the administrative principal ``admin/admin``
240 kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU
242 WARNING: no policy specified for "admin/admin@ATHENA.MIT.EDU";
244 Enter password for principal admin/admin@ATHENA.MIT.EDU: <= Enter a password.
245 Re-enter password for principal admin/admin@ATHENA.MIT.EDU: <= Type it again.
246 Principal "admin/admin@ATHENA.MIT.EDU" created.
249 .. _start_kdc_daemons:
251 Start the Kerberos daemons on the master KDC
252 --------------------------------------------
254 At this point, you are ready to start the Kerberos KDC
255 (:ref:`krb5kdc(8)`) and administrative daemons on the Master KDC. To
261 Each server daemon will fork and run in the background.
265 Assuming you want these daemons to start up automatically at
266 boot time, you can add them to the KDC's ``/etc/rc`` or
267 ``/etc/inittab`` file. You need to have a
268 :ref:`stash_definition` in order to do this.
270 You can verify that they started properly by checking for their
271 startup messages in the logging locations you defined in
272 :ref:`krb5.conf(5)` (see :ref:`logging`). For example::
274 shell% tail /var/log/krb5kdc.log
275 Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
276 shell% tail /var/log/kadmin.log
277 Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting
279 Any errors the daemons encounter while starting will also be listed in
282 As an additional verification, check if :ref:`kinit(1)` succeeds
283 against the principals that you have created on the previous step
284 (:ref:`addadmin_kdb`). Run::
286 shell% kinit admin/admin@ATHENA.MIT.EDU
289 Install the slave KDCs
290 ----------------------
292 You are now ready to start configuring the slave KDCs.
296 Assuming you are setting the KDCs up so that you can easily
297 switch the master KDC with one of the slaves, you should
298 perform each of these steps on the master KDC as well as the
299 slave KDCs, unless these instructions specify otherwise.
304 Create host keytabs for slave KDCs
305 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
307 Each KDC needs a ``host`` key in the Kerberos database. These keys
308 are used for mutual authentication when propagating the database dump
309 file from the master KDC to the secondary KDC servers.
311 On the master KDC, connect to administrative interface and create the
312 host principal for each of the KDCs' ``host`` services. For example,
313 if the master KDC were called ``kerberos.mit.edu``, and you had a
314 slave KDC named ``kerberos-1.mit.edu``, you would type the following::
317 kadmin: addprinc -randkey host/kerberos.mit.edu
318 NOTICE: no policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU"; assigning "default"
319 Principal "host/kerberos.mit.edu@ATHENA.MIT.EDU" created.
321 kadmin: addprinc -randkey host/kerberos-1.mit.edu
322 NOTICE: no policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU"; assigning "default"
323 Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created.
325 It is not strictly necessary to have the master KDC server in the
326 Kerberos database, but it can be handy if you want to be able to swap
327 the master KDC with one of the slaves.
329 Next, extract ``host`` random keys for all participating KDCs and
330 store them in each host's default keytab file. Ideally, you should
331 extract each keytab locally on its own KDC. If this is not feasible,
332 you should use an encrypted session to send them across the network.
333 To extract a keytab directly on a slave KDC called
334 ``kerberos-1.mit.edu``, you would execute the following command::
336 kadmin: ktadd host/kerberos-1.mit.edu
337 Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
338 type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
339 Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
340 type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
341 Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
342 type des3-cbc-sha1 added to keytab FILE:/etc/krb5.keytab.
343 Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
344 type arcfour-hmac added to keytab FILE:/etc/krb5.keytab.
346 If you are instead extracting a keytab for the slave KDC called
347 ``kerberos-1.mit.edu`` on the master KDC, you should use a dedicated
348 temporary keytab file for that machine's keytab::
350 kadmin: ktadd -k /tmp/kerberos-1.keytab host/kerberos-1.mit.edu
351 Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
352 type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
353 Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
354 type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
356 The file ``/tmp/kerberos-1.keytab`` can then be installed as
357 ``/etc/krb5.keytab`` on the host ``kerberos-1.mit.edu``.
363 Database propagation copies the contents of the master's database, but
364 does not propagate configuration files, stash files, or the kadm5 ACL
365 file. The following files must be copied by hand to each slave (see
366 :ref:`mitK5defaults` for the default locations for these files):
371 * master key stash file
373 Move the copied files into their appropriate directories, exactly as
374 on the master KDC. kadm5.acl is only needed to allow a slave to swap
377 The database is propagated from the master KDC to the slave KDCs via
378 the :ref:`kpropd(8)` daemon. You must explicitly specify the
379 principals which are allowed to provide Kerberos dump updates on the
380 slave machine with a new database. Create a file named kpropd.acl in
381 the KDC state directory containing the ``host`` principals for each of
384 host/kerberos.mit.edu@ATHENA.MIT.EDU
385 host/kerberos-1.mit.edu@ATHENA.MIT.EDU
389 If you expect that the master and slave KDCs will be
390 switched at some point of time, list the host principals
391 from all participating KDC servers in kpropd.acl files on
392 all of the KDCs. Otherwise, you only need to list the
393 master KDC's host principal in the kpropd.acl files of the
396 Then, add the following line to ``/etc/inetd.conf`` on each KDC
397 (adjust the path to kpropd)::
399 krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd
401 You also need to add the following line to ``/etc/services`` on each
402 KDC, if it is not already present (assuming that the default port is
405 krb5_prop 754/tcp # Kerberos slave propagation
407 Restart inetd daemon.
409 Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon. This is
410 required when incremental propagation is enabled.
412 Now that the slave KDC is able to accept database propagation, you’ll
413 need to propagate the database from the master server.
415 NOTE: Do not start the slave KDC yet; you still do not have a copy of
416 the master's database.
421 Propagate the database to each slave KDC
422 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
424 First, create a dump file of the database on the master KDC, as
427 shell% kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans
429 Then, manually propagate the database to each slave KDC, as in the
432 shell% kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-1.mit.edu
434 Database propagation to kerberos-1.mit.edu: SUCCEEDED
436 You will need a script to dump and propagate the database. The
437 following is an example of a Bourne shell script that will do this.
441 Remember that you need to replace ``/usr/local/var/krb5kdc``
442 with the name of the KDC state directory.
448 kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu"
450 kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans
454 kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc
457 You will need to set up a cron job to run this script at the intervals
458 you decided on earlier (see :ref:`db_prop`).
460 Now that the slave KDC has a copy of the Kerberos database, you can
461 start the krb5kdc daemon::
465 As with the master KDC, you will probably want to add this command to
466 the KDCs' ``/etc/rc`` or ``/etc/inittab`` files, so they will start
467 the krb5kdc daemon automatically at boot time.
473 You may encounter the following error messages. For a more detailed
474 discussion on possible causes and solutions click on the error link
475 to be redirected to :ref:`troubleshoot` section.
477 .. include:: ./troubleshoot.rst
478 :start-after: _prop_failed_start:
479 :end-before: _prop_failed_end:
482 Add Kerberos principals to the database
483 ---------------------------------------
485 Once your KDCs are set up and running, you are ready to use
486 :ref:`kadmin(1)` to load principals for your users, hosts, and other
487 services into the Kerberos database. This procedure is described
488 fully in :ref:`add_mod_del_princs`.
490 You may occasionally want to use one of your slave KDCs as the master.
491 This might happen if you are upgrading the master KDC, or if your
492 master KDC has a disk crash. See the following section for the
496 .. _switch_master_slave:
498 Switching master and slave KDCs
499 -------------------------------
501 You may occasionally want to use one of your slave KDCs as the master.
502 This might happen if you are upgrading the master KDC, or if your
503 master KDC has a disk crash.
505 Assuming you have configured all of your KDCs to be able to function
506 as either the master KDC or a slave KDC (as this document recommends),
507 all you need to do to make the changeover is:
509 If the master KDC is still running, do the following on the *old*
512 #. Kill the kadmind process.
513 #. Disable the cron job that propagates the database.
514 #. Run your database propagation script manually, to ensure that the
515 slaves all have the latest copy of the database (see
516 :ref:`kprop_to_slaves`).
518 On the *new* master KDC:
520 #. Start the :ref:`kadmind(8)` daemon (see :ref:`start_kdc_daemons`).
521 #. Set up the cron job to propagate the database (see
522 :ref:`kprop_to_slaves`).
523 #. Switch the CNAMEs of the old and new master KDCs. If you can't do
524 this, you'll need to change the :ref:`krb5.conf(5)` file on every
525 client machine in your Kerberos realm.
528 Incremental database propagation
529 --------------------------------
531 If you expect your Kerberos database to become large, you may wish to
532 set up incremental propagation to slave KDCs. See :ref:`incr_db_prop`