proxmox-tape(1)

PROXMOX-TAPE(1)

Proxmox Backup

PROXMOX-TAPE(1)

NAME

proxmox-tape - Proxmox Tape Backup CLI Tool

SYNOPSIS

proxmox-tape backup <store> <pool> [OPTIONS]

Backup datastore to tape media pool

<store>: <string> Datastore name.
<pool>: <string> Media pool name.

Optional parameters:

--drive <string>: Drive Identifier.
--eject-media <boolean>: Eject media upon job completion.
--export-media-set <boolean>: Export media set upon job completion.
--force-media-set <boolean> (default=false): Ignore the allocation policy and start a new media-set.
--groups [<exclude:|include:>]<type:<vm|ct|host>|group:GROUP|regex:RE>: List of group filters. Can be specified more than once.
--latest-only <boolean>: Backup latest snapshots only.
--max-depth <integer> (0 - 7) (default=7): How many levels of namespaces should be operated on (0 == no recursion)
--notify-user <string>: User ID
--ns <string>: Namespace.
--output-format text|json|json-pretty: Output format.

----

proxmox-tape backup-job create <id> --drive <string> --pool <string> --store <string> [OPTIONS]

Create a new tape backup job.

<id>: <string> Job ID.
--drive <string>: Drive Identifier.
--pool <string>: Media pool name.
--store <string>: Datastore name.

Optional parameters:

--comment <string>: Comment.
--eject-media <boolean>: Eject media upon job completion.
--export-media-set <boolean>: Export media set upon job completion.
--group-filter [<exclude:|include:>]<type:<vm|ct|host>|group:GROUP|regex:RE>: List of group filters. Can be specified more than once.
--latest-only <boolean>: Backup latest snapshots only.
--max-depth <integer> (0 - 7) (default=7): How many levels of namespaces should be operated on (0 == no recursion)
--notification-mode legacy-sendmail|notification-system (default=notification-system): Configure how notifications for this datastore should be sent. legacy- sendmail sends email notifications to the user configured in notify-user via the system's sendmail executable. notification-system emits matchable notification events to the notification system.
--notify-user <string>: User ID
--ns <string>: Namespace.
--schedule <calendar-event>: Run sync job at specified schedule.
--worker-threads <integer> (1 - 32) (default=1): The number of threads to use for the tape backup job.

----

proxmox-tape backup-job list [OPTIONS]

Tape backup job list.

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape backup-job remove <id> [OPTIONS]

Remove a tape backup job configuration

<id>: <string> Job ID.

Optional parameters:

--digest <string>: Prevent changes if current configuration file has different SHA256 digest. This can be used to prevent concurrent modifications.

----

proxmox-tape backup-job run <id>

Run THape Backup Job

<id>: <string> Job ID.

----

proxmox-tape backup-job show <id> [OPTIONS]

Show tape backup job configuration

<id>: <string> Job ID.

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape backup-job update <id> [OPTIONS]

Update the tape backup job

<id>: <string> Job ID.

Optional parameters:

--comment <string>: Comment.
--delete comment|schedule|eject-media|export-media-set|latest-only|notify-user|notification-mode|group-filter|max-depth|ns|worker-threads: List of properties to delete. Can be specified more than once.
--digest <string>: Prevent changes if current configuration file has different SHA256 digest. This can be used to prevent concurrent modifications.
--drive <string>: Drive Identifier.
--eject-media <boolean>: Eject media upon job completion.
--export-media-set <boolean>: Export media set upon job completion.
--group-filter [<exclude:|include:>]<type:<vm|ct|host>|group:GROUP|regex:RE>: List of group filters. Can be specified more than once.
--latest-only <boolean>: Backup latest snapshots only.
--max-depth <integer> (0 - 7) (default=7): How many levels of namespaces should be operated on (0 == no recursion)
--notification-mode legacy-sendmail|notification-system (default=notification-system): Configure how notifications for this datastore should be sent. legacy- sendmail sends email notifications to the user configured in notify-user via the system's sendmail executable. notification-system emits matchable notification events to the notification system.
--notify-user <string>: User ID
--ns <string>: Namespace.
--pool <string>: Media pool name.
--schedule <calendar-event>: Run sync job at specified schedule.
--store <string>: Datastore name.
--worker-threads <integer> (1 - 32) (default=1): The number of threads to use for the tape backup job.

----

proxmox-tape barcode-label [OPTIONS]

Label media with barcodes from changer device

Optional parameters:

--drive <string>: Drive Identifier.
--output-format text|json|json-pretty: Output format.
--pool <string>: Media pool name.

----

proxmox-tape cartridge-memory [OPTIONS]

Read Cartridge Memory (Medium auxiliary memory attributes)

Optional parameters:

--drive <string>: Drive Identifier.
--output-format text|json|json-pretty: Output format.

----

proxmox-tape catalog [OPTIONS]

Scan media and record content

Optional parameters:

--drive <string>: Drive Identifier.
--force <boolean>: Force overriding existing index.
--output-format text|json|json-pretty: Output format.
--scan <boolean>: Re-read the whole tape to reconstruct the catalog instead of restoring saved versions.
--verbose <boolean>: Verbose mode - log all found chunks.

----

proxmox-tape changer config <name> [OPTIONS]

Get tape changer configuration

<name>: <string> Tape Changer Identifier.

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape changer create <name> --path <string> [OPTIONS]

Create a new changer device

<name>: <string> Tape Changer Identifier.
--path <string>: Path to Linux generic SCSI device (e.g. '/dev/sg4')

Optional parameters:

--eject-before-unload <boolean> (default=false): if set to true, tapes are ejected manually before unloading
--export-slots [<integer>, ...]: A list of slot numbers, comma separated. Those slots are reserved for Import/ Export, i.e. any media in those slots are considered to be 'offline'.

----

proxmox-tape changer list [OPTIONS]

List changers

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape changer remove <name>

Delete a tape changer configuration

<name>: <string> Tape Changer Identifier.

----

proxmox-tape changer scan [OPTIONS]

Scan for SCSI tape changers

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape changer status [<name>] [OPTIONS]

Get tape changer status

<name>: <string> Tape Changer Identifier.

Optional parameters:

--cache <boolean> (default=true): Use cached value.
--output-format text|json|json-pretty: Output format.

----

proxmox-tape changer transfer [<name>] --from <integer> (1 - N) --to <integer> (1 - N)

Transfers media from one slot to another

<name>: <string> Tape Changer Identifier.
--from <integer> (1 - N): Source slot number
--to <integer> (1 - N): Destination slot number

----

proxmox-tape changer update <name> [OPTIONS]

Update a tape changer configuration

<name>: <string> Tape Changer Identifier.

Optional parameters:

--delete export-slots|eject-before-unload: List of properties to delete. Can be specified more than once.
--digest <string>: Prevent changes if current configuration file has different SHA256 digest. This can be used to prevent concurrent modifications.
--eject-before-unload <boolean> (default=false): if set to true, tapes are ejected manually before unloading
--export-slots [<integer>, ...]: A list of slot numbers, comma separated. Those slots are reserved for Import/ Export, i.e. any media in those slots are considered to be 'offline'.
--path <string>: Path to Linux generic SCSI device (e.g. '/dev/sg4')

----

proxmox-tape clean [OPTIONS]

Clean drive

Optional parameters:

--drive <string>: Drive Identifier.
--output-format text|json|json-pretty: Output format.

----

proxmox-tape drive config <name> [OPTIONS]

Get pool configuration

<name>: <string> Drive Identifier.

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape drive create <name> --path <string> [OPTIONS]

Create a new drive

<name>: <string> Drive Identifier.
--path <string>: The path to a LTO SCSI-generic tape device (i.e. '/dev/sg0')

Optional parameters:

--changer <string>: Tape Changer Identifier.
--changer-drivenum <integer> (0 - 255) (default=0): Associated changer drive number (requires option changer)

----

proxmox-tape drive list [OPTIONS]

List drives

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape drive remove <name>

Delete a drive configuration

<name>: <string> Drive Identifier.

----

proxmox-tape drive scan [OPTIONS]

Scan for drives

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape drive update <name> [OPTIONS]

Update a drive configuration

<name>: <string> Drive Identifier.

Optional parameters:

--changer <string>: Tape Changer Identifier.
--changer-drivenum <integer> (0 - 255) (default=0): Associated changer drive number (requires option changer)
--delete changer|changer-drivenum: List of properties to delete. Can be specified more than once.
--digest <string>: Prevent changes if current configuration file has different SHA256 digest. This can be used to prevent concurrent modifications.
--path <string>: The path to a LTO SCSI-generic tape device (i.e. '/dev/sg0')

----

proxmox-tape eject [OPTIONS]

Eject/Unload drive media

Optional parameters:

--drive <string>: Drive Identifier.
--output-format text|json|json-pretty: Output format.

----

proxmox-tape eod [OPTIONS]

Move to end of media (MTEOM, used to debug)

Optional parameters:

--drive <string>: Drive Identifier.

----

proxmox-tape export-media <label-text> [OPTIONS]

Export media with specified label

<label-text>: <string> Media Label/Barcode.

Optional parameters:

--drive <string>: Drive Identifier.

----

proxmox-tape format [OPTIONS]

Format media

Optional parameters:

--drive <string>: Drive Identifier.
--fast <boolean> (default=true): Use fast erase.
--output-format text|json|json-pretty: Output format.

----

proxmox-tape 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-tape inventory [OPTIONS]

List (and update) media labels (Changer Inventory)

Optional parameters:

--catalog <boolean> (default=false): Try to restore catalogs from tapes.
--drive <string>: Drive Identifier.
--output-format text|json|json-pretty: Output format.
--read-all-labels <boolean> (default=false): Load all tapes and try read labels (even if already inventoried)
--read-labels <boolean> (default=false): Load unknown tapes and try read labels

----

proxmox-tape key change-passphrase <fingerprint> --hint <string> [OPTIONS]

Change the encryption key's password.

<fingerprint>: <string> Tape encryption key fingerprint (sha256).
--hint <string>: Password hint.

Optional parameters:

--force <boolean> (default=false): Reset the passphrase for a tape key, without asking for the old one.
--kdf none|scrypt|pbkdf2 (default=scrypt): Key derivation function for password protected encryption keys.

----

proxmox-tape key create --hint <string> [OPTIONS]

Create key (read password from stdin)

--hint <string>: Password restore hint.

Optional parameters:

--kdf none|scrypt|pbkdf2 (default=scrypt): Key derivation function for password protected encryption keys.

----

proxmox-tape key list [OPTIONS]

List keys

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape key paperkey <fingerprint> [OPTIONS]

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

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

<fingerprint>: <string> Tape encryption key fingerprint (sha256).

Optional parameters:

--output-format text|html: Paperkey output format
--subject <string>: Include the specified subject as title text.

----

proxmox-tape key remove <fingerprint> [OPTIONS]

Remove a encryption key from the database

Please note that you can no longer access tapes using this key.

<fingerprint>: <string> Tape encryption key fingerprint (sha256).

Optional parameters:

--digest <string>: Prevent changes if current configuration file has different SHA256 digest. This can be used to prevent concurrent modifications.

----

proxmox-tape key restore [OPTIONS]

Restore encryption key from tape or from a backup file/string (reads password from stdin)

Optional parameters:

--drive <string>: Drive Identifier.
--key <string>: Import key from json string or an exported paperkey-format.
--key-file <string>: Import key from a file with either json or exported paperkey-format.

----

proxmox-tape key show <fingerprint> [OPTIONS]

Print the encryption key's metadata.

<fingerprint>: <string> Tape encryption key fingerprint (sha256).

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape label --label-text <string> [OPTIONS]

Label media

--label-text <string>: Media Label/Barcode.

Optional parameters:

--drive <string>: Drive Identifier.
--output-format text|json|json-pretty: Output format.
--pool <string>: Media pool name.

----

proxmox-tape load-media <label-text> [OPTIONS]

Load media with specified label

<label-text>: <string> Media Label/Barcode.

Optional parameters:

--drive <string>: Drive Identifier.
--output-format text|json|json-pretty: Output format.

----

proxmox-tape load-media-from-slot <source-slot> [OPTIONS]

Load media from the specified slot

<source-slot>: <integer> (1 - N) Source slot number.

Optional parameters:

--drive <string>: Drive Identifier.

----

proxmox-tape media content [OPTIONS]

List media content

Optional parameters:

--backup-id <string>: Backup ID.
--backup-type vm|ct|host: Backup types.
--label-text <string>: Media Label/Barcode.
--media <string>: Media Uuid.
--media-set <string>: MediaSet Uuid (We use the all-zero Uuid to reserve an empty media for a specific pool).
--output-format text|json|json-pretty: Output format.
--pool <string>: Media pool name.

----

proxmox-tape media destroy [<label-text>] [OPTIONS]

Destroy media (completely remove from database)

<label-text>: <string> Media Label/Barcode.

Optional parameters:

--force <boolean>: Force removal (even if media is used in a media set).
--uuid <string>: Media Uuid.

----

proxmox-tape media list [OPTIONS]

List pool media

Optional parameters:

--output-format text|json|json-pretty: Output format.
--pool <string>: Media pool name.
--update-status <boolean> (default=true): Try to update tape library status (check what tapes are online).
--update-status-changer <string>: Tape Changer Identifier.

----

proxmox-tape pool config <name> [OPTIONS]

Get media pool configuration

<name>: <string> Media pool name.

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape pool create <name> [OPTIONS]

Create a new media pool

<name>: <string> Media pool name.

Optional parameters:

--allocation <string>: Media set allocation policy ('continue', 'always', or a calendar event).
--comment <string>: Comment.
--encrypt <string>: Tape encryption key fingerprint (sha256).
--retention <string>: Media retention policy ('overwrite', 'keep', or time span).
--template <string>: Media set naming template (may contain strftime() time format specifications).

----

proxmox-tape pool list [OPTIONS]

List media pool

Optional parameters:

--output-format text|json|json-pretty: Output format.

----

proxmox-tape pool remove <name>

Delete a media pool configuration

<name>: <string> Media pool name.

----

proxmox-tape pool update <name> [OPTIONS]

Update media pool settings

<name>: <string> Media pool name.

Optional parameters:

--allocation <string>: Media set allocation policy ('continue', 'always', or a calendar event).
--comment <string>: Comment.
--delete allocation|retention|template|encrypt|comment: List of properties to delete. Can be specified more than once.
--encrypt <string>: Tape encryption key fingerprint (sha256).
--retention <string>: Media retention policy ('overwrite', 'keep', or time span).
--template <string>: Media set naming template (may contain strftime() time format specifications).

----

proxmox-tape read-label [OPTIONS]

Read media label

Optional parameters:

--drive <string>: Drive Identifier.
--inventorize <boolean>: Inventorize media
--output-format text|json|json-pretty: Output format.

----

proxmox-tape restore <media-set> <store> [{<snapshots>}] [OPTIONS]

Restore data from media-set

<media-set>: <string> Media set UUID.
<store>: [(<source>=)?<target>, ...] A list of Datastore mappings (or single datastore), comma separated. For example 'a=b,e' maps the source datastore 'a' to target 'b and all other sources to the default 'e'. If no default is given, only the specified sources are mapped.
<snapshots>: store:[ns/namespace/...]type/id/time List of snapshots. Can be specified more than once.

Optional parameters:

--drive <string>: Drive Identifier.
--namespaces [store=<string> [,max-depth=<integer>] [,source=<string>] [,target=<string>]]: List of namespace to restore. Can be specified more than once.
--notify-user <string>: User ID
--output-format text|json|json-pretty: Output format.
--owner <string>: Authentication ID

----

proxmox-tape rewind [OPTIONS]

Rewind tape

Optional parameters:

--drive <string>: Drive Identifier.
--output-format text|json|json-pretty: Output format.

----

proxmox-tape scan [OPTIONS]

Rewind, then read media contents and print debug info

Note: This reads unless the driver returns an IO Error, so this method is expected to fails when we reach EOT.

Optional parameters:

--drive <string>: Drive Identifier.

----

proxmox-tape status [OPTIONS]

Get drive/media status

Optional parameters:

--drive <string>: Drive Identifier.
--output-format text|json|json-pretty: Output format.

----

proxmox-tape unload [OPTIONS]

Unload media via changer

Optional parameters:

--drive <string>: Drive Identifier.
--output-format text|json|json-pretty: Output format.
--target-slot <integer> (1 - N): Target slot number. If omitted, defaults to the slot that the drive was loaded from.

----

proxmox-tape volume-statistics [OPTIONS]

Read Volume Statistics (SCSI log page 17h)

Optional parameters:

--drive <string>: Drive Identifier.
--output-format text|json|json-pretty: Output format.

DESCRIPTION

This tool can configure and manage tape backups.

COPYRIGHT AND DISCLAIMER

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/

AUTHOR

Proxmox Support Team

COPYRIGHT

2019-2026, Proxmox Server Solutions GmbH

Wednesday, 06 May 2026