From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id 428551FF0DA for ; Thu, 19 Nov 2026 20:25:26 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 114BC21BEE; Thu, 19 Nov 2026 20:20:25 +0100 (CET) From: Thomas Lamprecht 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 Message-ID: <20261119191914.2336934-37-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261119191914.2336934-1-t.lamprecht@proxmox.com> References: <20261119191914.2336934-1-t.lamprecht@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1795115961374 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.156 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: 6ZTJALCSZK7R3UZK4T7HWGMEO6BVT6HN X-Message-ID-Hash: 6ZTJALCSZK7R3UZK4T7HWGMEO6BVT6HN X-MailFrom: t.lamprecht@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: 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 --- 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 ` or `pct unlock `. +. Remove a placeholder, for example with `qm destroy ` or + `pct destroy `. 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 --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