Rename a host

Change the name of a workstation, server or gateway, without touching the hardware. The host name acts as a key everywhere : it designates the deployment node, the machine folder and the supervision label.

For a machine replacement, see Migrating a gateway’s hardware.

What happens on its own

Regenerated, then propagated at deployment, without intervention.

Taken care of automatically	Why
Zone DNS and DHCP	Derived from the declared name
Service registry, portal, reverse proxy	Derived from the declared name
Supervision targets, deployment tags	Derived from the declared name
sops secrets	Linked to the host’s SSH key, not its name
Deployment SSH keys	Never pinned to the deployment account

Procedure

1. Rename in the configuration

   etc/config.yaml

   - hostname: "srv-maison"   # ancien nom : "srv"
     zone: "maison:1.2"
     profile: "server"

2. Move the machine folder

   git mv usr/machines/srv usr/machines/srv-maison

   Mandatory step

   This folder is imported by its path, usr/machines/<nom-d-hôte>. If forgotten, it is silently ignored : the hardware-configuration.nix file and the settings specific to the machine leave the built configuration.

3. Regenerate

   just clean

4. Create the backup account

   just passwd-restic

   Otherwise the backup server won’t start

   A restic server declares one secret per host name in the fleet, whether the host is backed up or not. Without the secret for the new name, sops activation fails on that server. The command is idempotent and reads the generated files, so run it after just clean.

5. Validate

   just commit "refactor(maison): rename srv to srv-maison"

6. Deploy

   The node is addressed by its name, which must resolve from the administration machine. The safest option is to redirect ssh to its address during the first deployment.

   just roaming srv-maison 10.0.1.2
   just apply srv-maison
   just roaming-clear srv-maison

   Without a redirect, first deploy the gateway of the zone from which you administer : it then publishes the new name in its DNS.

7. Make the new name effective

   The deployment writes the static name, but the kernel one only changes at boot : hostname still returns the old name until the machine has rebooted.

   just reboot srv-maison

   To avoid the outage, set the name on the fly, then restart the services that read it at startup (the VPN client first).

   sudo hostname srv-maison
   sudo systemctl restart tailscaled

   Do not use hostnamectl

   This command rewrites /etc/hostname, which is a link to the read-only store. The link would be replaced by an ordinary file and the name would stop following the configuration on subsequent deployments.

   Before a remote reboot

   Check that no encrypted disk waits for a passphrase at boot, otherwise the machine stops in initrd, out of network reach.

Keeping the old name

The aliases field adds extra DNS names, useful for devices that keep the old name in a bookmark.

etc/config.yaml

- hostname: "srv-maison"
  aliases: ["srv"]

Scope limited to the zone

An alias is only published in its host’s zone, whereas the host name is published in all zones. The old name therefore only resolves from the local network of its zone.

Alias set in advance

Reserving the future name as an alias is convenient, but this alias must disappear in the same edit as the rename : an alias cannot carry the name of a host in its zone, the generator refuses the configuration.

Gateway case

A gateway carries the DNS and binary cache of its zone, hence two ordering rules :

• Deploy the gateway before its clients (their binary cache points to its name).
• Then deploy the gateways of the other zones, which publish the new name.

The VPN node keeps its key, its address and its approved routes. Only the displayed name stays frozen, to fix on the coordination server.

sudo headscale nodes list
sudo headscale nodes rename <nouveau-nom> -i <identifiant>

Never delete the node

Deleting then re-enrolling releases the tailnet’s fixed address and clears the approved routes. See VPN.

After the rename

• Supervision : the host label changes, the graph history is cut.
• Silences : those carrying the old name must be recreated.
• Backups : if the host backs up, rename its repository on the server, otherwise an empty repository is created.
• Tooling : the old node leaves the hive, any script that references it fails loudly.

Final check

just apply srv-maison build confirms that the node exists and that its configuration evaluates. After deployment, just enter srv-maison then hostname must return the new name. See Network backups for renaming a restic repository.