Browse documentation
Showing guest IP addresses
When you import a VM or container from a Proxmox host, JOATOS can give it an IP address automatically, so it can be pinged and scanned straight away. Without an address, an imported VM can't be polled at all.
Proxmox only knows a VM's address if the QEMU guest agent tells it. This page covers what that needs, how to check it's working, and which address JOATOS picks.
What you need
All four must be in place for a VM:
| # | Requirement | Where |
|---|---|---|
| 1 | Site Collector 0.13.0 or later on the collector that polls the Proxmox host | Your collector host |
| 2 | The API token can read guest agent information | Proxmox → Datacenter → Permissions |
| 3 | QEMU Guest Agent is enabled in the VM's options, followed by a full stop and start | Proxmox → the VM → Options |
| 4 | The guest agent is installed and running inside the VM | Inside the guest operating system |
Containers (LXC) need only items 1 and 2. Proxmox reads a container's addresses directly — nothing to install or enable.
The VM or container must be running. Stopped guests are not asked for an address.
1. Site Collector version
Guest addresses are collected by the Site Collector. Check its version under Settings → Site Collectors — an Update available badge means it's behind. To update it, see Updating the Site Collector.
2. API token permissions
The token JOATOS uses for the Proxmox host needs permission to ask the guest agent for network details.
| Proxmox version | What the token needs |
|---|---|
| Proxmox VE 9 | PVEAuditor on / (with Propagate) already covers it (VM.GuestAgent.Audit) — no change if that's what you granted. |
| Proxmox VE 8 | PVEAuditor is not enough. Also grant a role that includes VM.Monitor. |
Containers only need VM.Audit, which PVEAuditor includes on both versions.
If the token has Privilege Separation ticked, it has only the permissions granted to the token itself — not those of its user.
3. Enable the QEMU Guest Agent option
- In Proxmox, open the VM and select Options.
- Double-click QEMU Guest Agent, tick Use QEMU Guest Agent, and select OK.
- Shut the VM down completely, then start it again.
⚠ A restart is not enough. The option only takes effect when the VM is started from powered off. Restarting from inside the guest — or anything that doesn't fully stop the VM — leaves the change pending, and the option can look disabled again afterwards.
From the Proxmox host shell:
qm pending <vmid> | grep agent # "new agent: 1" means it's still waiting for a full stop/start
qm shutdown <vmid> && qm wait <vmid> && qm start <vmid>
qm config <vmid> shows pending values as if they were live, so it can say agent: 1 before the change has applied. Use qm pending to tell the difference.
4. Install the guest agent inside the VM
| Guest | What to do |
|---|---|
| Home Assistant OS | Nothing — the agent is built in. |
| Debian / Ubuntu | sudo apt install qemu-guest-agent, then sudo systemctl start qemu-guest-agent (or reboot). |
| RHEL / Rocky / Alma / Fedora | sudo dnf install qemu-guest-agent, then sudo systemctl enable --now qemu-guest-agent. |
| Windows (desktop or server) | Attach the VirtIO drivers ISO (virtio-win.iso) to the VM's CD/DVD drive and run virtio-win-guest-tools.exe from it. This installs the VirtIO serial driver and the QEMU Guest Agent service — installing only the agent MSI isn't enough if the driver is missing. Check with Get-Service QEMU-GA (should be Running). |
| Network appliances (firewalls, routers, switches) | Usually no agent is available. Set the address by hand — see below. |
Checking it works
On the Proxmox host:
qm agent <vmid> ping
qm agent <vmid> network-get-interfaces | grep -E '"name"|"ip-address"'
pingprints nothing when it works. An error such as QEMU guest agent is not running means the agent isn't installed, isn't running, or step 3's full stop/start hasn't happened.- In the interfaces output, each adapter's addresses are printed above its
"name"— Proxmox sorts the fields alphabetically.
Once ping succeeds, the address reaches JOATOS within one poll of the Proxmox host (its scanning profile interval — five minutes by default).
Which address JOATOS uses
A guest often reports several addresses. JOATOS keeps IPv4 addresses only, in the order the guest reports its adapters, and polls the first one. It leaves out:
- Loopback (
127.x.x.x) and link-local (169.254.x.x) addresses - Container and virtual bridges named
lo,docker…,br-…,veth…,virbr…orhassio - All IPv6 addresses
Windows hosts running Hyper-V show virtual adapters named vEthernet (…). These are not left out, because on a host with an external virtual switch that adapter is the real network connection. If an internal switch adapter has a usable address and is listed before the management adapter, JOATOS may poll the wrong one — set the address by hand for that host.
When the address is set, and when it isn't
- Importing a guest copies its addresses to the new server.
- Importing a guest that matches an existing server by name links them, and fills in the address only if that server has none.
- A VM imported before its agent was working gets its address filled in automatically once the agent reports — as long as the server still has no address.
- An address you've entered yourself is never replaced.
- A later change of the guest's IP is not picked up once an address is set. Update it under Edit → Connection address.
To set or correct an address yourself, open the server, select Edit, and fill in Connection address.
Troubleshooting
| Symptom | Likely cause |
|---|---|
qm agent <vmid> ping errors | Agent not installed/running in the guest, or the VM hasn't had a full stop/start since the option was enabled. |
| QEMU Guest Agent looks disabled again after a restart | The change was pending — do a full stop and start (step 3). |
ping works but no address appears after five minutes | Site Collector older than 0.13.0, or the API token lacks the permission in step 2 (Proxmox VE 8 needs VM.Monitor). |
| The server was given the wrong address | Another adapter was listed first (common on Hyper-V hosts). Set Connection address by hand. |
| A firewall, router or switch VM never gets an address | The appliance has no guest agent. Set the address by hand. |
Notes & tips
- VMware and Hyper-V hosts don't use this — see Supported platforms.
- Having an address lets JOATOS reach a VM; what it can collect still depends on the VM's scanning profile and credential. See Choosing a collection method.