# pbc A Bash wrapper around Proxmox's `proxmox-backup-client` for Proxmox Backup Server (PBS). 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 ```bash 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: ```bash 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: ```bash sudo pbc install --update ``` This is skipped when the client is managed by the package manager — use `apt` in that case. ## Configuration ```bash 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](#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: ```bash 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: ```bash pbc list ``` Use a different config with `-c`: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash pbc backup ``` Extra arguments are forwarded to the client: ```bash pbc backup --exclude '/mnt/data/cache' ``` ### backup-cron Same backup, but output is suppressed unless it fails — so cron only mails you on errors: ```cron 0 3 * * * /usr/local/bin/pbc backup-cron ``` ### list List backup groups with their latest snapshot and archives: ```bash pbc list ``` ### snapshot-list List snapshots of a group with sizes and archives. Without an argument you get a menu of the available groups: ```bash 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: ```bash 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: ```bash 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. ```bash pbc catalog-shell pbc catalog-shell host/myhost/2026-08-24T01:00:00Z root.pxar ``` ### install Install or update the dependencies. Requires root: ```bash sudo pbc install sudo pbc install --update ``` ## Restoring files ### Selectively, with `catalog-shell` ```bash 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 ` — mark a single file, relative to the current directory - `find --select` — mark everything matching a glob - `deselect ` / `clear-selected` — drop one entry or all of them - `list-selected` — show what is currently marked - `restore-selected ` — restore only the marked entries - `restore [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: ```bash 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. ```bash 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](LICENSE).