\input texinfo @c -*-texinfo-*-
@c Note: the above texinfo file must include the "doubleleftarrow"
@c definitions added by jcb.
@c %**start of header
@c guide
@setfilename krb425.info
@settitle Upgrading to Kerberos V5 from Kerberos V4
@setchapternewpage odd                  @c chapter begins on next odd page
@c @setchapternewpage on                   @c chapter begins on next page
@c @smallbook                              @c Format for 7" X 9.25" paper
@c %**end of header

@paragraphindent 0
@iftex
@parskip 6pt plus 6pt
@end iftex

@include definitions.texinfo
@set EDITION 1.0
@set UPDATED October 8, 1996

@finalout                               @c don't print black warning boxes

@titlepage
@title Upgrading to @value{PRODUCT} from Kerberos V4
@subtitle Release:  @value{RELEASE}
@subtitle Document Edition:  @value{EDITION}
@subtitle Last updated:  @value{UPDATED}
@author @value{COMPANY}

@page
@vskip 0pt plus 1filll

@include copyright.texinfo
@end titlepage

@node Top, Copyright, (dir), (dir)

@ifinfo
This document describes how to convert to @value{PRODUCT} from Kerberos V4.

@menu
* Copyright::                   
* Introduction::                
* Configuration Files::         
* Upgrading KDCs::              
* Upgrading Application Servers::  
* Upgrading Client machines::   
* Firewall Considerations::     
@end menu

@node Copyright, Introduction, Top, Top
@unnumbered Copyright
@include copyright.texinfo

@end ifinfo

@node Introduction, Configuration Files, Copyright, Top
@chapter Introduction

As with most software upgrades, @value{PRODUCT} is generally backward
compatible but not necessarily forward compatible.  The @value{PRODUCT}
daemons can interoperate with Kerberos V4 clients, but most of the
Kerberos V4 daemons can not interoperate with Kerberos V5 clients.  This
suggests the following strategy for performing the upgrade:

@enumerate
@item
@strong{Upgrade your KDCs.}  This is must be done first, so that
interactions with the Kerberos database, whether by Kerberos V5 clients
or by Kerberos V4 clients, will succeed.

@item
@strong{Upgrade your servers.}  This must be done before upgrading
client machines, so that the servers are able to respond to both
Kerberos V5 and Kerberos V4 queries.

@item
@strong{Upgrade your client machines.}  Do this only after your KDCs and
application servers are upgraded, so that all of your Kerberos V5
clients will be talking to Kerberos V5 daemons.
@end enumerate

@node Configuration Files, Upgrading KDCs, Introduction, Top
@chapter Configuration Files

The Kerberos @code{krb5.conf} and KDC @code{kdc.conf} configuration
files allow additional tags for Kerberos V4 compatibility.

@menu
* krb5.conf::                   
* kdc.conf::                    
@end menu

@node krb5.conf, kdc.conf, Configuration Files, Configuration Files
@section krb5.conf

If you used the defaults, both when you installed Kerberos V4 and when
you installed @value{PRODUCT}, you should not need to include any of
these tags.  However, some or all of them may be necessary for
nonstandard installations.

@menu
* libdefaults::                 
* realms (krb5.conf)::          
@end menu

@node libdefaults, realms (krb5.conf), krb5.conf, krb5.conf
@subsection [libdefaults]

In the [libdefaults] section, the following additional tags may be used:

@table @b
@item krb4_srvtab
Specifies the location of the Kerberos V4 srvtab file.  Default is
@code{/etc/srvtab}.

@item krb4_config
Specifies the location of the Kerberos V4 configuration file.  Default
is @code{/etc/krb.conf}.

@item krb4_realms
Specifies the location of the Kerberos V4 domain/realm translation
file.  Default is @code{/etc/krb.realms}.
@end table

@node realms (krb5.conf),  , libdefaults, krb5.conf
@subsection [realms]

In the [realms] section, the following Kerberos V4 tags may be used:
@table @b
@itemx default_domain
Identifies the default domain for hosts in this realm.  This is needed
for translating V4 principal names (which do not contain a domain name)
to V5 principal names.  The default is your Kerberos realm name,
converted to lower case.

@itemx v4_instance_convert
This subsection allows the administrator to configure exceptions to the
default_domain mapping rule.  It contains V4 instances (tag name) which
should be translated to some specific hostname (tag value) as the second
component in a Kerberos V5 principal name.

@itemx v4_realm
This relation allows the administrator to configure a different
realm name to be used when converting V5 principals to V4
ones.  This should only be used when running separate V4 and V5
realms, with some external means of password sychronization
between the realms.

@end table

@node kdc.conf,  , krb5.conf, Configuration Files
@section kdc.conf

Because Kerberos V4 requires a different type of salt for the encryption
type, you will need to change the @code{supported_enctypes} line in the
[realms] section to:

@smallexample
supported_enctypes = des-cbc-crc:normal des-cbc-crc:v4
@end smallexample

This is the only change needed to the @code{kdc.conf} file.

@node Upgrading KDCs, Upgrading Application Servers, Configuration Files, Top
@chapter Upgrading KDCs

To convert your KDCs from Kerberos V4 to @value{PRODUCT}, do the
following:

@enumerate
@item
Install @value{PRODUCT} on each KDC, according to the instructions in
the @value{PRODUCT} Installation Guide, up to the point where it tells
you to create the database.

@item
Find the @code{kadmind} (V4) daemon process on the master KDC and kill
it.  This will prevent changes to the Kerberos database while you
convert the database to the new Kerberos V5 format.

@item
Create a dump of the V4 database in the directory where your V5 database
will reside by issuing the command:

@smallexample
% kdb_util dump @value{ROOTDIR}/var/krb5kdc/v4-dump
@end smallexample

@item
Load the V4 dump into a Kerberos V5 database, by issuing the command:

@smallexample
% kdb5_util load_v4 v4-dump
@end smallexample

@item
Create a Kerberos V5 stash file, if desired, by issuing the command:

@smallexample
% kdb5_util stash
@end smallexample

@item
Proceed with the rest of the @value{PRODUCT} installation as described
in the @value{PRODUCT} Installation Guide.  When you get to the section
that tells you to start the @code{krb5kdc} and @code{kadmind} daemons,
first find and kill the Kerberos V4 @code{kerberos} daemon on each of
the KDCs.  Then start the @code{krb5kdc} and @code{kadmind} daemons as
directed.  Finally, start the Kerberos V5 to V4 ticket translator
daemon, @code{krb524d}, by issuing the command:

@smallexample
% @value{ROOTDIR}/sbin/krb524d -m > /dev/null &
@end smallexample

If you have a stash file and you start the @code{krb5kdc} and
@code{kadmind} daemons at boot time, you should add the above line to
your @code{/etc/rc} (or @code{/etc/rc.local}) file on each KDC.
@end enumerate

@node Upgrading Application Servers, Upgrading Client machines, Upgrading KDCs, Top
@chapter Upgrading Application Servers

Install @value{PRODUCT} on each application server, according to the
instructions in the @value{PRODUCT} Installation Guide, with the
following exceptions:

@itemize @bullet
@item
In the file @code{/etc/services}, add or edit the lines described in the
@value{PRODUCT} Installation Guide, with the following exception:

in place of:

@smallexample
@group
kerberos      88/udp    kdc    # Kerberos V5 KDC
kerberos      88/tcp    kdc    # Kerberos V5 KDC
@end group
@end smallexample

@noindent
add instead:

@smallexample
@group
kerberos-sec  88/udp    kdc    # Kerberos V5 KDC
kerberos-sec  88/tcp    kdc    # Kerberos V5 KDC
@end group
@end smallexample

@item
In the file @code{/etc/inetd.conf}, for a @emph{secure} server, instead
of making the changes described in the @value{PRODUCT} Installation
Guide, do the following:

Find and comment out any lines for the services @code{ftp},
@code{telnet}, @code{shell}, @code{login}, and @code{exec}.

@need 1800
Add the following lines.  (Note:  each line beginning with @result{} is
a continuation of the previous line.)

@smallexample
@group
klogin  stream  tcp  nowait  root
@result{}    @value{ROOTDIR}/sbin/klogind  klogind -k -c
eklogin stream  tcp  nowait  root
n@result{}   @value{ROOTDIR}/sbin/klogind  klogind -k -c -e
kshell  stream  tcp  nowait  root
@result{}    @value{ROOTDIR}/sbin/kshd  kshd -k -c -A
ftp     stream  tcp  nowait  root
@result{}    @value{ROOTDIR}/sbin/ftpd  ftpd -a
telnet  stream  tcp  nowait  root
@result{}    @value{ROOTDIR}/sbin/telnetd  telnetd -a valid
@end group
@end smallexample

@ifset CYGNUS
@strong{N.B.}:  As noted in the @value{PRODUCT} Installation Guide, if
you have some clients running older versions of Kerberos V5 (beta
6@footnote{@value{PRODUCT} is based on the MIT beta 7 release.} or
earlier), checksums were done differently in those versions, which will
cause authentication to fail.  To get around this problem, have the
@code{klogind} and @code{kshd} daemons ignore checksums, by replacing
each @code{-c} flag above with @code{-i}.
@end ifset
@ifclear CYGNUS
@strong{N.B.}: As noted in the @value{PRODUCT} Installation Guide, if
you have some clients running older versions of Kerberos V5 (beta 6 or
earlier), checksums were done differently in those versions, which will
cause authentication to fail.  To get around this problem, have the
@code{klogind} and @code{kshd} daemons ignore checksums, by replacing
each @code{-c} flag above with @code{-i}.
@end ifclear

For an @emph{insecure} server, make the changes described in the
@value{PRODUCT} Installation Guide.

When you make changes to @code{inetd.conf}, remember to @code{kill -HUP}
the @code{inetd} process to cause the changes to take effect.

@item
Convert your Kerberos V4 srvtab file to Kerberos V5 keytab file as
follows:

@smallexample
@group
@b{#} @value{ROOTDIR}/sbin/ktutil
@b{ktutil:}  rst /etc/krb-srvtab
@b{ktutil:}  wkt /etc/krb5.keytab
@b{ktutil:}  q
@b{#}
@end group
@end smallexample
@end itemize

@node Upgrading Client machines, Firewall Considerations, Upgrading Application Servers, Top
@chapter Upgrading Client machines

Install @value{PRODUCT} on each client machine, according to the
instructions in the @value{PRODUCT} Installation Guide.

Tell your users to add the appropriate directory to their paths.  On
UNIX machines, this will probably be @code{@value{BINDIR}}.

Note that if you upgrade your client machines before all of your
application servers are upgraded, your users will need to use the
Kerberos V4 programs to connect to application servers that are still
running Kerberos V4.  (The one exception is the UNIX version of
@value{PRODUCT} telnet, which can connect to a Kerberos V4 and Kerberos
V5 application servers.)  Users can use either the Kerberos V4 or
@value{PRODUCT} programs to connect to Kerberos V5 servers.

@node Firewall Considerations,  , Upgrading Client machines, Top
@chapter Firewall Considerations

@value{PRODUCT} uses port 88, which is the port assigned by the IETF,
for KDC requests.  Kerberos V4 used port 750.  If your users will need
to get to any KDCs outside your firewall, you will need to allow TCP and
UDP requests on port 88 for your users to get to off-site Kerberos V5
KDCs, and on port 750 for your users to get to off-site Kerberos V4
KDCs.

@contents
@c second page break makes sure right-left page alignment works right
@c with a one-page toc, even though we don't have setchapternewpage odd.
@c end of texinfo file
@bye