Tape Backup¶
Caution
Tape Backup is a technical preview feature, not meant for production use. To enable it in the GUI, you need to issue the following command (as root user on the console):
# touch /etc/proxmox-backup/tape.cfg
Proxmox tape backup provides an easy way to store datastore content onto magnetic tapes. This increases data safety because you get:
- an additional copy of the data,
- on a different media type (tape),
- to an additional location (you can move tapes off-site)
In most restore jobs, only data from the last backup job is restored. Restore requests further decline, the older the data gets. Considering this, tape backup may also help to reduce disk usage, because you can safely remove data from disk, once it's archived on tape. This is especially true if you need to retain data for several years.
Tape backups do not provide random access to the stored data. Instead, you need to restore the data to disk, before you can access it again. Also, if you store your tapes off-site (using some kind of tape vaulting service), you need to bring them back on-site, before you can do any restores. So please consider that restoring from tape can take much longer than restoring from disk.
Tape Technology Primer¶
As of 2021, the only widely available tape technology standard is Linear Tape-Open (LTO). Different vendors offer LTO Ultrium tape drives, auto-loaders, and LTO tape cartridges.
There are a few vendors that offer proprietary drives with slight advantages in performance and capacity. Nevertheless, they have significant disadvantages:
- proprietary (single vendor)
- a much higher purchase cost
So we currently do not test such drives.
In general, LTO tapes offer the following advantages:
- Durability (30 year lifespan)
- High Capacity (12 TB)
- Relatively low cost per TB
- Cold Media
- Movable (storable inside vault)
- Multiple vendors (for both media and drives)
- Build in AES-GCM Encryption engine
Note that Proxmox Backup Server already stores compressed data, so using the tape compression feature has no advantage.
Supported Hardware¶
Proxmox Backup Server supports Linear Tape-Open generation 4 (LTO-4) or later. In general, all SCSI-2 tape drives supported by the Linux kernel should work, but features like hardware encryption need LTO-4 or later.
Tape changing is carried out using the Linux 'mtx' command line tool, so any changer device supported by this tool should work.
Drive Performance¶
Current LTO-8 tapes provide read/write speeds of up to 360 MB/s. This means, that it still takes a minimum of 9 hours to completely write or read a single tape (even at maximum speed).
The only way to speed up that data rate is to use more than one drive. That way, you can run several backup jobs in parallel, or run restore jobs while the other dives are used for backups.
Also consider that you first need to read data from your datastore (disk). However, a single spinning disk is unable to deliver data at this rate. We measured a maximum rate of about 60MB/s to 100MB/s in practice, so it takes 33 hours to read the 12TB needed to fill up an LTO-8 tape. If you want to write to your tape at full speed, please make sure that the source datastore is able to deliver that performance (e.g, by using SSDs).
Terminology¶
Tape Labels: | are used to uniquely identify a tape. You would normally apply a sticky paper label to the front of the cartridge. We additionally store the label text magnetically on the tape (first file on tape). |
---|
Barcodes: | are a special form of tape labels, which are electronically readable. Most LTO tape robots use an 8 character string encoded as Code 39, as defined in the LTO Ultrium Cartridge Label Specification. You can either buy such barcode labels from your cartridge vendor, or print them yourself. You can use our LTO Barcode Generator app, if you would like to print them yourself. |
---|
Note
Physical labels and the associated adhesive should have an environmental performance to match or exceed the environmental specifications of the cartridge to which it is applied.
Media Pools: | A media pool is a logical container for tapes. A backup job targets one media pool, so a job only uses tapes from that pool. The pool additionally defines how long a backup job can append data to tapes (allocation policy) and how long you want to keep the data (retention policy). |
---|---|
Media Set: | A group of continuously written tapes (all from the same media pool). |
Tape drive: | The device used to read and write data to the tape. There are standalone drives, but drives are usually shipped within tape libraries. |
Tape changer: | A device which can change the tapes inside a tape drive (tape robot). They are usually part of a tape library. |
Tape library: | A storage device that contains one or more tape drives, a number of slots to hold tape cartridges, a barcode reader to identify tape cartridges, and an automated method for loading tapes (a robot). This is also commonly known as an 'autoloader', 'tape robot' or 'tape jukebox'. |
---|---|
Inventory: | The inventory stores the list of known tapes (with additional status information). |
Catalog: | A media catalog stores information about the media content. |
Tape Quick Start¶
- Configure your tape hardware (drives and changers)
- Configure one or more media pools
- Label your tape cartridges
- Start your first tape backup job ...
Configuration¶
Please note that you can configure anything using the graphical user interface or the command line interface. Both methods result in the same configuration.
Tape changers¶
Tape changers (robots) are part of a Tape Library. You can skip this step if you are using a standalone drive.
Linux is able to auto detect these devices, and you can get a list of available devices using:
# proxmox-tape changer scan
┌─────────────────────────────┬─────────┬──────────────┬────────┐
│ path │ vendor │ model │ serial │
╞═════════════════════════════╪═════════╪══════════════╪════════╡
│ /dev/tape/by-id/scsi-CC2C52 │ Quantum │ Superloader3 │ CC2C52 │
└─────────────────────────────┴─────────┴──────────────┴────────┘
In order to use a device with Proxmox Backup Server, you need to create a configuration entry:
# proxmox-tape changer create sl3 --path /dev/tape/by-id/scsi-CC2C52
Where sl3
is an arbitrary name you can choose.
Note
Please use the persistent device path names from inside
/dev/tape/by-id/
. Names like /dev/sg0
may point to a
different device after reboot, and that is not what you want.
You can display the final configuration with:
# proxmox-tape changer config sl3
┌──────┬─────────────────────────────┐
│ Name │ Value │
╞══════╪═════════════════════════════╡
│ name │ sl3 │
├──────┼─────────────────────────────┤
│ path │ /dev/tape/by-id/scsi-CC2C52 │
└──────┴─────────────────────────────┘
Or simply list all configured changer devices:
# proxmox-tape changer list
┌──────┬─────────────────────────────┬─────────┬──────────────┬────────────┐
│ name │ path │ vendor │ model │ serial │
╞══════╪═════════════════════════════╪═════════╪══════════════╪════════════╡
│ sl3 │ /dev/tape/by-id/scsi-CC2C52 │ Quantum │ Superloader3 │ CC2C52 │
└──────┴─────────────────────────────┴─────────┴──────────────┴────────────┘
The Vendor, Model and Serial number are auto detected, but only shown if the device is online.
To test your setup, please query the status of the changer device with:
# proxmox-tape changer status sl3
┌───────────────┬──────────┬────────────┬─────────────┐
│ entry-kind │ entry-id │ changer-id │ loaded-slot │
╞═══════════════╪══════════╪════════════╪═════════════╡
│ drive │ 0 │ vtape1 │ 1 │
├───────────────┼──────────┼────────────┼─────────────┤
│ slot │ 1 │ │ │
├───────────────┼──────────┼────────────┼─────────────┤
│ slot │ 2 │ vtape2 │ │
├───────────────┼──────────┼────────────┼─────────────┤
│ ... │ ... │ │ │
├───────────────┼──────────┼────────────┼─────────────┤
│ slot │ 16 │ │ │
└───────────────┴──────────┴────────────┴─────────────┘
Tape libraries usually provide some special import/export slots (also
called "mail slots"). Tapes inside those slots are accessible from
outside, making it easy to add/remove tapes to/from the library. Those
tapes are considered to be "offline", so backup jobs will not use
them. Those special slots are auto-detected and marked as an
import-export
slot in the status command.
It's worth noting that some of the smaller tape libraries don't have such slots. While they have something called a "Mail Slot", that slot is just a way to grab the tape from the gripper. They are unable to hold media while the robot does other things. They also do not expose that "Mail Slot" over the SCSI interface, so you wont see them in the status output.
As a workaround, you can mark some of the normal slots as export
slot. The software treats those slots like real import-export
slots, and the media inside those slots is considered to be 'offline'
(not available for backup):
# proxmox-tape changer update sl3 --export-slots 15,16
After that, you can see those artificial import-export
slots in
the status output:
# proxmox-tape changer status sl3
┌───────────────┬──────────┬────────────┬─────────────┐
│ entry-kind │ entry-id │ changer-id │ loaded-slot │
╞═══════════════╪══════════╪════════════╪═════════════╡
│ drive │ 0 │ vtape1 │ 1 │
├───────────────┼──────────┼────────────┼─────────────┤
│ import-export │ 15 │ │ │
├───────────────┼──────────┼────────────┼─────────────┤
│ import-export │ 16 │ │ │
├───────────────┼──────────┼────────────┼─────────────┤
│ slot │ 1 │ │ │
├───────────────┼──────────┼────────────┼─────────────┤
│ slot │ 2 │ vtape2 │ │
├───────────────┼──────────┼────────────┼─────────────┤
│ ... │ ... │ │ │
├───────────────┼──────────┼────────────┼─────────────┤
│ slot │ 14 │ │ │
└───────────────┴──────────┴────────────┴─────────────┘
Tape drives¶
Linux is able to auto detect tape drives, and you can get a list of available tape drives using:
# proxmox-tape drive scan
┌────────────────────────────────┬────────┬─────────────┬────────┐
│ path │ vendor │ model │ serial │
╞════════════════════════════════╪════════╪═════════════╪════════╡
│ /dev/tape/by-id/scsi-12345-nst │ IBM │ ULT3580-TD4 │ 12345 │
└────────────────────────────────┴────────┴─────────────┴────────┘
In order to use that drive with Proxmox, you need to create a configuration entry:
# proxmox-tape drive create mydrive --path /dev/tape/by-id/scsi-12345-nst
Note
Please use the persistent device path names from inside
/dev/tape/by-id/
. Names like /dev/nst0
may point to a
different device after reboot, and that is not what you want.
If you have a tape library, you also need to set the associated changer device:
# proxmox-tape drive update mydrive --changer sl3 --changer-drivenum 0
The --changer-drivenum
is only necessary if the tape library
includes more than one drive (the changer status command lists all
drive numbers).
You can display the final configuration with:
# proxmox-tape drive config mydrive
┌─────────┬────────────────────────────────┐
│ Name │ Value │
╞═════════╪════════════════════════════════╡
│ name │ mydrive │
├─────────┼────────────────────────────────┤
│ path │ /dev/tape/by-id/scsi-12345-nst │
├─────────┼────────────────────────────────┤
│ changer │ sl3 │
└─────────┴────────────────────────────────┘
Note
The changer-drivenum
value 0 is not stored in the
configuration, because it is the default.
To list all configured drives use:
# proxmox-tape drive list
┌──────────┬────────────────────────────────┬─────────┬────────┬─────────────┬────────┐
│ name │ path │ changer │ vendor │ model │ serial │
╞══════════╪════════════════════════════════╪═════════╪════════╪═════════════╪════════╡
│ mydrive │ /dev/tape/by-id/scsi-12345-nst │ sl3 │ IBM │ ULT3580-TD4 │ 12345 │
└──────────┴────────────────────────────────┴─────────┴────────┴─────────────┴────────┘
The Vendor, Model and Serial number are auto detected, but only shown if the device is online.
For testing, you can simply query the drive status with:
# proxmox-tape status --drive mydrive
┌───────────┬────────────────────────┐
│ Name │ Value │
╞═══════════╪════════════════════════╡
│ blocksize │ 0 │
├───────────┼────────────────────────┤
│ status │ DRIVE_OPEN | IM_REP_EN │
└───────────┴────────────────────────┘
Note
Blocksize should always be 0 (variable block size mode). This is the default anyway.
Media Pools¶
A media pool is a logical container for tapes. A backup job targets one media pool, so a job only uses tapes from that pool.
Media Set
A media set is a group of continuously written tapes, used to split the larger pool into smaller, restorable units. One or more backup jobs write to a media set, producing an ordered group of tapes. Media sets are identified by a unique ID. That ID and the sequence number are stored on each tape of that set (tape label).
Media sets are the basic unit for restore tasks. This means that you need every tape in the set to restore the media set contents. Data is fully deduplicated inside a media set.
Media Set Allocation Policy
The pool additionally defines how long backup jobs can append data to a media set. The following settings are possible:
Try to use the current media set (
continue
).This setting produces one large media set. While this is very space efficient (deduplication, no unused space), it can lead to long restore times, because restore jobs need to read all tapes in the set.
Note
Data is fully deduplicated inside a media set. This also means that data is randomly distributed over the tapes in the set. Thus, even if you restore a single VM, data may have to be read from all tapes inside the media set.
Larger media sets are also more error-prone, because a single damaged tape makes the restore fail.
Usage scenario: Mostly used with tape libraries. You manually trigger new set creation by running a backup job with the
--export
option.Note
Retention period starts with the existence of a newer media set.
Always create a new media set (
always
).With this setting, each backup job creates a new media set. This is less space efficient, because the media from the last set may not be fully written, leaving the remaining space unused.
The advantage is that this procudes media sets of minimal size. Small sets are easier to handle, can be moved more conveniently to an off-site vault, and can be restored much faster.
Note
Retention period starts with the creation time of the media set.
Create a new set when the specified Calendar Event triggers.
This allows you to specify points in time by using systemd like Calendar Event specifications (see systemd.time manpage).
For example, the value
weekly
(orMon *-*-* 00:00:00
) will create a new set each week.This balances between space efficiency and media count.
Note
Retention period starts when the calendar event triggers.
Additionally, the following events may allocate a new media set:
- Required tape is offline (and you use a tape library).
- Current set contains damaged or retired tapes.
- Media pool encryption has changed
- Database consistency errors, for example, if the inventory does not contain the required media information, or it contains conflicting information (outdated data).
Retention Policy
Defines how long we want to keep the data.
Always overwrite media.
Protect data for the duration specified.
We use systemd like time spans to specify durations, e.g.
2 weeks
(see systemd.time manpage).Never overwrite data.
Hardware Encryption
LTO-4 (or later) tape drives support hardware encryption. If you configure the media pool to use encryption, all data written to the tapes is encrypted using the configured key.
This way, unauthorized users cannot read data from the media, for example, if you loose a tape while shipping to an offsite location.
Note
If the backup client also encrypts data, data on the tape will be double encrypted.
The password protected key is stored on each medium, so that it is possbible to restore the key using the password. Please make sure to remember the password, in case you need to restore the key.
Note
We use global content namespace, meaning we do not store the source datastore name. Because of this, it is impossible to distinguish store1:/vm/100 from store2:/vm/100. Please use different media pools if the sources are from different namespaces with conflicting names (for example, if the sources are from different Proxmox VE clusters).
The following command creates a new media pool:
// proxmox-tape pool create <name> --drive <string> [OPTIONS]
# proxmox-tape pool create daily --drive mydrive
Additional option can be set later, using the update command:
# proxmox-tape pool update daily --allocation daily --retention 7days
To list all configured pools use:
# proxmox-tape pool list
┌───────┬──────────┬────────────┬───────────┬──────────┐
│ name │ drive │ allocation │ retention │ template │
╞═══════╪══════════╪════════════╪═══════════╪══════════╡
│ daily │ mydrive │ daily │ 7days │ │
└───────┴──────────┴────────────┴───────────┴──────────┘
Tape Backup Jobs¶
To automate tape backup, you can configure tape backup jobs which write datastore content to a media pool, based on a specific time schedule. The required settings are:
store
: The datastore you want to backuppool
: The media pool - only tape cartridges from that pool are used.drive
: The tape drive.schedule
: Job schedule (see Calendar Events)
For example, to configure a tape backup job for datastore vmstore1
use:
# proxmox-tape backup-job create job2 --store vmstore1 \
--pool yourpool --drive yourdrive --schedule daily
The backup includes all snapshots from a backup group by default. You can
set the latest-only
flag to include only the latest snapshots:
# proxmox-tape backup-job update job2 --latest-only
Backup jobs can use email to send tape request notifications or report errors. You can set the notification user with:
# proxmox-tape backup-job update job2 --notify-user root@pam
Note
The email address is a property of the user (see User Management).
It is sometimes useful to eject the tape from the drive after a
backup. For a standalone drive, the eject-media
option ejects the
tape, making sure that the following backup cannot use the tape
(unless someone manually loads the tape again). For tape libraries,
this option unloads the tape to a free slot, which provides better
dust protection than inside a drive:
# proxmox-tape backup-job update job2 --eject-media
Note
For failed jobs, the tape remains in the drive.
For tape libraries, the export-media
option moves all tapes from
the media set to an export slot, making sure that the following backup
cannot use the tapes. An operator can pick up those tapes and move them
to a vault.
# proxmox-tape backup-job update job2 --export-media
Note
The export-media
option can be used to force the start
of a new media set, because tapes from the current set are no
longer online.
It is also possible to run backup jobs manually:
# proxmox-tape backup-job run job2
To remove a job, please use:
# proxmox-tape backup-job remove job2
Administration¶
Many sub-commands of the proxmox-tape
command line tools take a
parameter called --drive
, which specifies the tape drive you want
to work on. For convenience, you can set this in an environment
variable:
# export PROXMOX_TAPE_DRIVE=mydrive
You can then omit the --drive
parameter from the command. If the
drive has an associated changer device, you may also omit the changer
parameter from commands that needs a changer device, for example:
# proxmox-tape changer status
should display the changer status of the changer device associated with
drive mydrive
.
Label Tapes¶
By default, tape cartridges all look the same, so you need to put a label on them for unique identification. First, put a sticky paper label with some human readable text on the cartridge.
If you use a Tape Library, you should use an 8 character string encoded as Code 39, as defined in the LTO Ultrium Cartridge Label Specification. You can either buy such barcode labels from your cartridge vendor, or print them yourself. You can use our LTO Barcode Generator app to print them.
Next, you need to write that same label text to the tape, so that the software can uniquely identify the tape too.
For a standalone drive, manually insert the new tape cartridge into the drive and run:
# proxmox-tape label --changer-id <label-text> [--pool <pool-name>]
You may omit the --pool
argument to allow the tape to be used by any pool.
Note
For safety reasons, this command fails if the tape contains any data. If you want to overwrite it anyway, erase the tape first.
You can verify success by reading back the label:
# proxmox-tape read-label
┌─────────────────┬──────────────────────────────────────┐
│ Name │ Value │
╞═════════════════╪══════════════════════════════════════╡
│ changer-id │ vtape1 │
├─────────────────┼──────────────────────────────────────┤
│ uuid │ 7f42c4dd-9626-4d89-9f2b-c7bc6da7d533 │
├─────────────────┼──────────────────────────────────────┤
│ ctime │ Wed Jan 6 09:07:51 2021 │
├─────────────────┼──────────────────────────────────────┤
│ pool │ daily │
├─────────────────┼──────────────────────────────────────┤
│ media-set-uuid │ 00000000-0000-0000-0000-000000000000 │
├─────────────────┼──────────────────────────────────────┤
│ media-set-ctime │ Wed Jan 6 09:07:51 2021 │
└─────────────────┴──────────────────────────────────────┘
Note
The media-set-uuid
using all zeros indicates an empty
tape (not used by any media set).
If you have a tape library, apply the sticky barcode label to the tape cartridges first. Then load those empty tapes into the library. You can then label all unlabeled tapes with a single command:
# proxmox-tape barcode-label [--pool <pool-name>]
Run Tape Backups¶
To manually run a backup job use:
# proxmox-tape backup <store> <pool> [OPTIONS]
The following options are available:
--eject-media | Eject media upon job completion. It is normally good practice to eject the tape after use. This unmounts the tape from the drive and prevents the tape from getting dusty. |
--export-media-set | |
Export media set upon job completion. After a successful backup job, this moves all tapes from the used media set into import-export slots. The operator can then pick up those tapes and move them to a media vault. |
Restore from Tape¶
Restore is done at media-set granularity, so you first need to find out which media set contains the data you want to restore. This information is stored in the media catalog. If you do not have media catalogs, you need to restore them first. Please note that you need the catalog to find your data, but restoring a complete media-set does not need media catalogs.
The following command lists the media content (from catalog):
# proxmox-tape media content
┌────────────┬──────┬──────────────────────────┬────────┬────────────────────────────────┬──────────────────────────────────────┐
│ label-text │ pool │ media-set-name │ seq-nr │ snapshot │ media-set-uuid │
╞════════════╪══════╪══════════════════════════╪════════╪════════════════════════════════╪══════════════════════════════════════╡
│ TEST01L8 │ p2 │ Wed Jan 13 13:55:55 2021 │ 0 │ vm/201/2021-01-11T10:43:48Z │ 9da37a55-aac7-4deb-91c6-482b3b675f30 │
├────────────┼──────┼──────────────────────────┼────────┼────────────────────────────────┼──────────────────────────────────────┤
│ ... │ ... │ ... │ ... │ ... │ ... │
└────────────┴──────┴──────────────────────────┴────────┴────────────────────────────────┴──────────────────────────────────────┘
A restore job reads the data from the media set and moves it back to data disk (datastore):
// proxmox-tape restore <media-set-uuid> <datastore>
# proxmox-tape restore 9da37a55-aac7-4deb-91c6-482b3b675f30 mystore
Update Inventory¶
Restore Catalog¶
Encryption Key Management¶
Creating a new encryption key:
# proxmox-tape key create --hint "tape pw 2020"
Tape Encryption Key Password: **********
Verify Password: **********
"14:f8:79:b9:f5:13:e5:dc:bf:b6:f9:88:48:51:81:dc:79:bf:a0:22:68:47:d1:73:35:2d:b6:20:e1:7f:f5:0f"
List existing encryption keys:
# proxmox-tape key list
┌───────────────────────────────────────────────────┬───────────────┐
│ fingerprint │ hint │
╞═══════════════════════════════════════════════════╪═══════════════╡
│ 14:f8:79:b9:f5:13:e5:dc: ... :b6:20:e1:7f:f5:0f │ tape pw 2020 │
└───────────────────────────────────────────────────┴───────────────┘
To show encryption key details:
# proxmox-tape key show 14:f8:79:b9:f5:13:e5:dc:...:b6:20:e1:7f:f5:0f
┌─────────────┬───────────────────────────────────────────────┐
│ Name │ Value │
╞═════════════╪═══════════════════════════════════════════════╡
│ kdf │ scrypt │
├─────────────┼───────────────────────────────────────────────┤
│ created │ Sat Jan 23 14:47:21 2021 │
├─────────────┼───────────────────────────────────────────────┤
│ modified │ Sat Jan 23 14:47:21 2021 │
├─────────────┼───────────────────────────────────────────────┤
│ fingerprint │ 14:f8:79:b9:f5:13:e5:dc:...:b6:20:e1:7f:f5:0f │
├─────────────┼───────────────────────────────────────────────┤
│ hint │ tape pw 2020 │
└─────────────┴───────────────────────────────────────────────┘
The paperkey
subcommand can be used to create a QR encoded
version of a tape encryption key. The following command sends the output of the
paperkey
command to a text file, for easy printing:
proxmox-tape key paperkey <fingerprint> --output-format text > qrkey.txt
Restoring Encryption Keys¶
You can restore the encryption key from the tape, using the password used to generate the key. First, load the tape you want to restore into the drive. Then run:
# proxmox-tape key restore
Tepe Encryption Key Password: ***********
If the password is correct, the key will get imported to the database. Further restore jobs automatically use any available key.
Tape Cleaning¶
LTO tape drives require regular cleaning. This is done by loading a cleaning cartridge into the drive, which is a manual task for standalone drives.
For tape libraries, cleaning cartridges are identified using special labels starting with letters "CLN". For example, our tape library has a cleaning cartridge inside slot 3:
# proxmox-tape changer status sl3
┌───────────────┬──────────┬────────────┬─────────────┐
│ entry-kind │ entry-id │ changer-id │ loaded-slot │
╞═══════════════╪══════════╪════════════╪═════════════╡
│ drive │ 0 │ vtape1 │ 1 │
├───────────────┼──────────┼────────────┼─────────────┤
│ slot │ 1 │ │ │
├───────────────┼──────────┼────────────┼─────────────┤
│ slot │ 2 │ vtape2 │ │
├───────────────┼──────────┼────────────┼─────────────┤
│ slot │ 3 │ CLN001CU │ │
├───────────────┼──────────┼────────────┼─────────────┤
│ ... │ ... │ │ │
└───────────────┴──────────┴────────────┴─────────────┘
To initiate a cleaning operation simply run:
# proxmox-tape clean
This command does the following:
- find the cleaning tape (in slot 3)
- unload the current media from the drive (back to slot 1)
- load the cleaning tape into the drive
- run drive cleaning operation
- unload the cleaning tape (to slot 3)
Configuration Files¶
media-pool.cfg
¶
File Format¶
Each entry starts with a header pool: <name>
, followed by the
media pool configuration options.
pool: company1
allocation always
retention overwrite
pool: ...
You can use the proxmox-tape pool
command to manipulate this file.
Options¶
Optional properties:
allocation
:<string>
- Media set allocation policy ('continue', 'always', or a calendar event).
comment
:<string>
- Comment (single line).
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).
tape.cfg
¶
File Format¶
Each drive configuration section starts with a header linux: <name>
,
followed by the drive configuration options.
Tape changer configurations starts with changer: <name>
,
followed by the changer configuration options.
linux: hh8
changer sl3
path /dev/tape/by-id/scsi-10WT065325-nst
changer: sl3
export-slots 14,15,16
path /dev/tape/by-id/scsi-CJ0JBE0059
You can use the proxmox-tape drive
and proxmox-tape changer
commands to manipulate this file.
Note
The virtual:
drive type is experimental and onyl used
for debugging.
Options¶
Section type 'linux
': Linux SCSI tape driver
Required properties:
path
:<string>
- The path to a LINUX non-rewinding SCSI tape device (i.e. '/dev/nst0')
Optional properties:
changer
:<string>
- Tape Changer Identifier.
changer-drivenum
:<integer> (0 - 8) (default=0)
- Associated changer drive number (requires option changer)
Section type 'virtual
': Simulate tape drives (only for test and debug)
Required properties:
path
:<string>
- Path to directory
Optional properties:
max-size
:<integer> (0 - N)
- Virtual tape size
Section type 'changer
': SCSI tape changer
Required properties:
path
:<string>
- Path to Linux generic SCSI device (e.g. '/dev/sg4')
Optional properties:
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'.
tape-job.cfg
¶
File Format¶
Each entry starts with a header backup: <name>
, followed by the
job configuration options.
backup: job1
drive hh8
pool p4
store store3
schedule daily
backup: ...
You can use the proxmox-tape backup-job
command to manipulate
this file.
Options¶
Required properties:
drive
:<string>
- Drive Identifier.
pool
:<string>
- Media pool name.
store
:<string>
- Datastore name.
Optional properties:
comment
:<string>
- Comment (single line).
schedule
:<calendar-event>
- Run sync job at specified schedule.
eject-media
:<boolean>
- Eject media upon job completion.
export-media-set
:<boolean>
- Export media set upon job completion.
latest-only
:<boolean>
- Backup latest snapshots only.
notify-user
:<string>
- User ID
Command Syntax¶
proxmox-tape
¶
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.
--latest-only
<boolean>
- Backup latest snapshots only.
--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 (single line).
--schedule
<calendar-event>
- Run sync job at specified schedule.
--eject-media
<boolean>
- Eject media upon job completion.
--export-media-set
<boolean>
- Export media set upon job completion.
--latest-only
<boolean>
- Backup latest snapshots only.
--notify-user
<string>
- User ID
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 (single line).
--delete
<array>
- List of properties to delete.
--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.
--latest-only
<boolean>
- Backup latest snapshots only.
--notify-user
<string>
- User ID
--pool
<string>
- Media pool name.
--schedule
<calendar-event>
- Run sync job at specified schedule.
--store
<string>
- Datastore name.
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:
--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
<array>
- List of properties to delete.
--digest
<string>
- Prevent changes if current configuration file has different SHA256 digest. This can be used to prevent concurrent modifications.
--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 LINUX non-rewinding SCSI tape device (i.e. '/dev/nst0')
Optional parameters:
--changer
<string>
- Tape Changer Identifier.
--changer-drivenum
<integer> (0 - 8) (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 - 8) (default=0)
- Associated changer drive number (requires option changer)
--delete
<array>
- List of properties to delete.
--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 LINUX non-rewinding SCSI tape device (i.e. '/dev/nst0')
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 erase [OPTIONS]
Erase media
Optional parameters:
--drive
<string>
- Drive Identifier.
--fast
<boolean> (default=true)
- Use fast erase.
--output-format
text|json|json-pretty
- Output format.
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 help [{<command>}] [OPTIONS]
Get help about specified command (or sub-command).
<command>
:<array>
- Command. This may be a list in order to spefify nested sub-commands.
Optional parameters:
--verbose
<boolean>
- Verbose help.
proxmox-tape inventory [OPTIONS]
List (and update) media labels (Changer Inventory)
Optional parameters:
--drive
<string>
- Drive Identifier.
--output-format
text|json|json-pretty
- Output format.
--read-all-labels
<boolean>
- Load all tapes and try read labels (even if already inventoried)
--read-labels
<boolean>
- Load unknown tapes and try read labels
proxmox-tape key change-passphrase <fingerprint> [OPTIONS]
Change the encryption key's password.
<fingerprint>
:<string>
- Tape encryption key fingerprint (sha256).
Optional parameters:
--hint
<string>
- Password hint.
--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 (read password from stdin)
Optional parameters:
--drive
<string>
- Drive Identifier.
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:
--output-format
text|json|json-pretty
- Output format.
--backup-id
<string>
- Backup ID.
--backup-type
vm|ct|host
- Backup type.
--label-text
<string>
- Media Label/Barcode.
--media
<string>
- Media Uuid.
--media-set
<string>
- MediaSet Uuid (We use the all-zero Uuid to reseve an empty media for a specific pool).
--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).
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 (single line).
--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 (single line).
--delete
<array>
- List of properties to delete.
--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> [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.
Optional parameters:
--drive
<string>
- Drive Identifier.
--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.
pmt
¶
All commands support the following parameters to specify the tape device:
--device <path> | |
Path to the Linux tape device | |
--drive <name> | Use drive from Proxmox Backup Server configuration. |
Commands which generate output support the --output-format
parameter. It accepts the following values:
text : | Text format (default). Human readable. |
---|---|
json : | JSON (single line). |
json-pretty : | JSON (multiple lines, nicely formatted). |
Device driver options can be specified as integer numbers (see
/usr/include/linux/mtio.h
), or using symbolic names:
buffer-writes : | Enable buffered writes |
---|---|
async-writes : | Enable async writes |
read-ahead : | Use read-ahead for fixed block size |
debugging : | Enable debugging if compiled into the driver |
two-fm : | Write two file marks when closing the file |
fast-mteom : | Space directly to eod (and lose file number) |
auto-lock : | Automatically lock/unlock drive door |
def-writes : | Defaults are meant only for writes |
can-bsr : | Indicates that the drive can space backwards |
no-blklims : | Drive does not support read block limits |
can-partitions : | Drive can handle partitioned tapes |
scsi2locical : | Seek and tell use SCSI-2 logical block addresses |
sysv : | Enable the System V semantics |
nowait : | Do not wait for rewind, etc. to complete |
sili : | Enables setting the SILI bit in SCSI commands when reading in variable block mode to enhance performance when reading blocks shorter than the byte count |
pmt asf <count>
Position the tape at the beginning of the count file.
Positioning is done by first rewinding the tape and then spacing forward over count file marks.
<count>
:<integer> (1 - 2147483647)
- File mark count.
pmt bsf <count>
Backward space count files (position before file mark).
The tape is positioned on the last block of the previous file.
<count>
:<integer> (1 - 2147483647)
- File mark count.
pmt bsfm <count>
Backward space count files, then forward space one record (position after file mark).
This leaves the tape positioned at the first block of the file that is count - 1 files before the current file.
<count>
:<integer> (1 - 2147483647)
- File mark count.
pmt bsr <count>
Backward space records.
<count>
:<integer> (1 - 2147483647)
- Record count.
pmt cartridge-memory
Read Cartridge Memory
pmt eject
Eject drive media
pmt eod
Move to end of media
pmt erase [OPTIONS]
Erase media
Optional parameters:
--fast
<boolean> (default=true)
- Use fast erase.
pmt fsf <count>
Forward space count files (position after file mark).
The tape is positioned on the first block of the next file.
<count>
:<integer> (1 - 2147483647)
- File mark count.
pmt fsfm <count>
Forward space count files, then backward space one record (position before file mark).
This leaves the tape positioned at the last block of the file that is count - 1 files past the current file.
<count>
:<integer> (1 - 2147483647)
- File mark count.
pmt fsr <count>
Forward space records.
<count>
:<integer> (1 - 2147483647)
- Record count.
pmt help [{<command>}] [OPTIONS]
Get help about specified command (or sub-command).
<command>
:<array>
- Command. This may be a list in order to spefify nested sub-commands.
Optional parameters:
--verbose
<boolean>
- Verbose help.
pmt load
Load media
pmt lock
Lock the tape drive door
pmt rewind
Rewind the tape
pmt scan
Scan for existing tape changer devices
pmt setblk <size>
Set the block size of the drive
<size>
:<integer> (0 - 2147483647)
- Block size in bytes.
pmt status
Drive Status
pmt stclearoptions {<options>}
Clear selected device driver options bits (root only)
<options>
:<array>
- Drive Option List.
pmt stoptions [{<options>}] [OPTIONS]
Set device driver options (root only)
<options>
:<array>
- Drive Option List.
Optional parameters:
--defaults
<boolean>
- Set default options (buffer-writes async-writes read-ahead can-bsr).
pmt stsetoptions {<options>}
Set selected device driver options bits (root only)
<options>
:<array>
- Drive Option List.
pmt tape-alert-flags
Read Tape Alert Flags
pmt unlock
Unlock the tape drive door
pmt volume-statistics
Volume Statistics
pmt weof [<count>]
Write count (default 1) EOF marks at current position.
<count>
:<integer> (1 - 2147483647)
- File mark count.
pmtx
¶
pmtx help [{<command>}] [OPTIONS]
Get help about specified command (or sub-command).
<command>
:<array>
- Command. This may be a list in order to spefify nested sub-commands.
Optional parameters:
--verbose
<boolean>
- Verbose help.
pmtx inquiry
Inquiry
pmtx inventory
Inventory
pmtx load <slot> [OPTIONS]
Load
<slot>
:<integer>
- Storage slot number (source).
Optional parameters:
--drivenum
<integer>
- Target drive number (defaults to Drive 0)
pmtx scan
Scan for existing tape changer devices
pmtx status
Changer Status
pmtx transfer <from> <to>
Transfer
<from>
:<integer>
- Source storage slot number.
<to>
:<integer>
- Target storage slot number.
pmtx unload [OPTIONS]
Unload
Optional parameters:
--drivenum
<integer>
- Target drive number (defaults to Drive 0)
--slot
<integer>
- Storage slot number (target). If omitted, defaults to the slot that the drive was loaded from.