svn rev #25393: trunk/doc/rst_source/ krb_build/ krb_users/user_commands/
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Thu Oct 20 18:50:22 EDT 2011
http://src.mit.edu/fisheye/changelog/krb5/?cs=25393
Commit By: tsitkova
Log Message:
Added documentation on how to build Kerberos. Mainly from the Installation Guide with some corrections.
Changed Files:
A trunk/doc/rst_source/krb_build/
A trunk/doc/rst_source/krb_build/directory_org.rst
A trunk/doc/rst_source/krb_build/doing_build.rst
A trunk/doc/rst_source/krb_build/index.rst
A trunk/doc/rst_source/krb_build/options2configure.rst
A trunk/doc/rst_source/krb_build/osconf.rst
U trunk/doc/rst_source/krb_users/user_commands/index.rst
Added: trunk/doc/rst_source/krb_build/directory_org.rst
===================================================================
--- trunk/doc/rst_source/krb_build/directory_org.rst (rev 0)
+++ trunk/doc/rst_source/krb_build/directory_org.rst 2011-10-20 22:50:22 UTC (rev 25393)
@@ -0,0 +1,72 @@
+Organization of the source directory
+============================================
+
+Below is a brief overview of the organization of the complete source directory. More detailed descriptions follow.
+
+=============== ==============================================
+*appl* Kerberos application client and server programs
+*clients* Kerberos V5 user programs (See :ref:`user_commands`)
+gen-manpages_ manpages for Kerberos V5 and the Kerberos V5 login program
+*include* include files needed to build the Kerberos system
+*kadmin* administrative interface to the Kerberos master database: :ref:`kadmin(1)`, :ref:`kdb5_util(8)`, :ref:`ktutil(1)`.
+*kdc* the Kerberos V5 Authentication Service and Key Distribution Center
+*krb524* utilities for converting Kerberos V5 credentials into Kerberos V4 credentials suitable for use with applications that for whatever reason do not use V5 directly.
+lib_ libraries for use with/by Kerberos V5
+*mac* source code for building Kerberos V5 on MacOS
+prototype_ templates for source code files
+*slave* utilities for propagating the database to slave KDCs :ref:`kprop(8)` and :ref:`kpropd(8)`
+*tests* test suite
+util_ various utilities for building/configuring the code, sending bug reports, etc.
+*windows* source code for building Kerberos V5 on Windows (see windows/README)
+=============== ==============================================
+
+
+**gen-manpages**
+----------------
+
+There are two manual pages in this directory. One is an introduction to the Kerberos system.
+The other describes the *.k5login* file which allows users to give access with their UID
+to other users authenticated by the Kerberos system.
+
+.. _lib:
+
+**lib**
+------------------
+
+The *lib* directory contain several subdirectories as well as some definition and glue files.
+The *crypto* subdirectory contains the Kerberos V5 encryption library.
+The *gssapi* library contains the Generic Security Services API, which is a library of commands to be used in secure client-server communication.
+The *kadm5* directory contains the libraries for the KADM5 administration utilities.
+The Kerberos 5 database libraries are contained in *kdb*.
+The *krb5* directory contains Kerberos 5 API.
+The *rpc* directory contains the API for the Kerberos Remote Procedure Call protocol.
+The *apputils* directory contains the code for the generic network servicing.
+
+.. _prototype:
+
+**prototype**
+-----------------
+
+This directory contains several template files.
+The *prototype.h* and *prototype.c* files contain the MIT copyright message and a placeholder for the title and description of the file.
+*prototype.h* also has a short template for writing ifdef and ifndef preprocessor statements.
+The *getopt.c* file provides a template for writing code that will parse the options with which a program was called.
+
+.. _util:
+
+**util**
+-----------------------------------
+
+
+This directory contains several utility programs and libraries.
+The programs used to configure and build the code, such as *autoconf, lndir, kbuild, reconf, and makedepend*, are in this directory.
+The *profile* directory contains most of the functions which parse the Kerberos configuration files (krb5.conf and kdc.conf).
+Also in this directory are
+the Kerberos error table library and
+utilities (et),
+the Sub-system library and utilities (ss),
+database utilities (db2),
+pseudo-terminal utilities (pty),
+bug-reporting program send-pr, and
+a generic support library support used by several of our other libraries.
+
Added: trunk/doc/rst_source/krb_build/doing_build.rst
===================================================================
--- trunk/doc/rst_source/krb_build/doing_build.rst (rev 0)
+++ trunk/doc/rst_source/krb_build/doing_build.rst 2011-10-20 22:50:22 UTC (rev 25393)
@@ -0,0 +1,96 @@
+Doing the Build
+======================
+
+You have a number of different options in how to build Kerberos.
+
+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.
+
+ * Building Within a Single Tree
+ * Building with Separate Build Directories:
+ * Building using lndir:
+
+If you don't want separate build trees for each architecture, then use the following abbreviated procedure::
+
+ 1. cd /u1/krb5-1.6/src
+ 2. ./configure
+ 3. make
+
+That's it!
+
+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 create a build directory for pmax binaries you might use the following procedure::
+
+ 1. mkdir /u1/krb5-1.6/pmax
+ 2. cd /u1/krb5-1.6/pmax
+ 3. ../src/configure
+ 4. make
+
+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::
+
+ 1. mkdir /u1/krb5-1.6/solaris
+ 2. cd /u1/krb5-1.6/solaris
+ 3. /u1/krb5-1.6/src/util/lndir `pwd`/../src
+ 4. ./configure
+ 5. make
+
+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.
+
+
+Installing the Binaries
+-------------------------
+
+Once you have built Kerberos, you should install the binaries. You can do this by running::
+
+ make install
+
+
+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::
+
+ make install DESTDIR=/path/to/destdir
+
+
+This will install the binaries under DESTDIR/PREFIX, e.g., the user programs will install into *DESTDIR\/PREFIX\/bin*,
+the libraries into *DESTDIR\/PREFIX\/lib*, etc.
+
+.. note:: If you want to test the build (see Testing the Build), you usually do not need to do a make install first.
+
+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.
+
+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 Doing the Build.)::
+
+ % make check
+
+
+However, there are several prerequisites that must be satisfied first:
+
+ * Configure and build Kerberos with Tcl support. Tcl is used to drive the test suite. This often means passing --with-tcl to configure to tell it the location of the Tcl configuration script. (See :ref:`options2configure`.)
+ * You have to run make install before running make check, or the test suite will often pick up the installed version of Kerberos rather than the newly built one. You can install into a prefix that isn't in the system library search path, though. This theoretically could be fixed with the appropriate environment variable magic in the test suite, but hasn't been yet.
+ * In order to test the RPC layer, the local system has to be running the portmap daemon and it has to be listening to the regular network interface (not just localhost).
+
Added: trunk/doc/rst_source/krb_build/index.rst
===================================================================
--- trunk/doc/rst_source/krb_build/index.rst (rev 0)
+++ trunk/doc/rst_source/krb_build/index.rst 2011-10-20 22:50:22 UTC (rev 25393)
@@ -0,0 +1,57 @@
+.. _build_V5:
+
+Building Kerberos V5
+===================================
+
+.. note:: This document was copied from **Kerberos V5 Installation Guide** with minor changes.
+ Currently it is under review. Please, send your feedback, corrections and additions to krb5-bugs at mit.edu.
+ Your contribution is greatly appreciated.
+
+
+
+
+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 build tree, which contains the compiled \*.o file and executables,
+separate from your source tree, you will need a make program which supports *VPATH*,
+or you will need to use a tool such as lndir to produce a symbolic link tree for your build tree.
+
+The first step in each of these build procedures is to unpack the source distribution.
+The Kerberos V5 distribution comes in a tar file, generally named krb5-1.9.tar
+(for version 1.9. We will assume that version is 1.9. Please, adjust this number accordingly),
+which contains a compressed tar file consisting of the sources for all of Kerberos (generally krb5-1.9.tar.gz)
+and a PGP signature for this source tree (generally krb5-1.9.tar.gz.asc).
+MIT highly recommends that you verify the integrity of the source code using this signature.
+
+Unpack the compressed tar file in some directory, such as /u1/krb5-1.9.
+(In the rest of this document, we will assume that you have chosen to unpack the Kerberos V5 source distribution in this directory.
+Note that the tarfiles will by default all unpack into the ./krb5-1.9 directory,
+so that if your current directory is /u1 when you unpack the tarfiles, you will get /u1/krb5-1.9/src, etc.)
+
+Contents:
+---------
+
+
+.. toctree::
+ :maxdepth: 1
+
+ directory_org.rst
+ doing_build.rst
+ options2configure.rst
+ osconf.rst
+
+
+
+------------
+
+Feedback:
+
+Please, provide your feedback or suggest a new topic at krb5-bugs at mit.edu?subject=Documentation___build
+
Added: trunk/doc/rst_source/krb_build/options2configure.rst
===================================================================
--- trunk/doc/rst_source/krb_build/options2configure.rst (rev 0)
+++ trunk/doc/rst_source/krb_build/options2configure.rst 2011-10-20 22:50:22 UTC (rev 25393)
@@ -0,0 +1,111 @@
+.. _options2configure:
+
+Options to Configure
+=========================
+
+There are a number of options to configure which you can use to control how the Kerberos distribution is built. i
+The following table lists the most commonly used options to Kerberos V5's configure program.
+
+
+--help
+ Provides help to configure. This will list the set of commonly used options for building Kerberos.
+--prefix=PREFIX
+ By default, Kerberos will install the package's files rooted at '\/usr\/local' as in '\/usr\/local/bin', '\/usr\/local\/sbin', etc.
+ If you desire a different location, use this option.
+--exec-prefix=EXECPREFIX
+ This option allows one to separate the architecture independent programs from the configuration files and manual pages.
+--localstatedir=LOCALSTATEDIR
+ This option sets the directory for locally modifiable single-machine data.
+ In Kerberos, this mostly is useful for setting a location for the KDC data files,
+ as they will be installed in LOCALSTATEDIR\/krb5kdc, which is by default PREFIX\/var\/krb5kdc.
+CC=COMPILER
+ Use COMPILER as the C compiler.
+CFLAGS=FLAGS
+ Use FLAGS as the default set of C compiler flags.
+ Note that if you use the native Ultrix compiler on a DECstation you are likely to lose
+ if you pass no flags to cc; md4.c takes an estimated 3,469 billion years to compile if you provide neither the -g flag nor the -O flag to cc.
+CPPFLAGS=CPPOPTS
+ Use 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.
+LD=LINKER
+ Use LINKER as the default loader if it should be different from C compiler as specified above.
+LDFLAGS=LDOPTS
+ This option allows one to specify optional arguments to be passed to the linker. This might be used to specify optional library paths.
+--with-krb4
+ This option enables Kerberos V4 backwards compatibility using the builtin Kerberos V4 library.
+--with-krb4=KRB4DIR
+ This option enables Kerberos V4 backwards compatibility using a pre-existing Kerberos V4 installation.
+ The directory specified by KRB4DIR specifies where the V4 header files should be found (KRB4DIR\/include)
+ as well as where the V4 Kerberos library should be found (KRB4DIR/lib).
+--without-krb4
+ Disables Kerberos V4 backwards compatibility.
+ This prevents Kerberos V4 clients from using the V5 services including the KDC.
+ This would be useful if you know you will never install or need to interact with V4 clients.
+--with-netlib[=libs]
+ Allows for suppression of or replacement of network libraries.
+ By default, Kerberos V5 configuration will look for *-lnsl* and *-lsocket*.
+ If your operating system has a broken resolver library (see Solaris versions 2.0 through 2.3)
+ or fails to pass the tests in src/tests/resolv you will need to use this option.
+--with-tcl=TCLPATH
+ Some of the unit-tests in the build tree rely upon using a program in Tcl.
+ The directory specified by TCLPATH specifies where the Tcl header file (TCLPATH/include/tcl.h
+ as well as where the Tcl library should be found (TCLPATH/lib).
+--enable-shared
+ This option will turn on the building and use of shared library objects in the Kerberos build. This option is only supported on certain platforms.
+--enable-dns
+
+--enable-dns-for-kdc
+
+--enable-dns-for-realm
+ Enable the use of DNS to look up a host's Kerberos realm, or a realm's KDCs, if the information is not provided in krb5.conf.
+ See Hostnames for the Master and Slave KDCs for information about using DNS to locate the KDCs,
+ and Mapping Hostnames onto Kerberos Realms for information about using DNS to determine the default realm.
+ By default, DNS lookups are enabled for the former but not for the latter.
+--enable-kdc-replay-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.
+--with-system-et
+ Use an installed version of the error-table 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 CPPFLAGS=-I/some/dir and 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.
+--with-system-ss
+ Use an installed version of the subsystem command-line interface software,
+ the mk_cmds program, the ss/ss.h header file and the ss library.
+ If these are not in the default locations, you may wish to specify CPPFLAGS=-I/some/dir and LDFLAGS=-L/some/other/dir options
+ at configuration time as well. See also the 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.
+SS_LIB=libs...
+ If -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 --with-system-ss is not specified.
+--with-system-db
+ Use an installed version of the Berkeley DB package, which must provide an API compatible with version 1.85.
+ This option is 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.)
+DB_HEADER=headername.h
+ 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, DB_HEADER=db3/db_185.h.
+DB_LIB=libs...
+ If -ldb is not the correct library specification for the Berkeley DB library version to be used, override it with this option. For example, DB_LIB=-ldb-3.3.
+
+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::
+
+ % ./configure CC=suncc CFLAGS=-O
+
+
+For a slightly more complicated example, consider a system where several packages to be used by Kerberos are installed in /usr/foobar, i
+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::
+
+ ./configure CPPFLAGS=-I/usr/foobar/include LDFLAGS=-L/usr/foobar/lib \
+ --with-system-et --with-system-ss --with-system-db \
+ SS_LIB='-lss -lcurses' \
+ DB_HEADER=db3/db_185.h DB_LIB=-ldb-3.3
+
+
+In previous releases, --with- options were used to specify the compiler and linker and their options.
+
Added: trunk/doc/rst_source/krb_build/osconf.rst
===================================================================
--- trunk/doc/rst_source/krb_build/osconf.rst (rev 0)
+++ trunk/doc/rst_source/krb_build/osconf.rst 2011-10-20 22:50:22 UTC (rev 25393)
@@ -0,0 +1,27 @@
+osconf.hin
+==============
+
+There is one configuration file which you may wish to edit to control various compile-time parameters in the Kerberos distribution::
+
+ include/stock/osconf.hin
+
+The list that follows is by no means complete, just some of the more interesting variables.
+
+.. note:: The former configuration file config.h no longer exists
+ as its functionality has been merged into the auto-configuration process. See Options to Configure.
+
+
+**DEFAULT_PROFILE_PATH**
+ The pathname to the file which contains the profiles for the known realms, their KDCs, etc. The default value is /etc/krb5.conf.
+
+ The profile file format is no longer the same format as Kerberos V4's krb.conf file.
+**DEFAULT_KEYTAB_NAME**
+ The type and pathname to the default server keytab file (the equivalent of Kerberos V4's /etc/srvtab). The default is /etc/krb5.keytab.
+**DEFAULT_KDC_ENCTYPE**
+ The default encryption type for the KDC. The default value is des3-cbc-sha1.
+**KDCRCACHE**
+ The name of the replay cache used by the KDC. The default value is krb5kdc_rcache.
+**RCTMPDIR**
+ The directory which stores replay caches. The default is to try /var/tmp, /usr/tmp, /var/usr/tmp, and /tmp.
+**DEFAULT_KDB_FILE**
+ The location of the default database. The default value is /usr/local/var/krb5kdc/principal.
Modified: trunk/doc/rst_source/krb_users/user_commands/index.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/index.rst 2011-10-20 22:19:39 UTC (rev 25392)
+++ trunk/doc/rst_source/krb_users/user_commands/index.rst 2011-10-20 22:50:22 UTC (rev 25393)
@@ -1,3 +1,5 @@
+.. _user_commands:
+
User commands
====================================
More information about the cvs-krb5
mailing list