Proxmox

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

Requirements

To connect vScope to a Proxmox environment, you will need:

1. Proxmox User Account & API Token: A user account with at least read permissions to the assets you want to inventory. The recommended role is PVEAuditor over / to allow vScope to see all assets. You will also need to create an API token for this user.
2. Network Access: Ensure vScope can reach the Proxmox API endpoint over the network (typically port 8006/TCP).
3. QEMU Guest Agent: For vScope to collect detailed information from virtual machines, such as guest OS information and IP addresses, the QEMU Guest Agent must be installed and running on the VMs.

Creating an API Token

To create an API token in Proxmox VE:

1. Log in to the Proxmox VE web interface.
2. Navigate to Datacenter > Permissions > API Tokens.
3. Click Add.
4. Select the User (e.g. vscope@pam) and assign a Token ID (e.g. vscope-inventory).
5. Ensure the Privilege Separation box is checked.
6. Click Add.
7. A window will appear in the Token ID and the Secret.
8. Important: Copy the Secret and store it securely, as it will not be shown again. You will use the full Token ID (<user@realm>!<tokenId>) and the Secret to authenticate in vScope.

Assigning permissions

Now you need to assign permissions to the token:

1. Stay in the same view. Navigate to Permissions.
2. Click Add > API Token Permission.
3. Set path to /.
4. Select your newly created token from the list.
5. Select role PVEAuditor.
6. Ensure the Propagate box is checked.
7. Click Add.

How to add the credential in vScope

1. Navigate to Discovery > Credentials and click Create Credential.
2. Select Proxmox as credential type.
3. Enter the Proxmox server URL (e.g., https://proxmox-server:8006).
4. In the Authorization Header field, provide the Token ID and Secret prefixed with PVEAPITOKEN= (i.e. PVEAPIToken=<tokenId>=<secret>)
5. Toggle on Accept all server certificates.
6. Click Test Credential to verify the connection and Save.

---

Common Errors / FAQ

Error	What happened?	Suggested action
Guest OS information or IP addresses are missing	The QEMU Guest Agent is likely not installed, running, or enabled on the VMs.	Install and enable the QEMU Guest Agent on your virtual machines to allow vScope to fetch this detailed information.