doc/krb425.texinfo

   1 \input texinfo @c -*-texinfo-*-
   2 @c Note: the above texinfo file must include the "doubleleftarrow"
   3 @c definitions added by jcb.
   4 @c %**start of header
   5 @c guide
   6 @setfilename krb425.info
   7 @settitle Upgrading to Kerberos V5 from Kerberos V4
   8 @c @setchapternewpage odd                  @c chapter begins on next odd page
   9 @c @setchapternewpage on                   @c chapter begins on next page
  10 @c @smallbook                              @c Format for 7" X 9.25" paper
  11 @c %**end of header
  12
  13 @paragraphindent 0
  14 @iftex
  15 @parskip 6pt plus 6pt
  16 @end iftex
  17
  18 @dircategory Kerberos
  19 @direntry
  20 * krb425: (krb425).                     Upgrading to Kerberos V5 from V4
  21 @end direntry
  22
  23 @include definitions.texinfo
  24 @set EDITION 1.0
  25 @set UPDATED May 22, 2003
  26
  27 @finalout                               @c don't print black warning boxes
  28
  29 @titlepage
  30 @title Upgrading to @value{PRODUCT} from Kerberos V4
  31 @subtitle Release:  @value{RELEASE}
  32 @subtitle Document Edition:  @value{EDITION}
  33 @subtitle Last updated:  @value{UPDATED}
  34 @author @value{COMPANY}
  35
  36 @page
  37 @vskip 0pt plus 1filll
  38
  39 @end titlepage
  40
  41 @node Top, Copyright, (dir), (dir)
  42
  43 @ifinfo
  44 This document describes how to convert to @value{PRODUCT} from Kerberos V4.
  45 @end ifinfo
  46
  47 @menu
  48 * Copyright::
  49 * Introduction::
  50 * Configuration Files::
  51 * Upgrading KDCs::
  52 * Upgrading Application Servers::
  53 * Upgrading Client machines::
  54 * Firewall Considerations::
  55 @end menu
  56
  57 @node Copyright, Introduction, Top, Top
  58 @unnumbered Copyright
  59 @include copyright.texinfo
  60
  61 @node Introduction, Configuration Files, Copyright, Top
  62 @chapter Introduction
  63
  64 As with most software upgrades, @value{PRODUCT} is generally backward
  65 compatible but not necessarily forward compatible.  The @value{PRODUCT}
  66 daemons can interoperate with Kerberos V4 clients, but most of the
  67 Kerberos V4 daemons can not interoperate with Kerberos V5 clients.  This
  68 suggests the following strategy for performing the upgrade:
  69
  70 @enumerate
  71 @item
  72 @strong{Upgrade your KDCs.}  This must be done first, so that
  73 interactions with the Kerberos database, whether by Kerberos V5 clients
  74 or by Kerberos V4 clients, will succeed.
  75
  76 @item
  77 @strong{Upgrade your servers.}  This must be done before upgrading
  78 client machines, so that the servers are able to respond to both
  79 Kerberos V5 and Kerberos V4 queries.
  80
  81 @item
  82 @strong{Upgrade your client machines.}  Do this only after your KDCs and
  83 application servers are upgraded, so that all of your Kerberos V5
  84 clients will be talking to Kerberos V5 daemons.
  85 @end enumerate
  86
  87 @node Configuration Files, Upgrading KDCs, Introduction, Top
  88 @chapter Configuration Files
  89
  90 The Kerberos @code{krb5.conf} and KDC @code{kdc.conf} configuration
  91 files allow additional tags for Kerberos V4 compatibility.
  92
  93 @menu
  94 * krb5.conf::
  95 * kdc.conf::
  96 @end menu
  97
  98 @node krb5.conf, kdc.conf, Configuration Files, Configuration Files
  99 @section krb5.conf
 100
 101 If you used the defaults, both when you installed Kerberos V4 and when
 102 you installed @value{PRODUCT}, you should not need to include any of
 103 these tags.  However, some or all of them may be necessary for
 104 nonstandard installations.
 105
 106 @menu
 107 * libdefaults::
 108 * realms (krb5.conf)::
 109 * AFS and the Appdefaults Section::
 110 @end menu
 111
 112 @node libdefaults, realms (krb5.conf), krb5.conf, krb5.conf
 113 @subsection [libdefaults]
 114
 115 In the [libdefaults] section, the following additional tags may be used:
 116
 117 @table @b
 118 @item krb4_srvtab
 119 Specifies the location of the Kerberos V4 srvtab file.  Default is
 120 @value{DefaultKrb4Srvtab}.
 121
 122 @item krb4_config
 123 Specifies the location of the Kerberos V4 configuration file.  Default
 124 is @value{DefaultKrb4Config}.
 125
 126 @item krb4_realms
 127 Specifies the location of the Kerberos V4 domain/realm translation
 128 file.  Default is @value{DefaultKrb4Realms}.
 129 @end table
 130
 131 @node realms (krb5.conf), AFS and the Appdefaults Section, libdefaults, krb5.conf
 132 @subsection [realms]
 133
 134 In the [realms] section, the following Kerberos V4 tags may be used:
 135 @table @b
 136 @itemx default_domain
 137 Identifies the default domain for hosts in this realm.  This is needed
 138 for translating V4 principal names (which do not contain a domain name)
 139 to V5 principal names.  The default is your Kerberos realm name,
 140 converted to lower case.
 141
 142 @itemx v4_instance_convert
 143 This subsection allows the administrator to configure exceptions to the
 144 default_domain mapping rule.  It contains V4 instances (tag name) which
 145 should be translated to some specific hostname (tag value) as the second
 146 component in a Kerberos V5 principal name.
 147
 148 @itemx v4_realm
 149 This relation allows the administrator to configure a different
 150 realm name to be used when converting V5 principals to V4
 151 ones.  This should only be used when running separate V4 and V5
 152 realms, with some external means of password sychronization
 153 between the realms.
 154
 155 @end table
 156
 157 @node AFS and the Appdefaults Section,  , realms (krb5.conf), krb5.conf
 158 @subsection AFS and the Appdefaults Section
 159
 160 Many Kerberos 4 sites also run the Andrew File System (AFS).
 161
 162 Modern AFS servers (OpenAFS > 1.2.8) support the AFS 2b token format.
 163 This allows AFS to use Kerberos 5 tickets rather than version 4
 164 tickets, enabling cross-realm authentication.  By default, the
 165 @file{krb524d} service will issue the new AFS 2b tokens.  If you are
 166 using old AFS servers, you will need to disable these new tokens.
 167 Please see the documentation of the @code{appdefaults} section of
 168 @file{krb5.conf} in the Kerberos Administration guide.
 169
 170
 171
 172 @node kdc.conf,  , krb5.conf, Configuration Files
 173 @section kdc.conf
 174
 175 Because Kerberos V4 requires a different type of salt for the encryption
 176 type, you will need to change the @code{supported_enctypes} line in the
 177 [realms] section to:
 178
 179 @smallexample
 180 supported_enctypes = des-cbc-crc:normal des-cbc-crc:v4
 181 @end smallexample
 182
 183 This is the only change needed to the @code{kdc.conf} file.
 184
 185 @node Upgrading KDCs, Upgrading Application Servers, Configuration Files, Top
 186 @chapter Upgrading KDCs
 187
 188 To convert your KDCs from Kerberos V4 to @value{PRODUCT}, do the
 189 following:
 190
 191 @enumerate
 192 @item
 193 Install @value{PRODUCT} on each KDC, according to the instructions in
 194 the @value{PRODUCT} Installation Guide, up to the point where it tells
 195 you to create the database.
 196
 197 @item
 198 Find the @code{kadmind} (V4) daemon process on the master KDC and kill
 199 it.  This will prevent changes to the Kerberos database while you
 200 convert the database to the new Kerberos V5 format.
 201
 202 @item
 203 Create a dump of the V4 database in the directory where your V5 database
 204 will reside by issuing the command:
 205
 206 @smallexample
 207 % kdb_util dump @value{ROOTDIR}/var/krb5kdc/v4-dump
 208 @end smallexample
 209
 210 @item
 211 Load the V4 dump into a Kerberos V5 database, by issuing the command:
 212
 213 @smallexample
 214 % kdb5_util load_v4 v4-dump
 215 @end smallexample
 216
 217 @item
 218 Create a Kerberos V5 stash file, if desired, by issuing the command:
 219
 220 @smallexample
 221 % kdb5_util stash
 222 @end smallexample
 223
 224 @item
 225 Proceed with the rest of the @value{PRODUCT} installation as described
 226 in the @value{PRODUCT} Installation Guide.  When you get to the section
 227 that tells you to start the @code{krb5kdc} and @code{kadmind} daemons,
 228 first find and kill the Kerberos V4 @code{kerberos} daemon on each of
 229 the KDCs.  Then start the @code{krb5kdc} and @code{kadmind} daemons as
 230 You will need to specify an argument to the @code{-4} command line option to enable Kerberos 4 compatibility.
 231 See the @code{krb5kdc} man page for details.
 232 directed.  Finally, start the Kerberos V5 to V4 ticket translator
 233 daemon, @code{krb524d}, by issuing the command:
 234
 235 @smallexample
 236 % @value{ROOTDIR}/sbin/krb524d -m > /dev/null &
 237 @end smallexample
 238
 239 If you have a stash file and you start the @code{krb5kdc} and
 240 @code{kadmind} daemons at boot time, you should add the above line to
 241 your @code{/etc/rc} (or @code{/etc/rc.local}) file on each KDC.
 242 @end enumerate
 243
 244 @node Upgrading Application Servers, Upgrading Client machines, Upgrading KDCs, Top
 245 @chapter Upgrading Application Servers
 246
 247 Install @value{PRODUCT} on each application server, according to the
 248 instructions in the @value{PRODUCT} Installation Guide, with the
 249 following exceptions:
 250
 251 @itemize @bullet
 252 @item
 253 In the file @code{/etc/services}, add or edit the lines described in the
 254 @value{PRODUCT} Installation Guide, with the following exception:
 255
 256 in place of:
 257
 258 @smallexample
 259 @group
 260 kerberos      @value{DefaultPort}/udp    kdc    # Kerberos V5 KDC
 261 kerberos      @value{DefaultPort}/tcp    kdc    # Kerberos V5 KDC
 262 @end group
 263 @end smallexample
 264
 265 @noindent
 266 add instead:
 267
 268 @smallexample
 269 @group
 270 kerberos-sec  @value{DefaultPort}/udp    kdc    # Kerberos V5 KDC
 271 kerberos-sec  @value{DefaultPort}/tcp    kdc    # Kerberos V5 KDC
 272 @end group
 273 @end smallexample
 274
 275 @item
 276 Convert your Kerberos V4 srvtab file to Kerberos V5 keytab file as
 277 follows:
 278
 279 @smallexample
 280 @group
 281 @b{#} @value{ROOTDIR}/sbin/ktutil
 282 @b{ktutil:}  rst /etc/krb-srvtab
 283 @b{ktutil:}  wkt /etc/krb5.keytab
 284 @b{ktutil:}  q
 285 @b{#}
 286 @end group
 287 @end smallexample
 288 @end itemize
 289
 290 @node Upgrading Client machines, Firewall Considerations, Upgrading Application Servers, Top
 291 @chapter Upgrading Client machines
 292
 293 Install @value{PRODUCT} on each client machine, according to the
 294 instructions in the @value{PRODUCT} Installation Guide.
 295
 296 Tell your users to add the appropriate directory to their paths.  On
 297 UNIX machines, this will probably be @code{@value{BINDIR}}.
 298
 299 Note that if you upgrade your client machines before all of your
 300 application servers are upgraded, your users will need to use the
 301 Kerberos V4 programs to connect to application servers that are still
 302 running Kerberos V4.  (The one exception is the UNIX version of
 303 @value{PRODUCT} telnet, which can connect to a Kerberos V4 and Kerberos
 304 V5 application servers.)  Users can use either the Kerberos V4 or
 305 @value{PRODUCT} programs to connect to Kerberos V5 servers.
 306
 307 @node Firewall Considerations,  , Upgrading Client machines, Top
 308 @chapter Firewall Considerations
 309
 310 @value{PRODUCT} uses port @value{DefaultPort}, which is the port
 311 assigned by the IETF, for KDC requests.  Kerberos V4 used port
 312 @value{DefaultSecondPort}.  If your users will need to get to any KDCs
 313 outside your firewall, you will need to allow TCP and UDP requests on
 314 port @value{DefaultPort} for your users to get to off-site Kerberos V5
 315 KDCs, and on port @value{DefaultSecondPort} for your users to get to
 316 off-site Kerberos V4 KDCs.
 317
 318 @contents
 319 @c second page break makes sure right-left page alignment works right
 320 @c with a one-page toc, even though we don't have setchapternewpage odd.
 321 @c end of texinfo file
 322 @bye