pbs_pull
Pull backup snapshots from a remote PBS datastore into a local datastore. Use dry-run to preview changes and confirm to execute. Includes filtering, rate limiting, and options for verified or encrypted snapshots.
Instructions
MUTATION: pull backups from a remote PBS datastore into the LOCAL datastore store.
RISK_MEDIUM by default, escalating to RISK_HIGH when remove_vanished=True (see
proximo.pbs_admin module docstring's RISK RATING section — matches the campaign's own
"remove-vanished DELETES local snapshots" framing). WRITES real backup data into store; an
over-broad or absent group_filter transfers every group in scope. Dry-run by default (returns
a PLAN disclosing every param that changes where data lands or what gets deleted); confirm=True
executes (POST /pull). The live schema declares this returns null — no UPID to poll;
Smoke-confirm whether this call blocks synchronously for the full transfer duration before
relying on it for a large sync. No rollback primitive. Needs PROXIMO_PBS_* config.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ns | No | Namespace on the LOCAL datastore to pull into. Defaults to root. | |
| store | Yes | LOCAL PBS datastore name to pull backups INTO. REQUIRED. | |
| remote | No | Remote ID identifying the source PBS. OPTIONAL per the live schema (Smoke-confirm what PBS does when omitted). | |
| confirm | No | False (default) returns a dry-run PLAN only; True executes the pull. | |
| rate_in | No | Inbound rate limit as a byte size with unit. | |
| burst_in | No | Inbound burst limit as a byte size with unit, e.g. '10MB'. | |
| rate_out | No | Outbound rate limit as a byte size with unit. | |
| burst_out | No | Outbound burst limit as a byte size with unit. | |
| max_depth | No | Namespace recursion depth, 0-7 (0 = no recursion; empty/omitted = automatic full recursion). | |
| remote_ns | No | Namespace on the REMOTE datastore to pull from. Defaults to root. | |
| group_filter | No | Group filters, e.g. '[exclude:]type:vm' or 'group:GROUP' or 'regex:RE'. Omit to pull EVERY group in scope. | |
| remote_store | Yes | Datastore name on the remote PBS to pull FROM. REQUIRED. | |
| transfer_last | No | Limit transfer to the last N snapshots per group, skipping older ones (>=1). | |
| verified_only | No | Only synchronize verified backup snapshots, exclude others. | |
| encrypted_only | No | Only synchronize encrypted backup snapshots, exclude others. | |
| proximo_target | No | Which configured Proxmox target to run this call against — a target name from your multi-target config (a specific PVE/PBS/PMG/PDM box). Omit to use the single/default target from the environment; the selection applies only to this call. | |
| resync_corrupt | No | Re-pull local snapshots that previously failed verification, overwriting them. | |
| worker_threads | No | Number of worker threads to process groups in parallel, 1-32. | |
| decryption_keys | No | IDs of already-registered client encryption keys (pbs_encryption_key_*) to use for decrypting remote content. NOT the raw key material. | |
| remove_vanished | No | DELETE local snapshots that no longer exist on the remote. Escalates this call's risk to HIGH — no dry-run preview exists. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |