From 7c5214d28f984c31bedc3207b2f5c4bfe4791126 Mon Sep 17 00:00:00 2001 From: Ezra Peisach Date: Fri, 20 Oct 1995 18:11:04 +0000 Subject: [PATCH] Document shared library support - including gotchas on individual platforms. Add initial comments on SGI 5.2 libsocket brokeness (fixed in 5.3) git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@6974 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/ChangeLog | 5 + doc/install.texi | 273 ++++++++++++++++++++++++++++++++++------------- 2 files changed, 202 insertions(+), 76 deletions(-) diff --git a/doc/ChangeLog b/doc/ChangeLog index ef7d884c5..d11e1d3b7 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +Fri Oct 20 14:06:35 1995 Ezra Peisach + + * install.texi (Shared Library Support): Document shared library + specifics. + Tue Oct 17 19:23:50 1995 Ezra Peisach * .Sanitize (Things-to-keep): Add Makefile diff --git a/doc/install.texi b/doc/install.texi index 7b53f9f6a..ddedb5ab6 100644 --- a/doc/install.texi +++ b/doc/install.texi @@ -126,7 +126,7 @@ This is edition @value{EDITION}, for Kerberos V5 version @value{VERSION}. How Kerberos Works: A Schematic Description -* Network Services:: +* Network Services:: * Kerberos Tickets:: * The Kerberos Database:: * Kerberos Realms:: @@ -146,8 +146,9 @@ Building Kerberos * Doing the Build:: Compiling Kerberos. * Testing the Build:: Making sure Kerberos built correctly. * Options to Configure:: +* osconf.h:: +* Shared Library Support:: * OS Incompatibilities:: Special cases to watch for. -* Configuration .h files:: Kerberos V5's header files. * Using Autoconf:: Modifying Kerberos V5's configuration scripts. @@ -157,6 +158,14 @@ Doing the Build * Building with Separate Build Directories:: * Building using lndir:: +Shared Library Support + +* Shared Library Theory:: +* NetBSD Shared Library Support:: +* AIX 3.2.5 Shared Library Support:: +* Solaris 5.3 Shared Library Support:: +* Alpha OSF/1 Shared Library Support:: + Operating System Incompatibilities * Ultrix 4.2/3:: @@ -165,10 +174,7 @@ Operating System Incompatibilities * BSDI:: * Solaris versions 2.0 through 2.3:: * Solaris 2.X:: - -Configuration Header Files - -* osconf.h:: +* SGI Irix 5.X:: Installation @@ -187,8 +193,8 @@ Installation on any Machine Configuration files -* krb5.conf:: -* Converting V4 configuration files:: +* krb5.conf:: +* Converting V4 configuration files:: * /etc/services:: Installing the KDC @@ -249,7 +255,7 @@ Service for Open Network Systems}, a paper presented at Winter USENIX 1988, in Dallas, Texas. @menu -* Network Services:: +* Network Services:: * Kerberos Tickets:: * The Kerberos Database:: * Kerberos Realms:: @@ -258,7 +264,7 @@ Service for Open Network Systems}, a paper presented at Winter USENIX * The User-Kerberos Interaction:: @end menu -@node Network Services , Kerberos Tickets, How Kerberos Works, How Kerberos Works +@node Network Services, Kerberos Tickets, How Kerberos Works, How Kerberos Works @section Network Services and Their Client Programs In an environment that provides network services, you use @dfn{client} @@ -268,7 +274,7 @@ and you want to @samp{rlogin} to another machine. You use the local @samp{rlogin} client program to contact the remote machine's @samp{rlogind} daemon. -@node Kerberos Tickets, The Kerberos Database, Network Services , How Kerberos Works +@node Kerberos Tickets, The Kerberos Database, Network Services, How Kerberos Works @section Kerberos Tickets Under Kerberos, the @samp{rlogind} daemon allows you to login to a @@ -449,8 +455,9 @@ porting Kerberos V5 to a new platform. * Doing the Build:: Compiling Kerberos. * Testing the Build:: Making sure Kerberos built correctly. * Options to Configure:: +* osconf.h:: +* Shared Library Support:: * OS Incompatibilities:: Special cases to watch for. -* Configuration .h files:: Kerberos V5's header files. * Using Autoconf:: Modifying Kerberos V5's configuration scripts. @end menu @@ -567,7 +574,7 @@ building Kerberos; see @ref{Doing the Build}.): % @b{make check} @end example -@node Options to Configure, OS Incompatibilities, Testing the Build, Building Kerberos +@node Options to Configure, osconf.h, Testing the Build, Building Kerberos @section Options to Configure There are a number of options to @samp{configure} which you can use to @@ -680,7 +687,156 @@ script with the following options: % configure --with-cc=suncc --with-ccopts=-O @end example -@node OS Incompatibilities, Configuration .h files, Options to Configure, Building Kerberos +@node osconf.h, Shared Library Support, Options to Configure, Building Kerberos +@section @file{osconf.h} + +There is one configuration file which you may wish to edit to control +various compile-time parameters in the Kerberos distribution: +@file{osconf.h}. + +Please note: The former configuration file @file{config.h} no longer +exists as its functionality has been merged into the autoconfiguration +process. @xref{Options to Configure}. + + +This file is found in @file{include/krb5/stock/osconf.h}. + +@table @code + +@item DEFAULT_PROFILE_PATH + +The pathname to the file which contains the profiles for the known +realms, their KDCs, etc. + +It is no longer the same format as Kerberos V4's @file{krb.conf} file. + +@item DEFAULT_LNAME_FILENAME + +The pathname to the database that maps authentication names to local +account names. See kdb5_anadd(8). + +@item DEFAULT_KEYTAB_NAME + +The type and pathname to the default server keytab file (the equivalent +of Kerberos V4's @file{/etc/srvtab}). + +@item DEFAULT_KDC_ENCTYPE + +The default encryption type for the KDC. + +@item KDCRCACHE + +The name of the replay cache used by the KDC. + +@item RCTMPDIR + +The directory which stores replay caches. + +@item DEFAULT_KDB_FILE + +The location of the default database + +@end table + +@node Shared Library Support, OS Incompatibilities, osconf.h, Building Kerberos +@section Shared Library Support + +Shared library support is provided for a few operating systems. There +are restrictions as to which compiler to use when using shaed libraries. + +In all cases, executables linked with the shared libraries in this build +process will have built in the location of the libraries, therefore +obliterating the need for special LD_LIBRARY_PATH environment variables +which using the programs. + +Except where noted, multiple versions of the libraries may be installed +on the same system and continue to work. + +Supported platforms are: NetBSD 1.0A, AIX 3.2.5, Solaris 5.3, Alpha +OSF/1 V2.1. + +@c To enable shared libraries, XXXX + +One special note is that if the Kerberos V4 compatibility is compiled +in, you @b{must not} specify an alternate Kerberos V4 library from the +one in the tree or you will be missing references. + +@menu +* Shared Library Theory:: +* NetBSD Shared Library Support:: +* AIX 3.2.5 Shared Library Support:: +* Solaris 5.3 Shared Library Support:: +* Alpha OSF/1 Shared Library Support:: +@end menu + +@node Shared Library Theory, NetBSD Shared Library Support, Shared Library Support, Shared Library Support +@subsection Theory of How Shared Libraries are Used + +An explanation of how shared libraries are implemented on a given +platform is too broad a topic for this manual. Instead this will touch +on some of the issues that the Kerberos V5 tree uses to support version +numbering and alternate install locations. + +Normally when one builds a shared library and then links with it, the +name of the shared library is stored in the object +(i.e. libfoo.so). Most operating systems allows one to change name that +is referenced and we have done so, placing the version number into the +shared library (i.e. libfoo.so.0.1). At link time, one would reference +libfoo.so, but when one executes the program, the shared library loader +would then look for the shared library with the alternate name. Hence +multiple versions of shared libraries may be supported relatively +easily. @footnote{Under AIX 3.2.5 for the RS/6000 it is not possible to +append the version name of the shared library to use and only version is +allowed at a time.} + +All operating systems (that we have seen) provide a means for programs +to specify the location of shared libraries. On different operating +systems, this is either specified when creating the shared library, and +link time, or both.@footnote{Both is necessary sometimes as the shared +libraries are dependent on themselves} The build process will establish +paths to both the installed destination as well as the build tree, +although this may change in the future. + +@node NetBSD Shared Library Support, AIX 3.2.5 Shared Library Support, Shared Library Theory, Shared Library Support +@subsection NetBSD Shared Library Support + +Shared library support has been tested under NetBSD 1.0A using +GCC 2.4.5. Due to the vagaries of the loader in the operating system, +the library load path needs to be specified in building libraries and in +linking with them. Unless the library is placed in a standard location +to search for libraries, this may make it difficult for developers to +work with the shared libraries. + +@node AIX 3.2.5 Shared Library Support, Solaris 5.3 Shared Library Support, NetBSD Shared Library Support, Shared Library Support +@subsection AIX 3.2.5 Shared Library Support + +AIX 3.2.5 does not have a very good mechanism for dealing with version +numbering in the shared libraries. About all it can detect is if the +version number is different but we cannot currently specify +a shared library name which is version specific. This means that one +might have to have different install paths with different releases. + +@node Solaris 5.3 Shared Library Support, Alpha OSF/1 Shared Library Support, AIX 3.2.5 Shared Library Support, Shared Library Support +@subsection Solaris 5.3 Shared Library Support + +Shared library support only works when using the Sunsoft C compiler. We +are currently using version 3.0.1. + +The path to the shared library must be specified at link time as well as +when creating libraries. + +@node Alpha OSF/1 Shared Library Support, , Solaris 5.3 Shared Library Support, Shared Library Support +@subsection Alpha OSF/1 Shared Library Support + +Shared library support has been tested with V2.1 of the operating +system. Shared libraries may be compiled both with GCC and the native +compiler. + +One of the nice features on this platform is that the paths to the +shared libraries is specified in the library itself without requiring +that one specify the same at link time. + +@node OS Incompatibilities, Using Autoconf, Shared Library Support, Building Kerberos @section Operating System Incompatibilities This section details operating system incompatibilties with Kerberos V5 @@ -695,6 +851,7 @@ send a report to @b{krb5-bugs@@mit.edu}. Thanks! * BSDI:: * Solaris versions 2.0 through 2.3:: * Solaris 2.X:: +* SGI Irix 5.X:: @end menu @node Ultrix 4.2/3, Alpha OSF/1 V1.3, OS Incompatibilities, OS Incompatibilities @@ -738,6 +895,10 @@ remarkable.) Using GCC version 2.6.3 as the compiler will also work fine, both with or without optimization. +Note that we have changed the @file{md4.c} to fix the problem. There is +no problem under OSF/1 V2.1, but we no longer have access to earlier +versions of the operating system to see if they are affected. + @node BSDI, Solaris versions 2.0 through 2.3, Alpha OSF/1 V2.0, OS Incompatibilities @subsection BSDI @@ -781,7 +942,7 @@ name first. Example: @end enumerate -@node Solaris 2.X, , Solaris versions 2.0 through 2.3, OS Incompatibilities +@node Solaris 2.X, SGI Irix 5.X, Solaris versions 2.0 through 2.3, OS Incompatibilities @subsection Solaris 2.X You @b{must} compile Kerberos V5 without the UCB compatibility @@ -790,64 +951,23 @@ LD_LIBRARY_PATH environment variable when you compile it. Alternatively you can use the @code{-i} option to @samp{cc}, by using the specifiying @code{--with-ccopts=-i} option to @samp{configure}. -@node Configuration .h files, Using Autoconf, OS Incompatibilities, Building Kerberos -@section Configuration Header Files - -There is one configuration file which you may wish to edit to control -various compile-time parameters in the Kerberos distribution: -@file{osconf.h}. - -Please note: The former configuration file @file{config.h} no longer -exists as its functionality has been merged into the autoconfiguration -process. @xref{Options to Configure} - -@menu -* osconf.h:: -@end menu - -@node osconf.h, , Configuration .h files, Configuration .h files -@subsection @file{osconf.h} - -This file is found in @file{include/krb5/stock/osconf.h}. - -@table @code - -@item DEFAULT_PROFILE_PATH - -The pathname to the file which contains the profiles for the known -realms, their KDCs, etc. - -It is no longer the same format as Kerberos V4's @file{krb.conf} file. - -@item DEFAULT_LNAME_FILENAME - -The pathname to the database that maps authentication names to local -account names. See kdb5_anadd(8). - -@item DEFAULT_KEYTAB_NAME - -The type and pathname to the default server keytab file (the equivalent -of Kerberos V4's @file{/etc/srvtab}). +@node SGI Irix 5.X, , Solaris 2.X, OS Incompatibilities +@subsection SGI Irix 5.X -@item DEFAULT_KDC_ENCTYPE - -The default encryption type for the KDC. - -@item KDCRCACHE - -The name of the replay cache used by the KDC. +If you are building in a tree separate from the source tree, the vendors +version of make does not work properly with regards to +@samp{VPATH}. @xref{Building with Separate Build Directories}. -@item RCTMPDIR - -The directory which stores replay caches. +Under 5.2, there is a bug in the optional System V @code{-lsocket} +library in which the routine @code{gethostbyname()} is broken. The +system supplied version in @code{-lc} appears to work though so one may +simply specify @code{--with-netlib} option to @samp{configure}. -@item DEFAULT_KDB_FILE +In 5.3, @code{gethostbyname} is no longer present in @code{-lsocket} and +is no longer an issue. -The location of the default database - -@end table -@node Using Autoconf, , Configuration .h files, Building Kerberos +@node Using Autoconf, , OS Incompatibilities, Building Kerberos @section Using @samp{Autoconf} (If you are not a developer, you can skip this section.) @@ -856,7 +976,7 @@ In most of the Kerberos V5 source directories, there is a @file{configure} script which automatically determines the compilation environment and creates the proper Makefiles for a particular platform. These @file{configure} files are generated using @samp{autoconf} version -2.1, which can be found in the @file{src/util/autoconf} directory in the +2.4, which can be found in the @file{src/util/autoconf} directory in the distribution. Normal users will not need to worry about running @samp{autoconf}; the @@ -872,10 +992,11 @@ properly set up @samp{autoconf}. One tool which is provided for the convenience of developers can be found in @file{src/util/reconf}. This program should be run while the -current directory is the source directory. It will automatically rebuild any -@file{configure} files which need rebuilding. If you know that you have -made a change that will require that all the @file{configure} files need to -be rebuilt from scratch, specify the @code{--force} option: +current directory is the top source directory. It will automatically +rebuild any @file{configure} files which need rebuilding. If you know +that you have made a change that will require that all the +@file{configure} files need to be rebuilt from scratch, specify the +@code{--force} option: @example % cd /u1/krb5/src @@ -982,12 +1103,12 @@ your Kerberos realm should be @code{CYGNUS.COM}. @menu -* krb5.conf:: -* Converting V4 configuration files:: +* krb5.conf:: +* Converting V4 configuration files:: * /etc/services:: @end menu -@node krb5.conf, Converting V4 configuration files, Configuration files, Configuration files +@node krb5.conf, Converting V4 configuration files, Configuration files, Configuration files @subsubsection The @file{krb5.conf} File The @file{krb5.conf} file contains information needed by the Kerberos V5 -- 2.26.2