Configuration, retention and verification

The Configuration tab centralizes the settings that ensure the durability, cleanliness, and integrity of your PBS datastore.

---

Namespaces

Namespaces allow logical segmentation of backups within a single datastore. They are stored as a nested directory structure, requiring no additional configuration.

Use cases

• Separate multiple Proxmox VE clusters sharing the same datastore (overlapping VMIDs)
• Isolate environments: prod, preprod, dev
• Compartmentalize by client or project in a hosting context

Nested structure

Namespaces are hierarchical, expressed using slash notation:

/
├── prod/
│   ├── vm-infra/
│   └── vm-clients/
├── preprod/
└── client-a/

Creation

From the Configuration tab → Namespaces:

1. Enter the Namespace name (e.g. prod)
2. Select the Parent (/ for root, or an existing namespace)
3. Click +

Multi-cluster

If you back up multiple Proxmox VE clusters with identical VMIDs, use one namespace per cluster to avoid naming conflicts in the datastore.

---

Prune job (retention)

Pruning removes old snapshots according to your retention policy. It only removes metadata (manifest, index, logs) — actual chunks are only freed by Garbage Collection.

Available retention options

Option	Behavior
keep-last N	Keep the last N snapshots regardless of date
keep-hourly N	Keep the most recent snapshot for each of the last N hours
keep-daily N	Keep the most recent snapshot for each of the last N days
keep-weekly N	Keep the most recent snapshot for each of the last N weeks
keep-monthly N	Keep the most recent snapshot for each of the last N months
keep-yearly N	Keep the most recent snapshot for each of the last N years

ISO weeks

Weeks start on Monday and end on Sunday (ISO 8601 standard).

Example: daily backups, 10-year retention

From the official PBS documentation:

Option	Value	Reason
keep-last	3	Keeps recent manual backups before/after operations
keep-daily	13	At least 2 weeks (in addition to keep-last)
keep-weekly	8	At least 2 full months
keep-monthly	11	One year of monthly points
keep-yearly	9	Long-term archive — 9 additional years

Minimal example: typical use

keep-last:    3
keep-daily:   5
keep-weekly:  3
keep-monthly: 1

Prune simulator

Test your policy with the PBS prune simulator before applying it.

---

Garbage Collection (GC)

Garbage Collection frees actual disk space by removing orphan chunks — blocks no longer referenced by any snapshot.

Prune vs GC

Operation	What it removes
Prune	Snapshot metadata (manifest, index)
GC	Physical chunks that became orphans after pruning

Prune alone frees no disk space. GC is essential.

How GC works internally

GC runs in two phases:

1. Mark phase: PBS reads all datastore indexes and updates the access time (atime) of each referenced chunk
2. Sweep phase: PBS scans all chunks and deletes those whose atime is older than the grace period threshold

Grace period: 24h05

PBS waits 24 hours and 5 minutes before deleting an orphan chunk. This delay is tied to the relatime mount option on Linux filesystems (atime is only updated if the file hasn't been accessed in over 24h). It prevents deletion of chunks still being written by an active backup job.

Operation order

Always run prune before GC. GC must run after prune has removed the metadata, to correctly identify newly orphaned chunks.

Recommended schedule

Frequency	Use case
Daily	High-churn environments with many snapshot deletions
Weekly	Standard case — good balance
Manual	After bulk snapshot deletion

---

Verification jobs

Verification jobs check backup integrity by verifying the checksum of each chunk.

Why verify?

Physical drives degrade over time — a phenomenon known as bit rot (silent data degradation). A seemingly intact backup can be corrupted with no visible signal.

Configuring a verification job

From Configuration → Verification Jobs → Add verification job:

Parameter	Recommendation
Frequency	Weekly (new snapshots) + Monthly (full re-verify)
Namespace	Target a specific namespace or the entire datastore
Ignore already verified	No for the full monthly job
Threads	1 reader, 4 verify threads (PBS default)

Recommended dual-job strategy

1. Daily or weekly job: verifies only recent, not-yet-verified snapshots
2. Monthly job: re-verifies all snapshots (detects bit rot on old backups)

warning

Verification confirms the integrity of stored chunks but does not guarantee that a VM will start correctly after restore. Always complement with real restore tests.

---

Recommended global schedule

Task	Frequency	Time
Backup job	Daily	02:00
Prune	Daily	03:00 (after backup)
Garbage Collection	Daily	04:00 (after prune, at least 1h later)
Verification (recent)	Weekly	Saturday 05:00
Verification (full)	Monthly	1st of month 05:00