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-token). The user does not need to be in the pam realm.
5. Keep Privilege Separation checked.
6. Optional: add a Comment (e.g. Used by vScope) and leave Expire as never.
7. Click Add.
8. A window will appear showing the Token ID and Secret.

9. 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=.

For example:

PVEAPIToken=vscope@pam!vscope-inventory-token=your-secret

5. Toggle on Accept all server certificates only if the Proxmox server uses a self-signed certificate.
6. Click Test Credential to verify the connection and Save.

---

Troubleshooting

Connection reset

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

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.