* Makefile: made the list of manpages a variable

        * admin.texinfo: took out second inclusion of copyright notice,
        changed some section names, updated initial synopsis of file,
        added explanation of encryption types and the [login] section of
        krb5.conf, added documentation on various tags in the configuration
        files, added some more examples, fixed some typos, updated usage
        statements for various kadmin and kdb5_util commands, updated the
        sample output from the commands, updated the infotex for use with
        makeinfo --html, added a section about getting shared-realm keys,
        updated the error codes
        * build.texinfo: added a section describing the structure of the
        source code tree, updated documentation of options to configure
        script, added information about defaults for various variable
        settings, updated information about shared library support,
        added discussion of valid kerberos principals
        * definitions.texinfo: added some new default variables,
        corrected some pathnames of default values
        * dnssrv.texinfo: made the information about default port numbers
        reference a variable
        * glossary.texinfo: updated definition of principal
        * install.texinfo: fixed typos and formatting errors, removed old
        sample config files from appendix (samples are in the sections about
        the config files), added information about supporting RC4 keys
        * kadm5.acl: new file.  describes the kadm5.acl file.  included by
        both admin.texinfo and install.texinfo.  text is made up mostly of
        text that was split between those two documents.  documentation
        of backreferences was added
        * kdcconf.texinfo: made defaults reference variables
        * krb425.texinfo: deleted second inclusion of copyright info,
        made defaults reference variable, fixed typos, took out redundant
        part about editing inetd.conf and replaced it with reference to
        install guide
        * krb5conf.texinfo: documented the "final variable" feature,
        added mention of the [login] section,
        * send-pr.texinfo: minor change in wording for clarity
        * user-guide.texinfo: made various minor wording changes, updated
        some of the sample output, updated documention of command options

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

1 files changed, 101 insertions, 141 deletions

diff --git a/doc/install.texinfo b/doc/install.texinfo
index 9aa6654bc0..b105435e20 100644
--- a/doc/install.texinfo
+++ b/doc/install.texinfo
@@ -30,9 +30,6 @@
 @page
 @vskip 0pt plus 1filll
 
-@iftex
-@include copyright.texinfo
-@end iftex
 @end titlepage
 
 @node Top, Copyright, (dir), (dir)
@@ -112,8 +109,6 @@ security breaches in industry happen from @i{inside} firewalls,
 @value{PRODUCT} from @value{COMPANY} will play a vital role in the
 security of your network.
 
-@include document-list.texinfo
-
 @node Please Read the Documentation, Overview of This Guide, Why Should I use Kerberos?, Introduction
 @section Please Read the Documentation
 
@@ -134,12 +129,19 @@ believes that it is important.  Please read and follow these
 instructions carefully.
 @end ifset
 
+@include document-list.texinfo
+
 @node Overview of This Guide,  , Please Read the Documentation, Introduction
 @section Overview of This Guide
 
+@noindent
 The next chapter describes the decisions you need to make before
 installing @value{PRODUCT}.
 
+@noindent
+Chapter three provided instructions for building the Kerberos sources.
+
+@noindent
 Chapter four describes installation procedures for each class of
 Kerberos machines:
 
@@ -166,13 +168,13 @@ UNIX application server machines
 Note that a machine can be both a client machine and an application
 server.
 
+@noindent
 Chapter five describes procedure for updating previous installations of
 @value{PRODUCT}.
 
+@noindent
 Chapter six describes our problem reporting system.
 
-The appendices give sample configuration files.
-
 @node Realm Configuration Decisions, Building Kerberos V5, Introduction, Top
 @chapter Realm Configuration Decisions
 
@@ -233,15 +235,16 @@ BOSTON.@value{SECONDREALM} and HOUSTON.@value{SECONDREALM}.
 @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
 
-The default ports used by Kerberos are port 88 for the
-KDC@footnote{Kerberos V4 used port 750.  If necessary, you can run on
-both ports for backward compatibility.}  and port 749 for the admin
-server.  You can, however, choose to run on other ports, as long as they
-are specified in each host's @code{/etc/services} and @code{krb5.conf}
-files, and the @code{kdc.conf} file on each KDC.  For a more thorough
-treatment of port numbers used by the @value{PRODUCT} programs, refer to
-the ``Configuring Your Firewall to Work With @value{PRODUCT}'' section
-of the @cite{@value{PRODUCT} System Administrator's Guide}.
+The default ports used by Kerberos are port @value{DefaultPort} for the
+KDC@footnote{Kerberos V4 used port @value{DefaultSecondPort}.  If
+necessary, you can run on both ports for backward compatibility.}  and
+port @value{DefaultKadmindPort} for the admin server.  You can, however,
+choose to run on other ports, as long as they are specified in each
+host's @code{/etc/services} and @code{krb5.conf} files, and the
+@code{kdc.conf} file on each KDC.  For a more thorough treatment of
+port numbers used by the @value{PRODUCT} programs, refer to the
+``Configuring Your Firewall to Work With @value{PRODUCT}'' section of
+the @cite{@value{PRODUCT} System Administrator's Guide}.
 
 @node Slave KDCs, Hostnames for the Master and Slave KDCs, Ports for the KDC and Admin Services, Realm Configuration Decisions
 @section Slave KDCs
@@ -415,10 +418,12 @@ An example @code{krb5.conf} file:
     default_realm = @value{PRIMARYREALM}
 
 [realms]
-    kdc = @value{KDCSERVER}.@value{PRIMARYDOMAIN}
-    kdc = @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}
-    kdc = @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}
-    admin_server = @value{KDCSERVER}.@value{PRIMARYDOMAIN}
+    @value{PRIMARYREALM} = @{
+    	kdc = @value{KDCSERVER}.@value{PRIMARYDOMAIN}
+    	kdc = @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}
+    	kdc = @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}
+    	admin_server = @value{KDCSERVER}.@value{PRIMARYDOMAIN}
+    @{
 
 [logging]
     kdc = FILE:/var/log/krb5kdc.log
@@ -484,6 +489,10 @@ It is important that you NOT FORGET this password.}
 @b{Enter KDC database master key:}  @i{<= Type the master password.}
 @b{Re-enter KDC database master key to verify:}  @i{<= Type it again.}
 @end ifinfo
+@ifhtml
+@b{Enter KDC database master key:}  @i{<= Type the master password.}
+@b{Re-enter KDC database master key to verify:}  @i{<= Type it again.}
+@end ifhtml
 @b{shell%}
 @end group
 @end smallexample
@@ -502,79 +511,10 @@ want a stash file, run the above command without the @code{-s} option.
 Next, you need create an Access Control List (acl) file, and put the
 Kerberos principal of at least one of the administrators into it.  The
 filename should match the value you have set for ``acl_file'' in your
-@code{kdc.conf} file.  The default file name is @samp{kadm5.acl}.  The
-format of the file is:
-
-@smallexample
-Kerberos principal      permissions     optional target principal
-@end smallexample
-
-The Kerberos principal (and optional target principal) can include the
-``@b{*}'' wildcard, so if you want any principal with the instance
-``admin'' to have full permissions on the database, you could use the
-principal ``@code{*/admin@@REALM}'' where ``REALM'' is your Kerberos
-realm.
-
-Note:  a common use of an @i{admin} instance is so you can grant
-separate permissions (such as administrator access to the Kerberos
-database) to a separate Kerberos principal.  For example, the user
-@code{@value{ADMINUSER}} might have a principal for his administrative
-use, called @code{@value{ADMINUSER}/admin}.  This way,
-@code{@value{ADMINUSER}} would obtain @code{@value{ADMINUSER}/admin}
-tickets only when he actually needs to use those permissions.  Refer to
-the @value{PRODUCT} Administrator's Guide or the @value{PRODUCT} User's
-Guide for more detailed explanations of @dfn{principals} and
-@dfn{instances}.
-
-The permissions (acls) recognized in the acl file 
-are the following:
-
-@table @b
-@itemx a
-allows the addition of principals or policies in the database.
-@itemx A
-prohibits the addition of principals or policies in the database.
-@itemx d
-allows the deletion of principals or policies in the database.
-@itemx D
-prohibits the deletion of principals or policies in the database.
-@itemx m    
-allows the modification of principals or policies in the database.
-@itemx M
-prohibits the modification of principals or policies in the database.
-@itemx c
-allows the changing of passwords for principals in the database.
-@itemx C
-prohibits the changing of passwords for principals in the database.
-@itemx i
-allows inquiries to the database.
-@itemx I
-prohibits inquiries to the database.
-@itemx l
-allows the listing of principals or policies in the database.
-@itemx L
-prohibits the listing of principals or policies in the database.
-@itemx *
-Short for all privileges (admcil).
-@itemx x
-Short for all privileges (admcil); identical to ``*''.
-@end table
-
-To give the principal @code{*/admin@@@value{PRIMARYREALM}} permission to
-change all of the database permissions on any principal permissions, you
-would place the following line in the file:
-
-@smallexample
-*/admin@@@value{PRIMARYREALM}  *
-@end smallexample
+@code{kdc.conf} file.  The default file name is
+@samp{@value{DefaultAclFile}}.  
 
-To give the principal @code{@value{ADMINUSER}@@@value{PRIMARYREALM}}
-permission to add, list, and inquire about any principal that has the
-instance ``root'', you would add the following line to the acl file:
-
-@smallexample
-@value{ADMINUSER}@@@value{PRIMARYREALM}  ali  */root@@@value{PRIMARYREALM}
-@end smallexample
+@include kadm5acl.texinfo
 
 @node Add Administrators to the Kerberos Database, Create a kadmind Keytab, Add Administrators to the Acl File, Install the Master KDC
 @subsubsection Add Administrators to the Kerberos Database
@@ -590,8 +530,8 @@ administration principal @code{admin/admin} is created:
 @group
 @b{shell%} @value{ROOTDIR}/sbin/kadmin.local
 @b{kadmin.local:} addprinc admin/admin@@@value{PRIMARYREALM}
-@b{WARNING: no policy specified for "admin/admin@@@value{PRIMARYREALM}";
-defaulting to no policy.}
+@b{NOTICE: no policy specified for "admin/admin@@@value{PRIMARYREALM}";
+assigning "default".}
 @iftex
 @b{Enter password for principal admin/admin@@@value{PRIMARYREALM}:}  @i{@doubleleftarrow{} Enter a password.}
 Re-enter password for principal admin/admin@@@value{PRIMARYREALM}:  @i{@doubleleftarrow{} Type it again.}
@@ -600,6 +540,10 @@ Re-enter password for principal admin/admin@@@value{PRIMARYREALM}:  @i{@doublele
 @b{Enter password for principal admin/admin@@@value{PRIMARYREALM}:}  @i{<= Enter a password.}
 Re-enter password for principal admin/admin@@@value{PRIMARYREALM}:  @i{<= Type it again.}
 @end ifinfo
+@ifhtml
+@b{Enter password for principal admin/admin@@@value{PRIMARYREALM}:}  @i{<= Enter a password.}
+Re-enter password for principal admin/admin@@@value{PRIMARYREALM}:  @i{<= Type it again.}
+@end ifhtml
 @b{Principal "admin/admin@@@value{PRIMARYREALM}" created.
 kadmin.local:}
 @end group
@@ -625,12 +569,18 @@ continuation of the previous line.):
 @b{shell%} @value{ROOTDIR}/sbin/kadmin.local
 @b{kadmin.local:} ktadd -k @value{ROOTDIR}/var/krb5kdc/kadm5.keytab
 @result{} kadmin/admin kadmin/changepw 
-@b{Entry for principal kadmin/admin@@@value{PRIMARYREALM} with
-     kvno 3, encryption type DES-CBC-CRC added to keytab
-     WRFILE:@value{ROOTDIR}/var/krb5kdc/kadm5.keytab.
-Entry for principal kadmin/changepw@@@value{PRIMARYREALM} with
-     kvno 3, encryption type DES-CBC-CRC added to keytab
-     WRFILE:@value{ROOTDIR}/var/krb5kdc/kadm5.keytab.
+@b{ Entry for principal kadmin/admin with kvno 5, encryption
+	type Triple DES cbc mode with HMAC/sha1 added to keytab
+	WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
+Entry for principal kadmin/admin with kvno 5, encryption type DES cbc mode
+	with CRC-32 added to keytab
+	WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
+Entry for principal kadmin/changepw with kvno 5, encryption
+	type Triple DES cbc mode with HMAC/sha1 added to keytab
+	WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
+Entry for principal kadmin/changepw with kvno 5,
+	encryption type DES cbc mode with CRC-32 added to keytab
+	WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
 kadmin.local:} quit
 @b{shell%}
 @end group
@@ -705,16 +655,16 @@ named @value{KDCSLAVE1}.@value{PRIMARYDOMAIN} and
 @group
 @b{shell%} @value{ROOTDIR}/sbin/kadmin
 @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.
+@b{NOTICE: no policy specified for "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
+assigning "default"
 Principal "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.
 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.
+@b{NOTICE: no policy specified for "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
+assigning "default"
 Principal "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.}
 @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.
+@b{NOTICE: no policy specified for "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}";
+assigning "default"
 Principal "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.
 kadmin:}
 @end group
@@ -899,6 +849,9 @@ kdb5_util: Warning: proceeding without master key}
 @ifinfo
 @b{Enter KDC database master key:}  @i{<= Enter the database master key.}
 @end ifinfo
+@ifhtml
+@b{Enter KDC database master key:}  @i{<= Enter the database master key.}
+@end ifhtml
 @b{shell%}
 @end group
 @end smallexample
@@ -1102,16 +1055,16 @@ to just insert the following code:
 # you will need to switch the "kerberos" service to port 750 and create a
 # "kerberos-sec" service on port 88.
 #
-kerberos      88/udp    kdc    # Kerberos V5 KDC
-kerberos      88/tcp    kdc    # Kerberos V5 KDC
-klogin        543/tcp          # Kerberos authenticated rlogin
-kshell        544/tcp   cmd    # and remote shell
-kerberos-adm  749/tcp          # Kerberos 5 admin/changepw
-kerberos-adm  749/udp          # Kerberos 5 admin/changepw
-krb5_prop     754/tcp          # Kerberos slave propagation
+kerberos      @value{DefaultPort}/udp    kdc    # Kerberos V5 KDC
+kerberos      @value{DefaultPort}/tcp    kdc    # Kerberos V5 KDC
+klogin        @value{DefaultKloginPort}/tcp          # Kerberos authenticated rlogin
+kshell        @value{DefaultKshellPort}/tcp   cmd    # and remote shell
+kerberos-adm  @value{DefaultKamdindPort}/tcp          # Kerberos 5 admin/changepw
+kerberos-adm  @value{DefaultKamdindPort}/udp          # Kerberos 5 admin/changepw
+krb5_prop     @value{DefaultKrbPropPort}/tcp          # Kerberos slave propagation
 @c kpop          1109/tcp         # Pop with Kerberos
-eklogin       2105/tcp         # Kerberos auth. & encrypted rlogin
-krb524        4444/tcp         # Kerberos 5 to 4 ticket translator
+eklogin       @value{DefaultEkloginPort}/tcp         # Kerberos auth. & encrypted rlogin
+krb524        @value{DefaultKrb524Port}/tcp         # Kerberos 5 to 4 ticket translator
 @end group
 @end smallexample
 
@@ -1224,7 +1177,7 @@ If you have @value{PRODUCT} installed on all of your client machines,
 advantage of the security that Kerberos authentication affords.
 However, if you have some clients that do not have @value{PRODUCT}
 installed, you can run an insecure server, and still take advantage of
-@value{PRODUCT}'s single sign-on on capability.
+@value{PRODUCT}'s single sign-on capability.
 
 @menu
 * Server Programs::             
@@ -1384,10 +1337,12 @@ should be readable only by root.
 
 If you already have an existing Kerberos database that you created with
 a prior release of Kerberos 5, you can upgrade it to work with the
-current release with the @code{kdb5_util} command.  It is only necessary
-to perform this dump/undump procedure if you were running a krb5-1.0.x
-KDC and are migrating to a krb5-1.1.x or newer KDC.  The process for
-upgrading a Master KDC involves the following steps:
+current release with the @code{kdb5_util} command.  It is only
+necessary to perform this dump/undump procedure if you were running a
+krb5-1.0.x KDC and are migrating to a krb5-1.1.x or newer KDC or if you
+were running a krb5-1.1.x KDC and are migrating to a krb5-1.2.x or newer
+KDC.  The process for upgrading a Master KDC involves the following
+steps:
 
 @enumerate
 
@@ -1437,18 +1392,18 @@ Slave KDC, install the new server binaries, reload the most recent slave
 dump file, and re-start the server processes.
 
 @menu
-* Upgrading to Triple-DES Encryption Keys::  
+* Upgrading to Triple-DES and RC4 Encryption Keys::  
 @end menu
 
-@node Upgrading to Triple-DES Encryption Keys,  , Upgrading Existing Kerberos V5 Installations, Upgrading Existing Kerberos V5 Installations
+@node Upgrading to Triple-DES and RC4 Encryption Keys,  , Upgrading Existing Kerberos V5 Installations, Upgrading Existing Kerberos V5 Installations
 @section Upgrading to Triple-DES Encryption Keys
 
-Beginning with the 1.2 release from MIT, Kerberos includes a stronger
-encryption algorithm called ``triple DES'' -- essentially, three
-applications of the basic DES encryption algorithm, greatly increasing
-the resistance to a brute-force search for the key by an attacker.  This
-algorithm is more secure, but encryption is much slower.  We expect to
-add other, faster encryption algorithms at some point in the future.
+Beginning with the 1.2 release from @value{COMPANY}, Kerberos includes
+a stronger encryption algorithm called ``triple DES'' -- essentially,
+three applications of the basic DES encryption algorithm, greatly
+increasing the resistance to a brute-force search for the key by an
+attacker.  This algorithm is more secure, but encryption is much
+slower.
 
 Release 1.1 had some support for triple-DES service keys, but with
 release 1.2 we have added support for user keys and session keys as
@@ -1456,24 +1411,29 @@ well.  Release 1.0 had very little support for multiple cryptosystems,
 and some of that software may not function properly in an environment
 using triple-DES as well as plain DES.
 
-Because of the way the MIT Kerberos database is structured, the KDC will
-assume that a service supports only those encryption types for which
-keys are found in the database.  Thus, if a service has only a
+In the 1.3 release from @value{COMPANY}, Kerberos also includes the RC4
+encryption alogorithm, a stream cipher symmetric key algorithm
+developed in 1987 by Ronald Rivest at RSA Data Security.  Please note
+that RC4 is not part of the IETF standard.
+
+Because of the way the MIT Kerberos database is structured, the KDC
+will assume that a service supports only those encryption types for
+which keys are found in the database.  Thus, if a service has only a
 single-DES key in the database, the KDC will not issue tickets for that
-service that use triple-DES session keys; it will instead issue only
-single-DES session keys, even if other services are already capable of
-using triple-DES.  So if you make sure your application server software
-is updated before adding a triple-DES key for the service, clients
-should be able to talk to services at all times during the updating
-process.
+service that use triple-DES or RC4 session keys; it will instead issue
+only single-DES session keys, even if other services are already
+capable of using triple-DES or RC4.  So if you make sure your
+application server software is updated before adding a triple-DES or
+RC4 key for the service, clients should be able to talk to services at
+all times during the updating process.
 
 Normally, the listed @code{supported_enctypes} in @code{kdc.conf} are
 all used when a new key is generated.  You can control this with
 command-line flags to @code{kadmin} and @code{kadmin.local}.  You may
-want to exclude triple-DES by default until you have updated a lot of
-your application servers, and then change the default to include
-triple-DES.  We recommend that you always include @code{des-cbc-crc} in
-the default list.
+want to exclude triple-DES and RC4 by default until you have updated a
+lot of your application servers, and then change the default to include
+triple-DES and RC4.  We recommend that you always include
+@code{des-cbc-crc} in the default list.
 
 @node Bug Reports for Kerberos V5,  , Upgrading Existing Kerberos V5 Installations, Top
 @chapter Bug Reports for @value{PRODUCT}