[pve-devel] [PATCH docs 1/2] vzdump: add section about live-restore

[pve-devel] [PATCH docs 1/2] vzdump: add section about live-restore

[Stefan Reiter]

Signed-off-by: Stefan Reiter <s.reiter@proxmox.com>
---

As discussed off-list, the vzdump section in general seems a bit misorganized,
and is certainly missing some references to PBS. Dylan agreed to take a look at
it, thanks again for that!

 vzdump.adoc | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/vzdump.adoc b/vzdump.adoc
index 9453684..0577a97 100644
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -337,6 +337,34 @@ per configured storage, this can be done with:
 # pvesm set STORAGEID --bwlimit restore=KIBs
 ----
 
+Live-Restore
+~~~~~~~~~~~~
+
+Restoring a large backup can take a long time, in which a guest is still
+unavailable. For VM backups stored on a Proxmox Backup Server, this wait
+time can be mitigated using the live-restore option.
+
+Enabling live-restore via either the checkbox in the GUI or the `--live-restore`
+property for `qmrestore` causes the VM to start immediately as the restore
+begins. Data is copied in the background, chunks that the VM is actively
+accessing are prioritized.
+
+Note that this comes with two caveats:
+
+* During live-restore, the VM will operate with limited disk read speeds, as
+  data has to be loaded from the backup server (once loaded it is immediately
+  available on the destination storage however, so accessing data twice only
+  incurs the penalty the first time). Write speeds are largely unaffected.
+* If the live-restore fails for any reason, the VM will be left in an
+  unspecified state - that is, not all data might have been copied from the
+  backup, and it is _most likely_ not possible to keep any data that was written
+  during the failed restore operation.
+
+This mode of operation is especially useful for large VMs, where only a small
+amount of data is required for initial operation, e.g. web servers - once the OS
+and necessary services are started, the VM is already operational, while the
+background task keeps copying seldomly used data.
+
 [[vzdump_configuration]]
 Configuration
 -------------
-- 
2.20.1

[pve-devel] [PATCH docs 2/2] vzdump: add section about single file restore

[Stefan Reiter]

Signed-off-by: Stefan Reiter <s.reiter@proxmox.com>
---
 vzdump.adoc | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/vzdump.adoc b/vzdump.adoc
index 0577a97..c6063ad 100644
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -365,6 +365,30 @@ amount of data is required for initial operation, e.g. web servers - once the OS
 and necessary services are started, the VM is already operational, while the
 background task keeps copying seldomly used data.
 
+Single File Restore
+~~~~~~~~~~~~~~~~~~~
+
+The 'File Restore' button in the 'Backups' tab of the storage GUI can be used to
+open a file browser directly on the data contained in a backup. This feature
+is only available for backups on a Proxmox Backup Server.
+
+For containers, the first layer of the file tree shows all included 'pxar'
+archives, which can be opened and browsed freely. For VMs, the first layer shows
+contained drive images, which can be opened to reveal a list of supported
+storage technologies found on the drive. In the most basic case, this will be an
+entry called 'part', representing a partition table, containing entries for each
+partition found on the drive. Note that for VMs, not all data might be
+accessible (unsupported guest file systems, storage technologies, etc...).
+
+Files and directories can be downloaded using the 'Download' button, the latter
+being compressed into a zip archive on the fly.
+
+To enable secure access to VM images, which might contain untrusted data, a
+temporary VM (not visible as a guest) is started. This does not mean that data
+downloaded from such an archive is inherently safe, but avoids exposing the
+hypervisor system to danger. The VM will stop itself after a timeout, the entire
+process happens transparently from a users point of view.
+
 [[vzdump_configuration]]
 Configuration
 -------------
-- 
2.20.1

Re: [pve-devel] [PATCH docs 1/2] vzdump: add section about live-restore

[Dylan Whyte]

Hi,

I just made some very minor suggestions inline, but overall it's good (i 
had to search extra-hard for issues) :)

Reviewed-by: Dylan Whyte <d.whyte@proxmox.com>

On 4/22/21 10:25 AM, Stefan Reiter wrote:
> Signed-off-by: Stefan Reiter <s.reiter@proxmox.com>
> ---
>
> As discussed off-list, the vzdump section in general seems a bit misorganized,
> and is certainly missing some references to PBS. Dylan agreed to take a look at
> it, thanks again for that!
>
>   vzdump.adoc | 28 ++++++++++++++++++++++++++++
>   1 file changed, 28 insertions(+)
>
> diff --git a/vzdump.adoc b/vzdump.adoc
> index 9453684..0577a97 100644
> --- a/vzdump.adoc
> +++ b/vzdump.adoc
> @@ -337,6 +337,34 @@ per configured storage, this can be done with:
>   # pvesm set STORAGEID --bwlimit restore=KIBs
>   ----
>   
> +Live-Restore
> +~~~~~~~~~~~~
> +
> +Restoring a large backup can take a long time, in which a guest is still
> +unavailable. For VM backups stored on a Proxmox Backup Server, this wait
> +time can be mitigated using the live-restore option.
> +
> +Enabling live-restore via either the checkbox in the GUI or the `--live-restore`
> +property for `qmrestore` causes the VM to start immediately as the restore

s/property for/argument of/

s/immediately/as soon/

> +begins. Data is copied in the background, chunks that the VM is actively

s/, chunks/, and chunks/

or to reformulate: "Data is copied in the background, prioritizing 
chunks that the VM is actively accessing."

> +accessing are prioritized.
> +
> +Note that this comes with two caveats:
> +
> +* During live-restore, the VM will operate with limited disk read speeds, as
> +  data has to be loaded from the backup server (once loaded it is immediately
s/once loaded/once loaded,/
> +  available on the destination storage however, so accessing data twice only
> +  incurs the penalty the first time). Write speeds are largely unaffected.
> +* If the live-restore fails for any reason, the VM will be left in an
> +  unspecified state - that is, not all data might have been copied from the
s/unspecified/undefined/
> +  backup, and it is _most likely_ not possible to keep any data that was written
> +  during the failed restore operation.
> +
> +This mode of operation is especially useful for large VMs, where only a small
> +amount of data is required for initial operation, e.g. web servers - once the OS
> +and necessary services are started, the VM is already operational, while the

s/are started/have been started/

s/already operational/operational/

> +background task keeps copying seldomly used data.

s/keeps/continues/

> +
>   [[vzdump_configuration]]
>   Configuration
>   -------------

Re: [pve-devel] [PATCH docs 2/2] vzdump: add section about single file restore

[Dylan Whyte]

Hi,

Have even less notes for this one. Just some little things sounded off 
to me.

Reviewed-by: Dylan Whyte <d.whyte@proxmox.com>

On 4/22/21 10:25 AM, Stefan Reiter wrote:
> Signed-off-by: Stefan Reiter <s.reiter@proxmox.com>
> ---
>   vzdump.adoc | 24 ++++++++++++++++++++++++
>   1 file changed, 24 insertions(+)
>
> diff --git a/vzdump.adoc b/vzdump.adoc
> index 0577a97..c6063ad 100644
> --- a/vzdump.adoc
> +++ b/vzdump.adoc
> @@ -365,6 +365,30 @@ amount of data is required for initial operation, e.g. web servers - once the OS
>   and necessary services are started, the VM is already operational, while the
>   background task keeps copying seldomly used data.
>   
> +Single File Restore
> +~~~~~~~~~~~~~~~~~~~
> +
> +The 'File Restore' button in the 'Backups' tab of the storage GUI can be used to
> +open a file browser directly on the data contained in a backup. This feature
> +is only available for backups on a Proxmox Backup Server.
> +
> +For containers, the first layer of the file tree shows all included 'pxar'
> +archives, which can be opened and browsed freely. For VMs, the first layer shows
> +contained drive images, which can be opened to reveal a list of supported
> +storage technologies found on the drive. In the most basic case, this will be an
> +entry called 'part', representing a partition table, containing entries for each
s/containing/which contains/
> +partition found on the drive. Note that for VMs, not all data might be
> +accessible (unsupported guest file systems, storage technologies, etc...).
> +
> +Files and directories can be downloaded using the 'Download' button, the latter
> +being compressed into a zip archive on the fly.
> +
> +To enable secure access to VM images, which might contain untrusted data, a
> +temporary VM (not visible as a guest) is started. This does not mean that data
> +downloaded from such an archive is inherently safe, but avoids exposing the
s/avoids/it avoids/
> +hypervisor system to danger. The VM will stop itself after a timeout, the entire
s/, the entire/. This entire/
> +process happens transparently from a users point of view.
s/users/user's/
> +
>   [[vzdump_configuration]]
>   Configuration
>   -------------