Renaming a Managed Computer
You can rename a Windows, Linux or Mac computer that runs the Hermes agent. The agent keeps its certificate, reconnects under the new name, and stays the same agent in the console with its history, tags and assignments. Nothing needs to be reinstalled or re-enrolled. This page explains what the agent does after a rename, how certificate files written by older agents are upgraded, and how to read the agent log if a certificate still can't be opened.
This behaviour is in agent 1.2.181 and later on Windows, Linux and macOS. 1.2.181 is the first release that uses one version number on all three platforms. Agents get it through a normal agent update.
Why a rename used to break the agent#
Each agent keeps the certificate and private key it received at enrolment in the file
agent.pfx, in its server folder (see Agent Data
Folder Layout). Older agents protected that file with a password derived from the computer
name. After a rename the agent could no longer open its own certificate, so it stopped connecting
for good. The log called this "Certificate has expired", even when the certificate was still
valid.
Current agents protect agent.pfx with the machine's stable identity
instead. A rename does not change this identity:
| Platform | Machine identity used | Changes when… |
|---|---|---|
| Windows | The machine GUID (MachineGuid under HKLM\SOFTWARE\Microsoft\Cryptography) | Windows is reinstalled or generalised (sysprep). |
| Linux | /etc/machine-id (or /var/lib/dbus/machine-id) | A new machine-id is generated, for example on a reinstalled or freshly cloned system. |
| macOS | The Mac's hardware UUID | The logic board is replaced. |
If the operating system provides no identity (for example a Linux system with no machine-id file), the agent falls back to the computer-name password used by older agents. On such a machine a rename still makes the certificate unreadable.
The certificate's protection does not depend on this password. Anyone who can read the
agent.pfx file can work it out. The key is protected by the data folder's permissions:
SYSTEM and Administrators only on Windows, root only on Linux and macOS.
What happens when you rename a computer#
- Rename the computer as usual. On Windows, the rename takes effect after the restart (a pending computer rename is one of the restart reasons Athena reports, see Restart Policies).
- When the agent starts, it opens
agent.pfxwith the machine identity and connects to the server as before. - Every heartbeat carries the computer's current name. The server stores the new name and the Agents list and agent details show it. The record, its history, tags and assignments stay the same, because the agent keeps its agent ID and certificate.
The agent also records every computer name it has run under in its local state. It uses that list to upgrade certificate files that are still protected with an old name (see the next section).
Automatic upgrade of older certificate files#
A computer enrolled with an older agent still has an agent.pfx protected with its computer
name. After the agent updates to a current version, the first start upgrades the file by itself:
- The agent tries the machine-identity password first.
- If that fails, it tries the computer-name password for the current name, then for every earlier name it knows. It reads earlier names from its own state and from the agent log files in its log folder. Up to 32 earlier names are tried.
- When one of them opens the file, the agent re-protects the file with the machine identity. It writes
the new copy alongside the old one and swaps it in, keeping the old file as
agent.pfx.bak. - At the next start that opens the certificate normally, the agent deletes
agent.pfx.bak.
This also covers a computer renamed while an older agent was running. That agent can't connect any more, so it can't receive an update from the console. The simplest fix is to rename the computer back to its old name and restart it. The older agent opens its certificate and reconnects. Update it to 1.2.181 or later, let it start once so the file is upgraded, then rename the computer again.
An agent that is already on 1.2.181 or later when it starts also searches its log files for earlier names. If a log from before the rename is still on disk, it can open and upgrade the file without the rename back.
Agent builds from before this change only know the computer-name password. They can't open a certificate file that has been upgraded to the machine identity. Keep upgraded computers on 1.2.181 or later.
HermesCLI on a renamed computer#
hermes status shows certificate details by reading
agent.pfx the same way as the agent: first with the machine identity, then with the current
computer-name password. The CLI that ships with the current agent therefore keeps working after a rename
and after the upgrade. The CLI itself never upgrades the file. Only the agent does that.
What the agent log shows#
Look for these lines in the agent log:
| Message | Meaning |
|---|---|
| "Certificate <path> was protected with a computer-name password; re-protected with the machine identity (old file kept as agent.pfx.bak)" | Warning, logged once: an older certificate file was upgraded. No action is needed. |
| "Loaded certificate: Subject=…, Thumbprint=…, Expires=…" | The certificate opened normally. |
| "Certificate <path> could not be read with this machine's password or any earlier computer name's (computer renamed? file corrupt?)" | Error: no password the agent knows opens the file. See below. |
| "Server '<name>': Certificate could not be read (computer renamed?). Connection disabled." | Error: because of the line above, the agent gave up on that server. Older agents logged "Certificate has expired" in this case. |
| "Server '<name>': Certificate has expired. Connection disabled." | The certificate opened but has really expired. A rename is not the cause; see Certificates & PKI. |
If the certificate still can't be read#
The "could not be read" error usually has one of these causes:
| Situation | What to do |
|---|---|
| An older agent's file, and the old computer name is in no log on the machine (logs cleaned up, or more than 32 names). | Rename the computer back to its earlier name and start the agent. It upgrades the file, and you can then rename the computer again. |
| The machine identity changed: Windows was generalised with sysprep, Linux got a new machine-id, or the Mac's logic board was replaced. This includes a disk image cloned from a machine that already had an enrolled agent. | The certificate belongs to the old identity. Enrol the computer again (see Agent Enrollment). Don't capture images with an enrolled agent in them. |
| The agent was rolled back to a build from before this change after the upgrade. | Put agent 1.2.181 or later back on the computer. |
| The file is damaged. | Enrol the computer again. |
If the agent reports to more than one server, each server has its
own agent.pfx, and each one is opened and upgraded separately.
Related#
- Agent Data Folder Layout: where
agent.pfxand the logs live. - Agent Logs: reading the agent log on the machine and from the console.
- Agent Binaries & Updates: getting agents onto 1.2.181 or later.
- Certificates & PKI: agent certificate lifetime, renewal and revocation.
- Windows Agent: when the agent stops itself.
- Agent Enrollment: enrolling a computer again.