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
@end menu
@node Organization of the Source Directory, Build Requirements, Building Kerberos V5, Building Kerberos V5
-@section Build Requirements
+@section Organization of the Source Directory
Below is a brief overview of the organization of the complete source
directory. More detailed descriptions follow.
@menu
* The appl Directory::
-* The clients Directory::
-* The gen-manpages Directory::
-* The include 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 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 Kerberos release provides certain UNIX utilities, modified to use
-Kerberos authentication. In the @i{appl/bsd} directory are the
-Berkeley utilities @i{login}, @i{rlogin}, @i{rsh}, and @i{rcp}, as well as
-the associated daemons @i{kshd} and @i{klogind}. The @i{login} program
-obtains ticket-granting tickets for users upon login; the other utilities
-provide authenticated Unix network services.
-
-The @i{appl} directory also contains Kerberized telnet and ftp programs,
-as well as sample Kerberos application client and server programs.
+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 program changes a user's Kerberos password.
@itemx ksu
-This program is a Kerberized verions of the @code{su} program that is
+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.
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}), and bug-reporting program @code{send-pr}.
+(@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 Organization of the Source Directory
+@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
will get @file{/u1/krb5-@value{RELEASE}/src}, etc.)
-@node Doing the Build, Testing the Build, Unpacking the Sources, Building Kerberos V5
+@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
from the latest version as distributed and installed by the XConsortium
with X11R6. Either version should be acceptable.
-@node Testing the Build, Options to Configure, Doing the Build, Building Kerberos V5
+@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
% 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::
DejaGnu may be found wherever GNU software is archived.
-Most of the tests are setup to run as a non-privledged user. For some
-of the krb-root tests to work properly, either (a) the user running the
-tests must not have a .k5login file in the home directory or (b) the
-.k5login file must contain an entry for @code{<username>@@KRBTEST.COM}.
-There are two series of tests (@samp{rlogind} and @samp{telnetd}) which
-require the ability to @samp{rlogin} as root to the local
-machine. Admittedly, this does require the use of a @file{.rhosts} file
-or some authenticated means. @footnote{If you are fortunate enough to
-have a previous version of Kerberos V5 or V4 installed, and the Kerberos
-rlogin is first in your path, you can setup @file{.k5login} or
-@file{.klogin} respectively to allow you access.}
-
-If you cannot obtain root access to your machine, all the other tests
-will still run. Note however, with DejaGnu 1.2, the "untested testcases"
-will cause the testsuite to exit with a non-zero exit status which
-@samp{make} will consider a failure of the testing process. Do not worry
-about this, as these tests are the last run when @samp{make check} is
-executed from the top level of the build tree. This problem does not
-exist with DejaGnu 1.3.
-
@node The KADM5 Tests, , The DejaGnu Tests, Testing the Build
@subsection The KADM5 Tests
information about using DNS to determine the default realm. By default,
DNS lookups are enabled for the former but not for the latter.
-@item --enable-kdc-replay-cache
+@item --disable-kdc-lookaside-cache
-Enable a cache in the KDC to detect retransmitted messages, and resend
-the previous responses to them. This protects against certain types of
-attempts to extract information from the KDC through some of the
-hardware preauthentication systems.
+Disables the cache in the KDC which detects retransmitted client
+requests and resends the previous responses to them.
@item --with-system-et
@item --with-system-db
Use an installed version of the Berkeley DB package, which must
-provide an API compatible with version 1.85.
+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
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
There is one configuration file which you may wish to edit to control
various compile-time parameters in the Kerberos distribution:
-@file{include/krb5/stock/osconf.h}. The list that follows is by no means
+@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
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), and SunOS 4.x.
+(i386).
To enable shared libraries on the above platforms, run the configure
script with the option @samp{--enable-shared}.
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 work arounds to such
+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 (Digital Unix) V2.0++::
+* 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
@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 (Digital Unix) V2.0++, AIX, OS Incompatibilities
+@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
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 (Digital Unix) V2.0++, BSDI, Alpha OSF/1 V1.3, OS Incompatibilities
-@subsection Alpha OSF/1 V2.0++
+@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}
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 any
-problems with the native compiler.
+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 (Digital Unix) V2.0++, OS Incompatibilities
+@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
@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 compiler (c89) should
-work as long as you give it the @samp{-D_HPUX_SOURCE} flag
-(i.e. @samp{./configure --with-cc='c89 -D_HPUX_SOURCE'}). This has only
-been tested recently for HPUX 10.20.
+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
@end enumerate
-@node Solaris 2.X, SGI Irix 5.X, Solaris versions 2.0 through 2.3, OS Incompatibilities
+@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{--with-ccopts=-i} option to @samp{configure}.
+@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 2.X, OS Incompatibilities
+@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
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{--with-ccopts=-O} and
-@samp{--with-ccopts=-g} to configure. If you don't specify either, the
+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.
projects / krb5.git / blobdiff