Installing PDM and connecting clusters · Proxmox VE

Installing PDM is the least interesting part of this lesson and takes about twenty minutes. The interesting part is what happens immediately afterwards, when you type an address, a username and a password into an “Add remote” dialog and, in doing so, create a durable credential on a production cluster that will still be there in three years.

Get the install wrong and you reinstall. Get the connection model wrong and you find out during a certificate renewal, or during a security review, or on the day someone deletes the PDM VM.

Sizing the host

PDM does very little computationally. It polls remotes, keeps RRD series, and serves an interface. The published requirements reflect that:

	Evaluation minimum	Recommended
CPU	64-bit x86-64/AMD64, 1+ core	Modern 64-bit Intel or AMD, 2+ cores
Memory	1 GiB	4 GiB minimum for the OS
Storage	more than 10 GB	40 GB or more free
Disk resilience	—	Hardware RAID with a battery-backed write cache, or a redundant ZFS setup
Network	one NIC	Redundant multi-gigabit NICs

The evaluation column is explicitly labelled as not for production. The recommended column carries the standard Proxmox warning that ZFS is not compatible with a hardware RAID controller — pick one.

There is only one 64-bit answer available, incidentally: the FAQ states PDM supports 64-bit CPUs only, with no future plans for 32-bit.

Where the PDM host lives

The requirements table tells you what to give PDM. It does not tell you where to put it, and that is the decision with consequences.

PDM is a small Debian host. The obvious place to run it is as a VM on one of your clusters, and that is entirely workable — with one property you must decide about deliberately rather than discover.

The circular dependency you can choose to accept

If PDM runs as a guest on cluster A, then during a cluster A outage you lose PDM, and with it the cross-cluster view you would use to see how bad the outage is and what else is affected.

That is not automatically wrong. PDM is a convenience layer, every cluster still has its own working interface on port 8006, and the incident is on cluster A regardless.

It becomes wrong in two specific situations. The first is when PDM is your only aggregated task log and incident timeline, so losing it costs you the evidence at exactly the moment you need it. The second is when the estate has grown to the point where nobody remembers which of eleven clusters a given service lives on without looking it up in PDM — at which point the lookup tool being unavailable during an outage is a genuine operational problem.

The mitigations, in increasing order of cost: run PDM on the smallest, least loaded cluster rather than the busiest one; run it on a standalone node that is not a member of anything; or run two PDM instances on different clusters, which the roadmap notes already covers the high-availability gap in practice at the cost of doubled metric collection. Pick one on purpose and write down why.

Two network facts constrain the placement. PDM’s operators reach it over HTTPS, and PDM reaches every remote over each remote’s own API — port 8006 for Proxmox VE, port 8007 for Proxmox Backup Server. A PDM host behind a firewall that permits inbound management traffic but not outbound connections to your cluster networks is a PDM host that shows every remote as unreachable.

Which port does PDM listen on? 8443 — with a documentation wart

Two places in the PDM documentation state the answer clearly and agree with each other. The web interface chapter says the interface is reached at https://youripaddress:8443, and the service-daemon section says proxmox-datacenter-api exposes the whole API on TCP port 8443 using HTTPS.

One place disagrees. The technology-stack bullet list in the introduction chapter says “Communication occurs over TCP port 443 (HTTPS)”. That line conflicts with the other two and appears to be inherited boilerplate.

Use 8443. It is what the installation notes, the interface chapter and the daemon documentation all say, and it is what the firewall rule should permit. If you are writing a firewall change for a security review, verify against your own host with ss -ltnp rather than citing a doc page — this is a small example of why a young product deserves the extra confirmation step.

Two ways to install

The ISO. Download the installer image from the Proxmox downloads page. It is a hybrid image: burn it to a DVD or write it to a USB flash drive of at least 2 GB. On Linux, dd bs=1M conv=fdatasync writes it; on Windows, Etcher works directly and Rufus needs DD mode; on macOS, convert with hdiutil first. The documentation names one tool that does not work at all — do not use UNetbootin with the Proxmox image.

The interactive installer partitions the disks, sets language, time zone and network, and installs everything. There is also an unattended path driven by an answer file with filter rules for disk and NIC selection, which is worth knowing about because PDM 1.1 can serve exactly those answer files to other Proxmox installations.

On top of Debian. After configuring the repositories, two meta-packages are available and the choice between them is not cosmetic:

Configuration changeminimal install, keeping the Debian kernel— Installs a minimal required package set and leaves the running Debian kernel in place.

apt update
apt install proxmox-datacenter-manager-container-meta

Configuration changefull install, Proxmox kernel with ZFS support— Pulls in the Proxmox default kernel. Reboot required to run it.

apt update
apt install proxmox-datacenter-manager-meta

The first keeps the current Debian kernel and installs the minimum. The second installs the Proxmox default kernel with ZFS support. If PDM is running as a VM or a container on storage that is already redundant underneath it, the Proxmox kernel buys you nothing and costs you a kernel to patch; if PDM is on bare metal and you want a redundant ZFS root, you need it.

Repositories

PDM follows the Proxmox pattern exactly: a Debian base repository plus one Proxmox repository, in deb822 .sources format under /etc/apt/sources.list.d/.

The enterprise repository is enabled by default and is the stable, recommended one:

# /etc/apt/sources.list.d/pdm-enterprise.sources
Types: deb
URIs: https://enterprise.proxmox.com/debian/pdm
Suites: trixie
Components: pdm-enterprise
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg

The no-subscription repository is for testing and non-production use, and goes in /etc/apt/sources.list.d/proxmox.sources:

Types: deb
URIs: http://download.proxmox.com/debian/pdm
Suites: trixie
Components: pdm-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg

There is a third, pdm-test, which the documentation warns should only be used to test new features or bug fixes. It has no place in an estate you care about.

How PDM earns enterprise repository access

There is no dedicated PDM subscription. You cannot buy one.

Instead, PDM can use the enterprise repository if at least 80% of the configured remote nodes have a valid Basic or higher subscription. Existing Basic-or-higher subscriptions on your PVE and PBS remotes include PDM enterprise repository access and support at no extra cost.

Two consequences. First, the percentage is computed over configured remote nodes, so adding a lab cluster full of unsubscribed nodes to PDM can push you under the threshold and cost you enterprise access on the tool itself. Second, this is a good reason to care about the subscription registry that shipped in 1.1: a central pool with per-node assignment makes the 80% figure something you can see and manage rather than something you discover.

Two operational notes on Trixie. apt will complain about legacy repository definitions, and apt modernize-sources converts them. And upgrades must use apt full-upgrade, never apt upgrade: PDM uses a rolling release model on top of Debian, and apt upgrade cannot remove packages to satisfy dependencies, so it can leave a partially upgraded or broken package state.

Read-only / Safeconfirm SecureApt before trusting the repository— Expected SHA256 for the Trixie-era Proxmox archive keyring, per the PDM installation chapter. Once proxmox-archive-keyring is installed it manages this file and the hash may legitimately change.

# sha256sum /usr/share/keyrings/proxmox-archive-keyring.gpg

136673be77aba35dcce385b28737689ad64fd785a797e57897589aed08db6e45  /usr/share/keyrings/proxmox-archive-keyring.gpg

After installation, the interface is at https://<pdm-host>:8443 and the initial login is root in the pam realm, using the password set during installation or the existing root password on a Debian-based install.

The remote model

Now the part that matters.

A remote is one entry in /etc/proxmox-datacenter-manager/remotes.cfg. There are two section types, pve and pbs, and both take the same four required properties plus one optional:

Property	Meaning	Why it bites
`type`	`pve` or `pbs`, default `pve`	Determines which API surface PDM expects
`nodes`	A list of cluster node addresses; may be given more than once	A single-entry list makes one node a single point of failure for the whole remote
`authid`	The authentication ID PDM authenticates as	This is the identity every PDM action is attributed to in the cluster’s log
`token`	The access token secret	Stored on the PDM host, in cleartext, in a config file
`web-url`	Optional, for generating Web UI links	What “Open in PVE UI” points at; wrong here means a dead link, not a broken remote

Read the nodes row twice. PDM talks to a cluster through the node addresses you gave it. A cluster is quorate and healthy, one node is down for memory replacement, and if that node was the only address in the list, PDM reports the entire remote as unreachable. List several — ideally all of them, or at least three — and PDM has somewhere else to go.

Configuration changeadding a PVE cluster as a remote from the CLI— Run on the PDM host. The token must already exist on the target cluster. Values shown use documentation-reserved addresses.

proxmox-datacenter-manager-admin remote add \
--id site-a \
--type pve \
--nodes 192.0.2.11 \
--nodes 192.0.2.12 \
--nodes 192.0.2.13 \
--authid 'pdm@pve!datacenter-manager' \
--token 'REPLACE_ME'

Read-only / Safewhat PDM thinks it is managing— Lists configured remotes. Pair it with remote version to confirm PDM can actually reach each one.

# proxmox-datacenter-manager-admin remote list --output-format text

The companion commands are remote update <id> for changing the node list, authid, token or web URL; remote version <id> to confirm PDM can reach a remote and see what it is running; remote subscriptions for the fleet subscription picture; and remote remove <id>, which has a flag worth its own section.

remote remove deletes the token on the cluster by default — keep it that way

proxmox-datacenter-manager-admin remote remove <id> takes --delete-token <boolean>, and the default is true. Set it to false and token deletion on the remote is skipped.

The default is the safe behaviour and you should almost never override it. The token PDM authenticates with lives in the cluster’s own user.cfg, not in PDM. Removing the remote without removing the token leaves a valid, privileged credential on a production cluster with nothing on the other end of it — no owner, no rotation schedule, and no log entry when it is eventually used by somebody who found it in a backup of remotes.cfg.

The same hazard arrives by a route that has no flag at all: destroying the PDM host. There is no remote remove in that story, so every cluster keeps its orphaned token. If you are decommissioning or rebuilding PDM, remove the remotes first, then destroy the host.

Trust, and the certificate that will rotate

PDM validates a remote’s TLS certificate against the system certificate store. This produces two quite different operational worlds.

If the remote presents a publicly trusted certificate — for example one issued by Let’s Encrypt through ACME, which Part III covers configuring — then no further trust configuration is needed and certificate renewals are handled transparently. Nothing breaks in ninety days. This is the reason to do the ACME work.

If the remote presents the default self-signed Proxmox certificate, PDM pins the fingerprint you accepted when you added the remote. That pin is a snapshot of a certificate that has an expiry date.

When the remote renews or rotates that certificate, the pinned fingerprint no longer matches and every connection to that remote fails, with an error the interface and CLI both surface:

connection failed: Could not establish a TLS connection. Check whether the
fingerprint matches or the certificate on the remote is valid. OpenSSL Error:
error:0A000086:SSL routines:tls_post_process_server_certificate:certificate
verify failed

The most common cause is a legitimate renewal. It can also mean an expired or otherwise invalid certificate — or, if the change is unexpected, a man-in-the-middle attack. The documentation says to confirm the new certificate through a trusted channel before accepting it, and that instruction is the whole reason pinning exists. An operator who clicks accept reflexively has converted a security control into a dialog box.

Read-only / Safesee what the remote is presenting now— Probes the live certificate for one node of one remote. Read-only: it inspects, it does not store anything.

# proxmox-datacenter-manager-client remote probe-certificate site-a pve-01

Configuration changestore a verified fingerprint, or clear the pin— Only after confirming the certificate through a channel that is not the connection you are fixing. Omitting the fingerprint clears the pin, which is correct when the remote has moved to a publicly trusted certificate.

FPR='REPLACE_WITH_VERIFIED_FINGERPRINT'
proxmox-datacenter-manager-client remote set-fingerprint site-a pve-01 "$FPR"

# clearing the pin, for a remote that now uses a trusted certificate
proxmox-datacenter-manager-client remote set-fingerprint site-a pve-01

In the web interface, the equivalent is the Check Certificate action on the remote. PDM 1.1 improved it into a dialog that re-probes the configured nodes, lets you accept the new fingerprint per node or clear the stored pin, and applies the changes as one batch. It is reachable from the remotes list and is offered directly on a remote whose connection is currently failing.

The system journal on the PDM host records additional detail, including both the fingerprint the remote presented and the one that was expected — which is the evidence you compare against your trusted channel.

Under the hood

Why is the pin per node rather than per remote?

Because a remote is a cluster, and every node in a cluster has its own certificate. pmxcfs replicates cluster configuration, but each node’s API certificate is issued for that node’s name and lives in that node’s /etc/pve/nodes/<name>/. PDM stores a fingerprint for each node address it was given.

This is why the 1.1 re-pin dialog re-probes the configured nodes, plural, and accepts or clears per node in one batch. It is also why a partial failure is a normal state: rotate the certificate on one node of a five-node cluster and PDM’s connection to that node fails while the other four keep working. The remote does not go down; it degrades, and depending on which node PDM happened to try, an operator may see intermittent errors rather than a clean failure.

Two practical consequences. Rotate certificates cluster-wide in one maintenance action rather than node by node, so the re-pin is one batch rather than five separate mysteries. And when a remote is behaving intermittently, check the pins before you check the network — this failure mode looks exactly like a flaky link.

The token is the whole permission story

remote add needs an authid and a token. Everything PDM does on that cluster, forever, it does as that identity, bounded by that identity’s PVE-side privileges.

That has an immediate design consequence and a deferred one.

The immediate one: the PDM documentation does not prescribe a role for this token. It tells you the field exists and what shape the value takes. What privileges to grant is your decision, made once, on a cluster, in a pveum command — and it is the decision that determines whether a compromised PDM host can read your estate or reconfigure it.

The deferred one is lesson 5, which treats this properly. For now, three rules that hold regardless of how you resolve the design:

A dedicated user and token per remote. Not root@pam. Not one token reused across clusters. One identity per remote means one thing to revoke, and a cluster’s task log that names PDM rather than naming root.
Privilege separation on the PVE side. Part XV covers --privsep 1: the token carries its own ACLs rather than inheriting the user’s. That is what lets you grant the token less than the user has.
Write down what you granted. In six months, “what can PDM do on site-B” must be answerable from a document, not from an archaeology session in user.cfg.

Order of operations for adding a cluster to PDM

Do these in this order. Steps 1 through 3 happen on the cluster; only step 4 happens on PDM.

Create a dedicated user on the cluster in a realm you control, with no password login if the cluster permits it. Do not reuse a human account.
Create an API token for that user with privilege separation on, and record the secret once — the cluster shows it once.
Grant the token exactly the ACL you decided on, at the path you decided on, and record both in the design document.
Add the remote in PDM, listing at least three node addresses for a multi-node cluster, and confirm with remote version.
Verify the certificate posture. If the cluster uses ACME, confirm PDM did not need to pin anything. If it uses the self-signed default, record the pinned fingerprint and put the certificate expiry in the same calendar that holds your other renewals — because PDM will not warn you before it breaks.
Confirm the remote appears with live data, not just as configured. A remote that is configured but never collected looks similar in a list and very different on a dashboard.

What happens if you restore an old PDM backup?

PDM’s state is a directory: /etc/proxmox-datacenter-manager/ holds remotes.cfg with an authid and token secret per remote, access/acl.cfg, access/shadow.json with local password hashes, views.cfg, and the API certificate and key under auth/. Back it up, because rebuilding it means re-minting a token on every cluster.

Restoring an old copy is where it gets interesting, because that directory contains credentials and pins, and both drift.

A rotated token means the restored secret is stale. The remote fails to authenticate, and the failure looks like a permissions problem rather than a restore problem.
A rotated certificate means the restored pin is stale, and you get the TLS error above on a remote you did not touch.
A removed remote can come back to life. Restoring a remotes.cfg from before a decommission re-adds a cluster you deliberately disconnected, and PDM starts polling it again.
Restored ACLs undo revocations. access/acl.cfg from before an operator left restores that operator’s permissions on every path they had.

None of this is exotic; it is the ordinary property of backing up a file that contains secrets. The handling is ordinary too: treat a PDM restore as a change that requires verification, and after any restore run remote list and remote version across every remote and reconcile the result against what the estate is supposed to be today, not against what it was on the backup date.

Key takeaways

PDM is small: 2 cores, 4 GiB, 40 GB is the recommended shape. The decision that matters is placement, and running PDM inside a cluster it manages is a circular dependency you may accept, but must accept on purpose.
The ISO is the recommended install. The Debian route assumes you have already got the base system, storage and network right.
Enterprise repository access needs no PDM subscription, but does need at least 80% of configured remote nodes carrying Basic or higher.
Upgrade with apt full-upgrade. apt upgrade can leave PDM in a partially upgraded state.
A remote is a node list, an authid, a token and a type. List several node addresses so one node’s maintenance does not take the remote offline.
remote remove deletes the token on the cluster by default. Keep that default, and remove remotes before destroying a PDM host.
A publicly trusted certificate on the remote means renewals are transparent. A self-signed one means PDM pins a fingerprint that will one day stop matching, per node, with a TLS error that also happens to be what an attack looks like.

Knowledge check

Why this matters

Two things happen during a PDM installation and only one of them looks like a decision.

Installing the packages, choosing a repository, setting a hostname — those look like decisions and are almost entirely reversible. Reinstalling PDM costs an afternoon and nothing else.

Adding a remote does not look like a decision. It looks like filling in a dialog. But it mints a durable credential on a production cluster, records a trust anchor whose expiry nobody is tracking, and establishes an identity that will appear in that cluster’s task log for years. Every one of those is hard to change later, and two of them are security decisions being made by whoever happened to be doing the setup.

That asymmetry is the reason this lesson spends four paragraphs on installation and the rest on connection. The install is the part you can redo. The trust model is the part that outlives the person who configured it.