\input texinfo @c -*- texinfo -*-
@c %**start of header
@c $Id: kth-krb.texi,v 1.18 1996/07/30 15:44:08 joda Exp $
@setfilename kth-krb.info
@settitle KTH-krb
@iftex
@afourpaper
@end iftex
@setchapternewpage on
@syncodeindex pg cp
@c %**end of header

@c title page
@titlepage
@title KTH-krb
@subtitle Kerberos 4 from KTH
@subtitle Edition -1.0, for version 0.9
@subtitle 1996
@author Johan Danielsson
@author Ilja Hallberg
@author Assar Westerlund
@author last updated $Date: 1996/07/30 15:44:08 $

@page
Copyright 1987, 1989 by the Student Information Processing Board
	of the Massachusetts Institute of Technology

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 names of M.I.T. and the M.I.T. S.I.P.B. not be
used in advertising or publicity pertaining to distribution
of the software without specific, written prior permission.
M.I.T. and the M.I.T. S.I.P.B. make no representations about
the suitability of this software for any purpose.  It is
provided "as is" without express or implied warranty.

Copyright (c) 1983, 1990 The Regents of the University of California.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this software
   must display the following acknowledgement:
     This product includes software developed by the University of
     California, Berkeley and its contributors.

4. Neither the name of the University nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

Copyright (C) 1995 Eric Young (eay@@mincom.oz.au)
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this software
   must display the following acknowledgement:
   This product includes software developed by Eric Young (eay@@mincom.oz.au)

THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

Copyright (C) 1990 by the Massachusetts Institute of Technology

Export of this software from the United States of America is assumed
to require a specific license from the United States Government.
It is the responsibility of any person or organization contemplating
export to obtain such a license 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.

@end titlepage

@c Less filling! Tastes great!
@iftex
@parindent=0pt
@global@parskip 6pt plus 1pt
@global@chapheadingskip = 15pt plus 4pt minus 2pt 
@global@secheadingskip = 12pt plus 3pt minus 2pt
@global@subsecheadingskip = 9pt plus 2pt minus 2pt
@end iftex

@ifinfo
@node Top, Introduction, (dir), (dir)
@top KTH-krb
@end ifinfo

@menu
* Introduction::                
* What is Kerberos?::           
* Installing::                  
* How to set up a realm::       
* Administrator guide::         
* User guide::                  
* Programs::                    
* Resolving frequent problems::  
* Bypassing kerberos (what you should not do)::  
* Concept Index::               
@end menu

@node Introduction, What is Kerberos?, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction

This is the beginning of documentation for the Kerberos 4 distribution
from KTH (the Royal Institute of Technology in Stockholm, Sweden).  This
distribution is based on eBones, but has been improved in many ways. It
is more portable, and several new features has been added. It currently
runs (that is, we are using it) on the following systems.

@itemize @bullet
@item
AIX 3.2/4.1
@item
BSD/OS 2.0
@item
Digital UNIX 3.2
@item
HP-UX 9
@item
IRIX 5.3
@item
Linux 1.2/1.3
@item
NetBSD 1.1
@item
SunOS 4.1
@item
SunOS 5.4/5.5 (aka Solaris 2.4/2.5)
@item
Ultrix 4.4
@item
Most parts runs under Cray UNICOS 9.
@end itemize

It should work on anything that is almost POSIX, has an ANSI C
compiler, a dbm library, and sockets.

Bugs, suggestions, and comments about this manual are welcome.  Please
send them to ``kth-krb-bugs@@nada.kth.se''.

@node What is Kerberos?, Installing, Introduction, Top
@chapter What is Kerberos?

Kerberos is a system for authenticating users and services on a network.
It is built upon the assumption that the network is ``unsafe'', that we
cannot trust it.  Data sent over the network can be eavesdropped and
altered.  The addresses can also by altered so they cannot be used for
authentication purposes.

Kerberos is a trusted third-party service.  That means that there is a
third party (the kerberos server) that is trusted by all the entities on
the network (users and services).  All entities (also called principals)
share a secret password (or key) with the kerberos server and this
enables them to be sure that the messages from the kerberos are in fact,
authentic.  Trusting the kerberos server, users and services can use it
to authenticate to each other.

@node Installing, How to set up a realm, What is Kerberos?, Top
@chapter Installing

You can choose to build the distribution from the source code or
installing binaries if they are available for your machine.

@c XXX

Using pre-compiled binaries is easier.  If there are no binaries for
your machine or you want to configure in some special way, you will have
to compile from source.

@menu
* Compiling from source::       
* Bug reports::                 
* Installing a binary distribution::  
* Finishing the installation::  
@end menu

@node Compiling from source, Bug reports, Installing, Installing
@comment  node-name,  next,  previous,  up
@section Compiling from source

To build this software un-tar the distribution and run the
@code{configure} script.

To compile successfully, you will need an ANSI C compiler, such as
@code{gcc}. Other compilers might also work, but setting the ``ANSI
compliance'' too high, might break in parts of the code, not to mention
the standard include files.

To build in a separate build tree, run @code{configure} in that
directory.  You will need a make that understands VPATH correctly.  GNU
Make works fine.  Some makes get confused in @file{util/ss}, so you
might need to give it a hand there.

After building everything (which will take anywhere from a few minutes
to a long time), you can install everything in /usr/athena with @kbd{make
install} (running as root). It is possible to install in some other
place, but it isn't recommended. To do this you will have to run
configure with @samp{--prefix=/my/path}.

If you need to change the default behaviour, configure understands the
following options:

@table @asis
@item @kbd{--with-skeylib=}@var{dir}
This option enables programs that prompt for passwords to use
@cindex S/Key
S/Key for user authentication. You need S/Key from the
@cindex logdaemon
logdaemon distribution.

@item @kbd{--with-shared}
Also create shared versions of the Kerberos libraries.

@item @kbd{--with-cracklib=}@var{dir}
Use cracklib for password quality control in 
@pindex kadmind
@code{kadmind}. This option requires 
@cindex cracklib
cracklib with the patch from
@code{ftp://ftp.nada.kth.se/pub/krb/src/cracklib.patch}.

@item @kbd{--with-dictpath=}@var{dictpath}
This is the dictionary that cracklib should use.

@item @kbd{--with-mailspool=}@var{dir}
The configuration process tries to guess where your machine stores its
incoming mail.  This is typically @file{/usr/spool/mail} or
@file{/var/mail}.  If it does not work or you store your mail in some
unusual directory, this option can be used to specify where the mail
spool directory is located.  Only used by 
@pindex popper
@code{popper}.

@item @kbd{--enable-random-mkey}
Do not use this option unless you think you know what you are doing.

@item @kbd{--with-mkey=}@var{file}
Put the master key here, the default is @file{/.k}.

@item @kbd{--without-berkeley-db}
If you have
@cindex Berkeley DB
Berkeley DB installed, it is preferred over
@c XXX
dbm. If you already are running Kerberos this option is might be useful,
since there currently isn't any easy way to convert a dbm database to a
db one. This should probably be fixed.
@end table

@node Bug reports, Installing a binary distribution, Compiling from source, Installing
@comment  node-name,  next,  previous,  up
@section Bug reports

If you are not able to build the programs or they do not behave as you
think they should, please send us a bug report.  The bug report should
be sent to @code{kth-krb-bugs@@nada.kth.se}.  Please include information
on what machine and operating system (including version) you are
running, what you are trying to do, what happens, what you think should
have happened, an example for us to repeat, the output you get when
trying the example, and a patch for the problem if you have one.  Please
make any patches with @code{diff -u} or @code{diff -c}.  The more
detailed you make your bug report, the easier it is for us to reproduce
it and understand it and the faster it will be fixed.

@node Installing a binary distribution, Finishing the installation, Bug reports, Installing
@comment  node-name,  next,  previous,  up
@section Installing a binary distribution

The binary distribution is supposed to be installed in
@file{/usr/athena}, installing in some other place should work, but
is not recommended. A symlink to @file{/usr/athena} is fine.

@node Finishing the installation,  , Installing a binary distribution, Installing
@section Finishing the installation

@pindex su
The only program that needs to be installed setuid to root is @code{su}.

If 
@pindex rlogin
@pindex rsh
the setuid bit on @code{rlogin} and @code{rsh} is turned on they will
fall back to non-kerberised protocols if the kerberised fail for some
reason. The old protocols use reserved ports as security, and therefore
has to be setuid to root. If you don't need this functionality, consider
turning the setuid bit off.

@pindex login
@code{login} does not have to be setuid, as it is run by root (users
should use @code{su} rather than @code{login}).

The programs that users would want to use is located in
@file{/usr/athena/bin}.  Tell your users to include @file{/usr/athena/bin} in
their paths, or copy or symlink the binaries to some good place. The
binaries that you want to use are: @code{kauth}/@code{kinit},
@pindex kauth
@pindex kinit
@code{klist}, @code{kdestroy}, @code{kpasswd}, @code{ftp},
@pindex klist
@pindex kdestroy
@pindex kpasswd
@pindex ftp
@code{telnet}, @code{rcp}, @code{rsh}, @code{rlogin}, @code{su}, and
@pindex telnet
@pindex rcp
@pindex rsh
@pindex rlogin
@pindex su
@pindex xnlock
@pindex afslog
@pindex pagsh
@code{xnlock}. If you are using AFS, @code{afslog} and @code{pagsh} might
also be useful. Administrators will want to use @code{kadmin} and
@code{ksrvutil}.
@pindex kadmin
@pindex ksrvutil

@code{telnetd} and @code{rlogind} assume that login is located in
@file{/usr/athena/bin} (or whatever path you used as @samp{--prefix}). If for
some reason you want to move @file{login}, you will have to specify
the new location with the @samp{-L} switch when configuring
@pindex telnetd
telnetd
and
@pindex rlogind
rlogind
in @file{inetd.conf}.

It should be possible to replace the system's default @code{login} with
the kerberised @code{login}. However some systems assume that login
works some serious amount of magic that our login might not do (although
we've tried to do our best). So before replacing it, try and see what
happens.

The @code{login} program that we use was in an earlier life the standard
login program from NetBSD. In order to use it with a lot of weird
systems it has been enhanced with features from many systems (Solaris,
SunOS, IRIX, and others).
There might be some of these features that you want to use.  Until
someone writes some documentation you will have to read the source to
find all the features.

Follow the instruction in @file{etc/README} (from the distribution) of
how to fix the files in @file{/etc}.  You will want to update
@file{/etc/services}, @file{/etc/krb.conf}, and @file{/etc/krb.realms}.
These files are only
@pindex etc/services
@pindex krb.conf
@pindex krb.realms
in the source distribution.

@node How to set up a realm, Administrator guide, Installing, Top
@chapter How to set up a realm

@menu
* How to set up the kerberos server::  
* Install the client programs::  
* Install the kerberised services::  
* Install a slave kerberos server::  
* Cross-realm functionality ::  
@end menu

@node How to set up the kerberos server, Install the client programs, How to set up a realm, How to set up a realm
@section How to set up the kerberos server

@menu
* Choose a realm name::         
* Choose a kerberos server::    
* Install the configuration files::  
* Install the /etc/services::   
* Install the kerberos server::  
* Set up the server::           
* Add a few important principals::  
* Start the server::            
* Test to get tickets::         
* Create initial ACL for the admin server::  
* Start the admin server::      
* Test the admin server::       
* Automate the startup of the servers::  
@end menu

@node Choose a realm name, Choose a kerberos server, How to set up the kerberos server, How to set up the kerberos server
@subsection Choose a realm name

A realm is an administrative domain.  Kerberos realms are usually
written in uppercase and consists of the Internet domain
name@footnote{Using lowercase characters in the realm name might break
in mysterious ways. This should be fixed.}  Call your realm the same as
your Internet domain name if you do not have strong reasons for not
doing so.  It will make it easier for you and everyone else.

@node Choose a kerberos server, Install the configuration files, Choose a realm name, How to set up the kerberos server
@subsection Choose a kerberos server

You need to choose a machine to run the kerberos server program.
If the kerberos database residing on this host is compromised,
your entire realm will be compromised.  Therefore, this machine
must be as secure as possible.  Preferably it should not run
any other service than Kerberos.  If possible, only allow logins
on the console.

You also want this machine to be reliable.  If this machine is down, you
will not be able to use any kerberised services unless you have also
configured a slave server (@xref{Install a slave kerberos server}).

Running the kerberos server requires very little CPU power and
only small amounts of disk.  A 386 with some hundreds of megabytes of
free diskspace should do fine. 

@node Install the configuration files, Install the /etc/services, Choose a kerberos server, How to set up the kerberos server
@subsection Install the configuration files

There are two important configuration files: @file{/etc/krb.conf} and
@file{/etc/krb.realms}.
@pindex krb.conf
@pindex krb.realms

The @file{krb.conf} file determines which machines are servers for
different realms.  The format of this file is:

@example
THIS.REALM
THIS.REALM              kerberos.this.realm admin server
THIS.REALM              kerberos-1.this.realm
ANOTHER.REALM           kerberos.another.realm
@end example

The first line defines the name of the local realm. Line two defines the
name of the master kerberos server and the database administration
server for this realm.  You can define any number of kerberos slave
servers similar to the one defined in line three.  The clients will try
to contact the servers in the order they are defined in @file{krb.conf}.

If the information about a realm is missing from the @file{krb.conf}
file, all programs will try to lookup @samp{kerberos.@var{REALM}} in the
DNS and use that instead.  It strongly recommended to add a CNAME in
your DNS for your kerberos server.

The @file{krb.realms} file is used to find out what realm a particular
host belongs to.  An example of this file could look like:

@example
this.realm            THIS.REALM
.this.realm           THIS.REALM
foo.com               SOME.OTHER.REALM
www.foo.com           A.STRANGE.REALM
.foo.com              FOO.REALM
@end example

Entries starting with a dot is taken as the name of a domain. Entries
not starting with a dot is taken as a hostname. The first entry matched
is used. The entry for @samp{this.realm} is only necessary if there is a
host named @samp{this.realm}. If there isn't any matching entry for a host,
the uppercase hostname sans the first part will be used.

Make sure that @file{krb.conf} and @file{krb.realms} contains all other
realms that you will interact with.

@node Install the /etc/services, Install the kerberos server, Install the configuration files, How to set up the kerberos server
@subsection Updating /etc/services

You should append or merge the contents of @file{services.append} to your
@file{/etc/services} files or NIS-map. Remove any factory installed kerberos
port definitions to avoid possible conflicts.
@pindex /etc/services

Most of the programs will fall back to the default ports if the port
numbers are not found in @file{/etc/services}, but it is convenient to
have them there anyway.

@node Install the kerberos server, Set up the server, Install the /etc/services, How to set up the kerberos server
@subsection Install the kerberos server

You should have chosen the machine where you want to run the kerberos
server and the realm name prior to this.  The machine should also have
been made as secure as possible (@xref{Choose a kerberos server}) before
installing the kerberos server.  In this example, we will install a
kerberos server for the realm @samp{FOO.SE} on the machine called
@samp{hemlig.foo.se}.

@node Set up the server, Add a few important principals, Install the kerberos server, How to set up the kerberos server
@subsection Setup the server

Login as root on the console of the kerberos server.  Add
@file{/usr/athena/bin} and @file{/usr/athena/sbin} to your path.  Run
@kbd{kdb_init}:
@pindex kdb_init

@example
@cartouche
hemlig# kdb_init
Realm name [default  FOO.SE ]: 
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.

Enter Kerberos master password: 
Verifying password 
Enter Kerberos master password: 
@end cartouche
@end example

If you have set up the configuration files correctly, @kbd{kdb_init}
should choose the correct realm as default, otherwise a good guess is
made.  Enter the master password.

This password will only be used for encrypting the kerberos database on
disk and for generating new random keys.  You will not have to remember
it, only to type it again when you run @kbd{kstash}.  Please choose
something long and random and not necessarily something that you can
remember.  Now run @kbd{kstash} using the same password:
@pindex kstash

@example
@cartouche
hemlig# kstash

Enter Kerberos master password: 

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
Wrote master key to /.k
@end cartouche
@end example

After entering the same master password once again it will be saved in
the file @file{/.k} and the kerberos server will read it from @file{/.k}
when needed. Write down the master password and put it in a sealed
envelope in a safe, you might need it when your disk has crashed or when
you want to set up a secondary server.

@code{kdb_init} initializes the database with a few entries:

@table @samp
@item krbtgt.@var{realm}
The key used for authenticating to the kerberos server.

@item changepw.kerberos
The key used for authenticating to the administrative server, i.e. when
adding users, chaning passwords, and so on.

@item default
This entry is copied to new items when these are added.  So this is the
place where you put the values you want new entries to have,
particularly the expire date.

@item K.M
This is the master key and it is only used to verify that the master key
that is saved unencrypted in @file{/.k} is correct and corresponds to
this database.

@end table

@code{kstash} only reads the master passwords and writes it to
@file{/.k}.  This is to enable the kerberos server to start without you
having to enter the master password.  This file (@file{/.k}) is only
readable by root and resides on a ``secure'' machine.

@node Add a few important principals, Start the server, Set up the server, How to set up the kerberos server
@subsection Add a few important principals

Now the kerberos database has been created, containing only a few
principals.  The next step is to add a few more so that you can test
that it works properly and so that you can administer it without
having to use the console on the kerberos server.  Use @kbd{kdb_edit}
to edit the kerberos database direcectly on the server.
@pindex kdb_edit

@code{kdb_edit} is intended as a boostraping and fallback mechanism for
editing the database.  For normal purposes, use the kadmin program
(@xref{Test the admin server}).

The following example shows the addition of user @samp{nisse} into the
kerberos database. Replace @samp{nisse} and @samp{password} with your own
username and password.

@example
@cartouche
hemlig# kdb_edit -n
Opening database...
Current Kerberos master key version is 1.

Master key entered.  BEWARE!
Previous or default values are in [brackets] ,
enter return to leave the same, or new value.

Principal name: <nisse>
Instance: <>

<Not found>, Create [y] ? <>

Principal: nisse, Instance: , kdc_key_ver: 1
New Password: <password>
Verifying password 
New Password: <password>

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? <>
Max ticket lifetime (*5 minutes) [ 255 ] ? <>
Attributes [ 0 ] ? <>
Edit O.K.
Principal name: <nisse>
Instance: <admin>

<Not found>, Create [y] ? <>

Principal: nisse, Instance: admin, kdc_key_ver: 1
New Password: <password>
Verifying password 
New Password: <password>

Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? <>
Max ticket lifetime (*5 minutes) [ 255 ] ? <>
Attributes [ 0 ] ? <>
Edit O.K.
Principal name: <>
@end cartouche
@end example

@code{kdb_edit} will loop until you press only the @kbd{return} key at
the ``Principal name'' prompt. Now you have added two principals:
nisse as a normal user and nisse as an administrator.

@node Start the server, Test to get tickets, Add a few important principals, How to set up the kerberos server
@subsection Start the server

@pindex kerberos
@example
@cartouche
hemlig# /usr/athena/libexec/kerberos &
Kerberos server starting
Sleep forever on error
Log file is /var/log/kerberos.log
Current Kerberos master key version is 1.

Master key entered.  BEWARE!

Current Kerberos master key version is 1
Local realm: FOO.SE
@end cartouche
@end example

@node Test to get tickets, Create initial ACL for the admin server, Start the server, How to set up the kerberos server
@subsection Test to get tickets

Now you can verify that these entries have been added and that the
server is working correctly.

@pindex kinit
@example
@cartouche
hemlig# kinit
eBones International (hemlig.foo.se)
Kerberos Initialization
Kerberos name: <nisse>
Password: <password>
@end cartouche
@end example

If you do not get any error message from @code{kinit}, then everything
is working perfectly so far.  Use @code{klist} to verify the
tickets you acquired with @code{kinit}:

@pindex klist
@example
@cartouche
hemlig# klist
Ticket file:    /tmp/tkt0
Principal:      nisse@@FOO.SE

Issued           Expires          Principal
May 24 21:06:03  May 25 07:06:03  krbtgt.FOO.SE@@FOO.SE
@end cartouche
@end example

@node Create initial ACL for the admin server, Start the admin server, Test to get tickets, How to set up the kerberos server
@subsection Create initial ACL for the admin server

The admin server, @code{kadmind}, uses a series of files to determine who has
@pindex kadmind
the right to perform certain operations.  The files are:
@file{admin_acl.add}, @file{admin_acl.get}, @file{admin_acl.del}, and
@file{admin_acl.mod}.  Create these with @samp{nisse.admin@@FOO.SE} as
the contents.
@pindex admin_acl.add
@pindex admin_acl.get
@pindex admin_acl.mod

@example
@cartouche
hemlig# echo "nisse.admin@@FOO.SE" > /var/kerberos/admin_acl.add
hemlig# echo "nisse.admin@@FOO.SE" > /var/kerberos/admin_acl.get
hemlig# echo "nisse.admin@@FOO.SE" > /var/kerberos/admin_acl.mod
hemlig# echo "nisse.admin@@FOO.SE" > /var/kerberos/admin_acl.del
@end cartouche
@end example

Later on you may wish to add more users with administration
privieges. Make sure that you create both the admininstration principals
and add them to the admin server ACL.

@node Start the admin server, Test the admin server, Create initial ACL for the admin server, How to set up the kerberos server
@subsection Start the admin server

@pindex kadmind
@example
@cartouche
hemlig# /usr/athena/libexec/kadmind &
KADM Server KADM0.0A initializing
Please do not use 'kill -9' to kill this job, use a
regular kill instead

Current Kerberos master key version is 1.

Master key entered.  BEWARE!
@end cartouche
@end example

@node Test the admin server, Automate the startup of the servers, Start the admin server, How to set up the kerberos server
@subsection Test the admin server

Use the @code{kadmin} client to verify the operation of the admin
@pindex kadmin
server:

@example
@cartouche
hemlig# kadmin -u nisse -m
Welcome to the Kerberos Administration Program, version 2
Type "help" if you need it.
admin:  <get nisse>
Admin password: <nisse.admin's password>
Info in Database for nisse.:
Max Life: 255 (Forever)   Exp Date: Sat Jan  1 05:59:59 2000

Attribs: 00  key: 0 0
admin:  <^D>
Cleaning up and exiting.
@end cartouche
@end example

@node Automate the startup of the servers,  , Test the admin server, How to set up the kerberos server
@subsection Automate the startup of the servers

Add the lines that were used to start the kerberos server and the
admin server to whatever startup scripts (@file{/etc/rc} or similar)
@pindex /etc/rc
that your system uses.

@node Install the client programs, Install the kerberised services, How to set up the kerberos server, How to set up a realm
@section Install the client programs

To make a machine a kerberos client requires only a few steps.  First
you need to change the configuration files in the same manner as for the
kerberos server.  (@xref{Install the configuration files}, @xref{Install
the /etc/services})  Then you need to make the programs in
@file{/usr/athena/bin} available.  This can be done by adding the
@file{/usr/athena/bin} directory to the users' path, by making symbolic
links, or even by copying the programs.

You should also verify that the local time on the client is synchronised
with the time on the kerberos server by some means. The maximum allowed
time difference between the participating servers and a client is 5
minutes.  The recommended method of synchronizing the time is NTP
(Network Time Protocol).
@cindex NTP.
If your system lacks the NTP suite of programs
you can obtain source or binaries from most well known anonymous ftp
sites, use @kbd{archie} to locate the site closest to you.

If you need to run the client programs on a machine where you do
not have root-access, you can hopefully just use the binaries and no
configuration will be needed.  The heuristics used are mentioned above.
If this is not the case and you need to have @file{krb.conf} and/or
@file{krb.realms}, you can copy them into a directory of your choice and
@pindex krb.conf
@pindex krb.realms
set the environment variable @var{KRBCONFDIR} to point at this
@cindex KRBCONFDIR
directory.

To test the client functionality, run the @code{kinit} program:

@example
@cartouche
foo$ kinit
eBones International (foo.foo.se)
Kerberos Initialization
Kerberos name: <nisse>
Password: <password>

foo$ klist
Ticket file:    /tmp/tkt4711
Principal:      nisse@@FOO.SE

Issued           Expires          Principal
May 24 21:06:03  May 25 07:06:03  krbtgt.FOO.SE@@FOO.SE
@end cartouche
@end example

@node Install the kerberised services, Install a slave kerberos server, Install the client programs, How to set up a realm
@section Install the kerberised services

By this we mean make a machine use the services that use kerberos for
authentication.  Typically this includes @code{rsh}, @code{rlogin},
@code{telnet}, @code{ftp}, and so on.
@pindex rsh
@pindex rlogin
@pindex telnet
@pindex ftp

First take all the steps mentioned in the prior section to make it
a client and verify that it works correctly.  The next will be to
change @file{inetd.conf} to use the new daemons.  Look at the file
@pindex /etc/inetd.conf
@file{etc/inetd.conf.changes} to see the changes that we recommend you
do perform on @file{inetd.conf}.

You should at this point decide what services you want to run on
each machine.

@unnumberedsubsec rsh, rlogin, and rcp
@pindex rsh
@pindex rlogin
@pindex rcp

These exist in kerberised versions and ``old-style'' versions.  The
different versions use different port numbers, so you can choose
none, one, or both.  If you do not want to use ``old-style'' r*
services, you can let the programs output a text (``Remote host
requires Kerberos authentication'') instead of just refusing
connections to that port.  This is enabled with the ``-v'' option.
The kerberised services exists in encrypted and non-encrypted
versions.  The encrypted services have a ``e'' prepended to the name and
the programs take ``-x'' as an option indicating encryption.

Our recommendation is to only use the kerberised services and
supply the explanation message on the old port numbers.

@unnumberedsubsec telnet
@pindex telnet

The telnet service always uses the same port and then it does
negotiation as to which authentication should be used.  The
telnetd programs has an option ``-a user'' that only allows
kerberised and authenticated connections.  If this is not
included, it falls back to using clear text passwords.  For obvious
reasons, we recommend that you enable this option.

@unnumberedsubsec pop
@pindex popper

The Post Office Protocol (POP) is used to retrieve mail from the mail
hub, the machine that receives all incoming mail and stores it until
someone fetches it.  The @code{popper} program implements the standard
POP3 protocol and the kerberised KPOP.  Use the ``-k'' option to run the
kerberos version of the protocol. This service should only be run
on your mail hub.

@unnumberedsubsec kauth
@pindex kauth

This service allows you to create tickets on a remote host.  To
enable it just insert the corresponding line in @file{inetd.conf}.

@unnumberedsubsec srvtabs
@pindex /etc/srvtab

In the same way every user need to have a password registered with
the kerberos server, every service needs to have a shared key with the
kerberos server.  Instead of passwords that are (hopefully) remembered
by the users, the service keys are stored in a file, usually called
@file{/etc/srvtab}.  This file should not be readable by anyone but
root, to keep the key from being divulged.  The name of this principal
in the kerberos database is usually the service and the host.  The key
for the pop service is called @samp{pop.@var{hostname}}.  The one for
rsh/rlogin/telnet is named @samp{rcmd.@var{hostname}}.  (rcmd comes from
``remote command'').  To create these keys you will use the the
@code{ksrvutil} program.  Do the
@pindex ksrvutil
following:

@example
@cartouche
bar# ksrvutil -p nisse.admin get
Name [rcmd]: <>
Instance [bar]: <>
Realm [FOO.SE]: <>
Is this correct? (y,n) [y] <>
Add more keys? (y,n) [n] <>
Password for nisse.admin@@FOO.SE: <nisse.admin's password>
Written rcmd.bar
rcmd.bar@@FOO.SE
Old keyfile in /etc/srvtab.old.
@end cartouche
@end example

@unnumberedsubsec Test the kerberised services

Now comes the complete test.  Get a ticket on one machine (@samp{foo})
and use it to login with a kerberised service to a second machine
(@samp{bar}).  The test should look like this if successful:

@example
@cartouche
foo$ kinit nisse
eBones International (foo.foo.se)
Kerberos Initialization for "nisse"
Password: <nisse's password>
foo$ klist
Ticket file:    /tmp/tkt4711
Principal:      nisse@@FOO.SE

Issued           Expires          Principal
May 30 13:48:03  May 30 23:48:03  krbtgt.FOO.SE@@FOO.SE
foo$ telnet bar
Trying 17.17.17.17...
Connected to bar.foo.se
Escape character is '^]'.
[ Trying mutual KERBEROS4 ... ]
[ Kerberos V4 accepts you ]
[ Kerberos V4 challenge successful ]
bar$
@end cartouche
@end example

You can also try with ``rsh'', ``rcp'', ``rlogin'', ``rlogin -x'', and
some other commands to see that everything is working all right.

@node Install a slave kerberos server, Cross-realm functionality , Install the kerberised services, How to set up a realm
@section Install a slave kerberos server

It is desirable to have at least one backup (slave) server in case the
master server goes down. It is possible to have any number of such slave
servers but more than three usually doesn't buy much.

To set up a slave server you first have to select a good server machine.
@xref{Choose a kerberos server}. Since the master and slave servers will
use copies of the same database, they need to use the same master
key. 

Add a @samp{rcmd.kerberos} principal (using @samp{ksrvutil get}). The
@pindex kprop
@code{kprop} program will use this when authenticating to the
@pindex kpropd
@code{kpropd} daemons running on the slave servers, so this key should
reside in the @file{/etc/srvtab} file on the master server.

On your master server, create a file, e.g @file{/var/kerberos/slaves},
that contains the hostnames of your kerberos slave servers.

Start @code{kpropd} on your slave servers.

On your master server, create a dump of the database with @samp{kdb_util
dump /var/kerberos/slave_dump}, and then run @code{kprop}.

You should now have copies of the database on your slave servers. You
can verify this by issuing @samp{kdb_util slave_dump @var{file}} on your
slave servers, and comparing with the original file on the master
server. Note that the entries will not be in the same order.

This procedure should be automated with a script run regulary by cron,
for instance once an hour.

To start the kerberos server on slaves, you first have to copy the
master key from the master server. You can do this either by remembering
the master password and issuing @samp{kstash}, or you can just copy the
keyfile. Remember that if you copy the file, do so on a safe media, not
over the network. Good means are on a floppy or on paper. Paper is
better, since it is easier to eat afterwards.

The kerberos server should be started with @samp{-s} on the slave
servers. This enables some sanity checks, such as checking the time
since the last update from the master.

All changes to the database are made by @code{kadmind} at the master,
and then propagated to the slaves, so you should @strong{not} run
@code{kadmind} on the slaves.

All you have to do now is to add the slave servers to
@file{/etc/krb.conf}. The clients will ask the servers in the order
specified by that file.


@node Cross-realm functionality ,  , Install a slave kerberos server, How to set up a realm
@section Cross-realm functionality

Suppose you are residing in the realm @samp{MY.REALM}, how do you
authenticate to a servers in @samp{OTHER.REALM}? Having valid tickets in
@samp{MY.REALM} allows you to communicate with kerberised services in that
realm. However, the computer in the other realm does not have a secret
key shared with the kerberos server in your realm.

It is possible to add a shared key between two realms that trust each
other. When a client program, such as @code{telnet}, finds that the
other computer is in an other realm, it will try to get a ticket
granting ticket for that other realm, but from the local kerberos
server. With that ticket granting ticket, it will then obtain service
tickets from the kerberos server in the other realm.

To add this functionality you have to add a principal to each realm. The
principals should be @samp{krbtgt.OTHER.REALM} in @samp{MY.REALM}, and
@samp{krbtgt.MY.REALM} in @samp{OTHER.REALM}. The two different
principals should have the same key, remember to transfer this key in a
safe manner. This is all that is required.

@example
@cartouche
blubb$ klist
Ticket file:    /tmp/tkt3008
Principal:      joda@@NADA.KTH.SE

  Issued           Expires          Principal
Jun  7 02:26:23  Jun  7 12:26:23  krbtgt.NADA.KTH.SE@@NADA.KTH.SE
blubb$ telnet agat.e.kth.se
Trying 130.237.48.12...
Connected to agat.e.kth.se.
Escape character is '^]'.
[ Trying mutual KERBEROS4 ... ]
[ Kerberos V4 accepts you ]
[ Kerberos V4 challenge successful ]
Last login: Sun Jun  2 20:51:50 from emma.pdc.kth.se

agat$ exit
Connection closed by foreign host.
blubb$ klist
Ticket file:    /tmp/tkt3008
Principal:      joda@@NADA.KTH.SE

  Issued           Expires          Principal
Jun  7 02:26:23  Jun  7 12:26:23  krbtgt.NADA.KTH.SE@@NADA.KTH.SE
Jun  7 02:26:50  Jun  7 12:26:50  krbtgt.E.KTH.SE@@NADA.KTH.SE
Jun  7 02:26:51  Jun  7 12:26:51  rcmd.agat@@E.KTH.SE
@end cartouche
@end example

@node  Administrator guide, User guide, How to set up a realm, Top
@comment  node-name,  next,  previous,  up
@chapter Administrator guide

What should go in here?

@node  User guide, Programs, Administrator guide, Top
@comment  node-name,  next,  previous,  up
@chapter User guide

What should go in here?

@node Programs, Resolving frequent problems, User guide, Top
@chapter Programs

The programs included in the distributions can be divided into three
different categories and directories.

Here are some short descriptions of what these programs do.  More
details can be found the in the man pages (and in the source code).

@menu
* User programs::               
* System administrator programs::  
* Daemons::                     
@end menu

@node User programs, System administrator programs, Programs, Programs
@section User programs

The programs that are intended to be executed by users are located in
@file{/usr/athena/bin}.  

@unnumberedsubsec afslog
@pindex afslog

Obtains AFS tokens for the local or a remote cell.

@unnumberedsubsec compile_et
@pindex compile_et

Only used when compiling.

@unnumberedsubsec ftp
@pindex ftp

A FTP-client with the preliminary FTP security extensions. Supports
authentication and encryption of data.  Fall backs to the old
FTP-protocol if the server does not support the extensions, can
therefore replace the ftp client.

@unnumberedsubsec kadmin
@pindex kadmin

The administrative interface to the kerberos database.  Can be used to
set passwords and add, delete, and examine principals in the
kerberos database.

@unnumberedsubsec kauth
@pindex kauth

The catch-all program.  Obtains kerberos tickets (and AFS tokens, if the
machine is running AFS), either with a password from the user or from a
key file.  Can obtain tickets on this host and remote hosts.

@unnumberedsubsec kdestroy
@pindex kdestroy

Destroys the tickets (and AFS tokens).

@unnumberedsubsec kinit
@pindex kinit

Obtains a ticket granting ticket.

@unnumberedsubsec klist
@pindex klist

Shows the current list of tickets.

@unnumberedsubsec kpasswd
@pindex kpasswd

To change kerberos passwords, you have to supply your current
password. Administrators can use @code{kadmin} to change someone
else's password.

@unnumberedsubsec kstring2key
@pindex kstring2key

Does a @code{string2key} on a given string.  Mostly useful when trying
to interface with AFS.

@unnumberedsubsec kx
@pindex kx

Supports the forwarding of X-sessions over encrypted connections.

@unnumberedsubsec login
@pindex login

The program used by @code{rlogind} and @code{telnetd} to login the user
once they have been verified.  Uses kerberos for the user verification,
but with fall back to standard unix passwords.

@unnumberedsubsec mk_cmds
@pindex mk_cmds

Only used during the build process.

@unnumberedsubsec pagsh
@pindex pagsh

Runs a command (or shell) with a new setting of the @code{KRBTKFILE}
variable (and AFS-pag).  The usefulness is mainly when you want to
acquire tickets (and AFS-tokens) as somebody else without destroying
your existing ones.

@unnumberedsubsec rcp
@pindex rcp

A client for the remote copy protocol, both kerberised and non-kerberised.

@unnumberedsubsec rlogin
@pindex rlogin

A client for the rlogin protocol, both kerberised and non-kerberised.

@unnumberedsubsec rsh
@pindex rsh

A client for the remote shell protocol, both kerberised and non-kerberised.

@unnumberedsubsec telnet
@pindex telnet

A telnet-client that supports kerberos authentication and encryption of
sessions.  The @file{.telnetrc} can be used to set the defaults of how
it should behave.  Fall backs to non-authenticated protocol and can
replace the old telnet client.

@unnumberedsubsec xnlock
@pindex xnlock

A X-based screenlocker with support for checking the password with
kerberos.  Also tries to obtain new tickets (and AFS-tokens) when
unlocking the screen.

@unnumberedsubsec zrefresh
@pindex zrefresh

A place-holder to be called from @code{xnlock} and @code{kauth}.  Should
@cindex Zephyr
be replaced with the real program when using Zephyr.

@node System administrator programs, Daemons, User programs, Programs
@section System administrator programs

The programs normally only used by the system administrator are located
in @file{/usr/athena/sbin}.

@unnumberedsubsec ext_srvtab
@pindex ext_srvtab

A program to extract given keys from the kerberos database and create a
srvtab.  Must be run on the kerberos server.

@unnumberedsubsec kdb_destroy
@pindex kdb_destroy

Destroy the existing kerberos database.

@unnumberedsubsec kdb_edit
@pindex kdb_edit

Edit the kerberos database directly on the kerberos server.  The way to
bootstrap entries into the kerberos database before @code{kadmind} is
started.

@unnumberedsubsec kdb_init
@pindex kdb_init

Create an initial kerberos database.

@unnumberedsubsec kdb_util
@pindex kdb_util

Read and write the kerberos database in ascii format.  Mainly used when
propagating the database to slave servers.

@unnumberedsubsec ksrvutil
@pindex ksrvutil

A general program for examining and updating srvtabs.

@unnumberedsubsec kstash
@pindex kstash

Store the kerberos masterkey in a file.

@node Daemons,  , System administrator programs, Programs
@section Daemons

And daemons, the programs that are not started by any human being are
relegated to @file{/usr/athena/libexec}.

@unnumberedsubsec ftpd
@pindex ftpd

The FTP daemon.  Supports anonymous and kerberos authenticated ftp.

@unnumberedsubsec kadmind
@pindex kadmind

The adminstrative interface to the kerberos database.  This daemon is
the one that performs update to the kerberos database.

@unnumberedsubsec kauthd
@pindex kauthd

The daemon that must run on a host for @code{kauth} to be able to get
remote tickets there.

@unnumberedsubsec kerberos
@pindex kerberos

The kerberos daemon that is in charge of handling out tickets.

@unnumberedsubsec popper
@pindex popper

Talks the POP3 and the KPOP protocol for fetching electronic mail.

@unnumberedsubsec kprop
@pindex kprop

The program for pushing the kerberos database from the master server to
the slave servers.

@unnumberedsubsec kpropd
@pindex kpropd

The program that receives the database from @code{kprop}.

@unnumberedsubsec kxd
@pindex kxd

The server that @code{kx} talks to when forwarding X-connections.

@unnumberedsubsec movemail
@pindex movemail

A program used by emacs and others for fetching electronic mail with the
KPOP protocol.

@unnumberedsubsec rlogind
@pindex rlogind

Talks the kerberised rlogin (with or without encryption) and the normal
``rlogin'' protocol.

@unnumberedsubsec rshd
@pindex rshd

The server for kerberised and classical ``rsh'' and ``rcp''.

@unnumberedsubsec telnetd
@pindex telnetd

The daemon that responds to the telnet protocol.

@node Resolving frequent problems, Bypassing kerberos (what you should not do), Programs, Top
@chapter Resolving frequent problems


@section Common error messages

These are some of the more obscure error messages you might encounter:

@table @asis

@item @samp{Time is out of bounds}

The time on your machine differs from the time on either the kerberos
server or the machine you are trying to login to. If it isn't obvious
that this is the case, remember that all times are compared in UTC.

On unix systems you usually can find out what the local time is by doing
@code{telnet machine daytime}. This time (again, usually is the keyword)
is with correction for timezone and daylight savings.

If you have problem keeping your clocks syncronized, consider using a
time keeping system such as NTP.

@item @samp{Ticket issue date too far in the future}

The time on the kerberos server is more than five minutes ahead of the
time on the server.

@item @samp{Can't decode authenticator}

This means that either:
@itemize @bullet
@item
the server couldn't find a service key matching the request
@item
the service key does not match the key the packet was encrypted with
@end itemize

@item @samp{Incorrect network address}

The address in the ticket does not match the address you sent the
request from. This happens on systems with more than one network
address, either physically or logically. You can list addresses which
should be considered equal in @file{/etc/krb.equiv} on your servers. 

A note to programmers: a server should not pass @samp{*} as the instance
to @samp{krb_rd_req}. It should try to figure out on which interface the
request was sent, for instnce by using @samp{k_getsockinst}.

If you change addresses on your computer you invalidate any tickets you
might have. The easiest way to fix this is to get new tickets with the
new address.

@item @samp{Message integrity error}

The packet is broken in some way:
@itemize @bullet
@item
the lengths does not match the size of the packes, or
@item
the checksum does not match the contents of the packet
@end itemize

@item @samp{Can't send request}
There is some problem contacting the kerberos server. Either the server
is down, or it is using the wrong port (compare the entries for
@samp{kerberos} in @file{/etc/services}). The client might also have
failed to guess what kerberos server to talk to (check
@file{/etc/krb.conf} and @file{/etc/krb.realms}).

@item @samp{Generic kerberos error}
This is a generic catch-all error message.

@end table


@node Bypassing kerberos (what you should not do), Concept Index, Resolving frequent problems, Top
@chapter Bypassing kerberos (what you should not do)

@node Concept Index,  , Bypassing kerberos (what you should not do), Top
@comment  node-name,  next,  previous,  up
@unnumbered Concept Index

@printindex cp

@c @shortcontents
@contents
@bye
