crypto/heimdal-0.6.3/lib/krb5/krb5.conf.5

   1 .\" Copyright (c) 1999 - 2004 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" 3. Neither the name of the Institute nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Id: krb5.conf.5,v 1.35.2.2 2004/03/09 19:52:07 lha Exp $
  33 .\"
  34 .Dd March  9, 2004
  35 .Dt KRB5.CONF 5
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5.conf
  39 .Nd configuration file for Kerberos 5
  40 .Sh SYNOPSIS
  41 .In krb5.h
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 file specifies several configuration parameters for the Kerberos 5
  46 library, as well as for some programs.
  47 .Pp
  48 The file consists of one or more sections, containing a number of
  49 bindings.
  50 The value of each binding can be either a string or a list of other
  51 bindings.
  52 The grammar looks like:
  53 .Bd -literal -offset indent
  54 file:
  55         /* empty */
  56         sections
  57
  58 sections:
  59         section sections
  60         section
  61
  62 section:
  63         '[' section_name ']' bindings
  64
  65 section_name:
  66         STRING
  67
  68 bindings:
  69         binding bindings
  70         binding
  71
  72 binding:
  73         name '=' STRING
  74         name '=' '{' bindings '}'
  75
  76 name:
  77         STRING
  78
  79 .Ed
  80 .Li STRINGs
  81 consists of one or more non-whitespace characters.
  82 .Pp
  83 STRINGs that are specified later in this man-page uses the following
  84 notation.
  85 .Bl -tag -width "xxx" -offset indent
  86 .It boolean
  87 values can be either yes/true or no/false.
  88 .It time
  89 values can be a list of year, month, day, hour, min, second.
  90 Example: 1 month 2 days 30 min.
  91 .It etypes
  92 valid encryption types are: des-cbc-crc, des-cbc-md4, des-cbc-md5,
  93 des3-cbc-sha1, arcfour-hmac-md5, aes128-cts-hmac-sha1-96, and
  94 aes256-cts-hmac-sha1-96 .
  95 .It address
  96 an address can be either a IPv4 or a IPv6 address.
  97 .El
  98 .Pp
  99 Currently recognised sections and bindings are:
 100 .Bl -tag -width "xxx" -offset indent
 101 .It Li [appdefaults]
 102 Specifies the default values to be used for Kerberos applications.
 103 You can specify defaults per application, realm, or a combination of
 104 these.
 105 The preference order is:
 106 .Bl -enum -compact
 107 .It
 108 .Va application Va realm Va option
 109 .It
 110 .Va application Va option
 111 .It
 112 .Va realm Va option
 113 .It
 114 .Va option
 115 .El
 116 .Pp
 117 The supported options are:
 118 .Bl -tag -width "xxx" -offset indent
 119 .It Li forwardable = Va boolean
 120 When obtaining initial credentials, make the credentials forwardable.
 121 .It Li proxiable = Va boolean
 122 When obtaining initial credentials, make the credentials proxiable.
 123 .It Li no-addresses = Va boolean
 124 When obtaining initial credentials, request them for an empty set of
 125 addresses, making the tickets valid from any address.
 126 .It Li ticket_lifetime = Va time
 127 Default ticket lifetime.
 128 .It Li renew_lifetime = Va time
 129 Default renewable ticket lifetime.
 130 .It Li encrypt = Va boolean
 131 Use encryption, when available.
 132 .It Li forward = Va boolean
 133 Forward credentials to remote host (for
 134 .Xr rsh 1 ,
 135 .Xr telnet 1 ,
 136 etc).
 137 .El
 138 .It Li [libdefaults]
 139 .Bl -tag -width "xxx" -offset indent
 140 .It Li default_realm = Va REALM
 141 Default realm to use, this is also known as your
 142 .Dq local realm .
 143 The default is the result of
 144 .Fn krb5_get_host_realm "local hostname" .
 145 .It Li clockskew = Va time
 146 Maximum time differential (in seconds) allowed when comparing
 147 times.
 148 Default is 300 seconds (five minutes).
 149 .It Li kdc_timeout = Va time
 150 Maximum time to wait for a reply from the kdc, default is 3 seconds.
 151 .It v4_name_convert
 152 .It v4_instance_resolve
 153 These are described in the
 154 .Xr krb5_425_conv_principal  3
 155 manual page.
 156 .It Li capath = {
 157 .Bl -tag -width "xxx" -offset indent
 158 .It Va destination-realm Li = Va next-hop-realm
 159 .It ...
 160 .It Li }
 161 .El
 162 This is deprecated, see the
 163 .Li capaths
 164 section below.
 165 .It Li default_etypes = Va etypes ...
 166 A list of default encryption types to use.
 167 .It Li default_etypes_des = Va etypes ...
 168 A list of default encryption types to use when requesting a DES credential.
 169 .It Li default_keytab_name = Va keytab
 170 The keytab to use if no other is specified, default is
 171 .Dq FILE:/etc/krb5.keytab .
 172 .It Li dns_lookup_kdc = Va boolean
 173 Use DNS SRV records to lookup KDC services location.
 174 .It Li dns_lookup_realm = Va boolean
 175 Use DNS TXT records to lookup domain to realm mappings.
 176 .It Li kdc_timesync = Va boolean
 177 Try to keep track of the time differential between the local machine
 178 and the KDC, and then compensate for that when issuing requests.
 179 .It Li max_retries = Va number
 180 The max number of times to try to contact each KDC.
 181 .It Li ticket_lifetime = Va time
 182 Default ticket lifetime.
 183 .It Li renew_lifetime = Va time
 184 Default renewable ticket lifetime.
 185 .It Li forwardable = Va boolean
 186 When obtaining initial credentials, make the credentials forwardable.
 187 This option is also valid in the [realms] section.
 188 .It Li proxiable = Va boolean
 189 When obtaining initial credentials, make the credentials proxiable.
 190 This option is also valid in the [realms] section.
 191 .It Li verify_ap_req_nofail = Va boolean
 192 If enabled, failure to verify credentials against a local key is a
 193 fatal error.
 194 The application has to be able to read the corresponding service key
 195 for this to work.
 196 Some applications, like
 197 .Xr su 1 ,
 198 enable this option unconditionally.
 199 .It Li warn_pwexpire = Va time
 200 How soon to warn for expiring password.
 201 Default is seven days.
 202 .It Li http_proxy = Va proxy-spec
 203 A HTTP-proxy to use when talking to the KDC via HTTP.
 204 .It Li dns_proxy = Va proxy-spec
 205 Enable using DNS via HTTP.
 206 .It Li extra_addresses = Va address ...
 207 A list of addresses to get tickets for along with all local addresses.
 208 .It Li time_format = Va string
 209 How to print time strings in logs, this string is passed to
 210 .Xr strftime 3 .
 211 .It Li date_format = Va string
 212 How to print date strings in logs, this string is passed to
 213 .Xr strftime 3 .
 214 .It Li log_utc = Va boolean
 215 Write log-entries using UTC instead of your local time zone.
 216 .It Li scan_interfaces = Va boolean
 217 Scan all network interfaces for addresses, as opposed to simply using
 218 the address associated with the system's host name.
 219 .It Li fcache_version = Va int
 220 Use file credential cache format version specified.
 221 .It Li krb4_get_tickets = Va boolean
 222 Also get Kerberos 4 tickets in
 223 .Nm kinit ,
 224 .Nm login ,
 225 and other programs.
 226 This option is also valid in the [realms] section.
 227 .It Li fcc-mit-ticketflags = Va boolean
 228 Use MIT compatible format for file credential cache.
 229 It's the field ticketflags that is stored in reverse bit order for
 230 older than Heimdal 0.7.
 231 Setting this flag to
 232 .Dv TRUE
 233 make it store the MIT way, this is default for Heimdal 0.7.
 234 .El
 235 .It Li [domain_realm]
 236 This is a list of mappings from DNS domain to Kerberos realm.
 237 Each binding in this section looks like:
 238 .Pp
 239 .Dl domain = realm
 240 .Pp
 241 The domain can be either a full name of a host or a trailing
 242 component, in the latter case the domain-string should start with a
 243 period.
 244 The realm may be the token `dns_locate', in which case the actual
 245 realm will be determined using DNS (independently of the setting
 246 of the `dns_lookup_realm' option).
 247 .It Li [realms]
 248 .Bl -tag -width "xxx" -offset indent
 249 .It Va REALM Li = {
 250 .Bl -tag -width "xxx" -offset indent
 251 .It Li kdc = Va [service/]host[:port]
 252 Specifies a list of kdcs for this realm.
 253 If the optional
 254 .Va port
 255 is absent, the
 256 default value for the
 257 .Dq kerberos/udp
 258 .Dq kerberos/tcp ,
 259 and
 260 .Dq http/tcp
 261 port (depending on service) will be used.
 262 The kdcs will be used in the order that they are specified.
 263 .Pp
 264 The optional
 265 .Va service
 266 specifies over what medium the kdc should be
 267 contacted.
 268 Possible services are
 269 .Dq udp ,
 270 .Dq tcp ,
 271 and
 272 .Dq http .
 273 Http can also be written as
 274 .Dq http:// .
 275 Default service is
 276 .Dq udp
 277 and
 278 .Dq tcp .
 279 .It Li admin_server = Va host[:port]
 280 Specifies the admin server for this realm, where all the modifications
 281 to the database are performed.
 282 .It Li kpasswd_server = Va host[:port]
 283 Points to the server where all the password changes are performed.
 284 If there is no such entry, the kpasswd port on the admin_server host
 285 will be tried.
 286 .It Li krb524_server = Va host[:port]
 287 Points to the server that does 524 conversions.
 288 If it is not mentioned, the krb524 port on the kdcs will be tried.
 289 .It Li v4_instance_convert
 290 .It Li v4_name_convert
 291 .It Li default_domain
 292 See
 293 .Xr krb5_425_conv_principal 3 .
 294 .It Li tgs_require_subkey
 295 a boolan variable that defaults to false.
 296 Old DCE secd (pre 1.1) might need this to be true.
 297 .El
 298 .It Li }
 299 .El
 300 .It Li [capaths]
 301 .Bl -tag -width "xxx" -offset indent
 302 .It Va client-realm Li = {
 303 .Bl -tag -width "xxx" -offset indent
 304 .It Va server-realm Li = Va hop-realm ...
 305 This serves two purposes. First the first listed
 306 .Va hop-realm
 307 tells a client which realm it should contact in order to ultimately
 308 obtain credentials for a service in the
 309 .Va server-realm .
 310 Secondly, it tells the KDC (and other servers) which realms are
 311 allowed in a multi-hop traversal from
 312 .Va client-realm
 313 to
 314 .Va server-realm .
 315 Except for the client case, the order of the realms are not important.
 316 .El
 317 .It Va }
 318 .El
 319 .It Li [logging]
 320 .Bl -tag -width "xxx" -offset indent
 321 .It Va entity Li = Va destination
 322 Specifies that
 323 .Va entity
 324 should use the specified
 325 .Li destination
 326 for logging.
 327 See the
 328 .Xr krb5_openlog 3
 329 manual page for a list of defined destinations.
 330 .El
 331 .It Li [kdc]
 332 .Bl -tag -width "xxx" -offset indent
 333 .It database Li = {
 334 .Bl -tag -width "xxx" -offset indent
 335 .It dbname Li = Va DATABASENAME
 336 Use this database for this realm.
 337 .It realm Li = Va REALM
 338 Specifies the realm that will be stored in this database.
 339 .It mkey_file Li = Pa FILENAME
 340 Use this keytab file for the master key of this database.
 341 If not specified
 342 .Va DATABASENAME Ns .mkey
 343 will be used.
 344 .It acl_file Li = PA FILENAME
 345 Use this file for the ACL list of this database.
 346 .It log_file Li = Pa FILENAME
 347 Use this file as the log of changes performed to the database.
 348 This file is used by
 349 .Nm ipropd-master
 350 for propagating changes to slaves.
 351 .El
 352 .It Li }
 353 .It max-request = Va SIZE
 354 Maximum size of a kdc request.
 355 .It require-preauth = Va BOOL
 356 If set pre-authentication is required.
 357 Since krb4 requests are not pre-authenticated they will be rejected.
 358 .It ports = Va "list of ports"
 359 List of ports the kdc should listen to.
 360 .It addresses = Va "list of interfaces"
 361 List of addresses the kdc should bind to.
 362 .It enable-kerberos4 = Va BOOL
 363 Turn on Kerberos 4 support.
 364 .It v4-realm = Va REALM
 365 To what realm v4 requests should be mapped.
 366 .It enable-524 = Va BOOL
 367 Should the Kerberos 524 converting facility be turned on.
 368 Default is same as
 369 .Va enable-kerberos4 .
 370 .It enable-http = Va BOOL
 371 Should the kdc answer kdc-requests over http.
 372 .It enable-kaserver = Va BOOL
 373 If this kdc should emulate the AFS kaserver.
 374 .It check-ticket-addresses = Va BOOL
 375 verify the addresses in the tickets used in tgs requests.
 376 .\" XXX
 377 .It allow-null-ticket-addresses = Va BOOL
 378 Allow addresses-less tickets.
 379 .\" XXX
 380 .It allow-anonymous = Va BOOL
 381 If the kdc is allowed to hand out anonymous tickets.
 382 .It encode_as_rep_as_tgs_rep = Va BOOL
 383 Encode as-rep as tgs-rep tobe compatible with mistakes older DCE secd did.
 384 .\" XXX
 385 .It kdc_warn_pwexpire = Va TIME
 386 The time before expiration that the user should be warned that her
 387 password is about to expire.
 388 .It logging = Va Logging
 389 What type of logging the kdc should use, see also [logging]/kdc.
 390 .It use_2b = Va principal list
 391 List of principals to use AFS 2b tokens for.
 392 .El
 393 .It Li [kadmin]
 394 .Bl -tag -width "xxx" -offset indent
 395 .It require-preauth = Va BOOL
 396 If pre-authentication is required to talk to the kadmin server.
 397 .It default_keys = Va keytypes...
 398 for each entry in
 399 .Va default_keys
 400 try to parse it as a sequence of
 401 .Va etype:salttype:salt
 402 syntax of this if something like:
 403 .Pp
 404 [(des|des3|etype):](pw-salt|afs3-salt)[:string]
 405 .Pp
 406 If
 407 .Ar etype
 408 is omitted it means everything, and if string is omitted it means the
 409 default salt string (for that principal and encryption type).
 410 Additional special values of keytypes are:
 411 .Bl -tag -width "xxx" -offset indent
 412 .It v5
 413 The Kerberos 5 salt
 414 .Va pw-salt
 415 .It v4
 416 The Kerberos 4 salt
 417 .Va des:pw-salt:
 418 .El
 419 .It use_v4_salt = Va BOOL
 420 When true, this is the same as
 421 .Pp
 422 .Va default_keys = Va des3:pw-salt Va v4
 423 .Pp
 424 and is only left for backwards compatibility.
 425 .El
 426 .El
 427 .Sh ENVIRONMENT
 428 .Ev KRB5_CONFIG
 429 points to the configuration file to read.
 430 .Sh FILES
 431 .Bl -tag -width "/etc/krb5.conf"
 432 .It Pa /etc/krb5.conf
 433 configuration file for Kerberos 5.
 434 .El
 435 .Sh EXAMPLES
 436 .Bd -literal -offset indent
 437 [libdefaults]
 438         default_realm = FOO.SE
 439 [domain_realm]
 440         .foo.se = FOO.SE
 441         .bar.se = FOO.SE
 442 [realms]
 443         FOO.SE = {
 444                 kdc = kerberos.foo.se
 445                 v4_name_convert = {
 446                         rcmd = host
 447                 }
 448                 v4_instance_convert = {
 449                         xyz = xyz.bar.se
 450                 }
 451                 default_domain = foo.se
 452         }
 453 [logging]
 454         kdc = FILE:/var/heimdal/kdc.log
 455         kdc = SYSLOG:INFO
 456         default = SYSLOG:INFO:USER
 457 .Ed
 458 .Sh DIAGNOSTICS
 459 Since
 460 .Nm
 461 is read and parsed by the krb5 library, there is not a lot of
 462 opportunities for programs to report parsing errors in any useful
 463 format.
 464 To help overcome this problem, there is a program
 465 .Nm verify_krb5_conf
 466 that reads
 467 .Nm
 468 and tries to emit useful diagnostics from parsing errors.
 469 Note that this program does not have any way of knowing what options
 470 are actually used and thus cannot warn about unknown or misspelled
 471 ones.
 472 .Sh SEE ALSO
 473 .Xr kinit 1 ,
 474 .Xr krb5_425_conv_principal 3 ,
 475 .Xr krb5_openlog 3 ,
 476 .Xr strftime 3 ,
 477 .Xr verify_krb5_conf 8