PDM Documentation

Overview

PDM monitoring provides a centralized Home Assistant view of the Proxmox VE and Proxmox Backup Server environments managed by one Proxmox Datacenter Manager connection.

It is designed for Datacenter-level visibility: overall status, aggregate capacity, centralized inventory, available updates and the state of configured PVE/PBS remotes.

PDM complements direct connections

PDM does not recreate the detailed monitoring supplied by direct PVE, PBS or Cluster connections.

Use PDM when you want to see several managed environments together. Keep direct connections when you need node hardware, individual VM/LXC entities, detailed backup operations or supported actions.

Current V5.2 scope

The current implementation creates:

• one PDM root device;
• Datacenter Status, Datacenter Inventory, Datacenter Capacity and Datacenter Updates sensors;
• one child device for every configured PVE or PBS remote;
• Remote Status and Remote Overview sensors for each remote.

PDM V5.2 does not create individual VM or container entities and does not provide PDM actions or buttons.

Continue with Configuration to add a connection or Datacenter Monitoring to understand the centralized view.

Configuration

Add PDM as its own Proxmox Extended Sensors configuration entry in Home Assistant.

Open:

Settings → Devices & services → Add Integration

Search for Proxmox Extended Sensors, enter the PDM server address and select Proxmox Datacenter Manager as the server type.

Server address

Enter a hostname or IPv4 address without a protocol, path or port. The integration uses the PDM HTTPS API on port 8443 automatically.

IPv6 addresses are not currently accepted for PDM connections.

Credentials

The PDM flow goes directly to API Token credentials. Enter:

• User — including its realm;
• Token ID;
• Token Secret;
• Verify SSL Certificate — according to the certificate trusted by Home Assistant.

The connection must provide the remote inventory and Datacenter status required for initial setup. Access to version, detailed resources, subscriptions and updates is checked separately, so restricted permissions can leave some information unavailable without changing the connection into a different server type.

After setup, the integration creates the PDM root device and discovers its configured remotes dynamically.

Authentication

PDM connections use API Token authentication. Password authentication is not offered by the current PDM configuration flow.

Use a dedicated PDM account and token for Proxmox Extended Sensors. Home Assistant requires the user including its realm, the Token ID and the Token Secret as separate values.

The token secret is a credential. Never include it in screenshots, logs, issues or other public material.

Access requirements

The token must be able to read the configured remote inventory and aggregate Datacenter status. Additional read access is needed for detailed resources, subscription state, version information and the update summary.

The exact least-privilege PDM role and ACL recipe is still pending documentation. Until that contract has been validated for the supported PDM version, do not present an unverified permission set as sufficient for every sensor.

If authentication succeeds but a data area is missing, compare the token’s permissions with the affected feature before recreating the connection.

Datacenter Monitoring

The PDM root device presents the information that belongs to the managed Datacenter as a whole.

Datacenter Status

Datacenter Status reports Good when the known remotes are healthy and no failed remote is reported; otherwise it reports Degraded.

Its attributes summarize the total PVE/PBS remotes, failed remotes and the freshness of the polled PDM sections.

Datacenter Inventory

Datacenter Inventory summarizes the resources reported through PDM. Depending on the managed environments, its attributes can include PVE/PBS nodes, VMs, containers, PVE storage, PBS datastores and SDN zones.

Unknown categories remain unknown rather than being presented as zero.

Datacenter Capacity

Datacenter Capacity uses aggregate PVE and PBS information for CPU, memory and storage. Memory and storage are presented in GiB with calculated utilization percentages when both used and total values are available.

CPU is presented as used threads, available threads and—where PDM supplies it—allocated guest cores. CPU utilization is calculated from used threads divided by available threads.

This is an aggregate operational view. Direct PVE and PBS connections remain the detailed monitoring path for individual systems and resources.

Remotes

PDM exposes each configured PVE or PBS environment as a remote child device beneath the PDM root device.

A PVE remote represents one complete PVE cluster or one standalone PVE installation, not an individual node. One PDM server can manage multiple PVE remotes as well as independent PBS remotes.

Remote Status

Remote Status shows the state reported by PDM. Its attributes include the remote type, subscription state when available and whether the status section was refreshed successfully in the current poll.

Remote Overview

Remote Overview reports the total resources associated with that remote. Its attributes summarize the discovered inventory and aggregate CPU, memory and storage capacity available from the resource data.

Remotes are discovered dynamically. A temporary API error retains the last valid information and does not prove that a remote was removed. Removal is reconciled only from a fresh, valid remote inventory.

Updates

Datacenter Updates reports the total number of updates in the last complete update snapshot accepted from PDM.

The sensor attributes organize the snapshot by remote and node and can include:

• the raw query status reported by PDM;
• the raw repository status;
• the number of updates;
• package/version information;
• oldest and newest refresh timestamps;
• the age of the oldest refresh;
• endpoint and complete-snapshot freshness.

Repository status values are shown as supplied by PDM and are not reinterpreted by the integration. No arbitrary stale threshold is applied to the refresh age.

An API error, incomplete payload, missing configured remote or non-success query state does not replace the previous complete snapshot with zero. The last valid snapshot is retained while the freshness attributes expose the degraded poll.

The exact upstream cache/refresh cadence is controlled by PDM and remains pending further upstream documentation; the integration polls the summary every 60 seconds without claiming that the underlying node data was refreshed at the same time.

Troubleshooting

PDM problems are easier to diagnose when connection, authentication, permissions and temporary data availability are considered separately.

The PDM connection cannot be created

Verify:

• the hostname or IPv4 address, without https:// or a port;
• connectivity from Home Assistant to PDM port 8443;
• the complete user and realm;
• Token ID and Token Secret;
• the SSL verification setting and certificate trust.

Authentication works but some sensors are unavailable

Initial setup requires remote inventory and aggregate status, while resources, subscriptions, version and updates are separate data areas. A token can therefore connect but still lack access to some information.

Check the token permissions for the missing area. The exact least-privilege ACL recipe remains pending documentation.

A remote or value looks stale

Temporary endpoint failures retain last-known-good information. Check the freshness attributes before interpreting retained data as current.

For updates, distinguish endpoint freshness from the age of the PDM snapshot. A successful HTTP poll does not mean PDM has refreshed every managed node at that moment.

A remote disappeared from PDM

The integration removes a remote’s entities and owned child device only after a fresh remote inventory proves that it is absent. API errors or ambiguous data do not authorize cleanup.

Check Home Assistant logs

Open Settings → System → Logs and inspect entries from Proxmox Extended Sensors around the failed poll or setup attempt.

Remove credentials, token secrets, server addresses and other sensitive data before sharing logs publicly.

If the problem persists after these checks, use the project's GitHub issue tracker.