This site requires JavaScript to be enabled
An updated version of this article is available

The Kerberos Configuration File: krb5.conf

6 views

4.0 - Updated on 2021-03-11 by Brittany Bossarte

3.0 - Updated on 2021-02-19 by Carlos Salazar (Inactive)

2.0 - Updated on 2020-09-28 by Brittany Bossarte

1.0 - Authored on 2014-05-08 by Fang Wang

Intended for: Kerberos users and system administrators


Scenario/Use case:

This article describes the Kerberos configuration file krb5.conf.


Instructions:

A krb5.conf file must exist in the /etc directory on each UNIX, Linux or Macintosh node that is running Kerberos. We provide a template for this file as web pages for different operating system which can be found at

http://authentication.fnal.gov/krb5conf/.

Windows systems with Kerberos for Windows (KfW) installed (i.e. all FERMI Domain machines) usually have a similar Kerberos configuration also called krb5.conf installed in C:ProgramData\Kerberos\krb5.conf.  The two primary differences between the krb5.conf for Windows and Linux is that the default realm of FNAL.GOV is replaced by FERMI.WIN.FNAL.GOV in the Windows version and there are enctypes settings in the libdefaults section in the Linux version that are not necessary in the Windows version. Various (newer) versions of Kerberos for Windows use default names and locations for the configuration file.  Here are some of the known names and locations:

  • C:\ProgramData\Kerberos\krb5.conf (currently used by KfW in the FERMI Domain)
  • C:\ProgramData\MIT\Kerberos5\krb5.conf (apparently used by MIT KfW V4)
  • C:\ProgramData\MIT\Kerberos\krb5.conf
  • C:\Windows\krb5.ini (used by older versions of KfW)

Windows systems that are members of the FERMI Windows Domain use FERMI.WIN.FNAL.GOV as the default realm in the KfW configuration file. Non-domain (standalone) Windows systems can use either FERMI.WIN.FNAL.GOV or FNAL.GOV as the default realm depending on which makes more sense as the default based on usage.

If you install either of the RPM packages (krb5-fermi-config or krb5-fermi-krb5.conf) for Linux, the krb5.conf file gets installed automatically for you. If you obtain Kerberos from another source, you must obtain this file yourself, edit it as necessary, and copy it into the /etc directory of your machine.

You may need to update your krb5.conf file from time to time as the template gets updated. New versions are announced on the kerberos-users@fnal.gov and linux-users@fnal.gov mailing lists.

If you need to change a setting in krb5.conf but cannot or don't want to change the file in /etc, you can copy /etc/krb5.conf to a new file and edit this copy. Then set the environment variable $KRB5_CONFIG to the full name of your copy. Your copy will be honored by client programs such as kinit or rlogin, but not by programs that need a trusted configuration file, e.g., ksu and the service daemons.

What does krb5.conf Control?

The file consists of several stanzas, each of which controls certain aspects of the installation:

  • [libdefaul sets defaults for Kerberos on your system, e.g., default realm, default ticket lifetime
  • [realms] tells where to find the KDCs for each realm
  • [instancemapping] maps client principal properly (for things like cron jobs which require a special principal)
  • [capaths]  maps cross-realm trusts with the PILOT (test) realm and the FERMI and FERMIBETA Windows domains
  • [domain_realm] maps domains to realms
  • [logging] tells Kerberos where and how to log errors
  • [appdefaults] lists default settings for outgoing Kerberized network connection applications and for incoming portal mode connections

For complete documentation on the Kerberos configuration file, refer to the MIT Kerberos Documentation: krb5.conf.

krb5.conf Template

For reference, we provide a partial listing of  the krb5.conf file contents with some explanations inserted. If you install using the RPM packages, the necessary name substitutions will be made as part of the installation; otherwise, you need to edit this file manually.

[libdefaults]

This section sets defaults for Kerberos on your system.

ticket_lifetime = 1560m

There are some implementations of Kerberos that read the above number as seconds, and is equivalent to 26 hours. In MIT-derived code, it's read as minutes.

default_realm = FNAL.GOV

In Kerberos transactions, this default_realm is assumed when you mention any principal without its "@REALM" part.  For the Windows krb5.ini this is changed to be FERMI.WIN.FNAL.GOV.

checksum_type = 1
ccache_type = 3

allow_weak_crypto = true

Because our (old) KDCs were limited to DES encryption and as a result there are still many principals with DES keys, this setting tells modern Kerberos clients to allow the use of DES encryption.

[realms]

This section lists the realms, and for each realm the KDCs and admin server (master KDC) of that realm, the default_domain for  Kerberos v5 service names, and principal-to-account name matching info.

If and when we cross-authenticate with some other site, each host that wants to initiate connections to the other site will have to list that site's realm information here. (Not necessary for accepting connections from that site.)

System administrators can use a local KDC search list on their clients to reduce the load on the primary KDC, especially if a semi-dedicated slave KDC located on local subnets.  Re-order the FNAL.GOV KDC located between the #BEGINTAG and #ENDTAG lines putting the KDCs in the order desired.  Then save this section of krb5.conf as the file /etc/krb5.kdclist including the #BEGINTAG/#ENDTAG lines.  By doing this, your KDC search order will be preserved across krb5.conf updates when using the krb5-fermi-config or krb5-fermi-krb5.conf RPM packages.

FNAL.GOV = {
#BEGINTAG-KDCLIST
kdc = krb-fnal-fcc3.fnal.gov:88
kdc = krb-fnal-2.fnal.gov:88
kdc = krb-fnal-3.fnal.gov:88
kdc = krb-fnal-1.fnal.gov:88
kdc = krb-fnal-4.fnal.gov:88
kdc = krb-fnal-enstore.fnal.gov:88
kdc = krb-fnal-fg1.fnal.gov:88
kdc = krb-fnal-fg2.fnal.gov:88
kdc = krb-fnal-cms188.fnal.gov:88
kdc = krb-fnal-cms204.fnal.gov:88
kdc = krb-fnal-d0online.fnal.gov:88
kdc = krb-fnal-cdfonline.fnal.gov:88
kdc = krb-fnal-nova-fd.fnal.gov:88
kdc = krb-fnal-soudan.fnal.gov:88
# The krb-fnal-5/6/7 CNAME's still exist and will continue to exist
# but are deprecated in favor of krb-fnal-d0online/cdfonline/soudan
#ENDTAG-KDCLIST
master_kdc = krb-fnal-admin.fnal.gov:88
admin_server = krb-fnal-admin.fnal.gov
default_domain = fnal.gov
}

This section also contains definitions for the other Kerberos realms and Windows domains at Fermilab (FERMI, SERVICES, FERMITEST, PILOT, etc).  In addition, sections for the University of Chicago, CERN and SLAC Kerberos realms are present.

 
 
[logging]

This section tells Kerberos where and how to log errors; through syslog or directly to file.

kdc = SYSLOG:info:local1
admin-server = SYSLOG:info:local2
default = SYSLOG:err:auth

[capaths]

This section establishes the mappings for the two-way trust relationships between the FNAL.GOV and PILOT realms and between the FNAL.GOV realm
and the FERMI and FERMIBETA Windows Domains.

[domain_realm]

In this section the DNS domains get mapped to the realms. (This determines the realm in which you need to get a service ticket to log into a Kerberized host in a particular domain.) For individual machines in a domain that need to be mapped to a different realm than the domain as a whole, list each machine separately, mapped to the correct realm. Make your changes in the lower part of this section as noted below.

.fnal.gov = FNAL.GOV
.cdms-soudan.org = FNAL.GOV
.minos-soudan.org = FNAL.GOV
.dhcp.fnal.gov = FNAL.GOV
...
.fermi,win,fnal.gov = FERMI.WIN.FNAL.GOV
.services.fnal.gov = SERVICES.FNAL.GOV
...
.cs.ttu.edu = FNAL.GOV
...
.harvard.edu = FNAL.GOV
... (other "friends and family" by request)
# The whole "top half" is replaced during "ups installAsRoot krb5conf", so:
# It would probably be a bad idea to change anything on or above this line

# If you need to add any .domains or hosts, put them here
[domain_realm]
mojo.lunet.edu = FNAL.GOV

[appdefaults]

This section lists default application settings (ticket attributes, login parameters, etc.). Each of the applications listed may have additional attributes set (e.g., ticket lifetime, and so on). All of these defaults (or nearly all) can be overridden by a command-line flag. The krb5.conf file just sets the defaults for the host. (The ftp client does not look for defaults here; the ftpd ticket lifetime set in the file is invoked for CRYPTOCard FTP access and kcron.)

default_lifetime = 7d
retain_ccache = false

retain_ccache determines whether tickets in a user's ticket cache on a particular host get saved (true) or destroyed (false) when the user closes his session on that host.

autologin = true
forward = true
forwardable = true

forward should in most cases be set to true, in order to forward tickets obtained as "forwardable" to remote hosts by default.

renewable = true
encrypt = true
krb5_aklog_path = /usr/krb5/bin/aklog

The initial list is for common settings. These values are used by all the applications except when an overriding value is listed for a particular application; see below.

telnet = {
}

Telnet uses the common settings; no overrides.

Kerberized telnet is deprecated, Fermilab suggests using ssh or slogin instead..
Most servers at Fermilab have logins via telnet disabled as well.

rcp = {
forward = false
encrypt = false
allow_fallback = true
}

Whereas rcp sets two overrides (the first of which is unnecessary) and one additional parameter.

rsh = {
allow_fallback = true
}

rlogin = {
allow_fallback = false
}
 
login = {
forwardable = true
krb5_get_tickets = true
krb4_get_tickets = false
krb4_convert = false
}

login is invoked by telnetd (not telnet) and sshd (not ssh), and may be invoked by the OS for a local (console) login.

Kerberized telnet is deprecated, Fermilab suggests using ssh instead..
Most servers at Fermilab have logins via telnet disabled as well.

 

kinit = {
forwardable = true
}
 
pam = {
debug = false
forwardable = true
renew_lifetime = 7d
ticket_lifetime = 1560m
krb4_convert = false
krb4_convert_524 = false
krb4_use_as_req = false

}
 
rshd = {
}
 
ftpd = {
default_lifetime = 10h
}

See Also: