@setchapternewpage odd @c chapter begins on next odd page
@c @setchapternewpage on @c chapter begins on next page
@c @smallbook @c Format for 7" X 9.25" paper
+@documentencoding UTF-8
@c %**end of header
+@copying
+Copyright @copyright{} 1985-2010 by the Massachusetts Institute of Technology.
+@end copying
@paragraphindent 0
@iftex
@page
@vskip 0pt plus 1filll
-
+@insertcopying
@end titlepage
-@node Top, Copyright, (dir), (dir)
+@node Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up
@ifinfo
This file documents how to install the @value{RELEASE} release of
@value{PRODUCT}.
+@insertcopying
@end ifinfo
@c The master menu is updated using emacs19's M-x texinfo-all-menus-update
@c ---------------------------------------------------------------------
@menu
-* Copyright::
* Introduction::
* Realm Configuration Decisions::
* Building Kerberos V5::
* Installing Kerberos V5::
* Upgrading Existing Kerberos V5 Installations::
* Bug Reports for Kerberos V5::
+* Copyright::
@end menu
-@node Copyright, Introduction, Top, Top
-@unnumbered Copyright
-@include copyright.texinfo
-
-@node Introduction, Realm Configuration Decisions, Copyright, Top
+@node Introduction, Realm Configuration Decisions, Top, Top
@chapter Introduction
@menu
@item
How frequently you will propagate the database from the master KDC to
the slave KDCs.
-
-@item
-Whether you need backward compatibility with Kerberos V4.
@end itemize
@menu
* Add Kerberos Principals to the Database::
* Limit Access to the KDCs::
* Switching Master and Slave KDCs::
+* Incremental Database Propagation::
@end menu
@node Install the Master KDC, Install the Slave KDCs, Installing KDCs, Installing KDCs
@subsubsection Add Administrators to the Acl File
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{@value{DefaultAclFile}}.
+Kerberos principal of at least one of the administrators into it. This
+file is used by the @code{kadmind} daemon to control which principals
+may view and make privileged modifications to the Kerberos database
+files. The filename should match the value you have set for
+``acl_file'' in your @code{kdc.conf} file. The default file name is
+@samp{@value{DefaultAclFile}}.
@include kadm5acl.texinfo
@end smallexample
@need 1000
-Then, add the following lines to @code{/etc/inetd.conf} file on each KDC
-(the line beginnng with @result{} is a continuation of the previous
-line):
+Then, add the following line to @code{/etc/inetd.conf} file on each KDC:
@smallexample
@group
krb5_prop stream tcp nowait root @value{ROOTDIR}/sbin/kpropd kpropd
-eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
-@result{} klogind -k -c -e
@end group
@end smallexample
@noindent
-The first line sets up the @code{kpropd} database propagation daemon.
-The second line sets up the @code{eklogin} daemon, allowing
-Kerberos-authenticated, encrypted rlogin to the KDC.
-
You also need to add the following lines to @code{/etc/services} on each
KDC:
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)
-eklogin 2105/tcp # Kerberos encrypted rlogin
@end group
@end smallexample
root access through a security hole in any of those areas could gain
access to the Kerberos database.
-@need 4700
-@value{COMPANY} recommends that your KDCs use the following
-@code{/etc/inetd.conf} file. (Note: each line beginning with @result{}
-is a continuation of the previous line.):
-
-@smallexample
-@group
-#
-# Configuration file for inetd(1M). See inetd.conf(4).
-#
-# To re-configure the running inetd process, edit this file, then
-# send the inetd process a SIGHUP.
-#
-# Syntax for socket-based Internet services:
-# <service_name> <socket_type> <proto> <flags> <user>
-@result{} <server_pathname> <args>
-#
-# Syntax for TLI-based Internet services:
-#
-# <service_name> tli <proto> <flags> <user> <server_pathname> <args>
-#
-# Ftp and telnet are standard Internet services.
-#
-# This machine is a secure Kerberos Key Distribution Center (KDC).
-# Services are limited.
-#
-#
-# Time service is used for clock synchronization.
-#
-time stream tcp nowait root internal
-time dgram udp wait root internal
-#
-# Limited Kerberos services
-#
-krb5_prop stream tcp nowait root @value{ROOTDIR}/sbin/kpropd kpropd
-eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
-@result{} klogind -5 -c -e
-@end group
-@end smallexample
-
-@node Switching Master and Slave KDCs, , Limit Access to the KDCs, Installing KDCs
+@node Switching Master and Slave KDCs, Incremental Database Propagation, Limit Access to the KDCs, Installing KDCs
@subsection Switching Master and Slave KDCs
You may occasionally want to use one of your slave KDCs as the master.
@end enumerate
+@node Incremental Database Propagation, , Switching Master and Slave KDCs, Installing KDCs
+@subsection Incremental Database Propagation
+
+At some very large sites, dumping and transmitting the database can
+take more time than is desirable for changes to propagate from the
+master KDC to the slave KDCs. The incremental propagation support
+added in the 1.7 release is intended to address this.
+
+With incremental propagation enabled, all programs on the master KDC
+that change the database also write information about the changes to
+an ``update log'' file, maintained as a circular buffer of a certain
+size. A process on each slave KDC connects to a service on the master
+KDC (currently implemented in the @code{kadmind} server) and
+periodically requests the changes that have been made since the last
+check. By default, this check is done every two minutes. If the
+database has just been modified in the previous several seconds
+(currently the threshold is hard-coded at 10 seconds), the slave will
+not retrieve updates, but instead will pause and try again soon after.
+This reduces the likelihood that incremental update queries will cause
+delays for an administrator trying to make a bunch of changes to the
+database at the same time.
+
+Incremental propagation uses the following entries in the per-realm
+data in the KDC config file:
+
+@table @asis
+@item @code{iprop_enable} (boolean)
+If this is set to @code{true}, then incremental propagation is
+enabled, and (as noted below) normal @code{kprop} propagation is
+disabled. The default is @code{false}.
+
+@item @code{iprop_master_ulogsize} (integer)
+This indicates the number of entries that should be retained in the
+update log. The default is 1000; the maximum number is 2500.
+
+@item @code{iprop_slave_poll} (time interval)
+This indicates how often the slave should poll the master KDC for
+changes to the database. The default is two minutes.
+
+@item @code{iprop_port} (integer)
+This specifies the port number to be used for incremental
+propagation. This is required in both master and slave configuration
+files.
+
+@item @code{iprop_logfile} (file name)
+This specifies where the update log file for the realm database is to
+be stored. The default is to use the @code{database_name} entry from
+the @code{realms} section of the config file, with @file{.ulog} appended.
+(NOTE: If @code{database_name} isn't specified in the @code{realms}
+section, perhaps because the LDAP database back end is being used, or
+the file name is specified in the @code{dbmodules} section, then the
+hard-coded default for @code{database_name} is used. Determination of
+the @code{iprop_logfile} default value will not use values from the
+@code{dbmodules} section.)
+@end table
+
+Both master and slave sides must have principals named
+@code{kiprop/@var{hostname}} (where @var{hostname} is, as usual, the
+lower-case, fully-qualified, canonical name for the host) registered
+and keys stored in the default keytab file (@file{/etc/krb5.keytab}).
+@c XXX: I think the master side, at least, might be able to read the
+@c key out of the database. Test and document this.
+
+On the master KDC side, the @code{kiprop/@var{hostname}} principal
+must be listed in the @code{kadmind} ACL file @code{kadm5.acl}, and
+given the @code{p} privilege.
+
+On the slave KDC side, @code{kpropd} should be run. When incremental
+propagation is enabled, it will connect to the @code{kadmind} on the
+master KDC and start requesting updates.
+
+The normal @code{kprop} mechanism is disabled by the incremental
+propagation support. However, if the slave has been unable to fetch
+changes from the master KDC for too long (network problems, perhaps),
+the log on the master may wrap around and overwrite some of the
+updates that the slave has not yet retrieved. In this case, the slave
+will instruct the master KDC to dump the current database out to a
+file and invoke a one-time @code{kprop} propagation, with special
+options to also convey the point in the update log at which the slave
+should resume fetching incremental updates. Thus, all the keytab and
+ACL setup previously described for @code{kprop} propagation is still
+needed.
+
+There are several restrictions in the current implementation:
+
+@itemize
+@item
+Changes to password policy objects are not propagated incrementally.
+Changes to which policy applies to a principal are propagated.
+@item
+The master and slave must be able to initiate TCP connections in both
+directions, without an intervening NAT.
+@item
+If the slave has an IPv6 interface address but needs to accept
+connections over IPv4, the operating system needs ``dual stack'' support
+(i.e. the ability to accept IPv6 and IPv4 connections on a single IPv6
+listener socket). At this time, all modern Unix-like operating systems
+have dual stack support except OpenBSD.
+@end itemize
+
+@menu
+* Sun/MIT Incremental Propagation Differences::
+@end menu
+
+@node Sun/MIT Incremental Propagation Differences, , Incremental Database Propagation, Incremental Database Propagation
+@subsubsection Sun/MIT Incremental Propagation Differences
+
+Sun donated the original code for supporting incremental database
+propagation to MIT. Some changes have been made in the MIT source
+tree that will be visible to administrators. (These notes are based
+on Sun's patches. Changes to Sun's implementation since then may not
+be reflected here.)
+
+The Sun config file support looks for @code{sunw_dbprop_enable},
+@code{sunw_dbprop_master_ulogsize}, and @code{sunw_dbprop_slave_poll}.
+
+The incremental propagation service is implemented as an ONC RPC
+service. In the Sun implementation, the service is registered with
+@code{rpcbind} (also known as @code{portmapper}) and the client looks
+up the port number to contact. In the MIT implementation, where
+interaction with some modern versions of @code{rpcbind} doesn't always
+work well, the port number must be specified in the config file on
+both the master and slave sides.
+
+The Sun implementation hard-codes pathnames in @file{/var/krb5} for
+the update log and the per-slave @code{kprop} dump files. In the MIT
+implementation, the pathname for the update log is specified in the
+config file, and the per-slave dump files are stored in
+@code{@value{ROOTDIR}/var/krb5kdc/slave_datatrans_@var{hostname}}.
+
@node Installing and Configuring UNIX Client Machines, UNIX Application Servers, Installing KDCs, Installing Kerberos V5
@section Installing and Configuring UNIX Client Machines
@node Client Programs, Client Machine Configuration Files, Installing and Configuring UNIX Client Machines, Installing and Configuring UNIX Client Machines
@subsection Client Programs
-The Kerberized client programs are @code{login.krb5}, @code{rlogin},
-@code{telnet}, @code{ftp}, @code{rcp}, @code{rsh}, @code{kinit},
-@code{klist}, @code{kdestroy}, @code{kpasswd}, @code{ksu}, and
-@code{krb524init}. All of these programs are in the directory
-@code{@value{ROOTDIR}/bin}, except for @code{login.krb5} which is in
-@code{@value{ROOTDIR}/sbin}.
-
-You will probably want to have your users put @code{@value{ROOTDIR}/bin}
-ahead of @code{/bin} and @code{/usr/bin} in their paths, so they will by
-default get the @value{PRODUCT} versions of @code{rlogin},
-@code{telnet}, @code{ftp}, @code{rcp}, and @code{rsh}.
+The Kerberized client programs are @code{kinit}, @code{klist},
+@code{kdestroy}, @code{kpasswd}, and @code{ksu}. All of these programs
+are in the directory @code{@value{ROOTDIR}/bin}.
@value{COMPANY} recommends that you use @code{login.krb5} in place of
@code{/bin/login} to give your users a single-sign-on system. You will
they log in.
You will also need to educate your users to use the ticket management
-programs @code{kinit},
-@c @code{krb524init},
-@code{klist}, @code{kdestroy}, and to use the Kerberos programs
-@c @code{pfrom},
-@code{ksu}, and @code{kpasswd} in place of their non-Kerberos
-counterparts
-@c @code{from}
-@code{su}, @code{passwd}, and @code{rdist}.
+programs @code{kinit}, @code{klist}, @code{kdestroy}, and to use the
+Kerberos programs @code{ksu} and @code{kpasswd} in place of their
+non-Kerberos counterparts @code{su} and @code{passwd}.
@node Client Machine Configuration Files, , Client Programs, Installing and Configuring UNIX Client Machines
@subsection Client Machine Configuration Files
@smallexample
@group
-#
-# Note --- if you are using Kerberos V4 and you either:
-#
-# (a) haven't converted all your master or slave KDCs to V5, or
-#
-# (b) are worried about inter-realm interoperability with other KDC's
-# that are still using V4
-#
-# you will need to switch the "kerberos" service to port 750 and create a
-# "kerberos-sec" service on port 88.
-#
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{DefaultKadmindPort}/tcp # Kerberos 5 admin/changepw
kerberos-adm @value{DefaultKadmindPort}/udp # Kerberos 5 admin/changepw
krb5_prop @value{DefaultKrbPropPort}/tcp # Kerberos slave propagation
-@c kpop 1109/tcp # Pop with Kerberos
-eklogin @value{DefaultEkloginPort}/tcp # Kerberos auth. & encrypted rlogin
krb524 @value{DefaultKrb524Port}/tcp # Kerberos 5 to 4 ticket translator
@end group
@end smallexample
-@noindent As described in the comments in the above code, if your master
-KDC or any of your slave KDCs is running Kerberos V4, (or if you will be
-authenticating to any Kerberos V4 KDCs in another realm) you will need
-to switch the port number for @code{kerberos} to 750 and create a
-@code{kerberos-sec} service (tcp and udp) on port 88, so the Kerberos
-V4 KDC(s) will continue to work properly.
-
@menu
* Mac OS X Configuration::
@end menu
@value{PRODUCT}'s single sign-on capability.
@menu
-* Server Programs::
-* Server Configuration Files::
* The Keytab File::
* Some Advice about Secure Hosts::
@end menu
-@node Server Programs, Server Configuration Files, UNIX Application Servers, UNIX Application Servers
-@subsection Server Programs
-
-Just as @value{PRODUCT} provided its own Kerberos-enhanced versions of
-client UNIX network programs, @value{PRODUCT} also provides
-Kerberos-enhanced versions of server UNIX network daemons. These are
-@code{ftpd}, @code{klogind}, @code{kshd}, and @code{telnetd}.
-@c @code{popper},
-These programs are installed in the directory
-@code{@value{ROOTDIR}/sbin}. You may want to add this directory to
-root's path.
-
-@node Server Configuration Files, The Keytab File, Server Programs, UNIX Application Servers
-@subsection Server Configuration Files
-
-For a @emph{secure} server, make the following changes to
-@code{/etc/inetd.conf}:
-
-Find and comment out any lines for the services @code{ftp},
-@code{telnet}, @code{shell}, @code{login}, and @code{exec}.
-
-@need 1800
-Add the following lines. (Note: each line beginning with @result{} is
-a continuation of the previous line.)
-
-@smallexample
-@group
-klogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
-@result{} klogind -k -c
-eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
-@result{} klogind -k -c -e
-kshell stream tcp nowait root @value{ROOTDIR}/sbin/kshd
-@result{} kshd -k -c -A
-ftp stream tcp nowait root @value{ROOTDIR}/sbin/ftpd
-@result{} ftpd -a
-telnet stream tcp nowait root @value{ROOTDIR}/sbin/telnetd
-@result{} telnetd -a valid
-@end group
-@end smallexample
-
-For an @emph{insecure} server, make the following changes instead to
-@code{/etc/inetd.conf}:
-
-@need 1800
-Find and comment out any lines for the services @code{ftp} and
-@code{telnet}.
-
-Add the following lines. (Note: each line beginning with @result{} is
-a continuation of the previous line.)
-@smallexample
-@group
-klogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
-@result{} klogind -k -c
-eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind
-@result{} klogind -k -c -e
-kshell stream tcp nowait root @value{ROOTDIR}/sbin/kshd
-@result{} kshd -k -c -A
-ftp stream tcp nowait root @value{ROOTDIR}/sbin/ftpd
-@result{} ftpd
-telnet stream tcp nowait root @value{ROOTDIR}/sbin/telnetd
-@result{} telnetd -a none
-@end group
-@end smallexample
-
-@node The Keytab File, Some Advice about Secure Hosts, Server Configuration Files, UNIX Application Servers
+@node The Keytab File, Some Advice about Secure Hosts, UNIX Application Servers, UNIX Application Servers
@subsection The Keytab File
All Kerberos server machines need a @dfn{keytab} file, called
If you generate the keytab file on another host, you need to get a copy
of the keytab file onto the destination host (@code{trillium}, in the
-above example) without sending it unencrypted over the network. If you
-have installed the @value{PRODUCT} client programs, you can use
-encrypted @code{rcp}.
+above example) without sending it unencrypted over the network.
@node Some Advice about Secure Hosts, , The Keytab File, UNIX Application Servers
@subsection Some Advice about Secure Hosts
possible attack, but it is worth noting some of the larger holes and how
to close them.
-As stated earlier in this section, @value{COMPANY} recommends that on a
-secure host, you disable the standard @code{ftp}, @code{login},
-@code{telnet}, @code{shell}, and @code{exec} services in
-@code{/etc/inetd.conf}. We also recommend that secure hosts have an empty
-@code{/etc/hosts.equiv} file and that there not be a @code{.rhosts} file
-in @code{root}'s home directory. You can grant Kerberos-authenticated
-root access to specific Kerberos principals by placing those principals
-in the file @code{.k5login} in root's home directory.
-
We recommend that backups of secure machines exclude the keytab file
(@code{/etc/krb5.keytab}). If this is not possible, the backups should
at least be done locally, rather than over a network, and the backup
tapes should be physically secured.
-Finally, the keytab file and any programs run by root, including the
+The keytab file and any programs run by root, including the
@value{PRODUCT} binaries, should be kept on local disk. The keytab file
should be readable only by root.
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
+@node Bug Reports for Kerberos V5, Copyright, Upgrading Existing Kerberos V5 Installations, Top
@chapter Bug Reports for @value{PRODUCT}
@include send-pr.texinfo
+@node Copyright, , Bug Reports for Kerberos V5, Top
+@appendix Copyright
+@include copyright.texinfo
+
@contents
@bye
projects / krb5.git / blobdiff