svn rev #25403: trunk/doc/rst_source/krb_build/
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Fri Oct 21 15:10:57 EDT 2011
http://src.mit.edu/fisheye/changelog/krb5/?cs=25403
Commit By: tsitkova
Log Message:
Updated some of the topics related to "how to build Kerberos".
Changed Files:
U trunk/doc/rst_source/krb_build/directory_org.rst
U trunk/doc/rst_source/krb_build/doing_build.rst
U trunk/doc/rst_source/krb_build/osconf.rst
Modified: trunk/doc/rst_source/krb_build/directory_org.rst
===================================================================
--- trunk/doc/rst_source/krb_build/directory_org.rst 2011-10-21 18:03:54 UTC (rev 25402)
+++ trunk/doc/rst_source/krb_build/directory_org.rst 2011-10-21 19:10:57 UTC (rev 25403)
@@ -5,68 +5,60 @@
=============== ==============================================
*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)
+*ccapi* Credential cache services
+*clients* Kerberos V5 user programs (See :ref:`user_commands`)
+*config* Configure scripts
+*config-files* Sample Kerberos configuration files
+*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* Kerberos V5 Authentication Service and Key Distribution Center
+*kim* Kerberos Identiry Management API
+lib_ Libraries for use with/by Kerberos V5
+*plugins* Kerberos plugins directory
+*po* Localization infrastructure
+*prototype* Templates files containing the MIT copyright message and a placeholder for the title and description of the file.
+*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:
+ - The *apputils* directory contains the code for the generic network servicing.
+ - 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.
-**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.
+The *util* 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*).
+ - 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*;
+ - a generic support library *support* used by several of our other libraries;
+ - the build infrastructure for building lightweight Kerberos client (*collected-client-lib*)
+ - the tool for validating Kerberos configuration files (*confvalidator*);
+ - the toolkit for kernel integrators for building krb5 code subsets (*gss-kernel-lib*);
+ - source code for building Kerberos V5 on MacOS (*mac*)
+ - Windows *getopt* operations (*windows*)
Modified: trunk/doc/rst_source/krb_build/doing_build.rst
===================================================================
--- trunk/doc/rst_source/krb_build/doing_build.rst 2011-10-21 18:03:54 UTC (rev 25402)
+++ trunk/doc/rst_source/krb_build/doing_build.rst 2011-10-21 19:10:57 UTC (rev 25403)
@@ -1,42 +1,72 @@
-Doing the Build
+Doing the build
======================
+Using *autoconf*
+-------------------
+
+(If you are not a developer, you can skip this section.)
+
+In most of the Kerberos V5 source directories, there is a *configure* script which automatically determines
+the compilation environment and creates the proper Makefiles for a particular platform.
+These configure files are generated using *autoconf*, which can be found in the *src/util/autoconf* directory in the distribution.
+
+Normal users will not need to worry about running *autoconf*; the distribution comes with the configure files already prebuilt.
+
+Note that in order to run *autoconf*, you must have GNU m4 in your path.
+Before you use the *autoconf* in the Kerberos V5 source tree, you may also need to run configure,
+and then run make in the *src/util/autoconf* directory in order to properly set up *autoconf*.
+
+One tool which is provided for the convenience of developers can be found in *src/util/reconf*.
+This program should be run while the current directory is the top source directory.
+It will automatically rebuild any configure files which need rebuilding.
+If you know that you have made a change that will require that all the configure files need to be rebuilt from scratch, specify the *--force* option::
+
+ cd /u1/krb5-1.9/src
+ ./util/reconf --force
+
+Then follow the instructions for building packaged source trees (below).
+To install the binaries into a binary tree, do::
+
+ cd /u1/krb5-1.9/src
+ make all
+ make install DESTDIR=somewhere-else
+
You have a number of different options in how to build Kerberos.
-Building Within a Single Tree
+.. _do_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.
+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
+ 1. cd /u1/krb5-1.9/src
2. ./configure
3. make
That's it!
-Building with Separate Build Directories
+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.)
+(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::
+For example, if you wish to store the binaries in *tmpbuild* build directory you might use the following procedure::
- 1. mkdir /u1/krb5-1.6/pmax
- 2. cd /u1/krb5-1.6/pmax
- 3. ../src/configure
+ 1. mkdir /u1/tmpbuild
+ 2. cd /u1/tmpbuild
+ 3. /u1/krb5-1.9/src/configure
4. make
-Building Using *lndir*
+Building using *lndir*
-----------------------
If you wish to keep separate build directories for each platform,
@@ -45,18 +75,18 @@
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
+ 1. mkdir /u1/krb5-1.9/solaris
+ 2. cd /u1/krb5-1.9/solaris
+ 3. /u1/krb5-1.9/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.
+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
+Installing the binaries
-------------------------
Once you have built Kerberos, you should install the binaries. You can do this by running::
@@ -70,27 +100,40 @@
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.
+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
+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.)::
+(i.e., the directory where you sent typed make to start building Kerberos; see :ref:`do_build`.)::
- % make check
+ 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).
+ * 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.
+ Alternatively, you can run *make fake-install* ( need more info).
+ * 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).
+
+Cleaning up the build
+-------------------------
+
+ - Use *make clean* to remove all files generated by running *make* command.
+ - Use *make distclean* to remove all files generated by running *./configure * script.
+ After running *make distclean* your source tree (ideally) should look like the raw (just un-tarred) source tree with executed *util/reconf* command.
+
+
+
+
Modified: trunk/doc/rst_source/krb_build/osconf.rst
===================================================================
--- trunk/doc/rst_source/krb_build/osconf.rst 2011-10-21 18:03:54 UTC (rev 25402)
+++ trunk/doc/rst_source/krb_build/osconf.rst 2011-10-21 19:10:57 UTC (rev 25403)
@@ -3,25 +3,20 @@
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
+ include/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.
+ The type and pathname to the default server keytab file. The default is /etc/krb5.keytab.
**DEFAULT_KDC_ENCTYPE**
- The default encryption type for the KDC. The default value is des3-cbc-sha1.
+ The default encryption type for the KDC. The default value is aes256-cts-hmac-sha1-96.
**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.
+ The directory which stores replay caches. The default is /var/tmp.
**DEFAULT_KDB_FILE**
The location of the default database. The default value is /usr/local/var/krb5kdc/principal.
More information about the cvs-krb5
mailing list