1 \input texinfo-suppl.tex % contains @doubleleftarrow{} definition
2 % this line must come *before* \input texinfo
3 \input texinfo @c -*-texinfo-*-
6 @setfilename krb5-install.info
7 @settitle Kerberos V5 Installation Guide
8 @setchapternewpage odd @c chapter begins on next odd page
9 @c @setchapternewpage on @c chapter begins on next page
10 @c @smallbook @c Format for 7" X 9.25" paper
18 @include definitions.texinfo
21 @finalout @c don't print black warning boxes
24 @title @value{PRODUCT} Installation Guide
25 @subtitle Release: @value{RELEASE}
26 @subtitle Document Edition: @value{EDITION}
27 @subtitle Last updated: @value{UPDATED}
28 @author @value{COMPANY}
31 @vskip 0pt plus 1filll
34 @include copyright.texinfo
38 @node Top, Copyright, (dir), (dir)
39 @comment node-name, next, previous, up
42 This file documents how to install the @value{RELEASE} release of
45 @c The master menu is updated using emacs19's M-x texinfo-all-menus-update
46 @c function. Don't forget to run M-x texinfo-every-node-update after
47 @c you add a new section or subsection, or after you've rearranged the
48 @c order of sections or subsections. Also, don't forget to add an @node
49 @c comand before each @section or @subsection! All you need to enter
52 @c @node New Section Name
54 @c @section New Section Name
56 @c M-x texinfo-every-node-update will take care of calculating the
57 @c node's forward and back pointers.
59 @c ---------------------------------------------------------------------
64 * Realm Configuration Decisions::
65 * Building Kerberos V5::
66 * Installing Kerberos V5::
67 * Upgrading Existing Kerberos V5 Installations::
68 * Bug Reports for Kerberos V5::
72 @node Copyright, Introduction, Top, Top
74 @include copyright.texinfo
78 @node Introduction, Realm Configuration Decisions, Copyright, Top
82 * What is Kerberos and How Does it Work?::
83 * Why Should I use Kerberos?::
84 * Please Read the Documentation::
85 * Overview of This Guide::
88 @node What is Kerberos and How Does it Work?, Why Should I use Kerberos?, Introduction, Introduction
89 @section What is Kerberos and How Does it Work?
91 @value{PRODUCT} is based on the Kerberos authentication system developed
92 at MIT. Under Kerberos, a client (generally either a user or a service)
93 sends a request for a ticket to the Key Distribution Center (KDC). The
94 KDC creates a @dfn{ticket-granting ticket} (TGT) for the client,
95 encrypts it using the client's password as the key, and sends the
96 encrypted TGT back to the client. The client then attempts to decrypt
97 the TGT, using its password. If the client successfully decrypts the
98 TGT (@i{i.e.}, if the client gave the correct password), it keeps the
99 decrypted TGT, which indicates proof of the client's identity.
101 The TGT, which expires at a specified time, permits the client to obtain
102 additional tickets, which give permission for specific services. The
103 requesting and granting of these additional tickets is user-transparent.
105 @node Why Should I use Kerberos?, Please Read the Documentation, What is Kerberos and How Does it Work?, Introduction
106 @section Why Should I use Kerberos?
108 Since Kerberos negotiates authenticated, and optionally encrypted,
109 communications between two points anywhere on the Internet, it provides
110 a layer of security that is not dependent on which side of a firewall
111 either client is on. Since studies have shown that half of the computer
112 security breaches in industry happen from @i{inside} firewalls,
113 @value{PRODUCT} from @value{COMPANY} will play a vital role in the
114 security of your network.
116 @include document-list.texinfo
118 @node Please Read the Documentation, Overview of This Guide, Why Should I use Kerberos?, Introduction
119 @section Please Read the Documentation
121 As with any software package that uses a centrallized database, the
122 installation procedure is somewhat involved, and requires forethought
123 and planning. @value{COMPANY} has attempted to make this
124 @value{PRODUCT} Installation Guide as concise as possible, rather than
125 making it an exhaustive description of the details of Kerberos.
127 Consequently, everything in this guide appears because @value{COMPANY}
128 believes that it is important. Please read and follow these
129 instructions carefully, and if there is anything you do not understand
130 or are not sure of, please don't hesitate to call us.
133 Consequently, everything in this guide appears because @value{COMPANY}
134 believes that it is important. Please read and follow these
135 instructions carefully.
138 @node Overview of This Guide, , Please Read the Documentation, Introduction
139 @section Overview of This Guide
141 The next chapter describes the decisions you need to make before
142 installing @value{PRODUCT}.
144 Chapter four describes installation procedures for each class of
149 Key Distribution Centers (KDCs).
163 UNIX application server machines
167 Note that a machine can be both a client machine and an application
170 Chapter five describes procedure for updating previous installations of
173 Chapter six describes our problem reporting system.
175 The appendices give sample configuration files.
177 @node Realm Configuration Decisions, Building Kerberos V5, Introduction, Top
178 @chapter Realm Configuration Decisions
180 Before installing @value{PRODUCT}, it is necessary to consider the
185 The name of your Kerberos realm (or the name of each realm, if you need
189 How you will map your hostnames onto Kerberos realms.
192 Which ports your KDC and and kadmin (database access) services will use.
195 How many slave KDCs you need and where they should be located.
198 The hostnames of your master and slave KDCs.
201 How frequently you will propagate the database from the master KDC to
205 Whether you need backward compatibility with Kerberos V4.
210 * Mapping Hostnames onto Kerberos Realms::
211 * Ports for the KDC and Admin Services::
213 * Hostnames for the Master and Slave KDCs::
214 * Database Propagation::
217 @node Kerberos Realms, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions, Realm Configuration Decisions
218 @section Kerberos Realms
220 Although your Kerberos realm can be any ASCII string, convention is to
221 make it the same as your domain name, in upper-case letters. For
222 example, hosts in the domain @value{SECONDDOMAIN} would be in the
223 Kerberos realm @value{SECONDREALM}.
225 If you need multiple Kerberos realms, @value{COMPANY} recommends that
226 you use descriptive names which end with your domain name, such as
227 BOSTON.@value{SECONDREALM} and HOUSTON.@value{SECONDREALM}.
229 @node Mapping Hostnames onto Kerberos Realms, Ports for the KDC and Admin Services, Kerberos Realms, Realm Configuration Decisions
230 @section Mapping Hostnames onto Kerberos Realms
232 @include dnstxt.texinfo
234 @node Ports for the KDC and Admin Services, Slave KDCs, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions
235 @section Ports for the KDC and Admin Services
237 The default ports used by Kerberos are port 88 for the
238 KDC@footnote{Kerberos V4 used port 750. If necessary, you can run on
239 both ports for backward compatibility.} and port 749 for the admin
240 server. You can, however, choose to run on other ports, as long as they
241 are specified in each host's @code{/etc/services} and @code{krb5.conf}
242 files, and the @code{kdc.conf} file on each KDC. For a more thorough
243 treatment of port numbers used by the @value{PRODUCT} programs, refer to
244 the ``Configuring Your Firewall to Work With @value{PRODUCT}'' section
245 of the @cite{@value{PRODUCT} System Administrator's Guide}.
247 @node Slave KDCs, Hostnames for the Master and Slave KDCs, Ports for the KDC and Admin Services, Realm Configuration Decisions
250 Slave KDCs provide an additional source of Kerberos ticket-granting
251 services in the event of inaccessibility of the master KDC. The number
252 of slave KDCs you need and the decision of where to place them, both
253 physically and logically, depends on the specifics of your network.
255 All of the Kerberos authentication on your network requires that each
256 client be able to contact a KDC. Therefore, you need to anticipate any
257 likely reason a KDC might be unavailable and have a slave KDC to take up
260 Some considerations include:
264 Have at least one slave KDC as a backup, for when the master KDC is
265 down, is being upgraded, or is otherwise unavailable.
268 If your network is split such that a network outage is likely to cause a
269 network partition (some segment or segments of the network to become cut
270 off or isolated from other segments), have a slave KDC accessible to
274 If possible, have at least one slave KDC in a different building from
275 the master, in case of power outages, fires, or other localized
281 @node Hostnames for the Master and Slave KDCs, Database Propagation, Slave KDCs, Realm Configuration Decisions
282 @section Hostnames for the Master and Slave KDCs
284 @include dnssrv.texinfo
286 @node Database Propagation, , Hostnames for the Master and Slave KDCs, Realm Configuration Decisions
287 @section Database Propagation
289 The Kerberos database resides on the master KDC, and must be propagated
290 regularly (usually by a cron job) to the slave KDCs. In deciding how
291 frequently the propagation should happen, you will need to balance the
292 amount of time the propagation takes against the maximum reasonable
293 amount of time a user should have to wait for a password change to take
296 If the propagation time is longer than this maximum reasonable time
297 (@i{e.g.,} you have a particularly large database, you have a lot of
298 slaves, or you experience frequent network delays), you may wish to
299 cut down on your propagation delay by performing the propagation in
300 parallel. To do this, have the master KDC propagate the database to one
301 set of slaves, and then have each of these slaves propagate the database
302 to additional slaves.
304 @node Building Kerberos V5, Installing Kerberos V5, Realm Configuration Decisions, Top
305 @chapter Building @value{PRODUCT}
307 @include build.texinfo
309 @node Installing Kerberos V5, Upgrading Existing Kerberos V5 Installations, Building Kerberos V5, Top
310 @chapter Installing @value{PRODUCT}
312 The sections of this chapter describe procedures for installing
323 UNIX Application Servers
328 * Installing and Configuring UNIX Client Machines::
329 * UNIX Application Servers::
332 @node Installing KDCs, Installing and Configuring UNIX Client Machines, Installing Kerberos V5, Installing Kerberos V5
333 @section Installing KDCs
335 The Key Distribution Centers (KDCs) issue Kerberos tickets. Each KDC
336 contains a copy of the Kerberos database. The master KDC contains the
337 master copy of the database, which it propagates to the slave KDCs at
338 regular intervals. All database changes (such as password changes) are
339 made on the master KDC.
341 Slave KDCs provide Kerberos ticket-granting services, but not database
342 administration. This allows clients to continue to obtain tickets when
343 the master KDC is unavailable.
345 @value{COMPANY} recommends that you install all of your KDCs to be able
346 to function as either the master or one of the slaves. This will enable
347 you to easily switch your master KDC with one of the slaves if
348 necessary. (@xref{Switching Master and Slave KDCs}.) This installation
349 procedure is based on that recommendation.
352 * Install the Master KDC::
353 * Install the Slave KDCs::
354 * Back on the Master KDC::
355 * Finish Installing the Slave KDCs::
356 * Add Kerberos Principals to the Database::
357 * Limit Access to the KDCs::
358 * Switching Master and Slave KDCs::
361 @node Install the Master KDC, Install the Slave KDCs, Installing KDCs, Installing KDCs
362 @subsection Install the Master KDC
364 This installation procedure will require you to go back and forth a
365 couple of times between the master KDC and each of the slave KDCs. The
366 first few steps must be done on the master KDC.
369 * Edit the Configuration Files::
370 * Create the Database::
371 * Add Administrators to the Acl File::
372 * Add Administrators to the Kerberos Database::
373 * Create a kadmind Keytab::
374 * Start the Kerberos Daemons::
377 @node Edit the Configuration Files, Create the Database, Install the Master KDC, Install the Master KDC
378 @subsubsection Edit the Configuration Files
380 Modify the configuration files, @code{/etc/krb5.conf}
381 (@pxref{krb5.conf}) and @code{@value{ROOTDIR}/var/krb5kdc/kdc.conf}
382 (@pxref{kdc.conf}) to reflect the correct information (such as the
383 hostnames and realm name) for your realm. @value{COMPANY} recommends
384 that you keep @code{krb5.conf} in @code{/etc}.
386 Among the settings in your @code{/etc/krb5.conf} file, be sure to create
387 a @code{[logging]} stanza so that the KDC and kadmind will generate
388 logging output. For example:
393 kdc = FILE:/var/log/krb5kdc.log
394 admin_server = FILE:/var/log/kadmin.log
395 default = FILE:/var/log/krb5lib.log
399 @node Create the Database, Add Administrators to the Acl File, Edit the Configuration Files, Install the Master KDC
400 @subsubsection Create the Database
402 You will use the @code{kdb5_util} command @emph{on the Master KDC} to
403 create the Kerberos database and the optional stash file. The
404 @dfn{stash file} is a local copy of the master key that resides in
405 encrypted form on the KDC's local disk. The stash file is used to
406 authenticate the KDC to itself automatically before starting the
407 @code{kadmind} and @code{krb5kdc} daemons (@i{e.g.,} as part of the
408 machine's boot sequence). The stash file, like the keytab file
409 (see @xref{The Keytab File}, for more information) is a potential
410 point-of-entry for a break-in,
411 and if compromised, would allow unrestricted access to the Kerberos
412 database. If you choose to install a stash file, it should be readable
413 only by root, and should exist only on the KDC's local disk. The file
414 should not be part of any backup of the machine, unless access to the
415 backup data is secured as tightly as access to the master password
418 Note that @code{kdb5_util} will prompt you for the master key for the
419 Kerberos database. This key can be any string. A good key is one you
420 can remember, but that no one else can guess. Examples of bad keys are
421 words that can be found in a dictionary, any common or popular name,
422 especially a famous person (or cartoon character), your username in any
423 form (@i{e.g.}, forward, backward, repeated twice, @i{etc.}), and any of
424 the sample keys that appear in this manual. One example of a key which
425 might be good if it did not appear in this manual is ``MITiys4K5!'',
426 which represents the sentence ``MIT is your source for Kerberos 5!''
427 (It's the first letter of each word, substituting the numeral ``4'' for
428 the word ``for'', and includes the punctuation mark at the end.)
430 The following is an example of how to create a Kerberos database and
431 stash file on the master KDC, using the @code{kdb5_util} command. (The
432 line that begins with @result{} is a continuation of the previous line.)
433 Replace @i{@value{PRIMARYREALM}} with the name of your Kerberos realm.
437 @b{shell%} @value{ROOTDIR}/sbin/kdb5_util create -r @value{PRIMARYREALM} -s
438 @b{Initializing database '@value{ROOTDIR}/var/krb5kdc/principal' for
439 @result{} realm '@value{PRIMARYREALM}',
440 master key name 'K/M@@@value{PRIMARYREALM}'
441 You will be prompted for the database Master Password.
442 It is important that you NOT FORGET this password.}
444 @b{Enter KDC database master key:} @i{@doubleleftarrow{} Type the master password.}
445 @b{Re-enter KDC database master key to verify:} @i{@doubleleftarrow{} Type it again.}
448 @b{Enter KDC database master key:} @i{<= Type the master password.}
449 @b{Re-enter KDC database master key to verify:} @i{<= Type it again.}
455 This will create five files in the directory specified in your
456 @code{kdc.conf} file: two Kerberos database files, @code{principal.db},
457 and @code{principal.ok}; the Kerberos administrative database file,
458 @code{principal.kadm5}; the administrative database lock file,
459 @code{principal.kadm5.lock}; and the stash file, @code{.k5stash}. (The
460 default directory is @code{@value{ROOTDIR}/var/krb5kdc}.) If you do not
461 want a stash file, run the above command without the @code{-s} option.
463 @node Add Administrators to the Acl File, Add Administrators to the Kerberos Database, Create the Database, Install the Master KDC
464 @subsubsection Add Administrators to the Acl File
466 Next, you need create an Access Control List (acl) file, and put the
467 Kerberos principal of at least one of the administrators into it. The
468 filename should match the value you have set for ``acl_file'' in your
469 @code{kdc.conf} file. The default file name is @samp{kadm5.acl}. The
470 format of the file is:
473 Kerberos principal permissions optional target principal
476 The Kerberos principal (and optional target principal) can include the
477 ``@b{*}'' wildcard, so if you want any principal with the instance
478 ``admin'' to have full permissions on the database, you could use the
479 principal ``@code{*/admin@@REALM}'' where ``REALM'' is your Kerberos
482 Note: a common use of an @i{admin} instance is so you can grant
483 separate permissions (such as administrator access to the Kerberos
484 database) to a separate Kerberos principal. For example, the user
485 @code{@value{ADMINUSER}} might have a principal for his administrative
486 use, called @code{@value{ADMINUSER}/admin}. This way,
487 @code{@value{ADMINUSER}} would obtain @code{@value{ADMINUSER}/admin}
488 tickets only when he actually needs to use those permissions. Refer to
489 the @value{PRODUCT} Administrator's Guide or the @value{PRODUCT} User's
490 Guide for more detailed explanations of @dfn{principals} and
493 The permissions (acls) recognized in the acl file
498 allows the addition of principals or policies in the database.
500 prohibits the addition of principals or policies in the database.
502 allows the deletion of principals or policies in the database.
504 prohibits the deletion of principals or policies in the database.
506 allows the modification of principals or policies in the database.
508 prohibits the modification of principals or policies in the database.
510 allows the changing of passwords for principals in the database.
512 prohibits the changing of passwords for principals in the database.
514 allows inquiries to the database.
516 prohibits inquiries to the database.
518 allows the listing of principals or policies in the database.
520 prohibits the listing of principals or policies in the database.
522 Short for all privileges (admcil).
524 Short for all privileges (admcil); identical to ``*''.
527 To give the principal @code{*/admin@@@value{PRIMARYREALM}} permission to
528 change all of the database permissions on any principal permissions, you
529 would place the following line in the file:
532 */admin@@@value{PRIMARYREALM} *
535 To give the principal @code{@value{ADMINUSER}@@@value{PRIMARYREALM}}
536 permission to add, list, and inquire about any principal that has the
537 instance ``root'', you would add the following line to the acl file:
540 @value{ADMINUSER}@@@value{PRIMARYREALM} ali */root@@@value{PRIMARYREALM}
543 @node Add Administrators to the Kerberos Database, Create a kadmind Keytab, Add Administrators to the Acl File, Install the Master KDC
544 @subsubsection Add Administrators to the Kerberos Database
546 Next you need to add administrative principals to the Kerberos database.
547 (You must add at least one now.) To do this, use @code{kadmin.local}
548 @emph{on the master KDC}. The administrative principals you create
549 should be the ones you added to the ACL file. (See @xref{Add
550 Administrators to the Acl File}.) In the following example, the
551 administration principal @code{admin/admin} is created:
555 @b{shell%} @value{ROOTDIR}/sbin/kadmin.local
556 @b{kadmin.local:} addprinc admin/admin@@@value{PRIMARYREALM}
557 @b{WARNING: no policy specified for "admin/admin@@@value{PRIMARYREALM}";
558 defaulting to no policy.}
560 @b{Enter password for principal admin/admin@@@value{PRIMARYREALM}:} @i{@doubleleftarrow{} Enter a password.}
561 Re-enter password for principal admin/admin@@@value{PRIMARYREALM}: @i{@doubleleftarrow{} Type it again.}
564 @b{Enter password for principal admin/admin@@@value{PRIMARYREALM}:} @i{<= Enter a password.}
565 Re-enter password for principal admin/admin@@@value{PRIMARYREALM}: @i{<= Type it again.}
567 @b{Principal "admin/admin@@@value{PRIMARYREALM}" created.
574 @node Create a kadmind Keytab, Start the Kerberos Daemons, Add Administrators to the Kerberos Database, Install the Master KDC
575 @subsubsection Create a kadmind Keytab
577 The kadmind keytab is the key that kadmind will use to decrypt
578 administrators' Kerberos tickets to determine whether or not it should
579 give them access to the database. You need to create the kadmin keytab
580 with entries for the principals @code{kadmin/admin} and
581 @code{kadmin/changepw}. (These principals are placed in the Kerberos
582 database automatically when you create it.) To create the kadmin
583 keytab, run @code{kadmin.local} and use the @code{ktadd} command, as in
584 the following example. (The line beginning with @result{} is a
585 continuation of the previous line.):
589 @b{shell%} @value{ROOTDIR}/sbin/kadmin.local
590 @b{kadmin.local:} ktadd -k @value{ROOTDIR}/var/krb5kdc/kadm5.keytab
591 @result{} kadmin/admin kadmin/changepw
592 @b{Entry for principal kadmin/admin@@@value{PRIMARYREALM} with
593 kvno 3, encryption type DES-CBC-CRC added to keytab
594 WRFILE:@value{ROOTDIR}/var/krb5kdc/kadm5.keytab.
595 Entry for principal kadmin/changepw@@@value{PRIMARYREALM} with
596 kvno 3, encryption type DES-CBC-CRC added to keytab
597 WRFILE:@value{ROOTDIR}/var/krb5kdc/kadm5.keytab.
604 As specified in the @samp{-k} argument, @code{ktadd} will save the
605 extracted keytab as @* @code{@value{ROOTDIR}/var/krb5kdc/kadm5.keytab}.
606 The filename you use must be the one specified in your @code{kdc.conf}
610 @node Start the Kerberos Daemons, , Create a kadmind Keytab, Install the Master KDC
611 @subsubsection Start the Kerberos Daemons on the Master KDC
613 At this point, you are ready to start the Kerberos daemons on the Master
617 @b{shell%} @value{ROOTDIR}/sbin/krb5kdc
618 @b{shell%} @value{ROOTDIR}/sbin/kadmind
622 Each daemon will fork and run in the background. Assuming you want
623 these daemons to start up automatically at boot time, you can add them
624 to the KDC's @code{/etc/rc} or @code{/etc/inittab} file. You need to
625 have a stash file in order to do this.
627 You can verify that they started properly by checking for their startup
628 messages in the logging locations you defined in @code{/etc/krb5.conf}.
629 (@xref{Edit the Configuration Files}.) For example:
632 @b{shell%} tail /var/log/krb5kdc.log
633 Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
634 @b{shell%} tail /var/log/kadmin.log
635 Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting
638 Any errors the daemons encounter while starting will also be listed in
642 @node Install the Slave KDCs, Back on the Master KDC, Install the Master KDC, Installing KDCs
643 @subsection Install the Slave KDCs
645 You are now ready to start configuring the slave KDCs. Assuming you are
646 setting the KDCs up so that you can easily switch the master KDC with
647 one of the slaves, you should perform each of these steps on the master
648 KDC as well as the slave KDCs, unless these instructions specify
653 * Create Host Keys for the Slave KDCs::
654 * Extract Host Keytabs for the KDCs::
655 * Set Up the Slave KDCs for Database Propagation::
658 @node Create Host Keys for the Slave KDCs, Extract Host Keytabs for the KDCs, Install the Slave KDCs, Install the Slave KDCs
659 @subsubsection Create Host Keys for the Slave KDCs
661 Each KDC needs a host principal in the Kerberos database. You can enter
662 these from any host, once the @code{kadmind} daemon is running. For
663 example, if your master KDC were called
664 @value{KDCSERVER}.@value{PRIMARYDOMAIN}, and you had two KDC slaves
665 named @value{KDCSLAVE1}.@value{PRIMARYDOMAIN} and
666 @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}, you would type the following:
670 @b{shell%} @value{ROOTDIR}/sbin/kadmin
671 @b{kadmin:} addprinc -randkey host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}
672 @b{WARNING: no policy specified for "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
673 defaulting to no policy.
674 Principal "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.
675 kadmin:} addprinc -randkey host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}
676 @b{WARNING: no policy specified for "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
677 defaulting to no policy.
678 Principal "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.}
679 @b{kadmin:} addprinc -randkey host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}
680 @b{WARNING: no policy specified for "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
681 defaulting to no policy.
682 Principal "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.
688 It is not actually necessary to have the master KDC server in the
689 Kerberos database, but it can be handy if:
693 anyone will be logging into the machine as something other than root
696 you want to be able to swap the master KDC with one of the slaves if
700 @node Extract Host Keytabs for the KDCs, Set Up the Slave KDCs for Database Propagation, Create Host Keys for the Slave KDCs, Install the Slave KDCs
701 @subsubsection Extract Host Keytabs for the KDCs
703 Each KDC (including the master) needs a keytab to decrypt tickets.
704 Ideally, you should extract each keytab locally on its own KDC. If this
705 is not feasible, you should use an encrypted session to send them across
706 the network. To extract a keytab on a KDC called
707 @value{KDCSERVER}.@value{PRIMARYDOMAIN}, you would execute the following
712 @b{kadmin:} ktadd host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}
713 @b{kadmin: Entry for principal host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
714 kvno 1, encryption type DES-CBC-CRC added to keytab
715 WRFILE:/etc/krb5.keytab.
721 Note that the principal must exist in the Kerberos database in order to
724 @node Set Up the Slave KDCs for Database Propagation, , Extract Host Keytabs for the KDCs, Install the Slave KDCs
725 @subsubsection Set Up the Slave KDCs for Database Propagation
727 The database is propagated from the master KDC to the slave KDCs via the
728 @code{kpropd} daemon. To set up propagation, create a file on each KDC,
729 named @code{@value{ROOTDIR}/var/krb5kdc/kpropd.acl}, containing the
730 principals for each of the KDCs.
732 For example, if the master KDC were
733 @code{@value{KDCSERVER}.@value{PRIMARYDOMAIN}}, the slave KDCs were
734 @code{@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}} and
735 @code{@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}}, and the realm were
736 @code{@value{PRIMARYREALM}}, then the file's contents would be:
740 host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
741 host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
742 host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
747 Then, add the following lines to @code{/etc/inetd.conf} file on each KDC
748 (the line beginnng with @result{} is a continuation of the previous
753 krb5_prop stream tcp nowait root @value{ROOTDIR}/sbin/kpropd kpropd
754 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
755 @result{} klogind -k -c -e
760 The first line sets up the @code{kpropd} database propagation daemon.
761 The second line sets up the @code{eklogin} daemon, allowing
762 Kerberos-authenticated, encrypted rlogin to the KDC.
764 You also need to add the following lines to @code{/etc/services} on each
769 kerberos 88/udp kdc # Kerberos authentication (udp)
770 kerberos 88/tcp kdc # Kerberos authentication (tcp)
771 krb5_prop 754/tcp # Kerberos slave propagation
772 kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp)
773 kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp)
774 eklogin 2105/tcp # Kerberos encrypted rlogin
778 @node Back on the Master KDC, Finish Installing the Slave KDCs, Install the Slave KDCs, Installing KDCs
779 @subsection Back on the Master KDC
781 Now that the slave KDCs are able to accept database propagation, you'll
782 need to propagate the database to each of them.
785 * Propagate the Database to Each Slave KDC::
788 @node Propagate the Database to Each Slave KDC, , Back on the Master KDC, Back on the Master KDC
789 @subsubsection Propagate the Database to Each Slave KDC
791 First, create a dump of the database on the master KDC, as follows:
795 @b{shell%} @value{ROOTDIR}/sbin/kdb5_util dump @value{ROOTDIR}/var/krb5kdc/slave_datatrans
800 Next, you need to manually propagate the database to each slave KDC, as
801 in the following example. (The lines beginning with @result{} are
802 continuations of the previous line.):
806 @value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans
807 @result{} @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}
808 @value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans
809 @result{} @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}
813 You will need a script to dump and propagate the database. The
814 following is an example of a bourne shell script that will do this.
815 (Note that the line that begins with @result{} is a continuation of the
816 previous line. Remember that you need to replace @value{ROOTDIR} with
817 the name of the directory in which you installed @value{PRODUCT}.)
823 kdclist = "@value{KDCSLAVE1}.@value{PRIMARYDOMAIN} @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}"
825 @value{ROOTDIR}/sbin/kdb5_util -R "dump
826 @result{} @value{ROOTDIR}/var/krb5kdc/slave_datatrans"
830 @value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans $kdc
836 You will need to set up a cron job to run this script at the intervals
837 you decided on earlier (@xref{Database Propagation}.)
839 @node Finish Installing the Slave KDCs, Add Kerberos Principals to the Database, Back on the Master KDC, Installing KDCs
840 @subsection Finish Installing the Slave KDCs
842 Now that the slave KDCs have copies of the Kerberos database, you can
843 create stash files for them and start the @code{krb5kdc} daemon.
846 * Create Stash Files on the Slave KDCs::
847 * Start the krb5kdc Daemon on Each KDC::
850 @node Create Stash Files on the Slave KDCs, Start the krb5kdc Daemon on Each KDC, Finish Installing the Slave KDCs, Finish Installing the Slave KDCs
851 @subsubsection Create Stash Files on the Slave KDCs
853 Create stash files, by issuing the following commands on each slave KDC:
857 @b{shell%} kdb5_util stash
858 @b{kdb5_util: Cannot find/read stored master key while reading master key
859 kdb5_util: Warning: proceeding without master key}
861 @b{Enter KDC database master key:} @i{@doubleleftarrow{} Enter the database master key.}
864 @b{Enter KDC database master key:} @i{<= Enter the database master key.}
870 As mentioned above, the stash file is necessary for your KDCs to be able
871 authenticate to themselves, such as when they reboot. You could run
872 your KDCs without stash files, but you would then need to type in the
873 Kerberos database master key by hand every time you start a KDC daemon.
875 @node Start the krb5kdc Daemon on Each KDC, , Create Stash Files on the Slave KDCs, Finish Installing the Slave KDCs
876 @subsubsection Start the krb5kdc Daemon on Each KDC
878 The final step in configuing your slave KDCs is to run the KDC daemon:
882 @b{shell%} @value{ROOTDIR}/sbin/krb5kdc
886 As with the master KDC, you will probably want to add this command to
887 the KDCs' @code{/etc/rc} or @code{/etc/inittab} files, so they will
888 start the krb5kdc daemon automatically at boot time.
890 @node Add Kerberos Principals to the Database, Limit Access to the KDCs, Finish Installing the Slave KDCs, Installing KDCs
891 @subsection Add Kerberos Principals to the Database
894 Once your KDCs are set up and running, you are ready to use
895 @code{kadmin} to load principals for your users, hosts, and other
896 services into the Kerberos database. This procedure is described fully in the
897 ``Adding or Modifying Principals'' section of the @value{PRODUCT} System
898 Administrator's Guide. (@xref{Create Host Keys for the Slave KDCs}, for a
899 brief description.) The keytab is generated by running @code{kadmin}
900 and issuing the @code{ktadd} command.
902 @node Limit Access to the KDCs, Switching Master and Slave KDCs, Add Kerberos Principals to the Database, Installing KDCs
903 @subsection Limit Access to the KDCs
905 To limit the possibility that your Kerberos database could be
906 compromised, @value{COMPANY} recommends that each KDC be a dedicated
907 host, with limited access. If your KDC is also a file server, FTP
908 server, Web server, or even just a client machine, someone who obtained
909 root access through a security hole in any of those areas could gain
910 access to the Kerberos database.
913 @value{COMPANY} recommends that your KDCs use the following
914 @code{/etc/inetd.conf} file. (Note: each line beginning with @result{}
915 is a continuation of the previous line.):
920 # Configuration file for inetd(1M). See inetd.conf(4).
922 # To re-configure the running inetd process, edit this file, then
923 # send the inetd process a SIGHUP.
925 # Syntax for socket-based Internet services:
926 # <service_name> <socket_type> <proto> <flags> <user>
927 @result{} <server_pathname> <args>
929 # Syntax for TLI-based Internet services:
931 # <service_name> tli <proto> <flags> <user> <server_pathname> <args>
933 # Ftp and telnet are standard Internet services.
935 # This machine is a secure Kerberos Key Distribution Center (KDC).
936 # Services are limited.
939 # Time service is used for clock synchronization.
941 time stream tcp nowait root internal
942 time dgram udp wait root internal
944 # Limited Kerberos services
946 krb5_prop stream tcp nowait root @value{ROOTDIR}/sbin/kpropd kpropd
947 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
948 @result{} klogind -5 -c -e
952 @node Switching Master and Slave KDCs, , Limit Access to the KDCs, Installing KDCs
953 @subsection Switching Master and Slave KDCs
955 You may occasionally want to use one of your slave KDCs as the master.
956 This might happen if you are upgrading the master KDC, or if your master
957 KDC has a disk crash.
959 Assuming you have configured all of your KDCs to be able to function as
960 either the master KDC or a slave KDC (as this document recommends), all
961 you need to do to make the changeover is:
963 If the master KDC is still running, do the following on the @emph{old}
968 Kill the @code{kadmind} process.
971 Disable the cron job that propagates the database.
974 Run your database propagation script manually, to ensure that the slaves
975 all have the latest copy of the database. (@xref{Propagate the Database
976 to Each Slave KDC}.) If there is a need to preserve per-principal
977 policy information from the database, you should do a ``kdb5_util dump
978 -ov'' in order to preserve that information and propogate that dump file
979 securely by some means to the slave so that its database has the correct
980 state of the per-principal policy information.
983 On the @emph{new} master KDC:
987 Create a database keytab. (@xref{Create a kadmind Keytab}.)
990 Start the @code{kadmind} daemon. (@xref{Start the Kerberos Daemons}.)
993 Set up the cron job to propagate the database. (@xref{Propagate the
994 Database to Each Slave KDC}.)
997 Switch the CNAMEs of the old and new master KDCs. (If you don't do
998 this, you'll need to change the @code{krb5.conf} file on every client
999 machine in your Kerberos realm.)
1003 @node Installing and Configuring UNIX Client Machines, UNIX Application Servers, Installing KDCs, Installing Kerberos V5
1004 @section Installing and Configuring UNIX Client Machines
1006 Client machine installation is much more straightforward than
1007 installation of the KDCs.
1011 * Client Machine Configuration Files::
1014 @node Client Programs, Client Machine Configuration Files, Installing and Configuring UNIX Client Machines, Installing and Configuring UNIX Client Machines
1015 @subsection Client Programs
1017 The Kerberized client programs are @code{login.krb5}, @code{rlogin},
1018 @code{telnet}, @code{ftp}, @code{rcp}, @code{rsh}, @code{kinit},
1019 @code{klist}, @code{kdestroy}, @code{kpasswd}, @code{ksu}, and
1020 @code{krb524init}. All of these programs are in the directory
1021 @code{@value{ROOTDIR}/bin}, except for @code{login.krb5} which is in
1022 @code{@value{ROOTDIR}/sbin}.
1024 You will probably want to have your users put @code{@value{ROOTDIR}/bin}
1025 ahead of @code{/bin} and @code{/usr/bin} in their paths, so they will by
1026 default get the @value{PRODUCT} versions of @code{rlogin},
1027 @code{telnet}, @code{ftp}, @code{rcp}, and @code{rsh}.
1029 @value{COMPANY} recommends that you use @code{login.krb5} in place of
1030 @code{/bin/login} to give your users a single-sign-on system. You will
1031 need to make sure your users know to use their Kerberos passwords when
1034 You will also need to educate your users to use the ticket management
1035 programs @code{kinit},
1036 @c @code{krb524init},
1037 @code{klist}, @code{kdestroy}, and to use the Kerberos programs
1039 @code{ksu}, and @code{kpasswd} in place of their non-Kerberos
1042 @code{su}, @code{passwd}, and @code{rdist}.
1044 @node Client Machine Configuration Files, , Client Programs, Installing and Configuring UNIX Client Machines
1045 @subsection Client Machine Configuration Files
1047 Each machine running Kerberos must have a @code{/etc/krb5.conf} file.
1051 Also, for most UNIX systems, you must add the appropriate Kerberos
1052 services to each client machine's @code{/etc/services} file. If you are
1053 using the default configuration for @value{PRODUCT}, you should be able
1054 to just insert the following code:
1059 # Note --- if you are using Kerberos V4 and you either:
1061 # (a) haven't converted all your master or slave KDCs to V5, or
1063 # (b) are worried about inter-realm interoperability with other KDC's
1064 # that are still using V4
1066 # you will need to switch the "kerberos" service to port 750 and create a
1067 # "kerberos-sec" service on port 88.
1069 kerberos 88/udp kdc # Kerberos V5 KDC
1070 kerberos 88/tcp kdc # Kerberos V5 KDC
1071 klogin 543/tcp # Kerberos authenticated rlogin
1072 kshell 544/tcp cmd # and remote shell
1073 kerberos-adm 749/tcp # Kerberos 5 admin/changepw
1074 kerberos-adm 749/udp # Kerberos 5 admin/changepw
1075 krb5_prop 754/tcp # Kerberos slave propagation
1076 @c kpop 1109/tcp # Pop with Kerberos
1077 eklogin 2105/tcp # Kerberos auth. & encrypted rlogin
1078 krb524 4444/tcp # Kerberos 5 to 4 ticket translator
1082 @noindent As described in the comments in the above code, if your master
1083 KDC or any of your slave KDCs is running Kerberos V4, (or if you will be
1084 authenticating to any Kerberos V4 KDCs in another realm) you will need
1085 to switch the port number for @code{kerberos} to 750 and create a
1086 @code{kerberos-sec} service (tcp and udp) on port 88, so the Kerberos
1087 V4 KDC(s) will continue to work properly.
1090 * Mac OS X Configuration::
1093 @node Mac OS X Configuration, , Client Machine Configuration Files, Client Machine Configuration Files
1094 @subsubsection Mac OS X Configuration
1096 To install Kerberos V5 on Mac OS X and Mac OS X Server, follow the
1097 directions for generic Unix-based OS's, except for the
1098 @code{/etc/services} updates described above.
1100 Mac OS X and Mac OS X Server use a database called NetInfo to store
1101 the contents of files normally found in @code{/etc}. Instead of
1102 modifying @code{/etc/services}, you should run the following commands
1103 to add the Kerberos service entries to NetInfo:
1107 $ niutil -create . /services/kerberos
1108 $ niutil -createprop . /services/kerberos name kerberos kdc
1109 $ niutil -createprop . /services/kerberos port 750
1110 $ niutil -createprop . /services/kerberos protocol tcp udp
1111 $ niutil -create . /services/krbupdate
1112 $ niutil -createprop . /services/krbupdate name krbupdate kreg
1113 $ niutil -createprop . /services/krbupdate port 760
1114 $ niutil -createprop . /services/krbupdate protocol tcp
1115 $ niutil -create . /services/kpasswd
1116 $ niutil -createprop . /services/kpasswd name kpasswd kpwd
1117 $ niutil -createprop . /services/kpasswd port 761
1118 $ niutil -createprop . /services/kpasswd protocol tcp
1119 $ niutil -create . /services/klogin
1120 $ niutil -createprop . /services/klogin port 543
1121 $ niutil -createprop . /services/klogin protocol tcp
1122 $ niutil -create . /services/eklogin
1123 $ niutil -createprop . /services/eklogin port 2105
1124 $ niutil -createprop . /services/eklogin protocol tcp
1125 $ niutil -create . /services/kshell
1126 $ niutil -createprop . /services/kshell name kshell krcmd
1127 $ niutil -createprop . /services/kshell port 544
1128 $ niutil -createprop . /services/kshell protocol tcp
1132 In addition to adding services to NetInfo, you must also modify the
1133 resolver configuration in NetInfo so that the machine resolves its own
1134 hostname as a FQDN (fully qualified domain name). By default, Mac OS X
1135 and Mac OS X Server machines query NetInfo to resolve hostnames before
1136 falling back to DNS. Because NetInfo has an unqualified name for all
1137 the machines in the NetInfo database, the machine's own hostname will
1138 resolve to an unqualified name. Kerberos needs a FQDN to look up keys
1139 in the machine's keytab file.
1141 Fortunately, you can change the @code{lookupd} caching order to query
1142 DNS first. Run the following NetInfo commands and reboot the machine:
1146 $ niutil -create . /locations/lookupd/hosts
1147 $ niutil -createprop . /locations/lookupd/hosts LookupOrder CacheAgent DNSAgent
1152 Once you have rebooted, you can verify that the resolver now behaves
1153 correctly. Compile the Kerberos 5 distribution and run:
1157 $ cd .../src/tests/resolve
1162 This will tell you whether or not your machine returns FQDNs on name
1163 lookups. If the test still fails, you can also try turning off DNS
1164 caching. Run the following commands and reboot:
1168 $ niutil -create . /locations/lookupd/hosts
1169 $ niutil -createprop . /locations/lookupd/hosts LookupOrder DNSAgent
1170 CacheAgent NIAgent NILAgent
1174 The remainder of the setup of a Mac OS X client machine or application
1175 server should be the same as for other UNIX-based systems.
1177 @node UNIX Application Servers, , Installing and Configuring UNIX Client Machines, Installing Kerberos V5
1178 @section UNIX Application Servers
1180 An application server is a host that provides one or more services over
1181 the network. Application servers can be ``secure'' or ``insecure.'' A
1182 ``secure'' host is set up to require authentication from every client
1183 connecting to it. An ``insecure'' host will still provide Kerberos
1184 authentication, but will also allow unauthenticated clients to connect.
1186 If you have @value{PRODUCT} installed on all of your client machines,
1187 @value{COMPANY} recommends that you make your hosts secure, to take
1188 advantage of the security that Kerberos authentication affords.
1189 However, if you have some clients that do not have @value{PRODUCT}
1190 installed, you can run an insecure server, and still take advantage of
1191 @value{PRODUCT}'s single sign-on on capability.
1195 * Server Configuration Files::
1197 * Some Advice about Secure Hosts::
1200 @node Server Programs, Server Configuration Files, UNIX Application Servers, UNIX Application Servers
1201 @subsection Server Programs
1203 Just as @value{PRODUCT} provided its own Kerberos-enhanced versions of
1204 client UNIX network programs, @value{PRODUCT} also provides
1205 Kerberos-enhanced versions of server UNIX network daemons. These are
1206 @code{ftpd}, @code{klogind}, @code{kshd}, and @code{telnetd}.
1208 These programs are installed in the directory
1209 @code{@value{ROOTDIR}/sbin}. You may want to add this directory to
1212 @node Server Configuration Files, The Keytab File, Server Programs, UNIX Application Servers
1213 @subsection Server Configuration Files
1215 For a @emph{secure} server, make the following changes to
1216 @code{/etc/inetd.conf}:
1218 Find and comment out any lines for the services @code{ftp},
1219 @code{telnet}, @code{shell}, @code{login}, and @code{exec}.
1222 Add the following lines. (Note: each line beginning with @result{} is
1223 a continuation of the previous line.)
1227 klogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1228 @result{} klogind -k -c
1229 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1230 @result{} klogind -k -c -e
1231 kshell stream tcp nowait root @value{ROOTDIR}/sbin/kshd
1232 @result{} kshd -k -c -A
1233 ftp stream tcp nowait root @value{ROOTDIR}/sbin/ftpd
1235 telnet stream tcp nowait root @value{ROOTDIR}/sbin/telnetd
1236 @result{} telnetd -a valid
1240 For an @emph{insecure} server, make the following changes instead to
1241 @code{/etc/inetd.conf}:
1244 Find and comment out any lines for the services @code{ftp} and
1247 Add the following lines. (Note: each line beginning with @result{} is
1248 a continuation of the previous line.)
1251 klogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1252 @result{} klogind -k -c
1253 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1254 @result{} klogind -k -c -e
1255 kshell stream tcp nowait root @value{ROOTDIR}/sbin/kshd
1256 @result{} kshd -k -c -A
1257 ftp stream tcp nowait root @value{ROOTDIR}/sbin/ftpd
1259 telnet stream tcp nowait root @value{ROOTDIR}/sbin/telnetd
1260 @result{} telnetd -a none
1264 @node The Keytab File, Some Advice about Secure Hosts, Server Configuration Files, UNIX Application Servers
1265 @subsection The Keytab File
1267 All Kerberos server machines need a @dfn{keytab} file, called
1268 @code{/etc/krb5.keytab}, to authenticate to the KDC. The keytab file is
1269 an encrypted, local, on-disk copy of the host's key. The keytab file,
1270 like the stash file (@ref{Create the Database}) is a potential
1271 point-of-entry for a break-in, and if compromised, would allow
1272 unrestricted access to its host. The keytab file should be readable
1273 only by root, and should exist only on the machine's local disk. The
1274 file should not be part of any backup of the machine, unless access to
1275 the backup data is secured as tightly as access to the machine's root
1278 In order to generate a keytab for a host, the host must have a principal
1279 in the Kerberos database. The procedure for adding hosts to the
1280 database is described fully in the ``Adding or Modifying Principals''
1281 section of the @cite{@value{PRODUCT} System Administrator's Guide}.
1282 @xref{Create Host Keys for the Slave KDCs}. for a brief description.)
1283 The keytab is generated by running @code{kadmin} and issuing the
1284 @code{ktadd} command.
1287 For example, to generate a keytab file to allow the host
1288 trillium.@value{PRIMARYDOMAIN} to authenticate for the services
1289 @code{host}, @code{ftp}, and @code{pop}, the administrator
1290 @code{@value{ADMINUSER}} would issue the command (on
1291 trillium.@value{PRIMARYDOMAIN}):
1295 @b{trillium%} @value{ROOTDIR}/sbin/kadmin
1296 @b{kadmin5:} ktadd host/trillium.@value{PRIMARYDOMAIN} ftp/trillium.@value{PRIMARYDOMAIN}
1297 @result{} pop/trillium.@value{PRIMARYDOMAIN}
1298 @b{kadmin: Entry for principal host/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
1299 kvno 3, encryption type DES-CBC-CRC added to keytab
1300 WRFILE:/etc/krb5.keytab.
1301 kadmin: Entry for principal ftp/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
1302 kvno 3, encryption type DES-CBC-CRC added to keytab
1303 WRFILE:/etc/krb5.keytab.
1304 kadmin: Entry for principal pop/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
1305 kvno 3, encryption type DES-CBC-CRC added to keytab
1306 WRFILE:/etc/krb5.keytab.
1312 If you generate the keytab file on another host, you need to get a copy
1313 of the keytab file onto the destination host (@code{trillium}, in the
1314 above example) without sending it unencrypted over the network. If you
1315 have installed the @value{PRODUCT} client programs, you can use
1316 encrypted @code{rcp}.
1318 @node Some Advice about Secure Hosts, , The Keytab File, UNIX Application Servers
1319 @subsection Some Advice about Secure Hosts
1321 @value{PRODUCT} can protect your host from certain types of break-ins,
1322 but it is possible to install @value{PRODUCT} and still leave your host
1323 vulnerable to attack. Obviously an installation guide is not the place
1324 to try to include an exhaustive list of countermeasures for every
1325 possible attack, but it is worth noting some of the larger holes and how
1328 As stated earlier in this section, @value{COMPANY} recommends that on a
1329 secure host, you disable the standard @code{ftp}, @code{login},
1330 @code{telnet}, @code{shell}, and @code{exec} services in
1331 @code{/etc/inetd.conf}. We also recommend that secure hosts have an empty
1332 @code{/etc/hosts.equiv} file and that there not be a @code{.rhosts} file
1333 in @code{root}'s home directory. You can grant Kerberos-authenticated
1334 root access to specific Kerberos principals by placing those principals
1335 in the file @code{.k5login} in root's home directory.
1337 We recommend that backups of secure machines exclude the keytab file
1338 (@code{/etc/krb5.keytab}). If this is not possible, the backups should
1339 at least be done locally, rather than over a network, and the backup
1340 tapes should be physically secured.
1342 Finally, the keytab file and any programs run by root, including the
1343 @value{PRODUCT} binaries, should be kept on local disk. The keytab file
1344 should be readable only by root.
1346 @node Upgrading Existing Kerberos V5 Installations, Bug Reports for Kerberos V5, Installing Kerberos V5, Top
1347 @chapter Upgrading Existing @value{PRODUCT} Installations
1349 If you already have an existing Kerberos database that you created with
1350 a prior release of Kerberos 5, you can upgrade it to work with the
1351 current release with the @code{kdb5_util} command. It is only necessary
1352 to perform this dump/undump procedure if you were running a krb5-1.0.x
1353 KDC and are migrating to a krb5-1.1.x or newer KDC. The process for
1354 upgrading a Master KDC involves the following steps:
1358 @item Stop your current KDC and administration
1359 server processes, if any.
1361 @item Dump your existing Kerberos database to an ASCII file with
1362 @code{kdb5_util}'s ``dump'' command:
1366 @b{shell%} cd @value{ROOTDIR}/var/krb5kdc
1367 @b{shell%} kdb5_util dump old-kdb-dump
1368 @b{shell%} kdb5_util dump -ov old-kdb-dump.ov
1373 @item Create a new Master KDC installation (@xref{Install the Master
1374 KDC}.). If you have a stash file for your current database, choose any
1375 new master password but then copy your existing stash file to the
1376 location specified by your kdc.conf; if you do not have a stash file for
1377 your current database, you must choose the same master password.
1379 @item Load your old Kerberos database into the new system with
1380 @code{kdb5_util}'s ``load'' command:
1384 @b{shell%} cd @value{ROOTDIR}/var/krb5kdc
1385 @b{shell%} kdb5_util load old-kdb-dump
1386 @b{shell%} kdb5_util load -update old-kdb-dump.ov
1393 The ``dump -ov'' and ``load -update'' commands are necessary in order to
1394 preserve per-principal policy information, since the default dump format
1395 filters out that information. If you omit those steps, the loaded
1396 database database will lose the policy information for each principal
1399 To update a Slave KDC, you must stop the old server processes on the
1400 Slave KDC, install the new server binaries, reload the most recent slave
1401 dump file, and re-start the server processes.
1404 * Upgrading to Triple-DES Encryption Keys::
1407 @node Upgrading to Triple-DES Encryption Keys, , Upgrading Existing Kerberos V5 Installations, Upgrading Existing Kerberos V5 Installations
1408 @section Upgrading to Triple-DES Encryption Keys
1410 Beginning with the 1.2 release from MIT, Kerberos includes a stronger
1411 encryption algorithm called ``triple DES'' -- essentially, three
1412 applications of the basic DES encryption algorithm, greatly increasing
1413 the resistance to a brute-force search for the key by an attacker. This
1414 algorithm is more secure, but encryption is much slower. We expect to
1415 add other, faster encryption algorithms at some point in the future.
1417 Release 1.1 had some support for triple-DES service keys, but with
1418 release 1.2 we have added support for user keys and session keys as
1419 well. Release 1.0 had very little support for multiple cryptosystems,
1420 and some of that software may not function properly in an environment
1421 using triple-DES as well as plain DES.
1423 Because of the way the MIT Kerberos database is structured, the KDC will
1424 assume that a service supports only those encryption types for which
1425 keys are found in the database. Thus, if a service has only a
1426 single-DES key in the database, the KDC will not issue tickets for that
1427 service that use triple-DES session keys; it will instead issue only
1428 single-DES session keys, even if other services are already capable of
1429 using triple-DES. So if you make sure your application server software
1430 is updated before adding a triple-DES key for the service, clients
1431 should be able to talk to services at all times during the updating
1434 Normally, the listed @code{supported_enctypes} in @code{kdc.conf} are
1435 all used when a new key is generated. You can control this with
1436 command-line flags to @code{kadmin} and @code{kadmin.local}. You may
1437 want to exclude triple-DES by default until you have updated a lot of
1438 your application servers, and then change the default to include
1439 triple-DES. We recommend that you always include @code{des-cbc-crc} in
1442 @node Bug Reports for Kerberos V5, Files, Upgrading Existing Kerberos V5 Installations, Top
1443 @chapter Bug Reports for @value{PRODUCT}
1445 @include send-pr.texinfo
1447 @node Files, , Bug Reports for Kerberos V5, Top
1455 @node krb5.conf, kdc.conf, Files, Files
1456 @appendixsec krb5.conf
1458 Here is an example @code{krb5.conf} file:
1463 ticket_lifetime = 600
1464 default_realm = @value{PRIMARYREALM}
1465 default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc
1466 default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc
1469 @value{PRIMARYREALM} = @{
1470 kdc = @value{KDCSERVER}.@value{PRIMARYDOMAIN}:88
1471 kdc = @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}:88
1472 kdc = @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}:88
1473 admin_server = @value{KDCSERVER}.@value{PRIMARYDOMAIN}:749
1474 default_domain = @value{PRIMARYDOMAIN}
1478 .@value{PRIMARYDOMAIN} = @value{PRIMARYREALM}
1479 @value{PRIMARYDOMAIN} = @value{PRIMARYREALM}
1483 For the KDCs, add a section onto the end of the @code{krb5.conf} file
1484 telling how logging information should be stored, as in the following
1490 kdc = FILE:/var/log/krb5kdc.log
1491 admin_server = FILE:/var/log/kadmin.log
1492 default = FILE:/var/log/krb5lib.log
1501 @node kdc.conf, , krb5.conf, Files
1502 @appendixsec kdc.conf
1504 Here's an example of a kdc.conf file:
1512 @value{PRIMARYREALM} = @{
1513 database_name = @value{ROOTDIR}/var/krb5kdc/principal
1514 admin_keytab = @value{ROOTDIR}/var/krb5kdc/kadm5.keytab
1515 acl_file = @value{ROOTDIR}/var/krb5kdc/kadm5.acl
1516 dict_file = @value{ROOTDIR}/var/krb5kdc/kadm5.dict
1517 key_stash_file = @value{ROOTDIR}/var/krb5kdc/.k5.@value{PRIMARYREALM}
1519 max_life = 10h 0m 0s
1520 max_renewable_life = 7d 0h 0m 0s
1521 master_key_type = des3-hmac-sha1
1522 supported_enctypes = des3-hmac-sha1:normal des-cbc-crc:normal
1527 To add Kerberos V4 support, add @code{des-cbc-crc:v4} to the
1528 @code{supported_enctypes} line.
1531 * Encryption Types and Salt Types::
1534 @node Encryption Types and Salt Types, , kdc.conf, kdc.conf
1535 @appendixsubsec Encryption Types and Salt Types
1537 Currently, @value{PRODUCT} supports only DES and triple-DES encryption.
1538 The encoding types include
1539 @code{des-cbc-crc} and @code{des3-cbc-sha1}. The @dfn{salt} is
1540 additional information encoded within the key that tells what kind of
1541 key it is. The only salts that you will be likely to encounter are:
1544 @item @dfn{normal}, which @value{COMPANY} recommends using for all of
1545 your @value{PRODUCT} keys
1547 @item @dfn{v4}, which is necessary only for compatibility with a v4 KDC
1548 or a v4 version of @code{kinit}, and then only with @code{des-cbc-crc}
1551 @item @dfn{afs}, which you will never need to generate, and which you will
1552 encounter only if you dump an AFS database into a Kerberos database
1555 Support for additional encryption types is planned in the future.