Re: [pbs-devel] [PATCH proxmox-backup] Fix #4408: add 'disaster recovery' section for tapes

["Laurențiu Leahu-Vlăducu" <l.leahu-vladucu@proxmox.com>]

Thanks for the great suggestions, Shannon! I sent a second revision of 
my patch on Friday that contains your suggestions, and I also made sure 
that the words are wrapped to maximum 80 characters.


Laurențiu


On 20.12.24 13:50, Shannon Sterz wrote:
> On Fri Dec 13, 2024 at 2:24 PM CET, Laurențiu Leahu-Vlăducu wrote:
>> Signed-off-by: Laurențiu Leahu-Vlăducu <l.leahu-vladucu@proxmox.com>
>> ---
>>   docs/backup-client.rst |   2 +
>>   docs/tape-backup.rst   | 147 +++++++++++++++++++++++++++++++++++++++++
>>   www/OnlineHelpInfo.js  |  74 +++++++++++++++------
>>   3 files changed, 204 insertions(+), 19 deletions(-)
>>
>> diff --git a/docs/backup-client.rst b/docs/backup-client.rst
>> index 71f1ea92..1c2a98ed 100644
>> --- a/docs/backup-client.rst
>> +++ b/docs/backup-client.rst
>> @@ -470,6 +470,8 @@ version of your master key. The following command sends the output of the
>>     proxmox-backup-client key paperkey --output-format text > qrkey.txt
>>
>>
>> +.. _client_restoring_data:
>> +
>>   Restoring Data
>>   --------------
>>
>> diff --git a/docs/tape-backup.rst b/docs/tape-backup.rst
>> index 1fc89b67..06eec3e9 100644
>> --- a/docs/tape-backup.rst
>> +++ b/docs/tape-backup.rst
>> @@ -61,6 +61,7 @@ In general, LTO tapes offer the following advantages:
>>   Note that `Proxmox Backup Server` already stores compressed data, so using the
>>   tape compression feature has no advantage.
>>
>> +.. _tape-supported-hardware:
>>
>>   Supported Hardware
>>   ------------------
>> @@ -969,6 +970,8 @@ You can restore from a tape even without an existing catalog, but only the
>>   whole media set. If you do this, the catalog will be automatically created.
>>
>>
>> +.. _tape_key_management:
>> +
>>   Encryption Key Management
>>   ~~~~~~~~~~~~~~~~~~~~~~~~~
>>
>> @@ -1180,3 +1183,147 @@ In combination with fitting prune settings and tape backup schedules, this
>>   achieves long-term storage of some backups, while keeping the recent
>>   backups on smaller media sets that expire roughly every 4 weeks (that is, three
>>   plus the current week).
>> +
>> +
>> +Disaster recovery
>> +-----------------
>> +
>> +.. _Command-line Tools: command-line-tools.html
>> +
>> +In case of major disasters, important data, or even whole servers might be destroyed
>> +or at least damaged up to the point where everything - sometimes including the backup
>> +server - has to be restored from a backup. For such cases, the following step-by-step
>> +guide will help you to setup the Proxmox Backup Server and restore everything from
> 
> help you to set up -> here you are setting up something not talking abou
> a "setup".
> 
>> +tape backups.
>> +
>> +The following guide will explain the necessary steps using both the web GUI and the
>> +command line tools. For an overview of the command line tools,
>> +see `Command-line Tools`_.
>> +
>> +Restoring hardware
>> +~~~~~~~~~~~~~~~~~~
>> +
>> +.. _System Requirements: system-requirements.html
>> +
>> +.. _Installation Medium: installation-media.html
>> +
>> +.. _Server Installation: installation.html
>> +
>> +#. In case you need to buy new a new server, please consult the `System Requirements`_
>> +   for the Proxmox Backup Server.
>> +
>> +#. Make sure that the new server has power and starts without issues.
>> +
>> +#. Download the Proxmox Backup Server and create an `Installation Medium`_.
>> +
>> +#. Follow the :ref:`install_pbs` steps and install the Proxmox Backup
>> +   Server on the new hardware.
> 
> i wonder if this section is really necessary, maybe just start the next
> one with "after you set up a new pbs, as outlined in the Installation
> chapter" with a reference to the corresponding manual section.
> 
>> +
>> +
>> +Setting up a datastore
>> +~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +.. _proxmox-backup-manager: proxmox-backup-manager/man1.html
>> +
>> +A datastore on the Proxmox Backup Server is necessary in order to perform a restore
>> +from a tape to the local datastore. You will need to do the following:
> 
> this could be more concise:
> 
>      A datastore is necessary in order to restore a tape to it.
> 
> this is however kind of... obvious? so maybe:
> 
>      First set up a datastore so a tape can be restored to it:
> 
> should do the trick imo
> 
>> +
>> +#. Go to **Administration -> Storage / Disks** and make sure that the disk that will be used
>> +   as a datastore shows up.
>> +
>> +#. Under the **Directory** or **ZFS** tabs, you can either choose to create a directory
>> +   or create a ZFS ``zpool``, respectively. Here you can also directly add the newly created
>> +   directory or ZFS ``zpool`` as a datastore.
>> +
>> +Alternatively, the `proxmox-backup-manager`_ can be used to perform the same tasks.
>> +For more information, check the :ref:`datastore_intro` documentation.
>> +
>> +
>> +Setting up the tape drive
>> +~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +#. Make sure that you have a tape drive that is able to read the tape that
>> +   you want to restore from. Keep in mind that the Proxmox Backup Server supports LTO-5 or
>> +   later, although some LTO-4 might also work (see :ref:`tape-supported-hardware`).
>> +
>> +   As a short overview, in order to get everything working, you will need to set up the following:
>> +     * a tape drive
>> +     * optionally, a tape changer
>> +     * a cable to connect the tape drive(s) to the backup server
>> +     * physical storage on your backup server to restore data from the tape
>> +
>> +#. Connect the tape changer(s) and the tape drive(s) to the backup server. These should be
>> +   detected automatically by Linux. For more advanced information, please read the chapters
>> +   on :ref:`tape_changer_config` and :ref:`tape_drive_config`.
>> +
>> +#. If you have a tape changer, go to the web interface of the Proxmox Backup Server,
>> +   go to **Tape Backup -> Changers** and add it. For examples using the command line, read
>> +   the chapter on :ref:`tape_changer_config`. If the changer has been detected correctly by Linux,
>> +   the changer should show up in the list.
>> +
>> +#. In the web interface, go to **Tape Backup -> Drives** and add the tape drive that will be
>> +   used to read the tapes. For examples using the command line, read
>> +   the chapter on :ref:`tape_drive_config`. If the tape drive has been detected correctly by Linux,
>> +   the drive should show up in the list. If the drive also has a tape changer, make sure to
>> +   select the changer as well and assign it the correct drive number.
>> +
>> +
>> +Restoring data from the tape
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +.. _proxmox-tape: proxmox-tape/man1.html
>> +
>> +.. _proxmox-backup-client: proxmox-backup-client/man1.html
>> +
>> +.. _Restore: https://pve.proxmox.com/pve-docs/chapter-vzdump.html#vzdump_restore
>> +
>> +The following guide will explain the steps necessary to restore data from a tape, which can be
>> +done over either the web GUI or the command line. For details on the command line, read the
>> +documentation on the `proxmox-tape`_ tool.
>> +
>> +To restore data from tapes, do the following:
>> +
>> +#. Insert the first tape (as displayed on the label) into the tape drive or, if a tape changer
>> +   is available, use the tape changer to insert the tape into the right drive.
>> +   The web GUI can also be used to load or transfer tapes between tape drives
>> +   by selecting the changer.
>> +
>> +#. If the backup has been encrypted, the encryption keys need to be restored as well. In the
>> +   **Encryption Keys** tab, press **Restore Key**. For more details or examples that use the command line,
>> +   read the :ref:`tape_key_management` chapter.
>> +
>> +#. In order to restore data, you need to find out which media set contains the data that
>> +   should be restored. A media catalog stores this information, so if specific files need to be
>> +   restored, the media catalog needs to be restored first in order to find which files exist
>> +   on the tape. While it is possible to restore data from a tape that does not contain a catalog,
>> +   it is only possible to restore the whole media set. To restore a catalog, do the following:
>> +
>> +     * If a tape changer is used, click on the **Tape Changer**, go to **Inventory** and make sure
> 
> click on the **Tape Changer** _tab_ -> it seems a word is missing.
> alternatively get rid of the "the" in front of **Tape Changer**
> 
>> +       **Restore Catalog** is selected. This will restore the catalogs of all tapes in the changer.
>> +       Alternatively, tapes can also be loaded into drives, where pressing **Catalog** will restore
>> +       the catalog only for the currently loaded tape.
>> +
>> +     * If a standalone tape drive is used, click on the drive and click on **Catalog**.
>> +
>> +#. Go back to **Tape Backup**. In the **Content** tab, press **Restore** and select the desired media set.
>> +   Choose the snapshot you want to restore, press **Next**, select the drive and target datastore
>> +   and press **Restore**.
>> +
>> +#. By going to the datastore where the data has been restored, under the **Content** tab you should
>> +   be able to see the restored snapshots. In order to access the backups from another machine,
>> +   you will need to configure the access to the backup server. Go to **Configuration -> Access Control**
>> +   and either create a new user, or a new API token (API tokens allow easy revocation if the token
>> +   is compromised). Under **Permissions**, add the desired permissions, e.g. **DatastoreBackup**.
>> +
>> +#. You can now perform virtual machine, container or file restores. You now have
>> +   the following options:
>> +
>> +     * If you want to restore files on Linux distributions that are not based on Proxmox products
>> +       or you prefer using a command line tool, you can use the `proxmox-backup-client`_,
>> +       as explained in the :ref:`client_restoring_data` chapter. Use the newly created API token to be
>> +       able to access the data. You can then restore individual files or mount an archive to your system.
>> +
>> +     * If you want to restore virual machines or containers on a Proxmox VE server, add the datastore
> 
> virtual not virual
> 
>> +       of the backup server as storage and go to **Backups**. Here you can restore VMs and containers,
>> +       including their configuration. For more information on restoring backups in the Proxmox VE, visit
> 
> you can leave out the "the" before Proxmox VE here
> 
>> +       the `Restore`_ chapter of the Proxmox VE documentation.
>> diff --git a/www/OnlineHelpInfo.js b/www/OnlineHelpInfo.js
>> index ebb524e4..603761da 100644
>> --- a/www/OnlineHelpInfo.js
>> +++ b/www/OnlineHelpInfo.js
>> @@ -19,6 +19,10 @@ const proxmoxOnlineHelpInfo = {
>>       "link": "/docs/backup-client.html#client-encryption",
>>       "title": "Encryption"
>>     },
>> +  "client-restoring-data": {
>> +    "link": "/docs/backup-client.html#client-restoring-data",
>> +    "title": "Restoring Data"
>> +  },
>>     "changing-backup-owner": {
>>       "link": "/docs/backup-client.html#changing-backup-owner",
>>       "title": "Changing the Owner of a Backup Group"
>> @@ -87,9 +91,45 @@ const proxmoxOnlineHelpInfo = {
>>       "link": "/docs/system-requirements.html#minimum-system-requirements",
>>       "title": "Minimum Server Requirements, for Evaluation"
>>     },
>> -  "installation-media": {
>> -    "link": "/docs/installation-media.html#installation-media",
>> -    "title": "Installation Media"
>> +  "installation-medium": {
>> +    "link": "/docs/installation-media.html#installation-medium",
>> +    "title": "Installation Medium"
>> +  },
>> +  "install-pbs": {
>> +    "link": "/docs/installation.html#install-pbs",
>> +    "title": "Server Installation"
>> +  },
>> +  "using-the-installer": {
>> +    "link": "/docs/using-the-installer.html#using-the-installer",
>> +    "title": "Install `Proxmox Backup`_ Server using the Installer"
>> +  },
>> +  "advanced-lvm-options": {
>> +    "link": "/docs/using-the-installer.html#advanced-lvm-options",
>> +    "title": "Advanced LVM Configuration Options"
>> +  },
>> +  "advanced-zfs-options": {
>> +    "link": "/docs/using-the-installer.html#advanced-zfs-options",
>> +    "title": "Advanced ZFS Configuration Options"
>> +  },
>> +  "nomodeset-kernel-param": {
>> +    "link": "/docs/using-the-installer.html#nomodeset-kernel-param",
>> +    "title": "Adding the ``nomodeset`` Kernel Parameter"
>> +  },
>> +  "install-pbs-unattended": {
>> +    "link": "/docs/installation.html#install-pbs-unattended",
>> +    "title": "Install `Proxmox Backup`_ Server Unattended"
>> +  },
>> +  "install-pbs-on-debian": {
>> +    "link": "/docs/installation.html#install-pbs-on-debian",
>> +    "title": "Install `Proxmox Backup`_ Server on Debian"
>> +  },
>> +  "install-pbs-on-pve": {
>> +    "link": "/docs/installation.html#install-pbs-on-pve",
>> +    "title": "Install Proxmox Backup Server on `Proxmox VE`_"
>> +  },
>> +  "install-pbc": {
>> +    "link": "/docs/installation.html#install-pbc",
>> +    "title": "Client Installation"
>>     },
>>     "sysadmin-package-repositories": {
>>       "link": "/docs/installation.html#sysadmin-package-repositories",
>> @@ -107,26 +147,14 @@ const proxmoxOnlineHelpInfo = {
>>       "link": "/docs/installation.html#package-repositories-client-only",
>>       "title": "Proxmox Backup Client-only Repository"
>>     },
>> +  "package-repositories-client-only-apt": {
>> +    "link": "/docs/installation.html#package-repositories-client-only-apt",
>> +    "title": "APT-based Proxmox Backup Client Repository"
>> +  },
>>     "node-options-http-proxy": {
>>       "link": "/docs/installation.html#node-options-http-proxy",
>>       "title": "Repository Access Behind HTTP Proxy"
>>     },
>> -  "using-the-installer": {
>> -    "link": "/docs/using-the-installer.html#using-the-installer",
>> -    "title": "Install `Proxmox Backup`_ Server using the Installer"
>> -  },
>> -  "advanced-lvm-options": {
>> -    "link": "/docs/using-the-installer.html#advanced-lvm-options",
>> -    "title": "Advanced LVM Configuration Options"
>> -  },
>> -  "advanced-zfs-options": {
>> -    "link": "/docs/using-the-installer.html#advanced-zfs-options",
>> -    "title": "Advanced ZFS Configuration Options"
>> -  },
>> -  "nomodeset-kernel-param": {
>> -    "link": "/docs/using-the-installer.html#nomodeset-kernel-param",
>> -    "title": "Adding the ``nomodeset`` Kernel Parameter"
>> -  },
>>     "get-help": {
>>       "link": "/docs/introduction.html#get-help",
>>       "title": "Getting Help"
>> @@ -403,6 +431,10 @@ const proxmoxOnlineHelpInfo = {
>>       "link": "/docs/tape-backup.html#tape-backup",
>>       "title": "Tape Backup"
>>     },
>> +  "tape-supported-hardware": {
>> +    "link": "/docs/tape-backup.html#tape-supported-hardware",
>> +    "title": "Supported Hardware"
>> +  },
>>     "tape-changer-config": {
>>       "link": "/docs/tape-backup.html#tape-changer-config",
>>       "title": "Tape changers"
>> @@ -419,6 +451,10 @@ const proxmoxOnlineHelpInfo = {
>>       "link": "/docs/tape-backup.html#tape-backup-job-config",
>>       "title": "Tape Backup Jobs"
>>     },
>> +  "tape-key-management": {
>> +    "link": "/docs/tape-backup.html#tape-key-management",
>> +    "title": "Encryption Key Management"
>> +  },
>>     "tape-restore-encryption-key": {
>>       "link": "/docs/tape-backup.html#tape-restore-encryption-key",
>>       "title": "Restoring Encryption Keys"
> 



_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel