1
This is krb5-install.info, produced by makeinfo version 4.5 from
4
INFO-DIR-SECTION Kerberos
6
* krb5-install: (krb5-install). Kerberos V5 Installation Guide
10
File: krb5-install.info, Node: Start the Kerberos Daemons, Prev: Create a kadmind Keytab (optional), Up: Install the Master KDC
12
Start the Kerberos Daemons on the Master KDC
13
............................................
15
At this point, you are ready to start the Kerberos daemons on the Master
18
shell% /usr/local/sbin/krb5kdc
19
shell% /usr/local/sbin/kadmind
21
Each daemon will fork and run in the background. Assuming you want
22
these daemons to start up automatically at boot time, you can add them
23
to the KDC's `/etc/rc' or `/etc/inittab' file. You need to have a
24
stash file in order to do this.
26
You can verify that they started properly by checking for their startup
27
messages in the logging locations you defined in `/etc/krb5.conf'.
28
(*Note Edit the Configuration Files::.) For example:
30
shell% tail /var/log/krb5kdc.log
31
Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
32
shell% tail /var/log/kadmin.log
33
Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting
35
Any errors the daemons encounter while starting will also be listed in
39
File: krb5-install.info, Node: Install the Slave KDCs, Next: Back on the Master KDC, Prev: Install the Master KDC, Up: Installing KDCs
41
Install the Slave KDCs
42
----------------------
44
You are now ready to start configuring the slave KDCs. Assuming you are
45
setting the KDCs up so that you can easily switch the master KDC with
46
one of the slaves, you should perform each of these steps on the master
47
KDC as well as the slave KDCs, unless these instructions specify
52
* Create Host Keys for the Slave KDCs::
53
* Extract Host Keytabs for the KDCs::
54
* Set Up the Slave KDCs for Database Propagation::
57
File: krb5-install.info, Node: Create Host Keys for the Slave KDCs, Next: Extract Host Keytabs for the KDCs, Prev: Install the Slave KDCs, Up: Install the Slave KDCs
59
Create Host Keys for the Slave KDCs
60
...................................
62
Each KDC needs a host principal in the Kerberos database. You can enter
63
these from any host, once the `kadmind' daemon is running. For
64
example, if your master KDC were called kerberos.mit.edu, and you had
65
two KDC slaves named kerberos-1.mit.edu and kerberos-2.mit.edu, you
66
would type the following:
68
shell% /usr/local/sbin/kadmin
69
kadmin: addprinc -randkey host/kerberos.mit.edu
70
NOTICE: no policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU";
72
Principal "host/kerberos.mit.edu@ATHENA.MIT.EDU" created.
73
kadmin: addprinc -randkey host/kerberos-1.mit.edu
74
NOTICE: no policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU";
76
Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created.
77
kadmin: addprinc -randkey host/kerberos-2.mit.edu
78
NOTICE: no policy specified for "host/kerberos-2.mit.edu@ATHENA.MIT.EDU";
80
Principal "host/kerberos-2.mit.edu@ATHENA.MIT.EDU" created.
83
It is not actually necessary to have the master KDC server in the
84
Kerberos database, but it can be handy if:
86
* anyone will be logging into the machine as something other than
89
* you want to be able to swap the master KDC with one of the slaves
93
File: krb5-install.info, Node: Extract Host Keytabs for the KDCs, Next: Set Up the Slave KDCs for Database Propagation, Prev: Create Host Keys for the Slave KDCs, Up: Install the Slave KDCs
95
Extract Host Keytabs for the KDCs
96
.................................
98
Each KDC (including the master) needs a keytab to decrypt tickets.
99
Ideally, you should extract each keytab locally on its own KDC. If this
100
is not feasible, you should use an encrypted session to send them across
101
the network. To extract a keytab on a KDC called kerberos.mit.edu, you
102
would execute the following command:
104
kadmin: ktadd host/kerberos.mit.edu
105
kadmin: Entry for principal host/kerberos.mit.edu@ATHENA.MIT.EDU with
106
kvno 1, encryption type DES-CBC-CRC added to keytab
107
WRFILE:/etc/krb5.keytab.
110
Note that the principal must exist in the Kerberos database in order to
114
File: krb5-install.info, Node: Set Up the Slave KDCs for Database Propagation, Prev: Extract Host Keytabs for the KDCs, Up: Install the Slave KDCs
116
Set Up the Slave KDCs for Database Propagation
117
..............................................
119
The database is propagated from the master KDC to the slave KDCs via the
120
`kpropd' daemon. To set up propagation, create a file on each KDC,
121
named `/usr/local/var/krb5kdc/kpropd.acl', containing the principals
122
for each of the KDCs. For example, if the master KDC were
123
`kerberos.mit.edu', the slave KDCs were `kerberos-1.mit.edu' and
124
`kerberos-2.mit.edu', and the realm were `ATHENA.MIT.EDU', then the
125
file's contents would be:
127
host/kerberos.mit.edu@ATHENA.MIT.EDU
128
host/kerberos-1.mit.edu@ATHENA.MIT.EDU
129
host/kerberos-2.mit.edu@ATHENA.MIT.EDU
131
Then, add the following lines to `/etc/inetd.conf' file on each KDC
132
(the line beginnng with => is a continuation of the previous line):
134
krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd
135
eklogin stream tcp nowait root /usr/local/sbin/klogind
138
The first line sets up the `kpropd' database propagation daemon. The
139
second line sets up the `eklogin' daemon, allowing
140
Kerberos-authenticated, encrypted rlogin to the KDC.
142
You also need to add the following lines to `/etc/services' on each KDC:
144
kerberos 88/udp kdc # Kerberos authentication (udp)
145
kerberos 88/tcp kdc # Kerberos authentication (tcp)
146
krb5_prop 754/tcp # Kerberos slave propagation
147
kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp)
148
kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp)
149
eklogin 2105/tcp # Kerberos encrypted rlogin
152
File: krb5-install.info, Node: Back on the Master KDC, Next: Finish Installing the Slave KDCs, Prev: Install the Slave KDCs, Up: Installing KDCs
154
Back on the Master KDC
155
----------------------
157
Now that the slave KDCs are able to accept database propagation, you'll
158
need to propagate the database to each of them.
162
* Propagate the Database to Each Slave KDC::
165
File: krb5-install.info, Node: Propagate the Database to Each Slave KDC, Prev: Back on the Master KDC, Up: Back on the Master KDC
167
Propagate the Database to Each Slave KDC
168
........................................
170
First, create a dump of the database on the master KDC, as follows:
172
shell% /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans
175
Next, you need to manually propagate the database to each slave KDC, as
176
in the following example. (The lines beginning with => are
177
continuations of the previous line.):
179
/usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans
180
=> kerberos-1.mit.edu
181
/usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans
182
=> kerberos-2.mit.edu
184
You will need a script to dump and propagate the database. The
185
following is an example of a bourne shell script that will do this.
186
(Note that the line that begins with => is a continuation of the
187
previous line. Remember that you need to replace /usr/local with the
188
name of the directory in which you installed Kerberos V5.)
192
kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu"
194
/usr/local/sbin/kdb5_util "dump
195
=> /usr/local/var/krb5kdc/slave_datatrans"
199
/usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc
202
You will need to set up a cron job to run this script at the intervals
203
you decided on earlier (*Note Database Propagation::.)
206
File: krb5-install.info, Node: Finish Installing the Slave KDCs, Next: Add Kerberos Principals to the Database, Prev: Back on the Master KDC, Up: Installing KDCs
208
Finish Installing the Slave KDCs
209
--------------------------------
211
Now that the slave KDCs have copies of the Kerberos database, you can
212
create stash files for them and start the `krb5kdc' daemon.
216
* Create Stash Files on the Slave KDCs::
217
* Start the krb5kdc Daemon on Each KDC::
220
File: krb5-install.info, Node: Create Stash Files on the Slave KDCs, Next: Start the krb5kdc Daemon on Each KDC, Prev: Finish Installing the Slave KDCs, Up: Finish Installing the Slave KDCs
222
Create Stash Files on the Slave KDCs
223
....................................
225
Create stash files, by issuing the following commands on each slave KDC:
227
shell% kdb5_util stash
228
kdb5_util: Cannot find/read stored master key while reading master key
229
kdb5_util: Warning: proceeding without master key
230
Enter KDC database master key: <= Enter the database master key.
233
As mentioned above, the stash file is necessary for your KDCs to be able
234
authenticate to themselves, such as when they reboot. You could run
235
your KDCs without stash files, but you would then need to type in the
236
Kerberos database master key by hand every time you start a KDC daemon.
239
File: krb5-install.info, Node: Start the krb5kdc Daemon on Each KDC, Prev: Create Stash Files on the Slave KDCs, Up: Finish Installing the Slave KDCs
241
Start the krb5kdc Daemon on Each KDC
242
....................................
244
The final step in configuing your slave KDCs is to run the KDC daemon:
246
shell% /usr/local/sbin/krb5kdc
248
As with the master KDC, you will probably want to add this command to
249
the KDCs' `/etc/rc' or `/etc/inittab' files, so they will start the
250
krb5kdc daemon automatically at boot time.
253
File: krb5-install.info, Node: Add Kerberos Principals to the Database, Next: Limit Access to the KDCs, Prev: Finish Installing the Slave KDCs, Up: Installing KDCs
255
Add Kerberos Principals to the Database
256
---------------------------------------
258
Once your KDCs are set up and running, you are ready to use `kadmin' to
259
load principals for your users, hosts, and other services into the
260
Kerberos database. This procedure is described fully in the "Adding or
261
Modifying Principals" section of the Kerberos V5 System Administrator's
262
Guide. (*Note Create Host Keys for the Slave KDCs::, for a brief
263
description.) The keytab is generated by running `kadmin' and issuing
267
File: krb5-install.info, Node: Limit Access to the KDCs, Next: Switching Master and Slave KDCs, Prev: Add Kerberos Principals to the Database, Up: Installing KDCs
269
Limit Access to the KDCs
270
------------------------
272
To limit the possibility that your Kerberos database could be
273
compromised, MIT recommends that each KDC be a dedicated host, with
274
limited access. If your KDC is also a file server, FTP server, Web
275
server, or even just a client machine, someone who obtained root access
276
through a security hole in any of those areas could gain access to the
279
MIT recommends that your KDCs use the following `/etc/inetd.conf' file.
280
(Note: each line beginning with => is a continuation of the previous
284
# Configuration file for inetd(1M). See inetd.conf(4).
286
# To re-configure the running inetd process, edit this file, then
287
# send the inetd process a SIGHUP.
289
# Syntax for socket-based Internet services:
290
# <service_name> <socket_type> <proto> <flags> <user>
291
=> <server_pathname> <args>
293
# Syntax for TLI-based Internet services:
295
# <service_name> tli <proto> <flags> <user> <server_pathname> <args>
297
# Ftp and telnet are standard Internet services.
299
# This machine is a secure Kerberos Key Distribution Center (KDC).
300
# Services are limited.
303
# Time service is used for clock synchronization.
305
time stream tcp nowait root internal
306
time dgram udp wait root internal
308
# Limited Kerberos services
310
krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd
311
eklogin stream tcp nowait root /usr/local/sbin/klogind
315
File: krb5-install.info, Node: Switching Master and Slave KDCs, Next: Incremental Database Propagation, Prev: Limit Access to the KDCs, Up: Installing KDCs
317
Switching Master and Slave KDCs
318
-------------------------------
320
You may occasionally want to use one of your slave KDCs as the master.
321
This might happen if you are upgrading the master KDC, or if your master
322
KDC has a disk crash.
324
Assuming you have configured all of your KDCs to be able to function as
325
either the master KDC or a slave KDC (as this document recommends), all
326
you need to do to make the changeover is:
328
If the master KDC is still running, do the following on the _old_
331
1. Kill the `kadmind' process.
333
2. Disable the cron job that propagates the database.
335
3. Run your database propagation script manually, to ensure that the
336
slaves all have the latest copy of the database. (*Note Propagate
337
the Database to Each Slave KDC::.) If there is a need to preserve
338
per-principal policy information from the database, you should do
339
a "kdb5_util dump -ov" in order to preserve that information and
340
propogate that dump file securely by some means to the slave so
341
that its database has the correct state of the per-principal
344
On the _new_ master KDC:
346
1. Create a database keytab. (*Note Create a kadmind Keytab
349
2. Start the `kadmind' daemon. (*Note Start the Kerberos Daemons::.)
351
3. Set up the cron job to propagate the database. (*Note Propagate
352
the Database to Each Slave KDC::.)
354
4. Switch the CNAMEs of the old and new master KDCs. (If you don't do
355
this, you'll need to change the `krb5.conf' file on every client
356
machine in your Kerberos realm.)
360
File: krb5-install.info, Node: Incremental Database Propagation, Prev: Switching Master and Slave KDCs, Up: Installing KDCs
362
Incremental Database Propagation
363
--------------------------------
365
At some very large sites, dumping and transmitting the database can
366
take more time than is desirable for changes to propagate from the
367
master KDC to the slave KDCs. The incremental propagation support
368
added in the 1.7 release is intended to address this.
370
With incremental propagation enabled, all programs on the master KDC
371
that change the database also write information about the changes to an
372
"update log" file, maintained as a circular buffer of a certain size.
373
A process on each slave KDC connects to a service on the master KDC
374
(currently implmented in the `kadmind' server) and periodically
375
requests the changes that have been made since the last check. By
376
default, this check is done every two minutes. If the database has
377
just been modified in the previous several seconds (currently the
378
threshold is hard-coded at 10 seconds), the slave will not retrieve
379
updates, but instead will pause and try again soon after. This reduces
380
the likelihood that incremental update queries will cause delays for an
381
administrator trying to make a bunch of changes to the database at the
384
Incremental propagation uses the following entries in the per-realm
385
data in the KDC config file:
387
`iprop_enable' (boolean)
388
If this is set to `true', then incremental propagation is enabled,
389
and (as noted below) normal `kprop' propagation is disabled. The
392
`iprop_master_ulogsize' (integer)
393
This indicates the number of entries that should be retained in the
394
update log. The default is 1000; the maximum number is 2500.
396
`iprop_slave_poll' (time interval)
397
This indicates how often the slave should poll the master KDC for
398
changes to the database. The default is two minutes.
400
`iprop_port' (integer)
401
This specifies the port number to be used for incremental
402
propagation. This is required in both master and slave
405
`iprop_logfile' (file name)
406
This specifies where the update log file for the realm database is
407
to be stored. The default is to use the `database_name' entry from
408
the `realms' section of the config file, with `.ulog' appended.
409
(NOTE: If `database_name' isn't specified in the `realms' section,
410
perhaps because the LDAP database back end is being used, or the
411
file name is specified in the `dbmodules' section, then the
412
hard-coded default for `database_name' is used. Determination of
413
the `iprop_logfile' default value will not use values from the
414
`dbmodules' section.)
416
Both master and slave sides must have principals named
417
`kiprop/HOSTNAME' (where HOSTNAME is, as usual, the lower-case,
418
fully-qualified, canonical name for the host) registered and keys
419
stored in the default keytab file (`/etc/krb5.keytab').
421
On the master KDC side, the `kiprop/HOSTNAME' principal must be listed
422
in the `kadmind' ACL file `kadm5.acl', and given the `p' privilege.
424
On the slave KDC side, `kpropd' should be run. When incremental
425
propagation is enabled, it will connect to the `kadmind' on the master
426
KDC and start requesting updates.
428
The normal `kprop' mechanism is disabled by the incremental propagation
429
support. However, if the slave has been unable to fetch changes from
430
the master KDC for too long (network problems, perhaps), the log on the
431
master may wrap around and overwrite some of the updates that the slave
432
has not yet retrieved. In this case, the slave will instruct the
433
master KDC to dump the current database out to a file and invoke a
434
one-time `kprop' propagation, with special options to also convey the
435
point in the update log at which the slave should resume fetching
436
incremental updates. Thus, all the keytab and ACL setup previously
437
described for `kprop' propagation is still needed.
439
There are several known bugs and restrictions in the current
441
* The "call out to `kprop'" mechanism is a bit fragile; if the
442
`kprop' propagation fails to connect for some reason, the process
443
on the slave may hang waiting for it, and will need to be
446
* The master and slave must be able to initiate TCP connections in
447
both directions, without an intervening NAT. They must also be
448
able to communicate over IPv4, since MIT's kprop and RPC code does
449
not currently support IPv6.
453
* Sun/MIT Incremental Propagation Differences::
456
File: krb5-install.info, Node: Sun/MIT Incremental Propagation Differences, Prev: Incremental Database Propagation, Up: Incremental Database Propagation
458
Sun/MIT Incremental Propagation Differences
459
...........................................
461
Sun donated the original code for supporting incremental database
462
propagation to MIT. Some changes have been made in the MIT source tree
463
that will be visible to administrators. (These notes are based on
464
Sun's patches. Changes to Sun's implementation since then may not be
467
The Sun config file support looks for `sunw_dbprop_enable',
468
`sunw_dbprop_master_ulogsize', and `sunw_dbprop_slave_poll'.
470
The incremental propagation service is implemented as an ONC RPC
471
service. In the Sun implementation, the service is registered with
472
`rpcbind' (also known as `portmapper') and the client looks up the port
473
number to contact. In the MIT implementation, where interaction with
474
some modern versions of `rpcbind' doesn't always work well, the port
475
number must be specified in the config file on both the master and
478
The Sun implementation hard-codes pathnames in `/var/krb5' for the
479
update log and the per-slave `kprop' dump files. In the MIT
480
implementation, the pathname for the update log is specified in the
481
config file, and the per-slave dump files are stored in
482
`/usr/local/var/krb5kdc/slave_datatrans_HOSTNAME'.
485
File: krb5-install.info, Node: Installing and Configuring UNIX Client Machines, Next: UNIX Application Servers, Prev: Installing KDCs, Up: Installing Kerberos V5
487
Installing and Configuring UNIX Client Machines
488
===============================================
490
Client machine installation is much more straightforward than
491
installation of the KDCs.
496
* Client Machine Configuration Files::
499
File: krb5-install.info, Node: Client Programs, Next: Client Machine Configuration Files, Prev: Installing and Configuring UNIX Client Machines, Up: Installing and Configuring UNIX Client Machines
504
The Kerberized client programs are `login.krb5', `rlogin', `telnet',
505
`ftp', `rcp', `rsh', `kinit', `klist', `kdestroy', `kpasswd', `ksu', and
506
`krb524init'. All of these programs are in the directory
507
`/usr/local/bin', except for `login.krb5' which is in `/usr/local/sbin'.
509
You will probably want to have your users put `/usr/local/bin' ahead of
510
`/bin' and `/usr/bin' in their paths, so they will by default get the
511
Kerberos V5 versions of `rlogin', `telnet', `ftp', `rcp', and `rsh'.
513
MIT recommends that you use `login.krb5' in place of `/bin/login' to
514
give your users a single-sign-on system. You will need to make sure
515
your users know to use their Kerberos passwords when they log in.
517
You will also need to educate your users to use the ticket management
518
programs `kinit', `klist', `kdestroy', and to use the Kerberos programs
519
`ksu', and `kpasswd' in place of their non-Kerberos counterparts `su',
520
`passwd', and `rdist'.
523
File: krb5-install.info, Node: Client Machine Configuration Files, Prev: Client Programs, Up: Installing and Configuring UNIX Client Machines
525
Client Machine Configuration Files
526
----------------------------------
528
Each machine running Kerberos must have a `/etc/krb5.conf' file.
531
Also, for most UNIX systems, you must add the appropriate Kerberos
532
services to each client machine's `/etc/services' file. If you are
533
using the default configuration for Kerberos V5, you should be able to
534
just insert the following code:
536
kerberos 88/udp kdc # Kerberos V5 KDC
537
kerberos 88/tcp kdc # Kerberos V5 KDC
538
klogin 543/tcp # Kerberos authenticated rlogin
539
kshell 544/tcp cmd # and remote shell
540
kerberos-adm 749/tcp # Kerberos 5 admin/changepw
541
kerberos-adm 749/udp # Kerberos 5 admin/changepw
542
krb5_prop 754/tcp # Kerberos slave propagation
543
eklogin 2105/tcp # Kerberos auth. & encrypted rlogin
544
krb524 4444/tcp # Kerberos 5 to 4 ticket translator
548
* Mac OS X Configuration::
551
File: krb5-install.info, Node: Mac OS X Configuration, Prev: Client Machine Configuration Files, Up: Client Machine Configuration Files
553
Mac OS X Configuration
554
......................
556
To install Kerberos V5 on Mac OS X and Mac OS X Server, follow the
557
directions for generic Unix-based OS's, except for the `/etc/services'
558
updates described above.
560
Mac OS X and Mac OS X Server use a database called NetInfo to store the
561
contents of files normally found in `/etc'. Instead of modifying
562
`/etc/services', you should run the following commands to add the
563
Kerberos service entries to NetInfo:
565
$ niutil -create . /services/kerberos
566
$ niutil -createprop . /services/kerberos name kerberos kdc
567
$ niutil -createprop . /services/kerberos port 750
568
$ niutil -createprop . /services/kerberos protocol tcp udp
569
$ niutil -create . /services/krbupdate
570
$ niutil -createprop . /services/krbupdate name krbupdate kreg
571
$ niutil -createprop . /services/krbupdate port 760
572
$ niutil -createprop . /services/krbupdate protocol tcp
573
$ niutil -create . /services/kpasswd
574
$ niutil -createprop . /services/kpasswd name kpasswd kpwd
575
$ niutil -createprop . /services/kpasswd port 761
576
$ niutil -createprop . /services/kpasswd protocol tcp
577
$ niutil -create . /services/klogin
578
$ niutil -createprop . /services/klogin port 543
579
$ niutil -createprop . /services/klogin protocol tcp
580
$ niutil -create . /services/eklogin
581
$ niutil -createprop . /services/eklogin port 2105
582
$ niutil -createprop . /services/eklogin protocol tcp
583
$ niutil -create . /services/kshell
584
$ niutil -createprop . /services/kshell name kshell krcmd
585
$ niutil -createprop . /services/kshell port 544
586
$ niutil -createprop . /services/kshell protocol tcp
588
In addition to adding services to NetInfo, you must also modify the
589
resolver configuration in NetInfo so that the machine resolves its own
590
hostname as a FQDN (fully qualified domain name). By default, Mac OS X
591
and Mac OS X Server machines query NetInfo to resolve hostnames before
592
falling back to DNS. Because NetInfo has an unqualified name for all
593
the machines in the NetInfo database, the machine's own hostname will
594
resolve to an unqualified name. Kerberos needs a FQDN to look up keys
595
in the machine's keytab file.
597
Fortunately, you can change the `lookupd' caching order to query DNS
598
first. Run the following NetInfo commands and reboot the machine:
600
$ niutil -create . /locations/lookupd/hosts
601
$ niutil -createprop . /locations/lookupd/hosts LookupOrder CacheAgent DNSAgent
604
Once you have rebooted, you can verify that the resolver now behaves
605
correctly. Compile the Kerberos 5 distribution and run:
607
$ cd .../src/tests/resolve
610
This will tell you whether or not your machine returns FQDNs on name
611
lookups. If the test still fails, you can also try turning off DNS
612
caching. Run the following commands and reboot:
614
$ niutil -create . /locations/lookupd/hosts
615
$ niutil -createprop . /locations/lookupd/hosts LookupOrder DNSAgent
616
CacheAgent NIAgent NILAgent
618
The remainder of the setup of a Mac OS X client machine or application
619
server should be the same as for other UNIX-based systems.
622
File: krb5-install.info, Node: UNIX Application Servers, Prev: Installing and Configuring UNIX Client Machines, Up: Installing Kerberos V5
624
UNIX Application Servers
625
========================
627
An application server is a host that provides one or more services over
628
the network. Application servers can be "secure" or "insecure." A
629
"secure" host is set up to require authentication from every client
630
connecting to it. An "insecure" host will still provide Kerberos
631
authentication, but will also allow unauthenticated clients to connect.
633
If you have Kerberos V5 installed on all of your client machines,
634
MIT recommends that you make your hosts secure, to take advantage of
635
the security that Kerberos authentication affords. However, if you
636
have some clients that do not have Kerberos V5 installed, you can run
637
an insecure server, and still take advantage of Kerberos V5's single
643
* Server Configuration Files::
645
* Some Advice about Secure Hosts::
648
File: krb5-install.info, Node: Server Programs, Next: Server Configuration Files, Prev: UNIX Application Servers, Up: UNIX Application Servers
653
Just as Kerberos V5 provided its own Kerberos-enhanced versions of
654
client UNIX network programs, Kerberos V5 also provides
655
Kerberos-enhanced versions of server UNIX network daemons. These are
656
`ftpd', `klogind', `kshd', and `telnetd'. These programs are installed
657
in the directory `/usr/local/sbin'. You may want to add this directory
661
File: krb5-install.info, Node: Server Configuration Files, Next: The Keytab File, Prev: Server Programs, Up: UNIX Application Servers
663
Server Configuration Files
664
--------------------------
666
For a _secure_ server, make the following changes to `/etc/inetd.conf':
668
Find and comment out any lines for the services `ftp', `telnet',
669
`shell', `login', and `exec'.
671
Add the following lines. (Note: each line beginning with => is a
672
continuation of the previous line.)
674
klogin stream tcp nowait root /usr/local/sbin/klogind
676
eklogin stream tcp nowait root /usr/local/sbin/klogind
678
kshell stream tcp nowait root /usr/local/sbin/kshd
680
ftp stream tcp nowait root /usr/local/sbin/ftpd
682
telnet stream tcp nowait root /usr/local/sbin/telnetd
685
For an _insecure_ server, make the following changes instead to
688
Find and comment out any lines for the services `ftp' and `telnet'.
690
Add the following lines. (Note: each line beginning with => is a
691
continuation of the previous line.)
692
klogin stream tcp nowait root /usr/local/sbin/klogind
694
eklogin stream tcp nowait root /usr/local/sbin/klogind
696
kshell stream tcp nowait root /usr/local/sbin/kshd
698
ftp stream tcp nowait root /usr/local/sbin/ftpd
700
telnet stream tcp nowait root /usr/local/sbin/telnetd
704
File: krb5-install.info, Node: The Keytab File, Next: Some Advice about Secure Hosts, Prev: Server Configuration Files, Up: UNIX Application Servers
709
All Kerberos server machines need a "keytab" file, called
710
`/etc/krb5.keytab', to authenticate to the KDC. The keytab file is an
711
encrypted, local, on-disk copy of the host's key. The keytab file,
712
like the stash file (*Note Create the Database::) is a potential
713
point-of-entry for a break-in, and if compromised, would allow
714
unrestricted access to its host. The keytab file should be readable
715
only by root, and should exist only on the machine's local disk. The
716
file should not be part of any backup of the machine, unless access to
717
the backup data is secured as tightly as access to the machine's root
720
In order to generate a keytab for a host, the host must have a principal
721
in the Kerberos database. The procedure for adding hosts to the
722
database is described fully in the "Adding or Modifying Principals"
723
section of the `Kerberos V5 System Administrator's Guide'. *Note
724
Create Host Keys for the Slave KDCs::. for a brief description.) The
725
keytab is generated by running `kadmin' and issuing the `ktadd' command.
727
For example, to generate a keytab file to allow the host
728
trillium.mit.edu to authenticate for the services `host', `ftp', and
729
`pop', the administrator `joeadmin' would issue the command (on
732
trillium% /usr/local/sbin/kadmin
733
kadmin5: ktadd host/trillium.mit.edu ftp/trillium.mit.edu
734
=> pop/trillium.mit.edu
735
kadmin: Entry for principal host/trillium.mit.edu@ATHENA.MIT.EDU with
736
kvno 3, encryption type DES-CBC-CRC added to keytab
737
WRFILE:/etc/krb5.keytab.
738
kadmin: Entry for principal ftp/trillium.mit.edu@ATHENA.MIT.EDU with
739
kvno 3, encryption type DES-CBC-CRC added to keytab
740
WRFILE:/etc/krb5.keytab.
741
kadmin: Entry for principal pop/trillium.mit.edu@ATHENA.MIT.EDU with
742
kvno 3, encryption type DES-CBC-CRC added to keytab
743
WRFILE:/etc/krb5.keytab.
747
If you generate the keytab file on another host, you need to get a copy
748
of the keytab file onto the destination host (`trillium', in the above
749
example) without sending it unencrypted over the network. If you have
750
installed the Kerberos V5 client programs, you can use encrypted `rcp'.
753
File: krb5-install.info, Node: Some Advice about Secure Hosts, Prev: The Keytab File, Up: UNIX Application Servers
755
Some Advice about Secure Hosts
756
------------------------------
758
Kerberos V5 can protect your host from certain types of break-ins, but
759
it is possible to install Kerberos V5 and still leave your host
760
vulnerable to attack. Obviously an installation guide is not the place
761
to try to include an exhaustive list of countermeasures for every
762
possible attack, but it is worth noting some of the larger holes and how
765
As stated earlier in this section, MIT recommends that on a secure
766
host, you disable the standard `ftp', `login', `telnet', `shell', and
767
`exec' services in `/etc/inetd.conf'. We also recommend that secure
768
hosts have an empty `/etc/hosts.equiv' file and that there not be a
769
`.rhosts' file in `root''s home directory. You can grant
770
Kerberos-authenticated root access to specific Kerberos principals by
771
placing those principals in the file `.k5login' in root's home
774
We recommend that backups of secure machines exclude the keytab file
775
(`/etc/krb5.keytab'). If this is not possible, the backups should at
776
least be done locally, rather than over a network, and the backup tapes
777
should be physically secured.
779
Finally, the keytab file and any programs run by root, including the
780
Kerberos V5 binaries, should be kept on local disk. The keytab file
781
should be readable only by root.
784
File: krb5-install.info, Node: Upgrading Existing Kerberos V5 Installations, Next: Bug Reports for Kerberos V5, Prev: Installing Kerberos V5, Up: Top
786
Upgrading Existing Kerberos V5 Installations
787
********************************************
789
If you already have an existing Kerberos database that you created with
790
a prior release of Kerberos 5, you can upgrade it to work with the
791
current release with the `kdb5_util' command. It is only necessary to
792
perform this dump/undump procedure if you were running a krb5-1.0.x KDC
793
and are migrating to a krb5-1.1.x or newer KDC or if you were running a
794
krb5-1.1.x KDC and are migrating to a krb5-1.2.x or newer KDC. The
795
process for upgrading a Master KDC involves the following steps:
797
1. Stop your current KDC and administration server processes, if any.
799
2. Dump your existing Kerberos database to an ASCII file with
800
`kdb5_util''s "dump" command:
802
shell% cd /usr/local/var/krb5kdc
803
shell% kdb5_util dump old-kdb-dump
804
shell% kdb5_util dump -ov old-kdb-dump.ov
807
3. Create a new Master KDC installation (*Note Install the Master
808
KDC::.). If you have a stash file for your current database,
809
choose any new master password but then copy your existing stash
810
file to the location specified by your kdc.conf; if you do not
811
have a stash file for your current database, you must choose the
812
same master password.
814
4. Load your old Kerberos database into the new system with
815
`kdb5_util''s "load" command:
817
shell% cd /usr/local/var/krb5kdc
818
shell% kdb5_util load old-kdb-dump
819
shell% kdb5_util load -update old-kdb-dump.ov
823
The "dump -ov" and "load -update" commands are necessary in order to
824
preserve per-principal policy information, since the default dump format
825
filters out that information. If you omit those steps, the loaded
826
database database will lose the policy information for each principal
829
To update a Slave KDC, you must stop the old server processes on the
830
Slave KDC, install the new server binaries, reload the most recent slave
831
dump file, and re-start the server processes.
835
* Upgrading to Triple-DES and RC4 Encryption Keys::
838
File: krb5-install.info, Node: Upgrading to Triple-DES and RC4 Encryption Keys, Prev: Upgrading Existing Kerberos V5 Installations, Up: Upgrading Existing Kerberos V5 Installations
840
Upgrading to Triple-DES Encryption Keys
841
=======================================
843
Beginning with the 1.2 release from MIT, Kerberos includes a stronger
844
encryption algorithm called "triple DES" - essentially, three
845
applications of the basic DES encryption algorithm, greatly increasing
846
the resistance to a brute-force search for the key by an attacker.
847
This algorithm is more secure, but encryption is much slower.
849
Release 1.1 had some support for triple-DES service keys, but with
850
release 1.2 we have added support for user keys and session keys as
851
well. Release 1.0 had very little support for multiple cryptosystems,
852
and some of that software may not function properly in an environment
853
using triple-DES as well as plain DES.
855
In the 1.3 release from MIT, Kerberos also includes the RC4 encryption
856
alogorithm, a stream cipher symmetric key algorithm developed in 1987
857
by Ronald Rivest at RSA Data Security. Please note that RC4 is not
858
part of the IETF standard.
860
Because of the way the MIT Kerberos database is structured, the KDC
861
will assume that a service supports only those encryption types for
862
which keys are found in the database. Thus, if a service has only a
863
single-DES key in the database, the KDC will not issue tickets for that
864
service that use triple-DES or RC4 session keys; it will instead issue
865
only single-DES session keys, even if other services are already
866
capable of using triple-DES or RC4. So if you make sure your
867
application server software is updated before adding a triple-DES or
868
RC4 key for the service, clients should be able to talk to services at
869
all times during the updating process.
871
Normally, the listed `supported_enctypes' in `kdc.conf' are all used
872
when a new key is generated. You can control this with command-line
873
flags to `kadmin' and `kadmin.local'. You may want to exclude
874
triple-DES and RC4 by default until you have updated a lot of your
875
application servers, and then change the default to include triple-DES
876
and RC4. We recommend that you always include `des-cbc-crc' in the
880
File: krb5-install.info, Node: Bug Reports for Kerberos V5, Prev: Upgrading Existing Kerberos V5 Installations, Up: Top
882
Bug Reports for Kerberos V5
883
***************************
885
In any complex software, there will be bugs. If you have successfully
886
built and installed Kerberos V5, please use the `krb5-send-pr' program
887
to fill out a Problem Report should you encounter any errors in our
890
Bug reports that include proposed fixes are especially welcome. If you
891
do include fixes, please send them using either context diffs or unified
892
diffs (using `diff -c' or `diff -u', respectively). Please be careful
893
when using "cut and paste" or other such means to copy a patch into a
894
bug report; depending on the system being used, that can result in
895
converting TAB characters into spaces, which makes applying the patches
898
The `krb5-send-pr' program is installed in the directory
901
The `krb5-send-pr' program enters the problem report into our Problem
902
Report Management System (PRMS), which automatically assigns it to the
903
engineer best able to help you with problems in the assigned category.
905
The `krb5-send-pr' program will try to intelligently fill in as many
906
fields as it can. You need to choose the "category", "class",
907
"severity", and "priority" of the problem, as well as giving us as much
908
information as you can about its exact nature.
910
The PR category will be one of:
912
krb5-admin krb5-appl krb5-build krb5-clients
913
krb5-doc krb5-kdc krb5-libs krb5-misc
916
Choose the category that best describes the area under which your
919
The class can be "sw-bug", "doc-bug", "change-request", or "support".
920
The first two are exactly as their names imply. Use change-request
921
when the software is behaving according to specifications, but you want
922
to request changes in some feature or behavior. The support class is
923
intended for more general questions about building or using Kerberos V5.
925
The severity of the problem indicates the problem's impact on the
926
usability of Kerberos V5. If a problem is "critical", that means the
927
product, component or concept is completely non-operational, or some
928
essential functionality is missing, and no workaround is known. A
929
"serious" problem is one in which the product, component or concept is
930
not working properly or significant functionality is missing. Problems
931
that would otherwise be considered critical are rated serious when a
932
workaround is known. A "non-critical" problem is one that is indeed a
933
problem, but one that is having a minimal effect on your ability to use
934
Kerberos V5. E.g., The product, component or concept is working in
935
general, but lacks features, has irritating behavior, does something
936
wrong, or doesn't match its documentation. The default severity is
939
The priority indicates how urgent this particular problem is in
940
relation to your work. Note that low priority does not imply low
941
importance. A priority of "high" means a solution is needed as soon as
942
possible. A priority of "medium" means the problem should be solved no
943
later than the next release. A priority of "low" means the problem
944
should be solved in a future release, but it is not important to your
945
work how soon this happens. The default priority is medium.
947
Note that a given severity does not necessarily imply a given priority.
948
For example, a non-critical problem might still have a high priority if
949
you are faced with a hard deadline. Conversely, a serious problem might
950
have a low priority if the feature it is disabling is one that you do
953
It is important that you fill in the release field and tell us what
954
changes you have made, if any.
956
A sample filled-out form from a company named "Toasters, Inc." might
959
To: krb5-bugs@mit.edu
960
Subject: misspelled "Kerberos" in title of installation guide
964
X-send-pr-version: 3.99
968
>Originator: Jeffrey C. Gilman Bigler
972
>Synopsis: Misspelled "Kerberos" in title of installation guide
973
>Severity: non-critical
977
>Release: 1.0-development
979
<machine, os, target, libraries (multiple lines)>
980
System: ULTRIX imbrium 4.2 0 RISC
983
Misspelled "Kerberos" in title of "Kerboros V5 Installation Guide"
987
Correct the spelling.
989
If the `krb5-send-pr' program does not work for you, or if you did not
990
get far enough in the process to have an installed and working
991
`krb5-send-pr', you can generate your own form, using the above as an
added
removed
doc/krb5-install.info-3
