diff options
Diffstat (limited to 'doc/pdf/build.tex')
| -rw-r--r-- | doc/pdf/build.tex | 993 |
1 files changed, 993 insertions, 0 deletions
diff --git a/doc/pdf/build.tex b/doc/pdf/build.tex new file mode 100644 index 000000000000..43c9d606edb1 --- /dev/null +++ b/doc/pdf/build.tex @@ -0,0 +1,993 @@ +% 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} |