Michael Ablassmeier: pbsindex – file backup index

If you take backups using the proxmox-backup-client and you wondered what
backup may include a specific file, the only way to find out is to mount the
backup and search for the files.

For regular file backups, the Proxmox Backup Server frontend provides a pcat1
file for download, whose binary format is somewhat
undocumented but actually
includes a listing of the files backed up.

A Proxmox backup server datastore includes the same pcat1 file as blob index
(.pcat1.didx). So to actually beeing able to tell which backup contains which
files, one needs to:

1) Open the .pcat1.didx file and find out required blobs, see format documentation

2) Reconstruct the .pcat1 file from the blobs

3) Parse the pcat1 file and output the directory listing.

I’ve implemented this in pbsindex
which lets you create a central file index for your backups by scanning a
complete PBS datastore.

Lets say you want to have a file listing for a specific backup,
use:

 pbsindex --chunk-dir /backup/.chunks/ /backup/host/vm178/2026-03-02T10:47:57Z/catalog.pcat1.didx
 didx uuid=7e4086a9-4432-4184-a21f-0aeec2b2de93 ctime=2026-03-02T10:47:57Z chunks=2 total_size=1037386
 chunk[0] start=0 end=344652 size=344652 digest=af3851419f5e74fbb4d7ca6ac3bc7c5cbbdb7c03d3cb489d57742ea717972224
 chunk[1] start=344652 end=1037386 size=692734 digest=e400b13522df02641c2d9934c3880ae78ebb397c66f9b4cf3b931d309da1a7cc
 d ./usr.pxar.didx
 d ./usr.pxar.didx/bin
 l ./usr.pxar.didx/bin/Mail
 f ./usr.pxar.didx/bin/[ size=55720 mtime=2025-06-04T15:14:05Z
 f ./usr.pxar.didx/bin/aa-enabled size=18672 mtime=2025-04-10T15:06:25Z
 f ./usr.pxar.didx/bin/aa-exec size=18672 mtime=2025-04-10T15:06:25Z
 f ./usr.pxar.didx/bin/aa-features-abi size=18664 mtime=2025-04-10T15:06:25Z
 l ./usr.pxar.didx/bin/apropos

It also lets you scan a complete datastore for all existing .pcat1.didx files
and store the directory listings in a SQLite database for easier searching.