Every security checklist tells you to "rotate your keys and credentials on a schedule." Nobody tells you that in Proxmox Backup Server, that sentence hides two completely different jobs with two completely different costs. Treat them the same and you either rotate too often (and pay for it in re-transferred storage) or too rarely (and leave a stale credential live for years).
- PBS has no `key rotate` command. Rotating the client encryption key means generating a new keyfile and pointing the client at it going forward.
- Chunk IDs are derived from the active key via HMAC, so a new encryption key starts a fresh deduplication domain. The next backup after rotation transfers like a full seed, not an increment.
- Old snapshots stay encrypted with the old key forever. You must keep every retired keyfile until the last snapshot it protects is pruned.
- API tokens and remote credentials have none of that baggage. Rotate them on a calendar, same as you would any service account.
- A master key (covered in the encryption internals post) softens the blast radius of key rotation, but it does not remove the dedup reset.
- Stagger rotation dates across tokens instead of expiring everything on the same day, or one missed renewal takes down every automated job at once.
Two Rotations, Two Different Risk Profiles
"Rotate your credentials" usually means: create a new secret, phase out the old one, done. That model works fine for API tokens. It does not work for the client-side encryption key, because the encryption key is not just a secret, it is the input to the function that decides what counts as a duplicate chunk.
PBS derives each chunk's ID from an HMAC-SHA-256 over the plaintext, keyed by material from the active keyring. Change the key and every chunk your client uploads next gets a new ID, even for data that is byte-for-byte identical to something already sitting in the datastore under the old key. Deduplication only matches chunks that share an ID. Two keyrings never do.
That single fact drives almost every decision in this post. Token rotation is a scheduling problem. Encryption key rotation is a storage and restore-planning problem that happens to also involve a secret.
If you have not read how the keyfile itself needs to be stored and backed up, do that first. This post is about the mechanics and cost of rotating an existing key, not initial key management. See PBS encryption internals for the storage pattern.
What Actually Breaks When You Rotate the Encryption Key Carelessly
Walk through the failure modes before you touch anything, because none of them announce themselves until weeks later.
Restores fail silently until you notice the wrong key is loaded. A snapshot taken under key A cannot be decrypted with key B. If you delete or overwrite the old keyfile the moment you generate a new one, every snapshot older than that moment becomes permanent noise on disk: present in the datastore, unreadable forever.
Your next backup job balloons in size and duration. The first run after rotation cannot deduplicate against anything already in the datastore, because none of the existing chunk IDs were computed with the new key. If your normal incremental transfers a few GB, expect the post-rotation run to transfer close to the full dataset size, over the network, to every target the sync job touches.
Garbage collection stops reclaiming space the way you expect. Chunks from the old keyring stay referenced as long as any snapshot under the old key exists. garbage-collection only removes chunks with zero live references; it has no concept of "this key is retired," only "this chunk is unreferenced."
If a snapshot taken under an old key is still present in any datastore (including offsite sync targets), the old keyfile is not optional history, it is the only thing that can open that data. Prune the snapshots first, confirm they are gone everywhere, and only then retire the keyfile.
Rotating the Client-Side Encryption Key
Rotation here is really: generate a new key, run alongside the old one for as long as old snapshots exist, and retire the old key only once nothing depends on it.
Before You Rotate
- A tested backup of the CURRENT keyfile (paperkey or vault copy), confirmed recoverable
- Enough datastore headroom for one full-size, non-deduplicated backup cycle
- A note of every host, sync job, and remote that references the current key
Run proxmox-backup-client key create and give it a distinct, dated filename. Do not overwrite the existing keyfile in place.
Paperkey it, vault it, store it offline, the same way the current key is stored. A key you have not backed up is not a key you can rotate to.
Update the client config (or the --keyfile argument in your backup command) to reference the new file. Existing scheduled jobs need this change applied everywhere they run, not just on one host.
Confirm a snapshot taken under the new key restores cleanly before you rely on the automated schedule. Also confirm the transfer size you expected: no dedup match against the old key is normal here, not a bug.
Move it to cold storage labeled with its retirement date. It stays load-bearing until every snapshot it protects is pruned from every datastore and sync target.
Once your prune/retention policy has aged out everything created before the rotation date, the old key has no remaining live data. Only then does it become truly retired, and even then, most operators keep one archived copy indefinitely as a safety margin.
If you run a master key alongside the daily keyfile, rotating the daily key is cheaper on the recovery side (the master private key never changes and unwraps data keys from either era), but it does not touch the dedup problem. A new daily key still means a new HMAC input, still means a fresh dedup domain. Master key escrow and daily key rotation solve different problems and you need both.
If offsite sync jobs run nightly, a same-day key rotation on the source means that night's sync also transfers at full size, not incremental. Schedule rotations for a maintenance window, not the middle of a normal backup week, so the storage and bandwidth spike is expected rather than alarming.
Rotating API Tokens and Automation Credentials
This is the easy half. API tokens carry none of the dedup or restore-path baggage the encryption key does, because they authenticate access, they do not shape what gets stored or how.
Overlap old and new instead of a hard cutover:
proxmox-backup-manager user generate-token \
backup-automation@pbs offsite-sync-2026-08 \
--expire 7776000 \
--comment "Replaces offsite-sync-2026-05, rotate quarterly"Update every script, sync job, and monitoring integration that references the old token, one at a time, confirming each one succeeds against the new token before moving to the next. Only revoke the old token once nothing is using it:
proxmox-backup-manager user list-tokens backup-automation@pbs
proxmox-backup-manager user delete-token \
backup-automation@pbs offsite-sync-2026-05The API automation guide covers scoping tokens correctly in the first place, which matters more for blast radius than rotation frequency does. A tightly scoped token that leaks does far less damage than a broadly scoped one, rotation schedule notwithstanding.
Rotating Sync Job and Remote Credentials
Remote definitions (proxmox-backup-manager remote create) store a token for authenticating to the far end of a sync job. When you rotate the token on the target PBS instance, every remote entry on every source instance pointing at it needs the update, or the next sync run fails auth and the job just stops, often silently until someone checks the task log.
Before revoking an old token on the target, list every source instance with a remote entry referencing it. A quick way to catch this ahead of time: keep a plain text inventory of which remote name, on which source host, uses which token comment. It is not glamorous, but it is the difference between a planned five-minute update and an unplanned 2am page when overnight sync jobs fail.
If multiple sites sync into one central remote target (the pattern covered in the multi-site MSP architecture post), stagger the update: confirm one source's sync job succeeds on the new token before rolling it out to the rest. A typo in one remote config is a lot easier to isolate when it is the only one you changed that day.
Building a Rotation Schedule That Survives Contact With Reality
A schedule nobody follows is worse than no schedule, because it shows up as a checkbox in an audit without reflecting reality.
| Credential | API tokens (automation, sync) | User passwords / TOTP resets | Client encryption key | Master key (RSA escrow pair) |
|---|---|---|---|---|
Baseline cadence | Quarterly | As per your access policy | Only on a real trigger, not a fixed calendar | Rarely, on organizational change only |
Also rotate immediately on | Staff offboarding, suspected leak | Role change, suspected phishing | Suspected compromise, decommissioned host, offboarding someone who had the keyfile | Loss of trust in the storage holding the private half |
Operational cost of rotating | Low: create, migrate callers, revoke | Low | High: dedup reset, full-size re-transfer, indefinite retention of the old key | Medium: reissue public half to all clients, old wrapped data keys remain valid |
The practical takeaway: put tokens on a calendar, because rotating them is cheap and the compliance story (see the GDPR/SOC 2/ISO 27001 post for what auditors want to see) rewards regularity. Do not put the encryption key on the same calendar. Rotate it when there is a real reason: someone with keyfile access left, a host that held it was decommissioned or compromised, or you are moving to a master-key-backed model and want a clean cutover point. A key rotated for no reason on a fixed schedule buys you nothing except repeated full-size backup runs.
Stagger token expiry dates across your automation instead of issuing them all on the same day. If a dozen tokens created together all expire together and the renewal script has a bug, every job that depends on PBS access fails on the same night.
Common Mistakes
- Deleting the old encryption keyfile right after generating a new one. The new key protects nothing that already exists on disk. Every prior snapshot still needs the old key.
- Rotating the encryption key on a fixed quarterly schedule out of habit. That habit is correct for tokens. For the encryption key it just means paying the full-size re-transfer cost four times a year for no security benefit beyond what a triggered rotation already gives you.
- Rotating a remote's token without checking who else points at it. One missed source instance means a silently failing sync job until someone notices the offsite copy is stale.
- Not testing a restore under the new key before retiring the old one. Confirming the new key exists is not the same as confirming it works.
- Storing only one copy of a freshly rotated key. The moment a new key protects live backups, it needs the same paperkey/vault treatment as the key it replaced. See the keyfile backup pattern here.
Wrapping Up
Encryption key rotation and credential rotation get lumped together under one security checklist item, but they behave nothing alike inside Proxmox Backup Server. Tokens rotate cheaply and belong on a calendar. The encryption key changes what counts as a duplicate chunk, so it belongs on a trigger, not a date, and it demands that you keep every retired key alive until its last snapshot ages out. Get that distinction into your runbook and rotation stops being a source of surprise storage bills or unreadable backups.
remote-backups.com issues scoped, per-client credentials on encrypted PBS datastores in EU datacenters, so a rotation on your end never touches anyone else's access.
View Plans
