xref: /freebsd/crypto/heimdal/lib/krb5/krb5.conf.5 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
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
43The
44.Nm
45file specifies several configuration parameters for the Kerberos 5
46library, as well as for some programs.
47.Pp
48The file consists of one or more sections, containing a number of
49bindings.
50The value of each binding can be either a string or a list of other
51bindings.
52The grammar looks like:
53.Bd -literal -offset indent
54file:
55	/* empty */
56	sections
57
58sections:
59	section sections
60	section
61
62section:
63	'[' section_name ']' bindings
64
65section_name:
66	STRING
67
68bindings:
69	binding bindings
70	binding
71
72binding:
73	name '=' STRING
74	name '=' '{' bindings '}'
75
76name:
77	STRING
78
79.Ed
80.Li STRINGs
81consists of one or more non-whitespace characters.
82.Pp
83STRINGs that are specified later in this man-page uses the following
84notation.
85.Bl -tag -width "xxx" -offset indent
86.It boolean
87values can be either yes/true or no/false.
88.It time
89values can be a list of year, month, day, hour, min, second.
90Example: 1 month 2 days 30 min.
91.It etypes
92valid encryption types are: des-cbc-crc, des-cbc-md4, des-cbc-md5,
93des3-cbc-sha1, arcfour-hmac-md5, aes128-cts-hmac-sha1-96, and
94aes256-cts-hmac-sha1-96 .
95.It address
96an address can be either a IPv4 or a IPv6 address.
97.El
98.Pp
99Currently recognised sections and bindings are:
100.Bl -tag -width "xxx" -offset indent
101.It Li [appdefaults]
102Specifies the default values to be used for Kerberos applications.
103You can specify defaults per application, realm, or a combination of
104these.
105The 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
117The supported options are:
118.Bl -tag -width "xxx" -offset indent
119.It Li forwardable = Va boolean
120When obtaining initial credentials, make the credentials forwardable.
121.It Li proxiable = Va boolean
122When obtaining initial credentials, make the credentials proxiable.
123.It Li no-addresses = Va boolean
124When obtaining initial credentials, request them for an empty set of
125addresses, making the tickets valid from any address.
126.It Li ticket_lifetime = Va time
127Default ticket lifetime.
128.It Li renew_lifetime = Va time
129Default renewable ticket lifetime.
130.It Li encrypt = Va boolean
131Use encryption, when available.
132.It Li forward = Va boolean
133Forward credentials to remote host (for
134.Xr rsh 1 ,
135.Xr telnet 1 ,
136etc).
137.El
138.It Li [libdefaults]
139.Bl -tag -width "xxx" -offset indent
140.It Li default_realm = Va REALM
141Default realm to use, this is also known as your
142.Dq local realm .
143The default is the result of
144.Fn krb5_get_host_realm "local hostname" .
145.It Li clockskew = Va time
146Maximum time differential (in seconds) allowed when comparing
147times.
148Default is 300 seconds (five minutes).
149.It Li kdc_timeout = Va time
150Maximum time to wait for a reply from the kdc, default is 3 seconds.
151.It v4_name_convert
152.It v4_instance_resolve
153These are described in the
154.Xr krb5_425_conv_principal  3
155manual 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
162This is deprecated, see the
163.Li capaths
164section below.
165.It Li default_etypes = Va etypes ...
166A list of default encryption types to use.
167.It Li default_etypes_des = Va etypes ...
168A list of default encryption types to use when requesting a DES credential.
169.It Li default_keytab_name = Va keytab
170The keytab to use if no other is specified, default is
171.Dq FILE:/etc/krb5.keytab .
172.It Li dns_lookup_kdc = Va boolean
173Use DNS SRV records to lookup KDC services location.
174.It Li dns_lookup_realm = Va boolean
175Use DNS TXT records to lookup domain to realm mappings.
176.It Li kdc_timesync = Va boolean
177Try to keep track of the time differential between the local machine
178and the KDC, and then compensate for that when issuing requests.
179.It Li max_retries = Va number
180The max number of times to try to contact each KDC.
181.It Li ticket_lifetime = Va time
182Default ticket lifetime.
183.It Li renew_lifetime = Va time
184Default renewable ticket lifetime.
185.It Li forwardable = Va boolean
186When obtaining initial credentials, make the credentials forwardable.
187This option is also valid in the [realms] section.
188.It Li proxiable = Va boolean
189When obtaining initial credentials, make the credentials proxiable.
190This option is also valid in the [realms] section.
191.It Li verify_ap_req_nofail = Va boolean
192If enabled, failure to verify credentials against a local key is a
193fatal error.
194The application has to be able to read the corresponding service key
195for this to work.
196Some applications, like
197.Xr su 1 ,
198enable this option unconditionally.
199.It Li warn_pwexpire = Va time
200How soon to warn for expiring password.
201Default is seven days.
202.It Li http_proxy = Va proxy-spec
203A HTTP-proxy to use when talking to the KDC via HTTP.
204.It Li dns_proxy = Va proxy-spec
205Enable using DNS via HTTP.
206.It Li extra_addresses = Va address ...
207A list of addresses to get tickets for along with all local addresses.
208.It Li time_format = Va string
209How to print time strings in logs, this string is passed to
210.Xr strftime 3 .
211.It Li date_format = Va string
212How to print date strings in logs, this string is passed to
213.Xr strftime 3 .
214.It Li log_utc = Va boolean
215Write log-entries using UTC instead of your local time zone.
216.It Li scan_interfaces = Va boolean
217Scan all network interfaces for addresses, as opposed to simply using
218the address associated with the system's host name.
219.It Li fcache_version = Va int
220Use file credential cache format version specified.
221.It Li krb4_get_tickets = Va boolean
222Also get Kerberos 4 tickets in
223.Nm kinit ,
224.Nm login ,
225and other programs.
226This option is also valid in the [realms] section.
227.It Li fcc-mit-ticketflags = Va boolean
228Use MIT compatible format for file credential cache.
229It's the field ticketflags that is stored in reverse bit order for
230older than Heimdal 0.7.
231Setting this flag to
232.Dv TRUE
233make it store the MIT way, this is default for Heimdal 0.7.
234.El
235.It Li [domain_realm]
236This is a list of mappings from DNS domain to Kerberos realm.
237Each binding in this section looks like:
238.Pp
239.Dl domain = realm
240.Pp
241The domain can be either a full name of a host or a trailing
242component, in the latter case the domain-string should start with a
243period.
244The realm may be the token `dns_locate', in which case the actual
245realm will be determined using DNS (independently of the setting
246of 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]
252Specifies a list of kdcs for this realm.
253If the optional
254.Va port
255is absent, the
256default value for the
257.Dq kerberos/udp
258.Dq kerberos/tcp ,
259and
260.Dq http/tcp
261port (depending on service) will be used.
262The kdcs will be used in the order that they are specified.
263.Pp
264The optional
265.Va service
266specifies over what medium the kdc should be
267contacted.
268Possible services are
269.Dq udp ,
270.Dq tcp ,
271and
272.Dq http .
273Http can also be written as
274.Dq http:// .
275Default service is
276.Dq udp
277and
278.Dq tcp .
279.It Li admin_server = Va host[:port]
280Specifies the admin server for this realm, where all the modifications
281to the database are performed.
282.It Li kpasswd_server = Va host[:port]
283Points to the server where all the password changes are performed.
284If there is no such entry, the kpasswd port on the admin_server host
285will be tried.
286.It Li krb524_server = Va host[:port]
287Points to the server that does 524 conversions.
288If 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
292See
293.Xr krb5_425_conv_principal 3 .
294.It Li tgs_require_subkey
295a boolan variable that defaults to false.
296Old 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 ...
305This serves two purposes. First the first listed
306.Va hop-realm
307tells a client which realm it should contact in order to ultimately
308obtain credentials for a service in the
309.Va server-realm .
310Secondly, it tells the KDC (and other servers) which realms are
311allowed in a multi-hop traversal from
312.Va client-realm
313to
314.Va server-realm .
315Except 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
322Specifies that
323.Va entity
324should use the specified
325.Li destination
326for logging.
327See the
328.Xr krb5_openlog 3
329manual 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
336Use this database for this realm.
337.It realm Li = Va REALM
338Specifies the realm that will be stored in this database.
339.It mkey_file Li = Pa FILENAME
340Use this keytab file for the master key of this database.
341If not specified
342.Va DATABASENAME Ns .mkey
343will be used.
344.It acl_file Li = PA FILENAME
345Use this file for the ACL list of this database.
346.It log_file Li = Pa FILENAME
347Use this file as the log of changes performed to the database.
348This file is used by
349.Nm ipropd-master
350for propagating changes to slaves.
351.El
352.It Li }
353.It max-request = Va SIZE
354Maximum size of a kdc request.
355.It require-preauth = Va BOOL
356If set pre-authentication is required.
357Since krb4 requests are not pre-authenticated they will be rejected.
358.It ports = Va "list of ports"
359List of ports the kdc should listen to.
360.It addresses = Va "list of interfaces"
361List of addresses the kdc should bind to.
362.It enable-kerberos4 = Va BOOL
363Turn on Kerberos 4 support.
364.It v4-realm = Va REALM
365To what realm v4 requests should be mapped.
366.It enable-524 = Va BOOL
367Should the Kerberos 524 converting facility be turned on.
368Default is same as
369.Va enable-kerberos4 .
370.It enable-http = Va BOOL
371Should the kdc answer kdc-requests over http.
372.It enable-kaserver = Va BOOL
373If this kdc should emulate the AFS kaserver.
374.It check-ticket-addresses = Va BOOL
375verify the addresses in the tickets used in tgs requests.
376.\" XXX
377.It allow-null-ticket-addresses = Va BOOL
378Allow addresses-less tickets.
379.\" XXX
380.It allow-anonymous = Va BOOL
381If the kdc is allowed to hand out anonymous tickets.
382.It encode_as_rep_as_tgs_rep = Va BOOL
383Encode as-rep as tgs-rep tobe compatible with mistakes older DCE secd did.
384.\" XXX
385.It kdc_warn_pwexpire = Va TIME
386The time before expiration that the user should be warned that her
387password is about to expire.
388.It logging = Va Logging
389What type of logging the kdc should use, see also [logging]/kdc.
390.It use_2b = Va principal list
391List 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
396If pre-authentication is required to talk to the kadmin server.
397.It default_keys = Va keytypes...
398for each entry in
399.Va default_keys
400try to parse it as a sequence of
401.Va etype:salttype:salt
402syntax of this if something like:
403.Pp
404[(des|des3|etype):](pw-salt|afs3-salt)[:string]
405.Pp
406If
407.Ar etype
408is omitted it means everything, and if string is omitted it means the
409default salt string (for that principal and encryption type).
410Additional special values of keytypes are:
411.Bl -tag -width "xxx" -offset indent
412.It v5
413The Kerberos 5 salt
414.Va pw-salt
415.It v4
416The Kerberos 4 salt
417.Va des:pw-salt:
418.El
419.It use_v4_salt = Va BOOL
420When true, this is the same as
421.Pp
422.Va default_keys = Va des3:pw-salt Va v4
423.Pp
424and is only left for backwards compatibility.
425.El
426.El
427.Sh ENVIRONMENT
428.Ev KRB5_CONFIG
429points to the configuration file to read.
430.Sh FILES
431.Bl -tag -width "/etc/krb5.conf"
432.It Pa /etc/krb5.conf
433configuration 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
459Since
460.Nm
461is read and parsed by the krb5 library, there is not a lot of
462opportunities for programs to report parsing errors in any useful
463format.
464To help overcome this problem, there is a program
465.Nm verify_krb5_conf
466that reads
467.Nm
468and tries to emit useful diagnostics from parsing errors.
469Note that this program does not have any way of knowing what options
470are actually used and thus cannot warn about unknown or misspelled
471ones.
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
478