Proxmox

Integrating Proxmox Virtual Environment (VE) with vScope provides a detailed inventory of your virtual infrastructure, collecting data on hosts, virtual machines, containers, storage and networking.

Connecting vScope to Proxmox

Note

You will need administrator access to your Proxmox VE web interface.

Step 1: Create a User for vScope in Proxmox

1. Log in to the Proxmox VE web interface.
2. Navigate to Datacenter → Permissions → Users and click Add.
3. Enter a User name like vscope and select your preferred Realm (e.g., PAM).
4. Set a strong password.
5. Click Add.

Step 2: Grant Read-Only Permissions

1. Navigate to Datacenter → Permissions and click Add → User Permission.
2. Set Path to /, select the vscope user, and choose the PVEAuditor Role.
3. Ensure Propagate is checked and click Add.

Step 3: Create an API Token

1. Navigate to Datacenter > Permissions > API Tokens and click Add.
2. Select the vscope@pam User and give the token a Token ID (e.g., vscope-inventory-token).
3. Ensure Privilege Separation is checked and click Add.
4. Important: Copy the Token ID and Secret. You’ll need these when adding your credential in vScope.

Step 4: Assign Permissions to the API Token

1. Go to Permissions, click Add > API Token Permission.
2. Set the Path to /, select your new token, and assign the PVEAuditor Role.
3. Make sure Propagate is checked and click Add.

Step 5: Add the Proxmox Credential to vScope

1. In vScope, navigate to Discovery > Credentials and click Create Credential.
2. Select Proxmox.
3. Enter your Proxmox server URL (e.g., https://proxmox-server:8006).
4. In the Authorization Header field, enter PVEAPIToken= followed by your token ID and secret. It should look like this: PVEAPIToken=vscope@pam!vscope-inventory-token=your-secret-value.
5. Toggle on Accept all server certificates only if the Proxmox server uses a self-signed certificate.
6. Click Test Credential to verify, then Save.

Troubleshooting

Missing data in vScope?

Insufficiant permissions on either the user or the token can lead to discovery failure or missing data. The log output might show this error message:

Failed to get data from /api2/json/nodes/proxmox1/status: Unsuccessful response with status code:403
and body: {"data":null,"message":"Permission check failed (/nodes/prox,ox1, Sys.Audit)\n"}

Make sure you have granted read access, i.e. Sys.Audit permissions, to all enpoints. The permissions page (Datacenter > Permissions > Users/Api Tokens ) should look similar to this:

Connection reset

Another reason for discovery failure could be that the connection timed out and closed, possibily caused by a firewall blocking the communication.

1. From the vScope machine, open a browser and go to https://proxmox-server:8006/api2/json/version.
2. Expect an HTTP 401 response because no authentication is provided. This confirms the API is reachable.
3. If there is no response, open a shell on the Proxmox server and run:

curl -vk https://127.0.0.1:8006/api2/json/version

You should see output similar to:

* Connected to 127.0.0.1 (127.0.0.1) port 8006
* using HTTP/1.x
> GET /api2/json/version HTTP/1.1
> Host: 127.0.0.1:8006

4. If there is no response locally, confirm the API services are running:

systemctl status pveproxy --no-pager
systemctl status pvedaemon --no-pager

If the API is reachable locally on the Proxmox server but not from vScope, a firewall or network policy is likely blocking access to port 8006/TCP.

Guest OS information or IP addresses are missing

Make sure that the QEMU Guest Agent is installed, running, and enabled on your virtual machines.