Renaming a homelab server sounds cosmetic. Change /etc/hostname, reboot, and move on.

In practice, a hostname becomes an identifier shared by several systems. SSH remembers it. Backup jobs record it. Monitoring uses it in alerts. Overlay networks display it. Scripts may contain it as a destination or a lock-file label. Changing the visible name while leaving those dependencies behind creates a machine with two identities: the new one on the prompt and the old one everywhere that matters.

I recently renamed a small remote backup server. The Linux change took seconds. The useful work was proving that everything around it still worked.

Inventory the old name first

Before changing anything, search the places that may treat the hostname as data:

rg -n 'old-hostname' ~/.ssh ~/.config ~/.local/bin

On the server, check scheduled jobs, service definitions and application configuration:

crontab -l
systemctl list-unit-files --state=enabled
rg -n 'old-hostname' ~/.config ~/.local /etc/systemd 2>/dev/null

The important question is not only “where is this string used?” It is “what role does it play here?”

  • A label in a dashboard can be changed freely.
  • A backup repository’s recorded host field affects how snapshots are filtered.
  • An SSH alias can be preserved while its destination changes.
  • A TLS certificate or DNS record may require a deliberate migration.
  • A script may use the name as both a connection target and a human-readable label.

Write the dependencies down before editing them. That list becomes the verification plan.

Separate the kinds of name

A homelab machine can have several names at once:

  1. The operating-system hostname returned by hostnamectl.
  2. A DNS name used by other devices on the LAN.
  3. An overlay-network name used away from home.
  4. An SSH alias in the client’s config.
  5. An application label used in alerts, dashboards and backup metadata.

They do not have to be identical. In fact, treating the SSH alias as a stable interface can make a rename safer. Scripts can continue connecting to a familiar alias while the alias points at the new DNS or overlay name.

A simple SSH entry keeps that indirection explicit:

Host remote-backup
    HostName new-hostname.example.invalid
    User backup-user
    IdentityFile ~/.ssh/remote-backup
    IdentitiesOnly yes

The script uses remote-backup; the physical machine can be renamed again without another sweep through every command.

Change the machine, then the surrounding systems

On a normal systemd-based Linux host, the operating-system rename is straightforward:

sudo hostnamectl hostname new-hostname
hostnamectl

Some services read the hostname only when they start. A reboot is the cleanest boundary when it is convenient, but I do not treat the reboot itself as verification. After the machine returns, I check the name locally and reconnect through every intended route.

Then I update the surrounding systems deliberately:

  • the overlay-network device name;
  • DNS records, if the hostname is used in DNS;
  • SSH aliases and pinned host entries;
  • backup job labels and filters;
  • monitoring target names and alert text;
  • dashboards and inventory notes;
  • any wake-on-LAN or recovery scripts that display the old name.

I do not blindly delete the old SSH host key. First I compare the key received through the new name with the key already pinned for the old one. A rename should not silently weaken host verification.

Backups need more than a connection test

A successful SSH login proves authentication and reachability. It does not prove that the backup path, repository permissions or backup metadata still behave as intended.

For a backup host, my minimum post-rename test is:

  1. Connect non-interactively with the same identity the scheduled job uses.
  2. Check that the destination path is readable and writable as that account.
  3. Run the real backup command.
  4. Confirm that a new snapshot exists.
  5. Run the repository integrity check.
  6. Read the monitoring result generated by that run.

If the backup tool records a host field, decide whether new snapshots should use the new name. Historical snapshots keeping the old hostname is not corruption; it is history. What matters is knowing that filters and retention rules do not accidentally ignore one side of the rename.

Keep compatibility temporary and visible

Sometimes the safest migration keeps the old alias working for a short period. That is useful when several clients cannot be updated together.

Compatibility should be explicit, not mysterious. Add a comment saying why the alias exists and when it can be removed. Otherwise the old name becomes permanent because nobody knows whether it is still needed.

I remove a compatibility alias only after searches for the old name return either nothing or intentionally retained historical references.

My final checklist

I consider a rename complete only when all of these are true:

  • hostnamectl reports the new name;
  • LAN and remote access resolve the intended target;
  • SSH host-key verification still works;
  • scheduled jobs reference a stable, tested destination;
  • monitoring uses the new human-readable label;
  • a real backup completes;
  • the new snapshot is visible;
  • the repository check passes;
  • the old name appears only in documented compatibility entries or history.

The command that changes a hostname is the smallest part of the job. The real task is tracing the name through every place where it became an assumption, then replacing those assumptions with stable interfaces and tests.