Proxmox Backup Server Namespaces

Proxmox Backup Server has a feature called namespaces. Namespaces allow you to organize parts of your datastore under different directories, and then target these directories individually under prune jobs and sync jobs. One usecase may be if you have a set of backups that you only want to keep the last 30 days of, but you have another that you wish to keep a copy of per day.

Namespaces can be nested, with one inside another one, following directory slash notation (/root/nested_namespace1/nested_namespace2). Internally, Proxmox Backup Server's datastore uses a "ns" directory, alongside a "vm" and "ct" directory to organize this content. So internally, a root namespace with three VMs and a nested namespace with two more VMs may appear as such:

root/
| vm/
  | 100/
  | 101/
  | 102/
| ct/
| ns/
  | nested/
    | vm/
      | 103/ 
      | 104/
    | ct/

Namespaces can be nested many times over, if desired. Another important usecase for namespaces is that they allow you to have VMs from several PVE clusters that have overlapping VMIDs.

Sync Jobs

Note: this assumes sync jobs using pulls instead of pushes, which was and continues to be the standard paradigm intended for Proxmox Backup Server. In a recent update, the options for a push were added, but this is a bit limited. If using push jobs, adapt these notes with caution.

When configuring a sync job, the local and remote namespace may be specified, to avoid copying the full contents of the backup server to another backup server. You may use this to configure several identical backup servers in a mesh, with local machines pushing backups to the backup server, followed by remotes syncing from other sites' local servers.

• Site A may have a backup server with namespaces A and B.
• Site B may have the same configuration, with namespaces A and B.
• Site A backs up to its local backup server's A namespace.
• Later in the day, Site B's backup server syncs from Site A's A Namespace into its own A namespace, only populated by contents gathered from the sync job, while Site B backs up its own contents to its local backup server's B namespace.
• The same process occurs with Site A syncing Site B's namespace into Site A's B namespace.

Now, both sites have both copies of themselves, formed locally, and copies of each other. This can scale up with an arbitrary number of backup servers.

Nested namespaces

Sync jobs support nested namespaces. By default, when configuring a sync job, you specify source and destination namespaces. These can be as specific as you like. Note the "Max Depth" option, which defaults to "Full". This option controls how many namespaces deep the sync job will crawl. Without a value set, it will sync the entire directory all the way down its tree. If you set this to 0, it will sync any contents in the source namespace, but will not traverse past this specific namespace. With the above example, a Max Depth of 0 syncing on the root namespace would copy VMs 100, 101, and 102, but NOT the nested namespace or its content.

Nested namespaces will be created if not already present

In the above example, if we have another Proxmox Backup Server that has its own root namespace, but no nested subnamespace, and we sync the contents from root with Max Depth full to this second server's root, it will automatically generate the "nested" namespace and use it in any subsequent syncs. This is why it's important to understand your namespace structure, as a misalignment could lead to many erroneous namespaces being generated!

Manipulating namespaces

	DO NOT do ANY of this if a prune job, garbage collection, verify job, sync job, or standard backup is in progress. It'd be best to set this datastore to maintenance mode first!

Moving VMs and CTs from one namespace to another

This is not implicitly supported by Proxmox Backup Server, but due to the fact that the underlying infrastructure is a very simple POSIX directory system, it is not difficult to manually perform this action.

1. If a namespace has been created, but does not have any VMs in it yet, the vm directory will be absent, so we must create this manually.
   1. From the parent namespace directory: mkdir ns/<namespace>/vm
   2. Set the owner to backup:backup: chown backup:backup ns/<namespace>/vm
2. Move the contents you wish to move:
   1. mv vm/<vm_id> ns/<namespace>/vm/<vm_id>