proxmox-backup-client

Synopsis

proxmox-backup-client backup {<backupspec>} [OPTIONS]

Create (host) backup.

<backupspec><string>

List of backup source specifications ([<label.ext>:<path>] ...) Can be specified more than once.

Optional parameters:

--all-file-systems <boolean>   (default=false)

Include all mounted subdirectories.

--backup-id <string>

Backup ID.

--backup-time <integer> (1 - N)

Backup time (Unix epoch.)

--backup-type vm|ct|host

Backup type.

--burst <string>

Size of the token bucket (for Token bucket filter) in bytes with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).

--change-detection-mode legacy|data|metadata   (default=legacy)

Mode to detect file changes since last backup run

--chunk-size <integer> (64 - 4096)   (default=4096)

Chunk size in KB. Must be a power of 2.

--crypt-mode none|encrypt|sign-only   (default=encrypt)

Defines whether data is encrypted (using an AEAD cipher), only signed, or neither.

--dry-run <boolean>   (default=false)

Just show what backup would do, but do not upload anything.

--entries-max <integer>   (default=1048576)

Max number of entries to hold in memory.

--exclude <string>

List of paths or patterns for matching files to exclude. Can be specified more than once.

--include-dev <string>

Include mountpoints with same st_dev number (see man fstat) as specified files. Can be specified more than once.

--keyfd <integer> (0 - N)

Pass an encryption key via an already opened file descriptor.

--keyfile <string>

Path to encryption key. All data will be encrypted using this key.

--master-pubkey-fd <integer> (0 - N)

Pass a master public key via an already opened file descriptor.

--master-pubkey-file <string>

Path to master public key. The encryption key used for a backup will be encrypted using this key and appended to the backup.

--ns <string>

Namespace.

--rate <string>

Rate limit (for Token bucket filter) in bytes/s with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).

--repository <string>

Repository URL.

--skip-e2big-xattr <boolean>   (default=false)

Ignore the E2BIG error when retrieving xattrs. This includes the file, but discards the metadata.

--skip-lost-and-found <boolean>   (default=false)

Skip lost+found directory.

proxmox-backup-client benchmark [OPTIONS]

Run benchmark tests

Optional parameters:

--keyfile <string>

Path to encryption key. All data will be encrypted using this key.

--output-format text|json|json-pretty

Output format.

--repository <string>

Repository URL.

proxmox-backup-client catalog dump <snapshot> [OPTIONS]

Dump catalog.

<snapshot><string>

Snapshot path.

Optional parameters:

--keyfd <integer> (0 - N)

Pass an encryption key via an already opened file descriptor.

--keyfile <string>

Path to encryption key.

--ns <string>

Namespace.

--repository <string>

Repository URL.

proxmox-backup-client catalog shell <snapshot> <archive-name> [OPTIONS]

Shell to interactively inspect and restore snapshots.

<snapshot><string>

Group/Snapshot path.

<archive-name><string>

Backup archive name.

Optional parameters:

--keyfd <integer> (0 - N)

Pass an encryption key via an already opened file descriptor.

--keyfile <string>

Path to encryption key.

--ns <string>

Namespace.

--repository <string>

Repository URL.

proxmox-backup-client change-owner <group> <new-owner> [OPTIONS]

Change owner of a backup group

<group><string>

Backup group.

<new-owner><string>

Authentication ID

Optional parameters:

--ns <string>

Namespace.

--repository <string>

Repository URL.

proxmox-backup-client garbage-collect [OPTIONS]

Start garbage collection for a specific repository.

Optional parameters:

--output-format text|json|json-pretty

Output format.

--repository <string>

Repository URL.

proxmox-backup-client group forget <group> [OPTIONS]

Forget (remove) backup snapshots.

<group><string>

Backup group

Optional parameters:

--ns <string>

Namespace.

--repository <string>

Repository URL.

proxmox-backup-client help [{<command>}] [OPTIONS]

Get help about specified command (or sub-command).

<command><string>

Command. This may be a list in order to specify nested sub-commands. Can be specified more than once.

Optional parameters:

--verbose <boolean>

Verbose help.

proxmox-backup-client key change-passphrase [<path>] [OPTIONS]

Change the encryption key's password.

<path><string>

Key file. Without this the default key's password will be changed.

Optional parameters:

--hint <string>

Password hint.

--kdf none|scrypt|pbkdf2   (default=scrypt)

Key derivation function for password protected encryption keys.

proxmox-backup-client key create [<path>] [OPTIONS]

Create a new encryption key.

<path><string>

Output file. Without this the key will become the new default encryption key.

Optional parameters:

--hint <string>

Password hint.

--kdf none|scrypt|pbkdf2   (default=scrypt)

Key derivation function for password protected encryption keys.

proxmox-backup-client key create-master-key

Create an RSA public/private key pair used to put an encrypted version of the symmetric backup encryption key onto the backup server along with each backup.

proxmox-backup-client key import-master-pubkey <path>

Import an RSA public key used to put an encrypted version of the symmetric backup encryption key onto the backup server along with each backup.

The imported key will be used as default master key for future invocations by the same local user.

<path><string>

Path to the PEM formatted RSA public key.

proxmox-backup-client key import-with-master-key [<path>] --encrypted-keyfile <string> --master-keyfile <string> [OPTIONS]

Import an encrypted backup of an encryption key using a (private) master key.

<path><string>

Output file. Without this the key will become the new default encryption key.

--encrypted-keyfile <string>

RSA-encrypted keyfile to import.

--master-keyfile <string>

(Private) master key to use.

Optional parameters:

--hint <string>

Password hint.

--kdf none|scrypt|pbkdf2   (default=scrypt)

Key derivation function for password protected encryption keys.

proxmox-backup-client key paperkey [<path>] [OPTIONS]

Generate a printable, human readable text file containing the encryption key.

This also includes a scanable QR code for fast key restore.

<path><string>

Key file. Without this the default key's will be used.

Optional parameters:

--output-format text|html

Paperkey output format

--subject <string>

Include the specified subject as title text.

proxmox-backup-client key show [<path>] [OPTIONS]

Print the encryption key's metadata.

<path><string>

Key file. Without this the default key's metadata will be shown.

Optional parameters:

--output-format text|json|json-pretty

Output format.

proxmox-backup-client key show-master-pubkey [<path>] [OPTIONS]

List information about master key

<path><string>

Path to the PEM formatted RSA public key. Default location will be used if not specified.

Optional parameters:

--output-format text|json|json-pretty

Output format.

proxmox-backup-client list [OPTIONS]

List backup groups.

Optional parameters:

--ns <string>

Namespace.

--output-format text|json|json-pretty

Output format.

--repository <string>

Repository URL.

proxmox-backup-client login [OPTIONS]

Try to login. If successful, store ticket.

Optional parameters:

--repository <string>

Repository URL.

proxmox-backup-client logout [OPTIONS]

Logout (delete stored ticket).

Optional parameters:

--repository <string>

Repository URL.

proxmox-backup-client map <snapshot> <archive-name> [OPTIONS]

Map a drive image from a VM backup to a local loopback device. Use 'unmap' to undo. WARNING: Only do this with trusted backups!

<snapshot><string>

Group/Snapshot path.

<archive-name><string>

Backup archive name.

Optional parameters:

--keyfile <string>

Path to encryption key.

--ns <string>

Namespace.

--repository <string>

Repository URL.

--verbose <boolean>   (default=false)

Verbose output and stay in foreground.

proxmox-backup-client mount <snapshot> <archive-name> <target> [OPTIONS]

Mount pxar archive.

<snapshot><string>

Group/Snapshot path.

<archive-name><string>

Backup archive name.

<target><string>

Target directory path.

Optional parameters:

--keyfile <string>

Path to encryption key.

--ns <string>

Namespace.

--repository <string>

Repository URL.

--verbose <boolean>   (default=false)

Verbose output and stay in foreground.

proxmox-backup-client namespace create [<ns>] [OPTIONS]

Create a new namespace.

<ns><string>

Namespace.

Optional parameters:

--repository <string>

Repository URL.

proxmox-backup-client namespace delete [<ns>] [OPTIONS]

Delete an existing namespace.

<ns><string>

Namespace.

Optional parameters:

--delete-groups <boolean>

Destroys all groups in the hierarchy.

--repository <string>

Repository URL.

proxmox-backup-client namespace list [<ns>] [OPTIONS]

List namespaces in a repository.

<ns><string>

Namespace.

Optional parameters:

--max-depth <integer> (0 - N)

maximum recursion depth

--output-format text|json|json-pretty

Output format.

--repository <string>

Repository URL.

proxmox-backup-client prune <group> [OPTIONS]

Prune a backup repository.

<group><string>

Backup group

Optional parameters:

--dry-run <boolean>

Just show what prune would do, but do not delete anything.

--keep-daily <integer> (1 - N)

Number of daily backups to keep.

--keep-hourly <integer> (1 - N)

Number of hourly backups to keep.

--keep-last <integer> (1 - N)

Number of backups to keep.

--keep-monthly <integer> (1 - N)

Number of monthly backups to keep.

--keep-weekly <integer> (1 - N)

Number of weekly backups to keep.

--keep-yearly <integer> (1 - N)

Number of yearly backups to keep.

--max-depth <integer> (0 - 7)

How many levels of namespaces should be operated on (0 == no recursion, empty == automatic full recursion, namespace depths reduce maximum allowed value)

--ns <string>

Namespace.

--output-format text|json|json-pretty

Output format.

--quiet <boolean>   (default=false)

Minimal output - only show removals.

--repository <string>

Repository URL.

proxmox-backup-client restore <snapshot> <archive-name> <target> [OPTIONS]

Restore backup repository.

<snapshot><string>

Group/Snapshot path.

<archive-name><string>

Backup archive name.

<target><string>

Target directory path. Use '-' to write to standard output.

We do not extract '.pxar' archives when writing to standard output.

Optional parameters:

--allow-existing-dirs <boolean>   (default=false)

Do not fail if directories already exists.

--burst <string>

Size of the token bucket (for Token bucket filter) in bytes with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).

--crypt-mode none|encrypt|sign-only   (default=encrypt)

Defines whether data is encrypted (using an AEAD cipher), only signed, or neither.

--ignore-acls <boolean>   (default=false)

ignore acl settings

--ignore-extract-device-errors <boolean>   (default=false)

ignore errors that occur during device node extraction

--ignore-ownership <boolean>   (default=false)

ignore owner settings (no chown)

--ignore-permissions <boolean>   (default=false)

ignore permission settings (no chmod)

--ignore-xattrs <boolean>   (default=false)

ignore xattr settings

--keyfd <integer> (0 - N)

Pass an encryption key via an already opened file descriptor.

--keyfile <string>

Path to encryption key. All data will be encrypted using this key.

--ns <string>

Namespace.

--overwrite <boolean>   (default=false)

overwrite already existing files

--overwrite-files <boolean>   (default=false)

overwrite already existing files

--overwrite-hardlinks <boolean>   (default=false)

overwrite already existing entries by archives hardlink

--overwrite-symlinks <boolean>   (default=false)

overwrite already existing entries by archives symlink

--pattern <string>

Path or match pattern to limit files that get restored. Can be specified more than once.

--prelude-target <string>

Path to restore prelude to, (pxar v2 archives only).

--rate <string>

Rate limit (for Token bucket filter) in bytes/s with optional unit (B, KB (base 10), MB, GB, ..., KiB (base 2), MiB, Gib, ...).

--repository <string>

Repository URL.

proxmox-backup-client snapshot files <snapshot> [OPTIONS]

List snapshot files.

<snapshot><string>

Snapshot path.

Optional parameters:

--ns <string>

Namespace.

--output-format text|json|json-pretty

Output format.

--repository <string>

Repository URL.

proxmox-backup-client snapshot forget <snapshot> [OPTIONS]

Forget (remove) backup snapshots.

<snapshot><string>

Snapshot path.

Optional parameters:

--ns <string>

Namespace.

--repository <string>

Repository URL.

proxmox-backup-client snapshot list [<group>] [OPTIONS]

List backup snapshots.

<group><string>

Backup group.

Optional parameters:

--ns <string>

Namespace.

--output-format text|json|json-pretty

Output format.

--repository <string>

Repository URL.

proxmox-backup-client snapshot notes show <snapshot> [OPTIONS]

Show notes

<snapshot><string>

Snapshot path.

Optional parameters:

--ns <string>

Namespace.

--output-format text|json|json-pretty

Output format.

--repository <string>

Repository URL.

proxmox-backup-client snapshot notes update <snapshot> <notes> [OPTIONS]

Update Notes

<snapshot><string>

Snapshot path.

<notes><string>

The Notes.

Optional parameters:

--ns <string>

Namespace.

--repository <string>

Repository URL.

proxmox-backup-client snapshot protected show <snapshot> [OPTIONS]

Show protection status of the specified snapshot

<snapshot><string>

Snapshot path.

Optional parameters:

--ns <string>

Namespace.

--output-format text|json|json-pretty

Output format.

--repository <string>

Repository URL.

proxmox-backup-client snapshot protected update <snapshot> <protected> [OPTIONS]

Update Protection Status of a snapshot

<snapshot><string>

Snapshot path.

<protected><boolean>

The protection status.

Optional parameters:

--ns <string>

Namespace.

--repository <string>

Repository URL.

proxmox-backup-client snapshot upload-log <snapshot> <logfile> [OPTIONS]

Upload backup log file.

<snapshot><string>

Group/Snapshot path.

<logfile><string>

The path to the log file you want to upload.

Optional parameters:

--crypt-mode none|encrypt|sign-only   (default=encrypt)

Defines whether data is encrypted (using an AEAD cipher), only signed, or neither.

--keyfd <integer> (0 - N)

Pass an encryption key via an already opened file descriptor.

--keyfile <string>

Path to encryption key. All data will be encrypted using this key.

--ns <string>

Namespace.

--repository <string>

Repository URL.

proxmox-backup-client status [OPTIONS]

Get repository status.

Optional parameters:

--output-format text|json|json-pretty

Output format.

--repository <string>

Repository URL.

proxmox-backup-client task list [OPTIONS]

List running server tasks for this repo user

Optional parameters:

--all <boolean>

Also list stopped tasks.

--limit <integer> (1 - 1000)   (default=50)

The maximal number of tasks to list.

--output-format text|json|json-pretty

Output format.

--repository <string>

Repository URL.

proxmox-backup-client task log <upid> [OPTIONS]

Display the task log.

<upid><string>

Unique Process/Task Identifier

Optional parameters:

--repository <string>

Repository URL.

proxmox-backup-client task stop <upid> [OPTIONS]

Try to stop a specific task.

<upid><string>

Unique Process/Task Identifier

Optional parameters:

--repository <string>

Repository URL.

proxmox-backup-client unmap [<name>]

Unmap a loop device mapped with 'map' and release all resources.

<name><string>

Archive name, path to loopdev (/dev/loopX) or loop device number. Omit to list all current mappings and force cleaning up leftover instances.

proxmox-backup-client version [OPTIONS]

Show client and optional server version

Optional parameters:

--output-format text|json|json-pretty

Output format.

--repository <string>

Repository URL.

Catalog Shell Commands

Those command are available when you start an intercative restore shell:

proxmox-backup-client shell <snapshot> <name.pxar>

cd [<path>]

Change the current working directory to the new directory

<path><string>

target path.

clear-selected

Clear the list of files selected for restore.

deselect <path>

Deselect an entry for restore.

This will return an error if the entry was not found in the list of entries selected for restore.

<path><string>

path to entry to remove from list.

exit

Exit the shell

find <pattern> [OPTIONS]

Find entries in the catalog matching the given match pattern.

<pattern><string>

Path or match pattern for matching filenames.

Optional parameters:

--select <boolean>   (default=false)

Add matching filenames to list for restore.

help [{<command>}] [OPTIONS]

Get help about specified command (or sub-command).

<command><string>

Command. This may be a list in order to specify nested sub-commands. Can be specified more than once.

Optional parameters:

--verbose <boolean>

Verbose help.

list-selected [OPTIONS]

List entries currently selected for restore.

Optional parameters:

--patterns <boolean>   (default=false)

List match patterns instead of the matching files.

ls [<path>]

List the content of working directory or given path.

<path><string>

target path.

pwd

List the current working directory.

restore <target> [OPTIONS]

Restore the sub-archive given by the current working directory to target.

By further providing a pattern, the restore can be limited to a narrower subset of this sub-archive. If pattern is not present or empty, the full archive is restored to target.

<target><string>

target path for restore on local filesystem.

Optional parameters:

--pattern <string>

Path or match pattern for matching filenames.

restore-selected <target>

Restore the selected entries to the given target path.

Target must not exist on the clients filesystem.

<target><string>

target path for restore on local filesystem.

select <path>

Select an entry for restore.

This will return an error if the entry is already present in the list or if an invalid path was provided.

<path><string>

target path.

stat <path>

Read the metadata for a given directory entry.

This is expensive because the data has to be read from the pxar archive, which means reading over the network.

<path><string>

target path.

Common Options

Most commands that produce output support the --output-format parameter. This accepts the following values:

text:

Text format (default). Structured data is rendered as a table.

json:

JSON (single line).

json-pretty:

JSON (multiple lines, nicely formatted).

Also, the following environment variables can modify output behavior:

PROXMOX_OUTPUT_FORMAT

Defines the default output format.

PROXMOX_OUTPUT_NO_BORDER

If set (to any value), do not render table borders.

PROXMOX_OUTPUT_NO_HEADER

If set (to any value), do not render table headers.

Note

The text format is designed to be human readable, and not meant to be parsed by automation tools. Please use the json format if you need to process the output.

Description

This tool implements a backup server client, i.e. it can connect to a backup servers to issue management commands and to create or restore backups.