Proxmox Backup Server Namespaces: Multi-Tenant Datastore Guide

Every Proxmox Backup Server datastore starts out simple: one flat list of backup groups, one per VM, container, or host client. That works fine until you're running backups for more than one Proxmox VE cluster against the same datastore, hosting backups for multiple customers on shared PBS infrastructure, or just trying to keep a homelab's "prod" and "test" VMs from being backed up, pruned, and synced with the same policy. Two VMs with the same VMID on different clusters will collide in a flat datastore. A customer you're delegating backup access to shouldn't be able to browse or restore another customer's snapshots. And a nightly prune job tuned for disposable test VMs will happily apply the same retention to VMs you actually care about, if they're all sitting in the same undivided pool.

Backup namespaces, introduced in Proxmox Backup Server 2.2 and refined in every release since, solve this by letting a single datastore behave like several independent ones. A namespace is a subdirectory inside a datastore that can hold its own backup groups and its own child namespaces, with its own permissions, its own prune policy, and its own place in a sync job's scope. This guide walks through how the namespace hierarchy works, how to create and use namespaces from both the PBS side and the Proxmox VE side, how permissions and delegation work at each level, and how prune and sync jobs target specific branches of the tree instead of the whole datastore. Everything here is current for Proxmox Backup Server 4.2.x and Proxmox VE 9.2.x, though the namespace feature itself has been stable since PBS 2.2.

Why Namespaces Exist

Before namespaces, a Proxmox Backup Server datastore had exactly one flat list of backup groups, each identified by a type (vm, ct, or host) and an ID. If two different Proxmox VE clusters both had a VM numbered 105, and both pointed their backup storage at the same PBS datastore, their backups landed in the same group and overwrote each other's history. The only workaround was a separate datastore — and a separate datastore means a separate underlying disk or partition, which is wasteful when you just want logical separation, not physical separation.

Namespaces fix this by giving you logical separation on top of one physical datastore. Three use cases come up constantly in practice:

Multiple Proxmox VE clusters, one PBS server. Give each cluster its own top-level namespace (site-a, site-b) so their VMIDs never collide, even if two clusters both happen to run a VM 100.
Multi-tenant or multi-customer backup hosting. Each customer gets a namespace, and you delegate permissions scoped to just that namespace — a customer can browse and restore their own backups without ever seeing another customer's group list.
Splitting policy by workload class. A production namespace with a long retention and daily verify jobs, and a disposable namespace for test/scratch VMs with a two-week retention and no verify job at all, both inside the same datastore.

None of this requires new disks, new datastores, or new PBS instances — it's purely a matter of how the existing datastore's backup groups are organized and who can touch which branch.

How the Namespace Hierarchy Works

Every datastore has an implicit root namespace, written as an empty string or sometimes shown as / in the UI. Underneath that root, you can create child namespaces, and underneath those, further children — down to a maximum depth of 8 levels, root included. A namespace path is written slash-separated, e.g. customer-a/prod or site-a/hypervisor-01. Each namespace level can directly hold backup groups (VM, CT, or host-type) and, independently, further child namespaces — a namespace isn't forced to be either "a container for backups" or "a container for other namespaces," it can be both at once. A backup group's full identity is therefore its namespace path plus its type and ID, which is why two clusters can each have a VM 105 without conflict as long as they're backing up into different namespaces.

Namespaces exist only as an organizational and access-control layer inside a single datastore — they don't span datastores, and a sync job or prune job always operates within the boundary of one datastore even when it's copying or pruning across several namespaces inside it.

Creating Namespaces

Via the Web GUI

In the Proxmox Backup Server web interface, select the target datastore from the left-hand tree.
Open the datastore's Content tab, where the namespace tree is shown alongside the backup group list.
Use the namespace selector/tree control to create a new namespace under the root (or under an existing namespace, to nest it further).
Give it a short, descriptive name — customer-a, site-b, prod. Namespace names follow the same restrictions as other PBS identifiers: no slashes inside a single segment, since the slash is the path separator between levels.

Via the CLI

The same operation from a shell on the PBS host, using proxmox-backup-client against the datastore:

proxmox-backup-client namespace create customer-a --repository root@pam@localhost:main-store

For a nested namespace, pass the full path:

proxmox-backup-client namespace create customer-a/prod --repository root@pam@localhost:main-store

List the namespaces that already exist in a datastore before creating a new one, so you don't end up with near-duplicate names like customer-a and customera:

proxmox-backup-client namespace list --repository root@pam@localhost:main-store

Namespaces are created lazily in one other common path too: if you back up directly into a namespace path that doesn't exist yet (covered next), PBS creates the missing namespace levels automatically rather than rejecting the backup — useful for automated onboarding where you don't want a separate "create the namespace" step for every new client.

Backing Up Into a Namespace

From proxmox-backup-client Directly (Host Backups)

For a bare-metal or non-Proxmox-VE Linux host backing up directly with proxmox-backup-client, target a namespace with the --ns flag on the backup command itself:

proxmox-backup-client backup web01.pxar:/etc web01-data.pxar:/srv \
  --repository backup-user@pbs@pbs.example.com:main-store \
  --ns customer-a/prod \
  --backup-id web01

Everything else about the backup command is unchanged — --ns just tells PBS which branch of the datastore's namespace tree this snapshot belongs under. Restore works the same way, with the namespace specified on the restore command rather than assumed from context:

proxmox-backup-client restore host/web01/2026-07-18T02:00:00Z root.pxar /tmp/restore \
  --repository backup-user@pbs@pbs.example.com:main-store \
  --ns customer-a/prod

From Proxmox VE (VM and LXC Backups)

PVE's vzdump doesn't take a per-job namespace override — a given backup job in Proxmox VE always writes into whatever namespace is baked into the PBS storage definition it's using. That storage definition is where the namespace lives, configured either when you add the storage or afterward:

pvesm add pbs customer-a-prod \
  --server pbs.example.com \
  --datastore main-store \
  --username backup-user@pbs \
  --fingerprint aa:bb:cc:...:zz \
  --namespace customer-a/prod

The practical consequence: if you want VMs on one Proxmox VE cluster to land in two different namespaces (say, prod for real workloads and disposable for test VMs), you add two PBS storage entries in Proxmox VE, pointing at the same server and the same underlying datastore but with different --namespace values, and then assign each VM's backup job to whichever storage entry matches its intended namespace. There's no way to pick a namespace per-VM within a single storage entry — the namespace is a property of the storage definition, not the backup job.

Once that storage entry exists, everything downstream works exactly as it would without namespaces — scheduled backup jobs under Datacenter → Backup, manual backups from the VM's Backup tab, and restores from the Proxmox VE GUI all transparently read and write within that storage entry's configured namespace, with no extra flags to remember.

Namespace Permissions and Delegation

This is the feature that makes namespaces genuinely useful for multi-tenant setups, not just a folder-naming convenience. PBS's access control lets you grant a role on a specific namespace path, rather than only on the datastore as a whole:

Viewing content inside a namespace requires at least one of the Audit, Modify, Read, or Backup privileges granted on that namespace (or inherited from a parent namespace or the datastore root).
Creating or deleting a namespace requires the Modify privilege on its parent namespace — you can't create customer-a/prod unless you have modify rights on customer-a (or higher up the tree).
Backing up into and restoring from a namespace follows the same group-ownership rules as a datastore without namespaces — a user needs the Backup privilege on the namespace, or to already own the specific backup group, and restore additionally requires read access to that group's contents.

In practice, this means you assign a permission at customer-a once, and it flows down to every namespace and backup group nested underneath — customer-a/prod, customer-a/test, and anything created later, without having to reassign permissions each time a new sub-namespace shows up. Set up the permission from the Access Control panel exactly as you would for a datastore-wide role, but pick the namespace path as the object instead of the datastore root, or use the equivalent proxmox-backup-manager acl update command with the namespace path.

Prune Jobs Scoped to a Namespace

A prune job in PBS already lets you set retention independently per job; namespaces let you point that retention at a specific branch of the tree instead of the whole datastore. When creating or editing a prune job, set the namespace field to the branch you want it to apply to, and optionally enable recursion into sub-namespaces if you want one policy to cover an entire tenant's namespace and all of its children in one job, rather than defining a separate prune job per sub-namespace.

This is where the "production vs. disposable" split pays off directly: a prune job scoped to disposable with keep-last=3 and no keep-weekly/keep-monthly at all, running alongside a separate prune job scoped to production with a much longer retention window — both against the same datastore, with zero risk of one policy accidentally touching the other's groups, since the namespace boundary is enforced by the job's scope, not by convention.

Sync Jobs Across Namespaces (Remote Replication)

Sync jobs — pulling backups from a remote PBS instance into a local datastore, or the reverse push-sync direction — are namespace-aware in both directions, controlled by three key parameters:

remote-ns — the namespace anchor on the remote side to sync from. Defaults to the remote's root namespace if unset.
ns — the namespace anchor on the local side to sync into. Defaults to the local root namespace if unset.
max-depth — how many levels of sub-namespaces under remote-ns to recurse into. A value of 0 syncs only the groups directly in remote-ns itself, with no recursion into its children; leaving it unset recurses through the full depth available.

A sync job with remote-ns: customer-a, ns: offsite/customer-a, and max-depth: 8 mirrors an entire customer's namespace subtree — including every nested sub-namespace under it — from the source PBS server into a differently-named branch on the destination, which is exactly the shape you want for an offsite replica that keeps each tenant's backups walled off on both ends.

Layer a group-filter on top when you want to sync some but not all groups within that namespace scope — filters accept type:vm, type:ct, or type:host to match by backup type, group:<name> to match a specific group, or regex:<pattern> for anything more flexible, and any of those can be inverted by prefixing it with exclude: to sync everything except what matches. Multiple group-filter entries are additive (a group syncs if it matches any of them), so a common pattern is one broad filter plus one or two exclude: filters to carve out exceptions.

Reorganizing: Moving Groups and Namespaces

Namespace layouts aren't fixed once chosen. A backup group can be relocated to a different namespace within the same datastore without a full re-backup, using the group-move operation — handy when a VM originally landed in the wrong tenant's namespace, or when you're consolidating a flat pre-namespace datastore into a proper hierarchy after the fact. Whole namespaces can similarly be moved (renamed or relocated under a different parent), which carries all of their contained groups and sub-namespaces along with it. Both operations happen within the datastore — you still can't move a group or namespace across datastore boundaries this way, since namespaces are a structure inside one datastore, not a cross-datastore addressing scheme.

Practical Namespace Layouts

A few patterns cover the majority of real deployments:

Per-cluster: one top-level namespace per Proxmox VE cluster (cluster-hq, cluster-branch), sidestepping VMID collisions between clusters sharing one PBS datastore.
Per-customer, with per-environment children: customer-a/prod, customer-a/staging, customer-b/prod — permissions granted once at customer-a and customer-b, retention policy set independently per environment underneath.
Per-node: a namespace per hypervisor node in a cluster, useful mainly when different nodes run VMs with genuinely different backup schedules or retention needs, rather than as a default for every cluster.

Whichever layout you pick, keep the top two levels stable — permissions, sync jobs, and prune jobs all reference namespace paths directly, and renaming a namespace that other jobs already point at means updating every one of those job definitions afterward.

Common Mistakes

Mistake	Why it causes problems
Assuming a Proxmox VE backup job can target a namespace directly	The namespace lives on the PBS storage definition (`pvesm add pbs ... --namespace ...`), not on the backup job. Routing different VMs to different namespaces from one PVE cluster means adding a separate storage entry per namespace.
Granting permissions only at the datastore root for a multi-tenant setup	Every tenant ends up able to see every other tenant's backup groups. Grant the role at each tenant's namespace instead, so visibility and restore access stay scoped to that branch.
Renaming or moving a namespace that prune/sync jobs already reference	Existing job definitions keep their old namespace path and silently stop matching anything (or match the wrong branch) until you update the job to the new path.
Forgetting `max-depth` on a sync job meant to cover sub-namespaces	A sync job with `max-depth: 0` only pulls groups sitting directly in the anchor namespace — any nested customer or environment sub-namespaces underneath are silently skipped.
Treating namespaces as a substitute for separate datastores when physical isolation is required	Namespaces are a logical, access-controlled subdivision of one datastore on one set of disks. If a compliance requirement calls for physically separate storage per tenant, that still needs separate datastores, not namespaces.
Naming a namespace with a slash in a single segment	The slash is the path separator between levels; a name containing one is parsed as multiple nested levels instead of the single name you intended.

Frequently Asked Questions

Do namespaces work with Proxmox Backup Server's deduplication across different namespaces?
Yes. Deduplication happens at the chunk level for the datastore as a whole, independent of which namespace a backup group sits in, so two namespaces with similar data still benefit from shared chunk storage. Namespaces are strictly an organizational and access-control layer on top of the same underlying chunk store.

Can I move a backup group between two different datastores using namespaces?
No. Namespaces organize groups within a single datastore. Moving backups between separate datastores still requires a sync job or a manual restore-and-rebackup, not a namespace or group move operation.

What happens if I delete a namespace that still has backup groups in it?
PBS won't silently discard the contents — you need to remove or relocate the backup groups first (or use the appropriate force/recursive option if your PBS version's tooling exposes one), the same safety behavior as trying to delete a non-empty datastore.

Is there a performance cost to using deep namespace hierarchies?
Not meaningfully. Namespaces are a metadata and path structure, not a separate storage engine — the practical limit to worry about is the depth cap of 8 levels and keeping the hierarchy legible for whoever manages permissions and jobs, not runtime overhead.

Can non-admin users create their own namespaces?
Only if they hold the Modify privilege on the parent namespace where the new one would live. A typical delegated setup grants a tenant admin Modify on their own top-level namespace, letting them create their own sub-namespaces (like a new environment) without needing datastore-wide admin rights.

Do older Proxmox VE and PBS clients understand namespaces at all?
Namespace support requires both PBS and the connecting client (Proxmox VE's storage layer or proxmox-backup-client) to be on a version from PBS 2.2 onward. Older clients simply operate against the root namespace and won't show or address anything nested underneath it.

Conclusion

Namespaces turn a Proxmox Backup Server datastore from one flat bucket into a properly organized tree, without requiring a separate datastore — and therefore separate physical storage — for every cluster, tenant, or environment you need to keep apart. The mechanics are straightforward once you internalize where each piece lives: the namespace path itself is set on the PBS storage definition when connecting from Proxmox VE, permissions are granted per-namespace and inherit downward, and prune and sync jobs each get their own namespace scope so a retention policy or a replication job only ever touches the branch you pointed it at. The upfront work is mostly deciding on a layout — per-cluster, per-customer, per-environment, or some mix — since that structure is what every permission grant, prune job, and sync job will reference from then on.

Vormox is an independent virtualization management platform built on Proxmox VE. Proxmox® and Proxmox VE® are trademarks of Proxmox Server Solutions GmbH. Vormox is not affiliated with, endorsed by, or sponsored by Proxmox.

How to Organize Proxmox Backup Server with Datastore Namespaces