Have you ever edited /etc/hosts on Ubuntu, only to discover that your changes mysteriously disappeared after a reboot?

We've experienced this issue here at SNUBmonkey™. The culprit can be Cloud-Init, a utility commonly used to initialize cloud instances and configure system settings during startup.

Depending on the system's configuration, Cloud-Init can regenerate /etc/hosts, overwriting custom entries that were added manually.

This can become a frustrating problem, especially when your infrastructure relies on static hostname mappings for services such as SSH, rsync, and other network-dependent applications.

The good news? You can configure Cloud-Init to preserve your custom entries across reboots.

In this tutorial, we'll explain how Cloud-Init manages /etc/hosts, how to identify the cause of disappearing entries, and how to make your changes persistent.

1. Understand Why /etc/hosts Changes After Reboot

The /etc/hosts file provides a local mapping between IP addresses and hostnames.

For example:

$ cat /etc/hosts

You might see entries such as:

127.0.0.1 localhost
127.0.1.1 webserver
192.168.1.50 nas
192.168.1.60 backup

These mappings allow applications to resolve the specified hostnames locally without relying on an external DNS server.

However, on systems where Cloud-Init manages this file, the contents may be regenerated during startup.

Cloud-Init's behavior is controlled by the manage_etc_hosts setting, which can be configured in /etc/cloud/cloud.cfg or through other Cloud-Init configuration files.

When enabled, Cloud-Init can generate /etc/hosts using a template and information about the system's hostname.

The template commonly used on Ubuntu and Debian systems is:

/etc/cloud/templates/hosts.debian.tmpl

Important: Cloud-Init does not necessarily overwrite /etc/hosts on every Ubuntu installation or at every boot. The behavior depends on its configuration and whether the relevant module runs.

Let's check your configuration.

2. Confirm Whether Cloud-Init Manages /etc/hosts

First, inspect the main Cloud-Init configuration file:

$ grep -n 'manage_etc_hosts' /etc/cloud/cloud.cfg

You may see:

manage_etc_hosts: true

When set to true, Cloud-Init manages /etc/hosts and can regenerate it according to its configuration.

If the setting is absent, do not automatically assume that it is enabled or disabled without checking your Cloud-Init version and configuration.

You can also search the Cloud-Init configuration directory for additional settings:

$ grep -Rns 'manage_etc_hosts' /etc/cloud/cloud.cfg /etc/cloud/cloud.cfg.d/ 2>/dev/null

This helps identify whether the setting is defined in a separate configuration file.

Next, inspect the template:

$ sudo less /etc/cloud/templates/hosts.debian.tmpl

If the file exists, you can review how Cloud-Init constructs the hosts file.

You should also inspect the current hostname:

$ hostname

And the system's configured static hostname:

$ hostnamectl

These commands help establish whether the generated entries are associated with your system's hostname configuration.

3. Fix the Problem: Customize the Cloud-Init Template

If you want Cloud-Init to continue managing /etc/hosts while preserving custom static mappings, modifying the template can be an appropriate solution.

First, back up the existing template:

$ sudo cp -a /etc/cloud/templates/hosts.debian.tmpl /etc/cloud/templates/hosts.debian.tmpl.bak

Next, open the template:

$ sudo nano /etc/cloud/templates/hosts.debian.tmpl

Review its existing contents before making changes.

Add your custom hostname mappings to the template, taking care not to remove the existing hostname substitutions or other required template content.

For example, your custom entries might look like this:

# Custom network mappings
192.168.1.50 nas
192.168.1.60 backup
10.8.0.15 vpn-gateway

These are example addresses. Replace them with the actual IP addresses and hostnames used in your environment.

Do not blindly replace the entire template with a plain /etc/hosts file. Cloud-Init templates may contain variables that are substituted when the file is generated. Removing those variables can break the automatic configuration of your system's hostname entries.

Save the changes and exit the editor.

Apply the Changes

After updating the template, you can either allow Cloud-Init to regenerate /etc/hosts during its next applicable run or reboot the system after confirming that the configuration is correct.

To reboot:

$ sudo reboot

Keep in mind that modifying the template does not necessarily trigger an immediate update. If you need to apply the changes without rebooting, use a method appropriate for your installed Cloud-Init version and configuration.

For example, you can inspect the available Cloud-Init modules and their status with:

$ cloud-init status --long

You can also review the Cloud-Init logs to determine whether the update_etc_hosts module ran:

$ sudo grep -i 'update_etc_hosts' /var/log/cloud-init.log

Avoid assuming that manually invoking a Cloud-Init module will behave identically across all versions or configurations.

4. Verify That Your Entries Persist

After applying the changes, inspect /etc/hosts:

$ cat /etc/hosts

Confirm that your custom entries are present.

For example:

127.0.0.1 localhost
127.0.1.1 webserver

# Custom network mappings
192.168.1.50 nas
192.168.1.60 backup
10.8.0.15 vpn-gateway

::1 localhost ip6-localhost ip6-loopback
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

Your actual file may differ depending on your system configuration.

To verify that a hostname resolves to the expected address, use:

$ getent hosts nas

Expected output:

192.168.1.50    nas

This checks hostname resolution through the system's configured name-service mechanisms.

Finally, if persistence across reboots is important, verify the entries again after a reboot.

5. Alternative: Disable Cloud-Init's Management of /etc/hosts

If you prefer to manage /etc/hosts yourself, you can disable Cloud-Init's management of the file.

Before proceeding, consider whether your environment depends on automatically generated hostname entries. This setting can be particularly important on cloud instances and systems with dynamically assigned network configurations.

Open the Cloud-Init configuration file:

$ sudo nano /etc/cloud/cloud.cfg

Set the following option:

manage_etc_hosts: false

If the setting already exists, update its value. If it is defined in another configuration file, make sure you are modifying the effective configuration rather than creating conflicting settings.

Afterward, inspect the effective configuration and verify that Cloud-Init is no longer configured to manage /etc/hosts.

With this option disabled, you can maintain your hostname mappings directly in:

/etc/hosts

For example:

$ sudo nano /etc/hosts

Add or update your entries, then save the file.

Important: Disabling Cloud-Init's management of /etc/hosts does not disable Cloud-Init itself. Other Cloud-Init modules can continue to configure the system.

It also does not guarantee that no other service or configuration-management tool will modify the file.

6. Why Disabling Automatic Management Requires Care

Disabling Cloud-Init's management of /etc/hosts gives you greater control, but it also means you must maintain the relevant entries yourself.

Consider the following scenarios.

Dynamic IP Address Changes

In cloud environments, hostnames and IP addresses may change when instances are replaced or network configurations are modified.

If /etc/hosts contains an outdated IP address, applications that rely on that mapping may connect to the wrong destination or fail to connect.

For example, if your backup server changes from 192.168.1.60 to 192.168.1.70, you must update the mapping wherever it is maintained.

SSH Connectivity

Suppose you connect to a server using its hostname:

$ ssh user@webserver

If webserver resolves to an outdated address, the SSH client may attempt to connect to the wrong machine.

This can cause connection failures or unexpected host-key warnings.

rsync and Other Network Services

The same issue can affect rsync operations that use remote hostnames.

For example:

$ rsync -av ./backup/ user@nas:/srv/backups/

If nas no longer resolves to the correct IP address, the transfer may fail or target an unintended system.

Similar problems can affect scripts, monitoring agents, and other network-dependent applications.

Consistency Across Multiple Systems

If several machines rely on static hostname mappings, those mappings must remain consistent.

Updating /etc/hosts on one server does not automatically update the file on other servers.

For larger or more dynamic environments, a properly configured DNS service is often easier to maintain than manually synchronizing hostname mappings across multiple machines.

If your custom /etc/hosts entries disappear after rebooting Ubuntu, Cloud-Init may be responsible.

Check the manage_etc_hosts setting and inspect the Cloud-Init template. You can customize the template to preserve your entries or disable automatic management and maintain the file manually.

The best approach depends on your environment. Automatic management suits cloud instances with dynamic network configurations, while static configurations may work better for servers with stable hostname mappings.

Always identify which component manages /etc/hosts before making changes to avoid conflicts affecting hostname resolution, SSH, rsync, and other network services.

We hope this was helpful.