+++ /dev/null
-@value{PRODUCT} uses a configuration system built using the Free
-Software Foundation's @samp{autoconf} program. This system makes
-Kerberos V5 much simpler to build and reduces the amount of effort
-required in porting Kerberos V5 to a new platform.
-
-@menu
-* Organization of the Source Directory:: Description of the source tree.
-* Build Requirements:: How much disk space, etc. you need to
- build Kerberos.
-* Unpacking the Sources:: Preparing the source tree.
-* Doing the Build:: Compiling Kerberos.
-* Installing the Binaries:: Installing the compiled binaries.
-* Testing the Build:: Making sure Kerberos built correctly.
-* Options to Configure:: Command-line options to Configure
-* osconf.h:: Header file-specific configurations
-* Shared Library Support:: Building Shared Libraries for Kerberos V5
-* OS Incompatibilities:: Special cases to watch for.
-* Using Autoconf:: Modifying Kerberos V5's
- configuration scripts.
-@end menu
-
-@node Organization of the Source Directory, Build Requirements, Building Kerberos V5, Building Kerberos V5
-@section Organization of the Source Directory
-
-Below is a brief overview of the organization of the complete source
-directory. More detailed descriptions follow.
-
-@table @b
-@itemx appl
-applications with @value{PRODUCT} extensions
-@itemx clients
-@value{PRODUCT} user programs
-@itemx gen-manpages
-manpages for @value{PRODUCT} and the @value{PRODUCT} login program
-@itemx include
-include files
-@itemx kadmin
-administrative interface to the Kerberos master database
-@itemx kdc
-the @value{PRODUCT} Authentication Service and Key Distribution Center
-@itemx krb524
-utilities for converting between Kerberos 4 and Kerberos 5
-@itemx lib
-libraries for use with/by @value{PRODUCT}
-@itemx mac
-source code for building @value{PRODUCT} on MacOS
-@itemx prototype
-templates for source code files
-@itemx slave
-utilities for propagating the database to slave KDCs
-@itemx tests
-test suite
-@itemx util
-various utilities for building/configuring the code, sending bug reports, etc.
-@itemx windows
-source code for building @value{PRODUCT} on Windows (see windows/README)
-@end table
-
-@menu
-* The appl Directory::
-* The clients Directory::
-* The gen-manpages Directory::
-* The include Directory::
-* The kadmin Directory::
-* The kdc Directory::
-* The krb524 Directory::
-* The lib Directory::
-* The prototype Directory::
-* The slave Directory::
-* The util Directory::
-@end menu
-
-@node The appl Directory, The clients Directory, Organization of the Source Directory, Organization of the Source Directory
-@subsection The appl Directory
-
-The @i{appl} directory contains sample Kerberos application client and
-server programs. In previous releases, it contained Kerberized versions
-of remote access daemons, but those have now been moved to a separate
-project.
-
-@node The clients Directory, The gen-manpages Directory, The appl Directory, Organization of the Source Directory
-@subsection The clients Directory
-
-This directory contains the code for several user-oriented programs.
-
-@table @b
-@itemx kdestroy
-This program destroys the user's active Kerberos authorization tickets.
-@value{COMPANY} recommends that users @code{kdestroy} before logging out.
-
-@itemx kinit
-This program prompts users for their Kerberos principal name and password,
-and attempts to get an initial ticket-granting-ticket for that principal.
-
-@itemx klist
-This program lists the Kerberos principal and Kerberos tickets held in
-a credentials cache, or the keys held in a keytab file.
-
-@itemx kpasswd
-This program changes a user's Kerberos password.
-
-@itemx ksu
-This program is a Kerberized version of the @code{su} program that is
-meant to securely change the real and effective user ID to that of the
-target user and to create a new security context.
-
-@itemx kvno
-This program acquires a service ticket for the specified Kerberos
-principals and prints out the key version numbers of each.
-@end table
-
-@node The gen-manpages Directory, The include Directory, The clients Directory, Organization of the Source Directory
-@subsection The gen-manpages Directory
-
-There are two manual pages in this directory. One is an introduction
-to the Kerberos system. The other describes the @code{.k5login} file
-which allows users to give access with their UID to other users
-authenticated by the Kerberos system.
-
-@node The include Directory, The kadmin Directory, The gen-manpages Directory, Organization of the Source Directory
-@subsection The include Directory
-
-This directory contains the @i{include} files needed to build the
-Kerberos system.
-
-@node The kadmin Directory, The kdc Directory, The include Directory, Organization of the Source Directory
-@subsection The kadmin Directory
-
-In this directory is the code for the utilities @code{kadmin},
-@code{kadmin.local}, @code{kdb5_util}, and @code{ktutil}.
-@code{ktutil} is the Kerberos keytab file maintenance utility from
-which a Kerberos administrator can read, write, or edit entries in a
-Kerberos V5 keytab or Kerberos V4 srvtab. @code{kadmin} and
-@code{kadmin.local} are command-line interfaces to the Kerberos V5 KADM5
-administration system. @code{kadmin.local} runs on the master KDC and
-does not use Kerberos to authenticate to the database, while
-@code{kadmin} uses Kerberos authentication and an encrypted RPC. The
-two provide identical functionalities, which allow administrators to
-modify the database of Kerberos principals. @code{kdb5_util} allows
-administrators to perform low-level maintenance procedures on Kerberos
-and the KADM5 database. With this utility, databases can be created,
-destroyed, or dumped to and loaded from ASCII files. It can also be
-used to create master key stash files.
-
-@node The kdc Directory, The krb524 Directory, The kadmin Directory, Organization of the Source Directory
-@subsection The kdc Directory
-
-This directory contains the code for the @code{krb5kdc} daemon, the
-Kerberos Authentication Service and Key Distribution Center.
-
-@node The krb524 Directory, The lib Directory, The kdc Directory, Organization of the Source Directory
-@subsection The krb524 Directory
-
-This directory contains the code for @code{krb524}, a service that
-converts Kerberos V5 credentials into Kerberos V4 credentials suitable
-for use with applications that for whatever reason do not use V5
-directly.
-
-@node The lib Directory, The prototype Directory, The krb524 Directory, Organization of the Source Directory
-@subsection The lib Directory
-
-The @i{lib} directory contain 10 subdirectories as well as some
-definition and glue files. The @i{crypto} subdirectory contains the
-Kerberos V5 encryption library. The @i{des425} subdirectory exports
-the Kerberos V4 encryption API, and translates these functions into
-calls to the Kerberos V5 encryption API. The @i{gssapi} library
-contains the Generic Security Services API, which is a library of
-commands to be used in secure client-server communication. The
-@i{kadm5} directory contains the libraries for the KADM5 administration
-utilities. The Kerberos 5 database libraries are contained in
-@i{kdb}. The directories @i{krb4} and @i{krb5} contain the Kerberos 4
-and Kerberos 5 APIs, respectively. The @i{rpc} directory contains the
-API for the Kerberos Remote Procedure Call protocol.
-
-@node The prototype Directory, The slave Directory, The lib Directory, Organization of the Source Directory
-@subsection The prototype Directory
-
-This directory contains several template files. The @code{prototype.h}
-and @code{prototype.c} files contain the MIT copyright message and a
-placeholder for the title and description of the file.
-@code{prototype.h} also has a short template for writing @code{ifdef}
-and @code{ifndef} preprocessor statements. The @code{getopt.c} file
-provides a template for writing code that will parse the options with
-which a program was called.
-
-@node The slave Directory, The util Directory, The prototype Directory, Organization of the Source Directory
-@subsection The slave Directory
-
-This directory contains code which allows for the propagation of the
-Kerberos principal database from the master KDC to slave KDCs over an
-encrypted, secure channel. @code{kprop} is the program which actually
-propagates the database dump file. @code{kpropd} is the Kerberos V5
-slave KDC update server which accepts connections from the @code{kprop}
-program. @code{kslave_update} is a script that takes the name of a
-slave server, and propagates the database to that server if the
-database has been modified since the last dump or if the database has
-been dumped since the last propagation.
-
-@node The util Directory, , The slave Directory, Organization of the Source Directory
-@subsection The util Directory
-
-This directory contains several utility programs and libraries. The
-programs used to configure and build the code, such as @code{autoconf},
-@code{lndir}, @code{kbuild}, @code{reconf}, and @code{makedepend},
-are in this directory. The @i{profile} directory contains most of the
-functions which parse the Kerberos configuration files (@code{krb5.conf}
-and @code{kdc.conf}). Also in this directory are the Kerberos error table
-library and utilities (@i{et}), the Sub-system library and utilities
-(@i{ss}), database utilities (@i{db2}), pseudo-terminal utilities
-(@i{pty}), bug-reporting program @code{send-pr}, and a generic
-support library @code{support} used by several of our other libraries.
-
-@node Build Requirements, Unpacking the Sources, Organization of the Source Directory, Building Kerberos V5
-@section Build Requirements
-
-In order to build Kerberos V5, you will need approximately 60-70
-megabytes of disk space. The exact amount will vary depending on the
-platform and whether the distribution is compiled with debugging symbol
-tables or not.
-
-Your C compiler must conform to ANSI C (ISO/IEC 9899:1990, ``c89'').
-Some operating systems do not have an ANSI C compiler, or their
-default compiler requires extra command-line options to enable ANSI C
-conformance.
-
-If you wish to keep a separate @dfn{build tree}, which contains the compiled
-@file{*.o} file and executables, separate from your source tree, you
-will need a @samp{make} program which supports @samp{VPATH}, or
-you will need to use a tool such as @samp{lndir} to produce a symbolic
-link tree for your build tree.
-
-@c Library support...
-
-@node Unpacking the Sources, Doing the Build, Build Requirements, Building Kerberos V5
-@section Unpacking the Sources
-
-The first step in each of these build procedures is to unpack the
-source distribution. The Kerberos V5 distribution comes in a tar file,
-generally named @file{krb5-@value{RELEASE}.tar}, which contains a
-compressed tar file consisting of the sources for all of Kerberos
-(generally @file{krb5-@value{RELEASE}.tar.gz}) and a PGP signature for
-this source tree (generally @file{krb5-@value{RELEASE}.tar.gz.asc}).
-@value{COMPANY} highly recommends that you verify the integrity of the
-source code using this signature.
-
-Unpack the compressed tar file in some directory, such as
-@file{/u1/krb5-@value{RELEASE}}. (In the rest of this document, we
-will assume that you have chosen to unpack the Kerberos V5 source
-distribution in this directory. Note that the tarfiles will by default
-all unpack into the @file{./krb5-@value{RELEASE}} directory, so that if
-your current directory is @file{/u1} when you unpack the tarfiles, you
-will get @file{/u1/krb5-@value{RELEASE}/src}, etc.)
-
-
-@node Doing the Build, Installing the Binaries, Unpacking the Sources, Building Kerberos V5
-@section Doing the Build
-
-You have a number of different options in how to build Kerberos. If you
-only need to build Kerberos for one platform, using a single directory
-tree which contains both the source files and the object files is the
-simplest. However, if you need to maintain Kerberos for a large number
-of platforms, you will probably want to use separate build trees for
-each platform. We recommend that you look at @ref{OS
-Incompatibilities}, for notes that we have on particular operating
-systems.
-
-@menu
-* Building Within a Single Tree::
-* Building with Separate Build Directories::
-* Building using lndir::
-@end menu
-
-@node Building Within a Single Tree, Building with Separate Build Directories, Doing the Build, Doing the Build
-@subsection Building Within a Single Tree
-
-If you don't want separate build trees for each architecture, then
-use the following abbreviated procedure.
-
-@enumerate
-@item
- @code{cd /u1/krb5-@value{RELEASE}/src}
-@item
- @code{./configure}
-@item
- @code{make}
-@end enumerate
-
-That's it!
-
-@node Building with Separate Build Directories, Building using lndir, Building Within a Single Tree, Doing the Build
-@subsection Building with Separate Build Directories
-
-If you wish to keep separate build directories for each platform, you
-can do so using the following procedure. (Note, this requires that your
-@samp{make} program support @samp{VPATH}. GNU's make will provide this
-functionality, for example.) If your @samp{make} program does not
-support this, see the next section.
-
-For example, if you wish to create a build directory for @code{pmax} binaries
-you might use the following procedure:
-
-@enumerate
-@item
-@code{mkdir /u1/krb5-@value{RELEASE}/pmax}
-@item
- @code{cd /u1/krb5-@value{RELEASE}/pmax}
-@item
- @code{../src/configure}
-@item
- @code{make}
-@end enumerate
-
-@node Building using lndir, , Building with Separate Build Directories, Doing the Build
-@subsection Building Using @samp{lndir}
-
-If you wish to keep separate build directories for each platform, and
-you do not have access to a @samp{make} program which supports @samp{VPATH},
-all is not lost. You can use the @samp{lndir} program to create
-symbolic link trees in your build directory.
-
-For example, if you wish to create a build directory for solaris binaries
-you might use the following procedure:
-
-@enumerate
-@item
- @code{mkdir /u1/krb5-@value{RELEASE}/solaris}
-@item
- @code{cd /u1/krb5-@value{RELEASE}/solaris}
-@item
- @code{/u1/krb5-@value{RELEASE}/src/util/lndir `pwd`/../src}
-@item
- @code{./configure}
-@item
- @code{make}
-@end enumerate
-
-You must give an absolute pathname to @samp{lndir} because it has a bug that
-makes it fail for relative pathnames. Note that this version differs
-from the latest version as distributed and installed by the XConsortium
-with X11R6. Either version should be acceptable.
-
-@node Installing the Binaries, Testing the Build, Doing the Build, Building Kerberos V5
-@section Installing the Binaries
-
-Once you have built Kerberos, you should install the binaries. You
-can do this by running:
-
-@example
-% make install
-@end example
-
-If you want to install the binaries into a destination directory that
-is not their final destination, which may be convenient if you want to
-build a binary distribution to be deployed on multiple hosts, you may
-use:
-
-@example
-% make install DESTDIR=/path/to/destdir
-@end example
-
-This will install the binaries under @code{DESTDIR/PREFIX}, e.g., the
-user programs will install into @code{DESTDIR/PREFIX/bin}, the
-libraries into @code{DESTDIR/PREFIX/lib}, etc.
-
-Note that if you want to test the build (see @ref{Testing the Build}),
-you usually do not need to do a @code{make install} first.
-
-Some implementations of @samp{make} allow multiple commands to be run in
-parallel, for faster builds. We test our Makefiles in parallel builds with
-GNU @samp{make} only; they may not be compatible with other parallel build
-implementations.
-
-@node Testing the Build, Options to Configure, Installing the Binaries, Building Kerberos V5
-@section Testing the Build
-
-The Kerberos V5 distribution comes with built-in regression tests. To
-run them, simply type the following command while in the top-level build
-directory (i.e., the directory where you sent typed @samp{make} to start
-building Kerberos; see @ref{Doing the Build}.):
-
-@example
-% make check
-@end example
-
-However, there are several prerequisites that must be satisfied first:
-
-@itemize @bullet
-@item
-Configure and build Kerberos with Tcl support. Tcl is used to drive the
-test suite. This often means passing @code{--with-tcl} to configure to
-tell it the location of the Tcl configuration script. (See
-@xref{Options to Configure}.)
-
-@item
-On some operating systems, you have to run @samp{make install} before
-running @samp{make check}, or the test suite will pick up installed
-versions of Kerberos libraries rather than the newly built ones. You
-can install into a prefix that isn't in the system library search path,
-though. Alternatively, you can configure with @code{--disable-rpath},
-which renders the build tree less suitable for installation, but allows
-testing without interference from previously installed libraries.
-
-@item
-In order to test the RPC layer, the local system has to be running the
-@command{portmap} daemon and it has to be listening to the regular
-network interface (not just localhost).
-@end itemize
-
-@menu
-* The DejaGnu Tests::
-* The KADM5 Tests::
-@end menu
-
-@node The DejaGnu Tests, The KADM5 Tests, Testing the Build, Testing the Build
-@subsection The DejaGnu Tests
-
-Some of the built-in regression tests are setup to use the DejaGnu
-framework for running tests. These tests tend to be more comprehensive
-than the normal built-in tests as they setup test servers and test
-client/server activities.
-
-DejaGnu may be found wherever GNU software is archived.
-
-@node The KADM5 Tests, , The DejaGnu Tests, Testing the Build
-@subsection The KADM5 Tests
-
-Regression tests for the KADM5 system, including the GSS-RPC, KADM5
-client and server libraries, and kpasswd, are also included in this
-release. Each set of KADM5 tests is contained in a sub-directory called
-@code{unit-test} directly below the system being tested. For example,
-lib/rpc/unit-test contains the tests for GSS-RPC. The tests are all
-based on DejaGnu (but they are not actually called part of "The DejaGnu
-tests," whose naming predates the inclusion of the KADM5 system). In
-addition, they require the Tool Command Language (TCL) header files and
-libraries to be available during compilation and some of the tests also
-require Perl in order to operate. If all of these resources are not
-available during configuration, the KADM5 tests will not run. The TCL
-installation directory can be specified with the @code{--with-tcl}
-configure option. (See @xref{Options to Configure}.) The runtest and
-perl programs must be in the current execution path.
-
-If you install DejaGnu, TCL, or Perl after configuring and building
-Kerberos and then want to run the KADM5 tests, you will need to
-re-configure the tree and run @code{make} at the top level again to make
-sure all the proper programs are built. To save time, you actually only
-need to reconfigure and build in the directories src/kadmin/testing,
-src/lib/rpc, src/lib/kadm5.
-
-@node Options to Configure, osconf.h, Testing the Build, Building Kerberos V5
-@section Options to Configure
-
-There are a number of options to @samp{configure} which you can use to
-control how the Kerberos distribution is built. The following table
-lists the most commonly used options to Kerberos V5's @samp{configure}
-program.
-
-@table @code
-
-@item --help
-
-Provides help to configure. This will list the set of commonly used
-options for building Kerberos.
-
-@item --prefix=PREFIX
-
-By default, Kerberos will install the package's files rooted at
-`/usr/local' as in `/usr/local/bin', `/usr/local/sbin', etc. If you
-desire a different location, use this option.
-
-@item --exec-prefix=EXECPREFIX
-
-This option allows one to separate the architecture independent programs
-from the configuration files and manual pages.
-
-@item --localstatedir=LOCALSTATEDIR
-
-This option sets the directory for locally modifiable single-machine
-data. In Kerberos, this mostly is useful for setting a location for the
-KDC data files, as they will be installed in
-@code{LOCALSTATEDIR/krb5kdc}, which is by default
-@code{PREFIX/var/krb5kdc}.
-
-@item CC=COMPILER
-
-Use @code{COMPILER} as the C compiler.
-
-@item CFLAGS=FLAGS
-
-Use @code{FLAGS} as the default set of C compiler flags.
-
-Note that if you use the native Ultrix compiler on a
-DECstation you are likely to lose if you pass no flags to cc; md4.c
-takes an estimated 3,469 billion years to compile if you provide neither
-the @samp{-g} flag nor the @samp{-O} flag to @samp{cc}.
-
-@item CPPFLAGS=CPPOPTS
-
-Use @code{CPPOPTS} as the default set of C preprocessor flags. The most
-common use of this option is to select certain @code{#define}'s for use
-with the operating system's include files.
-
-@item LD=LINKER
-
-Use @code{LINKER} as the default loader if it should be different from C
-compiler as specified above.
-
-@item LDFLAGS=LDOPTS
-
-This option allows one to specify optional arguments to be passed to the
-linker. This might be used to specify optional library paths.
-
-@item --with-krb4
-
-This option enables Kerberos V4 backwards compatibility using the
-builtin Kerberos V4 library.
-
-@item --with-krb4=KRB4DIR
-
-This option enables Kerberos V4 backwards compatibility using a
-pre-existing Kerberos V4 installation. The directory specified by
-@code{KRB4DIR} specifies where the V4 header files should be found
-(@file{KRB4DIR/include}) as well as where the V4 Kerberos library should
-be found (@file{KRB4DIR/lib}).
-
-@item --without-krb4
-
-Disables Kerberos V4 backwards compatibility. This prevents Kerberos V4
-clients from using the V5 services including the KDC. This would be
-useful if you know you will never install or need to interact with V4
-clients.
-
-@item --with-netlib[=libs]
-
-Allows for suppression of or replacement of network libraries. By
-default, Kerberos V5 configuration will look for @code{-lnsl} and
-@code{-lsocket}. If your operating system has a broken resolver library
-(see @ref{Solaris versions 2.0 through 2.3}) or fails to pass the tests in
-@file{src/tests/resolv} you will need to use this option.
-
-@item --with-tcl=TCLPATH
-
-Some of the unit-tests in the build tree rely upon using a program in
-Tcl. The directory specified by @code{TCLPATH} specifies where the Tcl
-header file (@file{TCLPATH/include/tcl.h} as well as where the Tcl
-library should be found (@file{TCLPATH/lib}).
-
-@item --enable-shared
-
-This option will turn on the building and use of shared library objects
-in the Kerberos build. This option is only supported on certain
-platforms.
-
-@item --enable-dns
-@item --enable-dns-for-kdc
-@item --enable-dns-for-realm
-
-Enable the use of DNS to look up a host's Kerberos realm, or a realm's
-KDCs, if the information is not provided in krb5.conf. See @ref{Hostnames
-for the Master and Slave KDCs} for information about using DNS to
-locate the KDCs, and @ref{Mapping Hostnames onto Kerberos Realms} for
-information about using DNS to determine the default realm. By default,
-DNS lookups are enabled for the former but not for the latter.
-
-@item --disable-kdc-lookaside-cache
-
-Disables the cache in the KDC which detects retransmitted client
-requests and resends the previous responses to them.
-
-@item --with-system-et
-
-Use an installed version of the error-table support software, the
-@samp{compile_et} program, the @file{com_err.h} header file and the
-@file{com_err} library. If these are not in the default locations,
-you may wish to specify @code{CPPFLAGS=-I/some/dir} and
-@code{LDFLAGS=-L/some/other/dir} options at configuration time as
-well.
-
-If this option is not given, a version supplied with the Kerberos
-sources will be built and installed along with the rest of the
-Kerberos tree, for Kerberos applications to link against.
-
-@item --with-system-ss
-
-Use an installed version of the subsystem command-line interface
-software, the @samp{mk_cmds} program, the @file{ss/ss.h} header file
-and the @file{ss} library. If these are not in the default locations,
-you may wish to specify @code{CPPFLAGS=-I/some/dir} and
-@code{LDFLAGS=-L/some/other/dir} options at configuration time as
-well. See also the @samp{SS_LIB} option.
-
-If this option is not given, the @file{ss} library supplied with the
-Kerberos sources will be compiled and linked into those programs that
-need it; it will not be installed separately.
-
-@item SS_LIB=libs...
-
-If @samp{-lss} is not the correct way to link in your installed
-@file{ss} library, for example if additional support libraries are
-needed, specify the correct link options here. Some variants of this
-library are around which allow for Emacs-like line editing, but
-different versions require different support libraries to be
-explicitly specified.
-
-This option is ignored if @samp{--with-system-ss} is not specified.
-
-@item --with-system-db
-
-Use an installed version of the Berkeley DB package, which must
-provide an API compatible with version 1.85. This option is
-@emph{unsupported} and untested. In particular, we do not know if the
-database-rename code used in the dumpfile load operation will behave
-properly.
-
-If this option is not given, a version supplied with the Kerberos
-sources will be built and installed. (We are not updating this
-version at this time because of licensing issues with newer versions
-that we haven't investigated sufficiently yet.)
-
-@item DB_HEADER=headername.h
-
-If @samp{db.h} is not the correct header file to include to compile
-against the Berkeley DB 1.85 API, specify the correct header file name
-with this option. For example, @samp{DB_HEADER=db3/db_185.h}.
-
-@item DB_LIB=libs...
-
-If @samp{-ldb} is not the correct library specification for the
-Berkeley DB library version to be used, override it with this option.
-For example, @samp{DB_LIB=-ldb-3.3}.
-
-@item --with-crypto-impl=IMPL
-
-Use specified crypto implementation in lieu of the default builtin.
-Currently only one alternative crypto-system openssl is available and
-it requires version 1.0.0 or higher of OpenSSL.
-
-@end table
-
-For example, in order to configure Kerberos on a Solaris machine using
-the @samp{suncc} compiler with the optimizer turned on, run the configure
-script with the following options:
-
-@example
-% ./configure CC=suncc CFLAGS=-O
-@end example
-
-For a slightly more complicated example, consider a system where
-several packages to be used by Kerberos are installed in
-@samp{/usr/foobar}, including Berkeley DB 3.3, and an @samp{ss}
-library that needs to link against the @samp{curses} library. The
-configuration of Kerberos might be done thus:
-
-@example
-% ./configure CPPFLAGS=-I/usr/foobar/include LDFLAGS=-L/usr/foobar/lib \
- --with-system-et --with-system-ss --with-system-db \
- SS_LIB='-lss -lcurses' \
- DB_HEADER=db3/db_185.h DB_LIB=-ldb-3.3
-@end example
-
-In previous releases, @code{--with-} options were used to specify the
-compiler and linker and their options.
-
-@node osconf.h, Shared Library Support, Options to Configure, Building Kerberos V5
-@section @file{osconf.h}
-
-There is one configuration file which you may wish to edit to control
-various compile-time parameters in the Kerberos distribution:
-@file{include/stock/osconf.h}. The list that follows is by no means
-complete, just some of the more interesting variables.
-
-Please note: The former configuration file @file{config.h} no longer
-exists as its functionality has been merged into the auto-configuration
-process. @xref{Options to Configure}.
-
-
-@table @code
-
-@item DEFAULT_PROFILE_PATH
-
-The pathname to the file which contains the profiles for the known realms,
-their KDCs, etc. The default value is @value{DefaultDefaultProfilePath}.
-
-The profile file format is no longer the same format as Kerberos V4's
-@file{krb.conf} file.
-
-@item DEFAULT_KEYTAB_NAME
-
-The type and pathname to the default server keytab file (the
-equivalent of Kerberos V4's @file{/etc/srvtab}). The default is
-@value{DefaultDefaultKeytabName}.
-
-@item DEFAULT_KDC_ENCTYPE
-
-The default encryption type for the KDC. The default value is
-@value{DefaultMasterKeyType}.
-
-@item KDCRCACHE
-
-The name of the replay cache used by the KDC. The default value is
-@value{DefaultKDCRCache}.
-
-@item RCTMPDIR
-
-The directory which stores replay caches. The default is to try
-@value{DefaultRCTmpDirs}.
-
-@item DEFAULT_KDB_FILE
-
-The location of the default database. The default value is
-@value{DefaultDatabaseName}.
-
-@end table
-
-@node Shared Library Support, OS Incompatibilities, osconf.h, Building Kerberos V5
-@section Shared Library Support
-
-Shared library support is provided for a few operating systems. There
-are restrictions as to which compiler to use when using shared
-libraries. In all cases, executables linked with the shared libraries in
-this build process will have built in the location of the libraries,
-therefore obliterating the need for special LD_LIBRARY_PATH, et al environment
-variables when using the programs. Except where noted, multiple versions
-of the libraries may be installed on the same system and continue to
-work.
-
-Currently the supported platforms are Solaris 2.6-2.9 (aka SunOS
-5.6-5.9), Irix 6.5, Redhat Linux, MacOS 8-10, and Microsoft Windows
-(using DLLs).
-
-Shared library support has been tested on the following platforms but
-not exhaustively (they have been built but not necessarily tested in an
-installed state): Tru64 (aka Alpha OSF/1 or Digital Unix) 4.0, and
-HP/UX 10.20.
-
-Platforms for which there is shared library support but not significant
-testing include FreeBSD, OpenBSD, AIX (4.3.3), Linux, NetBSD 1.4.x
-(i386).
-
-To enable shared libraries on the above platforms, run the configure
-script with the option @samp{--enable-shared}.
-
-@ifset notdef
-
-XXX What does this mean?
-
-One special note is that if the Kerberos V4 compatibility is compiled
-in, you @b{must not} specify an alternate Kerberos V4 library from the
-one in the tree or you will be missing references.
-
-@end ifset
-
-@node OS Incompatibilities, Using Autoconf, Shared Library Support, Building Kerberos V5
-@section Operating System Incompatibilities
-
-This section details operating system incompatibilities with Kerberos V5
-which have been reported to the developers at MIT. If you find
-additional incompatibilities, and/or discover workarounds to such
-problems, please send a report via the @code{krb5-send-pr} program.
-Thanks!
-
-@menu
-* AIX::
-* Alpha OSF/1 V1.3::
-* Alpha OSF/1 V2.0::
-* Alpha OSF/1 V4.0::
-* BSDI::
-* HPUX::
-* Solaris versions 2.0 through 2.3::
-* Solaris 2.X::
-* Solaris 9::
-* SGI Irix 5.X::
-* Ultrix 4.2/3::
-@end menu
-
-@node AIX, Alpha OSF/1 V1.3, OS Incompatibilities, OS Incompatibilities
-@subsection AIX
-
-The AIX 3.2.5 linker dumps core trying to build a shared
-@samp{libkrb5.a} produced with the GNU C compiler. The native AIX
-compiler works fine. This problem is fixed using the AIX 4.1 linker.
-
-@node Alpha OSF/1 V1.3, Alpha OSF/1 V2.0, AIX, OS Incompatibilities
-@subsection Alpha OSF/1 V1.3
-
-Using the native compiler, compiling with the @samp{-O} compiler flag
-causes the @code{asn.1} library to be compiled incorrectly.
-
-Using GCC version 2.6.3 or later instead of the native compiler will also work
-fine, both with or without optimization.
-
-@node Alpha OSF/1 V2.0, Alpha OSF/1 V4.0, Alpha OSF/1 V1.3, OS Incompatibilities
-@subsection Alpha OSF/1 V2.0
-
-There used to be a bug when using the native compiler in compiling
-@file{md4.c} when compiled without either the @samp{-O} or @samp{-g}
-compiler options. We have changed the code and there is no problem
-under V2.1, but we do not have access to V2.0 to test and see if the
-problem would exist there. (We welcome feedback on this issue). There
-was never a problem in using GCC version 2.6.3.
-
-In version 3.2 and beyond of the operating system, we have not seen
-this sort of problem with the native compiler.
-
-@node Alpha OSF/1 V4.0, BSDI, Alpha OSF/1 V2.0, OS Incompatibilities
-@subsection Alpha OSF/1 (Digital UNIX) V4.0
-
-The C compiler provided with Alpha OSF/1 V4.0 (a.k.a. Digital UNIX)
-defaults to an extended K&R C mode, not ANSI C. You need to provide
-the @samp{-std} argument to the compiler (i.e., @samp{./configure
-CC='cc -std'}) to enable extended ANSI C mode. More recent versions
-of the operating system, such as 5.0, seem to have C compilers which
-default to @samp{-std}.
-
-@c @node Alpha Tru64 UNIX 5.0
-@c @subsection Alpha Tru64 UNIX 5.0
-@c ... login.krb5 problems
-
-@node BSDI, HPUX, Alpha OSF/1 V4.0, OS Incompatibilities
-@subsection BSDI
-
-BSDI versions 1.0 and 1.1 reportedly has a bad @samp{sed} which causes
-it to go into an infinite loop during the build. The work around is
-to use a @samp{sed} from somewhere else, such as GNU. (This may be
-true for some versions of other systems derived from BSD 4.4, such as
-NetBSD and FreeBSD.)
-
-@node HPUX, Solaris versions 2.0 through 2.3, BSDI, OS Incompatibilities
-@subsection HPUX
-
-The native (bundled) compiler for HPUX currently will not work,
-because it is not a full ANSI C compiler. The optional ANSI C
-compiler should work as long as you give it the @samp{-Ae} flag
-(i.e. @samp{./configure CC='cc -Ae'}). This is equivalent to
-@samp{./configure CC='c89 -D_HPUX_SOURCE'}, which was the previous
-recommendation. This has only been tested recently for HPUX 10.20.
-
-You will need to configure with @samp{--disable-shared
---enable-static}, because as of 1.4 we don't have support for HPUX
-shared library finalization routines, nor the option (yet) to ignore
-that lack of support (which means repeated
-@code{dlopen}/@code{dlclose} cycles on the Kerberos libraries may not
-be safe) and build the shared libraries anyways.
-
-You will also need to configure the build tree with
-@samp{--disable-thread-support} if you are on HPUX 10 and do not have
-the DCE development package installed, because that's where the
-@code{pthread.h} header file is found. (We don't know if our code
-will work with such a package installed, because according to some HP
-documentation, their @code{pthread.h} has to be included before any
-other header files, and our code doesn't do that.)
-
-If you use GCC, it may work, but some versions of GCC have omitted
-certain important preprocessor defines, like @code{__STDC_EXT__} and
-@code{__hpux}.
-
-@node Solaris versions 2.0 through 2.3, Solaris 2.X, HPUX, OS Incompatibilities
-@subsection Solaris versions 2.0 through 2.3
-
-The @code{gethostbyname()} routine is broken; it does not return a fully
-qualified domain name, even if you are using the Domain Name Service
-routines. Since Kerberos V5 uses the fully qualified domain name as the
-second component of a service principal (i.e,
-@samp{host/tsx-11.mit.edu@@ATHENA.MIT.EDU}), this causes problems for servers
-who try to figure out their own fully qualified domain name.
-
-Workarounds:
-
-@enumerate
-
-@item
- Supply your own resolver library. (such as bind-4.9.3pl1 available
-from ftp.vix.com)
-
-@item
- Upgrade to Solaris 2.4
-
-@item
- Make sure your /etc/nsswitch.conf has `files' before `dns' like:
-
-@example
-hosts: files dns
-@end example
-
-and then in /etc/hosts, make sure there is a line with your
-workstation's IP address and hostname, with the fully qualified domain
-name first. Example:
-
-@example
-18.172.1.4 dcl.mit.edu dcl
-@end example
-
-Note that making this change may cause other programs in your
-environment to break or behave differently.
-
-@end enumerate
-
-@node Solaris 2.X, Solaris 9, Solaris versions 2.0 through 2.3, OS Incompatibilities
-@subsection Solaris 2.X
-
-You @b{must} compile Kerberos V5 without the UCB compatibility
-libraries. This means that @file{/usr/ucblib} must not be in the
-LD_LIBRARY_PATH environment variable when you compile it. Alternatively
-you can use the @code{-i} option to @samp{cc}, by using the specifying
-@code{CFLAGS=-i} option to @samp{configure}.
-
-If you are compiling for a 64-bit execution environment, you may need
-to configure with the option @code{CFLAGS="-D_XOPEN_SOURCE=500
--D__EXTENSIONS__"}. This is not well tested; at MIT we work primarily
-with the 32-bit execution environment.
-
-@node Solaris 9, SGI Irix 5.X, Solaris 2.X, OS Incompatibilities
-@subsection Solaris 9
-
-Solaris 9 has a kernel race condition which causes the final output
-written to the slave side of a pty to be lost upon the final close()
-of the slave device. This causes the dejagnu-based tests to fail
-intermittently. A workaround exists, but requires some help from the
-scheduler, and the ``make check'' must be executed from a shell with
-elevated priority limits.
-
-Run something like
-
-@code{priocntl -s -c FX -m 30 -p 30 -i pid nnnn}
-
-as root, where @code{nnnn} is the pid of the shell whose priority
-limit you wish to raise.
-
-Sun has released kernel patches for this race condition. Apply patch
-117171-11 for sparc, or patch 117172-11 for x86. Later revisions of
-the patches should also work. It is not necessary to run ``make
-check'' from a shell with elevated priority limits once the patch has
-been applied.
-
-@node SGI Irix 5.X, Ultrix 4.2/3, Solaris 9, OS Incompatibilities
-@subsection SGI Irix 5.X
-
-If you are building in a tree separate from the source tree, the vendors
-version of make does not work properly with regards to
-@samp{VPATH}. It also has problems with standard inference rules in 5.2
-(not tested yet in 5.3) so one needs to use GNU's make.
-
-Under 5.2, there is a bug in the optional System V @code{-lsocket}
-library in which the routine @code{gethostbyname()} is broken. The
-system supplied version in @code{-lc} appears to work though so one may
-simply specify @code{--with-netlib} option to @samp{configure}.
-
-In 5.3, @code{gethostbyname()} is no longer present in @code{-lsocket} and
-is no longer an issue.
-
-@node Ultrix 4.2/3, , SGI Irix 5.X, OS Incompatibilities
-@subsection Ultrix 4.2/3
-
-The DEC MIPS platform currently will not support the native compiler,
-since the Ultrix compiler is not a full ANSI C compiler. You should use
-GCC instead.
-
-@ifset notdef
-
-On the DEC MIPS platform, using the native compiler, @file{md4.c} and
-@file{md5.c} can not be compiled with the optimizer set at level 1.
-That is, you must specify either @samp{CFLAGS=-O} and
-@samp{CFLAGS=-g} to configure. If you don't specify either, the
-compile will never complete.
-
-The optimizer isn't hung; it just takes an exponentially long time.
-Compiling 6 out of the 48 algorithmic steps takes 3 seconds; compiling 7
-steps takes 9 seconds; compiling 8 steps takes 27 seconds, and so on.
-Calculations estimate it will finish in approximately 3,469 billion
-years....
-
-Using GCC instead of the native compiler will also work fine, both with
-or without optimization.
-
-@end ifset
-
-@node Using Autoconf, , OS Incompatibilities, Building Kerberos V5
-@section Using @samp{Autoconf}
-
-(If you are not a developer, you can skip this section.)
-
-In most of the Kerberos V5 source directories, there is a
-@file{configure} script which automatically determines the compilation
-environment and creates the proper Makefiles for a particular
-platform. These @file{configure} files are generated using
-@samp{autoconf}, which can be found in the @file{src/util/autoconf}
-directory in the distribution.
-
-Normal users will not need to worry about running @samp{autoconf}; the
-distribution comes with the @file{configure} files already prebuilt.
-Developers who wish to modify the @file{configure.in} files should see
-@ref{Top, , Overview, autoconf, The Autoconf Manual}.
-
-Note that in order to run @samp{autoconf}, you must have GNU @samp{m4}
-in your path. Before you use the @samp{autoconf} in the Kerberos V5
-source tree, you may also need to run @samp{configure}, and then run
-@samp{make} in the @file{src/util/autoconf} directory in order to
-properly set up @samp{autoconf}.
-
-One tool which is provided for the convenience of developers can be
-found in @file{src/util/reconf}. This program should be run while the
-current directory is the top source directory. It will automatically
-rebuild any @file{configure} files which need rebuilding. If you know
-that you have made a change that will require that all the
-@file{configure} files need to be rebuilt from scratch, specify the
-@code{--force} option:
-
-@example
-% cd /u1/krb5-@value{RELEASE}/src
-% ./util/reconf --force
-@end example
-
-The developmental sources are a raw source tree (before it's been packaged
-for public release), without the pre-built @file{configure} files.
-In order to build from such a source tree, you must do:
-
-@example
-% cd krb5/util/autoconf
-% ./configure
-% make
-% cd ../..
-% util/reconf
-@end example
-
-Then follow the instructions for building packaged source trees (above).
-To install the binaries into a binary tree, do:
-
-@example
-% cd /u1/krb5-@value{RELEASE}/src
-% make all
-% make install DESTDIR=somewhere-else
-@end example
-
+++ /dev/null
-\input texinfo-suppl.tex % contains @doubleleftarrow{} definition
- % this line must come *before* \input texinfo
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@c guide
-@setfilename krb5-install.info
-@settitle Kerberos V5 Installation Guide
-@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
-@parskip 6pt plus 6pt
-@end iftex
-
-@dircategory Kerberos
-@direntry
-* krb5-install: (krb5-install). Kerberos V5 Installation Guide
-@end direntry
-
-@include definitions.texinfo
-@set EDITION 1.1
-
-@finalout @c don't print black warning boxes
-
-@titlepage
-@title @value{PRODUCT} Installation Guide
-@subtitle Release: @value{RELEASE}
-@subtitle Document Edition: @value{EDITION}
-@subtitle Last updated: @value{UPDATED}
-@author @value{COMPANY}
-
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@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 function. Don't forget to run M-x texinfo-every-node-update after
-@c you add a new section or subsection, or after you've rearranged the
-@c order of sections or subsections. Also, don't forget to add an @node
-@c comand before each @section or @subsection! All you need to enter
-@c is:
-@c
-@c @node New Section Name
-
-@c @section New Section Name
-@c
-@c M-x texinfo-every-node-update will take care of calculating the
-@c node's forward and back pointers.
-@c
-@c ---------------------------------------------------------------------
-
-@menu
-* Introduction::
-* Realm Configuration Decisions::
-* Building Kerberos V5::
-* Installing Kerberos V5::
-* Upgrading Existing Kerberos V5 Installations::
-* Bug Reports for Kerberos V5::
-* Copyright::
-@end menu
-
-@node Introduction, Realm Configuration Decisions, Top, Top
-@chapter Introduction
-
-@menu
-* What is Kerberos and How Does it Work?::
-* Why Should I use Kerberos?::
-* Please Read the Documentation::
-* Overview of This Guide::
-@end menu
-
-@node What is Kerberos and How Does it Work?, Why Should I use Kerberos?, Introduction, Introduction
-@section What is Kerberos and How Does it Work?
-
-@value{PRODUCT} is based on the Kerberos authentication system developed
-at MIT. Under Kerberos, a client (generally either a user or a service)
-sends a request for a ticket to the Key Distribution Center (KDC). The
-KDC creates a @dfn{ticket-granting ticket} (TGT) for the client,
-encrypts it using the client's password as the key, and sends the
-encrypted TGT back to the client. The client then attempts to decrypt
-the TGT, using its password. If the client successfully decrypts the
-TGT (@i{i.e.}, if the client gave the correct password), it keeps the
-decrypted TGT, which indicates proof of the client's identity.
-
-The TGT, which expires at a specified time, permits the client to obtain
-additional tickets, which give permission for specific services. The
-requesting and granting of these additional tickets is user-transparent.
-
-@node Why Should I use Kerberos?, Please Read the Documentation, What is Kerberos and How Does it Work?, Introduction
-@section Why Should I use Kerberos?
-
-Since Kerberos negotiates authenticated, and optionally encrypted,
-communications between two points anywhere on the Internet, it provides
-a layer of security that is not dependent on which side of a firewall
-either client is on. Since studies have shown that half of the computer
-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.
-
-@node Please Read the Documentation, Overview of This Guide, Why Should I use Kerberos?, Introduction
-@section Please Read the Documentation
-
-As with any software package that uses a centrallized database, the
-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
-
-@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:
-
-@enumerate
-@item
-Key Distribution Centers (KDCs).
-
-@enumerate A
-@item
-The Master KDC.
-
-@item
-Slave KDCs.
-@end enumerate
-
-@item
-UNIX client machines
-
-@item
-UNIX application server machines
-@end enumerate
-
-@noindent
-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.
-
-@node Realm Configuration Decisions, Building Kerberos V5, Introduction, Top
-@chapter Realm Configuration Decisions
-
-Before installing @value{PRODUCT}, it is necessary to consider the
-following issues:
-
-@itemize @bullet
-@item
-The name of your Kerberos realm (or the name of each realm, if you need
-more than one).
-
-@item
-How you will map your hostnames onto Kerberos realms.
-
-@item
-Which ports your KDC and and kadmin (database access) services will use.
-
-@item
-How many slave KDCs you need and where they should be located.
-
-@item
-The hostnames of your master and slave KDCs.
-
-@item
-How frequently you will propagate the database from the master KDC to
-the slave KDCs.
-@end itemize
-
-@menu
-* Kerberos Realms::
-* Mapping Hostnames onto Kerberos Realms::
-* Ports for the KDC and Admin Services::
-* Slave KDCs::
-* Hostnames for the Master and Slave KDCs::
-* Database Propagation::
-@end menu
-
-@node Kerberos Realms, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions, Realm Configuration Decisions
-@section Kerberos Realms
-
-Although your Kerberos realm can be any ASCII string, convention is to
-make it the same as your domain name, in upper-case letters. For
-example, hosts in the domain @value{SECONDDOMAIN} would be in the
-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 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
-
-@include dnstxt.texinfo
-
-@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 @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
-
-Slave KDCs provide an additional source of Kerberos ticket-granting
-services in the event of inaccessibility of the master KDC. The number
-of slave KDCs you need and the decision of where to place them, both
-physically and logically, depends on the specifics of your network.
-
-All of the Kerberos authentication on your network requires that each
-client be able to contact a KDC. Therefore, you need to anticipate any
-likely reason a KDC might be unavailable and have a slave KDC to take up
-the slack.
-
-Some considerations include:
-
-@itemize @bullet
-@item
-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 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
-the master, in case of power outages, fires, or other localized
-disasters.
-@end itemize
-
-
-
-@node Hostnames for the Master and Slave KDCs, Database Propagation, Slave KDCs, Realm Configuration Decisions
-@section Hostnames for the Master and Slave KDCs
-
-@include dnssrv.texinfo
-
-@node Database Propagation, , Hostnames for the Master and Slave KDCs, Realm Configuration Decisions
-@section Database Propagation
-
-The Kerberos database resides on the master KDC, and must be propagated
-regularly (usually by a cron job) to the slave KDCs. In deciding how
-frequently the propagation should happen, you will need to balance the
-amount of time the propagation takes against the maximum reasonable
-amount of time a user should have to wait for a password change to take
-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, 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
-to additional slaves.
-
-@node Building Kerberos V5, Installing Kerberos V5, Realm Configuration Decisions, Top
-@chapter Building @value{PRODUCT}
-
-@include build.texinfo
-
-@node Installing Kerberos V5, Upgrading Existing Kerberos V5 Installations, Building Kerberos V5, Top
-@chapter Installing @value{PRODUCT}
-
-The sections of this chapter describe procedures for installing
-@value{PRODUCT} on:
-
-@enumerate
-@item
-The KDCs
-
-@item
-UNIX client machines
-
-@item
-UNIX Application Servers
-@end enumerate
-
-@menu
-* Installing KDCs::
-* Installing and Configuring UNIX Client Machines::
-* UNIX Application Servers::
-@end menu
-
-@node Installing KDCs, Installing and Configuring UNIX Client Machines, Installing Kerberos V5, Installing Kerberos V5
-@section Installing KDCs
-
-The Key Distribution Centers (KDCs) issue Kerberos tickets. Each KDC
-contains a copy of the Kerberos database. The master KDC contains the
-master copy of the database, which it propagates to the slave KDCs at
-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
-administration. This allows clients to continue to obtain tickets when
-the master KDC is unavailable.
-
-@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.
-
-@menu
-* Install the Master KDC::
-* Install the Slave KDCs::
-* Back on the Master KDC::
-* Finish Installing the Slave KDCs::
-* 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
-@subsection Install the Master KDC
-
-This installation procedure will require you to go back and forth a
-couple of times between the master KDC and each of the slave KDCs. The
-first few steps must be done on the master KDC.
-
-@menu
-* Edit the Configuration Files::
-* krb5.conf::
-* kdc.conf::
-* Create the Database::
-* Add Administrators to the Acl File::
-* Add Administrators to the Kerberos Database::
-* Create a kadmind Keytab (optional)::
-* Start the Kerberos Daemons::
-@end menu
-
-@node Edit the Configuration Files, krb5.conf, Install the Master KDC, Install the Master KDC
-@subsubsection Edit the Configuration Files
-
-Modify the configuration files, @code{/etc/krb5.conf} and
-@code{@value{ROOTDIR}/var/krb5kdc/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}.
-
-Most of the tags in the configuration have default values that will
-work well for most sites. There are some tags in the @code{krb5.conf}
-file whose values must be specified, and this section will explain
-those as well as give an overview of all of the sections in both
-configuration files. For more information on changing defaults with
-the configuration files, see the @value{PRODUCT} System Administrator's
-Guide sections on configuration files.
-
-@node krb5.conf, kdc.conf, Edit the Configuration Files, Install the Master KDC
-@subsubsection krb5.conf
-
-@include krb5conf.texinfo
-
-If you are not using DNS TXT records, you must specify the
-@code{default_realm} in the @code{libdefaults} section. If you are not
-using DNS SRV records, you must include the @code{kdc} tag for each
-realm in the @code{realms} section. To communicate with the kadmin
-server in each realm, the @code{admin_server} tag must be set in the
-@code{realms} section. If your domain name and realm name are not the
-same, you must provide a translation in @code{domain_realm}. It is
-also higly recommeneded that you create a @code{[logging]} stanza if
-the computer will be functioning as a KDC so that the KDC and kadmind
-will generate logging output.
-
-An example @code{krb5.conf} file:
-
-@smallexample
-@group
-[libdefaults]
- default_realm = @value{PRIMARYREALM}
-
-[realms]
- @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
- admin_server = FILE:/var/log/kadmin.log
- default = FILE:/var/log/krb5lib.log
-@end group
-@end smallexample
-
-@node kdc.conf, Create the Database, krb5.conf, Install the Master KDC
-@subsubsection kdc.conf
-
-@include kdcconf.texinfo
-
-@node Create the Database, Add Administrators to the Acl File, kdc.conf, Install the Master KDC
-@subsubsection Create the Database
-
-You will use the @code{kdb5_util} command @emph{on the Master KDC} to
-create the Kerberos database and the optional stash file. The
-@dfn{stash file} is a local copy of the master key that resides in
-encrypted form on the KDC's local disk. The stash file is used to
-authenticate the KDC to itself automatically before starting the
-@code{kadmind} and @code{krb5kdc} daemons (@i{e.g.,} as part of the
-machine's boot sequence). The stash file, like the keytab file
-(see @xref{The Keytab File}, for more information) is a potential
-point-of-entry for a break-in,
-and if compromised, would allow unrestricted access to the Kerberos
-database. If you choose to install a stash file, it should be readable
-only by root, and should exist only on the KDC's local disk. The file
-should not be part of any backup of the machine, unless access to the
-backup data is secured as tightly as access to the master password
-itself.
-
-If you choose not to install a stash file, the KDC will prompt you for
-the master key each time it starts up. This means that the KDC will
-not be able to start automatically, such as after a system reboot.
-
-Note that @code{kdb5_util} will prompt you for the master key for the
-Kerberos database. This key can be any string. A good key is one you
-can remember, but that no one else can guess. Examples of bad keys are
-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
-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
-line that begins with @result{} is a continuation of the previous line.)
-Replace @i{@value{PRIMARYREALM}} with the name of your Kerberos realm.
-
-@smallexample
-@group
-@b{shell%} @value{ROOTDIR}/sbin/kdb5_util create -r @value{PRIMARYREALM} -s
-@b{Initializing database '@value{ROOTDIR}/var/krb5kdc/principal' for
-@result{} realm '@value{PRIMARYREALM}',
-master key name 'K/M@@@value{PRIMARYREALM}'
-You will be prompted for the database Master Password.
-It is important that you NOT FORGET this password.}
-@iftex
-@b{Enter KDC database master key:} @i{@doubleleftarrow{} Type the master password.}
-@b{Re-enter KDC database master key to verify:} @i{@doubleleftarrow{} Type it again.}
-@end iftex
-@ifinfo
-@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
-
-This will create five files in the directory specified in your
-@code{kdc.conf} file: two Kerberos database files, @code{principal.db},
-and @code{principal.ok}; the Kerberos administrative database file,
-@code{principal.kadm5}; the administrative database lock file,
-@code{principal.kadm5.lock}; and the stash file, @code{.k5stash}. (The
-default directory is @code{@value{ROOTDIR}/var/krb5kdc}.) If you do not
-want a stash file, run the above command without the @code{-s} option.
-
-@node Add Administrators to the Acl File, Add Administrators to the Kerberos Database, Create the Database, Install the Master KDC
-@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. 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
-
-@node Add Administrators to the Kerberos Database, Create a kadmind Keytab (optional), Add Administrators to the Acl File, Install the Master KDC
-@subsubsection Add Administrators to the Kerberos Database
-
-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}. 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
-@b{shell%} @value{ROOTDIR}/sbin/kadmin.local
-@b{kadmin.local:} addprinc admin/admin@@@value{PRIMARYREALM}
-@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.}
-@end iftex
-@ifinfo
-@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
-@end smallexample
-
-
-
-@node Create a kadmind Keytab (optional), Start the Kerberos Daemons, Add Administrators to the Kerberos Database, Install the Master KDC
-@subsubsection Create a kadmind Keytab (optional)
-
-The kadmind keytab is the key that the legacy admininstration daemons
-@code{kadmind4} and @code{v5passwdd} will use to decrypt
-administrators' or clients' Kerberos tickets to determine whether or
-not they should have access to the database. You need to create the
-kadmin keytab with entries for the principals @code{kadmin/admin} and
-@code{kadmin/changepw}. (These principals are placed in the Kerberos
-database automatically when you create it.) To create the kadmin
-keytab, run @code{kadmin.local} and use the @code{ktadd} command, as
-in the following example. (The line beginning with @result{} is a
-continuation of the previous line.):
-
-@smallexample
-@group
-@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 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
-@end smallexample
-
-@noindent
-As specified in the @samp{-k} argument, @code{ktadd} will save the
-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.
-
-@need 2000
-@node Start the Kerberos Daemons, , Create a kadmind Keytab (optional), Install the Master KDC
-@subsubsection Start the Kerberos Daemons on the Master KDC
-
-At this point, you are ready to start the Kerberos daemons on the Master
-KDC. To do so, type:
-
-@smallexample
-@b{shell%} @value{ROOTDIR}/sbin/krb5kdc
-@b{shell%} @value{ROOTDIR}/sbin/kadmind
-@end smallexample
-
-@noindent
-Each daemon will fork and run in the background. Assuming you want
-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}.
-(@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
-
-You are now ready to start configuring the slave KDCs. Assuming you are
-setting the KDCs up so that you can easily switch the master KDC with
-one of the slaves, you should perform each of these steps on the master
-KDC as well as the slave KDCs, unless these instructions specify
-otherwise.
-
-
-@menu
-* Create Host Keys for the Slave KDCs::
-* Extract Host Keytabs for the KDCs::
-* Set Up the Slave KDCs for Database Propagation::
-@end menu
-
-@node Create Host Keys for the Slave KDCs, Extract Host Keytabs for the KDCs, Install the Slave KDCs, Install the Slave KDCs
-@subsubsection Create Host Keys for the Slave KDCs
-
-Each KDC needs a host principal in the Kerberos database. You can enter
-these from any host, once the @code{kadmind} daemon is running. For
-example, if your master KDC were called
-@value{KDCSERVER}.@value{PRIMARYDOMAIN}, and you had two KDC slaves
-named @value{KDCSLAVE1}.@value{PRIMARYDOMAIN} and
-@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}, you would type the following:
-
-@smallexample
-@group
-@b{shell%} @value{ROOTDIR}/sbin/kadmin
-@b{kadmin:} addprinc -randkey host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}
-@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{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{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
-@end smallexample
-
-@noindent
-It is not actually necessary to have the master KDC server in the
-Kerberos database, but it can be handy if:
-
-@itemize @bullet
-@item
-anyone will be logging into the machine as something other than root
-
-@item
-you want to be able to swap the master KDC with one of the slaves if
-necessary.
-@end itemize
-
-@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
-@subsubsection Extract Host Keytabs for the KDCs
-
-Each KDC (including the master) needs a keytab to decrypt tickets.
-Ideally, you should extract each keytab locally on its own KDC. If this
-is not feasible, you should use an encrypted session to send them across
-the network. To extract a keytab on a KDC called
-@value{KDCSERVER}.@value{PRIMARYDOMAIN}, you would execute the following
-command:
-
-@smallexample
-@group
-@b{kadmin:} ktadd host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}
-@b{kadmin: Entry for principal host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
- kvno 1, encryption type DES-CBC-CRC added to keytab
- WRFILE:/etc/krb5.keytab.
-kadmin:}
-@end group
-@end smallexample
-
-@noindent
-Note that the principal must exist in the Kerberos database in order to
-extract the keytab.
-
-@node Set Up the Slave KDCs for Database Propagation, , Extract Host Keytabs for the KDCs, Install the Slave KDCs
-@subsubsection Set Up the Slave KDCs for Database Propagation
-
-The database is propagated from the master KDC to the slave KDCs via the
-@code{kpropd} daemon. To set up propagation, create a file on each KDC,
-named @code{@value{ROOTDIR}/var/krb5kdc/kpropd.acl}, containing the
-principals for each of the KDCs.
-@need 1200
-For example, if the master KDC were
-@code{@value{KDCSERVER}.@value{PRIMARYDOMAIN}}, the slave KDCs were
-@code{@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}} and
-@code{@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}}, and the realm were
-@code{@value{PRIMARYREALM}}, then the file's contents would be:
-
-@smallexample
-@group
-host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
-host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
-host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
-@end group
-@end smallexample
-
-@need 1000
-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
-@end group
-@end smallexample
-
-@noindent
-You also need to add the following lines to @code{/etc/services} on each
-KDC:
-
-@smallexample
-@group
-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)
-@end group
-@end smallexample
-
-@node Back on the Master KDC, Finish Installing the Slave KDCs, Install the Slave KDCs, Installing KDCs
-@subsection Back on the Master KDC
-
-Now that the slave KDCs are able to accept database propagation, you'll
-need to propagate the database to each of them.
-
-@menu
-* Propagate the Database to Each Slave KDC::
-@end menu
-
-@node Propagate the Database to Each Slave KDC, , Back on the Master KDC, Back on the Master KDC
-@subsubsection Propagate the Database to Each Slave KDC
-
-First, create a dump of the database on the master KDC, as follows:
-
-@smallexample
-@group
-@b{shell%} @value{ROOTDIR}/sbin/kdb5_util dump @value{ROOTDIR}/var/krb5kdc/slave_datatrans
-@b{shell%}
-@end group
-@end smallexample
-
-Next, you need to manually propagate the database to each slave KDC, as
-in the following example. (The lines beginning with @result{} are
-continuations of the previous line.):
-
-@smallexample
-@group
-@value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans
-@result{} @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}
-@value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans
-@result{} @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}
-@end group
-@end smallexample
-
-You will need a script to dump and propagate the database. The
-following is an example of a bourne shell script that will do this.
-(Note that the line that begins with @result{} is a continuation of the
-previous line. Remember that you need to replace @value{ROOTDIR} with
-the name of the directory in which you installed @value{PRODUCT}.)
-
-@smallexample
-@group
-#!/bin/sh
-
-kdclist = "@value{KDCSLAVE1}.@value{PRIMARYDOMAIN} @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}"
-
-@value{ROOTDIR}/sbin/kdb5_util "dump
-@result{} @value{ROOTDIR}/var/krb5kdc/slave_datatrans"
-
-for kdc in $kdclist
-do
-@value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/var/krb5kdc/slave_datatrans $kdc
-done
-@end group
-@end smallexample
-
-@noindent
-You will need to set up a cron job to run this script at the intervals
-you decided on earlier (@xref{Database Propagation}.)
-
-@node Finish Installing the Slave KDCs, Add Kerberos Principals to the Database, Back on the Master KDC, Installing KDCs
-@subsection Finish Installing the Slave KDCs
-
-Now that the slave KDCs have copies of the Kerberos database, you can
-create stash files for them and start the @code{krb5kdc} daemon.
-
-@menu
-* Create Stash Files on the Slave KDCs::
-* Start the krb5kdc Daemon on Each KDC::
-@end menu
-
-@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
-@subsubsection Create Stash Files on the Slave KDCs
-
-Create stash files, by issuing the following commands on each slave KDC:
-
-@smallexample
-@group
-@b{shell%} kdb5_util stash
-@b{kdb5_util: Cannot find/read stored master key while reading master key
-kdb5_util: Warning: proceeding without master key}
-@iftex
-@b{Enter KDC database master key:} @i{@doubleleftarrow{} Enter the database master key.}
-@end iftex
-@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
-
-As mentioned above, the stash file is necessary for your KDCs to be able
-authenticate to themselves, such as when they reboot. You could run
-your KDCs without stash files, but you would then need to type in the
-Kerberos database master key by hand every time you start a KDC daemon.
-
-@node Start the krb5kdc Daemon on Each KDC, , Create Stash Files on the Slave KDCs, Finish Installing the Slave KDCs
-@subsubsection Start the krb5kdc Daemon on Each KDC
-
-The final step in configuing your slave KDCs is to run the KDC daemon:
-
-@smallexample
-@group
-@b{shell%} @value{ROOTDIR}/sbin/krb5kdc
-@end group
-@end smallexample
-
-As with the master KDC, you will probably want to add this command to
-the KDCs' @code{/etc/rc} or @code{/etc/inittab} files, so they will
-start the krb5kdc daemon automatically at boot time.
-
-@node Add Kerberos Principals to the Database, Limit Access to the KDCs, Finish Installing the Slave KDCs, Installing KDCs
-@subsection Add Kerberos Principals to the Database
-
-@need 1800
-Once your KDCs are set up and running, you are ready to use
-@code{kadmin} to load principals for your users, hosts, and other
-services into the Kerberos database. This procedure is described fully in the
-``Adding or Modifying Principals'' section of the @value{PRODUCT} System
-Administrator's Guide. (@xref{Create Host Keys for the Slave KDCs}, for a
-brief description.) The keytab is generated by running @code{kadmin}
-and issuing the @code{ktadd} command.
-
-@node Limit Access to the KDCs, Switching Master and Slave KDCs, Add Kerberos Principals to the Database, Installing KDCs
-@subsection Limit Access to the KDCs
-
-To limit the possibility that your Kerberos database could be
-compromised, @value{COMPANY} recommends that each KDC be a dedicated
-host, with limited access. If your KDC is also a file server, FTP
-server, Web server, or even just a client machine, someone who obtained
-root access through a security hole in any of those areas could gain
-access to the Kerberos database.
-
-@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.
-This might happen if you are upgrading the master KDC, or if your master
-KDC has a disk crash.
-
-Assuming you have configured all of your KDCs to be able to function as
-either the master KDC or a slave KDC (as this document recommends), all
-you need to do to make the changeover is:
-
-If the master KDC is still running, do the following on the @emph{old}
-master KDC:
-
-@enumerate
-@item
-Kill the @code{kadmind} process.
-
-@item
-Disable the cron job that propagates the database.
-
-@item
-Run your database propagation script manually, to ensure that the slaves
-all have the latest copy of the database. (@xref{Propagate the Database
-to Each Slave KDC}.) If there is a need to preserve per-principal
-policy information from the database, you should do a ``kdb5_util dump
--ov'' in order to preserve that information and propogate that dump file
-securely by some means to the slave so that its database has the correct
-state of the per-principal policy information.
-@end enumerate
-
-On the @emph{new} master KDC:
-
-@enumerate
-@item
-Create a database keytab. (@xref{Create a kadmind Keytab (optional)}.)
-
-@item
-Start the @code{kadmind} daemon. (@xref{Start the Kerberos Daemons}.)
-
-@item
-Set up the cron job to propagate the database. (@xref{Propagate the
-Database to Each Slave KDC}.)
-
-@item
-Switch the CNAMEs of the old and new master KDCs. (If you don't do
-this, you'll need to change the @code{krb5.conf} file on every client
-machine in your Kerberos realm.)
-
-@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
-
-Client machine installation is much more straightforward than
-installation of the KDCs.
-
-@menu
-* Client Programs::
-* Client Machine Configuration Files::
-@end menu
-
-@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{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
-need to make sure your users know to use their Kerberos passwords when
-they log in.
-
-You will also need to educate your users to use the ticket management
-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
-
-Each machine running Kerberos must have a @code{/etc/krb5.conf} file.
-(@xref{krb5.conf}.)
-
-@need 4000
-Also, for most UNIX systems, you must add the appropriate Kerberos
-services to each client machine's @code{/etc/services} file. If you are
-using the default configuration for @value{PRODUCT}, you should be able
-to just insert the following code:
-
-@smallexample
-@group
-kerberos @value{DefaultPort}/udp kdc # Kerberos V5 KDC
-kerberos @value{DefaultPort}/tcp kdc # Kerberos V5 KDC
-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
-krb524 @value{DefaultKrb524Port}/tcp # Kerberos 5 to 4 ticket translator
-@end group
-@end smallexample
-
-@menu
-* Mac OS X Configuration::
-@end menu
-
-@node Mac OS X Configuration, , Client Machine Configuration Files, Client Machine Configuration Files
-@subsubsection Mac OS X Configuration
-
-To install Kerberos V5 on Mac OS X and Mac OS X Server, follow the
-directions for generic Unix-based OS's, except for the
-@code{/etc/services} updates described above.
-
-Mac OS X and Mac OS X Server use a database called NetInfo to store
-the contents of files normally found in @code{/etc}. Instead of
-modifying @code{/etc/services}, you should run the following commands
-to add the Kerberos service entries to NetInfo:
-
-@smallexample
-@group
-$ niutil -create . /services/kerberos
-$ niutil -createprop . /services/kerberos name kerberos kdc
-$ niutil -createprop . /services/kerberos port 750
-$ niutil -createprop . /services/kerberos protocol tcp udp
-$ niutil -create . /services/krbupdate
-$ niutil -createprop . /services/krbupdate name krbupdate kreg
-$ niutil -createprop . /services/krbupdate port 760
-$ niutil -createprop . /services/krbupdate protocol tcp
-$ niutil -create . /services/kpasswd
-$ niutil -createprop . /services/kpasswd name kpasswd kpwd
-$ niutil -createprop . /services/kpasswd port 761
-$ niutil -createprop . /services/kpasswd protocol tcp
-$ niutil -create . /services/klogin
-$ niutil -createprop . /services/klogin port 543
-$ niutil -createprop . /services/klogin protocol tcp
-$ niutil -create . /services/eklogin
-$ niutil -createprop . /services/eklogin port 2105
-$ niutil -createprop . /services/eklogin protocol tcp
-$ niutil -create . /services/kshell
-$ niutil -createprop . /services/kshell name kshell krcmd
-$ niutil -createprop . /services/kshell port 544
-$ niutil -createprop . /services/kshell protocol tcp
-@end group
-@end smallexample
-
-In addition to adding services to NetInfo, you must also modify the
-resolver configuration in NetInfo so that the machine resolves its own
-hostname as a FQDN (fully qualified domain name). By default, Mac OS X
-and Mac OS X Server machines query NetInfo to resolve hostnames before
-falling back to DNS. Because NetInfo has an unqualified name for all
-the machines in the NetInfo database, the machine's own hostname will
-resolve to an unqualified name. Kerberos needs a FQDN to look up keys
-in the machine's keytab file.
-
-Fortunately, you can change the @code{lookupd} caching order to query
-DNS first. Run the following NetInfo commands and reboot the machine:
-
-@smallexample
-@group
-$ niutil -create . /locations/lookupd/hosts
-$ niutil -createprop . /locations/lookupd/hosts LookupOrder CacheAgent DNSAgent
- NIAgent NILAgent
-@end group
-@end smallexample
-
-Once you have rebooted, you can verify that the resolver now behaves
-correctly. Compile the Kerberos 5 distribution and run:
-
-@smallexample
-@group
-$ cd .../src/tests/resolve
-$ ./resolve
-@end group
-@end smallexample
-
-This will tell you whether or not your machine returns FQDNs on name
-lookups. If the test still fails, you can also try turning off DNS
-caching. Run the following commands and reboot:
-
-@smallexample
-@group
-$ niutil -create . /locations/lookupd/hosts
-$ niutil -createprop . /locations/lookupd/hosts LookupOrder DNSAgent
- CacheAgent NIAgent NILAgent
-@end group
-@end smallexample
-
-The remainder of the setup of a Mac OS X client machine or application
-server should be the same as for other UNIX-based systems.
-
-@node UNIX Application Servers, , Installing and Configuring UNIX Client Machines, Installing Kerberos V5
-@section UNIX Application Servers
-
-An application server is a host that provides one or more services over
-the network. Application servers can be ``secure'' or ``insecure.'' A
-``secure'' host is set up to require authentication from every client
-connecting to it. An ``insecure'' host will still provide Kerberos
-authentication, but will also allow unauthenticated clients to connect.
-
-If you have @value{PRODUCT} installed on all of your client machines,
-@value{COMPANY} recommends that you make your hosts secure, to take
-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 capability.
-
-@menu
-* The Keytab File::
-* Some Advice about Secure Hosts::
-@end menu
-
-@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
-@code{/etc/krb5.keytab}, to authenticate to the KDC. The keytab file is
-an encrypted, local, on-disk copy of the host's key. The keytab file,
-like the stash file (@ref{Create the Database}) is a potential
-point-of-entry for a break-in, and if compromised, would allow
-unrestricted access to its host. The keytab file should be readable
-only by root, and should exist only on the machine's local disk. The
-file should not be part of any backup of the machine, unless access to
-the backup data is secured as tightly as access to the machine's root
-password itself.
-
-In order to generate a keytab for a host, the host must have a principal
-in the Kerberos database. The procedure for adding hosts to the
-database is described fully in the ``Adding or Modifying Principals''
-section of the @cite{@value{PRODUCT} System Administrator's Guide}.
-@xref{Create Host Keys for the Slave KDCs}. for a brief description.)
-The keytab is generated by running @code{kadmin} and issuing the
-@code{ktadd} command.
-
-@need 1100
-For example, to generate a keytab file to allow the host
-trillium.@value{PRIMARYDOMAIN} to authenticate for the services
-@code{host}, @code{ftp}, and @code{pop}, the administrator
-@code{@value{ADMINUSER}} would issue the command (on
-trillium.@value{PRIMARYDOMAIN}):
-
-@smallexample
-@group
-@b{trillium%} @value{ROOTDIR}/sbin/kadmin
-@b{kadmin5:} ktadd host/trillium.@value{PRIMARYDOMAIN} ftp/trillium.@value{PRIMARYDOMAIN}
-@result{} pop/trillium.@value{PRIMARYDOMAIN}
-@b{kadmin: Entry for principal host/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
-kvno 3, encryption type DES-CBC-CRC added to keytab
-WRFILE:/etc/krb5.keytab.
-kadmin: Entry for principal ftp/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
-kvno 3, encryption type DES-CBC-CRC added to keytab
-WRFILE:/etc/krb5.keytab.
-kadmin: Entry for principal pop/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with
-kvno 3, encryption type DES-CBC-CRC added to keytab
-WRFILE:/etc/krb5.keytab.
-kadmin5:} quit
-@b{trillium%}
-@end group
-@end smallexample
-
-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.
-
-@node Some Advice about Secure Hosts, , The Keytab File, UNIX Application Servers
-@subsection Some Advice about Secure Hosts
-
-@value{PRODUCT} can protect your host from certain types of break-ins,
-but it is possible to install @value{PRODUCT} and still leave your host
-vulnerable to attack. Obviously an installation guide is not the place
-to try to include an exhaustive list of countermeasures for every
-possible attack, but it is worth noting some of the larger holes and how
-to close them.
-
-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.
-
-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.
-
-@node Upgrading Existing Kerberos V5 Installations, Bug Reports for Kerberos V5, Installing Kerberos V5, Top
-@chapter Upgrading Existing @value{PRODUCT} Installations
-
-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 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
-
-@item Stop your current KDC and administration
-server processes, if any.
-
-@item Dump your existing Kerberos database to an ASCII file with
-@code{kdb5_util}'s ``dump'' command:
-
-@smallexample
-@group
-@b{shell%} cd @value{ROOTDIR}/var/krb5kdc
-@b{shell%} kdb5_util dump old-kdb-dump
-@b{shell%} kdb5_util dump -ov old-kdb-dump.ov
-@b{shell%}
-@end group
-@end smallexample
-
-@item Create a new Master KDC installation (@xref{Install the Master
-KDC}.). If you have a stash file for your current database, choose any
-new master password but then copy your existing stash file to the
-location specified by your kdc.conf; if you do not have a stash file for
-your current database, you must choose the same master password.
-
-@item Load your old Kerberos database into the new system with
-@code{kdb5_util}'s ``load'' command:
-
-@smallexample
-@group
-@b{shell%} cd @value{ROOTDIR}/var/krb5kdc
-@b{shell%} kdb5_util load old-kdb-dump
-@b{shell%} kdb5_util load -update old-kdb-dump.ov
-@b{shell%}
-@end group
-@end smallexample
-
-@end enumerate
-
-The ``dump -ov'' and ``load -update'' commands are necessary in order to
-preserve per-principal policy information, since the default dump format
-filters out that information. If you omit those steps, the loaded
-database database will lose the policy information for each principal
-that has a policy.
-
-To update a Slave KDC, you must stop the old server processes on the
-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 and RC4 Encryption Keys::
-@end menu
-
-@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 @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
-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.
-
-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 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 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, 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 / thirdparty / krb5.git / commitdiff
