====== Ubuntu - Networking - Configuration - Hostname - Change Hostname ======


===== Objective =====

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

----

===== Scenario =====

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.

----

===== Method =====

==== Overview ====

The method described here has three steps:

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


==== Ensure that the new hostname can be resolved using /etc/hosts ====

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:

  - Obtain the hostname reported by the operating system (which may or may not be fully qualified); then
  - 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:

<file bash /etc/hosts>
<ip-address> mail.example.com mail
</file>

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:

<file bash /etc/hosts>
203.0.113.1 mail.example.com mail
</file>

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:

<file bash /etc/hosts>
127.0.1.1 mail.example.com mail
</file>

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.

==== Alter the file /etc/hostname to contain the new hostname ====

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.)

==== Activate the new hostname ====

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

<code bash>
hostname -F /etc/hostname
</code>

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

----

===== Testing =====

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

<code bash>
hostname
</code>

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

<code bash>
mail
</code>

Executed again with the option **--fqdn**:

<code bash>
hostname --fqdn
</code>

it should print the fully-qualified hostname:

<code bash>
mail.example.com
</code>

----

===== Troubleshooting =====

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:

<code bash>
getent hosts mail.example.com
</code>

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

<code bash>
203.0.113.1 mail.example.com mail
</code>

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

<code bash>
getent hosts 203.0.113.1
</code>

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.

----

===== Further reading =====

  * 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]