docs/tape-backup.rst

   1 .. _tape_backup:
   2
   3 Tape Backup
   4 ===========
   5
   6 .. CAUTION:: Tape Backup is a technical preview feature, not meant for
   7    production use.
   8
   9 .. image:: images/screenshots/pbs-gui-tape-changer-overview.png
  10   :align: right
  11   :alt: Tape Backup: Tape changer overview
  12
  13 Proxmox tape backup provides an easy way to store datastore content
  14 onto magnetic tapes. This increases data safety because you get:
  15
  16 - an additional copy of the data,
  17 - on a different media type (tape),
  18 - to an additional location (you can move tapes off-site)
  19
  20 In most restore jobs, only data from the last backup job is restored.
  21 Restore requests further decline, the older the data
  22 gets. Considering this, tape backup may also help to reduce disk
  23 usage, because you can safely remove data from disk, once it's archived on
  24 tape. This is especially true if you need to retain data for several
  25 years.
  26
  27 Tape backups do not provide random access to the stored data. Instead,
  28 you need to restore the data to disk, before you can access it
  29 again. Also, if you store your tapes off-site (using some kind of tape
  30 vaulting service), you need to bring them back on-site, before you can do any
  31 restores. So please consider that restoring from tape can take much
  32 longer than restoring from disk.
  33
  34
  35 Tape Technology Primer
  36 ----------------------
  37
  38 .. _Linear Tape-Open: https://en.wikipedia.org/wiki/Linear_Tape-Open
  39
  40 As of 2021, the only widely available tape technology standard is
  41 `Linear Tape-Open`_ (LTO). Different vendors offer LTO Ultrium tape
  42 drives, auto-loaders, and LTO tape cartridges.
  43
  44 There are a few vendors that offer proprietary drives with
  45 slight advantages in performance and capacity. Nevertheless, they have
  46 significant disadvantages:
  47
  48 - proprietary (single vendor)
  49 - a much higher purchase cost
  50
  51 So we currently do not test such drives.
  52
  53 In general, LTO tapes offer the following advantages:
  54
  55 - Durability (30 year lifespan)
  56 - High Capacity (12 TB)
  57 - Relatively low cost per TB
  58 - Cold Media
  59 - Movable (storable inside vault)
  60 - Multiple vendors (for both media and drives)
  61 - Built in AES-GCM Encryption engine
  62
  63 Note that `Proxmox Backup Server` already stores compressed data, so using the
  64 tape compression feature has no advantage.
  65
  66
  67 Supported Hardware
  68 ------------------
  69
  70 Proxmox Backup Server supports `Linear Tape-Open`_ generation 5 (LTO-5)
  71 or later and has best-effort support for generation 4 (LTO-4). While
  72 many LTO-4 systems are known to work, some might need firmware updates or
  73 do not implement necessary features to work with Proxmox Backup Server.
  74
  75 Tape changing is carried out using the SCSI Medium Changer protocol,
  76 so all modern tape libraries should work.
  77
  78 .. Note:: We use a custom user space tape driver written in Rust_. This
  79    driver directly communicates with the tape drive using the SCSI
  80    generic interface. This may have negative side effects when used with the old
  81    Linux kernel tape driver, so you should not use that driver with
  82    Proxmox tape backup.
  83
  84
  85 Drive Performance
  86 ~~~~~~~~~~~~~~~~~
  87
  88 Current LTO-8 tapes provide read/write speeds of up to 360 MB/s. This means,
  89 that it still takes a minimum of 9 hours to completely write or
  90 read a single tape (even at maximum speed).
  91
  92 The only way to speed that data rate up is to use more than one
  93 drive. That way, you can run several backup jobs in parallel, or run
  94 restore jobs while the other dives are used for backups.
  95
  96 Also consider that you first need to read data from your datastore
  97 (disk). However, a single spinning disk is unable to deliver data at this
  98 rate. We measured a maximum rate of about 60MB/s to 100MB/s in practice,
  99 so it takes 33 hours to read the 12TB needed to fill up an LTO-8 tape. If you want
 100 to write to your tape at full speed, please make sure that the source
 101 datastore is able to deliver that performance (for example, by using SSDs).
 102
 103
 104 Terminology
 105 -----------
 106
 107 **Tape Labels:**
 108   are used to uniquely identify a tape. You would normally apply a
 109   sticky paper label to the front of the cartridge. We additionally
 110   store the label text magnetically on the tape (first file on tape).
 111
 112 .. _Code 39: https://en.wikipedia.org/wiki/Code_39
 113
 114 .. _LTO Ultrium Cartridge Label Specification: https://www.ibm.com/support/pages/ibm-lto-ultrium-cartridge-label-specification
 115
 116 .. _LTO Barcode Generator: lto-barcode/index.html
 117
 118 **Barcodes:**
 119   are a special form of tape labels, which are electronically
 120   readable. Most LTO tape robots use an 8 character string encoded as
 121   `Code 39`_, as defined in the `LTO Ultrium Cartridge Label
 122   Specification`_.
 123
 124   You can either buy such barcode labels from your cartridge vendor,
 125   or print them yourself. You can use our `LTO Barcode Generator`_
 126   app, if you would like to print them yourself.
 127
 128   .. Note:: Physical labels and the associated adhesive should have an
 129      environmental performance to match or exceed the environmental
 130      specifications of the cartridge to which it is applied.
 131
 132 **Media Pools:**
 133   A media pool is a logical container for tapes. A backup job targets
 134   one media pool, so a job only uses tapes from that pool. The pool
 135   additionally defines how long a backup job can append data to tapes
 136   (allocation policy) and how long you want to keep the data
 137   (retention policy).
 138
 139 **Media Set:**
 140   A group of continuously written tapes (all from the same media pool).
 141
 142 **Tape drive:**
 143   The device used to read and write data to the tape. There are
 144   standalone drives, but drives are usually shipped within tape
 145   libraries.
 146
 147 **Tape changer:**
 148   A device which can change the tapes inside a tape drive (tape
 149   robot). They are usually part of a tape library.
 150
 151 .. _Tape Library: https://en.wikipedia.org/wiki/Tape_library
 152
 153 `Tape library`_:
 154   A storage device that contains one or more tape drives, a number of
 155   slots to hold tape cartridges, a barcode reader to identify tape
 156   cartridges, and an automated method for loading tapes (a robot).
 157
 158   This is also commonly known as an 'autoloader', 'tape robot' or
 159   'tape jukebox'.
 160
 161 **Inventory:**
 162   The inventory stores the list of known tapes (with additional status
 163   information).
 164
 165 **Catalog:**
 166   A media catalog stores information about the media content.
 167
 168
 169 Tape Quick Start
 170 ----------------
 171
 172 1. Configure your tape hardware (drives and changers)
 173
 174 2. Configure one or more media pools
 175
 176 3. Label your tape cartridges
 177
 178 4. Start your first tape backup job ...
 179
 180
 181 Configuration
 182 -------------
 183
 184 Please note that you can configure anything using the graphical user
 185 interface or the command line interface. Both methods result in the
 186 same configuration.
 187
 188 .. _tape_changer_config:
 189
 190 Tape changers
 191 ~~~~~~~~~~~~~
 192
 193 .. image:: images/screenshots/pbs-gui-tape-changers.png
 194   :align: right
 195   :alt: Tape Backup: Tape Changers
 196
 197 Tape changers (robots) are part of a `Tape Library`_. They contain a number of
 198 slots to hold tape cartridges, a barcode reader to identify tape cartridges and
 199 an automated method for loading tapes.
 200
 201 You can skip this step if you are using a standalone drive.
 202
 203 Linux is able to auto detect these devices, and you can get a list
 204 of available devices using:
 205
 206 .. code-block:: console
 207
 208  # proxmox-tape changer scan
 209  ┌─────────────────────────────┬─────────┬──────────────┬────────┐
 210  │ path                        │ vendor  │ model        │ serial │
 211  ╞═════════════════════════════╪═════════╪══════════════╪════════╡
 212  │ /dev/tape/by-id/scsi-CC2C52 │ Quantum │ Superloader3 │ CC2C52 │
 213  └─────────────────────────────┴─────────┴──────────────┴────────┘
 214
 215 In order to use a device with Proxmox Backup Server, you need to create a
 216 configuration entry:
 217
 218 .. code-block:: console
 219
 220  # proxmox-tape changer create sl3 --path /dev/tape/by-id/scsi-CC2C52
 221
 222 Where ``sl3`` is an arbitrary name you can choose.
 223
 224 .. Note:: Please use the persistent device path names from inside
 225    ``/dev/tape/by-id/``. Names like ``/dev/sg0`` may point to a
 226    different device after reboot, and that is not what you want.
 227
 228 .. image:: images/screenshots/pbs-gui-tape-changers-add.png
 229   :align: right
 230   :alt: Tape Backup: Add a new tape changer
 231
 232 This operation can also be carried out from the GUI, by navigating to the
 233 **Changers** tab of **Tape Backup** and clicking **Add**.
 234
 235 You can display the final configuration with:
 236
 237 .. code-block:: console
 238
 239  # proxmox-tape changer config sl3
 240  ┌──────┬─────────────────────────────┐
 241  │ Name │ Value                       │
 242  ╞══════╪═════════════════════════════╡
 243  │ name │ sl3                         │
 244  ├──────┼─────────────────────────────┤
 245  │ path │ /dev/tape/by-id/scsi-CC2C52 │
 246  └──────┴─────────────────────────────┘
 247
 248 Or simply list all configured changer devices (as seen in the **Changers** tab
 249 of the GUI):
 250
 251 .. code-block:: console
 252
 253  # proxmox-tape changer list
 254  ┌──────┬─────────────────────────────┬─────────┬──────────────┬────────────┐
 255  │ name │ path                        │ vendor  │ model        │ serial     │
 256  ╞══════╪═════════════════════════════╪═════════╪══════════════╪════════════╡
 257  │ sl3  │ /dev/tape/by-id/scsi-CC2C52 │ Quantum │ Superloader3 │ CC2C52     │
 258  └──────┴─────────────────────────────┴─────────┴──────────────┴────────────┘
 259
 260 The Vendor, Model and Serial number are auto-detected, but only shown
 261 if the device is online.
 262
 263 To test your setup, please query the status of the changer device with:
 264
 265 .. code-block:: console
 266
 267  # proxmox-tape changer status sl3
 268  ┌───────────────┬──────────┬────────────┬─────────────┐
 269  │ entry-kind    │ entry-id │ changer-id │ loaded-slot │
 270  ╞═══════════════╪══════════╪════════════╪═════════════╡
 271  │ drive         │        0 │ vtape1     │           1 │
 272  ├───────────────┼──────────┼────────────┼─────────────┤
 273  │ slot          │        1 │            │             │
 274  ├───────────────┼──────────┼────────────┼─────────────┤
 275  │ slot          │        2 │ vtape2     │             │
 276  ├───────────────┼──────────┼────────────┼─────────────┤
 277  │ ...           │      ... │            │             │
 278  ├───────────────┼──────────┼────────────┼─────────────┤
 279  │ slot          │       16 │            │             │
 280  └───────────────┴──────────┴────────────┴─────────────┘
 281
 282 Tape libraries usually provide some special import/export slots (also
 283 called "mail slots"). Tapes inside those slots are accessible from
 284 outside, making it easy to add/remove tapes to/from the library. Those
 285 tapes are considered to be "offline", so backup jobs will not use
 286 them. Those special slots are auto-detected and marked as an
 287 ``import-export`` slot in the status command.
 288
 289 It's worth noting that some of the smaller tape libraries don't have
 290 such slots. While they have something called a "Mail Slot", that slot
 291 is just a way to grab the tape from the gripper. They are unable
 292 to hold media while the robot does other things. They also do not
 293 expose that "Mail Slot" over the SCSI interface, so you won't see them in
 294 the status output.
 295
 296 As a workaround, you can mark some of the normal slots as export
 297 slot. The software treats those slots like real ``import-export``
 298 slots, and the media inside those slots are considered to be 'offline'
 299 (not available for backup):
 300
 301 .. code-block:: console
 302
 303  # proxmox-tape changer update sl3 --export-slots 15,16
 304
 305 After that, you can see those artificial ``import-export`` slots in
 306 the status output:
 307
 308 .. code-block:: console
 309
 310  # proxmox-tape changer status sl3
 311  ┌───────────────┬──────────┬────────────┬─────────────┐
 312  │ entry-kind    │ entry-id │ changer-id │ loaded-slot │
 313  ╞═══════════════╪══════════╪════════════╪═════════════╡
 314  │ drive         │        0 │ vtape1     │           1 │
 315  ├───────────────┼──────────┼────────────┼─────────────┤
 316  │ import-export │       15 │            │             │
 317  ├───────────────┼──────────┼────────────┼─────────────┤
 318  │ import-export │       16 │            │             │
 319  ├───────────────┼──────────┼────────────┼─────────────┤
 320  │ slot          │        1 │            │             │
 321  ├───────────────┼──────────┼────────────┼─────────────┤
 322  │ slot          │        2 │ vtape2     │             │
 323  ├───────────────┼──────────┼────────────┼─────────────┤
 324  │ ...           │      ... │            │             │
 325  ├───────────────┼──────────┼────────────┼─────────────┤
 326  │ slot          │       14 │            │             │
 327  └───────────────┴──────────┴────────────┴─────────────┘
 328
 329 .. _tape_drive_config:
 330
 331 Tape drives
 332 ~~~~~~~~~~~
 333
 334 .. image:: images/screenshots/pbs-gui-tape-drives.png
 335   :align: right
 336   :alt: Tape Backup: Drive list
 337
 338 Linux is able to auto detect tape drives, and you can get a list
 339 of available tape drives using:
 340
 341 .. code-block:: console
 342
 343  # proxmox-tape drive scan
 344  ┌────────────────────────────────┬────────┬─────────────┬────────┐
 345  │ path                           │ vendor │ model       │ serial │
 346  ╞════════════════════════════════╪════════╪═════════════╪════════╡
 347  │ /dev/tape/by-id/scsi-12345-sg  │ IBM    │ ULT3580-TD4 │  12345 │
 348  └────────────────────────────────┴────────┴─────────────┴────────┘
 349
 350 .. image:: images/screenshots/pbs-gui-tape-drives-add.png
 351   :align: right
 352   :alt: Tape Backup: Add a tape drive
 353
 354 In order to use that drive with Proxmox, you need to create a
 355 configuration entry. This can be done through **Tape Backup -> Drives** in the
 356 GUI or by using the command below:
 357
 358 .. code-block:: console
 359
 360  # proxmox-tape drive create mydrive --path  /dev/tape/by-id/scsi-12345-sg
 361
 362 .. Note:: Please use the persistent device path names from inside
 363    ``/dev/tape/by-id/``. Names like ``/dev/sg0`` may point to a
 364    different device after reboot, and that is not what you want.
 365
 366 If you have a tape library, you also need to set the associated
 367 changer device:
 368
 369 .. code-block:: console
 370
 371  # proxmox-tape drive update mydrive --changer sl3  --changer-drivenum 0
 372
 373 The ``--changer-drivenum`` is only necessary if the tape library
 374 includes more than one drive (the changer status command lists all
 375 drive numbers).
 376
 377 You can display the final configuration with:
 378
 379 .. code-block:: console
 380
 381  # proxmox-tape drive config mydrive
 382  ┌─────────┬────────────────────────────────┐
 383  │ Name    │ Value                          │
 384  ╞═════════╪════════════════════════════════╡
 385  │ name    │ mydrive                        │
 386  ├─────────┼────────────────────────────────┤
 387  │ path    │ /dev/tape/by-id/scsi-12345-sg  │
 388  ├─────────┼────────────────────────────────┤
 389  │ changer │ sl3                            │
 390  └─────────┴────────────────────────────────┘
 391
 392 .. NOTE:: The ``changer-drivenum`` value 0 is not stored in the
 393    configuration, because it is the default.
 394
 395 To list all configured drives use:
 396
 397 .. code-block:: console
 398
 399  # proxmox-tape drive list
 400  ┌──────────┬────────────────────────────────┬─────────┬────────┬─────────────┬────────┐
 401  │ name     │ path                           │ changer │ vendor │ model       │ serial │
 402  ╞══════════╪════════════════════════════════╪═════════╪════════╪═════════════╪════════╡
 403  │ mydrive  │ /dev/tape/by-id/scsi-12345-sg  │ sl3     │ IBM    │ ULT3580-TD4 │ 12345  │
 404  └──────────┴────────────────────────────────┴─────────┴────────┴─────────────┴────────┘
 405
 406 The Vendor, Model and Serial number are auto detected and only shown
 407 if the device is online.
 408
 409 For testing, you can simply query the drive status with:
 410
 411 .. code-block:: console
 412
 413  # proxmox-tape status --drive mydrive
 414  ┌────────────────┬──────────────────────────┐
 415  │ Name           │ Value                    │
 416  ╞════════════════╪══════════════════════════╡
 417  │ blocksize      │ 0                        │
 418  ├────────────────┼──────────────────────────┤
 419  │ density        │ LTO4                     │
 420  ├────────────────┼──────────────────────────┤
 421  │ compression    │ 1                        │
 422  ├────────────────┼──────────────────────────┤
 423  │ buffer-mode    │ 1                        │
 424  ├────────────────┼──────────────────────────┤
 425  │ alert-flags    │ (empty)                  │
 426  ├────────────────┼──────────────────────────┤
 427  │ file-number    │ 0                        │
 428  ├────────────────┼──────────────────────────┤
 429  │ block-number   │ 0                        │
 430  ├────────────────┼──────────────────────────┤
 431  │ manufactured   │ Fri Dec 13 01:00:00 2019 │
 432  ├────────────────┼──────────────────────────┤
 433  │ bytes-written  │ 501.80 GiB               │
 434  ├────────────────┼──────────────────────────┤
 435  │ bytes-read     │ 4.00 MiB                 │
 436  ├────────────────┼──────────────────────────┤
 437  │ medium-passes  │ 20                       │
 438  ├────────────────┼──────────────────────────┤
 439  │ medium-wearout │ 0.12%                    │
 440  ├────────────────┼──────────────────────────┤
 441  │ volume-mounts  │ 2                        │
 442  └────────────────┴──────────────────────────┘
 443
 444 .. NOTE:: Blocksize should always be 0 (variable block size
 445    mode). This is the default anyway.
 446
 447
 448 .. _tape_media_pool_config:
 449
 450 Media Pools
 451 ~~~~~~~~~~~
 452
 453 .. image:: images/screenshots/pbs-gui-tape-pools.png
 454   :align: right
 455   :alt: Tape Backup: Media Pools
 456
 457 A media pool is a logical container for tapes. A backup job targets
 458 a single media pool, so a job only uses tapes from that pool.
 459
 460 .. topic:: Media Set
 461
 462    A media set is a group of continuously written tapes, used to split
 463    the larger pool into smaller, restorable units. One or more backup
 464    jobs write to a media set, producing an ordered group of
 465    tapes. Media sets are identified by a unique ID. That ID and the
 466    sequence number are stored on each tape of that set (tape label).
 467
 468    Media sets are the basic unit for restore tasks. This means that you need
 469    every tape in the set to restore the media set contents. Data is fully
 470    deduplicated inside a media set.
 471
 472
 473 .. topic:: Media Set Allocation Policy
 474
 475    The pool additionally defines how long backup jobs can append data
 476    to a media set. The following settings are possible:
 477
 478    - Try to use the current media set (``continue``).
 479
 480      This setting produces one large media set. While this is very
 481      space efficient (deduplication, no unused space), it can lead to
 482      long restore times, because restore jobs need to read all tapes in the
 483      set.
 484
 485      .. NOTE:: Data is fully deduplicated inside a media set. This
 486         also means that data is randomly distributed over the tapes in
 487         the set. Thus, even if you restore a single VM, data may have to be
 488         read from all tapes inside the media set.
 489
 490      Larger media sets are also more error-prone, because a single
 491      damaged tape makes the restore fail.
 492
 493      Usage scenario: Mostly used with tape libraries. You manually
 494      trigger new set creation by running a backup job with the
 495      ``--export`` option.
 496
 497      .. NOTE:: Retention period starts with the existence of a newer
 498         media set.
 499
 500    - Always create a new media set (``always``).
 501
 502      With this setting, each backup job creates a new media set. This
 503      is less space efficient, because the media from the last set
 504      may not be fully written, leaving the remaining space unused.
 505
 506      The advantage is that this procudes media sets of minimal
 507      size. Small sets are easier to handle, can be moved more conveniently
 508      to an off-site vault, and can be restored much faster.
 509
 510      .. NOTE:: Retention period starts with the creation time of the
 511         media set.
 512
 513    - Create a new set when the specified Calendar Event triggers.
 514
 515      .. _systemd.time manpage: https://manpages.debian.org/buster/systemd/systemd.time.7.en.html
 516
 517      This allows you to specify points in time by using systemd like
 518      Calendar Event specifications (see `systemd.time manpage`_).
 519
 520      For example, the value ``weekly`` (or ``Mon *-*-* 00:00:00``)
 521      will create a new set each week.
 522
 523      This balances between space efficiency and media count.
 524
 525      .. NOTE:: Retention period starts when the calendar event
 526         triggers.
 527
 528    Additionally, the following events may allocate a new media set:
 529
 530    - Required tape is offline (and you use a tape library).
 531
 532    - Current set contains damaged or retired tapes.
 533
 534    - Media pool encryption has changed
 535
 536    - Database consistency errors, for example, if the inventory does not
 537      contain the required media information, or it contains conflicting
 538      information (outdated data).
 539
 540 .. topic:: Retention Policy
 541
 542    Defines how long we want to keep the data.
 543
 544    - Always overwrite media.
 545
 546    - Protect data for the duration specified.
 547
 548      We use systemd like time spans to specify durations, e.g. ``2
 549      weeks`` (see `systemd.time manpage`_).
 550
 551    - Never overwrite data.
 552
 553 .. topic:: Hardware Encryption
 554
 555    LTO-4 (or later) tape drives support hardware encryption. If you
 556    configure the media pool to use encryption, all data written to the
 557    tapes is encrypted using the configured key.
 558
 559    This way, unauthorized users cannot read data from the media,
 560    for example, if you loose a tape while shipping to an offsite location.
 561
 562    .. Note:: If the backup client also encrypts data, data on the tape
 563       will be double encrypted.
 564
 565    The password protected key is stored on each medium, so that it is
 566    possbible to `restore the key <tape_restore_encryption_key_>`_ using
 567    the password. Please make sure to remember the password, in case
 568    you need to restore the key.
 569
 570
 571 .. NOTE:: We use global content namespace, meaning we do not store the
 572    source datastore name. Because of this, it is impossible to distinguish
 573    store1:/vm/100 from store2:/vm/100. Please use different media pools
 574    if the sources are from different namespaces with conflicting names
 575    (for example, if the sources are from different Proxmox VE clusters).
 576
 577 .. image:: images/screenshots/pbs-gui-tape-pools-add.png
 578   :align: right
 579   :alt: Tape Backup: Add a media pool
 580
 581 To create a new media pool, add one from **Tape Backup -> Media Pools** in the
 582 GUI, or enter the following command:
 583
 584 .. code-block:: console
 585
 586  // proxmox-tape pool create <name> --drive <string> [OPTIONS]
 587
 588  # proxmox-tape pool create daily --drive mydrive
 589
 590
 591 Additional options can be set later, using the update command:
 592
 593 .. code-block:: console
 594
 595  # proxmox-tape pool update daily --allocation daily --retention 7days
 596
 597
 598 To list all configured pools use:
 599
 600 .. code-block:: console
 601
 602  # proxmox-tape pool list
 603  ┌───────┬──────────┬────────────┬───────────┬──────────┐
 604  │ name  │ drive    │ allocation │ retention │ template │
 605  ╞═══════╪══════════╪════════════╪═══════════╪══════════╡
 606  │ daily │ mydrive  │ daily      │ 7days     │          │
 607  └───────┴──────────┴────────────┴───────────┴──────────┘
 608
 609 .. _tape_backup_job_config:
 610
 611 Tape Backup Jobs
 612 ~~~~~~~~~~~~~~~~
 613
 614 .. image:: images/screenshots/pbs-gui-tape-backup-jobs.png
 615   :align: right
 616   :alt: Tape Backup: Tape Backup Jobs
 617
 618 To automate tape backup, you can configure tape backup jobs which
 619 write datastore content to a media pool, based on a specific time schedule.
 620 The required settings are:
 621
 622 - ``store``: The datastore you want to backup
 623
 624 - ``pool``: The media pool - only tape cartridges from that pool are
 625   used.
 626
 627 - ``drive``: The tape drive.
 628
 629 - ``schedule``: Job schedule (see :ref:`calendar-event-scheduling`)
 630
 631 For example, to configure a tape backup job for datastore ``vmstore1``
 632 use:
 633
 634 .. code-block:: console
 635
 636  # proxmox-tape backup-job create job2 --store vmstore1 \
 637    --pool yourpool --drive yourdrive --schedule daily
 638
 639 The backup includes all snapshots from a backup group by default. You can
 640 set the ``latest-only`` flag to include only the latest snapshots:
 641
 642 .. code-block:: console
 643
 644  # proxmox-tape backup-job update job2 --latest-only
 645
 646 Backup jobs can use email to send tape request notifications or
 647 report errors. You can set the notification user with:
 648
 649 .. code-block:: console
 650
 651  # proxmox-tape backup-job update job2 --notify-user root@pam
 652
 653 .. Note:: The email address is a property of the user (see :ref:`user_mgmt`).
 654
 655 It is sometimes useful to eject the tape from the drive after a
 656 backup. For a standalone drive, the ``eject-media`` option ejects the
 657 tape, making sure that the following backup cannot use the tape
 658 (unless someone manually loads the tape again). For tape libraries,
 659 this option unloads the tape to a free slot, which provides better
 660 dust protection than inside a drive:
 661
 662 .. code-block:: console
 663
 664  # proxmox-tape backup-job update job2 --eject-media
 665
 666 .. Note:: For failed jobs, the tape remains in the drive.
 667
 668 For tape libraries, the ``export-media`` option moves all tapes from
 669 the media set to an export slot, making sure that the following backup
 670 cannot use the tapes. An operator can pick up those tapes and move them
 671 to a vault.
 672
 673 .. code-block:: console
 674
 675  # proxmox-tape backup-job update job2 --export-media
 676
 677 .. Note:: The ``export-media`` option can be used to force the start
 678    of a new media set, because tapes from the current set are no
 679    longer online.
 680
 681 It is also possible to run backup jobs manually:
 682
 683 .. code-block:: console
 684
 685  # proxmox-tape backup-job run job2
 686
 687 To remove a job, please use:
 688
 689 .. code-block:: console
 690
 691  # proxmox-tape backup-job remove job2
 692
 693 .. image:: images/screenshots/pbs-gui-tape-backup-jobs-add.png
 694   :align: right
 695   :alt: Tape Backup: Add a backup job
 696
 697 This same functionality also exists in the GUI, under the **Backup Jobs** tab of
 698 **Tape Backup**, where *Local Datastore* relates to the datastore you want to
 699 backup and *Media Pool* is the pool to back up to.
 700
 701
 702 Administration
 703 --------------
 704
 705 Many sub-commands of the ``proxmox-tape`` command line tools take a
 706 parameter called ``--drive``, which specifies the tape drive you want
 707 to work on. For convenience, you can set this in an environment
 708 variable:
 709
 710 .. code-block:: console
 711
 712  # export PROXMOX_TAPE_DRIVE=mydrive
 713
 714 You can then omit the ``--drive`` parameter from the command. If the
 715 drive has an associated changer device, you may also omit the changer
 716 parameter from commands that need a changer device, for example:
 717
 718 .. code-block:: console
 719
 720  # proxmox-tape changer status
 721
 722 should display the changer status of the changer device associated with
 723 drive ``mydrive``.
 724
 725
 726 Label Tapes
 727 ~~~~~~~~~~~
 728
 729 By default, tape cartridges all look the same, so you need to put a
 730 label on them for unique identification. First, put a sticky paper
 731 label with some human readable text on the cartridge.
 732
 733 If you use a `Tape Library`_, you should use an 8 character string
 734 encoded as `Code 39`_, as defined in the `LTO Ultrium Cartridge Label
 735 Specification`_. You can either buy such barcode labels from your
 736 cartridge vendor, or print them yourself. You can use our `LTO Barcode
 737 Generator`_ app to print them.
 738
 739 Next, you need to write that same label text to the tape, so that the
 740 software can uniquely identify the tape too.
 741
 742 For a standalone drive, manually insert the new tape cartridge into the
 743 drive and run:
 744
 745 .. code-block:: console
 746
 747  # proxmox-tape label --changer-id <label-text> [--pool <pool-name>]
 748
 749 You may omit the ``--pool`` argument to allow the tape to be used by any pool.
 750
 751 .. Note:: For safety reasons, this command fails if the tape contains
 752    any data. If you want to overwrite it anyway, erase the tape first.
 753
 754 You can verify success by reading back the label:
 755
 756 .. code-block:: console
 757
 758  # proxmox-tape read-label
 759  ┌─────────────────┬──────────────────────────────────────┐
 760  │ Name            │ Value                                │
 761  ╞═════════════════╪══════════════════════════════════════╡
 762  │ changer-id      │ vtape1                               │
 763  ├─────────────────┼──────────────────────────────────────┤
 764  │ uuid            │ 7f42c4dd-9626-4d89-9f2b-c7bc6da7d533 │
 765  ├─────────────────┼──────────────────────────────────────┤
 766  │ ctime           │ Wed Jan  6 09:07:51 2021             │
 767  ├─────────────────┼──────────────────────────────────────┤
 768  │ pool            │ daily                                │
 769  ├─────────────────┼──────────────────────────────────────┤
 770  │ media-set-uuid  │ 00000000-0000-0000-0000-000000000000 │
 771  ├─────────────────┼──────────────────────────────────────┤
 772  │ media-set-ctime │ Wed Jan  6 09:07:51 2021             │
 773  └─────────────────┴──────────────────────────────────────┘
 774
 775 .. NOTE:: The ``media-set-uuid`` using all zeros indicates an empty
 776    tape (not used by any media set).
 777
 778 If you have a tape library, apply the sticky barcode label to the tape
 779 cartridges first. Then load those empty tapes into the library. You
 780 can then label all unlabeled tapes with a single command:
 781
 782 .. code-block:: console
 783
 784  # proxmox-tape barcode-label [--pool <pool-name>]
 785
 786
 787 Run Tape Backups
 788 ~~~~~~~~~~~~~~~~
 789
 790 To manually run a backup job click *Run Now* in the GUI or use the command:
 791
 792 .. code-block:: console
 793
 794  # proxmox-tape backup <store> <pool> [OPTIONS]
 795
 796 The following options are available:
 797
 798 --eject-media  Eject media upon job completion.
 799
 800   It is normally good practice to eject the tape after use. This unmounts the
 801   tape from the drive and prevents the tape from getting dusty.
 802
 803 --export-media-set  Export media set upon job completion.
 804
 805   After a successful backup job, this moves all tapes from the used
 806   media set into import-export slots. The operator can then pick up
 807   those tapes and move them to a media vault.
 808
 809
 810 Restore from Tape
 811 ~~~~~~~~~~~~~~~~~
 812
 813 Restore is done at media-set granularity, so you first need to find
 814 out which media set contains the data you want to restore. This
 815 information is stored in the media catalog. If you do not have media
 816 catalogs, you need to restore them first. Please note that you need
 817 the catalog to find your data, but restoring a complete media-set does
 818 not need media catalogs.
 819
 820 The following command lists the media content (from catalog):
 821
 822 .. code-block:: console
 823
 824  # proxmox-tape media content
 825  ┌────────────┬──────┬──────────────────────────┬────────┬────────────────────────────────┬──────────────────────────────────────┐
 826  │ label-text │ pool │ media-set-name           │ seq-nr │ snapshot                       │ media-set-uuid                       │
 827  ╞════════════╪══════╪══════════════════════════╪════════╪════════════════════════════════╪══════════════════════════════════════╡
 828  │ TEST01L8   │ p2   │ Wed Jan 13 13:55:55 2021 │      0 │ vm/201/2021-01-11T10:43:48Z    │ 9da37a55-aac7-4deb-91c6-482b3b675f30 │
 829  ├────────────┼──────┼──────────────────────────┼────────┼────────────────────────────────┼──────────────────────────────────────┤
 830  │        ... │ ...  │                      ... │    ... │ ...                            │                                  ... │
 831  └────────────┴──────┴──────────────────────────┴────────┴────────────────────────────────┴──────────────────────────────────────┘
 832
 833
 834 A restore job reads the data from the media set and moves it back to
 835 data disk (datastore):
 836
 837 .. code-block:: console
 838
 839  // proxmox-tape restore <media-set-uuid> <datastore>
 840
 841  # proxmox-tape restore 9da37a55-aac7-4deb-91c6-482b3b675f30 mystore
 842
 843
 844 Update Inventory
 845 ~~~~~~~~~~~~~~~~
 846
 847
 848 Restore Catalog
 849 ~~~~~~~~~~~~~~~
 850
 851
 852 Encryption Key Management
 853 ~~~~~~~~~~~~~~~~~~~~~~~~~
 854
 855 .. image:: images/screenshots/pbs-gui-tape-crypt-keys.png
 856   :align: right
 857   :alt: Tape Backup: Encryption Keys
 858
 859 Proxmox Backup Server also provides an interface for handling encryption keys on
 860 the backup server. Encryption keys can be managed from the **Tape Backup ->
 861 Encryption Keys** section of the GUI or through the ``proxmox-tape key`` command
 862 line tool. To create a new encryption key from the command line:
 863
 864 .. code-block:: console
 865
 866  # proxmox-tape key create --hint "tape pw 2020"
 867  Tape Encryption Key Password: **********
 868  Verify Password: **********
 869  "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"
 870
 871 List existing encryption keys:
 872
 873 .. code-block:: console
 874
 875  # proxmox-tape key list
 876  ┌───────────────────────────────────────────────────┬───────────────┐
 877  │ fingerprint                                       │ hint          │
 878  ╞═══════════════════════════════════════════════════╪═══════════════╡
 879  │ 14:f8:79:b9:f5:13:e5:dc: ...   :b6:20:e1:7f:f5:0f │ tape pw 2020  │
 880  └───────────────────────────────────────────────────┴───────────────┘
 881
 882 To show encryption key details:
 883
 884 .. code-block:: console
 885
 886  # proxmox-tape key show 14:f8:79:b9:f5:13:e5:dc:...:b6:20:e1:7f:f5:0f
 887  ┌─────────────┬───────────────────────────────────────────────┐
 888  │ Name        │ Value                                         │
 889  ╞═════════════╪═══════════════════════════════════════════════╡
 890  │ kdf         │ scrypt                                        │
 891  ├─────────────┼───────────────────────────────────────────────┤
 892  │ created     │ Sat Jan 23 14:47:21 2021                      │
 893  ├─────────────┼───────────────────────────────────────────────┤
 894  │ modified    │ Sat Jan 23 14:47:21 2021                      │
 895  ├─────────────┼───────────────────────────────────────────────┤
 896  │ fingerprint │ 14:f8:79:b9:f5:13:e5:dc:...:b6:20:e1:7f:f5:0f │
 897  ├─────────────┼───────────────────────────────────────────────┤
 898  │ hint        │ tape pw 2020                                  │
 899  └─────────────┴───────────────────────────────────────────────┘
 900
 901 The ``paperkey`` subcommand can be used to create a QR encoded
 902 version of a tape encryption key. The following command sends the output of the
 903 ``paperkey`` command to a text file, for easy printing:
 904
 905 .. code-block:: console
 906
 907  proxmox-tape key paperkey <fingerprint> --output-format text > qrkey.txt
 908
 909
 910 .. _tape_restore_encryption_key:
 911
 912 Restoring Encryption Keys
 913 ^^^^^^^^^^^^^^^^^^^^^^^^^
 914
 915 You can restore the encryption key from the tape, using the password
 916 used to generate the key. First, load the tape you want to restore
 917 into the drive. Then run:
 918
 919 .. code-block:: console
 920
 921  # proxmox-tape key restore
 922  Tepe Encryption Key Password: ***********
 923
 924 If the password is correct, the key will get imported to the
 925 database. Further restore jobs automatically use any available key.
 926
 927
 928 Tape Cleaning
 929 ~~~~~~~~~~~~~
 930
 931 LTO tape drives require regular cleaning. This is done by loading a
 932 cleaning cartridge into the drive, which is a manual task for
 933 standalone drives.
 934
 935 For tape libraries, cleaning cartridges are identified using special
 936 labels starting with letters "CLN". For example, our tape library has a
 937 cleaning cartridge inside slot 3:
 938
 939 .. code-block:: console
 940
 941  # proxmox-tape changer status sl3
 942  ┌───────────────┬──────────┬────────────┬─────────────┐
 943  │ entry-kind    │ entry-id │ changer-id │ loaded-slot │
 944  ╞═══════════════╪══════════╪════════════╪═════════════╡
 945  │ drive         │        0 │ vtape1     │           1 │
 946  ├───────────────┼──────────┼────────────┼─────────────┤
 947  │ slot          │        1 │            │             │
 948  ├───────────────┼──────────┼────────────┼─────────────┤
 949  │ slot          │        2 │ vtape2     │             │
 950  ├───────────────┼──────────┼────────────┼─────────────┤
 951  │ slot          │        3 │ CLN001CU   │             │
 952  ├───────────────┼──────────┼────────────┼─────────────┤
 953  │ ...           │      ... │            │             │
 954  └───────────────┴──────────┴────────────┴─────────────┘
 955
 956 To initiate a cleaning operation simply run:
 957
 958 .. code-block:: console
 959
 960  # proxmox-tape clean
 961
 962 This command does the following:
 963
 964 - find the cleaning tape (in slot 3)
 965
 966 - unload the current media from the drive (back to slot 1)
 967
 968 - load the cleaning tape into the drive
 969
 970 - run drive cleaning operation
 971
 972 - unload the cleaning tape (to slot 3)