This file documents how to build and install the Kerberos V5 distribution.

Copyright (C) 1995 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.

This file documents how to build and install the Kerberos V5 distribution.

This is edition BETA 5, for Kerberos V5 version BETA 5.

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 yet built.  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.  In particular, the syntax and the names of the configuration files, krb.conf and krb.realms, are very likely to change in the near future. (Actually, they've changed already; this documentation hasn't been updated yet to reflect this yet, though.  See the krb5.conf man page for a description of the new configuration file format.)  In addition the location of the executable programs may also change as well.

As these changes occur, we will update the documentation accordingly.

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.

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.

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 identifiying 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.

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.

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 Setting up Slave Kerberos Servers.

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 know 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.

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.

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.

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_<uid>, where <uid> 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 file), will let you login.

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.

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 keep a 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.

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.)

Doing the Build
===============

You have a number of different options as 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.

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!

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

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.

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 Doing the Build.):

     % make check

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.

--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-krb5-root=DIR

     By default, Kerberos will expect its configuration files to be in the directory /krb5.  Change it with this option.

--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).

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

Operating System Incompatibilities
==================================

This section details operating system incompatibilties 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!

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.

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.

Alpha OSF/1 V2.0
----------------

Using the native compiler, md4.c must be compiled with either the -O or -g compiler options.  (This could possibly be the same sort of bug as found in Ultrix 4.2/3, but that seems rather remarkable.)

Using GCC version 2.6.3 as the compiler will also work fine, both with or without optimization.

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.)

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

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 specifiying --with-ccopts=-i option to configure.

Configuration Header Files
==========================

There are two configuration files which you may wish to edit to control various compile-time parameters in the Kerberos distribution: osconf.h and config.h.

osconf.h
--------

This file is found in include/krb5/stock/osconf.h.

DEFAULT_CONFIG_FILENAME

     The pathname to the file which defines the known realms and their KDCs. It currently uses the same format as Kerberos V4's krb.conf file.

DEFAULT_TRANS_FILENAME

     The pathname to the file which assigns hosts to realms.  It currently uses the same format as Kerberos V4's krb.realms.

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_ETYPE

     The default encryption type for the KDC.

DEFAULT_KDC_KEYTYPE

     The default keytype for the KDC.

KDCRCACHE

     The name of the replay cache used by the KDC.

RCTMPDIR

     The directory which stores replay caches.

config.h
--------

This file is located in include/krb5/stock/config.h.

KRBCONF_VAGUE_ERRORS

     If defined, 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.)

KRBCONF_KDC_MODIFIES_KDB

     Define this 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.

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.1, 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 Overview (The Autoconf Manual).

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 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 KRB5ROOT=somewhere-else

Currently this only works if somewhere-else is /krb5. (It's a bug.)

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.

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.

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 Installing the KDC, or A Sample Application, after you finish with the procedures found in this section.

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.

Configuration files
-------------------

WARNING: The krb.conf and krb.realms files are no longer used by this release; this documentation hasn't been updated yet to describe the new krb5.conf file, so please disregard the next two subsections.  Information about the contents of the krb5.conf file can be found in krb5.conf manual page, which is located in the source tree in the src/config-files subdirectory.

The krb.conf File
.................

The krb.conf file is used to specify a system's default Kerberos realm, and to specify the locations of the Kerberos servers.

Create a [KRB5ROOT]/krb.conf file using the following format:

     <realm_name>
     <realm_name>   <master_server_name> admin server

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 words admin server must appear next to the name of the server on which you intend to run the administration server (which must be a machine with access to the database).

For example, if your realm name is MIT.EDU and your master server's name is kerberos.mit.edu, the file should have these contents:

     MIT.EDU
     MIT.EDU  kerberos.mit.edu admin server

See the [SOURCE_DIR]/config-files/krb.conf file for an example krb.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.

The krb.realms File
...................

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 [KRB5ROOT]/krb.realms file.

Each line of the translation file specifies either a host name or domain name, and its associated realm:

     <.domain.name> KERBEROS.REALM1
     <host.name> 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:

     .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 krb.realms, the entry containing the host name takes precedence.

/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.

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:

  * /krb5/bin/kinit --- This program allows you to obtain Kerberos credentials.

  * /krb5/bin/kdestroy --- This program allows you to destroy Kerberos credentials which are no longer needed.

  * /krb5/bin/klist ---- This program allows you to list the credentials found in your credentials cache.

Installing the KDC
==================

Initializing the Kerberos Database
----------------------------------

Login to the Kerberos KDC, and use the su command to become root. If you installed the Kerberos administration tools with the make install command and the default pathnames, they should be in the /krb5/sbin directory. If you installed the tools in a different directory, hopefully you know what it is. From now on, we will refer to this directory as [ADMIN_DIR].

The kdb5_create command creates and initializes the master database. It asks you to the database's master password. Do not forget this password. If you do, the database becomes useless. (Your realm name should be substituted for [REALMNAME] below.)

Use kdb5_create as follows:

     # [ADMIN_DIR]/kdb5_create
     Initializing database '/krb5/principal' for realm '[REALMNAME],
     master key name 'K/M@[REALMNAME]
     You will be prompted for the database Master Password.
     It is important that you NOT FORGET this password.
     Enter KDC database master key:              <-- [Enter the master password.]
     Re-enter KDC database master key to verify: <-- [Re-enter it.]

Storing the Master Password
---------------------------

The kdb5_stash command "stashes" the master password in the file /.k.[REALM.NAME] so that the Kerberos server can be started automatically during an unattended reboot of the master server.  Other administrative programs use this hidden password so that they can access the master database without someone having to manually provide the master password.  This command is an optional one; if you'd rather enter the master password each time you start the Kerberos server, don't use kdb5_stash.

On the one hand, if you use kdb5_stash, a copy of the master key will reside on a disk, which may not be acceptable; on the other hand, if you don't use kdb5_stash, the server cannot be started unless someone is around to type the password manually.

The command merely prompts for the master password:

     # [ADMIN_DIR]/kdb5_stash
     Enter KDC database master key:    <-- [Enter the master password.]

WARNING: If your Kerberos database master key is compromised and the database is obtained, the security of your entire authentication system is compromised.  (If this happens you all of your user's passwords must be set to new values manually --- i.e., not using Kerberos.)  The master key must be a carefully kept secret.  If you keep backups, you must guard all the master keys you use, in case someone has stolen an old backup and wants to attack users' whose passwords haven't changed since the backup was stolen.  This is why we provide the option not to store it on disk.

Adding Users to the Database
----------------------------

The kdb5_edit program is used to add new users and services to the master database, and to modify existing database information.

For example, to add yourself to the newly created database: (replace your username with [USERNAME])

     # [ADMIN_DIR]/kdb5_edit
     kdb5_edit:  ank [USERNAME]
     Enter password:                        <-- [Enter your password.]
     Re-enter password for verification:    <-- [Re-enter it.]
     kdb5_edit: quit

The ank command is short for "add_new_key"; this command adds a new user to the database.  To see what other commands which kdb5_edit supports, type ? RET at the kdb5_edit prompt.

Starting the Kerberos Server
----------------------------

In order to start the Kerberos server, run it as a background process

     # /krb5/sbin/krb5kdc &

If you have used the kdb5_stash command to store the master database password, the server will start automatically. If you did not use kdb5_stash, use the following command:

     # /krb5/sbin/krb5kdc -m

The server will prompt you to enter the master password before actually starting itself.

Setting up Slave Kerberos Servers
---------------------------------

Slave Kerberos servers allow clients to be able to get Kerberos tickets even when the Master server is not available.  Users will not be able to change their passwords --- changes can only be made to database on the Master server; however, users will be able to authenticate to application servers, which is critically important in a distributed client-server environment.

Kerberos Slave Database Propagation
...................................

In order to propagate the Kerberos database from the Master server to the slaves, the kprop and kpropd client/server programs are used.  Periodically, the Master server will dump the Kerberos database out into an ASCII format, using the kdb5_edit program. The master server will then run kprop to prograte the dumped database file to each slave server.

On the slave server, the kpropd program is invoked out of /etc/inetd server.  After kprop and kpropd have mutually authenticated with one another, and kpropd is satisfied with the identity of the Master server, then the dumped ASCII database is transferred to the slave server in an encrypted fashion.  After the database is transfered, kpropd will then run kdb5_edit with the appropriate arguments in order to undump the database into a usable form by the KDC on the slave server.

Installing a Slave Server
.........................

To be written.

Inter-realm Kerberos Operation
------------------------------

To be written.

The Administration Server
-------------------------

There is currently an administration server in the Kerberos source tree. It is, however, very rough, and it will likely be significantly changed or replaced before the 1.0 release.  Hence, this manual does not document the current administration server.  Changes to the database can be made by logging in to the KDC directly, and using the kdb5_edit program; see Adding Users to the Database.

Testing the Kerberos Server
---------------------------

Use the kinit command to obtain Kerberos credentials.  This command creates your credentials cache and stores your credentials in it.

If you used the default make install command and directories to install the Kerberos user utilities, kinit will be in the /krb5/bin directory. From now on, we'll refer to the Kerberos user commands directory as [K_USER].

Use kinit as follows:

     # [K_USER]/kinit [USERNAME]
     Password for [USERNAME]@[REALMNAME]:        <-- enter your password

Use the klist program to list the contents of your ticket file.

     # [K_USER]/klist
     Ticket cache: /tmp/krb5cc_15806
     Default principal: [USERNAME]@[REALMNAME]

       Valid starting       Expires          Service principal
     31-Jan-95 21:58:32   1-Feb-95 05:57:39  krbtgt/[REALMMNAME]@[REALMNAME]

Migrating from V4 to V5 Kerberos
================================

To be written.

A Sample Application
====================

This release of Kerberos comes with a sample application server and a corresponding client program.  You will find this software in the [BUILD_DIR]/appl/sample/sserver and [BUILD_DIR]/appl/sample/sclient directories, which contain the server's executable, and the client program's executable, respectively.

The programs are rudimentary. When they have been installed (the installation procedure is described in detail later), they work as follows:

 1. The user starts sclient and provides as arguments to the command the name of the server machine and an optional port on which to contact the server.

 2. sclient contacts the server machine and authenticates the user to sserver.

 3. sserver authenticates itself to sclient (thus performing mutual authentication), and then returns a message to the client program. This message contains the name of the Kerberos principal that was used to authenticate to sserver.

 4. sclient displays the server's message on the user's terminal screen.

Installing the Sample Application
---------------------------------

In general, you use the following procedure to install a Kerberos-authenticated server-client system.

 1. Add the appropriate entry to the Kerberos database using kdb_edit

 2. Create a /etc/v5srvtab file for the server machine.

 3. Install the service program and the /etc/v5srvtab file on the server machine.

 4. Install the client program on the client machine.

 5. Update the /etc/services file on the client and server machines.

We will use the sample application as an example, although programs which do not take requests via the inetd program may have slightly different installation procedures.  Inetd starts sserver each time a client process contacts the server machine. sserver processes the request, terminiates, then is restarted when inetd receives another sserver request.  When you install the program on the server, you must add a sample entry to the server machine's /etc/inetd.conf file.

The following description assumes that you are installing sserver on the machine jimi.mit.edu. Here's the process, step by step:

 1. Login as root or su to root on the Kerberos server machine. Use the kdb5_edit program to create an entry for sample in the Kerberos database:

          # [ADMIN_DIR]/kdb5_edit
          kdb5_edit: add_random_key sample/jimi.mit.edu
          kdb5_edit: quit

     (Note: add_random_key may be abbreviated as ark.)

 2. Use kdb5_edit to create a srvtab file for sserver's host machine:

          # [ADMIN_DIR]/kdb5_edit
          kdb5_edit: extract_srvtab jimi.mit.edu sample
          'sample/jimi.mit.edu@ATHENA.MIT.EDU' added to keytab 'WRFILE:jimi.mit.edu-new-srvtab'
          kdb5_edit: quit

     (Note: extract_srvtab may be appreviated as xst.)

     Transfer the jimi.mit.edu-new-srvtab file to jimi.mit.edu and install it as /etc/v5srvtab.

     WARNING: Note that this file is equivalent to the service's password and should be treated with care.  For example, it could be transferred by removable media, but should not be sent over an open network in the clear.  This file should installed such that only the root user can read it.

 3. Add the following line to the /etc/services file on jimi.mit.edu, and on all machines that will run the sample_client program:

          sample     906/tcp       # Kerberos sample app server

 4. Add a line similar to the following line to the /etc/inetd.conf file on sample_server's machine:

          sample   stream   tcp   nowait   switched   root
              [PATH]/sserver sample_server

     where [PATH] should be substituted with the path to the sserver program. (This inetd.conf information should be placed on one line.) You should examine existing lines in /etc/inetd.conf and use the same format used by other entries (e.g. for telnet).  Most systems do not have a column for the `switched' keyword, and some do not have a column for the username (usually `root', as above).

 5. Restart inetd by sending the current inetd process a hangup signal:

          # kill -HUP process_id_number

 6. The sserver is now ready to take sclient requests.

Testing the Sample Server
-------------------------

Assume that you have installed sserver on jimi.mit.edu.

Login to your workstation and use the kinit command to obtain a Kerberos ticket-granting ticket:

     % [K_USER]/kinit [USERNAME]
     Password for [USERNAME]@[REALMNAME]:            <--- Enter your password

Now use the sclient program as follows:

     % [PATH]/sclient jimi

The command should display something like the following:

     sendauth succeeded, reply is:
     reply len 29, contents:
     You are [USERNAME]@[REALMNAME]

Common Kerberos Service Names
=============================

The following service names are used by Kerberos client/server applications.

host
     Used by telnet, rlogin, rsh, rcp, and other services which generally give login access to the host.

pop
     Used by the Post Office Protocol.

sample
     Used by the Kerberos sample applications.

These service names are used as the first component of the server's principal name, with the second component being the server's fully qualified domain name, in lower case.

Troubleshooting
***************

To be written.