This is Info file install.info, produced by Makeinfo-1.55 from the input file install.texi. This file documents how to build and install the Kerberos V5 distribution. Copyright (C) 1995, 1996 Massachusetts Institute of Technology. All Rights Reserved. Export of this software from the United States of America may require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain any necessary licenses before exporting. WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. Athena(r), Hesiod(r), Moira(r), and Discuss(r) are registered trademarks of the Massachusetts Institute of Technology (MIT). Project Athena, Athena Dashboard, Athena MUSE, Kerberos, X Window System, and Zephyr are trademarks of MIT. No commercial use of these trademarks may be made without prior written permission of MIT. All other product names are trademarks of their respective companies.  File: install.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) This file documents how to build and install the Kerberos V5 distribution. This is edition BETA 6, for Kerberos V5 version BETA 6. * Menu: * Introduction:: * How Kerberos Works:: * Building Kerberos:: * Installation:: * Troubleshooting:: -- The Detailed Node Listing -- How Kerberos Works: A Schematic Description * Network Services:: * Kerberos Tickets:: * The Kerberos Database:: * Kerberos Realms:: * The Ticket-Granting Ticket:: * Network Services and the Master Database:: * The User-Kerberos Interaction:: Network Services and the Master Database * The Keytab File:: Building Kerberos * Build Requirements:: How much disk space, etc. you need to build Kerberos. * Unpacking the Sources:: Preparing the source tree. * 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. * Using Autoconf:: Modifying Kerberos V5's configuration scripts. Doing the Build * Building Within a Single Tree:: * Building with Separate Build Directories:: * Building using lndir:: Testing the Build * The DejaGnu Tests:: Shared Library Support * Shared Library Theory:: * NetBSD Shared Library Support:: * AIX Shared Library Support:: * Solaris 5.3 Shared Library Support:: * Alpha OSF/1 Shared Library Support:: Operating System Incompatibilities * Ultrix 4.2/3:: * Alpha OSF/1 V1.3:: * Alpha OSF/1 V2.0++:: * BSDI:: * Solaris versions 2.0 through 2.3:: * Solaris 2.X:: * SGI Irix 5.X:: Installation * Background:: * Installation on any Machine:: * Installing the KDC:: * Migrating from V4 to V5 Kerberos:: * A Sample Application:: * Installing Kerberos Applications:: * Common Kerberos Service Names:: Installation on any Machine * Picking a Realm Name:: * Configuration files:: * Required Programs:: Configuration files * krb5.conf:: * Converting V4 configuration files:: * /etc/services:: Installing the KDC * kdc.conf:: * Initializing the KDB:: * Storing the Master Password:: * Adding Users to the Database:: * Starting the Kerberos Server:: * Setting up Slave Kerberos Servers:: * Inter-realm Kerberos Operation:: * The Administration Server:: * Testing the Kerberos Server:: Setting up Slave Kerberos Servers * Kerberos Slave Database Propagation:: * Installing a Slave Server:: A Sample Application * Installing the Sample Application:: * Testing the Sample Server:: Installing Kerberos Applications * Levels of Security:: * Preparing a Workstation for Kerberos Application Servers:: * BSD Utilities:: * Telnet and FTP:: BSD Utilities * Checksums:: Checksum facility for dealing with active attacks. * BSD Utility Configuration Example:: Sample `inetd.conf' entries for BSD utilities.  File: install.info, Node: Introduction, Next: How Kerberos Works, Prev: Top, Up: Top Introduction ************ This document describes the procedures necessary to compile Kerberos V5 from the source distribution, and then to install it at a particular site. The reader is assumed to be familiar with C/UNIX development tools. In any complex software, there will be bugs. In addition, you may find portability problems when you try to build Kerberos V5 on a platform on which the developers have not used. Please send bug reports or other problems you may uncover to the e-mail address krb5-bugs@mit.edu. Please mention which version of the Kerberos V5 distribution you are using, and whether you have made any private changes. Bug reports that include proposed fixes are especially welcome. If you do include fixes, please send them using either context diffs or unified diffs (using `diff -c' or `diff -u', respectively). Please note that there are still a number of aspects of Kerberos V5 which will likely change before the 1.0 release. As these changes occur, we will update the documentation accordingly.  File: install.info, Node: How Kerberos Works, Next: Building Kerberos, Prev: Introduction, Up: Top How Kerberos Works: A Schematic Description ******************************************* This section provides a simplified description of a general user's interaction with the Kerberos system. This interaction happens transparently-users don't need to know and probably don't care about what's going on-but Kerberos administrators might find a schematic description of the process useful. This description glosses over a lot of details; for more information, see Kerberos: An Authentication Service for Open Network Systems, a paper presented at Winter USENIX 1988, in Dallas, Texas. * Menu: * Network Services:: * Kerberos Tickets:: * The Kerberos Database:: * Kerberos Realms:: * The Ticket-Granting Ticket:: * Network Services and the Master Database:: * The User-Kerberos Interaction::  File: install.info, Node: Network Services, Next: Kerberos Tickets, Prev: How Kerberos Works, Up: How Kerberos Works Network Services and Their Client Programs ========================================== In an environment that provides network services, you use "client" programs to request service from "server" programs that are somewhere on the network. Suppose you have logged in to a workstation and you want to `rlogin' to another machine. You use the local `rlogin' client program to contact the remote machine's `rlogind' daemon.  File: install.info, Node: Kerberos Tickets, Next: The Kerberos Database, Prev: Network Services, Up: How Kerberos Works Kerberos Tickets ================ Under Kerberos, the `rlogind' daemon allows you to login to a remote machine if you can provide `rlogind' a Kerberos ticket which proves your identity. In addition to the ticket, you must also have possession of the corresponding ticket session key. The combination of a ticket and the ticket's session key is known as a credential. Typically, a client program automatically obtains credentials identifying the person using the client program. The credentials are obtained from a Kerberos server that resides somewhere on the network. A Kerberos server maintains a database of user, server, and password information.  File: install.info, Node: The Kerberos Database, Next: Kerberos Realms, Prev: Kerberos Tickets, Up: How Kerberos Works The Kerberos Database ===================== Kerberos will give you credentials only if you have an entry in the Kerberos server's "Kerberos database". Your database entry includes your Kerberos "principal" (which is often just your username), and your Kerberos password. Every Kerberos user must have an entry in this database.  File: install.info, Node: Kerberos Realms, Next: The Ticket-Granting Ticket, Prev: The Kerberos Database, Up: How Kerberos Works Kerberos Realms =============== Each site (or administrative domain within a site) will have their own Kerberos database, which contains information about the users and services for that particular site or administrative domain. A "Kerberos Realm" is used to distinguish the users and services in one particular area of administrative control from another area of administrative control. Each Kerberos realm will have at least one Kerberos server, where the master Kerberos database for that site or administrative domain is stored. A Kerberos realm may also have one or more "slave servers", which have read-only copies of the Kerberos database which are periodically propagated from the master server. For more details on how this is done, see *Note Setting up Slave Kerberos Servers::.  File: install.info, Node: The Ticket-Granting Ticket, Next: Network Services and the Master Database, Prev: Kerberos Realms, Up: How Kerberos Works The Ticket-Granting Ticket ========================== The `kinit' command prompts for your password, and if you enter it successfully, you will obtain a "ticket-granting ticket" and a "ticket session key" which gives you the right to use the ticket. This combination of the ticket and its associated key is also known as your "credentials". As illustrated below, client programs use your ticket-granting ticket credentials in order to obtain client-specific credentials as needed. Your credentials are stored in a "credentials cache", which is often simply just a file in `/tmp'. The credentials cache is also referred to as the "ticket file", especially in Kerberos V4 documentation. It should be noted, however, that a credentials cache does not have to be stored in a file.  File: install.info, Node: Network Services and the Master Database, Next: The User-Kerberos Interaction, Prev: The Ticket-Granting Ticket, Up: How Kerberos Works Network Services and the Master Database ======================================== The master database also contains entries for all network services that require Kerberos authentication. Suppose that your site has a machine, `laughter.mit.edu', that requires Kerberos authentication from anyone who wants to `rlogin' to it. The host's Kerberos realm is `ATHENA.MIT.EDU'. This service must be registered in the Kerberos database, using the proper service name, which in this case is `host/laughter.mit.edu@ATHENA.MIT.EDU'. The `/' character separates the various "components" of the Kerberos principal; the `@' character separates the realm name from the rest of the principal name. The first component, `host', denotes the name or type of the service that is being offered: generic host-level access to the machine. The second component, `laughter.mit.edu', names the specific machine which is offering this service. There will generally be many different machines, each offering one particular type of service, and the second component serves to give each one of these servers a different Kerberos name. * Menu: * The Keytab File::  File: install.info, Node: The Keytab File, Prev: Network Services and the Master Database, Up: Network Services and the Master Database The Keytab File --------------- For each service, there must also be a "service key" known only by Kerberos and the service. On the Kerberos server, the service key is stored in the Kerberos database. On the server host, these service keys are stored in the "Key tables", or "keytab files". (Keytab files were previously referred to as "srvtab files" in the V4 literature.) The service keys that are used by services which run as root are often stored in the file `/etc/v5srvtab'. WARNING: This service key is the equivalent of the service's password, and must be kept secure. Data which is meant to be read only by the service is encrypted using this key.  File: install.info, Node: The User-Kerberos Interaction, Prev: Network Services and the Master Database, Up: How Kerberos Works The User-Kerberos Interaction ============================= Suppose that you (in the guise of a general user) walk up to a workstation intending to login to it, and then `rlogin' to the machine `laughter'. Here's what happens: 1. You login to the workstation and use the `kinit' command to get a ticket-granting ticket. This command prompts you for your Kerberos password. (On some systems which have a modified `/bin/login' program, this may be done as part of the login process, not requiring the user to run a separate program.) A. The `kinit' command sends your request to the Kerberos master server machine. The server software looks for your principal name's entry in the Kerberos database. B. If this entry exists, the Kerberos server creates and returns a ticket-granting ticket and the key which allows you to use it, encrypted by your password. If `kinit' can decrypt the Kerberos reply using the password you provide, it stores this ticket in a credentials cache on your local machine for later use. The name of the credentials cache can be specified in the `KRB5_CCNAME' environment variable. If this variable is not set, the name of the file will be `/tmp/krb5cc_', where is your UNIX user-id, represented in decimal format. 2. Now you use the `rlogin' client to access the machine `laughter'. host% rlogin laughter A. The `rlogin' client checks your ticket file to see if you have a ticket for the `host' service for `laughter'. You don't, so `rlogin' uses the credential cache's ticket-granting ticket to make a request to the master server's ticket-granting service. B. This ticket-granting service receives the `host/laughter.mit.edu' request and looks in the master database for an `host/laughter.mit.edu' entry. If the entry exists, the ticket-granting service issues you a ticket for that service. That ticket is also cached in your credentials cache. C. The `rlogin' client now sends that ticket to the `laughter' `rlogind' service program. The service program checks the ticket by using its own service key. If the ticket is valid, it now knows your identity. If the ticket is valid and you are allowed to login to `laughter' (because the your name matches one in /etc/passwd, or you are in the appropriate `.klogin' or `.k5login' file), will let you login.  File: install.info, Node: Building Kerberos, Next: Installation, Prev: How Kerberos Works, Up: Top Building Kerberos ***************** Starting with the Beta 4 distribution, we are using a new configuration system, which was built using the Free Software Foundation's `autoconf' program. This system will hopefully make Kerberos V5 much simpler to build and reduce the amount of effort required in porting Kerberos V5 to a new platform. * Menu: * Build Requirements:: How much disk space, etc. you need to build Kerberos. * Unpacking the Sources:: Preparing the source tree. * 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. * Using Autoconf:: Modifying Kerberos V5's configuration scripts.  File: install.info, Node: Build Requirements, Next: Unpacking the Sources, Prev: Building Kerberos, Up: Building Kerberos 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. 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.  File: install.info, Node: Unpacking the Sources, Next: Doing the Build, Prev: Build Requirements, Up: Building Kerberos Unpacking the Sources ===================== The first step in each of these build procedures is to unpack the source distribution. The Kerberos V5 distribution comes in two compressed tar files. The first file, which is generally named `krb5.src.tar.gz', contains the sources for all of Kerberos except for the crypto library, which is found in the file `krb5.crypto.tar.gz'. Both files should be unpacked in the same directory, such as `/u1/krb5'. (In the rest of this document, we will assume that you have chosen to unpack the Kerberos V5 source distribution in this directory.)  File: install.info, Node: Doing the Build, Next: Testing the Build, Prev: Unpacking the Sources, Up: Building Kerberos Doing the Build =============== You have a number of different options in how to build Kerberos. 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 see *Note OS Incompatibilities:: for notes that we have on particular operating systems. * Menu: * Building Within a Single Tree:: * Building with Separate Build Directories:: * Building using lndir::  File: install.info, Node: Building Within a Single Tree, Next: Building with Separate Build Directories, Prev: Doing the Build, Up: Doing the Build Building Within a Single Tree ----------------------------- If you don't want separate build trees for each architecture, then use the following abbreviated procedure. 1. `cd /u1/krb5/src' 2. `./configure' 3. `make' That's it!  File: install.info, Node: Building with Separate Build Directories, Next: Building using lndir, Prev: Building Within a Single Tree, Up: Doing the 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 gmake 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/pmax' 2. `cd /u1/krb5/pmax' 3. `../src/configure' 4. `make'  File: install.info, Node: Building using lndir, Prev: Building with Separate Build Directories, Up: Doing the Build Building Using `lndir' ---------------------- If you wish to keep separate build directories for each platform, and you do cannot use 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/solaris' 2. `cd /u1/krb5/solaris' 3. `/u1/krb5/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.  File: install.info, Node: Testing the Build, Next: Options to Configure, Prev: Doing the Build, Up: Building Kerberos 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 typed `make' to start building Kerberos; see *Note Doing the Build::.): % make check * Menu: * The DejaGnu Tests::  File: install.info, Node: The DejaGnu Tests, Prev: Testing the Build, Up: Testing the Build The DejaGnu Tests ----------------- Some of the built-in regression tests are setup to use the DejaGnu framework for running tests. These tests tend to be more comprehensive than the normal built-in tests as they setup test servers and test client/server activities. DejaGnu may be found wherever GNU software is archived. Most of the tests are setup to run as a non-privledged user. There are two series of tests (`rlogind' and `telnetd') which require the ability to `rlogin' as root to the local machine. Admittedly, this does require the use of a `.rhosts' file or some other authenticated means. (1) If you cannot obtain root access to your machine, all the other tests will still run. Note however, with DejaGnu 1.2, the "untested testcases" will cause the testsuite to exit with a non-zero exit status which `make' will consider a failure of the testing process. Do not worry about this, as these tests are the last run when `make check' is executed from the top level of the build tree. ---------- Footnotes ---------- (1) If you are fortunate enough to have a previous version of Kerberos V5 or V4 installed, and the Kerberos rlogin is first in your path, you can setup `.k5login' or `.klogin' as appropriate to allow you access.  File: install.info, Node: Options to Configure, Next: osconf.h, Prev: Testing the Build, Up: Building Kerberos Options to Configure ==================== There are a number of options to `configure' which you can use to control how the Kerberos distribution is built. The following table lists the most commonly used options to Kerberos V5's `configure' program. `--prefix=DIR' 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=DIR' This option allows one to separate the architecture independent programs from the configuration files and manual pages. `--with-cc=COMPILER' Use `COMPILER' as the C compiler. `--with-ccopts=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'. `--with-cppopts=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. `--with-linker=LINKER' Use `LINKER' as the default loader if it should be different from C compiler as specified above. `--with-ldopts=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. 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 *Note Solaris versions 2.0 through 2.3::) or fails to pass the tests in `src/tests/resolv' you will need to use this option. `--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-athena' Was used to setup configuration files in such a way as to be compatible with the Athena environment at MIT. It currently does not appear to do anything useful. `--with-vague-errors' If enabled, gives vague and unhelpful error messages to the client... er, attacker. (Needed to meet silly government regulations; most other sites will want to keep this undefined.) `--with-kdc-kdb-update' Set this option if you want to allow the KDC to modify the Kerberos database; this allows the last request information to be updated, as well as the failure count information. Note that this doesn't work if you're using slave servers!!! It also causes the database to be modified (and thus needing to be locked) frequently. For example, in order to configure Kerberos on a Solaris machine using the `suncc' with the optimizer turned on, run the configure script with the following options: % configure --with-cc=suncc --with-ccopts=-O  File: install.info, Node: osconf.h, Next: Shared Library Support, Prev: Options to Configure, Up: Building Kerberos `osconf.h' ========== There is one configuration file which you may wish to edit to control various compile-time parameters in the Kerberos distribution: `include/krb5/stock/osconf.h'. The list that follows is by no means complete, just some of the more interesting variables. Please note: The former configuration file `config.h' no longer exists as its functionality has been merged into the auto-configuration process. *Note Options to Configure::. `DEFAULT_PROFILE_PATH' The pathname to the file which contains the profiles for the known realms, their KDCs, etc. The profile file format is no longer the same format as Kerberos V4's `krb.conf' file. `DEFAULT_LNAME_FILENAME' The pathname to the database that maps authentication names to local account names. See kdb5_anadd(8). `DEFAULT_KEYTAB_NAME' The type and pathname to the default server keytab file (the equivalent of Kerberos V4's `/etc/srvtab'). `DEFAULT_KDC_ENCTYPE' The default encryption type for the KDC. `KDCRCACHE' The name of the replay cache used by the KDC. `RCTMPDIR' The directory which stores replay caches. `DEFAULT_KDB_FILE' The location of the default database  File: install.info, Node: Shared Library Support, Next: OS Incompatibilities, Prev: osconf.h, Up: Building Kerberos Shared Library Support ====================== Shared library support is provided for a few operating systems. There are restrictions as to which compiler to use when using shared 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 when using the programs. Except where noted, multiple versions of the libraries may be installed on the same system and continue to work. Currently the supported platforms are: NetBSD 1.0A, AIX 3.2.5, AIX 4.1, Solaris 5.3, Alpha OSF/1 >= 2.1, HP-UX >= 9.X. To enable shared libraries on the above platforms, run the configure script with the option `--enable-shared'. One special note is that if the Kerberos V4 compatibility is compiled in, you 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 Shared Library Support:: * Solaris 5.3 Shared Library Support:: * Alpha OSF/1 Shared Library Support::  File: install.info, Node: Shared Library Theory, Next: NetBSD Shared Library Support, Prev: Shared Library Support, Up: Shared Library Support 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. (1) 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.(2) The build process will hardwire a path to the installed destination. ---------- Footnotes ---------- (1) Under AIX for the RISC/6000, multiple versions of shared libraries are supported by combining two or more versions of the shared library into one file. The Kerberos build procedure produces shared libraries with version numbers in the internal module names, so that the shared libraries are compatible with this scheme. Unfortunately, combining two shared libraries requires internal knowledge of the AIX shared library system beyond the scope of this document. Practicallyspeaking, only one version of AIX shared libraries can be supported on a system, unless the multi-version library is constructed by a programmer familiar with the AIX internals. (2) Both are necessary sometimes as the shared libraries are dependent on other shared libraries  File: install.info, Node: NetBSD Shared Library Support, Next: AIX Shared Library Support, Prev: Shared Library Theory, Up: Shared Library Support 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.  File: install.info, Node: AIX Shared Library Support, Next: Solaris 5.3 Shared Library Support, Prev: NetBSD Shared Library Support, Up: Shared Library Support AIX Shared Library Support --------------------------- AIX specifies shared library versions by combining multiple versions into a single file. Because of the complexity of this process, no automatic procedure for building multi-versioned shared libraries is provided.Therefore, supporting multiple versions of the Kerberos shared libraries under AIX will require significant work on the part of a programmer famiiliar with AIX internals. AIX allows a single library to be used both as a static library and as a shared library. For this reason, the `--enable-shared' switch to configure builds only shared libraries. On other operating systems, both shared and static libraries are built when this switch is specified. As with all other operating systems, only non-shared static libraries are built when `--enable-shared' is not specified. The AIX 3.2.5 linker dumps core trying to build a shared `libkrb5.a' produced with the GNU C compiler. The native AIX compiler works fine. In addition, the AIX 4.1 linker is able to build a shared `libkrb5.a' when GNU C is used.  File: install.info, Node: Solaris 5.3 Shared Library Support, Next: Alpha OSF/1 Shared Library Support, Prev: AIX Shared Library Support, Up: Shared Library Support 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.  File: install.info, Node: Alpha OSF/1 Shared Library Support, Prev: Solaris 5.3 Shared Library Support, Up: Shared Library Support Alpha OSF/1 Shared Library Support ---------------------------------- Shared library support has been tested with V2.1 and higher 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. We are using the `-rpath' option to `ld' to place the library load path into the executables. The one disadvantage of this is during testing where we want to make sure that we are using the build tree instead of a possibly installed library. The loader uses the contents of `-rpath' before LD_LIBRARY_PATH so we must specify a dummy _RLD_ROOT and complete LD_LIBRARY_PATH in our tests. The one disadvantage with the method we are using  File: install.info, Node: OS Incompatibilities, Next: Using Autoconf, Prev: Shared Library Support, Up: Building Kerberos Operating System Incompatibilities ================================== This section details operating system incompatibilities with Kerberos V5 which have been reported to the developers at MIT. If you find additional incompatibilities, and/or discover work arounds to such problems, please send a report to krb5-bugs@mit.edu. Thanks! * Menu: * Ultrix 4.2/3:: * Alpha OSF/1 V1.3:: * Alpha OSF/1 V2.0++:: * BSDI:: * Solaris versions 2.0 through 2.3:: * Solaris 2.X:: * SGI Irix 5.X::  File: install.info, Node: Ultrix 4.2/3, Next: Alpha OSF/1 V1.3, Prev: OS Incompatibilities, Up: OS Incompatibilities Ultrix 4.2/3 ------------ On the MIPS platform, using the native compiler, `md4.c' and `md5.c' can not be compiled with the optimizer set at level 1. That is, you must specify either `--with-ccopts=-O' and `--with-ccopts=-g' to configure. If you don't specify either, the compile will never complete. The optimizer isn't hung; it just takes an exponentially long time. Compiling 6 out of the 48 algorithmic steps takes 3 seconds; compiling 7 steps takes 9 seconds; compiling 8 steps takes 27 seconds, and so on. Calculations estimate it will finish in approximately 3,469 billion years.... Using GCC version 2.5 instead of the native compiler will also work fine, both with or without optimization.  File: install.info, Node: Alpha OSF/1 V1.3, Next: Alpha OSF/1 V2.0++, Prev: Ultrix 4.2/3, Up: OS Incompatibilities Alpha OSF/1 V1.3 ---------------- There is a bug in OSF/1's fgrep which causes the `configure' script to fail. Using the native compiler, compiling with the `-O' compiler flag causes the `asn.1' library to be compiled incorrectly. Using GCC version 2.6.3 instead of the native compiler will also work fine, both with or without optimization.  File: install.info, Node: Alpha OSF/1 V2.0++, Next: BSDI, Prev: Alpha OSF/1 V1.3, Up: OS Incompatibilities Alpha OSF/1 V2.0++ ------------------ There formerly used to be a bug when using the native compiler in compiling `md4.c' when compiled without either the `-O' or `-g' compiler options. (This could possibly be the same sort of bug as found in *Note Ultrix 4.2/3::, but that seems rather remarkable.) We have changed the code and there is no problem under V2.1, but we do not have access to V2.0 to test and see if the problem would exist there. (We welcome feedback on this issue). There was never a problem in using GCC version 2.6.3. In version 3.2 and beyond of the operating system, we have not seen any problems with the native compiler.  File: install.info, Node: BSDI, Next: Solaris versions 2.0 through 2.3, Prev: Alpha OSF/1 V2.0++, Up: OS Incompatibilities BSDI ---- BSDI versions 1.0 and 1.1 reportedly has a bad `sed' which causes it to go into an infinite loop during the build. The work around is to use a `sed' from somewhere else, such as GNU. (This may be true for some versions of other systems derived from BSD 4.4, such as NetBSD and FreeBSD.)  File: install.info, Node: Solaris versions 2.0 through 2.3, Next: Solaris 2.X, Prev: BSDI, Up: OS Incompatibilities Solaris versions 2.0 through 2.3 -------------------------------- The `gethostbyname()' routine is broken; it does not return a fully qualified domain name, even if you are using the Domain Name Service routines. Since Kerberos V5 uses the fully qualified domain name as the second component of a service principal (i.e, `host/tsx-11.mit.edu@ATHENA.MIT.EDU'), this causes problems for servers who try to figure out their own fully qualified domain name. Workarounds: 1. Supply your own resolver library. 2. Upgrade to Solaris 2.4 3. Make sure your /etc/nsswitch.conf has the line: hosts: files dns and then in /etc/hosts, make sure there is a line with your workstation's IP address and hostname, with the fully qualified domain name first. Example: 18.172.1.4 dcl.mit.edu dcl  File: install.info, Node: Solaris 2.X, Next: SGI Irix 5.X, Prev: Solaris versions 2.0 through 2.3, Up: OS Incompatibilities Solaris 2.X ----------- You must compile Kerberos V5 without the UCB compatibility libraries. This means that `/usr/ucblib' must not be in the LD_LIBRARY_PATH environment variable when you compile it. Alternatively you can use the `-i' option to `cc', by using the specifying `--with-ccopts=-i' option to `configure'.  File: install.info, Node: SGI Irix 5.X, Prev: Solaris 2.X, Up: OS Incompatibilities SGI Irix 5.X ------------ If you are building in a tree separate from the source tree, the vendors version of make does not work properly with regards to `VPATH'. It also has problems with standard inference rules in 5.2 (not tested yet in 5.3) so one needs to use GNU's make. Under 5.2, there is a bug in the optional System V `-lsocket' library in which the routine `gethostbyname()' is broken. The system supplied version in `-lc' appears to work though so one may simply specify `--with-netlib' option to `configure'. In 5.3, `gethostbyname()' is no longer present in `-lsocket' and is no longer an issue.  File: install.info, Node: Using Autoconf, Prev: OS Incompatibilities, Up: Building Kerberos 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' version 2.4, 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. Developers who wish to modify the `configure.in' files should see *Note Overview: (autoconf)Top. 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/src % ./util/reconf --force The developmental sources are a raw source tree (before it's been packaged for public release), without the pre-built `configure' files. In order to build from such a source tree, you must do: % cd krb5/util/autoconf % ./configure % make % cd ../.. % util/reconf Then follow the instructions for building packaged source trees (above). To install the binaries into a binary tree, do: % cd /u1/krb5/src % make all % make install DESTDIR=somewhere-else  File: install.info, Node: Installation, Next: Troubleshooting, Prev: Building Kerberos, Up: Top Installation ************ When you are installing Kerberos for the first time at a site, you must first decide on the realm name you will use for your site, and select a machine to host the "Kerberos server", which is also known as the "KDC" ("Key Distribution Center"). The KDC must be located on a secure machine, since its database contains the keys for the entire realm. It is extremely important that the database be kept secure, if the realm's Kerberos service is to remain secure. Once a KDC is installed and configured, you may then set up one or more client machines, and one or more application machines. * Menu: * Background:: * Installation on any Machine:: * Installing the KDC:: * Migrating from V4 to V5 Kerberos:: * A Sample Application:: * Installing Kerberos Applications:: * Common Kerberos Service Names::  File: install.info, Node: Background, Next: Installation on any Machine, Prev: Installation, Up: Installation Background Information ====================== Your system's security is only as good as the security of your `root' password. You should take other precautions to protect your system security in addition to installing Kerberos. Kerberos cannot protect you from someone who is able to steal `root' privileges. Kerberos also does not protect you from break-ins caused by bugs in your daemons (e.g., `fingerd' or `sendmail'). On almost all UNIX systems, if intruders can break in as an ordinary users, they can obtain superuser privileges by exploiting bugs or imperfect configuration files.  File: install.info, Node: Installation on any Machine, Next: Installing the KDC, Prev: Background, Up: Installation Installation on any Machine =========================== The following steps must be performed no matter what type of machine (KDC, Client, or Application server) you are installing. All machines functioning within the same administrative domain must use the same Kerberos realm name; and all machines which are using Kerberos must have the Kerberos configuration files properly installed. If you are installing Kerberos on a machine that will act only as a Kerberos client, this section describes all that you need to do. If you are installing a KDC, or an Kerberos Application server, you will also need to complete the procedures detailed in *Note Installing the KDC::, or *Note A Sample Application::, after you finish with the procedures found in this section. * Menu: * Picking a Realm Name:: * Configuration files:: * Required Programs::  File: install.info, Node: Picking a Realm Name, Next: Configuration files, Prev: Installation on any Machine, Up: Installation on any Machine Picking a Realm Name -------------------- Before you install Kerberos V5 at your site, you have to choose a "realm name", the name that specifies the system's administrative domain. By convention, we suggest that you use your internet domain name, in capital letters. (Kerberos realm names are case-sensitive, so it's important that your realm name be in all upper case.) For example, if your internet domain is `cygnus.com' (so that you have hostnames such as `ftp.cygnus.com' and `tweedledum.cygnus.com'), then your Kerberos realm should be `CYGNUS.COM'.  File: install.info, Node: Configuration files, Next: Required Programs, Prev: Picking a Realm Name, Up: Installation on any Machine Configuration files ------------------- * Menu: * krb5.conf:: * Converting V4 configuration files:: * /etc/services::  File: install.info, Node: krb5.conf, Next: Converting V4 configuration files, Prev: Configuration files, Up: Configuration files The `krb5.conf' File .................... The `krb5.conf' file contains information needed by the Kerberos V5 library including a system's default Kerberos realm, and the locations of the Kerberos servers. The `krb5.conf' uses an INI-style format. Sections are delimited by square braces; within each section, there are relations where tags can be assigned to have specific values. Tags can also contain a subsection, which contains further relations or subsections. A tag can be assigned to multiple values. Create a `/etc/krb5.conf' file using the following format: [libdefaults] default_realm = [realms] = { kdc = admin_server = default_domain = } [domain_realm] <.domain.name> = Where `realm_name' specifies the default realm to be used by that particular system, and `master_server_name' specifies the machine name on which you will run the master server. The keywords `kdc' and `admin_server' lists the location of the realms KDC and administration servers. For example, if your realm name is `ATHENA.MIT.EDU' and your master server's name is `kerberos.mit.edu', the file should have these contents: [libdefaults] default_realm = ATHENA.MIT.EDU [realms] ATHENA.MIT.EDU = { kdc = KERBEROS.MIT.EDU admin_server = KERBEROS.MIT.EDU default_domain = MIT.EDU } [domain_realm] .mit.edu = ATHENA.MIT.EDU mit.edu = ATHENA.MIT.EDU In many situations, the default realm in which a host operates will be identical to its Internet domain name, with the first component removed and all letters capitalized. For example, `ftp.cygnus.com' is traditionally in the realm `CYGNUS.COM'. If this is not the case, you will need to establish a translation from host name or domain name to realm name. This is accomplished with the `[domain_realm]' stanza Each line of the translation file specifies either a host name or domain name, and its associated realm: [domain_realm] <.domain.name> = KERBEROS.REALM1 = KERBEROS.REALM2 For example, to map all hosts in the domain LSC.MIT.EDU to LCS.MIT.EDU but the host FILMS.LSC.MIT.EDU to MIT.EDU your file would read: [domain_realm] .LSC.MIT.EDU = LSC.MIT.EDU FILMS.LSC.MIT.EDU = MIT.EDU If a particular host name matches both a domain name and a host name in `[domain_realm]', the entry containing the host name takes precedence. See the `[SOURCE_DIR]/config-files/krb5.conf' file for an example `krb5.conf' file. That file has examples of how to provide backup servers for a given realm (additional lines with the same leading realm name) and how to designate servers for remote realms.  File: install.info, Node: Converting V4 configuration files, Next: /etc/services, Prev: krb5.conf, Up: Configuration files Conversion of V4 configuration files .................................... Kerberos V4's `krb.conf' and `krb.realms' files formats are no longer used by the V5 library. A Perl script has been provided to allow for "easy" generation of an initial `krb5.conf'. It is located in `[SOURCE_DIR]/config-files/convert-config-files'. The produced file should be checked for errors. Note that if you are planning on using certain applications with Kerberos V4 compatibility compiled in, the V4 library still needs the files `krb.conf' and `krb.realms'.  File: install.info, Node: /etc/services, Prev: Converting V4 configuration files, Up: Configuration files /etc/services ............. All hosts which will use Kerberos will need to have certain ports defined in the system's `/etc/services' file. The file `[SOURCEDIR]/config-files/services.append' contains the entries which should be appended to the `/etc/services' file. If you are using the Network Information Services (NIS) or Yellow Pages (YP), you will need to add the services in the `services.append' file to the services exported in the NIS or YP server.  File: install.info, Node: Required Programs, Prev: Configuration files, Up: Installation on any Machine Required Programs ----------------- The following files should be installed on all machines which are running Kerberos, either as a client, a KDC, or an application server: If you used the default `make install' without using the `--prefix' argument to `configure', then [K_USER] refers to `/usr/local/bin'. * `/etc/krb5.conf' -- This files contains information required by Kerberos V5 giving system defaults as well as locations of Kerberos servers. * `[K_USER]/kinit' -- This program allows you to obtain Kerberos credentials. * `[K_USER]/bin/kdestroy' -- This program allows you to destroy Kerberos credentials which are no longer needed. * `[K_USER]/klist' --- This program allows you to list the credentials found in your credentials cache.  File: install.info, Node: Installing the KDC, Next: Migrating from V4 to V5 Kerberos, Prev: Installation on any Machine, Up: Installation Installing the KDC ================== * Menu: * kdc.conf:: * Initializing the KDB:: * Storing the Master Password:: * Adding Users to the Database:: * Starting the Kerberos Server:: * Setting up Slave Kerberos Servers:: * Inter-realm Kerberos Operation:: * The Administration Server:: * Testing the Kerberos Server::