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

[Dominik Csapak <d.csapak@proxmox.com>]

hi, some high level comments:

you add new chapter marks here, but it's not immediatly obvious why,
a short sentence in the commit message like: 'add new markers so we can refer to the chapters'
would be nice.

you also update the OnlineHelpInfo.js file which is not really related to this patch.
If you want to send that, please do so as it's own patch, but previously Thomas
did directly apply the updates for that (i think when bumping, not sure though).

third, i think it would be good to use 'title case' for the sub chapters,
e.g. a tool you could use for that is https://titlecaseconverter.com/
(i think the default settings are ok)

e.g. 'Setting up a datastore' becomes then 'Setting Up a Datastore'
which looks much nicer in a title.

some comments inline

On 12/20/24 15:44, 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   | 145 +++++++++++++++++++++++++++++++++++++++++
>   www/OnlineHelpInfo.js  |  74 +++++++++++++++------
>   3 files changed, 202 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..2c3de060 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,145 @@ 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 set up the Proxmox Backup
> +Server and restore everything from 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`_.
> +
> +
> +Setting up a datastore
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +.. _proxmox-backup-manager: proxmox-backup-manager/man1.html
> +
> +.. _Installation: installation.html
> +
> +After you set up a new Proxmox Backup Server, as outlined in the `Installation`_
> +chapter, first set up a datastore so a tape can be restored to it:
> +
> +#. 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

some LTO-4 *what* ? i guess you mean drive or tape, but i wouldn't include
that at all here, a link to supported hardware should be enough
(the tape medium dictates which drive you must use, so talking about LTO versions
here is IMO not helpful)

> +   :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

not super sure about this paragraph. The user already wants to restore from
tape when reading this, and presumably the user already set one up in the past
already (before backing up to them), so i think we could omit this, or at least
make it shorter like: 'make sure you have a properly working tape drive or changer
matching to the medium you want to restore from'.

> +
> +#. 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`.

a short command to verify the existance would be nice here, e.g.
`proxmox-tape drive scan`
`proxmox-tape changer scan`

> +
> +#. 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 **Tape Changer**, go to **Inventory**
> +       and make sure **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**.
> +

here i would write it a bit differently:
first i would not go into too much detail on catalogs,etc. but simply
describe what has to be done.
Also I'd separate more between changer and drive procedures, because:

for changers it's more easy to do:
* insert all tapes from the media-set you want to restore from
* press 'inventory' on the web gui, which will (AFAIR) restore
the catalogs of the tapes and update the inventory

for drives, the procedure would be:
* insert the first tape of the media-set
* click restore catalog
* repeat for all following tapes

> +#. 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 virtual machines or containers on a Proxmox VE
> +       server, add the datastore 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 Proxmox VE,
> +       visit 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