Why Your System Requires a Proper FQDN

People skip the “Preparing Your System” part of Kolab’s “Installation Guide” as if RTFM were somehow an acronym less well known than YOLO.

I originally published this article on the kolab.org blog on September 12th, 2013. It is more important today than it was before, for reasons explained below. With the refresh of kolab.org, the old blog post is offline. This is an edited copy with updated information and minor edits.

While only a warning in setup-kolab, some people set up a Kolab Groupware server with with an improper system fully qualified domain name, with all sorts of undesirable effects. I’m actually seriously considering making this warning a fatal error.

EDIT: And so there is T977.

Why does a system require a proper FQDN? Is it actually required?

I’ll answer the second question first, since it has the shortest possible answer: No.

Of course a proper FQDN is not absolutely required. But it is strongly recommended. For example, the default “localhost” and “localhost.localdomain” names you’ll find in /etc/hosts (with addresses and ::1) are not “fully qualified domain names”.

Right after you install a system (unless you have a fancy network infrastructure with (dynamic) DNS and DHCP, or a prepared DNS entry for a static IP address), the only way a system knows how to refer to itself is using these names “localhost” and “localhost.localdomain”. Avahi may add a “hostname.local” address for LAN discovery, but that too is still not a fully qualified domain name.

With a Kolab Groupware setup, this is somewhat problematic. Not because there’s a guarantee it won’t work, but because it is an insensible default, and secondary components that install alongside Kolab Groupware won’t work as expected.

So what is a proper FQDN?

Well, it exists of at least two parts: the host’s name, and a domain name space. For example, if the host’s name is ‘kolab01’, and the domain name space is ‘example.org’, the FQDN would be ‘kolab01.example.org’. Please note that the domain name space itself 1) exists of the domain name you (probably) registered and the top-level domain name you registered it with – apologies to those in the know, for bastardizing the terminology, and 2) may actually be a sub-domain name, such as ‘ch.kolabsys.com’. We refer to these as domain name spaces, rather than domain names.

When you set a system’s FQDN it is important that it exists of at least these three parts divided by a dot (.) character. Why?

A domain name (for example, ‘example.org’) is used for three purposes:

  1. its IN A is probably pointed at a web server, so that people can navigate to http://example.org equally well as http://www.example.org,
  2. its IN A is used as a fallback recipient SMTP server address should no IN MX records exist,
  3. it contains the SOA and NS records (authority statements, signatures, and other things).

Because of 1), the server to which the IN A for the domain name is pointing, it is unlikely (for larger deployments) that this is also the server on which the groupware deployment runs. Furthermore, it is best practice to set your MX records, possibly to the same system, but MX records nonetheless, so that you may have a level of redundancy (by supplying more than one MX record) and for sender policy framework definitions to work out OK.

That said, the Kolab Groupware component that is the 389 Directory server refers to itself using the configured system’s FQDN. While this can work should the IN A for “example.org” never change, it is more problematic should the system only be using ‘localhost’ or ‘localhost.localdomain’ – your 389 graphical console won’t be able to connect to the administrator server with that configured.

Furthermore, it is just bad, bad practice. A domain like ‘example.org’ is like a particular forest, and one of your systems is one of the trees. Unless you had a very specific deployment in mind, I’m sure you’ll want to be able to refer to a single tree rather than only being able to refer to the entire forest as a whole.

That said, this is not what setup-kolab is developed to handle either. It’ll chop off the first part of the “FQDN”, so using ‘example.org’ will lead the setup to conclude you’re going to want to set up for domain ‘org’. It’ll use that domain to build you a standard root dn as well, which in this example case would become ‘org’. Settings that relate to login realms, and other sorts of stuff all over the place will result in unexpected behaviour, not to say fail.

EDIT: In Kolab 16, the collaborative editing interface loaded from within Roundcube, using the kolab_files plugin addressing Chwala, is an iFrame pointing to Manticore. It is crucial for both sides of the iFrame (the iframor and iframee if you will) to be able to refer to one another with the exact and precise reference that the browser also uses, or fail browser’s XSS protection mechanisms.