public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
From: Thomas Lamprecht <t.lamprecht@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH docs v5 36/41] vzdump: restore: describe what a failed restore can leave behind
Date: Thu, 19 Nov 2026 20:19:08 +0100	[thread overview]
Message-ID: <20261119191914.2336934-37-t.lamprecht@proxmox.com> (raw)
In-Reply-To: <20261119191914.2336934-1-t.lamprecht@proxmox.com>

A restore that fails or gets killed can leave a locked guest behind,
or a placeholder and volumes at a VMID that was free before. The backup
and restore chapter did not mention that, nor how to clean up.

Describe when a guest stays and is locked, how to remove a placeholder
and the volumes that no guest config references anymore, and when a
retry needs another VMID.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---

changes v4 -> v5:
* restructured: a list of what a failed restore can leave behind, then
  numbered steps to clean up and retry, with the same content as before;
  the last step says that another VMID is only needed after removing a
  placeholder
* not carrying over the R-b and T-b that Dominik gave for v4, as the
  text got rewritten

changes v3 -> v4:
* new in v4: the part about locks and leftovers from the 'Failed
  Restores' section of the guest identity patch, as a section of the
  restore chapter, since it does not depend on the identity
* added there: a guest stays, locked, if its cleanup cannot remove a
  volume or the firewall config, and '--destroy-unreferenced-disks'
  removes all other volumes of the VMID, also of an earlier guest, with
  how to check first

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

diff --git a/vzdump.adoc b/vzdump.adoc
index 44db027..84b388c 100644
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -563,6 +563,39 @@ file in `/var/log/proxmox-backup/file-restore/`. The log file might contain
 additional information in case an attempt to restore individual files or
 accessing file systems contained in a backup archive fails.
 
+[[vzdump_restore_failed]]
+Failed Restores
+~~~~~~~~~~~~~~~
+
+A restore that fails or is canceled can leave one of the following leftover
+artifacts for its VMID:
+
+* The guest itself, possibly locked. This happens after a restore over an
+  existing guest, after a VM restore that fails once the data is restored or in
+  the live phase of a live restore, and if the restore task was killed.
+* A locked container, after a container restore over an existing container that
+  already destroyed the old container, if the cleanup could not remove the
+  firewall config or a volume. That can be a volume of the restore or of the
+  old container. If the cleanup succeeds, such a restore removes the container.
+* A locked placeholder without data, after a restore to a free VMID, if the
+  restore task was killed or the cleanup could not remove a volume or the
+  firewall config. Normally, a restore to a free VMID that fails before it
+  restored the data removes the guest again.
+
+To clean up and retry:
+
+. Remove the lock with `qm unlock <vmid>` or `pct unlock <vmid>`.
+. Remove a placeholder, for example with `qm destroy <vmid>` or
+  `pct destroy <vmid>`. With `--destroy-unreferenced-disks 1`, the command also
+  removes all other volumes with that VMID on the enabled storages. These
+  include volumes that a killed restore created or that the cleanup could not
+  remove, but can also be volumes of an earlier guest, so check them first with
+  `pvesm list <storage> --vmid <vmid>`.
+. Restore again, over the guest that was left behind or to the VMID of the
+  placeholder that you removed. After removing a placeholder, use another VMID
+  if the xref:pvecm_next_id_range[`next-id`] setting of the datacenter has the
+  `unique` and `enforce` options set, as the first VMID then counts as used.
+
 [[vzdump_configuration]]
 Configuration
 -------------
-- 
2.47.3





  parent reply	other threads:[~2026-11-19 19:25 UTC|newest]

Thread overview: 43+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-19 19:18 [PATCH cluster/guest-common/qemu-server/container/manager/docs v5 00/41] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
2026-11-19 19:18 ` [PATCH cluster v5 01/41] pmxcfs: reject changes to the cluster ID file from user space Thomas Lamprecht
2026-11-19 19:18 ` [PATCH cluster v5 02/41] pmxcfs: generate a cluster ID on standalone nodes Thomas Lamprecht
2026-11-19 19:18 ` [PATCH cluster v5 03/41] pmxcfs: dfsm: add a callback that runs once all members are in sync Thomas Lamprecht
2026-11-19 19:18 ` [PATCH cluster v5 04/41] pmxcfs: quorum: record the corosync membership Thomas Lamprecht
2026-11-19 19:18 ` [PATCH cluster v5 05/41] pmxcfs: dcdb: generate the cluster ID once the cluster is in sync Thomas Lamprecht
2026-11-19 19:18 ` [PATCH cluster v5 06/41] cluster: add helper to read the cluster ID Thomas Lamprecht
2026-11-19 19:18 ` [PATCH cluster v5 07/41] pmxcfs: allow removing the cluster ID file in forced local mode Thomas Lamprecht
2026-11-19 19:18 ` [PATCH guest-common v5 08/41] guest identity: add helpers for the guest uid and registration time Thomas Lamprecht
2026-11-19 19:18 ` [PATCH guest-common v5 09/41] abstract config: assign a guest identity and keep it on config writes Thomas Lamprecht
2026-11-19 19:18 ` [PATCH guest-common v5 10/41] abstract config: let the VMID reservation return the previous state Thomas Lamprecht
2026-11-19 19:18 ` [PATCH guest-common v5 11/41] guest identity: allow adopting a uid that is unused in the cluster Thomas Lamprecht
2026-11-19 19:18 ` [PATCH guest-common v5 12/41] migrate: add shared helpers for the identity command of the migration tunnel Thomas Lamprecht
2026-11-19 19:18 ` [PATCH guest-common v5 13/41] vzdump: notes template: list the uid variable Thomas Lamprecht
2026-11-19 19:18 ` [PATCH qemu-server v5 14/41] api: restore: release the VMID if a restore to an unused VMID fails Thomas Lamprecht
2026-11-19 19:18 ` [PATCH qemu-server v5 15/41] api: migrate, clone: refuse targets that would drop the guest identity Thomas Lamprecht
2026-11-19 19:18 ` [PATCH qemu-server v5 16/41] fix #7846: config: add a guest identity to the 'meta' property Thomas Lamprecht
2026-11-19 19:18 ` [PATCH qemu-server v5 17/41] restore: adopt the guest uid from the backup where possible Thomas Lamprecht
2026-11-19 19:18 ` [PATCH qemu-server v5 18/41] api: remote migration: adopt the guest uid from the source Thomas Lamprecht
2026-11-19 19:18 ` [PATCH qemu-server v5 19/41] api: status: return the guest uid Thomas Lamprecht
2026-11-19 19:18 ` [PATCH container v5 20/41] restore: decide by the reservation whether the container is new Thomas Lamprecht
2026-11-19 19:18 ` [PATCH container v5 21/41] config: add read-only meta property with the creation time Thomas Lamprecht
2026-11-19 19:18 ` [PATCH container v5 22/41] fix #7846: config: add a guest identity to the 'meta' property Thomas Lamprecht
2026-11-19 19:18 ` [PATCH container v5 23/41] api: migrate, clone: refuse targets that would drop the guest identity Thomas Lamprecht
2026-11-19 19:18 ` [PATCH container v5 24/41] restore: adopt the guest uid from the backup where possible Thomas Lamprecht
2026-11-19 19:18 ` [PATCH container v5 25/41] restore: refuse overwriting a container with another guest's backup Thomas Lamprecht
2026-11-19 19:18 ` [PATCH container v5 26/41] api: remote migration: adopt the guest uid from the source Thomas Lamprecht
2026-11-19 19:18 ` [PATCH container v5 27/41] api: status: return the guest uid Thomas Lamprecht
2026-11-19 19:19 ` [PATCH manager v5 28/41] api: cluster resources: add guest uid and registration time Thomas Lamprecht
2026-11-19 19:19 ` [PATCH manager v5 29/41] api: cluster status: add cluster ID Thomas Lamprecht
2026-11-19 19:19 ` [PATCH manager v5 30/41] ui: datacenter summary: show the " Thomas Lamprecht
2026-11-19 19:19 ` [PATCH manager v5 31/41] ui: restore: allow overwriting a guest with a backup of another guest Thomas Lamprecht
2026-11-19 19:19 ` [PATCH manager v5 32/41] ui: migrate: refuse target nodes that would drop the guest identity Thomas Lamprecht
2026-11-19 19:19 ` [PATCH manager v5 33/41] ui: guest summary: show " Thomas Lamprecht
2026-11-19 19:19 ` [PATCH manager v5 34/41] api: bulk migrate: refuse targets that would drop " Thomas Lamprecht
2026-11-19 19:19 ` [PATCH manager v5 35/41] vzdump: notes template: add the guest uid as variable Thomas Lamprecht
2026-11-19 19:19 ` Thomas Lamprecht [this message]
2026-11-19 19:19 ` [PATCH docs v5 37/41] vzdump: describe the guest identity of VMs and containers Thomas Lamprecht
2026-11-19 19:19 ` [PATCH docs v5 38/41] pvecm: document the cluster ID and how to get a new one Thomas Lamprecht
2026-11-19 19:19 ` [PATCH docs v5 39/41] qm: configuration: describe the read-only meta property Thomas Lamprecht
2026-11-19 19:19 ` [PATCH docs v5 40/41] pct: " Thomas Lamprecht
2026-11-19 19:19 ` [PATCH docs v5 41/41] vzdump: notes: document the uid template variable Thomas Lamprecht
2026-11-20  3:07 ` [PATCH cluster/guest-common/qemu-server/container/manager/docs v5 00/41] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261119191914.2336934-37-t.lamprecht@proxmox.com \
    --to=t.lamprecht@proxmox.com \
    --cc=pve-devel@lists.proxmox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal