To persistently change the hostname of a Debian-based system.

Suppose that you have installed a copy of Debian on a machine without specifying a hostname, causing it to default to the name debian with no domain. It is now to be configured as a mailserver, and you wish to change its fully-qualified hostname to mail.example.com. It has a single static IP address which is 203.0.113.1.

The method described here has three steps:

1. Ensure that the new hostname can be resolved using /etc/hosts.
2. Alter the file /etc/hostname to contain the new hostname.
3. Activate the new hostname.

When a program needs to know the fully-qualified hostname of the machine it is running on, the usual method for obtaining that information is as follows:

1. Obtain the hostname reported by the operating system (which may or may not be fully qualified); then
2. Canonicalise the hostname (thereby converting it into a fully-qualified domain name if that is possible).

For this to work, the unqualified hostname must be resolvable and must be an alias of the fully-qualified hostname. In principle this could be done through the DNS, but if you were to rely on that alone then any loss of network connectivity could cause the hostname to change. The preferred arrangement is therefore to ensure that the name can be resolved locally using the /etc/hosts file, regardless of whether it can also be resolved through the DNS.

Each line of /etc/hosts consists of an IP address, followed by the corresponding canonical domain name, followed by a list of aliases for that domain name. For the scenario described above, the file should therefore contain a line of the form:

/etc/hosts

<ip-address> mail.example.com mail

The remaining issue is how to choose the IP address. If the host has a static IP address (either public or private) then you should use that:

/etc/hosts

203.0.113.1 mail.example.com mail

If the address is set dynamically (for example, using DHCP), or if there is no address because the host is not networked, then the best alternative is to choose an address that is within the loopback netblock (127.0.0.0/8) but which differs from the address of localhost (127.0.0.1). The address used for this purpose by the Debian installer is 127.0.1.1:

/etc/hosts

127.0.1.1 mail.example.com mail

If the host has several static IP addresses then there is some advantage to the canonical address being a public address (so that the host can be referred to by its canonical name from anywhere), but that is not the only consideration. You should also establish which network services are sensitive to the choice of canonical address and where they will need to be accessed from.

On Debian-based systems, the hostname is configured in the file /etc/hostname. The unqualified hostname should appear by itself as the first line of the file, and there should be no other content.

(Both the manpage for the hostname command and the Debian Reference specify that it is the unqualified hostname that should appear in this file, as opposed to the fully-qualified hostname. This is also how the file is configured by the Debian and Ubuntu installers.)

The most portable way to activate the new hostname is to instruct the hostname command to re-read /etc/hostname:

hostname -F /etc/hostname

(Debian has a script /etc/init.d/hostname.sh which can be used instead, but this does not exist on Ubuntu-based distributions.)

You can check that the hostname has been correctly set using the hostname command. Executed with no options:

hostname

it should print the hostname reported by the kernel, which should be the unqualified hostname:

mail

Executed again with the option –fqdn:

hostname --fqdn

it should print the fully-qualified hostname:

mail.example.com

If the reported hostname is not as intended then this usually due to it not being correctly canonicalised. You can check this using the getent command. First attempt to resolve the unqualified hostname to an IP address:

getent hosts mail.example.com

This should display the relevant line from the hosts file, for example:

203.0.113.1 mail.example.com mail

Then, take the reported IP address and attempt to resolve it to a hostname:

getent hosts 203.0.113.1

This should give the same result. If either the hostname or the IP address fails to resolve then the most likely cause is an incorrectly written /etc/hosts. Alternatively it is possible that the Name Service Switch has been configured (in /etc/nsswitch.conf) to consult some other database first, and that this is giving a different result to /etc/hosts.

• Osamu Aoki, The hostname, Debian Reference, March 2012 [http://www.debian.org/doc/manuals/debian-reference/ch03.en.html#_the_hostname]
• hostname (Ubuntu manpage) [http://manpages.ubuntu.com/manpages/precise/man1/hostname.1.html]