\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename install.info
@settitle Kerberos V5
@c For double-sided printing, uncomment:
@setchapternewpage odd
@c %**end of header

@set EDITION BETA 5
@set VERSION BETA 5
@set UPDATED May 5, 1995

@ignore
@iftex
@finalout
@end iftex
@end ignore

@ifinfo
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.

@end ifinfo

@titlepage
@title Kerberos V5
@subtitle Notes on Building and Installing Kerberos
@subtitle Edition @value{EDITION}, for Kerberos version @value{VERSION}
@subtitle @value{UPDATED}
@author by Theodore Ts'o

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 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.

@end titlepage

@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up

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

This is edition @value{EDITION}, for Kerberos V5 version @value{VERSION}.

@end ifinfo

@c The master menu is updated using emacs19's M-x texinfo-all-menus-update
@c function.  Don't forget to run M-x texinfo-every-node-update after
@c you add a new section or subsection, or after you've rearranged the
@c order of sections or subsections.  Also, don't forget to add an @node
@c comand before each @section or @subsection!  All you need to enter
@c is:
@c
@c @node New Section Name

@c @section New Section Name
@c
@c M-x texinfo-every-node-update will take care of calculating the
@c node's forward and back pointers.
@c

@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::        
* OS Incompatibilities::        Special cases to watch for.
* Configuration .h files::      Kerberos V5's header files.
* Using Autoconf::              Modifying Kerberos V5's 
                                            configuration scripts.

Doing the Build

* Building Within a Single Tree::  
* Building with Separate Build Directories::  
* Building using lndir::        

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::                 

Configuration Header Files 

* osconf.h::                    
* config.h::                    

Installation

* Background::                  
* Installation on any Machine::  
* Installing the KDC::          
* Migrating from V4 to V5 Kerberos::  
* A Sample Application::        
* Common Kerberos Service Names::  

Installation on any Machine

* Picking a Realm Name::        
* Configuration files::         
* Required Programs::           

Configuration files

* krb.conf::                    
* krb.realms::                  
* /etc/services::               

Installing the KDC

* 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::   
@end menu

@node Introduction, How Kerberos Works, Top, Top
@chapter 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
@b{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 @samp{diff -c} or @samp{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, @file{krb.conf} and
@file{krb.realms}, are very likely to change in the near future.
(@strong{Actually}, they've changed already; this documentation hasn't
been updated yet to reflect this yet, though.  See the @file{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.

@node How Kerberos Works, Building Kerberos, Introduction, Top
@chapter 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 @i{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::  
@end menu

@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}
programs to request service from @dfn{server} programs that are
somewhere on the network.  Suppose you have logged in to a workstation
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
@section Kerberos Tickets

Under Kerberos, the @samp{rlogind} daemon allows you to login to a
remote machine if you can provide @samp{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.

@node The Kerberos Database, Kerberos Realms, Kerberos Tickets, How Kerberos Works
@section The Kerberos Database

Kerberos will give you credentials only if you have an entry in the Kerberos
server's @dfn{Kerberos database}.  Your database entry includes your
Kerberos @dfn{principal} (which is often just your username), and
your Kerberos password.  Every Kerberos user must have an entry in this
database.

@node Kerberos Realms, The Ticket-Granting Ticket, The Kerberos Database, How Kerberos Works
@section 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 @dfn{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 @dfn{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 @ref{Setting up Slave Kerberos Servers}.

@node The Ticket-Granting Ticket, Network Services and the Master Database, Kerberos Realms, How Kerberos Works
@section The Ticket-Granting Ticket

The @samp{kinit} command prompts for your password, and if you enter
it successfully, you will obtain a @dfn{ticket-granting ticket} and a
@dfn{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 @dfn{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 @dfn{credentials cache}, which is often
simply just a file in @file{/tmp}.  The credentials cache is also
referred to as the @dfn{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.

@node Network Services and the Master Database, The User-Kerberos Interaction, The Ticket-Granting Ticket, How Kerberos Works
@section 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, @samp{laughter.mit.edu}, that requires Kerberos
authentication from anyone who wants to @samp{rlogin} to it.  The host's
Kerberos realm is @samp{ATHENA.MIT.EDU}.  

This service must be registered in the Kerberos database, using the
proper service name, which in this case is
@samp{host/laughter.mit.edu@@ATHENA.MIT.EDU}.  The @kbd{/} character
separates the various @dfn{components} of the Kerberos principal; the
@kbd{@@} character separates the realm name from the rest of the
principal name.  The first component, @samp{host}, denotes the name or
type of the service that is being offered: generic host-level access to
the machine.  The second component, @samp{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::             
@end menu

@node The Keytab File,  , Network Services and the Master Database, Network Services and the Master Database
@subsection The Keytab File

For each service, there must also be a @dfn{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 @dfn{Key
tables}, or @dfn{keytab files}.  (Keytab files were previously
referred to as @dfn{srvtab files} in the V4 literature.)  The service
keys that are used by services which run as root are often stored in
the file @file{/etc/v5srvtab}.

@b{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.

@node The User-Kerberos Interaction,  , Network Services and the Master Database, How Kerberos Works
@section 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 @samp{rlogin} to the machine @samp{laughter}.
Here's what happens:

@enumerate

@item You login to the workstation and use the @samp{kinit} command
to get a ticket-granting ticket.
This command prompts you for your Kerberos password.  (On some systems
which have a modified @samp{/bin/login} program, this may be done as
part of the login process, not requiring the user to run a separate
program.)

@enumerate A

@item The @samp{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.

@item 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 @samp{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 @samp{KRB5_CCNAME} environment variable.  If
this variable is not set, the name of the file will be
@file{/tmp/krb5cc_<uid>}, where <uid> is your UNIX user-id, represented
in decimal format.
@end enumerate

@item Now you use the @samp{rlogin} client to access the machine
@samp{laughter}.

@example
host% @b{rlogin laughter}
@end example

@enumerate A

@item The @samp{rlogin} client checks your ticket file to see if you
have a ticket for the @samp{host} service for @samp{laughter}.
You don't, so @samp{rlogin} uses the credential cache's ticket-granting
ticket to make a request to the master server's ticket-granting service.

@item This ticket-granting service receives the
@samp{host/laughter.mit.edu} request and looks in the master database
for an @samp{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.

@item The @samp{rlogin} client now sends that ticket to 
the @samp{laughter} @samp{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 @samp{laughter} (because the your name matches one in
/etc/passwd, or you are in the appropriate @file{.klogin} file), will
let you login.

@end enumerate
@end enumerate

@node Building Kerberos, Installation, How Kerberos Works, Top
@chapter Building Kerberos

Starting with the Beta 4 distribution, we are using a new configuration
system, which was built using the Free Software Foundation's
@samp{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::        
* 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

@node Build Requirements, Unpacking the Sources, Building Kerberos, Building Kerberos
@section 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 @dfn{build tree}, which contains the compiled
@file{*.o} file and executables, separate from your source tree, you
will need a @samp{make} program which supports @samp{VPATH}, or
you will need to use a tool such as @samp{lndir} to produce a symbolic
link tree for your build tree.

@node Unpacking the Sources, Doing the Build, Build Requirements, Building Kerberos
@section 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 @file{krb5.src.tar.gz},
contains the sources for all of Kerberos except for the crypto library,
which is found in the file @file{krb5.crypto.tar.gz}.

Both files should be unpacked in the same directory, such as
@file{/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.)


@node Doing the Build, Testing the Build, Unpacking the Sources, Building Kerberos
@section 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.

@menu
* Building Within a Single Tree::  
* Building with Separate Build Directories::  
* Building using lndir::        
@end menu

@node Building Within a Single Tree, Building with Separate Build Directories, Doing the Build, Doing the Build
@subsection Building Within a Single Tree

If you don't want separate build trees for each architecture, then
use the following abbreviated procedure.

@enumerate
@item @code{cd /u1/krb5/src}
@item @code{./configure}
@item @code{make}
@end enumerate

That's it!

@node Building with Separate Build Directories, Building using lndir, Building Within a Single Tree, Doing the Build
@subsection 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
@samp{make} program support @samp{VPATH}.  GNU's gmake will provide this
functionality, for example.)  If your @samp{make} program does not
support this, see the next section.

For example, if you wish to create a build directory for @code{pmax} binaries
you might use the following procedure:

@enumerate
@item @code{mkdir /u1/krb5/pmax}
@item @code{cd /u1/krb5/pmax}
@item @code{../src/configure}
@item @code{make}
@end enumerate

@node Building using lndir,  , Building with Separate Build Directories, Doing the Build
@subsection Building Using @samp{lndir}

If you wish to keep separate build directories for each platform, and
you do cannot use a @samp{make} program which supports @samp{VPATH},
all is not lost.  You can use the @samp{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:

@enumerate
@item @code{mkdir /u1/krb5/solaris}
@item @code{cd /u1/krb5/solaris}
@item @code{/u1/krb5/src/util/lndir `pwd`/../src}
@item @code{./configure}
@item @code{make}
@end enumerate

You must give an absolute pathname to lndir because it has a bug that
makes it fail for relative pathnames.

@node Testing the Build, Options to Configure, Doing the Build, Building Kerberos
@section 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 @samp{make} to start
building Kerberos; see @ref{Doing the Build}.): 

@example
% @b{make check}
@end example

@node Options to Configure, OS Incompatibilities, Testing the Build, Building Kerberos
@section Options to Configure 

There are a number of options to @samp{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 @samp{configure}
program.

@table @code

@item --with-cc=COMPILER

Use @code{COMPILER} as the C compiler.

@item --with-ccopts=FLAGS

Use @code{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 @samp{-g} flag nor the @samp{-O} flag to @samp{cc}.

@item --with-cppopts=CPPOPTS 

Use @code{CPPOPTS} as the default set of C preprocessor flags.  The most
common use of this option is to select certain @code{#define}'s for use
with the operating system's include files.

@item --with-krb5-root=DIR

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

@item  --with-krb4=KRB4DIR 

This option enables Kerberos V4 backwards compatibility.  The directory
specified by @code{KRB4DIR} specifies where the V4 header files should
be found (@file{/KRB4DIR/include}) as well as where the V4 Kerberos
library should be found (@file{/KRB4DIR/lib}).

@end table

For example, in order to configure Kerberos on a Solaris machine using
the @samp{suncc} with the optimizer turned on, run the configure
script with the following options:

@example
% configure --with-cc=suncc --with-ccopts=-O
@end example

@node OS Incompatibilities, Configuration .h files, Options to Configure, Building Kerberos
@section 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 @b{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::                 
@end menu

@node Ultrix 4.2/3, Alpha OSF/1 V1.3, OS Incompatibilities, OS Incompatibilities
@subsection Ultrix 4.2/3

On the MIPS platform, using the native compiler, @file{md4.c} and
@file{md5.c} can not be compiled with the optimizer set at level 1.
That is, you must specify either @samp{--with-ccopts=-O} and
@samp{--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.

@node Alpha OSF/1 V1.3, Alpha OSF/1 V2.0, Ultrix 4.2/3, OS Incompatibilities
@subsection Alpha OSF/1 V1.3

There is a bug in OSF/1's fgrep which causes the @samp{configure}
script to fail.

Using the native compiler, compiling with the @samp{-O} compiler flag
causes the @code{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.

@node Alpha OSF/1 V2.0, BSDI, Alpha OSF/1 V1.3, OS Incompatibilities
@subsection Alpha OSF/1 V2.0

Using the native compiler, @file{md4.c} must be compiled with either the
@samp{-O} or @samp{-g} compiler options.  (This could possibly be the
same sort of bug as found in @ref{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.

@node BSDI, Solaris versions 2.0 through 2.3, Alpha OSF/1 V2.0, OS Incompatibilities
@subsection BSDI

BSDI reportedly has a bad @samp{sed} which causes it to go into an
infinite loop during the build.  The work around is to use a @samp{sed}
from somewhere else, such as GNU.

@node Solaris versions 2.0 through 2.3, Solaris 2.X, BSDI, OS Incompatibilities
@subsection Solaris versions 2.0 through 2.3

The @code{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,
@samp{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:  

@enumerate

@item   Supply your own resolver library.

@item   Upgrade to Solaris 2.4

@item   Make sure your /etc/nsswitch.conf has the line:

@example
hosts:      files dns
@end example

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:

@example
18.172.1.4      dcl.mit.edu dcl
@end example

@end enumerate

@node Solaris 2.X,  , Solaris versions 2.0 through 2.3, OS Incompatibilities
@subsection Solaris 2.X

You @b{must} compile Kerberos V5 without the UCB compatibility
libraries.  This means that @file{/usr/ucblib} must not be in the
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 are two configuration files which you may wish to edit to control
various compile-time parameters in the Kerberos distribution:
@file{osconf.h} and @file{config.h}.

@menu
* osconf.h::                    
* config.h::                    
@end menu

@node osconf.h, config.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_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 @file{krb.conf} file.

@item DEFAULT_TRANS_FILENAME

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

@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_ETYPE

The default encryption type for the KDC.

@item DEFAULT_KDC_KEYTYPE

The default keytype for the KDC.

@item KDCRCACHE

The name of the replay cache used by the KDC.

@item RCTMPDIR

The directory which stores replay caches.

@end table

@node config.h,  , osconf.h, Configuration .h files
@subsection @file{config.h}

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

@table @code

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

@item 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.

@end table

@node Using Autoconf,  , Configuration .h files, Building Kerberos
@section Using @samp{Autoconf}

(If you are not a developer, you can skip this section.)

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

Normal users will not need to worry about running @samp{autoconf}; the
distribution comes with the @file{configure} files already prebuilt.
Developers who wish to modify the @file{configure.in} files should see
@ref{Top, , Overview, autoconf, The Autoconf Manual}.  

Note that in order to run @samp{autoconf}, you must have GNU @samp{m4}
in your path.  Before you use the @samp{autoconf} in the Kerberos V5
source tree, you may also need to run @samp{configure}, and then run
@samp{make} in the @file{src/util/autoconf} directory in order to
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: 

@example
% cd /u1/krb5/src
% ./util/reconf --force
@end example

The developmental sources are a raw source tree (before it's been packaged
for public release), without the pre-built @file{configure} files.
In order to build from such a source tree, you must do:

@example
% cd krb5/util/autoconf
% ./configure
% make
% cd ../..
% util/reconf
@end example

Then follow the instructions for building packaged source trees (above).
To install the binaries into a binary tree, do:

@example
% cd /u1/krb5/src
% make all
% make install KRB5ROOT=somewhere-else
@end example

Currently this only works if @samp{somewhere-else} is @file{/krb5}.
(It's a bug.)

@node Installation, Troubleshooting, Building Kerberos, Top
@chapter 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 @dfn{Kerberos server}, which is also known as the
@dfn{KDC} (@dfn{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::        
* Common Kerberos Service Names::  
@end menu

@node Background, Installation on any Machine, Installation, Installation
@section Background Information

Your system's security is only as good as the security of your
@samp{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 @samp{root} privileges.
Kerberos also does not protect you from break-ins caused by bugs in your
daemons (e.g., @samp{fingerd} or @samp{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.


@node Installation on any Machine, Installing the KDC, Background, Installation
@section 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 @ref{Installing the KDC}, or
@ref{A Sample Application}, after you finish with the procedures found
in this section.

@menu
* Picking a Realm Name::        
* Configuration files::         
* Required Programs::           
@end menu

@node Picking a Realm Name, Configuration files, Installation on any Machine, Installation on any Machine
@subsection Picking a Realm Name

Before you install Kerberos V5 at your site, you have to choose a
@dfn{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 @code{cygnus.com} (so that you have hostnames
such as @code{ftp.cygnus.com} and @code{tweedledum.cygnus.com}), then
your Kerberos realm should be @code{CYGNUS.COM}.

@node Configuration files, Required Programs, Picking a Realm Name, Installation on any Machine
@comment  node-name,  next,  previous,  up@section 
@subsection Configuration files

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


@menu
* krb.conf::                    
* krb.realms::                  
* /etc/services::               
@end menu

@node krb.conf, krb.realms, Configuration files, Configuration files
@subsubsection The @file{krb.conf} File

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

Create a @file{[KRB5ROOT]/krb.conf} file using the following format:
@example
<realm_name>
<realm_name>   <master_server_name> admin server
@end example

Where @samp{realm_name} specifies the default realm to be used by that
particular system, and @samp{master_server_name} specifies the machine
name on which you will run the master server.  The words @samp{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 @samp{MIT.EDU} and your master
server's name is @samp{kerberos.mit.edu}, the file should have these
contents:

@example
MIT.EDU
MIT.EDU  kerberos.mit.edu admin server
@end example

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

@node krb.realms, /etc/services, krb.conf, Configuration files
@subsubsection The @file{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, @code{ftp.cygnus.com} is
traditionally in the realm @code{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
@samp{[KRB5ROOT]/krb.realms} file.

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

@example
<.domain.name> KERBEROS.REALM1
<host.name> KERBEROS.REALM2
@end example

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:
@example
.LSC.MIT.EDU LSC.MIT.EDU
FILMS.LSC.MIT.EDU MIT.EDU
@end example

If a particular host name matches both a domain name and a host name in
@file{krb.realms}, the entry containing the host name takes precedence.

@node     /etc/services,  , krb.realms, Configuration files
@subsubsection /etc/services

All hosts which will use Kerberos will need to have certain ports
defined in the system's @file{/etc/services} file.  The file
@file{[SOURCEDIR]/config-files/services.append} contains the entries
which should be appened to the @file{/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
@file{services.append} file to the services exported in the NIS or YP
server.

@node Required Programs,  , Configuration files, Installation on any Machine
@subsection 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:

@itemize
@item @file{/krb5/bin/kinit} --- This program allows you to obtain
Kerberos credentials.
@item @file{/krb5/bin/kdestroy} --- This program allows you to destroy
Kerberos credentials which are no longer needed.
@item @file{/krb5/bin/klist} ---- This program allows you to list the
credentials found in your credentials cache.
@end itemize

@node Installing the KDC, Migrating from V4 to V5 Kerberos, Installation on any Machine, Installation
@section Installing the KDC

@menu
* 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::  
@end menu

@node Initializing the KDB, Storing the Master Password, Installing the KDC, Installing the KDC
@subsection Initializing the Kerberos Database

Login to the Kerberos KDC, and use the @samp{su} command to become root.
If you installed the Kerberos administration tools 
with the @samp{make install} command and the default pathnames,
they should be in the @file{/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 @samp{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 @samp{kdb5_create} as follows:

@example
# @b{[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:              @b{<-- [Enter the master password.]}
Re-enter KDC database master key to verify: @b{<-- [Re-enter it.]}
@end example


@node Storing the Master Password, Adding Users to the Database, Initializing the KDB, Installing the KDC
@subsection Storing the Master Password

The @samp{kdb5_stash} command "stashes" the master password in the file
@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
@samp{kdb5_stash}.

On the one hand, if you use @samp{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 @samp{kdb5_stash}, the server cannot be started unless
someone is around to type the password manually.

The command merely prompts for the master password:

@example
# @b{[ADMIN_DIR]/kdb5_stash}
Enter KDC database master key:    @b{<-- [Enter the master password.]}
@end example

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.

@node Adding Users to the Database, Starting the Kerberos Server, Storing the Master Password, Installing the KDC
@subsection Adding Users to the Database

The @samp{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 @samp{[USERNAME]})

@example
# @b{[ADMIN_DIR]/kdb5_edit}
kdb5_edit:  @b{ank [USERNAME]}
Enter password:                        @b{<-- [Enter your password.]}
Re-enter password for verification:    @b{<-- [Re-enter it.]}
kdb5_edit: @b{quit}
@end example

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

@node Starting the Kerberos Server, Setting up Slave Kerberos Servers, Adding Users to the Database, Installing the KDC
@subsection Starting the Kerberos Server

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

@example
# @b{/krb5/sbin/krb5kdc &}
@end example

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

@example
# @b{/krb5/sbin/krb5kdc -m}
@end example

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

@node Setting up Slave Kerberos Servers, Inter-realm Kerberos Operation, Starting the Kerberos Server, Installing the KDC
@subsection 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.

@menu
* Kerberos Slave Database Propagation::  
* Installing a Slave Server::   
@end menu

@node Kerberos Slave Database Propagation, Installing a Slave Server, Setting up Slave Kerberos Servers, Setting up Slave Kerberos Servers
@subsubsection Kerberos Slave Database Propagation

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

On the slave server, the @samp{kpropd} program is invoked out of
@samp{/etc/inetd} server.  After @samp{kprop} and @samp{kpropd} have
mutually authenticated with one another, and @samp{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, @samp{kpropd} will then run @samp{kdb5_edit}
with the appropriate arguments in order to undump the database into a
usable form by the KDC on the slave server.

@node Installing a Slave Server,  , Kerberos Slave Database Propagation, Setting up Slave Kerberos Servers
@subsubsection Installing a Slave Server

@b{To be written.}


@node Inter-realm Kerberos Operation, The Administration Server, Setting up Slave Kerberos Servers, Installing the KDC
@subsection Inter-realm Kerberos Operation

@b{To be written.}

@node The Administration Server, Testing the Kerberos Server, Inter-realm Kerberos Operation, Installing the KDC
@subsection 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
@samp{kdb5_edit} program; see @ref{Adding Users to the Database}.

@node Testing the Kerberos Server,  , The Administration Server, Installing the KDC
@subsection Testing the Kerberos Server

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

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

Use @samp{kinit} as follows:

@example
# @b{[K_USER]/kinit [USERNAME]}
Password for [USERNAME]@@[REALMNAME]:        @b{<-- enter your password}
@end example


Use the @samp{klist} program to list the contents of your ticket file.

@example
# @b{[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]

@end example

@ignore
@c not yet...
If you have any problems, you can examine the log file
@file{/krb5/kerberos.log} on the Kerberos server machine to see if
there was some sort of error.
@end ignore

@node Migrating from V4 to V5 Kerberos, A Sample Application, Installing the KDC, Installation
@section Migrating from V4 to V5 Kerberos

@b{To be written.}

@node A Sample Application, Common Kerberos Service Names, Migrating from V4 to V5 Kerberos, Installation
@section 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
@file{[BUILD_DIR]/appl/sample/sserver} and
@file{[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:

@enumerate 

@item The user starts @samp{sclient} and provides as arguments
to the command the name of the server machine and an optional port on
which to contact the server.

@item @samp{sclient} contacts the server machine and
authenticates the user to @samp{sserver}.

@item @samp{sserver} authenticates itself to @samp{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 @samp{sserver}.

@item @samp{sclient} displays the server's message on the user's
terminal screen.

@end enumerate

@menu
* Installing the Sample Application::  
* Testing the Sample Server::   
@end menu

@node Installing the Sample Application, Testing the Sample Server, A Sample Application, A Sample Application
@subsection Installing the Sample Application

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

@enumerate

@item Add the appropriate entry to the Kerberos database using @samp{kdb_edit}

@item Create a @file{/etc/v5srvtab} file for the server machine.

@item Install the service program and the @file{/etc/v5srvtab}
file on the server machine.

@item Install the client program on the client machine.

@item Update the @file{/etc/services} file on the client and server machines.
@end enumerate

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

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

@enumerate

@item Login as root or @samp{su} to root on the Kerberos server machine.
Use the @samp{kdb5_edit} program to create an entry for
@code{sample} in the Kerberos database:

@example
# @b{[ADMIN_DIR]/kdb5_edit}
kdb5_edit: @b{add_random_key sample/jimi.mit.edu}         
kdb5_edit: @b{quit}
@end example

(Note: @samp{add_random_key} may be abbreviated as @samp{ark}.)

@item Use @samp{kdb5_edit} to create a @file{srvtab} file
for @samp{sserver}'s host machine:

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

(Note: @samp{extract_srvtab} may be appreviated as @samp{xst}.)

Transfer the @file{jimi.mit.edu-new-srvtab} file to @samp{jimi.mit.edu}
and install it as @file{/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.

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

@example
sample     906/tcp       # Kerberos sample app server
@end example

@item Add a line similar to the following line to the @file{/etc/inetd.conf}
file on @samp{sample_server}'s machine:

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

where [PATH] should be substituted with
the path to the @samp{sserver} program.
(This @file{inetd.conf} information should be placed on one line.)
You should examine existing lines in @file{/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).

@item Restart @samp{inetd} by sending the current @samp{inetd} process
a hangup signal:

@example
# @b{kill -HUP} @i{process_id_number}
@end example

@item The @samp{sserver} is now ready to take @samp{sclient} requests.

@end enumerate

@node Testing the Sample Server,  , Installing the Sample Application, A Sample Application
@subsection Testing the Sample Server

Assume that you have installed @samp{sserver} on @samp{jimi.mit.edu}.

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

@example
% @b{[K_USER]/kinit [USERNAME]}
Password for [USERNAME@@[REALMNAME]:            @b{<--- Enter your password}
@end example

Now use the @samp{sclient} program as follows:

@example
% @b{[PATH]/sclient jimi}
@end example

The command should display something like the following:

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

@node Common Kerberos Service Names,  , A Sample Application, Installation
@section Common Kerberos Service Names

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

@table @code

@item host
Used by @samp{telnet}, @samp{rlogin}, @samp{rsh}, @samp{rcp}, and other
services which generally give login access to the host. 

@item pop
Used by the Post Office Protocol.

@item sample
Used by the Kerberos sample applications.

@end table

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.

@node Troubleshooting,  , Installation, Top
@chapter Troubleshooting

@b{To be written.}

@contents
@bye
