Proxmox VE - edmozley/freeitsm GitHub Wiki

Proxmox VE servers

Since 3.1.0 Β· Contributed by Andrew Turbay (@turbay-a) in PR #167 Β· How it works underneath: Proxmox and Cloud Director β€” Developer Guide

FreeITSM reads the virtual machines, LXC containers, nodes, IP addresses and MAC addresses from one or more Proxmox VE servers and lists them under Asset Management β†’ Servers, next to vCenter. It only reads: nothing is ever changed in Proxmox.

You can add several servers. Each syncs on its own schedule, and its VMs are kept apart from every other server's.

Cloud Director too? See VMware Cloud Director. Both work the same way.

What you need

  • A Proxmox user who can manage permissions (for example root@pam), once, for the setup.
  • The address of a Proxmox node, normally https://<host>:8006.
  • The FreeITSM server able to reach port 8006 on that node.

1. A user for FreeITSM

  1. Proxmox web UI β†’ Datacenter β†’ Permissions β†’ Users β†’ Add.
  2. User name freeitsm, Realm Proxmox VE authentication server (pve). Use pve, not pam, so it isn't a Linux login.
  3. A password is optional: FreeITSM will use an API token, not the password.
  4. Add.

2. A read-only role

Datacenter β†’ Permissions β†’ Roles β†’ Create, name it FreeITSMSync, and tick:

Privilege Why
Sys.Audit the cluster and the node list
VM.Audit each VM's and container's configuration
Datastore.Audit storage, for disk sizes
VM.GuestAgent.Audit (Proxmox VE 9) or VM.Monitor (Proxmox VE 8) a VM's IP addresses, through the QEMU guest agent

Proxmox VE 9 removed VM.Monitor and split its job into the VM.GuestAgent.* privileges; VM.GuestAgent.Audit is the read-only one. Without either, every VM and container is still found, with its MAC addresses, but not a VM's IP addresses.

Give the role no write privilege. FreeITSM never needs one.

3. Give the role to the user

Datacenter β†’ Permissions β†’ Add β†’ User Permission: path /, user freeitsm@pve, role FreeITSMSync, Propagate on.

4. An API token (recommended)

A token has its own secret and can be revoked without touching the user.

  1. Datacenter β†’ Permissions β†’ API Tokens β†’ Add, user freeitsm@pve, Token ID itsm.
  2. Privilege Separation: untick it and the token has the user's permissions (simplest). Leave it ticked and you must also give the role to the token: Permissions β†’ Add β†’ API Token Permission, path /, token freeitsm@pve!itsm, role FreeITSMSync.
  3. Add. Proxmox shows the secret, a UUID, once. Copy it now; if it's lost, delete the token and make another.

That gives you two values: the Token ID freeitsm@pve!itsm and the secret.

5. Add the server in FreeITSM

Asset Management β†’ Settings β†’ Proxmox VE servers β†’ Add server:

Field Value
Name anything, e.g. pve-lab
Server address https://<host>:8006. https only: the secret travels with every request, so FreeITSM won't send it over plain http
User or API token freeitsm@pve!itsm (or a user such as freeitsm@pve, with its password)
Password the token secret (or the user's password). Stored encrypted, never shown again; leave it empty when editing to keep it
Sync every (minutes) 5 to 10080
Verify certificate ticked for a certificate from a trusted authority. Proxmox installs with its own self-signed certificate: untick it for that, or better, give Proxmox a trusted certificate
Active ticked

Save, then Test. It says how many nodes it can see. Then Sync now, and Show VMs.

IP addresses

  • VMs: Proxmox only knows a VM's address through the QEMU guest agent. Turn it on in the VM's Options β†’ QEMU Guest Agent, install qemu-guest-agent inside it (apt install qemu-guest-agent on Debian or Ubuntu), and restart the VM. Only addresses on the VM's own network cards are kept, so docker0, veth… and bridge interfaces inside the guest are skipped.
  • Containers: no agent needed; the address comes from the container's configuration. A container on DHCP shows no address, because Proxmox doesn't know its lease.

Keeping it in step

  • Sync hypervisors on the Servers page syncs vCenter, then every active Proxmox and Cloud Director server, with one result line for each. Anyone who can use Asset Management can press it, as for vCenter. Adding, changing and testing servers needs the Proxmox VE servers settings permission.
  • On a schedule, cron/proxmox_sync.php syncs every active server whose interval has passed. Run it every few minutes:
*/5 * * * *  php /var/www/html/cron/proxmox_sync.php >> /var/log/freeitsm-proxmox.log 2>&1

In Docker: docker exec <app container> php /var/www/html/cron/proxmox_sync.php, from the host's cron. On Windows, a Task Scheduler task running php.exe with the full path. It runs from the command line only; it can't be started from a browser.

When a VM disappears from the list

FreeITSM removes a VM only when a list it read successfully no longer has it:

  • A node that's offline keeps all its VMs.
  • A node that's online but whose list of VMs (or of containers) couldn't be read keeps those VMs.
  • The safety guard: if fewer than half of the VMs FreeITSM knows were seen in one sync, nothing is removed until a healthy sync confirms it. The usual cause is a permission or an offline node, not a real mass deletion.

A VM keeps its identity (server + VMID), so renaming it in Proxmox updates it rather than adding a second one.

Troubleshooting

What you see Likely cause
"Use an https:// address" The address starts http://. Proxmox serves its API on https, port 8006.
"Proxmox refused this request (HTTP 401)" Wrong token ID or secret, or the wrong realm: pve, not pam.
"Proxmox refused this request (HTTP 403)" The user or token has no permissions. Check step 3, and step 4 if Privilege Separation is ticked.
"Could not reach the Proxmox server: …" The address or port is wrong, or a firewall is in the way. The text after the colon says which.
"…SSL certificate problem…" Verify certificate is ticked and Proxmox has its self-signed certificate. Untick it, or install a trusted certificate.
"Connected, but the node list could not be read" The user lacks Sys.Audit on /.
A VM has no IP address The guest agent isn't running, or the role lacks VM.GuestAgent.Audit / VM.Monitor. For a container: it uses DHCP.
"Not reachable this cycle: pve2" or "pve2/qemu" That node, or that list on it, didn't answer. Its VMs are kept.
"SAFETY GUARD: only 3 of 40 known VMs were seen" Nothing was deleted. Check the nodes and the permissions, then sync again.

Related: VMware Cloud Director Β· Proxmox and Cloud Director β€” Developer Guide Β· Assets

FreeITSM β€” an open-source IT Service Management platform Β· github.com/edmozley/freeitsm Β· MIT licence

⚠️ **GitHub.com Fallback** ⚠️