merge from V1_0_RELEASE

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@9686 dc483132-0cff-0310-8789-dd5450dbe970

1 files changed, 79 insertions, 53 deletions

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
@@ -326,20 +332,9 @@ The sections of this chapter describe procedures for installing
 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