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
47 @c The master menu is updated using emacs19's M-x texinfo-all-menus-update
48 @c function. Don't forget to run M-x texinfo-every-node-update after
49 @c you add a new section or subsection, or after you've rearranged the
50 @c order of sections or subsections. Also, don't forget to add an @node
51 @c comand before each @section or @subsection! All you need to enter
54 @c @node New Section Name
56 @c @section New Section Name
58 @c M-x texinfo-every-node-update will take care of calculating the
59 @c node's forward and back pointers.
61 @c ---------------------------------------------------------------------
66 * Realm Configuration Decisions::
67 * Building Kerberos V5::
68 * Installing Kerberos V5::
69 * Upgrading Existing Kerberos V5 Installations::
70 * Bug Reports for Kerberos V5::
73 @node Copyright, Introduction, Top, Top
75 @include copyright.texinfo
77 @node Introduction, Realm Configuration Decisions, Copyright, Top
81 * What is Kerberos and How Does it Work?::
82 * Why Should I use Kerberos?::
83 * Please Read the Documentation::
84 * Overview of This Guide::
87 @node What is Kerberos and How Does it Work?, Why Should I use Kerberos?, Introduction, Introduction
88 @section What is Kerberos and How Does it Work?
90 @value{PRODUCT} is based on the Kerberos authentication system developed
91 at MIT. Under Kerberos, a client (generally either a user or a service)
92 sends a request for a ticket to the Key Distribution Center (KDC). The
93 KDC creates a @dfn{ticket-granting ticket} (TGT) for the client,
94 encrypts it using the client's password as the key, and sends the
95 encrypted TGT back to the client. The client then attempts to decrypt
96 the TGT, using its password. If the client successfully decrypts the
97 TGT (@i{i.e.}, if the client gave the correct password), it keeps the
98 decrypted TGT, which indicates proof of the client's identity.
100 The TGT, which expires at a specified time, permits the client to obtain
101 additional tickets, which give permission for specific services. The
102 requesting and granting of these additional tickets is user-transparent.
104 @node Why Should I use Kerberos?, Please Read the Documentation, What is Kerberos and How Does it Work?, Introduction
105 @section Why Should I use Kerberos?
107 Since Kerberos negotiates authenticated, and optionally encrypted,
108 communications between two points anywhere on the Internet, it provides
109 a layer of security that is not dependent on which side of a firewall
110 either client is on. Since studies have shown that half of the computer
111 security breaches in industry happen from @i{inside} firewalls,
112 @value{PRODUCT} from @value{COMPANY} will play a vital role in the
113 security of your network.
115 @include document-list.texinfo
117 @node Please Read the Documentation, Overview of This Guide, Why Should I use Kerberos?, Introduction
118 @section Please Read the Documentation
120 As with any software package that uses a centrallized database, the
121 installation procedure is somewhat involved, and requires forethought
122 and planning. @value{COMPANY} has attempted to make this
123 @value{PRODUCT} Installation Guide as concise as possible, rather than
124 making it an exhaustive description of the details of Kerberos.
126 Consequently, everything in this guide appears because @value{COMPANY}
127 believes that it is important. Please read and follow these
128 instructions carefully, and if there is anything you do not understand
129 or are not sure of, please don't hesitate to call us.
132 Consequently, everything in this guide appears because @value{COMPANY}
133 believes that it is important. Please read and follow these
134 instructions carefully.
137 @node Overview of This Guide, , Please Read the Documentation, Introduction
138 @section Overview of This Guide
140 The next chapter describes the decisions you need to make before
141 installing @value{PRODUCT}.
143 Chapter four describes installation procedures for each class of
148 Key Distribution Centers (KDCs).
162 UNIX application server machines
166 Note that a machine can be both a client machine and an application
169 Chapter five describes procedure for updating previous installations of
172 Chapter six describes our problem reporting system.
174 The appendices give sample configuration files.
176 @node Realm Configuration Decisions, Building Kerberos V5, Introduction, Top
177 @chapter Realm Configuration Decisions
179 Before installing @value{PRODUCT}, it is necessary to consider the
184 The name of your Kerberos realm (or the name of each realm, if you need
188 How you will map your hostnames onto Kerberos realms.
191 Which ports your KDC and and kadmin (database access) services will use.
194 How many slave KDCs you need and where they should be located.
197 The hostnames of your master and slave KDCs.
200 How frequently you will propagate the database from the master KDC to
204 Whether you need backward compatibility with Kerberos V4.
209 * Mapping Hostnames onto Kerberos Realms::
210 * Ports for the KDC and Admin Services::
212 * Hostnames for the Master and Slave KDCs::
213 * Database Propagation::
216 @node Kerberos Realms, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions, Realm Configuration Decisions
217 @section Kerberos Realms
219 Although your Kerberos realm can be any ASCII string, convention is to
220 make it the same as your domain name, in upper-case letters. For
221 example, hosts in the domain @value{SECONDDOMAIN} would be in the
222 Kerberos realm @value{SECONDREALM}.
224 If you need multiple Kerberos realms, @value{COMPANY} recommends that
225 you use descriptive names which end with your domain name, such as
226 BOSTON.@value{SECONDREALM} and HOUSTON.@value{SECONDREALM}.
228 @node Mapping Hostnames onto Kerberos Realms, Ports for the KDC and Admin Services, Kerberos Realms, Realm Configuration Decisions
229 @section Mapping Hostnames onto Kerberos Realms
231 @include dnstxt.texinfo
233 @node Ports for the KDC and Admin Services, Slave KDCs, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions
234 @section Ports for the KDC and Admin Services
236 The default ports used by Kerberos are port 88 for the
237 KDC@footnote{Kerberos V4 used port 750. If necessary, you can run on
238 both ports for backward compatibility.} and port 749 for the admin
239 server. You can, however, choose to run on other ports, as long as they
240 are specified in each host's @code{/etc/services} and @code{krb5.conf}
241 files, and the @code{kdc.conf} file on each KDC. For a more thorough
242 treatment of port numbers used by the @value{PRODUCT} programs, refer to
243 the ``Configuring Your Firewall to Work With @value{PRODUCT}'' section
244 of the @cite{@value{PRODUCT} System Administrator's Guide}.
246 @node Slave KDCs, Hostnames for the Master and Slave KDCs, Ports for the KDC and Admin Services, Realm Configuration Decisions
249 Slave KDCs provide an additional source of Kerberos ticket-granting
250 services in the event of inaccessibility of the master KDC. The number
251 of slave KDCs you need and the decision of where to place them, both
252 physically and logically, depends on the specifics of your network.
254 All of the Kerberos authentication on your network requires that each
255 client be able to contact a KDC. Therefore, you need to anticipate any
256 likely reason a KDC might be unavailable and have a slave KDC to take up
259 Some considerations include:
263 Have at least one slave KDC as a backup, for when the master KDC is
264 down, is being upgraded, or is otherwise unavailable.
267 If your network is split such that a network outage is likely to cause a
268 network partition (some segment or segments of the network to become cut
269 off or isolated from other segments), have a slave KDC accessible to
273 If possible, have at least one slave KDC in a different building from
274 the master, in case of power outages, fires, or other localized
280 @node Hostnames for the Master and Slave KDCs, Database Propagation, Slave KDCs, Realm Configuration Decisions
281 @section Hostnames for the Master and Slave KDCs
283 @include dnssrv.texinfo
285 @node Database Propagation, , Hostnames for the Master and Slave KDCs, Realm Configuration Decisions
286 @section Database Propagation
288 The Kerberos database resides on the master KDC, and must be propagated
289 regularly (usually by a cron job) to the slave KDCs. In deciding how
290 frequently the propagation should happen, you will need to balance the
291 amount of time the propagation takes against the maximum reasonable
292 amount of time a user should have to wait for a password change to take
295 If the propagation time is longer than this maximum reasonable time
296 (@i{e.g.,} you have a particularly large database, you have a lot of
297 slaves, or you experience frequent network delays), you may wish to
298 cut down on your propagation delay by performing the propagation in
299 parallel. To do this, have the master KDC propagate the database to one
300 set of slaves, and then have each of these slaves propagate the database
301 to additional slaves.
303 @node Building Kerberos V5, Installing Kerberos V5, Realm Configuration Decisions, Top
304 @chapter Building @value{PRODUCT}
306 @include build.texinfo
308 @node Installing Kerberos V5, Upgrading Existing Kerberos V5 Installations, Building Kerberos V5, Top
309 @chapter Installing @value{PRODUCT}
311 The sections of this chapter describe procedures for installing
322 UNIX Application Servers
327 * Installing and Configuring UNIX Client Machines::
328 * UNIX Application Servers::
331 @node Installing KDCs, Installing and Configuring UNIX Client Machines, Installing Kerberos V5, Installing Kerberos V5
332 @section Installing KDCs
334 The Key Distribution Centers (KDCs) issue Kerberos tickets. Each KDC
335 contains a copy of the Kerberos database. The master KDC contains the
336 master copy of the database, which it propagates to the slave KDCs at
337 regular intervals. All database changes (such as password changes) are
338 made on the master KDC.
340 Slave KDCs provide Kerberos ticket-granting services, but not database
341 administration. This allows clients to continue to obtain tickets when
342 the master KDC is unavailable.
344 @value{COMPANY} recommends that you install all of your KDCs to be able
345 to function as either the master or one of the slaves. This will enable
346 you to easily switch your master KDC with one of the slaves if
347 necessary. (@xref{Switching Master and Slave KDCs}.) This installation
348 procedure is based on that recommendation.
351 * Install the Master KDC::
352 * Install the Slave KDCs::
353 * Back on the Master KDC::
354 * Finish Installing the Slave KDCs::
355 * Add Kerberos Principals to the Database::
356 * Limit Access to the KDCs::
357 * Switching Master and Slave KDCs::
360 @node Install the Master KDC, Install the Slave KDCs, Installing KDCs, Installing KDCs
361 @subsection Install the Master KDC
363 This installation procedure will require you to go back and forth a
364 couple of times between the master KDC and each of the slave KDCs. The
365 first few steps must be done on the master KDC.
368 * Edit the Configuration Files::
371 * Create the Database::
372 * Add Administrators to the Acl File::
373 * Add Administrators to the Kerberos Database::
374 * Create a kadmind Keytab::
375 * Start the Kerberos Daemons::
378 @node Edit the Configuration Files, krb5.conf, Install the Master KDC, Install the Master KDC
379 @subsubsection Edit the Configuration Files
381 Modify the configuration files, @code{/etc/krb5.conf} and
382 @code{@value{ROOTDIR}/var/krb5kdc/kdc.conf} to reflect the correct
383 information (such as the hostnames and realm name) for your realm.
384 @value{COMPANY} recommends that you keep @code{krb5.conf} in @code{/etc}.
386 Most of the tags in the configuration have default values that will
387 work well for most sites. There are some tags in the @code{krb5.conf}
388 file whose values must be specified, and this section will explain
389 those as well as give an overview of all of the sections in both
390 configuration files. For more information on changing defaults with
391 the configuration files, see the @value{PRODUCT} System Administrator's
392 Guide sections on configuration files.
394 @node krb5.conf, kdc.conf, Edit the Configuration Files, Install the Master KDC
395 @subsubsection krb5.conf
397 @include krb5conf.texinfo
399 If you are not using DNS TXT records, you must specify the
400 @code{default_realm} in the @code{libdefaults} section. If you are not
401 using DNS SRV records, you must include the @code{kdc} tag for each
402 realm in the @code{realms} section. To communicate with the kadmin
403 server in each realm, the @code{admin_server} tag must be set in the
404 @code{realms} section. If your domain name and realm name are not the
405 same, you must provide a translation in @code{domain_realm}. It is
406 also higly recommeneded that you create a @code{[logging]} stanza if
407 the computer will be functioning as a KDC so that the KDC and kadmind
408 will generate logging output.
410 An example @code{krb5.conf} file:
415 default_realm = @value{PRIMARYREALM}
418 kdc = @value{KDCSERVER}.@value{PRIMARYDOMAIN}
419 kdc = @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}
420 kdc = @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}
421 admin_server = @value{KDCSERVER}.@value{PRIMARYDOMAIN}
424 kdc = FILE:/var/log/krb5kdc.log
425 admin_server = FILE:/var/log/kadmin.log
426 default = FILE:/var/log/krb5lib.log
430 @node kdc.conf, Create the Database, krb5.conf, Install the Master KDC
431 @subsubsection kdc.conf
433 @include kdcconf.texinfo
435 @node Create the Database, Add Administrators to the Acl File, kdc.conf, Install the Master KDC
436 @subsubsection Create the Database
438 You will use the @code{kdb5_util} command @emph{on the Master KDC} to
439 create the Kerberos database and the optional stash file. The
440 @dfn{stash file} is a local copy of the master key that resides in
441 encrypted form on the KDC's local disk. The stash file is used to
442 authenticate the KDC to itself automatically before starting the
443 @code{kadmind} and @code{krb5kdc} daemons (@i{e.g.,} as part of the
444 machine's boot sequence). The stash file, like the keytab file
445 (see @xref{The Keytab File}, for more information) is a potential
446 point-of-entry for a break-in,
447 and if compromised, would allow unrestricted access to the Kerberos
448 database. If you choose to install a stash file, it should be readable
449 only by root, and should exist only on the KDC's local disk. The file
450 should not be part of any backup of the machine, unless access to the
451 backup data is secured as tightly as access to the master password
454 Note that @code{kdb5_util} will prompt you for the master key for the
455 Kerberos database. This key can be any string. A good key is one you
456 can remember, but that no one else can guess. Examples of bad keys are
457 words that can be found in a dictionary, any common or popular name,
458 especially a famous person (or cartoon character), your username in any
459 form (@i{e.g.}, forward, backward, repeated twice, @i{etc.}), and any of
460 the sample keys that appear in this manual. One example of a key which
461 might be good if it did not appear in this manual is ``MITiys4K5!'',
462 which represents the sentence ``MIT is your source for Kerberos 5!''
463 (It's the first letter of each word, substituting the numeral ``4'' for
464 the word ``for'', and includes the punctuation mark at the end.)
466 The following is an example of how to create a Kerberos database and
467 stash file on the master KDC, using the @code{kdb5_util} command. (The
468 line that begins with @result{} is a continuation of the previous line.)
469 Replace @i{@value{PRIMARYREALM}} with the name of your Kerberos realm.
473 @b{shell%} @value{ROOTDIR}/sbin/kdb5_util create -r @value{PRIMARYREALM} -s
474 @b{Initializing database '@value{ROOTDIR}/var/krb5kdc/principal' for
475 @result{} realm '@value{PRIMARYREALM}',
476 master key name 'K/M@@@value{PRIMARYREALM}'
477 You will be prompted for the database Master Password.
478 It is important that you NOT FORGET this password.}
480 @b{Enter KDC database master key:} @i{@doubleleftarrow{} Type the master password.}
481 @b{Re-enter KDC database master key to verify:} @i{@doubleleftarrow{} Type it again.}
484 @b{Enter KDC database master key:} @i{<= Type the master password.}
485 @b{Re-enter KDC database master key to verify:} @i{<= Type it again.}
491 This will create five files in the directory specified in your
492 @code{kdc.conf} file: two Kerberos database files, @code{principal.db},
493 and @code{principal.ok}; the Kerberos administrative database file,
494 @code{principal.kadm5}; the administrative database lock file,
495 @code{principal.kadm5.lock}; and the stash file, @code{.k5stash}. (The
496 default directory is @code{@value{ROOTDIR}/var/krb5kdc}.) If you do not
497 want a stash file, run the above command without the @code{-s} option.
499 @node Add Administrators to the Acl File, Add Administrators to the Kerberos Database, Create the Database, Install the Master KDC
500 @subsubsection Add Administrators to the Acl File
502 Next, you need create an Access Control List (acl) file, and put the
503 Kerberos principal of at least one of the administrators into it. The
504 filename should match the value you have set for ``acl_file'' in your
505 @code{kdc.conf} file. The default file name is @samp{kadm5.acl}. The
506 format of the file is:
509 Kerberos principal permissions optional target principal
512 The Kerberos principal (and optional target principal) can include the
513 ``@b{*}'' wildcard, so if you want any principal with the instance
514 ``admin'' to have full permissions on the database, you could use the
515 principal ``@code{*/admin@@REALM}'' where ``REALM'' is your Kerberos
518 Note: a common use of an @i{admin} instance is so you can grant
519 separate permissions (such as administrator access to the Kerberos
520 database) to a separate Kerberos principal. For example, the user
521 @code{@value{ADMINUSER}} might have a principal for his administrative
522 use, called @code{@value{ADMINUSER}/admin}. This way,
523 @code{@value{ADMINUSER}} would obtain @code{@value{ADMINUSER}/admin}
524 tickets only when he actually needs to use those permissions. Refer to
525 the @value{PRODUCT} Administrator's Guide or the @value{PRODUCT} User's
526 Guide for more detailed explanations of @dfn{principals} and
529 The permissions (acls) recognized in the acl file
534 allows the addition of principals or policies in the database.
536 prohibits the addition of principals or policies in the database.
538 allows the deletion of principals or policies in the database.
540 prohibits the deletion of principals or policies in the database.
542 allows the modification of principals or policies in the database.
544 prohibits the modification of principals or policies in the database.
546 allows the changing of passwords for principals in the database.
548 prohibits the changing of passwords for principals in the database.
550 allows inquiries to the database.
552 prohibits inquiries to the database.
554 allows the listing of principals or policies in the database.
556 prohibits the listing of principals or policies in the database.
558 Short for all privileges (admcil).
560 Short for all privileges (admcil); identical to ``*''.
563 To give the principal @code{*/admin@@@value{PRIMARYREALM}} permission to
564 change all of the database permissions on any principal permissions, you
565 would place the following line in the file:
568 */admin@@@value{PRIMARYREALM} *
571 To give the principal @code{@value{ADMINUSER}@@@value{PRIMARYREALM}}
572 permission to add, list, and inquire about any principal that has the
573 instance ``root'', you would add the following line to the acl file:
576 @value{ADMINUSER}@@@value{PRIMARYREALM} ali */root@@@value{PRIMARYREALM}
579 @node Add Administrators to the Kerberos Database, Create a kadmind Keytab, Add Administrators to the Acl File, Install the Master KDC
580 @subsubsection Add Administrators to the Kerberos Database
582 Next you need to add administrative principals to the Kerberos database.
583 (You must add at least one now.) To do this, use @code{kadmin.local}
584 @emph{on the master KDC}. The administrative principals you create
585 should be the ones you added to the ACL file. (See @xref{Add
586 Administrators to the Acl File}.) In the following example, the
587 administration principal @code{admin/admin} is created:
591 @b{shell%} @value{ROOTDIR}/sbin/kadmin.local
592 @b{kadmin.local:} addprinc admin/admin@@@value{PRIMARYREALM}
593 @b{WARNING: no policy specified for "admin/admin@@@value{PRIMARYREALM}";
594 defaulting to no policy.}
596 @b{Enter password for principal admin/admin@@@value{PRIMARYREALM}:} @i{@doubleleftarrow{} Enter a password.}
597 Re-enter password for principal admin/admin@@@value{PRIMARYREALM}: @i{@doubleleftarrow{} Type it again.}
600 @b{Enter password for principal admin/admin@@@value{PRIMARYREALM}:} @i{<= Enter a password.}
601 Re-enter password for principal admin/admin@@@value{PRIMARYREALM}: @i{<= Type it again.}
603 @b{Principal "admin/admin@@@value{PRIMARYREALM}" created.
610 @node Create a kadmind Keytab, Start the Kerberos Daemons, Add Administrators to the Kerberos Database, Install the Master KDC
611 @subsubsection Create a kadmind Keytab
613 The kadmind keytab is the key that kadmind will use to decrypt
614 administrators' Kerberos tickets to determine whether or not it should
615 give them access to the database. You need to create the kadmin keytab
616 with entries for the principals @code{kadmin/admin} and
617 @code{kadmin/changepw}. (These principals are placed in the Kerberos
618 database automatically when you create it.) To create the kadmin
619 keytab, run @code{kadmin.local} and use the @code{ktadd} command, as in
620 the following example. (The line beginning with @result{} is a
621 continuation of the previous line.):
625 @b{shell%} @value{ROOTDIR}/sbin/kadmin.local
626 @b{kadmin.local:} ktadd -k @value{ROOTDIR}/var/krb5kdc/kadm5.keytab
627 @result{} kadmin/admin kadmin/changepw
628 @b{Entry for principal kadmin/admin@@@value{PRIMARYREALM} with
629 kvno 3, encryption type DES-CBC-CRC added to keytab
630 WRFILE:@value{ROOTDIR}/var/krb5kdc/kadm5.keytab.
631 Entry for principal kadmin/changepw@@@value{PRIMARYREALM} with
632 kvno 3, encryption type DES-CBC-CRC added to keytab
633 WRFILE:@value{ROOTDIR}/var/krb5kdc/kadm5.keytab.
640 As specified in the @samp{-k} argument, @code{ktadd} will save the
641 extracted keytab as @* @code{@value{ROOTDIR}/var/krb5kdc/kadm5.keytab}.
642 The filename you use must be the one specified in your @code{kdc.conf}
646 @node Start the Kerberos Daemons, , Create a kadmind Keytab, Install the Master KDC
647 @subsubsection Start the Kerberos Daemons on the Master KDC
649 At this point, you are ready to start the Kerberos daemons on the Master
653 @b{shell%} @value{ROOTDIR}/sbin/krb5kdc
654 @b{shell%} @value{ROOTDIR}/sbin/kadmind
658 Each daemon will fork and run in the background. Assuming you want
659 these daemons to start up automatically at boot time, you can add them
660 to the KDC's @code{/etc/rc} or @code{/etc/inittab} file. You need to
661 have a stash file in order to do this.
663 You can verify that they started properly by checking for their startup
664 messages in the logging locations you defined in @code{/etc/krb5.conf}.
665 (@xref{Edit the Configuration Files}.) For example:
668 @b{shell%} tail /var/log/krb5kdc.log
669 Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
670 @b{shell%} tail /var/log/kadmin.log
671 Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting
674 Any errors the daemons encounter while starting will also be listed in
678 @node Install the Slave KDCs, Back on the Master KDC, Install the Master KDC, Installing KDCs
679 @subsection Install the Slave KDCs
681 You are now ready to start configuring the slave KDCs. Assuming you are
682 setting the KDCs up so that you can easily switch the master KDC with
683 one of the slaves, you should perform each of these steps on the master
684 KDC as well as the slave KDCs, unless these instructions specify
689 * Create Host Keys for the Slave KDCs::
690 * Extract Host Keytabs for the KDCs::
691 * Set Up the Slave KDCs for Database Propagation::
694 @node Create Host Keys for the Slave KDCs, Extract Host Keytabs for the KDCs, Install the Slave KDCs, Install the Slave KDCs
695 @subsubsection Create Host Keys for the Slave KDCs
697 Each KDC needs a host principal in the Kerberos database. You can enter
698 these from any host, once the @code{kadmind} daemon is running. For
699 example, if your master KDC were called
700 @value{KDCSERVER}.@value{PRIMARYDOMAIN}, and you had two KDC slaves
701 named @value{KDCSLAVE1}.@value{PRIMARYDOMAIN} and
702 @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}, you would type the following:
706 @b{shell%} @value{ROOTDIR}/sbin/kadmin
707 @b{kadmin:} addprinc -randkey host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}
708 @b{WARNING: no policy specified for "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
709 defaulting to no policy.
710 Principal "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.
711 kadmin:} addprinc -randkey host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}
712 @b{WARNING: no policy specified for "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
713 defaulting to no policy.
714 Principal "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.}
715 @b{kadmin:} addprinc -randkey host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}
716 @b{WARNING: no policy specified for "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
717 defaulting to no policy.
718 Principal "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.
724 It is not actually necessary to have the master KDC server in the
725 Kerberos database, but it can be handy if:
729 anyone will be logging into the machine as something other than root
732 you want to be able to swap the master KDC with one of the slaves if
736 @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
737 @subsubsection Extract Host Keytabs for the KDCs
739 Each KDC (including the master) needs a keytab to decrypt tickets.
740 Ideally, you should extract each keytab locally on its own KDC. If this
741 is not feasible, you should use an encrypted session to send them across
742 the network. To extract a keytab on a KDC called
743 @value{KDCSERVER}.@value{PRIMARYDOMAIN}, you would execute the following
748 @b{kadmin:} ktadd host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}
749 @b{kadmin: Entry for principal host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
750 kvno 1, encryption type DES-CBC-CRC added to keytab
751 WRFILE:/etc/krb5.keytab.
757 Note that the principal must exist in the Kerberos database in order to
760 @node Set Up the Slave KDCs for Database Propagation, , Extract Host Keytabs for the KDCs, Install the Slave KDCs
761 @subsubsection Set Up the Slave KDCs for Database Propagation
763 The database is propagated from the master KDC to the slave KDCs via the
764 @code{kpropd} daemon. To set up propagation, create a file on each KDC,
765 named @code{@value{ROOTDIR}/var/krb5kdc/kpropd.acl}, containing the
766 principals for each of the KDCs.
768 For example, if the master KDC were
769 @code{@value{KDCSERVER}.@value{PRIMARYDOMAIN}}, the slave KDCs were
770 @code{@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}} and
771 @code{@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}}, and the realm were
772 @code{@value{PRIMARYREALM}}, then the file's contents would be:
776 host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
777 host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
778 host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
783 Then, add the following lines to @code{/etc/inetd.conf} file on each KDC
784 (the line beginnng with @result{} is a continuation of the previous
789 krb5_prop stream tcp nowait root @value{ROOTDIR}/sbin/kpropd kpropd
790 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
791 @result{} klogind -k -c -e
796 The first line sets up the @code{kpropd} database propagation daemon.
797 The second line sets up the @code{eklogin} daemon, allowing
798 Kerberos-authenticated, encrypted rlogin to the KDC.
800 You also need to add the following lines to @code{/etc/services} on each
805 kerberos 88/udp kdc # Kerberos authentication (udp)
806 kerberos 88/tcp kdc # Kerberos authentication (tcp)
807 krb5_prop 754/tcp # Kerberos slave propagation
808 kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp)
809 kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp)
810 eklogin 2105/tcp # Kerberos encrypted rlogin
814 @node Back on the Master KDC, Finish Installing the Slave KDCs, Install the Slave KDCs, Installing KDCs
815 @subsection Back on the Master KDC
817 Now that the slave KDCs are able to accept database propagation, you'll
818 need to propagate the database to each of them.
821 * Propagate the Database to Each Slave KDC::
824 @node Propagate the Database to Each Slave KDC, , Back on the Master KDC, Back on the Master KDC
825 @subsubsection Propagate the Database to Each Slave KDC
827 First, create a dump of the database on the master KDC, as follows:
831 @b{shell%} @value{ROOTDIR}/sbin/kdb5_util dump @value{ROOTDIR}/var/krb5kdc/slave_datatrans
836 Next, you need to manually propagate the database to each slave KDC, as
837 in the following example. (The lines beginning with @result{} are
838 continuations of the previous line.):
842 @value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans
843 @result{} @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}
844 @value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans
845 @result{} @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}
849 You will need a script to dump and propagate the database. The
850 following is an example of a bourne shell script that will do this.
851 (Note that the line that begins with @result{} is a continuation of the
852 previous line. Remember that you need to replace @value{ROOTDIR} with
853 the name of the directory in which you installed @value{PRODUCT}.)
859 kdclist = "@value{KDCSLAVE1}.@value{PRIMARYDOMAIN} @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}"
861 @value{ROOTDIR}/sbin/kdb5_util -R "dump
862 @result{} @value{ROOTDIR}/var/krb5kdc/slave_datatrans"
866 @value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans $kdc
872 You will need to set up a cron job to run this script at the intervals
873 you decided on earlier (@xref{Database Propagation}.)
875 @node Finish Installing the Slave KDCs, Add Kerberos Principals to the Database, Back on the Master KDC, Installing KDCs
876 @subsection Finish Installing the Slave KDCs
878 Now that the slave KDCs have copies of the Kerberos database, you can
879 create stash files for them and start the @code{krb5kdc} daemon.
882 * Create Stash Files on the Slave KDCs::
883 * Start the krb5kdc Daemon on Each KDC::
886 @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
887 @subsubsection Create Stash Files on the Slave KDCs
889 Create stash files, by issuing the following commands on each slave KDC:
893 @b{shell%} kdb5_util stash
894 @b{kdb5_util: Cannot find/read stored master key while reading master key
895 kdb5_util: Warning: proceeding without master key}
897 @b{Enter KDC database master key:} @i{@doubleleftarrow{} Enter the database master key.}
900 @b{Enter KDC database master key:} @i{<= Enter the database master key.}
906 As mentioned above, the stash file is necessary for your KDCs to be able
907 authenticate to themselves, such as when they reboot. You could run
908 your KDCs without stash files, but you would then need to type in the
909 Kerberos database master key by hand every time you start a KDC daemon.
911 @node Start the krb5kdc Daemon on Each KDC, , Create Stash Files on the Slave KDCs, Finish Installing the Slave KDCs
912 @subsubsection Start the krb5kdc Daemon on Each KDC
914 The final step in configuing your slave KDCs is to run the KDC daemon:
918 @b{shell%} @value{ROOTDIR}/sbin/krb5kdc
922 As with the master KDC, you will probably want to add this command to
923 the KDCs' @code{/etc/rc} or @code{/etc/inittab} files, so they will
924 start the krb5kdc daemon automatically at boot time.
926 @node Add Kerberos Principals to the Database, Limit Access to the KDCs, Finish Installing the Slave KDCs, Installing KDCs
927 @subsection Add Kerberos Principals to the Database
930 Once your KDCs are set up and running, you are ready to use
931 @code{kadmin} to load principals for your users, hosts, and other
932 services into the Kerberos database. This procedure is described fully in the
933 ``Adding or Modifying Principals'' section of the @value{PRODUCT} System
934 Administrator's Guide. (@xref{Create Host Keys for the Slave KDCs}, for a
935 brief description.) The keytab is generated by running @code{kadmin}
936 and issuing the @code{ktadd} command.
938 @node Limit Access to the KDCs, Switching Master and Slave KDCs, Add Kerberos Principals to the Database, Installing KDCs
939 @subsection Limit Access to the KDCs
941 To limit the possibility that your Kerberos database could be
942 compromised, @value{COMPANY} recommends that each KDC be a dedicated
943 host, with limited access. If your KDC is also a file server, FTP
944 server, Web server, or even just a client machine, someone who obtained
945 root access through a security hole in any of those areas could gain
946 access to the Kerberos database.
949 @value{COMPANY} recommends that your KDCs use the following
950 @code{/etc/inetd.conf} file. (Note: each line beginning with @result{}
951 is a continuation of the previous line.):
956 # Configuration file for inetd(1M). See inetd.conf(4).
958 # To re-configure the running inetd process, edit this file, then
959 # send the inetd process a SIGHUP.
961 # Syntax for socket-based Internet services:
962 # <service_name> <socket_type> <proto> <flags> <user>
963 @result{} <server_pathname> <args>
965 # Syntax for TLI-based Internet services:
967 # <service_name> tli <proto> <flags> <user> <server_pathname> <args>
969 # Ftp and telnet are standard Internet services.
971 # This machine is a secure Kerberos Key Distribution Center (KDC).
972 # Services are limited.
975 # Time service is used for clock synchronization.
977 time stream tcp nowait root internal
978 time dgram udp wait root internal
980 # Limited Kerberos services
982 krb5_prop stream tcp nowait root @value{ROOTDIR}/sbin/kpropd kpropd
983 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
984 @result{} klogind -5 -c -e
988 @node Switching Master and Slave KDCs, , Limit Access to the KDCs, Installing KDCs
989 @subsection Switching Master and Slave KDCs
991 You may occasionally want to use one of your slave KDCs as the master.
992 This might happen if you are upgrading the master KDC, or if your master
993 KDC has a disk crash.
995 Assuming you have configured all of your KDCs to be able to function as
996 either the master KDC or a slave KDC (as this document recommends), all
997 you need to do to make the changeover is:
999 If the master KDC is still running, do the following on the @emph{old}
1004 Kill the @code{kadmind} process.
1007 Disable the cron job that propagates the database.
1010 Run your database propagation script manually, to ensure that the slaves
1011 all have the latest copy of the database. (@xref{Propagate the Database
1012 to Each Slave KDC}.) If there is a need to preserve per-principal
1013 policy information from the database, you should do a ``kdb5_util dump
1014 -ov'' in order to preserve that information and propogate that dump file
1015 securely by some means to the slave so that its database has the correct
1016 state of the per-principal policy information.
1019 On the @emph{new} master KDC:
1023 Create a database keytab. (@xref{Create a kadmind Keytab}.)
1026 Start the @code{kadmind} daemon. (@xref{Start the Kerberos Daemons}.)
1029 Set up the cron job to propagate the database. (@xref{Propagate the
1030 Database to Each Slave KDC}.)
1033 Switch the CNAMEs of the old and new master KDCs. (If you don't do
1034 this, you'll need to change the @code{krb5.conf} file on every client
1035 machine in your Kerberos realm.)
1039 @node Installing and Configuring UNIX Client Machines, UNIX Application Servers, Installing KDCs, Installing Kerberos V5
1040 @section Installing and Configuring UNIX Client Machines
1042 Client machine installation is much more straightforward than
1043 installation of the KDCs.
1047 * Client Machine Configuration Files::
1050 @node Client Programs, Client Machine Configuration Files, Installing and Configuring UNIX Client Machines, Installing and Configuring UNIX Client Machines
1051 @subsection Client Programs
1053 The Kerberized client programs are @code{login.krb5}, @code{rlogin},
1054 @code{telnet}, @code{ftp}, @code{rcp}, @code{rsh}, @code{kinit},
1055 @code{klist}, @code{kdestroy}, @code{kpasswd}, @code{ksu}, and
1056 @code{krb524init}. All of these programs are in the directory
1057 @code{@value{ROOTDIR}/bin}, except for @code{login.krb5} which is in
1058 @code{@value{ROOTDIR}/sbin}.
1060 You will probably want to have your users put @code{@value{ROOTDIR}/bin}
1061 ahead of @code{/bin} and @code{/usr/bin} in their paths, so they will by
1062 default get the @value{PRODUCT} versions of @code{rlogin},
1063 @code{telnet}, @code{ftp}, @code{rcp}, and @code{rsh}.
1065 @value{COMPANY} recommends that you use @code{login.krb5} in place of
1066 @code{/bin/login} to give your users a single-sign-on system. You will
1067 need to make sure your users know to use their Kerberos passwords when
1070 You will also need to educate your users to use the ticket management
1071 programs @code{kinit},
1072 @c @code{krb524init},
1073 @code{klist}, @code{kdestroy}, and to use the Kerberos programs
1075 @code{ksu}, and @code{kpasswd} in place of their non-Kerberos
1078 @code{su}, @code{passwd}, and @code{rdist}.
1080 @node Client Machine Configuration Files, , Client Programs, Installing and Configuring UNIX Client Machines
1081 @subsection Client Machine Configuration Files
1083 Each machine running Kerberos must have a @code{/etc/krb5.conf} file.
1087 Also, for most UNIX systems, you must add the appropriate Kerberos
1088 services to each client machine's @code{/etc/services} file. If you are
1089 using the default configuration for @value{PRODUCT}, you should be able
1090 to just insert the following code:
1095 # Note --- if you are using Kerberos V4 and you either:
1097 # (a) haven't converted all your master or slave KDCs to V5, or
1099 # (b) are worried about inter-realm interoperability with other KDC's
1100 # that are still using V4
1102 # you will need to switch the "kerberos" service to port 750 and create a
1103 # "kerberos-sec" service on port 88.
1105 kerberos 88/udp kdc # Kerberos V5 KDC
1106 kerberos 88/tcp kdc # Kerberos V5 KDC
1107 klogin 543/tcp # Kerberos authenticated rlogin
1108 kshell 544/tcp cmd # and remote shell
1109 kerberos-adm 749/tcp # Kerberos 5 admin/changepw
1110 kerberos-adm 749/udp # Kerberos 5 admin/changepw
1111 krb5_prop 754/tcp # Kerberos slave propagation
1112 @c kpop 1109/tcp # Pop with Kerberos
1113 eklogin 2105/tcp # Kerberos auth. & encrypted rlogin
1114 krb524 4444/tcp # Kerberos 5 to 4 ticket translator
1118 @noindent As described in the comments in the above code, if your master
1119 KDC or any of your slave KDCs is running Kerberos V4, (or if you will be
1120 authenticating to any Kerberos V4 KDCs in another realm) you will need
1121 to switch the port number for @code{kerberos} to 750 and create a
1122 @code{kerberos-sec} service (tcp and udp) on port 88, so the Kerberos
1123 V4 KDC(s) will continue to work properly.
1126 * Mac OS X Configuration::
1129 @node Mac OS X Configuration, , Client Machine Configuration Files, Client Machine Configuration Files
1130 @subsubsection Mac OS X Configuration
1132 To install Kerberos V5 on Mac OS X and Mac OS X Server, follow the
1133 directions for generic Unix-based OS's, except for the
1134 @code{/etc/services} updates described above.
1136 Mac OS X and Mac OS X Server use a database called NetInfo to store
1137 the contents of files normally found in @code{/etc}. Instead of
1138 modifying @code{/etc/services}, you should run the following commands
1139 to add the Kerberos service entries to NetInfo:
1143 $ niutil -create . /services/kerberos
1144 $ niutil -createprop . /services/kerberos name kerberos kdc
1145 $ niutil -createprop . /services/kerberos port 750
1146 $ niutil -createprop . /services/kerberos protocol tcp udp
1147 $ niutil -create . /services/krbupdate
1148 $ niutil -createprop . /services/krbupdate name krbupdate kreg
1149 $ niutil -createprop . /services/krbupdate port 760
1150 $ niutil -createprop . /services/krbupdate protocol tcp
1151 $ niutil -create . /services/kpasswd
1152 $ niutil -createprop . /services/kpasswd name kpasswd kpwd
1153 $ niutil -createprop . /services/kpasswd port 761
1154 $ niutil -createprop . /services/kpasswd protocol tcp
1155 $ niutil -create . /services/klogin
1156 $ niutil -createprop . /services/klogin port 543
1157 $ niutil -createprop . /services/klogin protocol tcp
1158 $ niutil -create . /services/eklogin
1159 $ niutil -createprop . /services/eklogin port 2105
1160 $ niutil -createprop . /services/eklogin protocol tcp
1161 $ niutil -create . /services/kshell
1162 $ niutil -createprop . /services/kshell name kshell krcmd
1163 $ niutil -createprop . /services/kshell port 544
1164 $ niutil -createprop . /services/kshell protocol tcp
1168 In addition to adding services to NetInfo, you must also modify the
1169 resolver configuration in NetInfo so that the machine resolves its own
1170 hostname as a FQDN (fully qualified domain name). By default, Mac OS X
1171 and Mac OS X Server machines query NetInfo to resolve hostnames before
1172 falling back to DNS. Because NetInfo has an unqualified name for all
1173 the machines in the NetInfo database, the machine's own hostname will
1174 resolve to an unqualified name. Kerberos needs a FQDN to look up keys
1175 in the machine's keytab file.
1177 Fortunately, you can change the @code{lookupd} caching order to query
1178 DNS first. Run the following NetInfo commands and reboot the machine:
1182 $ niutil -create . /locations/lookupd/hosts
1183 $ niutil -createprop . /locations/lookupd/hosts LookupOrder CacheAgent DNSAgent
1188 Once you have rebooted, you can verify that the resolver now behaves
1189 correctly. Compile the Kerberos 5 distribution and run:
1193 $ cd .../src/tests/resolve
1198 This will tell you whether or not your machine returns FQDNs on name
1199 lookups. If the test still fails, you can also try turning off DNS
1200 caching. Run the following commands and reboot:
1204 $ niutil -create . /locations/lookupd/hosts
1205 $ niutil -createprop . /locations/lookupd/hosts LookupOrder DNSAgent
1206 CacheAgent NIAgent NILAgent
1210 The remainder of the setup of a Mac OS X client machine or application
1211 server should be the same as for other UNIX-based systems.
1213 @node UNIX Application Servers, , Installing and Configuring UNIX Client Machines, Installing Kerberos V5
1214 @section UNIX Application Servers
1216 An application server is a host that provides one or more services over
1217 the network. Application servers can be ``secure'' or ``insecure.'' A
1218 ``secure'' host is set up to require authentication from every client
1219 connecting to it. An ``insecure'' host will still provide Kerberos
1220 authentication, but will also allow unauthenticated clients to connect.
1222 If you have @value{PRODUCT} installed on all of your client machines,
1223 @value{COMPANY} recommends that you make your hosts secure, to take
1224 advantage of the security that Kerberos authentication affords.
1225 However, if you have some clients that do not have @value{PRODUCT}
1226 installed, you can run an insecure server, and still take advantage of
1227 @value{PRODUCT}'s single sign-on on capability.
1231 * Server Configuration Files::
1233 * Some Advice about Secure Hosts::
1236 @node Server Programs, Server Configuration Files, UNIX Application Servers, UNIX Application Servers
1237 @subsection Server Programs
1239 Just as @value{PRODUCT} provided its own Kerberos-enhanced versions of
1240 client UNIX network programs, @value{PRODUCT} also provides
1241 Kerberos-enhanced versions of server UNIX network daemons. These are
1242 @code{ftpd}, @code{klogind}, @code{kshd}, and @code{telnetd}.
1244 These programs are installed in the directory
1245 @code{@value{ROOTDIR}/sbin}. You may want to add this directory to
1248 @node Server Configuration Files, The Keytab File, Server Programs, UNIX Application Servers
1249 @subsection Server Configuration Files
1251 For a @emph{secure} server, make the following changes to
1252 @code{/etc/inetd.conf}:
1254 Find and comment out any lines for the services @code{ftp},
1255 @code{telnet}, @code{shell}, @code{login}, and @code{exec}.
1258 Add the following lines. (Note: each line beginning with @result{} is
1259 a continuation of the previous line.)
1263 klogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1264 @result{} klogind -k -c
1265 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1266 @result{} klogind -k -c -e
1267 kshell stream tcp nowait root @value{ROOTDIR}/sbin/kshd
1268 @result{} kshd -k -c -A
1269 ftp stream tcp nowait root @value{ROOTDIR}/sbin/ftpd
1271 telnet stream tcp nowait root @value{ROOTDIR}/sbin/telnetd
1272 @result{} telnetd -a valid
1276 For an @emph{insecure} server, make the following changes instead to
1277 @code{/etc/inetd.conf}:
1280 Find and comment out any lines for the services @code{ftp} and
1283 Add the following lines. (Note: each line beginning with @result{} is
1284 a continuation of the previous line.)
1287 klogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1288 @result{} klogind -k -c
1289 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1290 @result{} klogind -k -c -e
1291 kshell stream tcp nowait root @value{ROOTDIR}/sbin/kshd
1292 @result{} kshd -k -c -A
1293 ftp stream tcp nowait root @value{ROOTDIR}/sbin/ftpd
1295 telnet stream tcp nowait root @value{ROOTDIR}/sbin/telnetd
1296 @result{} telnetd -a none
1300 @node The Keytab File, Some Advice about Secure Hosts, Server Configuration Files, UNIX Application Servers
1301 @subsection The Keytab File
1303 All Kerberos server machines need a @dfn{keytab} file, called
1304 @code{/etc/krb5.keytab}, to authenticate to the KDC. The keytab file is
1305 an encrypted, local, on-disk copy of the host's key. The keytab file,
1306 like the stash file (@ref{Create the Database}) is a potential
1307 point-of-entry for a break-in, and if compromised, would allow
1308 unrestricted access to its host. The keytab file should be readable
1309 only by root, and should exist only on the machine's local disk. The
1310 file should not be part of any backup of the machine, unless access to
1311 the backup data is secured as tightly as access to the machine's root
1314 In order to generate a keytab for a host, the host must have a principal
1315 in the Kerberos database. The procedure for adding hosts to the
1316 database is described fully in the ``Adding or Modifying Principals''
1317 section of the @cite{@value{PRODUCT} System Administrator's Guide}.
1318 @xref{Create Host Keys for the Slave KDCs}. for a brief description.)
1319 The keytab is generated by running @code{kadmin} and issuing the
1320 @code{ktadd} command.
1323 For example, to generate a keytab file to allow the host
1324 trillium.@value{PRIMARYDOMAIN} to authenticate for the services
1325 @code{host}, @code{ftp}, and @code{pop}, the administrator
1326 @code{@value{ADMINUSER}} would issue the command (on
1327 trillium.@value{PRIMARYDOMAIN}):
1331 @b{trillium%} @value{ROOTDIR}/sbin/kadmin
1332 @b{kadmin5:} ktadd host/trillium.@value{PRIMARYDOMAIN} ftp/trillium.@value{PRIMARYDOMAIN}
1333 @result{} pop/trillium.@value{PRIMARYDOMAIN}
1334 @b{kadmin: Entry for principal host/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
1335 kvno 3, encryption type DES-CBC-CRC added to keytab
1336 WRFILE:/etc/krb5.keytab.
1337 kadmin: Entry for principal ftp/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
1338 kvno 3, encryption type DES-CBC-CRC added to keytab
1339 WRFILE:/etc/krb5.keytab.
1340 kadmin: Entry for principal pop/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
1341 kvno 3, encryption type DES-CBC-CRC added to keytab
1342 WRFILE:/etc/krb5.keytab.
1348 If you generate the keytab file on another host, you need to get a copy
1349 of the keytab file onto the destination host (@code{trillium}, in the
1350 above example) without sending it unencrypted over the network. If you
1351 have installed the @value{PRODUCT} client programs, you can use
1352 encrypted @code{rcp}.
1354 @node Some Advice about Secure Hosts, , The Keytab File, UNIX Application Servers
1355 @subsection Some Advice about Secure Hosts
1357 @value{PRODUCT} can protect your host from certain types of break-ins,
1358 but it is possible to install @value{PRODUCT} and still leave your host
1359 vulnerable to attack. Obviously an installation guide is not the place
1360 to try to include an exhaustive list of countermeasures for every
1361 possible attack, but it is worth noting some of the larger holes and how
1364 As stated earlier in this section, @value{COMPANY} recommends that on a
1365 secure host, you disable the standard @code{ftp}, @code{login},
1366 @code{telnet}, @code{shell}, and @code{exec} services in
1367 @code{/etc/inetd.conf}. We also recommend that secure hosts have an empty
1368 @code{/etc/hosts.equiv} file and that there not be a @code{.rhosts} file
1369 in @code{root}'s home directory. You can grant Kerberos-authenticated
1370 root access to specific Kerberos principals by placing those principals
1371 in the file @code{.k5login} in root's home directory.
1373 We recommend that backups of secure machines exclude the keytab file
1374 (@code{/etc/krb5.keytab}). If this is not possible, the backups should
1375 at least be done locally, rather than over a network, and the backup
1376 tapes should be physically secured.
1378 Finally, the keytab file and any programs run by root, including the
1379 @value{PRODUCT} binaries, should be kept on local disk. The keytab file
1380 should be readable only by root.
1382 @node Upgrading Existing Kerberos V5 Installations, Bug Reports for Kerberos V5, Installing Kerberos V5, Top
1383 @chapter Upgrading Existing @value{PRODUCT} Installations
1385 If you already have an existing Kerberos database that you created with
1386 a prior release of Kerberos 5, you can upgrade it to work with the
1387 current release with the @code{kdb5_util} command. It is only necessary
1388 to perform this dump/undump procedure if you were running a krb5-1.0.x
1389 KDC and are migrating to a krb5-1.1.x or newer KDC. The process for
1390 upgrading a Master KDC involves the following steps:
1394 @item Stop your current KDC and administration
1395 server processes, if any.
1397 @item Dump your existing Kerberos database to an ASCII file with
1398 @code{kdb5_util}'s ``dump'' command:
1402 @b{shell%} cd @value{ROOTDIR}/var/krb5kdc
1403 @b{shell%} kdb5_util dump old-kdb-dump
1404 @b{shell%} kdb5_util dump -ov old-kdb-dump.ov
1409 @item Create a new Master KDC installation (@xref{Install the Master
1410 KDC}.). If you have a stash file for your current database, choose any
1411 new master password but then copy your existing stash file to the
1412 location specified by your kdc.conf; if you do not have a stash file for
1413 your current database, you must choose the same master password.
1415 @item Load your old Kerberos database into the new system with
1416 @code{kdb5_util}'s ``load'' command:
1420 @b{shell%} cd @value{ROOTDIR}/var/krb5kdc
1421 @b{shell%} kdb5_util load old-kdb-dump
1422 @b{shell%} kdb5_util load -update old-kdb-dump.ov
1429 The ``dump -ov'' and ``load -update'' commands are necessary in order to
1430 preserve per-principal policy information, since the default dump format
1431 filters out that information. If you omit those steps, the loaded
1432 database database will lose the policy information for each principal
1435 To update a Slave KDC, you must stop the old server processes on the
1436 Slave KDC, install the new server binaries, reload the most recent slave
1437 dump file, and re-start the server processes.
1440 * Upgrading to Triple-DES Encryption Keys::
1443 @node Upgrading to Triple-DES Encryption Keys, , Upgrading Existing Kerberos V5 Installations, Upgrading Existing Kerberos V5 Installations
1444 @section Upgrading to Triple-DES Encryption Keys
1446 Beginning with the 1.2 release from MIT, Kerberos includes a stronger
1447 encryption algorithm called ``triple DES'' -- essentially, three
1448 applications of the basic DES encryption algorithm, greatly increasing
1449 the resistance to a brute-force search for the key by an attacker. This
1450 algorithm is more secure, but encryption is much slower. We expect to
1451 add other, faster encryption algorithms at some point in the future.
1453 Release 1.1 had some support for triple-DES service keys, but with
1454 release 1.2 we have added support for user keys and session keys as
1455 well. Release 1.0 had very little support for multiple cryptosystems,
1456 and some of that software may not function properly in an environment
1457 using triple-DES as well as plain DES.
1459 Because of the way the MIT Kerberos database is structured, the KDC will
1460 assume that a service supports only those encryption types for which
1461 keys are found in the database. Thus, if a service has only a
1462 single-DES key in the database, the KDC will not issue tickets for that
1463 service that use triple-DES session keys; it will instead issue only
1464 single-DES session keys, even if other services are already capable of
1465 using triple-DES. So if you make sure your application server software
1466 is updated before adding a triple-DES key for the service, clients
1467 should be able to talk to services at all times during the updating
1470 Normally, the listed @code{supported_enctypes} in @code{kdc.conf} are
1471 all used when a new key is generated. You can control this with
1472 command-line flags to @code{kadmin} and @code{kadmin.local}. You may
1473 want to exclude triple-DES by default until you have updated a lot of
1474 your application servers, and then change the default to include
1475 triple-DES. We recommend that you always include @code{des-cbc-crc} in
1478 @node Bug Reports for Kerberos V5, , Upgrading Existing Kerberos V5 Installations, Top
1479 @chapter Bug Reports for @value{PRODUCT}
1481 @include send-pr.texinfo