- About
- What it supports
- Requirements
- Usage
- Limitations
- Links
pbsindex decodes Proxmox catalog.pcat1 files and dynamic index files
(.pcat1.didx).
You can use it to generate a file index for your complete proxmox backup server datastores without having to mount the backup snapshots.
- Decode plain
catalog.pcat1and print entries. - Decode
catalog.pcat1.didxby resolving chunk blobs from a chunk directory. - Recursively scan a directory for all
*.pcat1.didxfiles. - Index decoded file lists into SQLite.
- Search indexed files by host, with wildcard support.
Following executables must be existent alongside pbsindex:
sqlite3CLI (forindexandsearch)zstdCLI (for compressed PBS chunk blobs)
sudo apt install sqlite3 zstdIf you've downloaded the pcat1 file via the PBS Webfrontend you can decode it via:
pbsindex /path/to/catalog.pcat1If you want to show the contents for a specific backup directly from the existing backup datastore use:
pbsindex \
--chunk-dir /backup/.chunks/ \
/backup/host/vm178/2026-03-02T10:47:57Z/catalog.pcat1.didx
d ./backup.pxar.didx
d ./backup.pxar.didx/bin
l ./backup.pxar.didx/bin/Mail
f ./backup.pxar.didx/bin/[ size=55720 mtime=2025-06-04T15:14:05Z
f ./backup.pxar.didx/bin/aa-enabled size=18672 mtime=2025-04-10T15:06:25Z
f ./backup.pxar.didx/bin/aa-exec size=18672 mtime=2025-04-10T15:06:25Z
f ./backup.pxar.didx/bin/aa-features-abi size=18664 mtime=2025-04-10T15:06:25Z
l ./backup.pxar.didx/bin/apropos
f ./backup.pxar.didx/bin/apt size=18752 mtime=2025-06-24T17:02:46Z
[..]To scan all existing file backups within a datastore use:
pbsindex \
--chunk-dir /backup/.chunks/ \
--scan-dir /backup/host/vm178/Use index to ingest all .pcat1.didx files under a host path into SQLite.
pbsindex index \
--db /tmp/pcat.db \
--scan-dir /backup/host/vm178 \
--chunk-dir /backup/.chunks/
indexed /backup/host/vm178/2026-03-02T10:36:15Z/catalog.pcat1.didx entries=1415 uuid=09d276f0-96a0-4e7e-8208-d4b54fcb6ccd
indexed /backup/host/vm178/2026-03-02T10:47:57Z/catalog.pcat1.didx entries=48820 uuid=7e4086a9-4432-4184-a21f-0aeec2b2de93Notes:
archive.didx_uuidis unique and used as the stable identity for a catalog file list.- Re-indexing is idempotent for the same UUID (archive metadata and file entries are updated).
--hostis optional. If omitted, host key defaults to--scan-dir(normalized path). If you want a shorter stable key, pass--hostexplicitly.
Use search to query indexed files for a host.
pbsindex search \
--db /tmp/pcat.db \
--file 'iptables'
snapshot=2026-03-02T10:47:57Z host=/backup/host/vm178 uuid=7e4086a9-4432-4184-a21f-0aeec2b2de93 archive=JO.pxar.didx type=l path=/JO.pxar.didx/sbin/iptablespbsindex search \
--db /tmp/pcat.db \
--file 'iptables' \
--all
snapshot=2026-03-02T10:47:57Z host=/backup/host/vm178 uuid=7e4086a9-4432-4184-a21f-0aeec2b2de93 archive=JO.pxar.didx type=l path=/JO.pxar.didx/sbin/iptables
snapshot=2026-03-02T10:47:57Z host=/backup/host/vm178 uuid=7e4086a9-4432-4184-a21f-0aeec2b2de93 archive=JO.pxar.didx type=f path=/JO.pxar.didx/share/bash-completion/completions/iptables size=2109 mtime=2025-01-26T19:49:00Z
snapshot=2026-03-02T10:47:57Z host=/backup/host/vm178 uuid=7e4086a9-4432-4184-a21f-0aeec2b2de93 archive=JO.pxar.didx type=d path=/JO.pxar.didx/share/doc/iptables
snapshot=2026-03-02T10:47:57Z host=/backup/host/vm178 uuid=7e4086a9-4432-4184-a21f-0aeec2b2de93 archive=JO.pxar.didx type=d path=/JO.pxar.didx/share/iptablespbsindex search \
--db /tmp/pcat.db \
--host backup/host/vm178 \
--file 'iptables' \
--allWildcard behavior:
- If pattern contains
*,?, or[], SQLiteGLOBis used. - Otherwise exact filename match is used (
name = pattern). --hostis optional for search. If omitted, search runs across all indexed hosts.
pbsindex --help
pbsindex index --help
pbsindex search --helpEncrypted blobs cannot be indexed.