path: root/doc/pdf/build.tex

% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}
\usepackage{multirow}


\title{Building MIT Kerberos}
\date{ }
\release{1.15.1}
\author{MIT}
\newcommand{\sphinxlogo}{}
\renewcommand{\releasename}{Release}
\makeindex

\makeatletter
\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax%
    \let\PYG@ul=\relax \let\PYG@tc=\relax%
    \let\PYG@bc=\relax \let\PYG@ff=\relax}
\def\PYG@tok#1{\csname PYG@tok@#1\endcsname}
\def\PYG@toks#1+{\ifx\relax#1\empty\else%
    \PYG@tok{#1}\expandafter\PYG@toks\fi}
\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{%
    \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}}
\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}}

\expandafter\def\csname PYG@tok@gd\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gu\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@gt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.27,0.87}{##1}}}
\expandafter\def\csname PYG@tok@gs\endcsname{\let\PYG@bf=\textbf}
\expandafter\def\csname PYG@tok@gr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@cm\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@vg\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@m\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@cs\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}
\expandafter\def\csname PYG@tok@ge\endcsname{\let\PYG@it=\textit}
\expandafter\def\csname PYG@tok@vc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@il\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@go\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\expandafter\def\csname PYG@tok@cp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@gi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gh\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@ni\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.84,0.33,0.22}{##1}}}
\expandafter\def\csname PYG@tok@nl\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##1}}}
\expandafter\def\csname PYG@tok@nn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@no\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.38,0.68,0.84}{##1}}}
\expandafter\def\csname PYG@tok@na\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@nb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@nd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}}
\expandafter\def\csname PYG@tok@ne\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}}
\expandafter\def\csname PYG@tok@si\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##1}}}
\expandafter\def\csname PYG@tok@s2\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@vi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@nt\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.45}{##1}}}
\expandafter\def\csname PYG@tok@nv\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@s1\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@gp\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@sh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@ow\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@sx\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@bp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c1\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@kc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@mf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@err\endcsname{\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}
\expandafter\def\csname PYG@tok@kd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@ss\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.32,0.47,0.09}{##1}}}
\expandafter\def\csname PYG@tok@sr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##1}}}
\expandafter\def\csname PYG@tok@mo\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@kn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@o\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.40,0.40,0.40}{##1}}}
\expandafter\def\csname PYG@tok@kr\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@s\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@kp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@w\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}}
\expandafter\def\csname PYG@tok@kt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##1}}}
\expandafter\def\csname PYG@tok@sc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@k\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@se\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sd\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}

\def\PYGZbs{\char`\\}
\def\PYGZus{\char`\_}
\def\PYGZob{\char`\{}
\def\PYGZcb{\char`\}}
\def\PYGZca{\char`\^}
\def\PYGZam{\char`\&}
\def\PYGZlt{\char`\<}
\def\PYGZgt{\char`\>}
\def\PYGZsh{\char`\#}
\def\PYGZpc{\char`\%}
\def\PYGZdl{\char`\$}
\def\PYGZhy{\char`\-}
\def\PYGZsq{\char`\'}
\def\PYGZdq{\char`\"}
\def\PYGZti{\char`\~}
% for compatibility with earlier versions
\def\PYGZat{@}
\def\PYGZlb{[}
\def\PYGZrb{]}
\makeatother

\begin{document}

\maketitle
\tableofcontents
\phantomsection\label{build/index::doc}


This section details how to build and install MIT Kerberos software
from the source.


\chapter{Prerequisites}
\label{build/index:building-kerberos-v5}\label{build/index:prerequisites}\label{build/index:build-v5}
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 build tree, which contains the compiled
*.o file and executables, separate from your source tree, you will
need a make program which supports \textbf{VPATH}, or you will need to use
a tool such as lndir to produce a symbolic link tree for your build
tree.


\chapter{Obtaining the software}
\label{build/index:obtaining-the-software}
The source code can be obtained from MIT Kerberos Distribution page,
at \href{http://web.mit.edu/kerberos/dist/index.html}{http://web.mit.edu/kerberos/dist/index.html}.
The MIT Kerberos distribution comes in an archive file, generally
named krb5-VERSION-signed.tar, where \emph{VERSION} is a placeholder for
the major and minor versions of MIT Kerberos.  (For example, MIT
Kerberos 1.9 has major version ``1'' and minor version ``9''.)

The krb5-VERSION-signed.tar contains a compressed tar file consisting
of the sources for all of Kerberos (generally named
krb5-VERSION.tar.gz) and a PGP signature file for this source tree
(generally named krb5-VERSION.tar.gz.asc).  MIT highly recommends that
you verify the integrity of the source code using this signature,
e.g., by running:

\begin{Verbatim}[commandchars=\\\{\}]
tar xf krb5\PYGZhy{}VERSION\PYGZhy{}signed.tar
gpg \PYGZhy{}\PYGZhy{}verify krb5\PYGZhy{}VERSION.tar.gz.asc
\end{Verbatim}

Unpack krb5-VERSION.tar.gz in some directory. In this section we will assume
that you have chosen the top directory of the distribution the directory
\code{/u1/krb5-VERSION}.

Review the README file for the license, copyright and other sprecific to the
distribution information.


\chapter{Contents}
\label{build/index:contents}

\section{Organization of the source directory}
\label{build/directory_org::doc}\label{build/directory_org:organization-of-the-source-directory}
Below is a brief overview of the organization of the complete source
directory.  More detailed descriptions follow.

\begin{tabulary}{\linewidth}{|L|L|}
\hline

appl
 & 
Kerberos application client and server programs
\\
\hline
ccapi
 & 
Credential cache services
\\
\hline
clients
 & 
Kerberos V5 user programs (See \emph{user\_commands})
\\
\hline
config
 & 
Configure scripts
\\
\hline
config-files
 & 
Sample Kerberos configuration files
\\
\hline
include
 & 
include files needed to build the Kerberos system
\\
\hline
kadmin
 & 
Administrative interface to the Kerberos master database: \emph{kadmin(1)}, \emph{kdb5\_util(8)}, \emph{ktutil(1)}.
\\
\hline
kdc
 & 
Kerberos V5 Authentication Service and Key Distribution Center
\\
\hline
{\hyperref[build/directory_org:lib]{lib}}
 & 
Libraries for use with/by Kerberos V5
\\
\hline
plugins
 & 
Kerberos plugins directory
\\
\hline
po
 & 
Localization infrastructure
\\
\hline
prototype
 & 
Templates files containing the MIT copyright message and a placeholder for the title and description of the file.
\\
\hline
slave
 & 
Utilities for propagating the database to slave KDCs \emph{kprop(8)} and \emph{kpropd(8)}
\\
\hline
tests
 & 
Test suite
\\
\hline
{\hyperref[build/directory_org:util]{util}}
 & 
Various utilities for building/configuring the code, sending bug reports, etc.
\\
\hline
windows
 & 
Source code for building Kerberos V5 on Windows (see windows/README)
\\
\hline\end{tabulary}



\subsection{lib}
\label{build/directory_org:lib}\label{build/directory_org:id1}
The lib directory contain several subdirectories as well as some
definition and glue files.
\begin{itemize}
\item {} 
The apputils directory contains the code for the generic network
servicing.

\item {} 
The crypto subdirectory contains the Kerberos V5 encryption
library.

\item {} 
The gssapi library contains the Generic Security Services API,
which is a library of commands to be used in secure client-server
communication.

\item {} 
The kadm5 directory contains the libraries for the KADM5
administration utilities.

\item {} 
The Kerberos 5 database libraries are contained in kdb.

\item {} 
The krb5 directory contains Kerberos 5 API.

\item {} 
The rpc directory contains the API for the Kerberos Remote
Procedure Call protocol.

\end{itemize}


\subsection{util}
\label{build/directory_org:util}\label{build/directory_org:id2}\begin{description}
\item[{The util directory contains several utility programs and libraries.}] \leavevmode\begin{itemize}
\item {} 
the programs used to configure and build the code, such as
autoconf, lndir, kbuild, reconf, and makedepend, are in this
directory.

\item {} 
the profile directory contains most of the functions which parse
the Kerberos configuration files (krb5.conf and kdc.conf).

\item {} 
the Kerberos error table library and utilities (et);

\item {} 
the Sub-system library and utilities (ss);

\item {} 
database utilities (db2);

\item {} 
pseudo-terminal utilities (pty);

\item {} 
bug-reporting program send-pr;

\item {} 
a generic support library support used by several of our other
libraries;

\item {} 
the build infrastructure for building lightweight Kerberos client
(collected-client-lib)

\item {} 
the tool for validating Kerberos configuration files
(confvalidator);

\item {} 
the toolkit for kernel integrators for building krb5 code subsets
(gss-kernel-lib);

\item {} 
source code for building Kerberos V5 on MacOS (mac)

\item {} 
Windows getopt operations (windows)

\end{itemize}

\end{description}


\section{Doing the build}
\label{build/doing_build::doc}\label{build/doing_build:doing-the-build}

\subsection{Building within a single tree}
\label{build/doing_build:do-build}\label{build/doing_build:building-within-a-single-tree}
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 OS
Incompatibilities, for notes that we have on particular operating
systems.

If you don't want separate build trees for each architecture, then use
the following abbreviated procedure:

\begin{Verbatim}[commandchars=\\\{\}]
cd /u1/krb5\PYGZhy{}VERSION/src
./configure
make
\end{Verbatim}

That's it!


\subsection{Building with separate build directories}
\label{build/doing_build: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 make program support VPATH.  GNU's make will provide this
functionality, for example.)  If your make program does not support
this, see the next section.

For example, if you wish to store the binaries in \code{tmpbuild} build
directory you might use the following procedure:

\begin{Verbatim}[commandchars=\\\{\}]
mkdir /u1/tmpbuild
cd /u1/tmpbuild
/u1/krb5\PYGZhy{}VERSION/src/configure
make
\end{Verbatim}


\subsection{Building using lndir}
\label{build/doing_build:building-using-lndir}
If you wish to keep separate build directories for each platform, and
you do not have access to a make program which supports VPATH, all is
not lost.  You can use the 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:

\begin{Verbatim}[commandchars=\\\{\}]
mkdir /u1/krb5\PYGZhy{}VERSION/solaris
cd /u1/krb5\PYGZhy{}VERSION/solaris
/u1/krb5\PYGZhy{}VERSION/src/util/lndir {}`pwd{}`/../src
./configure
make
\end{Verbatim}

You must give an absolute pathname to 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.


\subsection{Installing the binaries}
\label{build/doing_build:installing-the-binaries}
Once you have built Kerberos, you should install the binaries. You can
do this by running:

\begin{Verbatim}[commandchars=\\\{\}]
make install
\end{Verbatim}

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:

\begin{Verbatim}[commandchars=\\\{\}]
make install DESTDIR=/path/to/destdir
\end{Verbatim}

This will install the binaries under \emph{DESTDIR/PREFIX}, e.g., the user
programs will install into \emph{DESTDIR/PREFIX/bin}, the libraries into
\emph{DESTDIR/PREFIX/lib}, etc.

Some implementations of make allow multiple commands to be run in
parallel, for faster builds.  We test our Makefiles in parallel builds
with GNU make only; they may not be compatible with other parallel
build implementations.


\subsection{Testing the build}
\label{build/doing_build: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 make to
start building Kerberos; see {\hyperref[build/doing_build:do-build]{\emph{Building within a single tree}}}):

\begin{Verbatim}[commandchars=\\\{\}]
make check
\end{Verbatim}

However, there are several prerequisites that must be satisfied first:
\begin{itemize}
\item {} 
Configure and build Kerberos with Tcl support. Tcl is used to drive
the test suite.  This often means passing \textbf{-}\textbf{-with-tcl} to
configure to tell it the location of the Tcl configuration
script. (See {\hyperref[build/options2configure:options2configure]{\emph{Options to configure}}}.)

\item {} 
In addition to Tcl, DejaGnu must be available on the system for some
of the tests to run.  The test suite will still run the other tests
if DejaGnu is not present, but the test coverage will be reduced
accordingly.

\item {} 
On some operating systems, you have to run \code{make install} before
running \code{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
\textbf{-}\textbf{-disable-rpath}, which renders the build tree less suitable for
installation, but allows testing without interference from
previously installed libraries.

\end{itemize}

There are additional regression tests available, which are not run
by \code{make check}.  These tests require manual setup and teardown of
support infrastructure which is not easily automated, or require
excessive resources for ordinary use.  The procedure for running
the manual tests is documented at
\href{http://k5wiki.kerberos.org/wiki/Manual\_Testing}{http://k5wiki.kerberos.org/wiki/Manual\_Testing}.


\subsection{Cleaning up the build}
\label{build/doing_build:cleaning-up-the-build}\begin{itemize}
\item {} 
Use \code{make clean} to remove all files generated by running make
command.

\item {} 
Use \code{make distclean} to remove all files generated by running
./configure script.  After running \code{make distclean} your source
tree (ideally) should look like the raw (just un-tarred) source
tree.

\end{itemize}


\subsection{Using autoconf}
\label{build/doing_build:using-autoconf}
(If you are not a developer, you can ignore this section.)

In the Kerberos V5 source directory, there is a configure script which
automatically determines the compilation environment and creates the
proper Makefiles for a particular platform.  This configure script is
generated using autoconf, which you should already have installed if
you will be making changes to \code{src/configure.in}.

Normal users will not need to worry about running autoconf; the
distribution comes with the configure script already prebuilt.

The autoconf package comes with a script called \code{autoreconf} that
will automatically run \code{autoconf} and \code{autoheader} as needed.  You
should run \code{autoreconf} from the top source directory, e.g.:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{cd} \PYG{o}{/}\PYG{n}{u1}\PYG{o}{/}\PYG{n}{krb5}\PYG{o}{\PYGZhy{}}\PYG{n}{VERSION}\PYG{o}{/}\PYG{n}{src}
\PYG{n}{autoreconf} \PYG{o}{\PYGZhy{}}\PYG{o}{\PYGZhy{}}\PYG{n}{verbose}
\end{Verbatim}


\section{Options to \emph{configure}}
\label{build/options2configure:options2configure}\label{build/options2configure::doc}\label{build/options2configure:options-to-configure}
There are a number of options to configure which you can use to
control how the Kerberos distribution is built.


\subsection{Most commonly used options}
\label{build/options2configure:most-commonly-used-options}\begin{description}
\item[{\textbf{-}\textbf{-help}}] \leavevmode
Provides help to configure.  This will list the set of commonly
used options for building Kerberos.

\item[{\textbf{-}\textbf{-prefix=}\emph{PREFIX}}] \leavevmode
By default, Kerberos will install the package's files rooted at
\code{/usr/local}.  If you desire to place the binaries into the
directory \emph{PREFIX}, use this option.

\item[{\textbf{-}\textbf{-exec-prefix=}\emph{EXECPREFIX}}] \leavevmode
This option allows one to separate the architecture independent
programs from the host-dependent files (configuration files,
manual pages).  Use this option to install architecture-dependent
programs in \emph{EXECPREFIX}.  The default location is the value of
specified by \textbf{-}\textbf{-prefix} option.

\item[{\textbf{-}\textbf{-localstatedir=}\emph{LOCALSTATEDIR}}] \leavevmode
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[{\textbf{-}\textbf{-with-netlib}{[}=\emph{libs}{]}}] \leavevmode
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 or fails to pass the tests in \code{src/tests/resolv}, you
will need to use this option.

\item[{\textbf{-}\textbf{-with-tcl=}\emph{TCLPATH}}] \leavevmode
Some of the unit-tests in the build tree rely upon using a program
in Tcl.  The directory specified by \emph{TCLPATH} specifies where the
Tcl header file (TCLPATH/include/tcl.h) as well as where the Tcl
library (TCLPATH/lib) should be found.

\item[{\textbf{-}\textbf{-enable-dns-for-realm}}] \leavevmode
Enable the use of DNS to look up a host's Kerberos realm,
if the information is not provided in
\emph{krb5.conf(5)}.  See \emph{mapping\_hostnames}
for information about using DNS to determine the default realm.
DNS lookups for realm names are disabled by default.

\item[{\textbf{-}\textbf{-with-system-et}}] \leavevmode
Use an installed version of the error-table (et) support software,
the compile\_et program, the com\_err.h header file and the 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[{\textbf{-}\textbf{-with-system-ss}}] \leavevmode
Use an installed version of the subsystem command-line interface
software, the mk\_cmds program, the \code{ss/ss.h} header file and the
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 \textbf{SS\_LIB} option.

If this option is not given, the 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[{\textbf{-}\textbf{-with-system-db}}] \leavevmode
Use an installed version of the Berkeley DB package, which must
provide an API compatible with version 1.85.  This option is
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.)

\end{description}


\subsection{Environment variables}
\label{build/options2configure:environment-variables}\begin{description}
\item[{\textbf{CC=}\emph{COMPILER}}] \leavevmode
Use \emph{COMPILER} as the C compiler.

\item[{\textbf{CFLAGS=}\emph{FLAGS}}] \leavevmode
Use \emph{FLAGS} as the default set of C compiler flags.

\item[{\textbf{CPP=}\emph{CPP}}] \leavevmode
C preprocessor to use. (e.g., \code{CPP='gcc -E'})

\item[{\textbf{CPPFLAGS=}\emph{CPPOPTS}}] \leavevmode
Use \emph{CPPOPTS} as the default set of C preprocessor flags.  The
most common use of this option is to select certain \#define's for
use with the operating system's include files.

\item[{\textbf{DB\_HEADER=}\emph{headername}}] \leavevmode
If 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, \code{DB\_HEADER=db3/db\_185.h}.

\item[{\textbf{DB\_LIB=}\emph{libs}...}] \leavevmode
If \code{-ldb} is not the correct library specification for the
Berkeley DB library version to be used, override it with this
option. For example, \code{DB\_LIB=-ldb-3.3}.

\item[{\textbf{DEFCCNAME=}\emph{ccachename}}] \leavevmode
Override the built-in default credential cache name.
For example, \code{DEFCCNAME=DIR:/var/run/user/\%\{USERID\}/ccache}
See \emph{parameter\_expansion} for information about supported
parameter expansions.

\item[{\textbf{DEFCKTNAME=}\emph{keytabname}}] \leavevmode
Override the built-in default client keytab name.
The format is the same as for \emph{DEFCCNAME}.

\item[{\textbf{DEFKTNAME=}\emph{keytabname}}] \leavevmode
Override the built-in default keytab name.
The format is the same as for \emph{DEFCCNAME}.

\item[{\textbf{LD=}\emph{LINKER}}] \leavevmode
Use \emph{LINKER} as the default loader if it should be different from
C compiler as specified above.

\item[{\textbf{LDFLAGS=}\emph{LDOPTS}}] \leavevmode
This option informs the linker where to get additional libraries
(e.g., \code{-L\textless{}lib dir\textgreater{}}).

\item[{\textbf{LIBS=}\emph{LDNAME}}] \leavevmode
This option allows one to specify libraries to be passed to the
linker (e.g., \code{-l\textless{}library\textgreater{}})

\item[{\textbf{SS\_LIB=}\emph{libs}...}] \leavevmode
If \code{-lss} is not the correct way to link in your installed 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 \textbf{-}\textbf{-with-system-ss} is not specified.

\item[{\textbf{YACC}}] \leavevmode
The `Yet Another C Compiler' implementation to use. Defaults to
the first program found out of: `\emph{bison -y}`, `\emph{byacc}`,
`\emph{yacc}`.

\item[{\textbf{YFLAGS}}] \leavevmode
The list of arguments that will be passed by default to \$YACC.
This script will default YFLAGS to the empty string to avoid a
default value of \code{-d} given by some make applications.

\end{description}


\subsection{Fine tuning of the installation directories}
\label{build/options2configure:fine-tuning-of-the-installation-directories}\begin{description}
\item[{\textbf{-}\textbf{-bindir=}\emph{DIR}}] \leavevmode
User executables.  Defaults to \code{EXECPREFIX/bin}, where
\emph{EXECPREFIX} is the path specified by \textbf{-}\textbf{-exec-prefix}
configuration option.

\item[{\textbf{-}\textbf{-sbindir=}\emph{DIR}}] \leavevmode
System admin executables.  Defaults to \code{EXECPREFIX/sbin}, where
\emph{EXECPREFIX} is the path specified by \textbf{-}\textbf{-exec-prefix}
configuration option.

\item[{\textbf{-}\textbf{-sysconfdir=}\emph{DIR}}] \leavevmode
Read-only single-machine data such as krb5.conf.
Defaults to \code{PREFIX/etc}, where
\emph{PREFIX} is the path specified by \textbf{-}\textbf{-prefix} configuration
option.

\item[{\textbf{-}\textbf{-libdir=}\emph{DIR}}] \leavevmode
Object code libraries.  Defaults to \code{EXECPREFIX/lib}, where
\emph{EXECPREFIX} is the path specified by \textbf{-}\textbf{-exec-prefix}
configuration option.

\item[{\textbf{-}\textbf{-includedir=}\emph{DIR}}] \leavevmode
C header files.  Defaults to \code{PREFIX/include}, where \emph{PREFIX} is
the path specified by \textbf{-}\textbf{-prefix} configuration option.

\item[{\textbf{-}\textbf{-datarootdir=}\emph{DATAROOTDIR}}] \leavevmode
Read-only architecture-independent data root.  Defaults to
\code{PREFIX/share}, where \emph{PREFIX} is the path specified by
\textbf{-}\textbf{-prefix} configuration option.

\item[{\textbf{-}\textbf{-datadir=}\emph{DIR}}] \leavevmode
Read-only architecture-independent data.  Defaults to path
specified by \textbf{-}\textbf{-datarootdir} configuration option.

\item[{\textbf{-}\textbf{-localedir=}\emph{DIR}}] \leavevmode
Locale-dependent data.  Defaults to \code{DATAROOTDIR/locale}, where
\emph{DATAROOTDIR} is the path specified by \textbf{-}\textbf{-datarootdir}
configuration option.

\item[{\textbf{-}\textbf{-mandir=}\emph{DIR}}] \leavevmode
Man documentation.  Defaults to \code{DATAROOTDIR/man}, where
\emph{DATAROOTDIR} is the path specified by \textbf{-}\textbf{-datarootdir}
configuration option.

\end{description}


\subsection{Program names}
\label{build/options2configure:program-names}\begin{description}
\item[{\textbf{-}\textbf{-program-prefix=}\emph{PREFIX}}] \leavevmode
Prepend \emph{PREFIX} to the names of the programs when installing
them. For example, specifying \code{-{-}program-prefix=mit-} at the
configure time will cause the program named \code{abc} to be
installed as \code{mit-abc}.

\item[{\textbf{-}\textbf{-program-suffix=}\emph{SUFFIX}}] \leavevmode
Append \emph{SUFFIX} to the names of the programs when installing them.
For example, specifying \code{-{-}program-suffix=-mit} at the configure
time will cause the program named \code{abc} to be installed as
\code{abc-mit}.

\item[{\textbf{-}\textbf{-program-transform-name=}\emph{PROGRAM}}] \leavevmode
Run \code{sed -e PROGRAM} on installed program names. (\emph{PROGRAM} is a
sed script).

\end{description}


\subsection{System types}
\label{build/options2configure:system-types}\begin{description}
\item[{\textbf{-}\textbf{-build=}\emph{BUILD}}] \leavevmode
Configure for building on \emph{BUILD}
(e.g., \code{-{-}build=x86\_64-linux-gnu}).

\item[{\textbf{-}\textbf{-host=}\emph{HOST}}] \leavevmode
Cross-compile to build programs to run on \emph{HOST}
(e.g., \code{-{-}host=x86\_64-linux-gnu}).  By default, Kerberos V5
configuration will look for ``build'' option.

\end{description}


\subsection{Optional features}
\label{build/options2configure:optional-features}\begin{description}
\item[{\textbf{-}\textbf{-disable-option-checking}}] \leavevmode
Ignore unrecognized --enable/--with options.

\item[{\textbf{-}\textbf{-disable-}\emph{FEATURE}}] \leavevmode
Do not include \emph{FEATURE} (same as --enable-FEATURE=no).

\item[{\textbf{-}\textbf{-enable-}\emph{FEATURE}{[}=\emph{ARG}{]}}] \leavevmode
Include \emph{FEATURE} {[}ARG=yes{]}.

\item[{\textbf{-}\textbf{-enable-maintainer-mode}}] \leavevmode
Enable rebuilding of source files, Makefiles, etc.

\item[{\textbf{-}\textbf{-disable-delayed-initialization}}] \leavevmode
Initialize library code when loaded.  Defaults to delay until
first use.

\item[{\textbf{-}\textbf{-disable-thread-support}}] \leavevmode
Don't enable thread support.  Defaults to enabled.

\item[{\textbf{-}\textbf{-disable-rpath}}] \leavevmode
Suppress run path flags in link lines.

\item[{\textbf{-}\textbf{-enable-athena}}] \leavevmode
Build with MIT Project Athena configuration.

\item[{\textbf{-}\textbf{-disable-kdc-lookaside-cache}}] \leavevmode
Disable the cache which detects client retransmits.

\item[{\textbf{-}\textbf{-disable-pkinit}}] \leavevmode
Disable PKINIT plugin support.

\item[{\textbf{-}\textbf{-disable-aesni}}] \leavevmode
Disable support for using AES instructions on x86 platforms.

\item[{\textbf{-}\textbf{-enable-asan}{[}=\emph{ARG}{]}}] \leavevmode
Enable building with asan memory error checking.  If \emph{ARG} is
given, it controls the -fsanitize compilation flag value (the
default is ``address'').

\end{description}


\subsection{Optional packages}
\label{build/options2configure:optional-packages}\begin{description}
\item[{\textbf{-}\textbf{-with-}\emph{PACKAGE}{[}=ARG{]}}] \leavevmode
Use \emph{PACKAGE} (e.g., \code{-{-}with-imap}).  The default value of \emph{ARG}
is \code{yes}.

\item[{\textbf{-}\textbf{-without-}\emph{PACKAGE}}] \leavevmode
Do not use \emph{PACKAGE} (same as \code{-{-}with-PACKAGE=no})
(e.g., \code{-{-}without-libedit}).

\item[{\textbf{-}\textbf{-with-size-optimizations}}] \leavevmode
Enable a few optimizations to reduce code size possibly at some
run-time cost.

\item[{\textbf{-}\textbf{-with-system-et}}] \leavevmode
Use the com\_err library and compile\_et utility that are already
installed on the system, instead of building and installing
local versions.

\item[{\textbf{-}\textbf{-with-system-ss}}] \leavevmode
Use the ss library and mk\_cmds utility that are already installed
on the system, instead of building and using private versions.

\item[{\textbf{-}\textbf{-with-system-db}}] \leavevmode
Use the berkeley db utility already installed on the system,
instead of using a private version.  This option is not
recommended; enabling it may result in incompatibility with key
databases originating on other systems.

\item[{\textbf{-}\textbf{-with-netlib=}\emph{LIBS}}] \leavevmode
Use the resolver library specified in \emph{LIBS}.  Use this variable
if the C library resolver is insufficient or broken.

\item[{\textbf{-}\textbf{-with-hesiod=}\emph{path}}] \leavevmode
Compile with Hesiod support.  The \emph{path} points to the Hesiod
directory.  By default Hesiod is unsupported.

\item[{\textbf{-}\textbf{-with-ldap}}] \leavevmode
Compile OpenLDAP database backend module.

\item[{\textbf{-}\textbf{-with-tcl=}\emph{path}}] \leavevmode
Specifies that \emph{path} is the location of a Tcl installation.
Tcl is needed for some of the tests run by `make check'; such tests
will be skipped if this option is not set.

\item[{\textbf{-}\textbf{-with-vague-errors}}] \leavevmode
Do not send helpful errors to client.  For example, if the KDC
should return only vague error codes to clients.

\item[{\textbf{-}\textbf{-with-crypto-impl=}\emph{IMPL}}] \leavevmode
Use specified crypto implementation (e.g., \textbf{-}\textbf{-with-crypto-impl=}\emph{openssl}).  The default is the native MIT
Kerberos implementation \code{builtin}.  The other currently
implemented crypto backend is \code{openssl}.  (See
\emph{mitK5features})

\item[{\textbf{-}\textbf{-with-prng-alg=}\emph{ALG}}] \leavevmode
Use specified PRNG algorithm.  For example, to use the OS native
prng specify \code{-{-}with-prng-alg=os}.  The default is \code{fortuna}.
(See \emph{mitK5features})

\item[{\textbf{-}\textbf{-with-pkinit-crypto-impl=}\emph{IMPL}}] \leavevmode
Use the specified pkinit crypto implementation \emph{IMPL}.
Defaults to using OpenSSL.

\item[{\textbf{-}\textbf{-without-libedit}}] \leavevmode
Do not compile and link against libedit.  Some utilities will no
longer offer command history or completion in interactive mode if
libedit is disabled.

\item[{\textbf{-}\textbf{-with-readline}}] \leavevmode
Compile and link against GNU readline, as an alternative to libedit.
Building with readline breaks the dejagnu test suite, which is a
subset of the tests run by `make check'.

\item[{\textbf{-}\textbf{-with-system-verto}}] \leavevmode
Use an installed version of libverto.  If the libverto header and
library are not in 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, the build system will try to detect
an installed version of libverto and use it if it is found.
Otherwise, a version supplied with the Kerberos sources will be
built and installed.  The built-in version does not contain the
full set of back-end modules and is not a suitable general
replacement for the upstream version, but will work for the
purposes of Kerberos.

Specifying \textbf{-}\textbf{-without-system-verto} will cause the built-in
version of libverto to be used unconditionally.

\item[{\textbf{-}\textbf{-with-krb5-config=}\emph{PATH}}] \leavevmode
Use the krb5-config program at \emph{PATH} to obtain the build-time
default credential cache, keytab, and client keytab names.  The
default is to use \code{krb5-config} from the program path.  Specify
\code{-{-}without-krb5-config} to disable the use of krb5-config and
use the usual built-in defaults.

\end{description}


\subsection{Examples}
\label{build/options2configure:examples}
For example, in order to configure Kerberos on a Solaris machine using
the suncc compiler with the optimizer turned on, run the configure
script with the following options:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZpc{} ./configure CC=suncc CFLAGS=\PYGZhy{}O
\end{Verbatim}

For a slightly more complicated example, consider a system where
several packages to be used by Kerberos are installed in
\code{/usr/foobar}, including Berkeley DB 3.3, and an ss library that
needs to link against the curses library.  The configuration of
Kerberos might be done thus:

\begin{Verbatim}[commandchars=\\\{\}]
./configure CPPFLAGS=\PYGZhy{}I/usr/foobar/include LDFLAGS=\PYGZhy{}L/usr/foobar/lib \PYGZbs{}
\PYGZhy{}\PYGZhy{}with\PYGZhy{}system\PYGZhy{}et \PYGZhy{}\PYGZhy{}with\PYGZhy{}system\PYGZhy{}ss \PYGZhy{}\PYGZhy{}with\PYGZhy{}system\PYGZhy{}db  \PYGZbs{}
SS\PYGZus{}LIB=\PYGZsq{}\PYGZhy{}lss \PYGZhy{}lcurses\PYGZsq{}  DB\PYGZus{}HEADER=db3/db\PYGZus{}185.h DB\PYGZus{}LIB=\PYGZhy{}ldb\PYGZhy{}3.3
\end{Verbatim}


\section{osconf.hin}
\label{build/osconf:osconf-hin}\label{build/osconf::doc}
There is one configuration file which you may wish to edit to control
various compile-time parameters in the Kerberos distribution:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{include}\PYG{o}{/}\PYG{n}{osconf}\PYG{o}{.}\PYG{n}{hin}
\end{Verbatim}

The list that follows is by no means complete, just some of the more
interesting variables.
\begin{description}
\item[{\textbf{DEFAULT\_PROFILE\_PATH}}] \leavevmode
The pathname to the file which contains the profiles for the known
realms, their KDCs, etc. The default value is \code{/etc/krb5.conf}.

\item[{\textbf{DEFAULT\_KEYTAB\_NAME}}] \leavevmode
The type and pathname to the default server keytab file.  The
default is \emph{DEFKTNAME}.

\item[{\textbf{DEFAULT\_KDC\_ENCTYPE}}] \leavevmode
The default encryption type for the KDC database master key.  The
default value is \code{aes256-cts-hmac-sha1-96}.

\item[{\textbf{RCTMPDIR}}] \leavevmode
The directory which stores replay caches.  The default is
\code{/var/tmp}.

\item[{\textbf{DEFAULT\_KDB\_FILE}}] \leavevmode
The location of the default database.  The default value is
\emph{LOCALSTATEDIR}\code{/krb5kdc}\code{/principal}.

\end{description}



\renewcommand{\indexname}{Index}
\printindex
\end{document}