What’s a Kerberos Realm?

A Kerberos realm is the domain over which a Kerberos authentication server has the authority to authenticate a user, host or service. A realm name is often, but not always the upper case version of the name of the DNS domain over which it presides.

Why do Realms Matter to the Linux VDA

It is important that Kerberos on the Linux VDA has been adequately configured so that the Citrix Broker Agent service can determine the Kerberos Realm associated with a fully qualified host name.  If the configuration is either wrong or incomplete it is very likely that the Linux VDA will be unable to register with the Delivery Controller (DDC), and ultimately prevent sessions being launched on the VDA.  If registration failure occurs it may be:

  • Reported in syslog on the Linux VDA with a message along the lines of “The Citrix Desktop Service failed to register with any delivery controller.”
  • Reported in the Application Log of the DDC by a registration failure message from the “Citrix Broker Service”
  • Shown in Citrix Studio where the Registration State of the Linux VDA will be categorised as “Unregistered”

Note that Kerberos Realm misconfiguration is only one of many reasons that a Linux VDA may fail to register with a DDC.  Some of those reasons will be discussed in a separate blog.

How to Specify Kerberos Realm Mappings

These mappings are either statically configured in /etc/krb5.conf on each VDA machine, or as of version 1.1, can be queried via DNS TXT records.

The Linux VDA attempts to determine the Kerberos realm associated with a fully qualified host name from the following sources in the following order:

  1. Domain to realm mappings within the [domain_realm] section of the krb5.conf file.
  2. DNS TXT records if the dns_lookup_realm item in the [libdefaults] section of the krb5.conf file is set to true. Note that a value of true is considered to be any of y, yes, true, t, 1 and on,and false any of n, no, false, nil, 0 and off. The DNS TXT record name is formed by prepending “_kerberos” to the fully qualified host name. If that record is not found, the name is formed by prepending “_kerberos” to the host’s domain name, then its parent domain, up to the top level domain. For example, for the hostname “ddc1.central.mycorp.net” the names of the DNS TXT records that would be looked up would be:
    • _kerberos.ddc1.central.mycorp.net
    • _kerberos.central.mycorp.net
    • _kerberos.mycorp.net
    • _kerberos.net
  3. The value of the default_realm item within the [libdefaults] section of the krb5.conf file, provided that the domain of the fully qualified host name is the same as the domain of the machine on which the krb5.conf file resides.
  4. The upper case version of the fully qualified host name’s domain.

Consider the following excerpt from an example krb5.conf in which dns_lookup_realm is false and the machine on which the krk5.conf file resides is in the domain workers.acme.net.

   [libdefaults]
      default_ccache_name = FILE:/tmp/krb5cc_%{uid}
      default_realm       = SERVERS.ACME.NET
      dns_lookup_realm    = false

   [domain_realm]
      workers.mycorp.net  = WORKERS.MYCORP.NET
      .workers.mycorp.net = WORKERS.MYCORP.NET
      central.mycorp.net  = CENTRAL.MYCORP.NET
      .central.mycorp.net = CENTRAL.MYCORP.NET

In the above example the following domain to realm mappings would be determined by the Linux VDA. The third column in the table shows the reason for the mapping:

Domain Realm Reason
workers.mycorp.net WORKERS.MYCORP.NET krb5.conf domain_realm
vda1.workers.mycorp.net WORKERS.MYCORP.NET krb5.conf domain_realm
central.mycorp.net CENTRAL.MYCORP.NET krb5.conf domain_realm
ddc1.central.mycorp.net CENTRAL.MYCORP.NET krb5.conf domain_realm
vda2.workers.acme.net SERVERS.ACME.NET krb5.conf default_realm
ddc2.central.acme.net CENTRAL.ACME.NET Upper case domain name

Consider the same excerpt from a krb5.conf file, but this time with a dns_lookup_realm value of true and the following DNS TXT records:

Name Text
_kerberos.workers.acme.net WORKERS.ACME.NET
_kerberos.central.acme.net CENTRAL.ACME.NET

The resulting domain to realm mappings would be:

Domain Realm Reason
workers.mycorp.net WORKERS.MYCORP.NET krb5.conf domain_realm
vda1.workers.mycorp.net WORKERS.MYCORP.NET krb5.conf domain_realm
central.mycorp.net CENTRAL.MYCORP.NET krb5.conf domain_realm
ddc1.central.mycorp.net CENTRAL.MYCORP.NET krb5.conf domain_realm
vda2.workers.acme.net WORKERS.ACME.NET DNS TXT record
ddc2.central.acme.net CENTRAL.ACME.NET DNS TXT record

Summary

If Kerberos domain to realm mappings are incomplete or incorrect on a Linux VDA it is very likely that it will be impossible to launch sessions on that VDA.  So it is important to get it right.

The mappings can be specified in a number of ways within the /etc/krb.conf file or via DNS TXT records. But given that configuring the [domain_realm] mapping section within the krb5.conf file on every VDA can be onerous and may not scale well, using DNS TXT records may be a better option.

To read more from the Linux Virtual Desktop Team, be sure to check out all of our posts here.