From 1c3559d6f74f042ed190090fc0bc858e5f9c68e0 Mon Sep 17 00:00:00 2001 From: Tom Yu Date: Tue, 24 Dec 1996 10:18:06 +0000 Subject: merge from V1_0_RELEASE git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@9686 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/install.texinfo | 132 +++++++++++++++++++++++++++++++--------------------- 1 file changed, 79 insertions(+), 53 deletions(-) (limited to 'doc/install.texinfo') diff --git a/doc/install.texinfo b/doc/install.texinfo index 216abf9744..f5c4396a8c 100644 --- a/doc/install.texinfo +++ b/doc/install.texinfo @@ -16,7 +16,7 @@ @end iftex @include definitions.texinfo -@set EDITION b7-1 +@set EDITION 1.0 @finalout @c don't print black warning boxes @@ -123,10 +123,17 @@ installation procedure is somewhat involved, and requires forethought and planning. @value{COMPANY} has attempted to make this @value{PRODUCT} Installation Guide as concise as possible, rather than making it an exhaustive description of the details of Kerberos. +@ifset CYGNUS Consequently, everything in this guide appears because @value{COMPANY} believes that it is important. Please read and follow these instructions carefully, and if there is anything you do not understand or are not sure of, please don't hesitate to call us. +@end ifset +@ifset MIT +Consequently, everything in this guide appears because @value{COMPANY} +believes that it is important. Please read and follow these +instructions carefully. +@end ifset @node Overview of This Guide, , Please Read the Documentation, Introduction @section Overview of This Guide @@ -134,7 +141,7 @@ or are not sure of, please don't hesitate to call us. The next chapter describes the decisions you need to make before installing @value{PRODUCT}. -Chapter three describes installation procedures for each class of +Chapter four describes installation procedures for each class of Kerberos machines: @enumerate @@ -150,28 +157,20 @@ Slave KDCs. @end enumerate @item -Client machines (user machines): - -@enumerate A -@item -UNIX client machines. - -@item -Windows machines. - -@item -Macintoshes. -@end enumerate +UNIX client machines @item -application server machines +UNIX application server machines @end enumerate @noindent Note that a machine can be both a client machine and an application server. -Chapter four describes our problem reporting system. +Chapter five describes procedure for updating previous installations of +@value{PRODUCT}. + +Chapter six describes our problem reporting system. The appendices give sample configuration files. @@ -225,7 +224,7 @@ Kerberos realm @value{SECONDREALM}. If you need multiple Kerberos realms, @value{COMPANY} recommends that you use descriptive names which end with your domain name, such as -BOSTON.@value{SECONDREALM} and SAN_FRANCISCO.@value{SECONDREALM}. +BOSTON.@value{SECONDREALM} and HOUSTON.@value{SECONDREALM}. @node Mapping Hostnames onto Kerberos Realms, Ports for the KDC and Admin Services, Kerberos Realms, Realm Configuration Decisions @section Mapping Hostnames onto Kerberos Realms @@ -237,6 +236,12 @@ hostname-by-hostname basis. Since greater specificity takes precedence, you would do this by specifying the mappings for a given domain or subdomain and listing the exceptions. +The @value{PRODUCT} System Administrator's Guide contains a thorough +description of the parts of the @code{krb5.conf} file and what may be +specified in each. A sample @code{krb5.conf} file appears in +@ref{krb5.conf}. You should be able to use this file, substituting the +relevant information for your Kerberos instllation for the samples. + @node Ports for the KDC and Admin Services, Slave KDCs, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions @section Ports for the KDC and Admin Services @@ -271,9 +276,10 @@ Have at least one slave KDC as a backup, for when the master KDC is down, is being upgraded, or is otherwise unavailable. @item -If your network is split such that a network outage is likely to cause -some segment or segments of the network to become cut off or isolated, -have a slave KDC accessible to each segment. +If your network is split such that a network outage is likely to cause a +network partition (some segment or segments of the network to become cut +off or isolated from other segments), have a slave KDC accessible to +each segment. @item If possible, have at least one slave KDC in a different building from @@ -304,7 +310,7 @@ effect. If the propagation time is longer than this maximum reasonable time (@i{e.g.,} you have a particularly large database, you have a lot of -slaves, and/or you experience frequent network delays), you may wish to +slaves, or you experience frequent network delays), you may wish to cut down on your propagation delay by performing the propagation in parallel. To do this, have the master KDC propagate the database to one set of slaves, and then have each of these slaves propagate the database @@ -325,20 +331,9 @@ The sections of this chapter describe procedures for installing @item The KDCs -@item -Client machines - -@enumerate A @item UNIX client machines -@item -Windows machines - -@item -Macintoshes -@end enumerate - @item UNIX Application Servers @end enumerate @@ -359,12 +354,12 @@ regular intervals. All database changes (such as password changes) are made on the master KDC. Slave KDCs provide Kerberos ticket-granting services, but not database -access. This allows clients to continue to obtain tickets when the -master KDC is unavailable. +administration. This allows clients to continue to obtain tickets when +the master KDC is unavailable. -@value{COMPANY}'s recommends that you install all of your KDCs to be -able to function as either the master or one of the slaves. This will -enable you to easily switch your master KDC with one of the slaves if +@value{COMPANY} recommends that you install all of your KDCs to be able +to function as either the master or one of the slaves. This will enable +you to easily switch your master KDC with one of the slaves if necessary. (@xref{Switching Master and Slave KDCs}.) This installation procedure is based on that recommendation. @@ -401,9 +396,20 @@ Modify the configuration files, @code{/etc/krb5.conf} (@pxref{krb5.conf}) and @code{@value{ROOTDIR}/var/krb5kdc/kdc.conf} (@pxref{kdc.conf}) to reflect the correct information (such as the hostnames and realm name) for your realm. @value{COMPANY} recommends -that you keep @code{krb5.conf} in @code{/etc}. The @code{krb5.conf} -file may contain a pointer to @code{kdc.conf}, which you need to change -if you want to move @code{kdc.conf} to another location. +that you keep @code{krb5.conf} in @code{/etc}. + +Among the settings in your @code{/etc/krb5.conf} file, be sure to create +a @code{[logging]} stanza so that the KDC and kadmind will generate +logging output. For example: + +@smallexample +@group +[logging] + kdc = FILE:/var/log/krb5kdc.log + admin_server = FILE:/var/log/kadmin.log + default = FILE:/var/log/krb5lib.log +@end group +@end smallexample @node Create the Database, Add Administrators to the Acl File, Edit the Configuration Files, Install the Master KDC @subsubsection Create the Database @@ -430,11 +436,10 @@ words that can be found in a dictionary, any common or popular name, especially a famous person (or cartoon character), your username in any form (@i{e.g.}, forward, backward, repeated twice, @i{etc.}), and any of the sample keys that appear in this manual. One example of a key which -would be good if it did not appear in this manual is ``MITiys4K5!'', -which represents the sentence ``@value{COMPANY} is your source for -Kerberos 5!'' (It's the first letter of each word, substituting the -numeral ``4'' for the word ``for'', and includes the punctuation mark at -the end.) +might be good if it did not appear in this manual is ``MITiys4K5!'', +which represents the sentence ``MIT is your source for Kerberos 5!'' +(It's the first letter of each word, substituting the numeral ``4'' for +the word ``for'', and includes the punctuation mark at the end.) The following is an example of how to create a Kerberos database and stash file on the master KDC, using the @code{kdb5_util} command. (The @@ -554,7 +559,10 @@ instance ``root'', you would add the following line to the acl file: Next you need to add administrative principals to the Kerberos database. (You must add at least one now.) To do this, use @code{kadmin.local} -@emph{on the master KDC}, as in the following example: +@emph{on the master KDC}. The administrative principals you create +should be the ones you added to the ACL file (see @xref{Add +Administrators to the Acl File}). In the following example, the +administration principal @code{admin/admin} is created: @smallexample @group @@ -575,6 +583,8 @@ kadmin.local:} @end group @end smallexample + + @node Create a kadmind Keytab, Start the Kerberos Daemons, Add Administrators to the Kerberos Database, Install the Master KDC @subsubsection Create a kadmind Keytab @@ -606,7 +616,7 @@ kadmin.local:} quit @noindent As specified in the @samp{-k} argument, @code{ktadd} will save the -extracted keytab as @code{@value{ROOTDIR}/var/krb5kdc/kadm5.keytab}. +extracted keytab as @* @code{@value{ROOTDIR}/var/krb5kdc/kadm5.keytab}. The filename you use must be the one specified in your @code{kdc.conf} file. @@ -628,6 +638,21 @@ these daemons to start up automatically at boot time, you can add them to the KDC's @code{/etc/rc} or @code{/etc/inittab} file. You need to have a stash file in order to do this. +You can verify that they started properly by checking for their startup +messages in the logging locations you defined in @code{/etc/krb5.conf} +(see @xref{Edit the Configuration Files}). For example: + +@smallexample +@b{shell%} tail /var/log/krb5kdc.log +Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation +@b{shell%} tail /var/log/kadmin.log +Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting +@end smallexample + +Any errors the daemons encounter while starting will also be listed in +the logging output. + + @node Install the Slave KDCs, Back on the Master KDC, Install the Master KDC, Installing KDCs @subsection Install the Slave KDCs @@ -657,15 +682,15 @@ named @value{KDCSLAVE1}.@value{PRIMARYDOMAIN} and @smallexample @group @b{shell%} @value{ROOTDIR}/sbin/kadmin -@b{kadmin:} addprinc -randpass host/@value{KDCSERVER}.@value{PRIMARYDOMAIN} +@b{kadmin:} addprinc -randkey host/@value{KDCSERVER}.@value{PRIMARYDOMAIN} @b{WARNING: no policy specified for "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}"; defaulting to no policy. Principal "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created. -kadmin:} addprinc -randpass host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN} +kadmin:} addprinc -randkey host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN} @b{WARNING: no policy specified for "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}"; defaulting to no policy. Principal "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.} -@b{kadmin:} addprinc -randpass host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN} +@b{kadmin:} addprinc -randkey host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN} @b{WARNING: no policy specified for "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}"; defaulting to no policy. Principal "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created. @@ -758,8 +783,8 @@ KDC: kerberos 88/udp kdc # Kerberos authentication (udp) kerberos 88/tcp kdc # Kerberos authentication (tcp) krb5_prop 754/tcp # Kerberos slave propagation -kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp) -kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp) +kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp) +kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp) eklogin 2105/tcp # Kerberos encrypted rlogin @end group @end smallexample @@ -1350,7 +1375,8 @@ terminology. @node Bug Reports for Kerberos V5, Files, Upgrading Existing Kerberos V5 Installations, Top @chapter Bug Reports for @value{PRODUCT} -@include bug-report.texinfo + +@include send-pr.texinfo @node Files, , Bug Reports for Kerberos V5, Top @appendix Files -- cgit