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 Mapping hostnames onto Kerberos realms is done through a set of rules in
233 the @code{krb5.conf} configuration file. (@xref{krb5.conf}.) You can
234 specify mappings for an entire domain or subdomain, and/or on a
235 hostname-by-hostname basis. Since greater specificity takes precedence,
236 you would do this by specifying the mappings for a given domain or
237 subdomain and listing the exceptions.
239 The @value{PRODUCT} System Administrator's Guide contains a thorough
240 description of the parts of the @code{krb5.conf} file and what may be
241 specified in each. A sample @code{krb5.conf} file appears in
242 @ref{krb5.conf}. You should be able to use this file, substituting the
243 relevant information for your Kerberos instllation for the samples.
245 @node Ports for the KDC and Admin Services, Slave KDCs, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions
246 @section Ports for the KDC and Admin Services
248 The default ports used by Kerberos are port 88 for the
249 KDC@footnote{Kerberos V4 used port 750. If necessary, you can run on
250 both ports for backward compatibility.} and port 749 for the admin
251 server. You can, however, choose to run on other ports, as long as they
252 are specified in each host's @code{/etc/services} and @code{krb5.conf}
253 files, and the @code{kdc.conf} file on each KDC. For a more thorough
254 treatment of port numbers used by the @value{PRODUCT} programs, refer to
255 the ``Configuring Your Firewall to Work With @value{PRODUCT}'' section
256 of the @cite{@value{PRODUCT} System Administrator's Guide}.
258 @node Slave KDCs, Hostnames for the Master and Slave KDCs, Ports for the KDC and Admin Services, Realm Configuration Decisions
261 Slave KDCs provide an additional source of Kerberos ticket-granting
262 services in the event of inaccessibility of the master KDC. The number
263 of slave KDCs you need and the decision of where to place them, both
264 physically and logically, depends on the specifics of your network.
266 All of the Kerberos authentication on your network requires that each
267 client be able to contact a KDC. Therefore, you need to anticipate any
268 likely reason a KDC might be unavailable and have a slave KDC to take up
271 Some considerations include:
275 Have at least one slave KDC as a backup, for when the master KDC is
276 down, is being upgraded, or is otherwise unavailable.
279 If your network is split such that a network outage is likely to cause a
280 network partition (some segment or segments of the network to become cut
281 off or isolated from other segments), have a slave KDC accessible to
285 If possible, have at least one slave KDC in a different building from
286 the master, in case of power outages, fires, or other localized
292 @node Hostnames for the Master and Slave KDCs, Database Propagation, Slave KDCs, Realm Configuration Decisions
293 @section Hostnames for the Master and Slave KDCs
295 @value{COMPANY} recommends that your KDCs have a predefined set of
296 CNAMEs, such as @code{@value{KDCSERVER}} for the master KDC and
297 @code{@value{KDCSLAVE1}}, @code{@value{KDCSLAVE2}}, @dots{} for the
298 slave KDCs. This way, if you need to swap a machine, you only need to
299 change a DNS entry, rather than having to change hostnames.
301 @node Database Propagation, , Hostnames for the Master and Slave KDCs, Realm Configuration Decisions
302 @section Database Propagation
304 The Kerberos database resides on the master KDC, and must be propagated
305 regularly (usually by a cron job) to the slave KDCs. In deciding how
306 frequently the propagation should happen, you will need to balance the
307 amount of time the propagation takes against the maximum reasonable
308 amount of time a user should have to wait for a password change to take
311 If the propagation time is longer than this maximum reasonable time
312 (@i{e.g.,} you have a particularly large database, you have a lot of
313 slaves, or you experience frequent network delays), you may wish to
314 cut down on your propagation delay by performing the propagation in
315 parallel. To do this, have the master KDC propagate the database to one
316 set of slaves, and then have each of these slaves propagate the database
317 to additional slaves.
319 @node Building Kerberos V5, Installing Kerberos V5, Realm Configuration Decisions, Top
320 @chapter Building @value{PRODUCT}
322 @include build.texinfo
324 @node Installing Kerberos V5, Upgrading Existing Kerberos V5 Installations, Building Kerberos V5, Top
325 @chapter Installing @value{PRODUCT}
327 The sections of this chapter describe procedures for installing
338 UNIX Application Servers
343 * Installing and Configuring UNIX Client Machines::
344 * UNIX Application Servers::
347 @node Installing KDCs, Installing and Configuring UNIX Client Machines, Installing Kerberos V5, Installing Kerberos V5
348 @section Installing KDCs
350 The Key Distribution Centers (KDCs) issue Kerberos tickets. Each KDC
351 contains a copy of the Kerberos database. The master KDC contains the
352 master copy of the database, which it propagates to the slave KDCs at
353 regular intervals. All database changes (such as password changes) are
354 made on the master KDC.
356 Slave KDCs provide Kerberos ticket-granting services, but not database
357 administration. This allows clients to continue to obtain tickets when
358 the master KDC is unavailable.
360 @value{COMPANY} recommends that you install all of your KDCs to be able
361 to function as either the master or one of the slaves. This will enable
362 you to easily switch your master KDC with one of the slaves if
363 necessary. (@xref{Switching Master and Slave KDCs}.) This installation
364 procedure is based on that recommendation.
367 * Install the Master KDC::
368 * Install the Slave KDCs::
369 * Back on the Master KDC::
370 * Finish Installing the Slave KDCs::
371 * Add Kerberos Principals to the Database::
372 * Limit Access to the KDCs::
373 * Switching Master and Slave KDCs::
376 @node Install the Master KDC, Install the Slave KDCs, Installing KDCs, Installing KDCs
377 @subsection Install the Master KDC
379 This installation procedure will require you to go back and forth a
380 couple of times between the master KDC and each of the slave KDCs. The
381 first few steps must be done on the master KDC.
384 * Edit the Configuration Files::
385 * Create the Database::
386 * Add Administrators to the Acl File::
387 * Add Administrators to the Kerberos Database::
388 * Create a kadmind Keytab::
389 * Start the Kerberos Daemons::
392 @node Edit the Configuration Files, Create the Database, Install the Master KDC, Install the Master KDC
393 @subsubsection Edit the Configuration Files
395 Modify the configuration files, @code{/etc/krb5.conf}
396 (@pxref{krb5.conf}) and @code{@value{ROOTDIR}/var/krb5kdc/kdc.conf}
397 (@pxref{kdc.conf}) to reflect the correct information (such as the
398 hostnames and realm name) for your realm. @value{COMPANY} recommends
399 that you keep @code{krb5.conf} in @code{/etc}.
401 Among the settings in your @code{/etc/krb5.conf} file, be sure to create
402 a @code{[logging]} stanza so that the KDC and kadmind will generate
403 logging output. For example:
408 kdc = FILE:/var/log/krb5kdc.log
409 admin_server = FILE:/var/log/kadmin.log
410 default = FILE:/var/log/krb5lib.log
414 @node Create the Database, Add Administrators to the Acl File, Edit the Configuration Files, Install the Master KDC
415 @subsubsection Create the Database
417 You will use the @code{kdb5_util} command @emph{on the Master KDC} to
418 create the Kerberos database and the optional stash file. The
419 @dfn{stash file} is a local copy of the master key that resides in
420 encrypted form on the KDC's local disk. The stash file is used to
421 authenticate the KDC to itself automatically before starting the
422 @code{kadmind} and @code{krb5kdc} daemons (@i{e.g.,} as part of the
423 machine's boot sequence). The stash file, like the keytab file
424 (@xref{The Keytab File}) is a potential point-of-entry for a break-in,
425 and if compromised, would allow unrestricted access to the Kerberos
426 database. If you choose to install a stash file, it should be readable
427 only by root, and should exist only on the KDC's local disk. The file
428 should not be part of any backup of the machine, unless access to the
429 backup data is secured as tightly as access to the master password
432 Note that @code{kdb5_util} will prompt you for the master key for the
433 Kerberos database. This key can be any string. A good key is one you
434 can remember, but that no one else can guess. Examples of bad keys are
435 words that can be found in a dictionary, any common or popular name,
436 especially a famous person (or cartoon character), your username in any
437 form (@i{e.g.}, forward, backward, repeated twice, @i{etc.}), and any of
438 the sample keys that appear in this manual. One example of a key which
439 might be good if it did not appear in this manual is ``MITiys4K5!'',
440 which represents the sentence ``MIT is your source for Kerberos 5!''
441 (It's the first letter of each word, substituting the numeral ``4'' for
442 the word ``for'', and includes the punctuation mark at the end.)
444 The following is an example of how to create a Kerberos database and
445 stash file on the master KDC, using the @code{kdb5_util} command. (The
446 line that begins with @result{} is a continuation of the previous line.)
447 Replace @i{@value{PRIMARYREALM}} with the name of your Kerberos realm.
451 @b{shell%} @value{ROOTDIR}/sbin/kdb5_util create -r @value{PRIMARYREALM} -s
452 @b{Initializing database '@value{ROOTDIR}/var/krb5kdc/principal' for
453 @result{} realm '@value{PRIMARYREALM}',
454 master key name 'K/M@@@value{PRIMARYREALM}'
455 You will be prompted for the database Master Password.
456 It is important that you NOT FORGET this password.}
458 @b{Enter KDC database master key:} @i{@doubleleftarrow{} Type the master password.}
459 @b{Re-enter KDC database master key to verify:} @i{@doubleleftarrow{} Type it again.}
462 @b{Enter KDC database master key:} @i{<= Type the master password.}
463 @b{Re-enter KDC database master key to verify:} @i{<= Type it again.}
469 This will create five files in the directory specified in your
470 @code{kdc.conf} file: two Kerberos database files, @code{principal.db},
471 and @code{principal.ok}; the Kerberos administrative database file,
472 @code{principal.kadm5}; the administrative database lock file,
473 @code{principal.kadm5.lock}; and the stash file, @code{.k5stash}. (The
474 default directory is @code{@value{ROOTDIR}/var/krb5kdc}.) If you do not
475 want a stash file, run the above command without the @code{-s} option.
477 @node Add Administrators to the Acl File, Add Administrators to the Kerberos Database, Create the Database, Install the Master KDC
478 @subsubsection Add Administrators to the Acl File
480 Next, you need create an Access Control List (acl) file, and put the
481 Kerberos principal of at least one of the administrators into it. The
482 filename should match the value you have set for ``acl_file'' in your
483 @code{kdc.conf} file. The default file name is @samp{kadm5.acl}. The
484 format of the file is:
487 Kerberos principal permissions optional target principal
490 The Kerberos principal (and optional target principal) can include the
491 ``@b{*}'' wildcard, so if you want any principal with the instance
492 ``admin'' to have full permissions on the database, you could use the
493 principal ``@code{*/admin@@REALM}'' where ``REALM'' is your Kerberos
496 Note: a common use of an @i{admin} instance is so you can grant
497 separate permissions (such as administrator access to the Kerberos
498 database) to a separate Kerberos principal. For example, the user
499 @code{@value{ADMINUSER}} might have a principal for his administrative
500 use, called @code{@value{ADMINUSER}/admin}. This way,
501 @code{@value{ADMINUSER}} would obtain @code{@value{ADMINUSER}/admin}
502 tickets only when he actually needs to use those permissions. Refer to
503 the @value{PRODUCT} Administrator's Guide or the @value{PRODUCT} User's
504 Guide for more detailed explanations of @dfn{principals} and
507 The permissions (acls) recognized in the acl file
512 allows the addition of principals or policies in the database.
514 prohibits the addition of principals or policies in the database.
516 allows the deletion of principals or policies in the database.
518 prohibits the deletion of principals or policies in the database.
520 allows the modification of principals or policies in the database.
522 prohibits the modification of principals or policies in the database.
524 allows the changing of passwords for principals in the database.
526 prohibits the changing of passwords for principals in the database.
528 allows inquiries to the database.
530 prohibits inquiries to the database.
532 allows the listing of principals or policies in the database.
534 prohibits the listing of principals or policies in the database.
536 Short for all privileges (admcil).
538 Short for all privileges (admcil); identical to ``*''.
541 To give the principal @code{*/admin@@@value{PRIMARYREALM}} permission to
542 change all of the database permissions on any principal permissions, you
543 would place the following line in the file:
546 */admin@@@value{PRIMARYREALM} *
549 To give the principal @code{@value{ADMINUSER}@@@value{PRIMARYREALM}}
550 permission to add, list, and inquire about any principal that has the
551 instance ``root'', you would add the following line to the acl file:
554 @value{ADMINUSER}@@@value{PRIMARYREALM} ali */root@@@value{PRIMARYREALM}
557 @node Add Administrators to the Kerberos Database, Create a kadmind Keytab, Add Administrators to the Acl File, Install the Master KDC
558 @subsubsection Add Administrators to the Kerberos Database
560 Next you need to add administrative principals to the Kerberos database.
561 (You must add at least one now.) To do this, use @code{kadmin.local}
562 @emph{on the master KDC}. The administrative principals you create
563 should be the ones you added to the ACL file (see @xref{Add
564 Administrators to the Acl File}). In the following example, the
565 administration principal @code{admin/admin} is created:
569 @b{shell%} @value{ROOTDIR}/sbin/kadmin.local
570 @b{kadmin.local:} addprinc admin/admin@@@value{PRIMARYREALM}
571 @b{WARNING: no policy specified for "admin/admin@@@value{PRIMARYREALM}";
572 defaulting to no policy.}
574 @b{Enter password for principal admin/admin@@@value{PRIMARYREALM}:} @i{@doubleleftarrow{} Enter a password.}
575 Re-enter password for principal admin/admin@@@value{PRIMARYREALM}: @i{@doubleleftarrow{} Type it again.}
578 @b{Enter password for principal admin/admin@@@value{PRIMARYREALM}:} @i{<= Enter a password.}
579 Re-enter password for principal admin/admin@@@value{PRIMARYREALM}: @i{<= Type it again.}
581 @b{Principal "admin/admin@@@value{PRIMARYREALM}" created.
588 @node Create a kadmind Keytab, Start the Kerberos Daemons, Add Administrators to the Kerberos Database, Install the Master KDC
589 @subsubsection Create a kadmind Keytab
591 The kadmind keytab is the key that kadmind will use to decrypt
592 administrators' Kerberos tickets to determine whether or not it should
593 give them access to the database. You need to create the kadmin keytab
594 with entries for the principals @code{kadmin/admin} and
595 @code{kadmin/changepw}. (These principals are placed in the Kerberos
596 database automatically when you create it.) To create the kadmin
597 keytab, run @code{kadmin.local} and use the @code{ktadd} command, as in
598 the following example. (The line beginning with @result{} is a
599 continuation of the previous line.):
603 @b{shell%} @value{ROOTDIR}/sbin/kadmin.local
604 @b{kadmin.local:} ktadd -k @value{ROOTDIR}/var/krb5kdc/kadm5.keytab
605 @result{} kadmin/admin kadmin/changepw
606 @b{Entry for principal kadmin/admin@@@value{PRIMARYREALM} with
607 kvno 3, encryption type DES-CBC-CRC added to keytab
608 WRFILE:@value{ROOTDIR}/var/krb5kdc/kadm5.keytab.
609 Entry for principal kadmin/changepw@@@value{PRIMARYREALM} with
610 kvno 3, encryption type DES-CBC-CRC added to keytab
611 WRFILE:@value{ROOTDIR}/var/krb5kdc/kadm5.keytab.
618 As specified in the @samp{-k} argument, @code{ktadd} will save the
619 extracted keytab as @* @code{@value{ROOTDIR}/var/krb5kdc/kadm5.keytab}.
620 The filename you use must be the one specified in your @code{kdc.conf}
624 @node Start the Kerberos Daemons, , Create a kadmind Keytab, Install the Master KDC
625 @subsubsection Start the Kerberos Daemons on the Master KDC
627 At this point, you are ready to start the Kerberos daemons on the Master
631 @b{shell%} @value{ROOTDIR}/sbin/krb5kdc
632 @b{shell%} @value{ROOTDIR}/sbin/kadmind
636 Each daemon will fork and run in the background. Assuming you want
637 these daemons to start up automatically at boot time, you can add them
638 to the KDC's @code{/etc/rc} or @code{/etc/inittab} file. You need to
639 have a stash file in order to do this.
641 You can verify that they started properly by checking for their startup
642 messages in the logging locations you defined in @code{/etc/krb5.conf}
643 (see @xref{Edit the Configuration Files}). For example:
646 @b{shell%} tail /var/log/krb5kdc.log
647 Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
648 @b{shell%} tail /var/log/kadmin.log
649 Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting
652 Any errors the daemons encounter while starting will also be listed in
656 @node Install the Slave KDCs, Back on the Master KDC, Install the Master KDC, Installing KDCs
657 @subsection Install the Slave KDCs
659 You are now ready to start configuring the slave KDCs. Assuming you are
660 setting the KDCs up so that you can easily switch the master KDC with
661 one of the slaves, you should perform each of these steps on the master
662 KDC as well as the slave KDCs, unless these instructions specify
667 * Create Host Keys for the Slave KDCs::
668 * Extract Host Keytabs for the KDCs::
669 * Set Up the Slave KDCs for Database Propagation::
672 @node Create Host Keys for the Slave KDCs, Extract Host Keytabs for the KDCs, Install the Slave KDCs, Install the Slave KDCs
673 @subsubsection Create Host Keys for the Slave KDCs
675 Each KDC needs a host principal in the Kerberos database. You can enter
676 these from any host, once the @code{kadmind} daemon is running. For
677 example, if your master KDC were called
678 @value{KDCSERVER}.@value{PRIMARYDOMAIN}, and you had two KDC slaves
679 named @value{KDCSLAVE1}.@value{PRIMARYDOMAIN} and
680 @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}, you would type the following:
684 @b{shell%} @value{ROOTDIR}/sbin/kadmin
685 @b{kadmin:} addprinc -randkey host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}
686 @b{WARNING: no policy specified for "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
687 defaulting to no policy.
688 Principal "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.
689 kadmin:} addprinc -randkey host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}
690 @b{WARNING: no policy specified for "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
691 defaulting to no policy.
692 Principal "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.}
693 @b{kadmin:} addprinc -randkey host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}
694 @b{WARNING: no policy specified for "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
695 defaulting to no policy.
696 Principal "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.
702 It is not actually necessary to have the master KDC server in the
703 Kerberos database, but it can be handy if:
707 anyone will be logging into the machine as something other than root
710 you want to be able to swap the master KDC with one of the slaves if
714 @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
715 @subsubsection Extract Host Keytabs for the KDCs
717 Each KDC (including the master) needs a keytab to decrypt tickets.
718 Ideally, you should extract each keytab locally on its own KDC. If this
719 is not feasible, you should use an encrypted session to send them across
720 the network. To extract a keytab on a KDC called
721 @value{KDCSERVER}.@value{PRIMARYDOMAIN}, you would execute the following
726 @b{kadmin:} ktadd host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}
727 @b{kadmin: Entry for principal host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
728 kvno 1, encryption type DES-CBC-CRC added to keytab
729 WRFILE:/etc/krb5.keytab.
735 Note that the principal must exist in the Kerberos database in order to
738 @node Set Up the Slave KDCs for Database Propagation, , Extract Host Keytabs for the KDCs, Install the Slave KDCs
739 @subsubsection Set Up the Slave KDCs for Database Propagation
741 The database is propagated from the master KDC to the slave KDCs via the
742 @code{kpropd} daemon. To set up propagation, create a file on each KDC,
743 named @code{@value{ROOTDIR}/var/krb5kdc/kpropd.acl}, containing the
744 principals for each of the KDCs.
746 For example, if the master KDC were
747 @code{@value{KDCSERVER}.@value{PRIMARYDOMAIN}}, the slave KDCs were
748 @code{@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}} and
749 @code{@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}}, and the realm were
750 @code{@value{PRIMARYREALM}}, then the file's contents would be:
754 host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
755 host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
756 host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
761 Then, add the following lines to @code{/etc/inetd.conf} file on each KDC
762 (the line beginnng with @result{} is a continuation of the previous
767 krb5_prop stream tcp nowait root @value{ROOTDIR}/sbin/kpropd kpropd
768 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
769 @result{} klogind -k -c -e
774 The first line sets up the @code{kpropd} database propagation daemon.
775 The second line sets up the @code{eklogin} daemon, allowing
776 Kerberos-authenticated, encrypted rlogin to the KDC.
778 You also need to add the following lines to @code{/etc/services} on each
783 kerberos 88/udp kdc # Kerberos authentication (udp)
784 kerberos 88/tcp kdc # Kerberos authentication (tcp)
785 krb5_prop 754/tcp # Kerberos slave propagation
786 kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp)
787 kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp)
788 eklogin 2105/tcp # Kerberos encrypted rlogin
792 @node Back on the Master KDC, Finish Installing the Slave KDCs, Install the Slave KDCs, Installing KDCs
793 @subsection Back on the Master KDC
795 Now that the slave KDCs are able to accept database propagation, you'll
796 need to propagate the database to each of them.
799 * Propagate the Database to Each Slave KDC::
802 @node Propagate the Database to Each Slave KDC, , Back on the Master KDC, Back on the Master KDC
803 @subsubsection Propagate the Database to Each Slave KDC
805 First, create a dump of the database on the master KDC, as follows:
809 @b{shell%} @value{ROOTDIR}/sbin/kdb5_util dump @value{ROOTDIR}/var/krb5kdc/slave_datatrans
814 Next, you need to manually propagate the database to each slave KDC, as
815 in the following example. (The lines beginning with @result{} are
816 continuations of the previous line.):
820 @value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans
821 @result{} @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}
822 @value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans
823 @result{} @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}
827 You will need a script to dump and propagate the database. The
828 following is an example of a bourne shell script that will do this.
829 (Note that the line that begins with @result{} is a continuation of the
830 previous line. Remember that you need to replace @value{ROOTDIR} with
831 the name of the directory in which you installed @value{PRODUCT}.)
837 kdclist = "@value{KDCSLAVE1}.@value{PRIMARYDOMAIN} @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}"
839 @value{ROOTDIR}/sbin/kdb5_util -R "dump
840 @result{} @value{ROOTDIR}/var/krb5kdc/slave_datatrans"
844 @value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans $kdc
850 You will need to set up a cron job to run this script at the intervals
851 you decided on earlier (@xref{Database Propagation}.)
853 @node Finish Installing the Slave KDCs, Add Kerberos Principals to the Database, Back on the Master KDC, Installing KDCs
854 @subsection Finish Installing the Slave KDCs
856 Now that the slave KDCs have copies of the Kerberos database, you can
857 create stash files for them and start the @code{krb5kdc} daemon.
860 * Create Stash Files on the Slave KDCs::
861 * Start the krb5kdc Daemon on Each KDC::
864 @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
865 @subsubsection Create Stash Files on the Slave KDCs
867 Create stash files, by issuing the following commands on each slave KDC:
871 @b{shell%} kdb5_util stash
872 @b{kdb5_util: Cannot find/read stored master key while reading master key
873 kdb5_util: Warning: proceeding without master key}
875 @b{Enter KDC database master key:} @i{@doubleleftarrow{} Enter the database master key.}
878 @b{Enter KDC database master key:} @i{<= Enter the database master key.}
884 As mentioned above, the stash file is necessary for your KDCs to be able
885 authenticate to themselves, such as when they reboot. You could run
886 your KDCs without stash files, but you would then need to type in the
887 Kerberos database master key by hand every time you start a KDC daemon.
889 @node Start the krb5kdc Daemon on Each KDC, , Create Stash Files on the Slave KDCs, Finish Installing the Slave KDCs
890 @subsubsection Start the krb5kdc Daemon on Each KDC
892 The final step in configuing your slave KDCs is to run the KDC daemon:
896 @b{shell%} @value{ROOTDIR}/sbin/krb5kdc
900 As with the master KDC, you will probably want to add this command to
901 the KDCs' @code{/etc/rc} or @code{/etc/inittab} files, so they will
902 start the krb5kdc daemon automatically at boot time.
904 @node Add Kerberos Principals to the Database, Limit Access to the KDCs, Finish Installing the Slave KDCs, Installing KDCs
905 @subsection Add Kerberos Principals to the Database
908 Once your KDCs are set up and running, you are ready to use
909 @code{kadmin} to load principals for your users, hosts, and other
910 services into the Kerberos database. This procedure is described fully in the
911 ``Adding or Modifying Principals'' section of the @value{PRODUCT} System
912 Administrator's Guide. (@xref{Create Host Keys for the Slave KDCs} for a
913 brief description.) The keytab is generated by running @code{kadmin}
914 and issuing the @code{ktadd} command.
916 @node Limit Access to the KDCs, Switching Master and Slave KDCs, Add Kerberos Principals to the Database, Installing KDCs
917 @subsection Limit Access to the KDCs
919 To limit the possibility that your Kerberos database could be
920 compromised, @value{COMPANY} recommends that each KDC be a dedicated
921 host, with limited access. If your KDC is also a file server, FTP
922 server, Web server, or even just a client machine, someone who obtained
923 root access through a security hole in any of those areas could gain
924 access to the Kerberos database.
927 @value{COMPANY} recommends that your KDCs use the following
928 @code{/etc/inetd.conf} file. (Note: each line beginning with @result{}
929 is a continuation of the previous line.):
934 # Configuration file for inetd(1M). See inetd.conf(4).
936 # To re-configure the running inetd process, edit this file, then
937 # send the inetd process a SIGHUP.
939 # Syntax for socket-based Internet services:
940 # <service_name> <socket_type> <proto> <flags> <user>
941 @result{} <server_pathname> <args>
943 # Syntax for TLI-based Internet services:
945 # <service_name> tli <proto> <flags> <user> <server_pathname> <args>
947 # Ftp and telnet are standard Internet services.
949 # This machine is a secure Kerberos Key Distribution Center (KDC).
950 # Services are limited.
953 # Time service is used for clock synchronization.
955 time stream tcp nowait root internal
956 time dgram udp wait root internal
958 # Limited Kerberos services
960 krb5_prop stream tcp nowait root @value{ROOTDIR}/sbin/kpropd kpropd
961 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
962 @result{} klogind -5 -c -e
966 @node Switching Master and Slave KDCs, , Limit Access to the KDCs, Installing KDCs
967 @subsection Switching Master and Slave KDCs
969 You may occasionally want to use one of your slave KDCs as the master.
970 This might happen if you are upgrading the master KDC, or if your master
971 KDC has a disk crash.
973 Assuming you have configured all of your KDCs to be able to function as
974 either the master KDC or a slave KDC (as this document recommends), all
975 you need to do to make the changeover is:
977 If the master KDC is still running, do the following on the @emph{old}
982 Kill the @code{kadmind} process.
985 Disable the cron job that propagates the database.
988 Run your database propagation script manually, to ensure that the slaves
989 all have the latest copy of the database. (@xref{Propagate the Database
993 On the @emph{new} master KDC:
997 Create a database keytab. (@xref{Create a kadmind Keytab}.)
1000 Start the @code{kadmind} daemon. (@xref{Start the Kerberos Daemons}.)
1003 Set up the cron job to propagate the database. (@xref{Propagate the
1004 Database to Each Slave KDC}.)
1007 Switch the CNAMEs of the old and new master KDCs. (If you don't do
1008 this, you'll need to change the @code{krb5.conf} file on every client
1009 machine in your Kerberos realm.)
1012 @node Installing and Configuring UNIX Client Machines, UNIX Application Servers, Installing KDCs, Installing Kerberos V5
1013 @section Installing and Configuring UNIX Client Machines
1015 Client machine installation is much more straightforward than
1016 installation of the KDCs.
1020 * Client Machine Configuration Files::
1023 @node Client Programs, Client Machine Configuration Files, Installing and Configuring UNIX Client Machines, Installing and Configuring UNIX Client Machines
1024 @subsection Client Programs
1026 The Kerberized client programs are @code{login.krb5}, @code{rlogin},
1027 @code{telnet}, @code{ftp}, @code{rcp}, @code{rsh}, @code{kinit},
1028 @code{klist}, @code{kdestroy}, @code{kpasswd}, @code{ksu}, and
1029 @code{krb524init}. All of these programs are in the directory
1030 @code{@value{ROOTDIR}/bin}, except for @code{login.krb5} which is in
1031 @code{@value{ROOTDIR}/sbin}.
1033 You will probably want to have your users put @code{@value{ROOTDIR}/bin}
1034 ahead of @code{/bin} and @code{/usr/bin} in their paths, so they will by
1035 default get the @value{PRODUCT} versions of @code{rlogin},
1036 @code{telnet}, @code{ftp}, @code{rcp}, and @code{rsh}.
1038 @value{COMPANY} recommends that you use @code{login.krb5} in place of
1039 @code{/bin/login} to give your users a single-sign-on system. You will
1040 need to make sure your users know to use their Kerberos passwords when
1043 You will also need to educate your users to use the ticket management
1044 programs @code{kinit},
1045 @c @code{krb524init},
1046 @code{klist}, @code{kdestroy}, and to use the Kerberos programs
1048 @code{ksu}, and @code{kpasswd} in place of their non-Kerberos
1051 @code{su}, @code{passwd}, and @code{rdist}.
1053 @node Client Machine Configuration Files, Mac OS X Configuration, Client Programs, Installing and Configuring UNIX Client Machines
1054 @subsection Client Machine Configuration Files
1056 Each machine running Kerberos must have a @code{/etc/krb5.conf} file.
1060 Also, for most UNIX systems, you must add the appropriate Kerberos
1061 services to each client machine's @code{/etc/services} file. If you are
1062 using the default configuration for @value{PRODUCT}, you should be able
1063 to just insert the following code:
1068 # Note --- if you are using Kerberos V4 and you either:
1070 # (a) haven't converted all your master or slave KDCs to V5, or
1072 # (b) are worried about inter-realm interoperability with other KDC's
1073 # that are still using V4
1075 # you will need to switch the "kerberos" service to port 750 and create a
1076 # "kerberos-sec" service on port 88.
1078 kerberos 88/udp kdc # Kerberos V5 KDC
1079 kerberos 88/tcp kdc # Kerberos V5 KDC
1080 klogin 543/tcp # Kerberos authenticated rlogin
1081 kshell 544/tcp cmd # and remote shell
1082 kerberos-adm 749/tcp # Kerberos 5 admin/changepw
1083 kerberos-adm 749/udp # Kerberos 5 admin/changepw
1084 krb5_prop 754/tcp # Kerberos slave propagation
1085 @c kpop 1109/tcp # Pop with Kerberos
1086 eklogin 2105/tcp # Kerberos auth. & encrypted rlogin
1087 krb524 4444/tcp # Kerberos 5 to 4 ticket translator
1091 @noindent As described in the comments in the above code, if your master
1092 KDC or any of your slave KDCs is running Kerberos V4, (or if you will be
1093 authenticating to any Kerberos V4 KDCs in another realm) you will need
1094 to switch the port number for @code{kerberos} to 750 and create a
1095 @code{kerberos-sec} service (tcp and udp) on port 88, so the Kerberos
1096 V4 KDC(s) will continue to work properly.
1099 * Mac OS X Configuration::
1102 @node Mac OS X Configuration, , Client Machine Configuration Files, Client Machine Configuration Files
1103 @subsubsection Mac OS X Configuration
1105 To install Kerberos V5 on Mac OS X and Mac OS X Server, follow the
1106 directions for generic Unix-based OS's, except for the
1107 @code{/etc/services} updates described above.
1109 Mac OS X and Mac OS X Server use a database called NetInfo to store
1110 the contents of files normally found in @code{/etc}. Instead of
1111 modifying @code{/etc/services}, you should run the following commands
1112 to add the Kerberos service entries to NetInfo:
1116 $ niutil -create . /services/kerberos
1117 $ niutil -createprop . /services/kerberos name kerberos kdc
1118 $ niutil -createprop . /services/kerberos port 750
1119 $ niutil -createprop . /services/kerberos protocol tcp udp
1120 $ niutil -create . /services/krbupdate
1121 $ niutil -createprop . /services/krbupdate name krbupdate kreg
1122 $ niutil -createprop . /services/krbupdate port 760
1123 $ niutil -createprop . /services/krbupdate protocol tcp
1124 $ niutil -create . /services/kpasswd
1125 $ niutil -createprop . /services/kpasswd name kpasswd kpwd
1126 $ niutil -createprop . /services/kpasswd port 761
1127 $ niutil -createprop . /services/kpasswd protocol tcp
1128 $ niutil -create . /services/klogin
1129 $ niutil -createprop . /services/klogin port 543
1130 $ niutil -createprop . /services/klogin protocol tcp
1131 $ niutil -create . /services/eklogin
1132 $ niutil -createprop . /services/eklogin port 2105
1133 $ niutil -createprop . /services/eklogin protocol tcp
1134 $ niutil -create . /services/kshell
1135 $ niutil -createprop . /services/kshell name kshell krcmd
1136 $ niutil -createprop . /services/kshell port 544
1137 $ niutil -createprop . /services/kshell protocol tcp
1141 In addition to adding services to NetInfo, you must also modify the
1142 resolver configuration in NetInfo so that the machine resolves its own
1143 hostname as a FQDN (fully qualified domain name). By default, Mac OS X
1144 and Mac OS X Server machines query NetInfo to resolve hostnames before
1145 falling back to DNS. Because NetInfo has an unqualified name for all
1146 the machines in the NetInfo database, the machine's own hostname will
1147 resolve to an unqualified name. Kerberos needs a FQDN to look up keys
1148 in the machine's keytab file.
1150 Fortunately, you can change the @code{lookupd} caching order to query
1151 DNS first. Run the following NetInfo commands and reboot the machine:
1155 $ niutil -create . /locations/lookupd/hosts
1156 $ niutil -createprop . /locations/lookupd/hosts LookupOrder CacheAgent DNSAgent
1161 Once you have rebooted, you can verify that the resolver now behaves
1162 correctly. Compile the Kerberos 5 distribution and run:
1166 $ cd .../src/tests/resolve
1171 This will tell you whether or not your machine returns FQDNs on name
1172 lookups. If the test still fails, you can also try turning off DNS
1173 caching. Run the following commands and reboot:
1177 $ niutil -create . /locations/lookupd/hosts
1178 $ niutil -createprop . /locations/lookupd/hosts LookupOrder DNSAgent
1179 CacheAgent NIAgent NILAgent
1183 The remainder of the setup of a Mac OS X client machine or application
1184 server should be the same as for other UNIX-based systems.
1186 @node UNIX Application Servers, , Installing and Configuring UNIX Client Machines, Installing Kerberos V5
1187 @section UNIX Application Servers
1189 An application server is a host that provides one or more services over
1190 the network. Application servers can be ``secure'' or ``insecure.'' A
1191 ``secure'' host is set up to require authentication from every client
1192 connecting to it. An ``insecure'' host will still provide Kerberos
1193 authentication, but will also allow unauthenticated clients to connect.
1195 If you have @value{PRODUCT} installed on all of your client machines,
1196 @value{COMPANY} recommends that you make your hosts secure, to take
1197 advantage of the security that Kerberos authentication affords.
1198 However, if you have some clients that do not have @value{PRODUCT}
1199 installed, you can run an insecure server, and still take advantage of
1200 @value{PRODUCT}'s single sign-on on capability.
1204 * Server Configuration Files::
1206 * Some Advice about Secure Hosts::
1209 @node Server Programs, Server Configuration Files, UNIX Application Servers, UNIX Application Servers
1210 @subsection Server Programs
1212 Just as @value{PRODUCT} provided its own Kerberos-enhanced versions of
1213 client UNIX network programs, @value{PRODUCT} also provides
1214 Kerberos-enhanced versions of server UNIX network daemons. These are
1215 @code{ftpd}, @code{klogind}, @code{kshd}, and @code{telnetd}.
1217 These programs are installed in the directory
1218 @code{@value{ROOTDIR}/sbin}. You may want to add this directory to
1221 @node Server Configuration Files, The Keytab File, Server Programs, UNIX Application Servers
1222 @subsection Server Configuration Files
1224 For a @emph{secure} server, make the following changes to
1225 @code{/etc/inetd.conf}:
1227 Find and comment out any lines for the services @code{ftp},
1228 @code{telnet}, @code{shell}, @code{login}, and @code{exec}.
1231 Add the following lines. (Note: each line beginning with @result{} is
1232 a continuation of the previous line.)
1236 klogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1237 @result{} klogind -k -c
1238 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1239 @result{} klogind -k -c -e
1240 kshell stream tcp nowait root @value{ROOTDIR}/sbin/kshd
1241 @result{} kshd -k -c -A
1242 ftp stream tcp nowait root @value{ROOTDIR}/sbin/ftpd
1244 telnet stream tcp nowait root @value{ROOTDIR}/sbin/telnetd
1245 @result{} telnetd -a valid
1249 For an @emph{insecure} server, make the following changes instead to
1250 @code{/etc/inetd.conf}:
1253 Find and comment out any lines for the services @code{ftp} and
1256 Add the following lines. (Note: each line beginning with @result{} is
1257 a continuation of the previous line.)
1260 klogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1261 @result{} klogind -k -c
1262 eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
1263 @result{} klogind -k -c -e
1264 kshell stream tcp nowait root @value{ROOTDIR}/sbin/kshd
1265 @result{} kshd -k -c -A
1266 ftp stream tcp nowait root @value{ROOTDIR}/sbin/ftpd
1268 telnet stream tcp nowait root @value{ROOTDIR}/sbin/telnetd
1269 @result{} telnetd -a none
1273 @node The Keytab File, Some Advice about Secure Hosts, Server Configuration Files, UNIX Application Servers
1274 @subsection The Keytab File
1276 All Kerberos server machines need a @dfn{keytab} file, called
1277 @code{/etc/krb5.keytab}, to authenticate to the KDC. The keytab file is
1278 an encrypted, local, on-disk copy of the host's key. The keytab file,
1279 like the stash file (@ref{Create the Database}) is a potential
1280 point-of-entry for a break-in, and if compromised, would allow
1281 unrestricted access to its host. The keytab file should be readable
1282 only by root, and should exist only on the machine's local disk. The
1283 file should not be part of any backup of the machine, unless access to
1284 the backup data is secured as tightly as access to the machine's root
1287 In order to generate a keytab for a host, the host must have a principal
1288 in the Kerberos database. The procedure for adding hosts to the
1289 database is described fully in the ``Adding or Modifying Principals''
1290 section of the @cite{@value{PRODUCT} System Administrator's Guide}.
1291 @xref{Create Host Keys for the Slave KDCs} for a brief description.)
1292 The keytab is generated by running @code{kadmin} and issuing the
1293 @code{ktadd} command.
1296 For example, to generate a keytab file to allow the host
1297 trillium.@value{PRIMARYDOMAIN} to authenticate for the services
1298 @code{host}, @code{ftp}, and @code{pop}, the administrator
1299 @code{@value{ADMINUSER}} would issue the command (on
1300 trillium.@value{PRIMARYDOMAIN}):
1304 @b{trillium%} @value{ROOTDIR}/sbin/kadmin
1305 @b{kadmin5:} ktadd host/trillium.@value{PRIMARYDOMAIN} ftp/trillium.@value{PRIMARYDOMAIN}
1306 @result{} pop/trillium.@value{PRIMARYDOMAIN}
1307 @b{kadmin: Entry for principal host/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
1308 kvno 3, encryption type DES-CBC-CRC added to keytab
1309 WRFILE:/etc/krb5.keytab.
1310 kadmin: Entry for principal ftp/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
1311 kvno 3, encryption type DES-CBC-CRC added to keytab
1312 WRFILE:/etc/krb5.keytab.
1313 kadmin: Entry for principal pop/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
1314 kvno 3, encryption type DES-CBC-CRC added to keytab
1315 WRFILE:/etc/krb5.keytab.
1321 If you generate the keytab file on another host, you need to get a copy
1322 of the keytab file onto the destination host (@code{trillium}, in the
1323 above example) without sending it unencrypted over the network. If you
1324 have installed the @value{PRODUCT} client programs, you can use
1325 encrypted @code{rcp}.
1327 @node Some Advice about Secure Hosts, , The Keytab File, UNIX Application Servers
1328 @subsection Some Advice about Secure Hosts
1330 @value{PRODUCT} can protect your host from certain types of break-ins,
1331 but it is possible to install @value{PRODUCT} and still leave your host
1332 vulnerable to attack. Obviously an installation guide is not the place
1333 to try to include an exhaustive list of countermeasures for every
1334 possible attack, but it is worth noting some of the larger holes and how
1337 As stated earlier in this section, @value{COMPANY} recommends that on a
1338 secure host, you disable the standard @code{ftp}, @code{login},
1339 @code{telnet}, @code{shell}, and @code{exec} services in
1340 @code{/etc/inetd.conf}. We also recommend that secure hosts have an empty
1341 @code{/etc/hosts.equiv} file and that there not be a @code{.rhosts} file
1342 in @code{root}'s home directory. You can grant Kerberos-authenticated
1343 root access to specific Kerberos principals by placing those principals
1344 in the file @code{.k5login} in root's home directory.
1346 We recommend that backups of secure machines exclude the keytab file
1347 (@code{/etc/krb5.keytab}). If this is not possible, the backups should
1348 at least be done locally, rather than over a network, and the backup
1349 tapes should be physically secured.
1351 Finally, the keytab file and any programs run by root, including the
1352 @value{PRODUCT} binaries, should be kept on local disk. The keytab file
1353 should be readable only by root.
1355 @node Upgrading Existing Kerberos V5 Installations, Bug Reports for Kerberos V5, Installing Kerberos V5, Top
1356 @chapter Upgrading Existing @value{PRODUCT} Installations
1358 If you already have an existing Kerberos database that you created with
1359 a prior release of Kerberos 5, you can upgrade it to work with the
1360 current release with the @code{kdb5_util} command. The process for
1361 upgrading a Master KDC involves the following steps (the lines beginning
1362 with => indicate a continuation of the previous line):
1366 @item Stopping your current KDC and administration
1367 server processes, if any.
1369 @item Dumping your existing Kerberos database to an ASCII file with
1370 @code{kdb5_util}'s ``dump'' command:
1374 @b{shell%} kdb5_util -r @value{PRIMARYREALM} dump
1375 @result{} @value{ROOTDIR}/var/krb5kdc/old-kdb-dump
1380 @item Creating a new Master KDC installation (@xref{Install the Master
1381 KDC}). If you have a stash file for your current database, choose any
1382 new master password but then copy your existing stash file to the
1383 location specified by your kdc.conf; if you do not have a stash file for
1384 your current database, you must choose the same master password.
1386 @item Load your old Kerberos database into the new system with
1387 @code{kdb5_util}'s ``load'' command:
1391 @b{shell%} kdb5_util load @value{ROOTDIR}/var/krb5kdc/old-kdb-dump
1398 To update a Slave KDC, you must stop the old server processes on the
1399 Slave KDC, install the new server binaries, reload the most recent slave
1400 dump file, and re-start the server processes.
1402 @node Bug Reports for Kerberos V5, Files, Upgrading Existing Kerberos V5 Installations, Top
1403 @chapter Bug Reports for @value{PRODUCT}
1405 @include send-pr.texinfo
1407 @node Files, , Bug Reports for Kerberos V5, Top
1415 @node krb5.conf, kdc.conf, Files, Files
1416 @appendixsec krb5.conf
1418 Here is an example @code{krb5.conf} file:
1423 ticket_lifetime = 600
1424 default_realm = @value{PRIMARYREALM}
1425 default_tkt_enctypes = des-cbc-crc
1426 default_tgs_enctypes = des-cbc-crc
1429 @value{PRIMARYREALM} = @{
1430 kdc = @value{KDCSERVER}.@value{PRIMARYDOMAIN}:88
1431 kdc = @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}:88
1432 kdc = @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}:88
1433 admin_server = @value{KDCSERVER}.@value{PRIMARYDOMAIN}:749
1434 default_domain = @value{PRIMARYDOMAIN}
1438 .@value{PRIMARYDOMAIN} = @value{PRIMARYREALM}
1439 @value{PRIMARYDOMAIN} = @value{PRIMARYREALM}
1443 For the KDCs, add a section onto the end of the @code{krb5.conf} file
1444 telling how logging information should be stored, as in the following
1450 kdc = FILE:/var/log/krb5kdc.log
1451 admin_server = FILE:/var/log/kadmin.log
1452 default = FILE:/var/log/krb5lib.log
1461 @node kdc.conf, , krb5.conf, Files
1462 @appendixsec kdc.conf
1464 Here's an example of a kdc.conf file:
1472 @value{PRIMARYREALM} = @{
1473 database_name = @value{ROOTDIR}/var/krb5kdc/principal
1474 admin_keytab = @value{ROOTDIR}/var/krb5kdc/kadm5.keytab
1475 acl_file = @value{ROOTDIR}/var/krb5kdc/kadm5.acl
1476 dict_file = @value{ROOTDIR}/var/krb5kdc/kadm5.dict
1477 key_stash_file = @value{ROOTDIR}/var/krb5kdc/.k5.@value{PRIMARYREALM}
1479 max_life = 10h 0m 0s
1480 max_renewable_life = 7d 0h 0m 0s
1481 master_key_type = des-cbc-crc
1482 supported_enctypes = des-cbc-crc:normal
1487 To add Kerberos V4 support, change the @code{supported_enctypes} line to:
1490 supported_enctypes = des-cbc-crc:normal des-cbc-crc:v4
1494 * Encryption Types and Salt Types::
1497 @node Encryption Types and Salt Types, , kdc.conf, kdc.conf
1498 @appendixsubsec Encryption Types and Salt Types
1500 Currently, @value{PRODUCT} supports only DES and triple-DES encryption;
1501 however, triple-DES is currently supported only for service keys, not
1502 for user keys or session keys. The encoding types include
1503 @code{des-cbc-crc} and @code{des3-cbc-sha1}. The @dfn{salt} is
1504 additional information encoded within the key that tells what kind of
1505 key it is. The only salts that you will be likely to encounter are:
1508 @item @dfn{normal}, which @value{COMPANY} recommends using for all of
1509 your @value{PRODUCT} keys
1511 @item @dfn{v4}, which is necessary only for compatibility with a v4 KDC
1513 @item @dfn{afs}, which you will never need to generate, and which you will
1514 encounter only if you dump an AFS database into a Kerberos database
1517 Support for additional encryption types is planned in the future.