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 disk, stateVersion, hardware inventory and machine-specific settings leave the built configuration.

3. Regenerate

   just clean

4. Create the backup account

   just configure-admin-host

   Otherwise the backup server no longer starts

   A restic server declares a secret per hostname in the fleet, whether the host is backed up or not. Without the secret for the new name, the sops activation fails on this 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 is to redirect ssh to its address for the first deployment.

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

   Without redirection, first deploy the gateway of the zone you administer from: 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 interruption, set the name on the fly, then restart the services that read it at their start (the VPN client first).

   sudo hostname srv-maison
   sudo systemctl restart tailscaled

   Do not go through hostnamectl

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

   Before a remote reboot

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

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 the binary cache of its zone, hence two ordering rules:

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

The VPN node keeps its key, address and routes. Only its name remains the old one: just tailnet-enroll renames it based on the configuration.

just tailnet-enroll <nouveau-nom>

Never delete the node

Deleting then re-enrolling assigns a new tailnet address: vpn.ipv4 and everything pointing to the old address would need to be redone. 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.