Authentication realms: LDAP, AD and sync jobs · Proxmox VE

A realm answers one question — is this person who they claim to be — and nothing else. It does not decide what they can do; that is the ACL model, and it stays entirely separate. The value of getting realms right is that joiners and leavers stop being a Proxmox task.

The failure this lesson exists to prevent is specific and common: an estate where the directory is the source of truth for identity everywhere except the hypervisor, so a person who left three months ago still has a working pve account with PVEVMAdmin on the production pool.

The realms you can configure

Type	Backing store	Use it for
`pam`	Local Linux users in `/etc/passwd`	`root@pam` only
`pve`	`/etc/pve/user.cfg`	Service accounts and token owners
`ldap`	Any LDAPv3 directory	Human accounts, non-Microsoft directory
`ad`	Active Directory	Human accounts, Microsoft directory
`openid`	An OIDC provider	Human accounts behind an SSO IdP

pam and pve are not a scaling problem so much as an evidence problem. A local account has no lifecycle owner outside Proxmox, so nothing outside Proxmox will ever tell you it should be gone. Keep them for the two cases that genuinely cannot use the directory: root@pam, and service identities that own API tokens.

Configuring the realm

Four things matter and the rest is detail: the servers, the transport, the bind account, and the base DN.

Configuration changean Active Directory realm over LDAPS— Creates the realm. No user can log in through it until the sync runs or --autocreate is enabled. Storing the bind password writes it to /etc/pve/priv/realm/, which is root-readable only.

AD_DOMAIN='corp.example.com'
BIND_DN='CN=svc-proxmox,OU=Service Accounts,DC=corp,DC=example,DC=com'
BASE_DN='OU=Staff,DC=corp,DC=example,DC=com'
GROUP_DN='OU=Groups,DC=corp,DC=example,DC=com'

pveum realm add corp --type ad \
--domain "$AD_DOMAIN" \
--server1 dc01.corp.example.com \
--server2 dc02.corp.example.com \
--port 636 \
--secure 1 \
--verify 1 \
--capath /etc/ssl/certs \
--bind-dn "$BIND_DN" \
--base-dn "$BASE_DN" \
--group-dn "$GROUP_DN" \
--comment 'Corporate AD, staff OU only'

The bind password is supplied interactively or with --password, and it is stored under /etc/pve/priv/ where only root can read it. It is also replicated to every node by pmxcfs, which is correct — every node authenticates independently — and worth knowing when you scope the bind account: it exists on every node in the cluster, so treat it as a cluster-wide credential.

Four options carry more weight than their length suggests.

--secure 1 with --port 636 is LDAPS. Without it the bind password and every username crosses the network in the clear. There is no reason to run a realm without TLS in 2026; if the directory does not offer it, that is a directory problem to escalate, not a Proxmox setting to skip.

--verify 1 validates the directory’s certificate. It is not the default. A realm with --secure 1 and --verify 0 encrypts the traffic and accepts any certificate, which stops passive capture and does nothing about an active attacker. Turning verification on and pointing --capath at the CA bundle — or --cacert at an internal CA file — is the difference between transport encryption and authenticated transport.

A narrow --base-dn. Scoping to the OU that holds staff accounts rather than the domain root means a sync cannot pull in service accounts, disabled accounts in a tombstone OU, or a contractor OU nobody told you about. It is also much faster on a large directory.

A read-only bind account. The bind account needs to read user and group objects and nothing more. It should not be a domain admin, and it should be excluded from any policy that expires or rotates it silently, because when it stops working nobody can log in.

Verify the realm before anyone depends on it

A realm that cannot reach the directory produces a login failure indistinguishable from a wrong password, and the first person to discover it is usually someone trying to respond to an incident.

Test the bind path independently before the realm is anyone’s only way in — ldapsearch against the same server, port, bind DN and base DN tells you whether the failure is Proxmox or the directory:

BIND_DN='CN=svc-proxmox,OU=Service Accounts,DC=corp,DC=example,DC=com'
BASE_DN='OU=Staff,DC=corp,DC=example,DC=com'
ldapsearch -x -H ldaps://dc01.corp.example.com:636 \
  -D "$BIND_DN" -W -b "$BASE_DN" \
  '(sAMAccountName=alice)' dn memberOf

Keep root@pam working with TFA and a stored credential for exactly this case. That is not a break-glass account with the controls removed; it is the account that was always there, kept usable.

Mapping directory groups onto Proxmox groups

This is the part that turns a realm from an authentication convenience into an authorisation mechanism.

Proxmox does not read AD group membership at permission-check time. The sync job reads it, creates a matching Proxmox group, and populates its membership. Your ACLs then reference the Proxmox group. The chain is:

AD group → synced PVE group → ACL entry → privileges on a path.

Change someone’s AD group membership and the next sync moves them between PVE groups; their permissions change without anybody touching an ACL. That is the entire point.

Configuration changebind ACLs to synced groups, once— Assigns roles to groups that the sync will populate. These entries are written once and never edited again; membership changes arrive through the directory.

pveum acl modify /pool/production --groups 'pve-vm-admins' --roles PVEVMAdmin
pveum acl modify /              --groups 'pve-auditors'  --roles PVEAuditor
pveum acl modify /nodes         --groups 'pve-node-ops'  --roles PVESysAdmin

The group names on the Proxmox side are whatever the directory group names sync to. Naming the AD groups with a pve- prefix is worth doing on day one: it makes the AD side self-documenting, and it means a search of the directory for who can administer the hypervisor returns an answer.

The sync job

pveum realm sync reads the directory and reconciles PVE users and groups against it. It is the operation that carries risk, because it can delete things.

Configure its defaults on the realm so that a scheduled run and a manual run behave identically:

Configuration changeset the sync defaults on the realm— Stores the options the sync will use when run without arguments, including by the scheduled job. Setting them here rather than on the command line is what makes a manual run match a scheduled one.

pveum realm modify corp \
--sync-defaults-options 'scope=both,enable-new=0,remove-vanished=acl;properties' \
--user-classes 'user' \
--user-filter '(&(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))' \
--group-filter '(&(objectClass=group)(cn=pve-*))' \
--sync_attributes 'email=mail,firstname=givenName,lastname=sn'

Reading those left to right:

scope=both syncs users and groups. users or groups alone are for staged rollouts and for directories where groups come from somewhere else.
enable-new=0 creates newly discovered users in a disabled state. They exist, they appear in the GUI, and they cannot log in until someone enables them. On a first sync against a large directory this is the difference between an inventory and an access grant.
remove-vanished is the leaver policy, covered below.
--user-filter is doing real work in that example: the userAccountControl bit-and filter excludes accounts disabled in AD, so a disabled AD account never becomes an enabled PVE user.
--group-filter restricts the sync to groups whose name starts with pve-, which keeps several thousand irrelevant AD groups out of user.cfg.
--sync_attributes maps directory attributes onto PVE user properties, so the email that backup-failure notifications go to is the one in the directory.

Always dry-run first

Read-only / Safepreview the reconciliation— Read-only. Performs the full directory query and prints what it would change, writing nothing. This is the only safe way to run a sync whose filters or remove-vanished policy have changed.

pveum realm sync corp --dry-run 1

Read the output before you commit it. Two numbers matter more than the rest: how many users it would create, and how many it would remove. A sync that proposes to remove most of your users has almost always got a filter wrong or lost its connection to a part of the directory tree — that is a configuration bug presenting as a mass deletion, and the dry-run is where you catch it.

Read-only / Safea dry run that should stop you— Illustrative. The removal count is the line to read first: forty-one vanished users on a routine sync is a filter or connectivity problem, not forty-one leavers.

$ pveum realm sync corp --dry-run 1

starting sync for realm corp (dry-run)
users:  found 3, created 0, updated 3
groups: found 2, created 0, updated 2
vanished users: 41 (would remove: acl, properties)
sync finished (dry-run, nothing written)

Illustrative output

The leaver policy

remove-vanished takes a semicolon-separated list of what to clean up when a user or group is no longer returned by the directory query. The three values, and what each one actually means for the departing person:

Value	Effect	The risk it leaves
(unset)	Nothing is removed	The account persists with all its ACLs. This is the state that leaves a leaver with `PVEVMAdmin`.
`acl`	ACL entries referencing the principal are deleted	The user object remains but grants nothing. Auditable, reversible, safe.
`properties`	Synced attributes not present in the directory are cleared	Email and name go stale-free; no authorisation change.
`entry`	The user or group object is deleted from `user.cfg`	Immediate and complete — and it removes the evidence along with the access.

acl;properties is the policy to default to. It removes the access on the next sync, keeps the user object so an audit can still see that the account existed and what it used to hold, and is undone by re-adding one ACL if the removal was wrong.

entry is defensible when a compliance requirement demands that identities be deleted rather than deactivated, and it should be a deliberate decision recorded somewhere, not a default someone copied.

Scheduling it

The sync is a datacenter-level job, configured under Datacenter → Permissions → Realms → realm → Sync options, with the schedule set on the realm. A daily sync is the usual cadence — it bounds how long a leaver keeps access to one day, which is what most access-control policies actually ask for.

Do not schedule a sync that has never been dry-run with its current filters. And send its notifications somewhere a human reads: a sync that has been failing for six weeks looks exactly like a sync that has nothing to do.

Under the hood

What the sync writes, and why membership is a snapshot rather than a lookup.

Realm definitions live in /etc/pve/domains.cfg; the bind password lives separately under /etc/pve/priv/. Both are pmxcfs files, so a realm configured on one node is configured on all of them, and the credential is present on every node — which is the reason a compromised node is a compromised bind account.

The sync itself writes into /etc/pve/user.cfg, the same file the ACL model uses. This is why directory membership is a snapshot: at permission-check time Proxmox reads user.cfg and never contacts the directory. Authentication contacts the directory; authorisation does not.

Three consequences follow, and they are all operationally visible.

Removing someone from an AD group does not remove their Proxmox access until the next sync runs. The window is your sync interval. If your offboarding SLA is shorter than that interval, the sync is not your offboarding control and something else has to be — usually disabling the AD account, which blocks authentication immediately and therefore blocks everything.

Disabling the AD account is the fast path. Authentication is live against the directory, so a disabled or locked account fails at login on the next attempt, regardless of what user.cfg still says. That is the lever to pull during an incident; the sync then tidies up behind it.

A user who is deleted from user.cfg but still exists in the directory comes back on the next sync, with no ACLs, because ACLs are separate records. Deleting the user object by hand as a revocation is therefore both ineffective and confusing — the account reappears and the audit trail of what it held is gone.

The realm is also consulted for TFA. TFA settings are stored per user in /etc/pve/priv/tfa.cfg, not in the directory, so a realm can require TFA while the second factor itself remains Proxmox-side. Deleting and recreating a user through a sync with remove-vanished=entry therefore discards their enrolled factors.

What happens if the directory is unreachable when someone tries to log in?

Authentication against that realm fails, for everyone in it, immediately. There is no cached-credential fallback: PVE binds to the directory on every login attempt.

The GUI reports a generic authentication failure. It does not say “the directory is down”, which means the first hypothesis of whoever is locked out is that they typed their password wrong, and the second is that their account was disabled. Neither leads anywhere. Expect several minutes of confusion before somebody checks the realm.

What still works: root@pam, because PAM is local. Any account in the pve realm, because user.cfg is local. SSH to the node with a key, because that is sshd and not pveproxy. And every already-issued API token, because token authentication reads user.cfg and never touches the directory — which is worth knowing in both directions, since it also means a token belonging to a departed user keeps working while the directory is down.

--server2 covers the common case of one DC being unavailable; PVE tries the second server when the first does not answer. It does not cover a network path that is down for both, a firewall change that blocked port 636, or an expired certificate on the directory side once --verify 1 is on — which is a failure that arrives on a specific date, all at once, for every node.

The operational conclusion is not to weaken the realm. It is to make sure the local path is genuinely usable: root@pam with TFA enrolled and its recovery keys stored where the on-call engineer can reach them, tested often enough that somebody knows it works.

Common mistakes

--secure 1 without --verify 1. Encrypted and unauthenticated. Set --capath or --cacert and turn verification on.
Base DN at the domain root. Slow, and it pulls in every service and disabled account in the directory.
No --dry-run before changing a filter. The dry run is where a mass removal is a number on a screen instead of an incident.
remove-vanished=entry on a scheduled job. The sync’s own failure mode looks identical to a mass departure, and entry makes it destructive.
Assuming an AD group change revokes access immediately. It revokes at the next sync. Disabling the account revokes at the next login attempt.
A bind account subject to the normal password-rotation policy. When it expires, nobody can log in, and the error message does not say why.

Key takeaways

Realms authenticate; ACLs authorise. Changing one never changes the other.
Map directory groups onto PVE groups and bind ACLs to the groups. After that, joiners and leavers are a directory operation.
enable-new=0 makes a first sync an inventory rather than an access grant.
remove-vanished=acl;properties removes access, keeps evidence, and survives a sync that misfires. entry does not.
Always --dry-run 1 after changing a filter, a base DN or the remove-vanished policy, and read the removal count first.
The fast revocation is disabling the directory account, because authentication is live and authorisation is a snapshot.

Knowledge check

Why this matters

Directory integration is usually sold as convenience — one password, fewer accounts. That is true and it is the least interesting part.

What it actually buys is that Proxmox stops being a place where identity decisions are made. Somebody joins, somebody leaves, somebody changes team: those events already have an owner, a process and an audit trail somewhere in the organisation. Every account that lives only in /etc/pve/user.cfg is an identity that process does not know about, and the organisation will find out about it during an audit or during an incident, neither of which is a good time.

The two settings that decide whether you get that benefit are the group mapping and the leaver policy. Without group mapping, you have single sign-on and a hand-maintained ACL list, which is the same maintenance burden with an extra dependency. Without a leaver policy, you have a directory that grants access and never revokes it.

And the honest caveat: the sync is a daily reconciliation, not a control plane. It bounds exposure to a day. When you need revocation in minutes — a compromised credential, a hostile departure — the lever is disabling the account in the directory, because authentication is the live path. Knowing which of the two to reach for, and that they operate on different timescales, is the difference between a revocation that happened and one that is scheduled for 02:00.