It keeps the repository, credentials and the list of paths to back up in a single config file, injects the configured namespace (--ns) and encryption key (--keyfile) into every command that needs them, and lets you pick a snapshot group, snapshot and archive from an interactive menu instead of typing them out. Any command it does not implement itself is passed straight through to proxmox-backup-client.

Requirements

A Debian-based host with bash and curl
jq and proxmox-backup-client — both installed by pbc install
A reachable PBS with a datastore and an API token

Installation

curl -fsSL https://git.ccc-rheintal.ch/spacefreak/pbc/raw/branch/master/install.sh | sudo bash

This installs the newest tagged version to /usr/local/bin/pbc, installs the dependencies, and puts an example config at /etc/pbc/config.example.

Updating

Run the same command again to update pbc itself:

curl -fsSL https://git.ccc-rheintal.ch/spacefreak/pbc/raw/branch/master/install.sh | sudo bash

It fetches the newest tag and overwrites /usr/local/bin/pbc. Your /etc/pbc/config is left untouched.

To update only the proxmox-backup-client binary:

sudo pbc install --update

This is skipped when the client is managed by the package manager — use apt in that case.

Configuration

sudo cp /etc/pbc/config.example /etc/pbc/config
sudo chmod 640 /etc/pbc/config
sudo editor /etc/pbc/config

Key	Description
`PBS_SERVER`	PBS host and port
`PBS_USER`	User and API token name, `user@realm:token-name`
`PBS_PASSWORD`	The API token secret
`PBS_DATASTORE`	Datastore to back up to
`PBS_NAMESPACE`	Optional, namespace inside the datastore
`BACKUP`	Array of `archive-name.pxar:/path` entries to back up
`ENCRYPTION_KEYFILE`	Optional, path to the client encryption key — see Encryption
`PBC`	Optional, path to `proxmox-backup-client` (default `/usr/local/bin/proxmox-backup-client`)

pbc never creates the config for you — copy the example and edit it yourself. The file has to be readable for the user that runs pbc, so if that is not root, hand it over:

sudo chown youruser /etc/pbc/config

The config is sourced as Bash and contains your token secret. pbc refuses to run if the file is writable by group or others, and warns if it is readable by others.

Check that it works:

pbc list

Use a different config with -c:

pbc -c ./myconfig list

Encryption

Backups can be encrypted client-side, so PBS only ever sees ciphertext. Create a key and point ENCRYPTION_KEYFILE at it:

sudo proxmox-backup-client key create /etc/pbc/backup.key --kdf none
sudo chmod 600 /etc/pbc/backup.key

pbc errors out if the key is missing or unreadable, and warns if it is readable by others. As with the config, the file has to be readable for the user that runs pbc — sudo chown youruser /etc/pbc/backup.key if that is not root.

Back the key up somewhere else. Without it the backups are unrecoverable, and a key stored only on the machine you are backing up is gone exactly when you need it. Print a recovery sheet and keep it off-host:

sudo proxmox-backup-client key paperkey /etc/pbc/backup.key

--kdf none leaves the key unprotected on disk, which is what makes unattended backups possible. With a passphrase-protected key (--kdf scrypt) the client prompts on every run and backup-cron hangs; export PBS_ENCRYPTION_PASSWORD in that case.

The key is passed to backup, backup-cron, mount and catalog-shell. It is not passed to commands that fall through to proxmox-backup-client — pbc restore needs both flags spelled out:

pbc restore --ns MyBackups --keyfile /etc/pbc/backup.key \
  host/myhost/2026-08-24T01:00:00Z root.pxar /mnt/restore

Setting ENCRYPTION_KEYFILE only affects snapshots made from then on. Older unencrypted snapshots stay readable, and listing works without the key either way — only reading archive contents needs it.

Usage

Run pbc --help for the synopsis and the list of options, or pbc -H to additionally list every command of proxmox-backup-client. The commands pbc implements itself are described below.

backup

Back up everything listed in BACKUP and print the client output:

pbc backup

Extra arguments are forwarded to the client:

pbc backup --exclude '/mnt/data/cache'

backup-cron

Same backup, but output is suppressed unless it fails — so cron only mails you on errors:

0 3 * * * /usr/local/bin/pbc backup-cron

list

List backup groups with their latest snapshot and archives:

pbc list

snapshot-list

List snapshots of a group with sizes and archives. Without an argument you get a menu of the available groups:

pbc snapshot-list
pbc snapshot-list host/myhost

mount

Mount a single archive of a snapshot on a local directory. Anything you leave out is asked for interactively:

pbc mount
pbc mount host/myhost/2026-08-24T01:00:00Z root.pxar /mnt/restore

The target directory is not created for you — create it beforehand and make sure it is writable for the user that runs pbc. Encrypted archives are decrypted transparently when ENCRYPTION_KEYFILE is configured. Unmount when done:

umount /mnt/restore

catalog-shell

Open an interactive shell to browse an archive and restore selected files — see below. Encrypted archives are decrypted transparently when ENCRYPTION_KEYFILE is configured.

pbc catalog-shell
pbc catalog-shell host/myhost/2026-08-24T01:00:00Z root.pxar

install

Install or update the dependencies. Requires root:

sudo pbc install
sudo pbc install --update

Restoring files

Selectively, with `catalog-shell`

pbc catalog-shell

Pick a snapshot and an archive from the menu, then browse the archive as if it were a filesystem and mark what you want back:

pxar:/ > cd etc
pxar:/etc > ls
pxar:/etc > select hosts
pxar:/etc > find etc/nginx/** --select
pxar:/etc > list-selected
pxar:/etc > restore-selected /mnt/restore
pxar:/etc > exit

ls, cd, pwd, stat — browse the archive
select <path> — mark a single file, relative to the current directory
find <pattern> --select — mark everything matching a glob
deselect <path> / clear-selected — drop one entry or all of them
list-selected — show what is currently marked
restore-selected <target> — restore only the marked entries
restore <target> [pattern] — restore the current directory and everything below it
help — list all available shell commands
exit — leave the shell

Selecting a directory and everything beneath it

select marks exactly the entry you give it and nothing else. Marking a directory therefore restores an empty directory — its contents are not included. Use a glob with find --select instead:

pxar:/ > find etc/nginx/** --select
pxar:/ > select etc/nginx
pxar:/ > restore-selected /mnt/restore

The find line picks up everything below etc/nginx; the select line adds the directory itself, so its own permissions and ownership are restored as well.

Note that find patterns are always matched against paths relative to the archive root, no matter which directory you are in, and that find scans the whole archive — expect it to take a while on large backups.

The target path must not exist yet; the restore creates it. Its parent directory has to be writable for the user that runs pbc.

Everything, or with normal tools

To copy files out with cp, rsync or a file manager, mount the archive instead:

mkdir -p /mnt/restore     # must exist and be writable for the user running pbc
pbc mount
cp -a /mnt/restore/etc/nginx /etc/nginx
umount /mnt/restore

Running in WSL

pbc also works inside a Debian-based WSL instance, which makes it a way to back up Windows directories: the Windows drives show up under /mnt, so they can be listed in BACKUP like any other path.

BACKUP=('users.pxar:/mnt/c/Users' 'projects.pxar:/mnt/d/projects')

A few things to keep in mind:

Access to files under /mnt is governed by Windows, not by the user you are inside the WSL instance — sudo does not help there. To back up paths your Windows user cannot read, start the WSL instance itself as administrator (run the terminal or wsl.exe via Run as administrator), then run pbc in it.
The owner and permission metadata stored in the archive is the one WSL synthesizes for Windows files, not the original Windows ACLs.
Cron is not running in a WSL instance by default, so backup-cron only fires if you enable it — either by starting cron yourself, or by triggering pbc backup-cron from the Windows Task Scheduler with wsl.exe:
```
wsl.exe -d Debian -u root /usr/local/bin/pbc backup-cron
```
For the reason above, such a task has to run with highest privileges to reach files that are not accessible to your Windows user.

License

GPLv3 — see LICENSE.

README.md

pbc