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

   1 .\" $Id: krb5.conf.5,v 1.25 2002/08/28 15:33:59 nectar Exp $
   2 .\"
   3 .Dd April 11, 1999
   4 .Dt KRB5.CONF 5
   5 .Os HEIMDAL
   6 .Sh NAME
   7 .Nm /etc/krb5.conf
   8 .Nd configuration file for Kerberos 5
   9 .Sh DESCRIPTION
  10 The
  11 .Nm
  12 file specifies several configuration parameters for the Kerberos 5
  13 library, as well as for some programs.
  14 .Pp
  15 The file consists of one or more sections, containing a number of
  16 bindings. The value of each binding can be either a string or a list
  17 of other bindings. The grammar looks like:
  18 .Bd -literal -offset indent
  19 file:
  20         /* empty */
  21         sections
  22
  23 sections:
  24         section sections
  25         section
  26
  27 section:
  28         '[' section_name ']' bindings
  29
  30 section_name:
  31         STRING
  32
  33 bindings:
  34         binding bindings
  35         binding
  36
  37 binding:
  38         name '=' STRING
  39         name '=' '{' bindings '}'
  40
  41 name:
  42         STRING
  43
  44 .Ed
  45 .Li STRINGs
  46 consists of one or more non-white space characters.
  47 Currently recognised sections and bindings are:
  48 .Bl -tag -width "xxx" -offset indent
  49 .It Li [appdefaults]
  50 Specifies the default values to be used for Kerberos applications.
  51 You can specify defaults per application, realm, or a combination of
  52 these.  The preference order is:
  53 .Bl -enum -compact
  54 .It
  55 .Va application Va realm Va option
  56 .It
  57 .Va application Va option
  58 .It
  59 .Va realm Va option
  60 .It
  61 .Va option
  62 .El
  63 .Pp
  64 The supported options are:
  65 .Bl -tag -width "xxx" -offset indent
  66 .It Li forwardable = Va boolean
  67 When obtaining initial credentials, make the credentials forwardable.
  68 .It Li proxiable = Va boolean
  69 When obtaining initial credentials, make the credentials proxiable.
  70 .It Li no-addresses = Va boolean
  71 When obtaining initial credentials, request them for an empty set of
  72 addresses, making the tickets valid from any address.
  73 .It Li ticket_lifetime = Va time
  74 Default ticket lifetime.
  75 .It Li renew_lifetime = Va time
  76 Default renewable ticket lifetime.
  77 .El
  78 .It Li [libdefaults]
  79 .Bl -tag -width "xxx" -offset indent
  80 .It Li default_realm = Va REALM
  81 Default realm to use, this is also known as your
  82 .Dq local realm .
  83 The default is the result of
  84 .Fn krb5_get_host_realm "local hostname" .
  85 .It Li clockskew = Va time
  86 Maximum time differential (in seconds) allowed when comparing
  87 times. Default is 300 seconds (five minutes).
  88 .It Li kdc_timeout = Va time
  89 Maximum time to wait for a reply from the kdc, default is 3 seconds.
  90 .It v4_name_convert
  91 .It v4_instance_resolve
  92 These are decribed in the
  93 .Xr krb5_425_conv_principal  3
  94 manual page.
  95 .It Li capath = {
  96 .Bl -tag -width "xxx" -offset indent
  97 .It Va destination-realm Li = Va next-hop-realm
  98 .It ...
  99 .El
 100 Normally, all requests to realms different from the one of the current
 101 client are sent to this KDC to get cross-realm tickets.
 102 If this KDC does not have a cross-realm key with the desired realm and
 103 the hierarchical path to that realm does not work, a path can be
 104 configured using this directive.
 105 The text shown above instructs the KDC to try to obtain a cross-realm
 106 ticket to
 107 .Va next-hop-realm
 108 when the desired realm is
 109 .Va destination-realm .
 110 This configuration should preferably be done on the KDC where it will
 111 help all its clients but can also be done on the client itself.
 112 .It Li }
 113 .It Li default_etypes = Va etypes...
 114 A list of default etypes to use.
 115 .It Li default_etypes_des = Va etypes...
 116 A list of default etypes to use when requesting a DES credential.
 117 .It Li default_keytab_name = Va keytab
 118 The keytab to use if none other is specified, default is
 119 .Dq FILE:/etc/krb5.keytab .
 120 .It Li dns_lookup_kdc = Va boolean
 121 Use DNS SRV records to lookup KDC services location.
 122 .It Li dns_lookup_realm = Va boolean
 123 Use DNS TXT records to lookup domain to realm mappings.
 124 .It Li kdc_timesync = Va boolean
 125 Try to keep track of the time differential between the local machine
 126 and the KDC, and then compensate for that when issuing requests.
 127 .It Li max_retries = Va number
 128 The max number of times to try to contact each KDC.
 129 .It Li ticket_lifetime = Va time
 130 Default ticket lifetime.
 131 .It Li renew_lifetime = Va time
 132 Default renewable ticket lifetime.
 133 .It Li forwardable = Va boolean
 134 When obtaining initial credentials, make the credentials forwardable.
 135 This option is also valid in the [realms] section.
 136 .It Li proxiable = Va boolean
 137 When obtaining initial credentials, make the credentials proxiable.
 138 This option is also valid in the [realms] section.
 139 .It Li verify_ap_req_nofail = Va boolean
 140 If enabled, failure to verify credentials against a local key is a
 141 fatal error. The application has to be able to read the corresponding
 142 service key for this to work. Some applications, like
 143 .Xr su 8 ,
 144 enable this option unconditionally.
 145 .It Li warn_pwexpire = Va time
 146 How soon to warn for expiring password. Default is seven days.
 147 .It Li http_proxy = Va proxy-spec
 148 A HTTP-proxy to use when talking to the KDC via HTTP.
 149 .It Li dns_proxy = Va proxy-spec
 150 Enable using DNS via HTTP.
 151 .It Li extra_addresses = Va address...
 152 A list of addresses to get tickets for along with all local addresses.
 153 .It Li time_format = Va string
 154 How to print time strings in logs, this string is passed to
 155 .Xr strftime 3 .
 156 .It Li date_format = Va string
 157 How to print date strings in logs, this string is passed to
 158 .Xr strftime 3 .
 159 .It Li log_utc = Va boolean
 160 Write log-entries using UTC instead of your local time zone.
 161 .It Li scan_interfaces = Va boolean
 162 Scan all network interfaces for addresses, as opposed to simply using
 163 the address associated with the system's host name.
 164 .It Li fcache_version = Va int
 165 Use file credential cache format version specified.
 166 .It Li krb4_get_tickets = Va boolean
 167 Also get Kerberos 4 tickets in
 168 .Nm kinit ,
 169 .Nm login ,
 170 and other programs.
 171 This option is also valid in the [realms] section.
 172 .El
 173 .It Li [domain_realm]
 174 This is a list of mappings from DNS domain to Kerberos realm. Each
 175 binding in this section looks like:
 176 .Pp
 177 .Dl domain = realm
 178 .Pp
 179 The domain can be either a full name of a host or a trailing
 180 component, in the latter case the domain-string should start with a
 181 perid.
 182 The realm may be the token `dns_locate', in which case the actual
 183 realm will be determined using DNS (independently of the setting
 184 of the `dns_lookup_realm' option).
 185 .It Li [realms]
 186 .Bl -tag -width "xxx" -offset indent
 187 .It Va REALM Li = {
 188 .Bl -tag -width "xxx" -offset indent
 189 .It Li kdc = Va host[:port]
 190 Specifies a list of kdcs for this realm. If the optional port is absent, the
 191 default value for the
 192 .Dq kerberos/udp
 193 service will be used.
 194 The kdcs will be used in the order that they are specified.
 195 .It Li admin_server = Va host[:port]
 196 Specifies the admin server for this realm, where all the modifications
 197 to the database are perfomed.
 198 .It Li kpasswd_server = Va host[:port]
 199 Points to the server where all the password changes are perfomed.
 200 If there is no such entry, the kpasswd port on the admin_server host
 201 will be tried.
 202 .It Li krb524_server = Va Host[:port]
 203 Points to the server that does 524 conversions.  If it is not
 204 mentioned, the krb524 port on the kdcs will be tried.
 205 .It Li v4_instance_convert
 206 .It Li v4_name_convert
 207 .It Li default_domain
 208 See
 209 .Xr krb5_425_conv_principal 3 .
 210 .El
 211 .It Li }
 212 .El
 213 .It Li [logging]
 214 .Bl -tag -width "xxx" -offset indent
 215 .It Va entity Li = Va destination
 216 Specifies that
 217 .Va entity
 218 should use the specified
 219 .Li destination
 220 for logging. See the
 221 .Xr krb5_openlog 3
 222 manual page for a list of defined destinations.
 223 .El
 224 .It Li [kdc]
 225 .Bl -tag -width "xxx" -offset indent
 226 .It database Li = {
 227 .Bl -tag -width "xxx" -offset indent
 228 .It dbname Li = Va DATABASENAME
 229 use this database for this realm.
 230 .It realm Li = Va REALM
 231 specifies the realm that will be stored in this database.
 232 .It mkey_file Li = Pa FILENAME
 233 use this keytab file for the master key of this database.
 234 If not specified
 235 .Va DATABASENAME Ns .mkey
 236 will be used.
 237 .It acl_file Li = PA FILENAME
 238 use this file for the ACL list of this database.
 239 .It log_file Li = Pa FILENAME
 240 use this file as the log of changes performed to the database.  This
 241 file is used by
 242 .Nm ipropd-master
 243 for propagating changes to slaves.
 244 .El
 245 .It Li }
 246 .It max-request = Va SIZE
 247 Maximum size of a kdc request.
 248 .It require-preauth = Va BOOL
 249 If set pre-authentication is required. Since krb4 requests are not
 250 pre-authenticated they will be rejected.
 251 .It ports = Va "list of ports"
 252 list of ports the kdc should listen to.
 253 .It addresses = Va "list of interfaces"
 254 list of addresses the kdc should bind to.
 255 .It enable-kerberos4 = Va BOOL
 256 turn on kerberos4 support.
 257 .It v4-realm = Va REALM
 258 to what realm v4 requests should be mapped.
 259 .It enable-524 = Va BOOL
 260 should the Kerberos 524 converting facility be turned on. Default is same as
 261 .Va enable-kerberos4 .
 262 .It enable-http = Va BOOL
 263 should the kdc answer kdc-requests over http.
 264 .It enable-kaserver = Va BOOL
 265 if this kdc should emulate the AFS kaserver.
 266 .It check-ticket-addresses = Va BOOL
 267 verify the addresses in the tickets used in tgs requests.
 268 .\" XXX
 269 .It allow-null-ticket-addresses = Va BOOL
 270 allow addresses-less tickets.
 271 .\" XXX
 272 .It allow-anonymous = Va BOOL
 273 if the kdc is allowed to hand out anonymous tickets.
 274 .It encode_as_rep_as_tgs_rep = Va BOOL
 275 encode as-rep as tgs-rep tobe compatible with mistakes older DCE secd did.
 276 .\" XXX
 277 .It kdc_warn_pwexpire = Va TIME
 278 the time before expiration that the user should be warned that her
 279 password is about to expire.
 280 .It logging = Va Logging
 281 What type of logging the kdc should use, see also [logging]/kdc.
 282 .El
 283 .It Li [kadmin]
 284 .Bl -tag -width "xxx" -offset indent
 285 .It require-preauth = Va BOOL
 286 If pre-authentication is required to talk to the kadmin server.
 287 .It default_keys = Va keytypes...
 288 for each entry in
 289 .Va default_keys
 290 try to parse it as a sequence of
 291 .Va etype:salttype:salt
 292 syntax of this if something like:
 293 .Pp
 294 [(des|des3|etype):](pw-salt|afs3-salt)[:string]
 295 .Pp
 296 if
 297 .Ar etype
 298 is omitted it means everything, and if string is omitted is means the default string (for that principal). Additional special values of keyttypes are:
 299 .Bl -tag -width "xxx" -offset indent
 300 .It v5
 301 The kerberos 5 salt
 302 .Va pw-salt
 303 .It v4
 304 The kerberos 4 type
 305 .Va des:pw-salt:
 306 .El
 307 .It use_v4_salt = Va BOOL
 308 When true, this is the same as
 309 .Pp
 310 .Va default_keys = Va des3:pw-salt Va v4
 311 .Pp
 312 and is only left for backwards compatability.
 313 .El
 314 .El
 315 .Sh ENVIRONMENT
 316 .Ev KRB5_CONFIG
 317 points to the configuration file to read.
 318 .Sh EXAMPLE
 319 .Bd -literal -offset indent
 320 [libdefaults]
 321         default_realm = FOO.SE
 322 [domain_realm]
 323         .foo.se = FOO.SE
 324         .bar.se = FOO.SE
 325 [realms]
 326         FOO.SE = {
 327                 kdc = kerberos.foo.se
 328                 v4_name_convert = {
 329                         rcmd = host
 330                 }
 331                 v4_instance_convert = {
 332                         xyz = xyz.bar.se
 333                 }
 334                 default_domain = foo.se
 335         }
 336 [logging]
 337         kdc = FILE:/var/heimdal/kdc.log
 338         kdc = SYSLOG:INFO
 339         default = SYSLOG:INFO:USER
 340 .Ed
 341 .Sh DIAGNOSTICS
 342 Since
 343 .Nm
 344 is read and parsed by the krb5 library, there is not a lot of
 345 opportunities for programs to report parsing errors in any useful
 346 format.
 347 To help overcome this problem, there is a program
 348 .Nm verify_krb5_conf
 349 that reads
 350 .Nm
 351 and tries to emit useful diagnostics from parsing errors.  Note that
 352 this program does not have any way of knowing what options are
 353 actually used and thus cannot warn about unknown or misspelled ones.
 354 .Sh SEE ALSO
 355 .Xr kinit 1 ,
 356 .Xr krb5_425_conv_principal 3 ,
 357 .Xr krb5_openlog 3 ,
 358 .Xr strftime 3 ,
 359 .Xr verify_krb5_conf 8