Move or re-link a node
A KVM node accepts commands from exactly one panel. This page explains how that link works, how to release a node so a different panel can take it over, and what to update when an IP address changes.
Proxmox VE nodes are linked through an API token instead and are not covered here.
How the link works
Section titled “How the link works”When you click Add Hypervisor for a KVM node, the panel calls the agent on port 2443. On that first call the agent:
- Generates a token, stores its hash and the IP address the request came from, and returns the token to the panel.
- Returns its TLS certificate, which the panel pins so it only ever talks to that exact certificate on port 2443.
The agent keeps this in a single file, master.json, in the agent service user’s home directory. On a current install that is:
/home/virtconsole/master.jsonOlder installs may use /home/hypervisor/master.json. To be sure, check the service user’s home:
getent passwd virtconsole | cut -d: -f6From then on the link works in both directions:
- The agent accepts a command only when it carries that token and comes from the stored panel IP address. Anything else is answered
403 Unauthorized. - The panel accepts a report from the node only when it comes from the IP address on the node’s hypervisor record and carries the matching token. Anything else is answered
401 Hypervisor not authenticated.
A node can be linked once. While master.json exists, every further link request is refused with The slave is already linked to <panel IP>, whichever panel sends it.
Release a node from a panel that can still reach it
Section titled “Release a node from a panel that can still reach it”This is the normal path, for example before you move a node to a different panel:
- Move or destroy the node’s instances. Remove refuses while instances remain.
- In the current panel, open the hypervisor and click Remove, then confirm.
The panel asks the agent to unlink, which deletes master.json, and then deletes the hypervisor record. The node is now free to be added to any panel.
Release a node by hand
Section titled “Release a node by hand”Use this when the panel that linked the node is gone, reinstalled, or can no longer reach the node, so Remove cannot ask the agent to unlink. The new panel’s Add Hypervisor then fails with The slave is already linked to <old panel IP>.
On the node, as root, move the link file aside. Keep the copy until the new link works:
H=$(getent passwd virtconsole | cut -d: -f6)mv "$H/master.json" "$H/master.json.bak-$(date +%F)"From this moment the node accepts no commands from any panel until it is linked again, so do the next step straight away:
- In the new panel, go to Infrastructure > Hypervisors and click Add Hypervisor.
- Choose KVM Agent and enter the node’s name, its current IP address and its group. See Hypervisors.
- Open the new hypervisor and check that it shows Online and that Verifies node TLS reads
yes(see Agent channel security).
When the new link works, delete the backup file:
rm "$H"/master.json.bak-*If the old panel still has a record for this node, delete it there with Remove and then Force. The node no longer answers that panel, so its record only goes stale.
Instances that already run on the node
Section titled “Instances that already run on the node”Linking a node to a new panel adds the hypervisor only. The new panel does not know the virtual machines already running there, and nothing on the node is changed or stopped. To manage them from the new panel, adopt them with Orphan VM import.
The node’s IP address changed
Section titled “The node’s IP address changed”Do not delete master.json. The node still trusts the same panel. Only the panel’s record of the node is out of date: the panel now rejects every call the node makes to it with 401 Hypervisor not authenticated. The node’s own syncs fail (security groups, VPC, DNS, task updates), and after a reboot the node cannot start its instances, because its boot recovery service first fetches the VPC state from the panel and retries until that succeeds.
- In the panel, open the hypervisor and click Edit on the Node card.
- Set IP address to the node’s new public address and save.
Saving sends the node’s configuration again, and the node’s next call to the panel is accepted. A boot recovery that was retrying then completes on its own within 30 seconds and starts the instances. The certificate pin stays valid, because it is tied to the certificate, not to the address.
If the node also has a Private IP for migrations, update that in the same dialog when it changed.
The panel’s IP address changed
Section titled “The panel’s IP address changed”Do not delete master.json either. The node still has the right token but now refuses the panel’s commands, because they come from an address it does not know. Commands from the panel fail and the node answers 403 Unauthorized.
On each node, as root, replace the stored panel address. sed -i keeps the file’s owner and permissions:
H=$(getent passwd virtconsole | cut -d: -f6)cp -p "$H/master.json" "$H/master.json.bak-$(date +%F)"sed -i 's/"ip": "OLD_PANEL_IP"/"ip": "NEW_PANEL_IP"/' "$H/master.json"grep '"ip"' "$H/master.json"The node uses this one address for two things: it accepts commands only from it, and it sends its own reports to https://<address>/api/v1/slave/. So it must be the panel’s own address, the one its requests to the node come from and the one that answers HTTPS directly (not a CDN or proxy address). You can check the panel’s outbound address from the panel host with curl -s https://api.ipify.org.
No restart is needed: the agent reads the file on every request. Run any action against the node from the panel (for example open the hypervisor page) to confirm it answers, then delete the backup file.
If many nodes need the same change, you can also release and re-link each one (see above). Editing the address keeps every pin and token, so it is the faster option.
Troubleshooting
Section titled “Troubleshooting”| What you see | Cause | Fix |
|---|---|---|
The slave is already linked to <IP> when adding a node |
The node is still linked to a panel | Remove it from that panel, or release it by hand |
Node log shows 401 Hypervisor not authenticated, instances do not start after a node reboot |
The node’s IP address changed | Update the node’s IP address in the panel |
Panel commands to the node fail, node log shows authenticated from an unauthorized IP |
The panel’s IP address changed | Update the stored panel address on the node |
| Node certificate changed, re-link on the hypervisor page | The node presents a different certificate than the pinned one | See Agent channel security |
The node’s own log is storage/logs/lumen.log under the agent install directory (/opt/virtconsole on a current install).

