all lists on lists.proxmox.com
 help / color / mirror / Atom feed
* [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID
@ 2026-11-16  0:46 Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH cluster 01/34] pmxcfs: reject changes to the cluster ID file from user space Thomas Lamprecht
                   ` (35 more replies)
  0 siblings, 36 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

A VMID can be reused for another guest, and a guest can get another
VMID or move to another cluster through a restore or a remote
migration. So backup software and other tools cannot tell whether they
still look at the same guest, see [0].

This series gives every VM and container a guest identity in the
read-only 'meta' property: a random uid (100 bits as 20 base32
characters) and the time the guest was registered in the cluster. Create
and clone get a new uid. Config changes, migration, rollback, backup and
restore keep it, also under another VMID or in another cluster, as long
as no other guest there has it. Each cluster or standalone node also
gets a cluster ID in the same format, generated and protected by pmxcfs.
The docs patches describe the details.

Two behavior changes come with it:

* Restoring over an existing guest whose uid differs from the one of
  the backup is refused unless 'allow-identity-mismatch' is set. 'force'
  alone does not override this.
* Older versions drop the whole 'meta' property of a guest that has an
  identity. So migration and clone to such nodes is refused, and remote
  migration bumps the tunnel version. This also hits moves by the HA
  stack, which stops a container or a relocated VM before the migration
  gets refused. A target check in the LRM that avoids this will follow
  separately.

The patches are in dependency order: guest-common needs a pve-cluster
newer than 9.1.9, qemu-server and container need guest-common, and
manager needs all of them. manager also has to depend on the
qemu-server and container versions with this series, as the migration
guard takes the pve-manager version of a node as proof that the node
keeps the identity. MIN_PVE_MANAGER_VERSION in guest-common is a
stand-in for that pve-manager version.

Tested with the test suites of the repositories and end to end on a
nested three-node cluster that was upgraded node by node.

[0]: https://bugzilla.proxmox.com/show_bug.cgi?id=7846

cluster:

Thomas Lamprecht (7):
  pmxcfs: reject changes to the cluster ID file from user space
  pmxcfs: generate a cluster ID on standalone nodes
  pmxcfs: dfsm: add a callback that runs once all members are in sync
  pmxcfs: quorum: pass the corosync membership to an optional listener
  pmxcfs: dcdb: generate the cluster ID once the cluster is in sync
  cluster: add helper to read the cluster ID
  pmxcfs: allow removing the cluster ID file in forced local mode

 src/PVE/Cluster.pm          |  16 ++
 src/pmxcfs/Makefile         |  12 +-
 src/pmxcfs/cfs-plug-memdb.c |  46 ++++
 src/pmxcfs/cfs-utils.c      |   8 +
 src/pmxcfs/cfs-utils.h      |   5 +
 src/pmxcfs/check_dcdb.c     | 529 ++++++++++++++++++++++++++++++++++++
 src/pmxcfs/check_memdb.c    | 311 +++++++++++++++++++++
 src/pmxcfs/cluster-id.c     | 158 +++++++++++
 src/pmxcfs/cluster-id.h     |  52 ++++
 src/pmxcfs/dcdb.c           | 144 ++++++++++
 src/pmxcfs/dcdb.h           |   5 +
 src/pmxcfs/dfsm.c           |  58 ++++
 src/pmxcfs/dfsm.h           |  14 +
 src/pmxcfs/pmxcfs.c         |  10 +-
 src/pmxcfs/quorum.c         |  26 +-
 src/pmxcfs/quorum.h         |   8 +-
 src/pmxcfs/status.c         |  12 +
 src/pmxcfs/status.h         |   3 +
 src/test/Makefile           |   6 +-
 src/test/test_cluster_id.pl |  47 ++++
 20 files changed, 1458 insertions(+), 12 deletions(-)
 create mode 100644 src/pmxcfs/check_dcdb.c
 create mode 100644 src/pmxcfs/cluster-id.c
 create mode 100644 src/pmxcfs/cluster-id.h
 create mode 100644 src/test/test_cluster_id.pl


guest-common:

Thomas Lamprecht (4):
  guest identity: add helpers for the guest uid and registration time
  abstract config: assign a guest identity and keep it on config writes
  abstract config: let the VMID reservation return the previous state
  guest identity: allow taking over a uid that is unused in the cluster

 debian/control                     |    1 +
 src/Makefile                       |    1 +
 src/PVE/AbstractConfig.pm          |  235 +++++-
 src/PVE/GuestIdentity.pm           |  384 ++++++++++
 src/tests/Makefile                 |   10 +-
 src/tests/config-identity-tests.pl | 1090 ++++++++++++++++++++++++++++
 src/tests/guest-identity-tests.pl  |  421 +++++++++++
 7 files changed, 2135 insertions(+), 7 deletions(-)
 create mode 100644 src/PVE/GuestIdentity.pm
 create mode 100755 src/tests/config-identity-tests.pl
 create mode 100755 src/tests/guest-identity-tests.pl


qemu-server:

Thomas Lamprecht (6):
  api: restore: release the VMID if a restore to an unused VMID fails
  api: migrate, clone: refuse targets that would drop the guest identity
  fix #7846: config: add a guest identity to the 'meta' property
  restore: take over the guest uid from the backup where possible
  api: remote migration: take over the guest uid from the source
  api: status: return the guest uid

 src/PVE/API2/Qemu.pm                          | 104 +-
 src/PVE/CLI/qmrestore.pm                      |   7 +
 src/PVE/QemuConfig.pm                         |   7 +
 src/PVE/QemuMigrate.pm                        |   9 +-
 src/PVE/QemuServer.pm                         | 150 ++-
 src/PVE/QemuServer/MetaInfo.pm                |   2 +
 src/test/Makefile                             |   5 +-
 src/test/QemuServerTest/FakeCFS.pm            | 197 ++++
 .../q35-windows-pinning-identity-only.conf    |   6 +
 ...q35-windows-pinning-identity-only.conf.cmd |  26 +
 .../meta-identity-invalid.conf                |   6 +
 .../meta-identity-invalid.conf.strict.error   |   2 +
 .../meta-identity-invalid.conf                |   7 +
 .../parse-config-input/meta-identity.conf     |  20 +
 src/test/restore-config-expected/150.conf     |   9 +
 src/test/restore-config-input/150.conf        |  10 +
 src/test/run_api_tests.pl                     | 157 +++
 src/test/run_guest_identity_tests.pl          | 533 ++++++++++
 src/test/run_parse_config_tests.pl            |   2 +-
 src/test/run_qemu_restore_config_tests.pl     | 916 +++++++++++++++++-
 .../create/qemu-server/401.conf               |  31 +
 .../create/qemu-server/402.conf               |  31 +
 .../rollback/qemu-server/401.conf             |  36 +
 .../rollback/qemu-server/402.conf             |  35 +
 .../create/qemu-server/401.conf               |  13 +
 .../create/qemu-server/402.conf               |  13 +
 .../rollback/qemu-server/401.conf             |  35 +
 .../rollback/qemu-server/402.conf             |  34 +
 src/test/snapshot-test.pm                     |  85 +-
 29 files changed, 2439 insertions(+), 49 deletions(-)
 create mode 100644 src/test/QemuServerTest/FakeCFS.pm
 create mode 100644 src/test/cfg2cmd/q35-windows-pinning-identity-only.conf
 create mode 100644 src/test/cfg2cmd/q35-windows-pinning-identity-only.conf.cmd
 create mode 100644 src/test/parse-config-expected/meta-identity-invalid.conf
 create mode 100644 src/test/parse-config-expected/meta-identity-invalid.conf.strict.error
 create mode 100644 src/test/parse-config-input/meta-identity-invalid.conf
 create mode 100644 src/test/parse-config-input/meta-identity.conf
 create mode 100644 src/test/restore-config-expected/150.conf
 create mode 100644 src/test/restore-config-input/150.conf
 create mode 100755 src/test/run_guest_identity_tests.pl
 create mode 100644 src/test/snapshot-expected/create/qemu-server/401.conf
 create mode 100644 src/test/snapshot-expected/create/qemu-server/402.conf
 create mode 100644 src/test/snapshot-expected/rollback/qemu-server/401.conf
 create mode 100644 src/test/snapshot-expected/rollback/qemu-server/402.conf
 create mode 100644 src/test/snapshot-input/create/qemu-server/401.conf
 create mode 100644 src/test/snapshot-input/create/qemu-server/402.conf
 create mode 100644 src/test/snapshot-input/rollback/qemu-server/401.conf
 create mode 100644 src/test/snapshot-input/rollback/qemu-server/402.conf


container:

Thomas Lamprecht (8):
  config: add read-only meta property with the creation time
  fix #7846: config: add a guest identity to the 'meta' property
  api: migrate, clone: refuse targets that would drop the guest identity
  restore: take over the guest uid from the backup where possible
  restore: refuse overwriting a container with another guest's backup
  migrate: remote: clean up the target on a tunnel version mismatch
  api: remote migration: take over the guest uid from the source
  api: status: return the guest uid

 src/PVE/API2/LXC.pm         |  166 +++-
 src/PVE/API2/LXC/Config.pm  |   29 +-
 src/PVE/API2/LXC/Status.pm  |   10 +
 src/PVE/LXC/Config.pm       |   63 +-
 src/PVE/LXC/Migrate.pm      |   31 +-
 src/test/Makefile           |    8 +-
 src/test/config_tests.pl    |   23 +
 src/test/lifecycle_tests.pl | 1878 +++++++++++++++++++++++++++++++++++
 8 files changed, 2177 insertions(+), 31 deletions(-)
 create mode 100755 src/test/lifecycle_tests.pl


manager:

Thomas Lamprecht (5):
  api: cluster resources: add guest uid and registration time
  api: cluster status: add cluster ID
  ui: restore: allow overwriting a guest with a backup of another guest
  ui: migrate: refuse target nodes that would drop the guest identity
  ui: guest summary: show the guest identity

 PVE/API2/Cluster.pm                      |  35 +++-
 test/ClusterResources_test.pl            | 249 +++++++++++++++++++++++
 test/ClusterStatus_test.pl               | 114 +++++++++++
 test/Makefile                            |  10 +-
 www/manager6/Makefile                    |   1 +
 www/manager6/panel/GuestIdentity.js      | 142 +++++++++++++
 www/manager6/panel/GuestStatusView.js    |   3 +
 www/manager6/panel/TemplateStatusView.js |   3 +
 www/manager6/window/Migrate.js           |  29 +++
 www/manager6/window/Restore.js           |  18 ++
 10 files changed, 602 insertions(+), 2 deletions(-)
 create mode 100755 test/ClusterResources_test.pl
 create mode 100755 test/ClusterStatus_test.pl
 create mode 100644 www/manager6/panel/GuestIdentity.js


docs:

Thomas Lamprecht (4):
  vzdump: describe the guest identity of VMs and containers
  pvecm: document the cluster ID and how to get a new one
  qm: configuration: describe the read-only meta property
  pct: configuration: describe the read-only meta property

 pct.adoc    |  35 +++++++
 pmxcfs.adoc |   1 +
 pvecm.adoc  |  86 +++++++++++++++++
 qm.adoc     |  38 ++++++++
 vzdump.adoc | 259 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 419 insertions(+)


Summary over all repositories:
  79 files changed, 9230 insertions(+), 101 deletions(-)

-- 
2.47.3





^ permalink raw reply	[flat|nested] 49+ messages in thread

* [PATCH cluster 01/34] pmxcfs: reject changes to the cluster ID file from user space
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH cluster 02/34] pmxcfs: generate a cluster ID on standalone nodes Thomas Lamprecht
                   ` (34 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

The cluster ID identifies a cluster or standalone node and must remain
stable during normal operation. Reserve /etc/pve/cluster-id for pmxcfs
by rejecting local changes to its content and stored metadata with
EACCES, and report the file as read-only.

Protect timestamps too: changing them updates the entry's version and
writer and replicates like a content change. Keep the existing chmod
and chown behavior, which does not change stored data.

Allow rmdir to remove a directory left at this path by an older node;
otherwise it would prevent ID generation. The kernel already rejects
rmdir on the regular file.

Cluster-delivered operations bypass these local filesystem guards, so
the ID still replicates normally, including between mixed versions.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/pmxcfs/cfs-plug-memdb.c | 42 ++++++++++++++++++
 src/pmxcfs/cfs-utils.c      |  8 ++++
 src/pmxcfs/cfs-utils.h      |  4 ++
 src/pmxcfs/check_memdb.c    | 86 +++++++++++++++++++++++++++++++++++++
 4 files changed, 140 insertions(+)

diff --git a/src/pmxcfs/cfs-plug-memdb.c b/src/pmxcfs/cfs-plug-memdb.c
index dd32684..6040017 100644
--- a/src/pmxcfs/cfs-plug-memdb.c
+++ b/src/pmxcfs/cfs-plug-memdb.c
@@ -129,6 +129,10 @@ static int cfs_plug_memdb_getattr(cfs_plug_t *plug, const char *path, struct sta
 
     if (te) {
         tree_entry_stat(te, stbuf, cfs_is_quorate());
+        /* user space can change neither the content nor the stored metadata of the ID file */
+        if (path_is_cluster_id(path)) {
+            stbuf->st_mode &= ~(S_IWUSR | S_IWGRP | S_IWOTH);
+        }
         memdb_tree_entry_free(te);
         return 0;
     }
@@ -186,6 +190,12 @@ static int cfs_plug_memdb_open(cfs_plug_t *plug, const char *path, struct fuse_f
     g_return_val_if_fail(path != NULL, PARAM_CHECK_ERRNO);
     g_return_val_if_fail(fi != NULL, PARAM_CHECK_ERRNO);
 
+    /* only affects local user space, dcdb applies the operations of other nodes directly */
+    if (path_is_cluster_id(path) &&
+        ((fi->flags & O_ACCMODE) != O_RDONLY || (fi->flags & (O_TRUNC | O_APPEND)))) {
+        return -EACCES;
+    }
+
     memdb_tree_entry_t *te;
 
     cfs_plug_memdb_t *mdb = (cfs_plug_memdb_t *)plug;
@@ -255,6 +265,10 @@ static int cfs_plug_memdb_write(
     g_return_val_if_fail(path != NULL, PARAM_CHECK_ERRNO);
     g_return_val_if_fail(buf != NULL, PARAM_CHECK_ERRNO);
 
+    if (path_is_cluster_id(path)) {
+        return -EACCES;
+    }
+
     int res;
 
     cfs_plug_memdb_t *mdb = (cfs_plug_memdb_t *)plug;
@@ -276,6 +290,10 @@ static int cfs_plug_memdb_truncate(cfs_plug_t *plug, const char *path, off_t siz
     g_return_val_if_fail(plug->ops == &cfs_ops, PARAM_CHECK_ERRNO);
     g_return_val_if_fail(path != NULL, PARAM_CHECK_ERRNO);
 
+    if (path_is_cluster_id(path)) {
+        return -EACCES;
+    }
+
     int res;
 
     cfs_plug_memdb_t *mdb = (cfs_plug_memdb_t *)plug;
@@ -298,6 +316,10 @@ cfs_plug_memdb_create(cfs_plug_t *plug, const char *path, mode_t mode, struct fu
     g_return_val_if_fail(path != NULL, PARAM_CHECK_ERRNO);
     g_return_val_if_fail(fi != NULL, PARAM_CHECK_ERRNO);
 
+    if (path_is_cluster_id(path)) {
+        return -EACCES;
+    }
+
     int res;
 
     cfs_plug_memdb_t *mdb = (cfs_plug_memdb_t *)plug;
@@ -318,6 +340,10 @@ static int cfs_plug_memdb_mkdir(cfs_plug_t *plug, const char *path, mode_t mode)
     g_return_val_if_fail(plug->ops == &cfs_ops, PARAM_CHECK_ERRNO);
     g_return_val_if_fail(path != NULL, PARAM_CHECK_ERRNO);
 
+    if (path_is_cluster_id(path)) {
+        return -EACCES;
+    }
+
     int res;
 
     cfs_plug_memdb_t *mdb = (cfs_plug_memdb_t *)plug;
@@ -337,6 +363,10 @@ static int cfs_plug_memdb_rmdir(cfs_plug_t *plug, const char *path) {
     g_return_val_if_fail(plug->ops == &cfs_ops, PARAM_CHECK_ERRNO);
     g_return_val_if_fail(path != NULL, PARAM_CHECK_ERRNO);
 
+    /* no cluster ID check: the kernel refuses rmdir on the regular file, and a directory that a
+     * node without the check created at that path must stay removable, as it keeps the ID from
+     * being written */
+
     int res;
 
     cfs_plug_memdb_t *mdb = (cfs_plug_memdb_t *)plug;
@@ -357,6 +387,10 @@ static int cfs_plug_memdb_rename(cfs_plug_t *plug, const char *from, const char
     g_return_val_if_fail(from != NULL, PARAM_CHECK_ERRNO);
     g_return_val_if_fail(to != NULL, PARAM_CHECK_ERRNO);
 
+    if (path_is_cluster_id(from) || path_is_cluster_id(to)) {
+        return -EACCES;
+    }
+
     int res;
 
     cfs_plug_memdb_t *mdb = (cfs_plug_memdb_t *)plug;
@@ -376,6 +410,10 @@ static int cfs_plug_memdb_unlink(cfs_plug_t *plug, const char *path) {
     g_return_val_if_fail(plug->ops == &cfs_ops, PARAM_CHECK_ERRNO);
     g_return_val_if_fail(path != NULL, PARAM_CHECK_ERRNO);
 
+    if (path_is_cluster_id(path)) {
+        return -EACCES;
+    }
+
     int res;
 
     cfs_plug_memdb_t *mdb = (cfs_plug_memdb_t *)plug;
@@ -396,6 +434,10 @@ static int cfs_plug_memdb_utimens(cfs_plug_t *plug, const char *path, const stru
     g_return_val_if_fail(path != NULL, PARAM_CHECK_ERRNO);
     g_return_val_if_fail(tv != NULL, PARAM_CHECK_ERRNO);
 
+    if (path_is_cluster_id(path)) {
+        return -EACCES;
+    }
+
     int res;
 
     cfs_plug_memdb_t *mdb = (cfs_plug_memdb_t *)plug;
diff --git a/src/pmxcfs/cfs-utils.c b/src/pmxcfs/cfs-utils.c
index db5e3ed..7527324 100644
--- a/src/pmxcfs/cfs-utils.c
+++ b/src/pmxcfs/cfs-utils.c
@@ -339,3 +339,11 @@ gboolean path_is_lockdir(const char *path) {
 
     return (strncmp(path, "priv/lock/", 10) == 0) && path[10];
 }
+
+gboolean path_is_cluster_id(const char *path) {
+    size_t len;
+    const char *component = path_next_component(&path, &len);
+
+    return component && path_component_is(component, len, CFS_CLUSTER_ID_FN) &&
+           !path_next_component(&path, &len);
+}
diff --git a/src/pmxcfs/cfs-utils.h b/src/pmxcfs/cfs-utils.h
index ed67264..175be38 100644
--- a/src/pmxcfs/cfs-utils.h
+++ b/src/pmxcfs/cfs-utils.h
@@ -34,6 +34,8 @@
 #define VARLIBDIR "/var/lib/pve-cluster"
 #define RUNDIR "/run/pve-cluster"
 
+#define CFS_CLUSTER_ID_FN "cluster-id"
+
 #define CFS_MAX(a, b) (((a) > (b)) ? (a) : (b))
 #define CFS_MIN(a, b) (((a) < (b)) ? (a) : (b))
 
@@ -98,4 +100,6 @@ gboolean path_is_lxc_conf(const char *path);
 
 gboolean path_is_lockdir(const char *path);
 
+gboolean path_is_cluster_id(const char *path);
+
 #endif /* _PVE_CFS_UTILS_H_ */
diff --git a/src/pmxcfs/check_memdb.c b/src/pmxcfs/check_memdb.c
index f21abd0..1ca1372 100644
--- a/src/pmxcfs/check_memdb.c
+++ b/src/pmxcfs/check_memdb.c
@@ -26,6 +26,7 @@
 #include <string.h>
 #include <unistd.h>
 
+#include "cfs-plug-memdb.h"
 #include "cfs-utils.h"
 #include "memdb.h"
 #include "status.h"
@@ -220,6 +221,87 @@ START_TEST(test_version_and_members_json) {
 }
 END_TEST
 
+START_TEST(test_path_is_cluster_id) {
+    ck_assert(path_is_cluster_id("cluster-id"));
+    ck_assert(path_is_cluster_id("/cluster-id"));
+    ck_assert(path_is_cluster_id("//cluster-id/"));
+
+    ck_assert(!path_is_cluster_id(""));
+    ck_assert(!path_is_cluster_id("/"));
+    ck_assert(!path_is_cluster_id("cluster-i"));
+    ck_assert(!path_is_cluster_id("cluster-id.new"));
+    ck_assert(!path_is_cluster_id("cluster-id/x"));
+    ck_assert(!path_is_cluster_id("nodes/n1/cluster-id"));
+}
+END_TEST
+
+START_TEST(test_cluster_id_fuse_read_only) {
+    time_t ctime = 1234;
+    const char *id = "abcdefghijklmnopqrst\n";
+    gpointer data;
+    struct fuse_file_info fi = {0};
+    struct fuse_file_info fi_write = {.flags = O_WRONLY};
+    struct fuse_file_info fi_trunc = {.flags = O_RDONLY | O_TRUNC};
+    struct fuse_file_info fi_append = {.flags = O_RDONLY | O_APPEND};
+    struct timespec tv[2] = {{.tv_sec = 42}, {.tv_sec = 42}};
+    struct stat stbuf;
+
+    cfs_plug_t *plug = (cfs_plug_t *)cfs_plug_memdb_new("memdb", memdb, NULL);
+    ck_assert(plug != NULL);
+
+    ck_assert(plug->ops->create(plug, "cluster-id", 0644, &fi) == -EACCES);
+    ck_assert(plug->ops->mkdir(plug, "cluster-id", 0755) == -EACCES);
+    ck_assert(memdb_read(memdb, "cluster-id", &data) == -ENOENT);
+
+    /* pmxcfs itself goes to the memdb directly */
+    ck_assert(memdb_create(memdb, "cluster-id", 0, ctime) == 0);
+    ck_assert(memdb_write(memdb, "cluster-id", 0, ctime, id, 21, 0, 1) == 21);
+
+    memdb_tree_entry_t *before = memdb_getattr(memdb, "cluster-id");
+    ck_assert(before != NULL);
+
+    ck_assert(plug->ops->open(plug, "cluster-id", &fi) == 0);
+    ck_assert(plug->ops->open(plug, "cluster-id", &fi_write) == -EACCES);
+    ck_assert(plug->ops->open(plug, "cluster-id", &fi_trunc) == -EACCES);
+    ck_assert(plug->ops->open(plug, "cluster-id", &fi_append) == -EACCES);
+    ck_assert(plug->ops->write(plug, "cluster-id", "x", 1, 0, &fi) == -EACCES);
+    ck_assert(plug->ops->truncate(plug, "cluster-id", 0) == -EACCES);
+    ck_assert(plug->ops->unlink(plug, "cluster-id") == -EACCES);
+    ck_assert(plug->ops->rename(plug, "cluster-id", "moved") == -EACCES);
+    ck_assert(plug->ops->mkdir(plug, "cluster-id", 0755) == -EACCES);
+    ck_assert(plug->ops->utimens(plug, "cluster-id", tv) == -EACCES);
+
+    ck_assert(plug->ops->create(plug, "other", 0644, &fi) == 0);
+    ck_assert(plug->ops->write(plug, "other", "x", 1, 0, &fi) == 1);
+    ck_assert(plug->ops->rename(plug, "other", "cluster-id") == -EACCES);
+
+    ck_assert(memdb_read(memdb, "cluster-id", &data) == 21);
+    ck_assert(memcmp(data, id, 21) == 0);
+    g_free(data);
+
+    /* not even the metadata changed */
+    memdb_tree_entry_t *after = memdb_getattr(memdb, "cluster-id");
+    ck_assert(after != NULL);
+    ck_assert(after->version == before->version);
+    ck_assert(after->mtime == before->mtime);
+    memdb_tree_entry_free(before);
+    memdb_tree_entry_free(after);
+
+    cfs_set_quorate(1, TRUE);
+    ck_assert(plug->ops->getattr(plug, "cluster-id", &stbuf) == 0);
+    ck_assert((stbuf.st_mode & 0777) == 0444);
+    ck_assert(plug->ops->getattr(plug, "other", &stbuf) == 0);
+    ck_assert((stbuf.st_mode & 0777) == 0666);
+
+    /* a directory at the path, as a node without the check can create, stays removable */
+    ck_assert(memdb_delete(memdb, "cluster-id", 0, ctime) == 0);
+    ck_assert(memdb_mkdir(memdb, "cluster-id", 0, ctime) == 0);
+    ck_assert(plug->ops->rmdir(plug, "cluster-id") == 0);
+
+    plug->destroy_plug(plug);
+}
+END_TEST
+
 START_TEST(test_truncate_grow) {
     const char *fn = "/f1";
     time_t ctime = 1234;
@@ -504,6 +586,10 @@ static Suite *memdb_suite(void) {
 
     add_test(s, test_guest_config_properties_last_wins, "guest_config_properties_last_wins");
 
+    add_test(s, test_path_is_cluster_id, "path_is_cluster_id");
+
+    add_test(s, test_cluster_id_fuse_read_only, "cluster_id_fuse_read_only");
+
     add_test(s, test_indextest1, "indextest1");
 
     add_test(s, test_loaddb1, "loaddb1");
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH cluster 02/34] pmxcfs: generate a cluster ID on standalone nodes
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH cluster 01/34] pmxcfs: reject changes to the cluster ID file from user space Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH cluster 03/34] pmxcfs: dfsm: add a callback that runs once all members are in sync Thomas Lamprecht
                   ` (33 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Standalone nodes need a cluster ID to distinguish them from other
installations. Generate and persist it before mounting the filesystem
or starting the IPC server, when no other writer or reader can access
the database.

Use 100 random bits from /dev/urandom, encoded as 20 lowercase RFC 4648
base32 characters without padding, followed by a newline. Keep a valid
existing ID, with or without its newline. Replace invalid content,
including an empty file left by interrupted initialization. Log a
directory at the path and leave it for an administrator to remove with
rmdir.

Abort startup if storing the ID fails: the in-memory database could
otherwise expose an ID that is lost or replaced after a restart. A
failure to obtain random data only logs an error, since nothing was
written and the next startup can retry.

Do not generate an ID in forced local mode if corosync.conf exists.
That node belongs to a cluster and must not create a conflicting ID
before rejoining it.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/pmxcfs/Makefile      |   2 +-
 src/pmxcfs/check_memdb.c | 193 +++++++++++++++++++++++++++++++++++++++
 src/pmxcfs/cluster-id.c  | 158 ++++++++++++++++++++++++++++++++
 src/pmxcfs/cluster-id.h  |  52 +++++++++++
 src/pmxcfs/pmxcfs.c      |   6 ++
 5 files changed, 410 insertions(+), 1 deletion(-)
 create mode 100644 src/pmxcfs/cluster-id.c
 create mode 100644 src/pmxcfs/cluster-id.h

diff --git a/src/pmxcfs/Makefile b/src/pmxcfs/Makefile
index 547f258..cd93e72 100644
--- a/src/pmxcfs/Makefile
+++ b/src/pmxcfs/Makefile
@@ -21,7 +21,7 @@ all: pmxcfs create_pmxcfs_db logtest check_memdb
 
 libpmxcfs.a: logger.o loop.o server.o status.o confdb.o quorum.o dcdb.o dfsm.o
 libpmxcfs.a: cfs-plug.o cfs-plug-memdb.o cfs-plug-link.o cfs-plug-func.o
-libpmxcfs.a: cfs-utils.o memdb.o database.o
+libpmxcfs.a: cfs-utils.o memdb.o database.o cluster-id.o
 libpmxcfs.a:
 	$(AR) $(ARFLAGS) $@ $^
 
diff --git a/src/pmxcfs/check_memdb.c b/src/pmxcfs/check_memdb.c
index 1ca1372..bca6443 100644
--- a/src/pmxcfs/check_memdb.c
+++ b/src/pmxcfs/check_memdb.c
@@ -19,8 +19,10 @@
 */
 
 #include <check.h>
+#include <dirent.h>
 #include <errno.h>
 #include <glib.h>
+#include <sqlite3.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -28,6 +30,7 @@
 
 #include "cfs-plug-memdb.h"
 #include "cfs-utils.h"
+#include "cluster-id.h"
 #include "memdb.h"
 #include "status.h"
 
@@ -302,6 +305,184 @@ START_TEST(test_cluster_id_fuse_read_only) {
 }
 END_TEST
 
+START_TEST(test_cluster_id_encode) {
+    struct {
+        guint8 raw[CLUSTER_ID_RAW_SIZE];
+        const char *id;
+    } cases[] = {
+        {{0}, "aaaaaaaaaaaaaaaaaaaa\n"},
+        {{0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff},
+         "77777777777777777777\n"},
+        {{'f', 'o', 'o', 'b', 'a', 'f', 'o', 'o', 'b', 'a', 'f', 'o', 'o'}, "mzxw6ytbmzxw6ytbmzxw\n"
+        },
+        {{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}, "aaaqeayeaudaocajbifq\n"},
+        /* the last character takes bit 95 and the upper half of the last byte */
+        {{0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x01, 0xf0}, "qaaaaaaaaaaaaaaaaaa7\n"},
+        /* the lower half of the last byte is not used */
+        {{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x0f}, "aaaaaaaaaaaaaaaaaaaa\n"},
+    };
+
+    for (size_t i = 0; i < G_N_ELEMENTS(cases); i++) {
+        char id[CLUSTER_ID_FILE_SIZE];
+        cluster_id_encode(cases[i].raw, id);
+        ck_assert(memcmp(id, cases[i].id, CLUSTER_ID_FILE_SIZE) == 0);
+        ck_assert(cluster_id_is_valid(id, sizeof(id)));
+    }
+}
+END_TEST
+
+START_TEST(test_cluster_id_is_valid) {
+    ck_assert(cluster_id_is_valid("abcdefghijklmnopqrst\n", 21));
+    ck_assert(cluster_id_is_valid("uvwxyz234567abcdefgh\n", 21));
+    ck_assert(cluster_id_is_valid("abcdefghijklmnopqrst", 20));
+
+    ck_assert(!cluster_id_is_valid(NULL, 21));
+    ck_assert(!cluster_id_is_valid("", 0));
+    ck_assert(!cluster_id_is_valid("abcdefghijklmno", 15));
+    ck_assert(!cluster_id_is_valid("abcdefghijklmnop", 16));
+    ck_assert(!cluster_id_is_valid("abcdefghijklmnop\n", 17));
+    ck_assert(!cluster_id_is_valid("abcdefghijklmnopqrs\n", 20));
+    ck_assert(!cluster_id_is_valid("abcdefghijklmnopqrstu", 21));
+    ck_assert(!cluster_id_is_valid("abcdefghijklmnopqrstu\n", 22));
+    ck_assert(!cluster_id_is_valid("abcdefghijklmnopqrst\n\n", 22));
+    ck_assert(!cluster_id_is_valid("abcdefghijklmnopqrst ", 21));
+    ck_assert(!cluster_id_is_valid("Abcdefghijklmnopqrst\n", 21));
+    ck_assert(!cluster_id_is_valid("abcdefghijklmnopqrs1\n", 21));
+    ck_assert(!cluster_id_is_valid("abcdefghijklmnopqrs8\n", 21));
+    ck_assert(!cluster_id_is_valid("abcdefgh\0jklmnopqrst\n", 21));
+}
+END_TEST
+
+START_TEST(test_cluster_id_generate) {
+    char id1[CLUSTER_ID_FILE_SIZE], id2[CLUSTER_ID_FILE_SIZE];
+
+    ck_assert(cluster_id_generate(id1));
+    ck_assert(cluster_id_generate(id2));
+
+    ck_assert(cluster_id_is_valid(id1, sizeof(id1)));
+    ck_assert(cluster_id_is_valid(id2, sizeof(id2)));
+    ck_assert(memcmp(id1, id2, sizeof(id1)) != 0);
+}
+END_TEST
+
+START_TEST(test_cluster_id_state) {
+    time_t ctime = 1234;
+
+    ck_assert(cluster_id_state(memdb) == CLUSTER_ID_MISSING);
+
+    ck_assert(memdb_create(memdb, "cluster-id", 0, ctime) == 0);
+    ck_assert(cluster_id_state(memdb) == CLUSTER_ID_INVALID);
+
+    ck_assert(memdb_write(memdb, "cluster-id", 0, ctime, "abcdefghijklmnopqrst\n", 21, 0, 1) == 21);
+    ck_assert(cluster_id_state(memdb) == CLUSTER_ID_VALID);
+
+    ck_assert(memdb_write(memdb, "cluster-id", 0, ctime, "foo", 3, 0, 1) == 3);
+    ck_assert(cluster_id_state(memdb) == CLUSTER_ID_INVALID);
+
+    ck_assert(memdb_delete(memdb, "cluster-id", 0, ctime) == 0);
+    ck_assert(memdb_mkdir(memdb, "cluster-id", 0, ctime) == 0);
+    ck_assert(cluster_id_state(memdb) == CLUSTER_ID_NOT_A_FILE);
+}
+END_TEST
+
+START_TEST(test_cluster_id_standalone) {
+    time_t ctime = 1234;
+    gpointer data;
+    int len;
+
+    ck_assert(cluster_id_ensure_standalone(memdb));
+    len = memdb_read(memdb, "cluster-id", &data);
+    ck_assert(len == CLUSTER_ID_FILE_SIZE);
+    ck_assert(cluster_id_is_valid(data, len));
+
+    /* an existing ID is kept */
+    char id[CLUSTER_ID_FILE_SIZE];
+    memcpy(id, data, sizeof(id));
+    g_free(data);
+
+    ck_assert(cluster_id_ensure_standalone(memdb));
+    ck_assert(memdb_read(memdb, "cluster-id", &data) == CLUSTER_ID_FILE_SIZE);
+    ck_assert(memcmp(data, id, sizeof(id)) == 0);
+    g_free(data);
+
+    /* an empty file is what a crash between creating and writing leaves behind, it gets filled */
+    ck_assert(memdb_delete(memdb, "cluster-id", 0, ctime) == 0);
+    ck_assert(memdb_create(memdb, "cluster-id", 0, ctime) == 0);
+
+    ck_assert(cluster_id_ensure_standalone(memdb));
+    len = memdb_read(memdb, "cluster-id", &data);
+    ck_assert(len == CLUSTER_ID_FILE_SIZE);
+    ck_assert(cluster_id_is_valid(data, len));
+    g_free(data);
+
+    /* so is invalid content */
+    ck_assert(memdb_write(memdb, "cluster-id", 0, ctime, "foo\n", 4, 0, 1) == 4);
+
+    ck_assert(cluster_id_ensure_standalone(memdb));
+    len = memdb_read(memdb, "cluster-id", &data);
+    ck_assert(len == CLUSTER_ID_FILE_SIZE);
+    ck_assert(cluster_id_is_valid(data, len));
+    g_free(data);
+
+    /* a valid ID without newline is kept as is */
+    ck_assert(memdb_write(memdb, "cluster-id", 0, ctime, "abcdefghijklmnopqrst", 20, 0, 1) == 20);
+
+    ck_assert(cluster_id_ensure_standalone(memdb));
+    ck_assert(memdb_read(memdb, "cluster-id", &data) == 20);
+    ck_assert(memcmp(data, "abcdefghijklmnopqrst", 20) == 0);
+    g_free(data);
+
+    /* an ID with only 16 characters is malformed like anything else and gets replaced */
+    ck_assert(memdb_write(memdb, "cluster-id", 0, ctime, "abcdefghijklmnop\n", 17, 0, 1) == 17);
+
+    ck_assert(cluster_id_ensure_standalone(memdb));
+    len = memdb_read(memdb, "cluster-id", &data);
+    ck_assert(len == CLUSTER_ID_FILE_SIZE);
+    ck_assert(cluster_id_is_valid(data, len));
+    g_free(data);
+
+    /* a directory is left for the admin and does not stop the start */
+    ck_assert(memdb_delete(memdb, "cluster-id", 0, ctime) == 0);
+    ck_assert(memdb_mkdir(memdb, "cluster-id", 0, ctime) == 0);
+
+    ck_assert(cluster_id_ensure_standalone(memdb));
+    memdb_tree_entry_t *te = memdb_getattr(memdb, "cluster-id");
+    ck_assert(te != NULL);
+    ck_assert(te->type == DT_DIR);
+    memdb_tree_entry_free(te);
+}
+END_TEST
+
+static void sql_exec(const char *statement) {
+    sqlite3 *db = NULL;
+    ck_assert(sqlite3_open(TESTDB, &db) == SQLITE_OK);
+    ck_assert(sqlite3_exec(db, statement, NULL, NULL, NULL) == SQLITE_OK);
+    ck_assert(sqlite3_close(db) == SQLITE_OK);
+}
+
+START_TEST(test_cluster_id_standalone_write_failure) {
+    sql_exec(
+        "CREATE TRIGGER fail_cluster_id BEFORE INSERT ON tree "
+        "WHEN NEW.name = 'cluster-id' AND length(NEW.data) > 0 "
+        "BEGIN SELECT RAISE(FAIL, 'injected failure'); END;"
+    );
+
+    /* creating the empty file still works, storing the content fails */
+    ck_assert(!cluster_id_ensure_standalone(memdb));
+    ck_assert(memdb->errors);
+
+    memdb_close(memdb);
+    sql_exec("DROP TRIGGER fail_cluster_id;");
+    memdb = memdb_open(TESTDB);
+    ck_assert(memdb != NULL);
+
+    /* the next start finds the empty file and fills it */
+    ck_assert(cluster_id_state(memdb) == CLUSTER_ID_INVALID);
+    ck_assert(cluster_id_ensure_standalone(memdb));
+    ck_assert(cluster_id_state(memdb) == CLUSTER_ID_VALID);
+}
+END_TEST
+
 START_TEST(test_truncate_grow) {
     const char *fn = "/f1";
     time_t ctime = 1234;
@@ -590,6 +771,18 @@ static Suite *memdb_suite(void) {
 
     add_test(s, test_cluster_id_fuse_read_only, "cluster_id_fuse_read_only");
 
+    add_test(s, test_cluster_id_encode, "cluster_id_encode");
+
+    add_test(s, test_cluster_id_is_valid, "cluster_id_is_valid");
+
+    add_test(s, test_cluster_id_generate, "cluster_id_generate");
+
+    add_test(s, test_cluster_id_state, "cluster_id_state");
+
+    add_test(s, test_cluster_id_standalone, "cluster_id_standalone");
+
+    add_test(s, test_cluster_id_standalone_write_failure, "cluster_id_standalone_write_failure");
+
     add_test(s, test_indextest1, "indextest1");
 
     add_test(s, test_loaddb1, "loaddb1");
diff --git a/src/pmxcfs/cluster-id.c b/src/pmxcfs/cluster-id.c
new file mode 100644
index 0000000..57907d1
--- /dev/null
+++ b/src/pmxcfs/cluster-id.c
@@ -0,0 +1,158 @@
+/*
+  Copyright (C) 2026 Proxmox Server Solutions GmbH
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU Affero General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU Affero General Public License for more details.
+
+  You should have received a copy of the GNU Affero General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+  Author: Thomas Lamprecht <t.lamprecht@proxmox.com>
+
+*/
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif /* HAVE_CONFIG_H */
+
+#include <dirent.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <glib.h>
+#include <time.h>
+#include <unistd.h>
+
+#include "cfs-utils.h"
+#include "cluster-id.h"
+
+static const char base32_alphabet[] = "abcdefghijklmnopqrstuvwxyz234567";
+
+/* Every character takes the next five bits, so each one is uniformly distributed, and the bits
+ * left over after the last character are dropped instead of padded. */
+void cluster_id_encode(const guint8 raw[CLUSTER_ID_RAW_SIZE], char id[CLUSTER_ID_FILE_SIZE]) {
+    guint32 bits = 0;
+    int pending = 0;
+    int pos = 0;
+
+    for (int i = 0; i < CLUSTER_ID_RAW_SIZE && pos < CLUSTER_ID_LEN; i++) {
+        bits = (bits << 8) | raw[i];
+        pending += 8;
+
+        while (pending >= 5 && pos < CLUSTER_ID_LEN) {
+            pending -= 5;
+            id[pos++] = base32_alphabet[(bits >> pending) & 0x1f];
+        }
+    }
+
+    id[pos] = '\n';
+}
+
+gboolean cluster_id_generate(char id[CLUSTER_ID_FILE_SIZE]) {
+    guint8 raw[CLUSTER_ID_RAW_SIZE];
+
+    int fd = open("/dev/urandom", O_RDONLY | O_CLOEXEC);
+    if (fd == -1) {
+        cfs_critical("unable to open /dev/urandom - %s", g_strerror(errno));
+        return FALSE;
+    }
+
+    ssize_t res = safe_read(fd, (char *)raw, sizeof(raw));
+    int saved_errno = errno;
+    close(fd);
+
+    if (res != (ssize_t)sizeof(raw)) {
+        cfs_critical(
+            "unable to read from /dev/urandom - %s",
+            res < 0 ? g_strerror(saved_errno) : "short read"
+        );
+        return FALSE;
+    }
+
+    cluster_id_encode(raw, id);
+
+    return TRUE;
+}
+
+gboolean cluster_id_is_valid(gconstpointer data, size_t len) {
+    const char *id = data;
+
+    if (!id ||
+        !(len == CLUSTER_ID_LEN || (len == CLUSTER_ID_FILE_SIZE && id[CLUSTER_ID_LEN] == '\n'))) {
+        return FALSE;
+    }
+
+    for (int i = 0; i < CLUSTER_ID_LEN; i++) {
+        if (!((id[i] >= 'a' && id[i] <= 'z') || (id[i] >= '2' && id[i] <= '7'))) {
+            return FALSE;
+        }
+    }
+
+    return TRUE;
+}
+
+cluster_id_state_t cluster_id_state(memdb_t *memdb) {
+    g_return_val_if_fail(memdb != NULL, CLUSTER_ID_NOT_A_FILE);
+
+    memdb_tree_entry_t *te = memdb_getattr(memdb, CFS_CLUSTER_ID_FN);
+    if (!te) {
+        return CLUSTER_ID_MISSING;
+    }
+
+    gboolean is_file = te->type == DT_REG;
+    memdb_tree_entry_free(te);
+    if (!is_file) {
+        return CLUSTER_ID_NOT_A_FILE;
+    }
+
+    gpointer data = NULL;
+    int len = memdb_read(memdb, CFS_CLUSTER_ID_FN, &data);
+    gboolean valid = len >= 0 && cluster_id_is_valid(data, len);
+    g_free(data);
+
+    return valid ? CLUSTER_ID_VALID : CLUSTER_ID_INVALID;
+}
+
+gboolean cluster_id_ensure_standalone(memdb_t *memdb) {
+    g_return_val_if_fail(memdb != NULL, FALSE);
+
+    cluster_id_state_t state = cluster_id_state(memdb);
+    if (state == CLUSTER_ID_VALID) {
+        return TRUE;
+    }
+
+    if (state == CLUSTER_ID_NOT_A_FILE) {
+        cfs_message("not generating a cluster ID, '%s' is not a regular file", CFS_CLUSTER_ID_FN);
+        return TRUE;
+    }
+
+    /* nothing got written, so the start can go on, the next one tries again */
+    char id[CLUSTER_ID_FILE_SIZE];
+    if (!cluster_id_generate(id)) {
+        return TRUE;
+    }
+
+    /* nothing is mounted yet, so no reader can see the file between creating and writing it, and
+     * a crash in between leaves an empty file that the next start fills */
+    guint32 mtime = time(NULL);
+    int res = state == CLUSTER_ID_MISSING ? memdb_create(memdb, CFS_CLUSTER_ID_FN, 0, mtime) : 0;
+    if (res == 0) {
+        res = memdb_write(memdb, CFS_CLUSTER_ID_FN, 0, mtime, id, CLUSTER_ID_FILE_SIZE, 0, TRUE);
+    }
+
+    /* the memdb already shows the new content if only storing it failed, so it must not be used */
+    if (res != CLUSTER_ID_FILE_SIZE) {
+        cfs_critical("unable to write '%s' - %s", CFS_CLUSTER_ID_FN, g_strerror(-res));
+        return FALSE;
+    }
+
+    cfs_message("generated cluster ID %.*s", CLUSTER_ID_LEN, id);
+
+    return TRUE;
+}
diff --git a/src/pmxcfs/cluster-id.h b/src/pmxcfs/cluster-id.h
new file mode 100644
index 0000000..996cc71
--- /dev/null
+++ b/src/pmxcfs/cluster-id.h
@@ -0,0 +1,52 @@
+/*
+  Copyright (C) 2026 Proxmox Server Solutions GmbH
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU Affero General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU Affero General Public License for more details.
+
+  You should have received a copy of the GNU Affero General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+  Author: Thomas Lamprecht <t.lamprecht@proxmox.com>
+
+*/
+
+#ifndef _PVE_CLUSTER_ID_H_
+#define _PVE_CLUSTER_ID_H_
+
+#include <glib.h>
+
+#include "memdb.h"
+
+/* the ID is 100 random bits in lowercase RFC 4648 base32, pmxcfs writes it plus a newline */
+#define CLUSTER_ID_RAW_SIZE 13
+#define CLUSTER_ID_LEN 20
+#define CLUSTER_ID_FILE_SIZE (CLUSTER_ID_LEN + 1)
+
+void cluster_id_encode(const guint8 raw[CLUSTER_ID_RAW_SIZE], char id[CLUSTER_ID_FILE_SIZE]);
+
+gboolean cluster_id_generate(char id[CLUSTER_ID_FILE_SIZE]);
+
+gboolean cluster_id_is_valid(gconstpointer data, size_t len);
+
+typedef enum {
+    CLUSTER_ID_VALID,
+    CLUSTER_ID_MISSING,
+    CLUSTER_ID_INVALID,
+    /* a directory, which only rmdir can remove */
+    CLUSTER_ID_NOT_A_FILE,
+} cluster_id_state_t;
+
+cluster_id_state_t cluster_id_state(memdb_t *memdb);
+
+/* FALSE only if storing the ID failed, the memdb must not be used then */
+gboolean cluster_id_ensure_standalone(memdb_t *memdb);
+
+#endif /* _PVE_CLUSTER_ID_H_ */
diff --git a/src/pmxcfs/pmxcfs.c b/src/pmxcfs/pmxcfs.c
index 14f1168..0924eb8 100644
--- a/src/pmxcfs/pmxcfs.c
+++ b/src/pmxcfs/pmxcfs.c
@@ -48,6 +48,7 @@
 #include "cfs-plug-memdb.h"
 #include "cfs-plug.h"
 #include "cfs-utils.h"
+#include "cluster-id.h"
 #include "confdb.h"
 #include "dcdb.h"
 #include "dfsm.h"
@@ -912,6 +913,11 @@ int main(int argc, char *argv[]) {
     } else {
         cfs_debug("using local mode (corosync.conf does not exist)");
         cfs_set_quorate(1, TRUE);
+        /* only without a corosync.conf, forced local mode on a cluster node must not generate an ID
+         * of its own */
+        if (!cluster_id_ensure_standalone(memdb)) {
+            goto err;
+        }
     }
     if (conf_data) {
         g_free(conf_data);
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH cluster 03/34] pmxcfs: dfsm: add a callback that runs once all members are in sync
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH cluster 01/34] pmxcfs: reject changes to the cluster ID file from user space Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH cluster 02/34] pmxcfs: generate a cluster ID on standalone nodes Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH cluster 04/34] pmxcfs: quorum: pass the corosync membership to an optional listener Thomas Lamprecht
                   ` (32 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

A service acting on shared state from the loop thread needs to know
when the local state matches that of all members. The existing synced
callback runs before queued messages are delivered. The sync leader
also enters that state before members needing updates have received
them, so their queued messages are still pending.

Add an optional callback after all members are marked in sync and the
queued messages have been delivered. Call it again on service timer
ticks while that condition holds, allowing failed or skipped actions
to be retried.

Other loop events can request the same check with dfsm_check_in_sync().
Use dfsm_nodeid_is_member() to check membership in the current group.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/pmxcfs/dfsm.c | 58 +++++++++++++++++++++++++++++++++++++++++++++++
 src/pmxcfs/dfsm.h | 14 ++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/src/pmxcfs/dfsm.c b/src/pmxcfs/dfsm.c
index cc2b4db..cf0f1bf 100644
--- a/src/pmxcfs/dfsm.c
+++ b/src/pmxcfs/dfsm.c
@@ -126,6 +126,7 @@ struct dfsm {
     uint32_t local_epoch_counter;
     dfsm_sync_epoch_t sync_epoch;
     uint32_t lowest_nodeid;
+    gboolean in_sync; /* see dfsm_in_sync_fn */
     GSequence *msg_queue;
     GList *sync_queue;
 
@@ -509,6 +510,27 @@ gboolean dfsm_restartable(dfsm_t *dfsm) {
 
 void dfsm_set_errormode(dfsm_t *dfsm) { dfsm_set_mode(dfsm, DFSM_MODE_ERROR); }
 
+static void dfsm_notify_in_sync(dfsm_t *dfsm) {
+    g_return_if_fail(dfsm != NULL);
+    g_return_if_fail(dfsm->sync_info != NULL);
+
+    if (dfsm->in_sync || dfsm_get_mode(dfsm) != DFSM_MODE_SYNCED) {
+        return;
+    }
+
+    for (int i = 0; i < dfsm->sync_info->node_count; i++) {
+        if (!dfsm->sync_info->nodes[i].synced) {
+            return;
+        }
+    }
+
+    dfsm->in_sync = TRUE;
+
+    if (dfsm->dfsm_callbacks->dfsm_in_sync_fn) {
+        dfsm->dfsm_callbacks->dfsm_in_sync_fn(dfsm, dfsm->data);
+    }
+}
+
 static void dfsm_release_sync_resources(
     dfsm_t *dfsm, const struct cpg_address *member_list, size_t member_list_entries
 ) {
@@ -698,6 +720,8 @@ static void dfsm_cpg_deliver_callback(
                 goto leave;
             }
 
+            dfsm_notify_in_sync(dfsm);
+
             return;
 
         } else if (base_header->type == DFSM_MESSAGE_VERIFY_REQUEST) {
@@ -883,6 +907,8 @@ static void dfsm_cpg_deliver_callback(
                         goto leave;
                     }
 
+                    dfsm_notify_in_sync(dfsm);
+
                 } else {
                     dfsm_set_mode(dfsm, DFSM_MODE_UPDATE);
 
@@ -933,6 +959,8 @@ static void dfsm_cpg_deliver_callback(
 
             dfsm_release_sync_resources(dfsm, NULL, 0);
 
+            dfsm_notify_in_sync(dfsm);
+
             return;
         }
 
@@ -1104,6 +1132,7 @@ static void dfsm_cpg_confchg_callback(
     }
 
     dfsm->we_are_member = 0;
+    dfsm->in_sync = FALSE;
 
     /* create new epoch */
     dfsm->local_epoch_counter++;
@@ -1195,6 +1224,7 @@ static void dfsm_cpg_confchg_callback(
         if (!dfsm_deliver_queue(dfsm)) {
             goto leave;
         }
+        dfsm_notify_in_sync(dfsm);
     }
 
     if (dfsm->dfsm_callbacks->dfsm_confchg_fn) {
@@ -1281,6 +1311,31 @@ gboolean dfsm_is_initialized(dfsm_t *dfsm) {
     return (dfsm->cpg_handle != 0) ? TRUE : FALSE;
 }
 
+void dfsm_check_in_sync(dfsm_t *dfsm) {
+    g_return_if_fail(dfsm != NULL);
+
+    if (dfsm->in_sync && dfsm_get_mode(dfsm) == DFSM_MODE_SYNCED &&
+        dfsm->dfsm_callbacks->dfsm_in_sync_fn) {
+        dfsm->dfsm_callbacks->dfsm_in_sync_fn(dfsm, dfsm->data);
+    }
+}
+
+gboolean dfsm_nodeid_is_member(dfsm_t *dfsm, uint32_t nodeid) {
+    g_return_val_if_fail(dfsm != NULL, FALSE);
+
+    if (!dfsm->sync_info) {
+        return FALSE;
+    }
+
+    for (int i = 0; i < dfsm->sync_info->node_count; i++) {
+        if (dfsm->sync_info->nodes[i].nodeid == nodeid) {
+            return TRUE;
+        }
+    }
+
+    return FALSE;
+}
+
 gboolean dfsm_lowest_nodeid(dfsm_t *dfsm) {
     g_return_val_if_fail(dfsm != NULL, FALSE);
 
@@ -1364,6 +1419,7 @@ cs_error_t dfsm_initialize(dfsm_t *dfsm, int *fd) {
 
     dfsm->joined = FALSE;
     dfsm->we_are_member = 0;
+    dfsm->in_sync = FALSE;
 
     dfsm_set_mode(dfsm, DFSM_MODE_START);
 
@@ -1640,6 +1696,8 @@ static void service_dfsm_timer(cfs_service_t *service, gpointer context) {
     g_return_if_fail(dfsm != NULL);
 
     dfsm_verify_request(dfsm);
+
+    dfsm_check_in_sync(dfsm);
 }
 
 static cfs_service_callbacks_t cfs_dfsm_callbacks = {
diff --git a/src/pmxcfs/dfsm.h b/src/pmxcfs/dfsm.h
index 8628e0b..0cc0d45 100644
--- a/src/pmxcfs/dfsm.h
+++ b/src/pmxcfs/dfsm.h
@@ -79,6 +79,8 @@ typedef int (*dfsm_process_state_update_fn_t)(
 
 typedef void (*dfsm_synced_fn_t)(dfsm_t *dfsm);
 
+typedef void (*dfsm_in_sync_fn_t)(dfsm_t *dfsm, gpointer data);
+
 /* return values:
  * res < 0    ... serious error, leave group
  * res >=  0  ... OK
@@ -103,6 +105,12 @@ typedef struct {
     dfsm_process_update_fn_t dfsm_process_update_fn;
     dfsm_checksum_fn_t dfsm_checksum_fn;
     dfsm_synced_fn_t dfsm_synced_fn;
+    /* Called once per sync, as soon as all members are in sync and the messages queued meanwhile
+     * got delivered, so that the local state matches the one of all members, and again on every
+     * service timer tick and dfsm_check_in_sync() call while that holds. dfsm_synced_fn runs
+     * earlier, when the local node enters the synced mode and before the queued messages are
+     * delivered. */
+    dfsm_in_sync_fn_t dfsm_in_sync_fn;
 } dfsm_callbacks_t;
 
 typedef struct {
@@ -150,6 +158,12 @@ cs_error_t dfsm_send_update_complete(dfsm_t *dfsm);
 
 gboolean dfsm_lowest_nodeid(dfsm_t *dfsm);
 
+/* calls dfsm_in_sync_fn again if all members are still in sync, loop thread only */
+void dfsm_check_in_sync(dfsm_t *dfsm);
+
+/* whether a process of that node is a member of the current group, loop thread only */
+gboolean dfsm_nodeid_is_member(dfsm_t *dfsm, uint32_t nodeid);
+
 gboolean dfsm_nodeid_is_local(dfsm_t *dfsm, uint32_t nodeid, uint32_t pid);
 
 cs_error_t dfsm_verify_request(dfsm_t *dfsm);
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH cluster 04/34] pmxcfs: quorum: pass the corosync membership to an optional listener
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (2 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH cluster 03/34] pmxcfs: dfsm: add a callback that runs once all members are in sync Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH cluster 05/34] pmxcfs: dcdb: generate the cluster ID once the cluster is in sync Thomas Lamprecht
                   ` (31 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Quorum alone does not tell a service whether every node contributing to
it has participated in the service's synchronization. Pass the node IDs
from each corosync quorum notification to an optional listener, and an
empty list when the connection to corosync is lost.

The listener runs on the loop thread, like the dfsm callbacks, so it
can compare corosync membership with dfsm group membership without
locking. Existing behavior is unchanged when no listener is registered.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/pmxcfs/pmxcfs.c |  2 +-
 src/pmxcfs/quorum.c | 26 +++++++++++++++++++++-----
 src/pmxcfs/quorum.h |  8 +++++++-
 3 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/src/pmxcfs/pmxcfs.c b/src/pmxcfs/pmxcfs.c
index 0924eb8..1c2f857 100644
--- a/src/pmxcfs/pmxcfs.c
+++ b/src/pmxcfs/pmxcfs.c
@@ -1019,7 +1019,7 @@ int main(int argc, char *argv[]) {
 
     if (dcdb) {
 
-        service_quorum = service_quorum_new();
+        service_quorum = service_quorum_new(NULL, NULL);
 
         cfs_loop_add_service(corosync_loop, service_quorum, QB_LOOP_HIGH);
 
diff --git a/src/pmxcfs/quorum.c b/src/pmxcfs/quorum.c
index e2ec0a3..ab47f53 100644
--- a/src/pmxcfs/quorum.c
+++ b/src/pmxcfs/quorum.c
@@ -35,12 +35,25 @@
 
 #include "cfs-utils.h"
 #include "loop.h"
+#include "quorum.h"
 #include "status.h"
 
 typedef struct {
     quorum_handle_t handle;
+    cfs_quorum_view_fn_t view_fn;
+    gpointer view_data;
 } qs_private_t;
 
+static void quorum_set(
+    qs_private_t *private, uint32_t quorate, gboolean quiet, const uint32_t *nodeids, size_t count
+) {
+    cfs_set_quorate(quorate, quiet);
+
+    if (private->view_fn) {
+        private->view_fn(private->view_data, quorate, nodeids, count);
+    }
+}
+
 static void quorum_notification_fn(
     quorum_handle_t handle,
     uint32_t quorate,
@@ -64,7 +77,7 @@ static void quorum_notification_fn(
         return;
     }
 
-    cfs_set_quorate(quorate, FALSE);
+    quorum_set(private, quorate, FALSE, view_list, view_list_entries);
 }
 
 static quorum_callbacks_t quorum_callbacks = {
@@ -80,7 +93,7 @@ static gboolean service_quorum_finalize(cfs_service_t *service, gpointer context
 
     cs_error_t result;
 
-    cfs_set_quorate(0, TRUE);
+    quorum_set(private, 0, TRUE, NULL, 0);
 
     result = quorum_finalize(handle);
     private->handle = 0;
@@ -150,7 +163,7 @@ static int service_quorum_initialize(cfs_service_t *service, gpointer context) {
     return quorum_fd;
 
 err_finalize:
-    cfs_set_quorate(0, FALSE);
+    quorum_set(private, 0, FALSE, NULL, 0);
     quorum_finalize(handle);
 err_reset_handle:
     private
@@ -185,7 +198,7 @@ loop:
 
     cfs_critical("quorum_dispatch failed: %s", cs_strerror(result));
 
-    cfs_set_quorate(0, FALSE);
+    quorum_set(private, 0, FALSE, NULL, 0);
     quorum_finalize(handle);
     private->handle = 0;
     return FALSE;
@@ -197,7 +210,7 @@ static cfs_service_callbacks_t cfs_quorum_callbacks = {
     .cfs_service_dispatch_fn = service_quorum_dispatch,
 };
 
-cfs_service_t *service_quorum_new(void) {
+cfs_service_t *service_quorum_new(cfs_quorum_view_fn_t view_fn, gpointer view_data) {
     cfs_service_t *service;
 
     qs_private_t *private = g_new0(qs_private_t, 1);
@@ -205,6 +218,9 @@ cfs_service_t *service_quorum_new(void) {
         return NULL;
     }
 
+    private->view_fn = view_fn;
+    private->view_data = view_data;
+
     service = cfs_service_new(&cfs_quorum_callbacks, G_LOG_DOMAIN, private);
 
     return service;
diff --git a/src/pmxcfs/quorum.h b/src/pmxcfs/quorum.h
index da6ba85..f1c9aaa 100644
--- a/src/pmxcfs/quorum.h
+++ b/src/pmxcfs/quorum.h
@@ -25,7 +25,13 @@
 
 #include "loop.h"
 
-cfs_service_t *service_quorum_new(void);
+/* Called on the loop thread with the node IDs of the current corosync membership each time corosync
+ * reports a change, and with none when the connection to corosync is lost. */
+typedef void (*cfs_quorum_view_fn_t)(
+    gpointer data, uint32_t quorate, const uint32_t *nodeids, size_t count
+);
+
+cfs_service_t *service_quorum_new(cfs_quorum_view_fn_t view_fn, gpointer view_data);
 
 void service_quorum_destroy(cfs_service_t *service);
 
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH cluster 05/34] pmxcfs: dcdb: generate the cluster ID once the cluster is in sync
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (3 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH cluster 04/34] pmxcfs: quorum: pass the corosync membership to an optional listener Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH cluster 06/34] cluster: add helper to read the cluster ID Thomas Lamprecht
                   ` (30 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Generate a missing or invalid cluster ID in pmxcfs, including for
upgraded clusters. Only the member with the lowest node ID generates
it, preventing competing IDs within a group.

Quorum alone is insufficient. During a cold boot, corosync can be
quorate before all pmxcfs instances have joined their group. A node
with a stale database could generate an ID before learning the
existing one. At equal database versions, its newer mtime could
then make that ID win the next synchronization.

Require quorum, more than half of the configured nodes in the corosync
membership, and every member of that membership synchronized in the
pmxcfs group. Majorities of the same configured node set overlap;
together with normal database transfer on join, this prevents a stale
minority from generating before synchronizing with the other nodes.
Count nodes rather than votes so this also holds with a QDevice,
two_node, last_man_standing, or lowered expected votes. The tradeoff is
that no ID is generated while half or more of the nodes are down.

This does not prevent ordinary database synchronization from selecting
a database that lacks the ID for other reasons. An ID is generated
again in that case. Log why generation is blocked whenever the reason
changes, naming the nodes whose pmxcfs is missing.

Retry after synchronization, quorum or membership changes, and on the
hourly dcdb timer. Generation uses the existing ordered file messages
without waiting on the loop thread. Interrupted creation can leave an
empty file, which a later attempt fills. Reuse the generated ID until a
valid one is observed, so retries before delivery do not replace it.
Leave a directory at the path untouched and log it.

Older nodes can replicate the file without a new message type. If the
lowest member runs an older version, generation waits until that node
is upgraded or leaves.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/pmxcfs/Makefile     |  10 +-
 src/pmxcfs/check_dcdb.c | 529 ++++++++++++++++++++++++++++++++++++++++
 src/pmxcfs/dcdb.c       | 144 +++++++++++
 src/pmxcfs/dcdb.h       |   5 +
 src/pmxcfs/pmxcfs.c     |   2 +-
 src/pmxcfs/status.c     |  11 +
 src/pmxcfs/status.h     |   3 +
 7 files changed, 700 insertions(+), 4 deletions(-)
 create mode 100644 src/pmxcfs/check_dcdb.c

diff --git a/src/pmxcfs/Makefile b/src/pmxcfs/Makefile
index cd93e72..64d6d6f 100644
--- a/src/pmxcfs/Makefile
+++ b/src/pmxcfs/Makefile
@@ -17,7 +17,7 @@ ARFLAGS = crs
 .c.o:
 	$(CC) $(CFLAGS) -c -o $@ $< -MMD -MT $@ -MF $@.d
 
-all: pmxcfs create_pmxcfs_db logtest check_memdb
+all: pmxcfs create_pmxcfs_db logtest check_memdb check_dcdb
 
 libpmxcfs.a: logger.o loop.o server.o status.o confdb.o quorum.o dcdb.o dfsm.o
 libpmxcfs.a: cfs-plug.o cfs-plug-memdb.o cfs-plug-link.o cfs-plug-func.o
@@ -41,6 +41,9 @@ logtest2: logtest2.o libpmxcfs.a
 check_memdb: check_memdb.o libpmxcfs.a
 	$(CC) $(CFLAGS) -o $@ $^ $(LDFLAGS) $(shell pkg-config --libs check)
 
+check_dcdb: check_dcdb.o libpmxcfs.a
+	$(CC) $(CFLAGS) -o $@ $^ $(LDFLAGS) $(shell pkg-config --libs check)
+
 pmxcfs.8:
 
 -include /usr/share/pve-doc-generator/pve-doc-generator.mk
@@ -57,11 +60,12 @@ format:
 	git ls-files ':/src/pmxcfs/*.[ch]' | xargs -n2 -P0 -- clang-format -i
 
 .PHONY: check
-check: check_memdb
+check: check_memdb check_dcdb
 	./check_memdb
+	./check_dcdb
 
 .PHONY: clean
 clean:
-	rm -f *.o *.o.d *.a pmxcfs create_pmxcfs_db check_memdb logtest pmxcfs.8
+	rm -f *.o *.o.d *.a pmxcfs create_pmxcfs_db check_memdb check_dcdb logtest pmxcfs.8
 
 -include *.o.d
diff --git a/src/pmxcfs/check_dcdb.c b/src/pmxcfs/check_dcdb.c
new file mode 100644
index 0000000..c79fce8
--- /dev/null
+++ b/src/pmxcfs/check_dcdb.c
@@ -0,0 +1,529 @@
+/*
+  Copyright (C) 2026 Proxmox Server Solutions GmbH
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU Affero General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU Affero General Public License for more details.
+
+  You should have received a copy of the GNU Affero General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+  Author: Thomas Lamprecht <t.lamprecht@proxmox.com>
+
+*/
+
+/* Runs several dcdb instances in one process, each with its own memdb, and replaces the CPG
+ * transport with an ordered in-process queue, so that membership changes, syncs and the cluster ID
+ * generation can be tested without corosync. The sources are included to reach the static CPG
+ * callbacks. */
+
+#include <check.h>
+#include <stdint.h>
+
+#include "dfsm.c"
+#undef G_LOG_DOMAIN
+#include "dcdb.c"
+
+#if CHECK_MAJOR_VERSION == 0 && CHECK_MINOR_VERSION <= 10
+#define _TEST_TYPE TFun
+#else
+#define _TEST_TYPE const TTest *
+#endif
+
+cfs_t cfs = {
+    .debug = 0,
+    .nodename = "testnode",
+};
+
+typedef struct {
+    uint32_t nodeid;
+    uint32_t pid;
+    size_t len;
+    void *data;
+} packet_t;
+
+static GQueue packets = G_QUEUE_INIT;
+
+cs_error_t cpg_context_get(cpg_handle_t handle, void **context) {
+    *context = (void *)(uintptr_t)handle;
+    return CS_OK;
+}
+
+cs_error_t cpg_mcast_joined(
+    cpg_handle_t handle, cpg_guarantee_t guarantee, const struct iovec *iov, unsigned int iov_len
+) {
+    dfsm_t *sender = (dfsm_t *)(uintptr_t)handle;
+    packet_t *p = g_new0(packet_t, 1);
+
+    p->nodeid = sender->nodeid;
+    p->pid = sender->pid;
+
+    for (unsigned int i = 0; i < iov_len; i++) {
+        p->len += iov[i].iov_len;
+    }
+
+    p->data = g_malloc(p->len);
+
+    size_t pos = 0;
+    for (unsigned int i = 0; i < iov_len; i++) {
+        if (iov[i].iov_len) {
+            memcpy((char *)p->data + pos, iov[i].iov_base, iov[i].iov_len);
+        }
+        pos += iov[i].iov_len;
+    }
+
+    g_queue_push_tail(&packets, p);
+
+    return CS_OK;
+}
+
+/* delivers all queued messages, including those sent meanwhile, to the given nodes in order */
+static void pump(dfsm_t **nodes, int count) {
+    int rounds = 0;
+
+    while (!g_queue_is_empty(&packets)) {
+        ck_assert(++rounds < 1000);
+
+        packet_t *p = g_queue_pop_head(&packets);
+        for (int i = 0; i < count; i++) {
+            dfsm_cpg_deliver_callback(
+                nodes[i]->cpg_handle, &nodes[i]->cpg_group_name, p->nodeid, p->pid, p->data, p->len
+            );
+            ck_assert(dfsm_get_mode(nodes[i]) < DFSM_ERROR_MODE_START);
+        }
+
+        g_free(p->data);
+        g_free(p);
+    }
+}
+
+/* the databases of all tests, removed at the end whatever the tests left behind */
+static char *tmpdir;
+
+static memdb_t *open_db(const char *name) {
+    char *filename = g_build_filename(tmpdir, name, NULL);
+    unlink(filename);
+    memdb_t *memdb = memdb_open(filename);
+    g_free(filename);
+    ck_assert(memdb != NULL);
+
+    /* a node in cluster mode always has a corosync.conf */
+    ck_assert(memdb_create(memdb, "corosync.conf", 0, 100) == 0);
+
+    return memdb;
+}
+
+static dfsm_t *start_node(memdb_t *memdb, uint32_t nodeid) {
+    dfsm_t *dfsm = dcdb_new(memdb);
+    ck_assert(dfsm != NULL);
+
+    dfsm->cpg_handle = (uintptr_t)dfsm;
+    dfsm->nodeid = nodeid;
+    dfsm->pid = 100 + nodeid;
+
+    return dfsm;
+}
+
+static void stop_nodes(dfsm_t **nodes, memdb_t **dbs, int count) {
+    for (int i = 0; i < count; i++) {
+        nodes[i]->cpg_handle = 0;
+        dfsm_destroy(nodes[i]);
+        memdb_close(dbs[i]);
+    }
+}
+
+/* the nodes in the corosync configuration, as the confdb service reads them */
+static void set_config_nodes(uint32_t count) {
+    cfs_clinfo_t *clinfo = cfs_clinfo_new("test", 1);
+
+    for (uint32_t i = 1; i <= count; i++) {
+        char *name = g_strdup_printf("node%u", i);
+        cfs_clinfo_add_node(clinfo, cfs_clnode_new(name, i, 1));
+        g_free(name);
+    }
+
+    cfs_status_set_clinfo(clinfo);
+}
+
+/* a change of the dcdb group, as seen by its members, without delivering what it causes */
+static void change_group(dfsm_t **nodes, int count) {
+    struct cpg_address members[count];
+
+    for (int i = 0; i < count; i++) {
+        members[i].nodeid = nodes[i]->nodeid;
+        members[i].pid = nodes[i]->pid;
+        members[i].reason = 0;
+    }
+
+    for (int i = 0; i < count; i++) {
+        dfsm_cpg_confchg_callback(
+            nodes[i]->cpg_handle, &nodes[i]->cpg_group_name, members, count, NULL, 0, members, count
+        );
+    }
+}
+
+static void set_group(dfsm_t **nodes, int count) {
+    change_group(nodes, count);
+    pump(nodes, count);
+}
+
+/* a change of the corosync membership, as the quorum service reports it */
+static void
+set_quorum(dfsm_t **nodes, int count, uint32_t quorate, uint32_t *view, size_t view_len) {
+    cfs_set_quorate(quorate, TRUE);
+
+    for (int i = 0; i < count; i++) {
+        dcdb_quorum_view_changed(nodes[i], quorate, view, view_len);
+    }
+
+    pump(nodes, count);
+}
+
+static void read_id(memdb_t *memdb, char id[CLUSTER_ID_FILE_SIZE]) {
+    gpointer data = NULL;
+
+    ck_assert(memdb_read(memdb, "cluster-id", &data) == CLUSTER_ID_FILE_SIZE);
+    ck_assert(cluster_id_is_valid(data, CLUSTER_ID_FILE_SIZE));
+    memcpy(id, data, CLUSTER_ID_FILE_SIZE);
+
+    g_free(data);
+}
+
+static void assert_id(memdb_t *memdb, const char *expected) {
+    char id[CLUSTER_ID_FILE_SIZE];
+
+    read_id(memdb, id);
+    ck_assert(memcmp(id, expected, CLUSTER_ID_FILE_SIZE) == 0);
+}
+
+static void write_id(memdb_t *memdb, const char *id, guint32 writer, guint32 mtime) {
+    ck_assert(memdb_create(memdb, "cluster-id", writer, mtime) == 0);
+    ck_assert(memdb_write(memdb, "cluster-id", writer, mtime, id, strlen(id), 0, 1) == strlen(id));
+}
+
+static void other_writes(memdb_t *memdb, int count) {
+    ck_assert(memdb_create(memdb, "other", 2, 100) == 0);
+    for (int i = 0; i < count; i++) {
+        ck_assert(memdb_write(memdb, "other", 2, 100, "x", 1, 0, 1) == 1);
+    }
+}
+
+START_TEST(test_single_node_cluster) {
+    memdb_t *dbs[] = {open_db("1.db")};
+    dfsm_t *nodes[] = {start_node(dbs[0], 1)};
+    uint32_t view[] = {1};
+    char id[CLUSTER_ID_FILE_SIZE];
+
+    /* without the configured nodes known, nothing happens */
+    set_quorum(nodes, 1, 1, view, 1);
+    set_group(nodes, 1);
+    ck_assert(cluster_id_state(dbs[0]) == CLUSTER_ID_MISSING);
+
+    set_config_nodes(1);
+    set_quorum(nodes, 1, 1, view, 1);
+    read_id(dbs[0], id);
+
+    stop_nodes(nodes, dbs, 1);
+}
+END_TEST
+
+START_TEST(test_only_lowest_generates) {
+    memdb_t *dbs[] = {open_db("1.db"), open_db("2.db")};
+    dfsm_t *nodes[] = {start_node(dbs[0], 1), start_node(dbs[1], 2)};
+    uint32_t view[] = {1, 2};
+    char id1[CLUSTER_ID_FILE_SIZE], id2[CLUSTER_ID_FILE_SIZE];
+
+    set_config_nodes(2);
+    set_quorum(nodes, 2, 1, view, 2);
+    set_group(nodes, 2);
+
+    read_id(dbs[0], id1);
+    read_id(dbs[1], id2);
+    ck_assert(memcmp(id1, id2, CLUSTER_ID_FILE_SIZE) == 0);
+
+    /* written by node 1, the lowest */
+    memdb_tree_entry_t *te = memdb_getattr(dbs[1], "cluster-id");
+    ck_assert(te != NULL);
+    ck_assert(te->writer == 1);
+    memdb_tree_entry_free(te);
+
+    stop_nodes(nodes, dbs, 2);
+}
+END_TEST
+
+/* A node with an outdated database starts first and is alone in the group, while corosync, with
+ * the other node running, makes it quorate. It must not publish an ID of its own. */
+START_TEST(test_stale_node_alone) {
+    memdb_t *dbs[] = {open_db("1.db"), open_db("2.db")};
+    write_id(dbs[1], "abcdefghijklmnopqrst\n", 2, 100);
+    other_writes(dbs[1], 10);
+
+    dfsm_t *nodes[] = {start_node(dbs[0], 1), start_node(dbs[1], 2)};
+    uint32_t view[] = {1, 2};
+
+    set_config_nodes(2);
+    set_quorum(nodes, 1, 1, view, 2);
+    set_group(nodes, 1);
+    ck_assert(cluster_id_state(dbs[0]) == CLUSTER_ID_MISSING);
+
+    set_group(nodes, 2);
+    assert_id(dbs[0], "abcdefghijklmnopqrst\n");
+    assert_id(dbs[1], "abcdefghijklmnopqrst\n");
+
+    stop_nodes(nodes, dbs, 2);
+}
+END_TEST
+
+/* Like above, but the outdated node holds the empty file of an interrupted creation. Filling it
+ * would make its database the newest one, so its ID would replace the established one. */
+START_TEST(test_stale_node_alone_with_empty_file) {
+    memdb_t *dbs[] = {open_db("1.db"), open_db("2.db")};
+    ck_assert(memdb_create(dbs[0], "cluster-id", 1, 100) == 0);
+    write_id(dbs[1], "abcdefghijklmnopqrst\n", 1, 100);
+
+    dfsm_t *nodes[] = {start_node(dbs[0], 1), start_node(dbs[1], 2)};
+    uint32_t view[] = {1, 2};
+
+    set_config_nodes(2);
+    set_quorum(nodes, 1, 1, view, 2);
+    set_group(nodes, 1);
+    ck_assert(cluster_id_state(dbs[0]) == CLUSTER_ID_INVALID);
+
+    set_group(nodes, 2);
+    assert_id(dbs[0], "abcdefghijklmnopqrst\n");
+    assert_id(dbs[1], "abcdefghijklmnopqrst\n");
+
+    stop_nodes(nodes, dbs, 2);
+}
+END_TEST
+
+/* Quorate through a QDevice, or two_node, last_man_standing or lowered expected votes, the
+ * corosync membership of a lone outdated node is just itself. */
+START_TEST(test_lone_node_without_node_majority) {
+    memdb_t *dbs[] = {open_db("1.db"), open_db("2.db")};
+    write_id(dbs[1], "abcdefghijklmnopqrst\n", 2, 100);
+
+    dfsm_t *nodes[] = {start_node(dbs[0], 1), start_node(dbs[1], 2)};
+    uint32_t view1[] = {1}, view12[] = {1, 2};
+
+    set_config_nodes(2);
+    set_quorum(nodes, 1, 1, view1, 1);
+    set_group(nodes, 1);
+    ck_assert(cluster_id_state(dbs[0]) == CLUSTER_ID_MISSING);
+
+    set_quorum(nodes, 2, 1, view12, 2);
+    set_group(nodes, 2);
+    assert_id(dbs[0], "abcdefghijklmnopqrst\n");
+    assert_id(dbs[1], "abcdefghijklmnopqrst\n");
+
+    stop_nodes(nodes, dbs, 2);
+}
+END_TEST
+
+START_TEST(test_half_of_the_nodes) {
+    memdb_t *dbs[] = {open_db("1.db"), open_db("2.db")};
+    dfsm_t *nodes[] = {start_node(dbs[0], 1), start_node(dbs[1], 2)};
+    uint32_t view[] = {1, 2};
+
+    set_config_nodes(4);
+    set_quorum(nodes, 2, 1, view, 2);
+    set_group(nodes, 2);
+    ck_assert(cluster_id_state(dbs[0]) == CLUSTER_ID_MISSING);
+    ck_assert(cluster_id_state(dbs[1]) == CLUSTER_ID_MISSING);
+
+    stop_nodes(nodes, dbs, 2);
+}
+END_TEST
+
+/* Neither gaining quorum nor a corosync membership change causes a sync of the group, so the
+ * generation must not wait for the next one. */
+START_TEST(test_quorum_change_triggers) {
+    memdb_t *dbs[] = {open_db("1.db"), open_db("2.db")};
+    dfsm_t *nodes[] = {start_node(dbs[0], 1), start_node(dbs[1], 2)};
+    uint32_t view12[] = {1, 2}, view123[] = {1, 2, 3};
+    char id[CLUSTER_ID_FILE_SIZE];
+
+    set_config_nodes(3);
+    set_quorum(nodes, 2, 0, view12, 2);
+    set_group(nodes, 2);
+    ck_assert(cluster_id_state(dbs[0]) == CLUSTER_ID_MISSING);
+
+    /* node 3 only runs corosync */
+    set_quorum(nodes, 2, 1, view123, 3);
+    ck_assert(cluster_id_state(dbs[0]) == CLUSTER_ID_MISSING);
+
+    /* node 3 left corosync again, the group did not change */
+    set_quorum(nodes, 2, 1, view12, 2);
+    read_id(dbs[0], id);
+    assert_id(dbs[1], id);
+
+    stop_nodes(nodes, dbs, 2);
+}
+END_TEST
+
+/* node 3 joins corosync and the group, in both orders the notifications can arrive */
+static void third_node_joins(gboolean quorum_first) {
+    memdb_t *dbs[] = {open_db("1.db"), open_db("2.db"), open_db("3.db")};
+    dfsm_t *nodes[] = {start_node(dbs[0], 1), start_node(dbs[1], 2), start_node(dbs[2], 3)};
+    uint32_t view12[] = {1, 2}, view123[] = {1, 2, 3};
+    char id[CLUSTER_ID_FILE_SIZE];
+
+    set_config_nodes(5);
+    set_quorum(nodes, 2, 0, view12, 2);
+    set_group(nodes, 2);
+
+    if (quorum_first) {
+        set_quorum(nodes, 3, 1, view123, 3);
+        ck_assert(cluster_id_state(dbs[0]) == CLUSTER_ID_MISSING);
+        set_group(nodes, 3);
+    } else {
+        set_group(nodes, 3);
+        ck_assert(cluster_id_state(dbs[0]) == CLUSTER_ID_MISSING);
+        set_quorum(nodes, 3, 1, view123, 3);
+    }
+
+    read_id(dbs[0], id);
+    assert_id(dbs[1], id);
+    assert_id(dbs[2], id);
+
+    stop_nodes(nodes, dbs, 3);
+}
+
+START_TEST(test_third_node_joins_quorum_first) { third_node_joins(TRUE); }
+END_TEST
+
+START_TEST(test_third_node_joins_group_first) { third_node_joins(FALSE); }
+END_TEST
+
+/* attempts made before the messages of the first one got delivered must write the same ID */
+START_TEST(test_pending_id_reused) {
+    memdb_t *dbs[] = {open_db("1.db")};
+    dfsm_t *nodes[] = {start_node(dbs[0], 1)};
+    uint32_t view[] = {1};
+    char first[CLUSTER_ID_FILE_SIZE];
+
+    set_config_nodes(1);
+    set_quorum(nodes, 1, 1, view, 1);
+
+    change_group(nodes, 1);
+    ck_assert(g_queue_get_length(&packets) == 2);
+    ck_assert(have_pending_cluster_id);
+    memcpy(first, pending_cluster_id, CLUSTER_ID_FILE_SIZE);
+
+    dfsm_check_in_sync(nodes[0]);
+    dcdb_quorum_view_changed(nodes[0], 1, view, 1);
+    ck_assert(g_queue_get_length(&packets) == 6);
+
+    pump(nodes, 1);
+    assert_id(dbs[0], first);
+
+    /* once delivered, the next check finds it valid and forgets the pending one */
+    dfsm_check_in_sync(nodes[0]);
+    ck_assert(g_queue_is_empty(&packets));
+    ck_assert(!have_pending_cluster_id);
+
+    stop_nodes(nodes, dbs, 1);
+}
+END_TEST
+
+START_TEST(test_lowest_repairs_empty_file) {
+    memdb_t *dbs[] = {open_db("1.db"), open_db("2.db")};
+    ck_assert(memdb_create(dbs[0], "cluster-id", 3, 100) == 0);
+    ck_assert(memdb_create(dbs[1], "cluster-id", 3, 100) == 0);
+
+    dfsm_t *nodes[] = {start_node(dbs[0], 1), start_node(dbs[1], 2)};
+    uint32_t view[] = {1, 2};
+    char id[CLUSTER_ID_FILE_SIZE];
+
+    set_config_nodes(2);
+    set_quorum(nodes, 2, 1, view, 2);
+    set_group(nodes, 2);
+
+    read_id(dbs[0], id);
+    assert_id(dbs[1], id);
+
+    stop_nodes(nodes, dbs, 2);
+}
+END_TEST
+
+/* an ID with only 16 characters is malformed like anything else */
+START_TEST(test_lowest_replaces_short_id) {
+    memdb_t *dbs[] = {open_db("1.db"), open_db("2.db")};
+    write_id(dbs[0], "abcdefghijklmnop\n", 1, 100);
+    write_id(dbs[1], "abcdefghijklmnop\n", 1, 100);
+
+    dfsm_t *nodes[] = {start_node(dbs[0], 1), start_node(dbs[1], 2)};
+    uint32_t view[] = {1, 2};
+    char id[CLUSTER_ID_FILE_SIZE];
+
+    set_config_nodes(2);
+    set_quorum(nodes, 2, 1, view, 2);
+    set_group(nodes, 2);
+
+    read_id(dbs[0], id);
+    assert_id(dbs[1], id);
+
+    stop_nodes(nodes, dbs, 2);
+}
+END_TEST
+
+static void add_test(Suite *s, _TEST_TYPE tf, const char *name) {
+    TCase *tc = tcase_create(name);
+    tcase_add_test(tc, tf);
+    suite_add_tcase(s, tc);
+}
+
+static void remove_tmpdir(void) {
+    GDir *dir = g_dir_open(tmpdir, 0, NULL);
+    if (dir) {
+        const char *name;
+        while ((name = g_dir_read_name(dir))) {
+            char *filename = g_build_filename(tmpdir, name, NULL);
+            unlink(filename);
+            g_free(filename);
+        }
+        g_dir_close(dir);
+    }
+
+    rmdir(tmpdir);
+    g_free(tmpdir);
+}
+
+int main(void) {
+    cfs_status_init();
+
+    if (!(tmpdir = g_dir_make_tmp("check_dcdb-XXXXXX", NULL))) {
+        fprintf(stderr, "unable to create a temporary directory\n");
+        return EXIT_FAILURE;
+    }
+
+    Suite *s = suite_create("dcdb");
+
+    add_test(s, test_single_node_cluster, "single_node_cluster");
+    add_test(s, test_only_lowest_generates, "only_lowest_generates");
+    add_test(s, test_stale_node_alone, "stale_node_alone");
+    add_test(s, test_stale_node_alone_with_empty_file, "stale_node_alone_with_empty_file");
+    add_test(s, test_lone_node_without_node_majority, "lone_node_without_node_majority");
+    add_test(s, test_half_of_the_nodes, "half_of_the_nodes");
+    add_test(s, test_quorum_change_triggers, "quorum_change_triggers");
+    add_test(s, test_third_node_joins_quorum_first, "third_node_joins_quorum_first");
+    add_test(s, test_third_node_joins_group_first, "third_node_joins_group_first");
+    add_test(s, test_pending_id_reused, "pending_id_reused");
+    add_test(s, test_lowest_repairs_empty_file, "lowest_repairs_empty_file");
+    add_test(s, test_lowest_replaces_short_id, "lowest_replaces_short_id");
+
+    SRunner *sr = srunner_create(s);
+    srunner_run_all(sr, CK_NORMAL);
+    int number_failed = srunner_ntests_failed(sr);
+    srunner_free(sr);
+
+    remove_tmpdir();
+
+    return (number_failed == 0) ? EXIT_SUCCESS : EXIT_FAILURE;
+}
diff --git a/src/pmxcfs/dcdb.c b/src/pmxcfs/dcdb.c
index 3a0bb81..3dfa051 100644
--- a/src/pmxcfs/dcdb.c
+++ b/src/pmxcfs/dcdb.c
@@ -38,6 +38,7 @@
 #include <unistd.h>
 
 #include "cfs-utils.h"
+#include "cluster-id.h"
 #include "dcdb.h"
 #include "loop.h"
 #include "status.h"
@@ -955,6 +956,148 @@ leave:
     goto ret;
 }
 
+/* node IDs of the current corosync membership while quorate, loop thread only */
+static uint32_t *quorum_view;
+static size_t quorum_view_len;
+
+/* Kept until the file holds a valid ID, so that an attempt made before the messages of an earlier
+ * one got delivered writes the same ID again instead of replacing it. Loop thread only. */
+static char pending_cluster_id[CLUSTER_ID_FILE_SIZE];
+static gboolean have_pending_cluster_id;
+
+/* why the last check did not generate, to log only changes, loop thread only */
+static char *blocked_reason;
+
+static void set_blocked_reason(char *reason) {
+    if (reason && g_strcmp0(reason, blocked_reason) != 0) {
+        cfs_message("not generating a cluster ID yet, %s", reason);
+    }
+
+    g_free(blocked_reason);
+    blocked_reason = reason;
+}
+
+/* An ID is only generated while more than half of the configured nodes are in the corosync
+ * membership and all of those are in sync in this group. Majorities of the same configured node
+ * set overlap. Together with normal database transfer on join, this prevents a stale minority from
+ * generating an ID before it synchronizes with the other nodes. Counting nodes instead of relying
+ * on quorum keeps that with a QDevice, two_node, last_man_standing or lowered expected votes, at
+ * the price of not generating while half of the nodes or more are down. Returns why generating is
+ * blocked. */
+static char *generation_blocker(dfsm_t *dfsm) {
+    if (!quorum_view_len || !cfs_is_quorate()) {
+        return g_strdup("not quorate");
+    }
+
+    guint nodes = cfs_clinfo_node_count();
+    if (!nodes) {
+        return g_strdup("the configured nodes are not known");
+    }
+
+    if (quorum_view_len * 2 <= nodes) {
+        return g_strdup_printf(
+            "only %zu of %u configured nodes are in the corosync membership", quorum_view_len, nodes
+        );
+    }
+
+    GString *missing = NULL;
+    for (size_t i = 0; i < quorum_view_len; i++) {
+        if (!dfsm_nodeid_is_member(dfsm, quorum_view[i])) {
+            if (!missing) {
+                missing = g_string_new(NULL);
+            } else {
+                g_string_append(missing, ", ");
+            }
+            g_string_append_printf(missing, "%u", quorum_view[i]);
+        }
+    }
+
+    if (missing) {
+        char *reason = g_strdup_printf(
+            "node ID(s) %s of the corosync membership are not in the pmxcfs group", missing->str
+        );
+        g_string_free(missing, TRUE);
+        return reason;
+    }
+
+    return NULL;
+}
+
+/* Only the node with the lowest ID generates the cluster ID, like only that node expires locks, so
+ * that no two nodes write different IDs. The loop thread cannot wait for the result of its own
+ * messages, so CREATE and WRITE go out back to back, the messages of one sender stay in order. */
+static void dcdb_in_sync(dfsm_t *dfsm, gpointer data) {
+    g_return_if_fail(dfsm != NULL);
+    g_return_if_fail(data != NULL);
+
+    memdb_t *memdb = (memdb_t *)data;
+
+    if (!dfsm_lowest_nodeid(dfsm)) {
+        return;
+    }
+
+    cluster_id_state_t state = cluster_id_state(memdb);
+    if (state == CLUSTER_ID_VALID) {
+        have_pending_cluster_id = FALSE;
+        set_blocked_reason(NULL);
+        return;
+    }
+
+    if (state == CLUSTER_ID_NOT_A_FILE) {
+        set_blocked_reason(g_strdup_printf("'%s' is not a regular file", CFS_CLUSTER_ID_FN));
+        return;
+    }
+
+    char *reason = generation_blocker(dfsm);
+    set_blocked_reason(reason);
+    if (reason) {
+        return;
+    }
+
+    if (!have_pending_cluster_id) {
+        if (!cluster_id_generate(pending_cluster_id)) {
+            return;
+        }
+        have_pending_cluster_id = TRUE;
+    }
+
+    if (state == CLUSTER_ID_MISSING &&
+        dcdb_send_fuse_message_full(
+            dfsm, DCDB_MESSAGE_CFS_CREATE, CFS_CLUSTER_ID_FN, NULL, NULL, 0, 0, 0, NULL
+        ) != CS_OK) {
+        return;
+    }
+
+    if (dcdb_send_fuse_message_full(
+            dfsm, DCDB_MESSAGE_CFS_WRITE, CFS_CLUSTER_ID_FN, NULL, pending_cluster_id,
+            CLUSTER_ID_FILE_SIZE, 0, 1, NULL
+        ) != CS_OK) {
+        return;
+    }
+
+    cfs_message("generating cluster ID %.*s", CLUSTER_ID_LEN, pending_cluster_id);
+}
+
+void dcdb_quorum_view_changed(
+    gpointer data, uint32_t quorate, const uint32_t *nodeids, size_t count
+) {
+    dfsm_t *dfsm = (dfsm_t *)data;
+
+    g_return_if_fail(dfsm != NULL);
+
+    g_free(quorum_view);
+    quorum_view = NULL;
+    quorum_view_len = 0;
+
+    if (quorate && count) {
+        quorum_view = g_memdup2(nodeids, count * sizeof(*nodeids));
+        quorum_view_len = count;
+    }
+
+    /* neither gaining quorum nor a node that only joins corosync causes a sync of the group */
+    dfsm_check_in_sync(dfsm);
+}
+
 static dfsm_callbacks_t dcdb_dfsm_callbacks = {
     .dfsm_deliver_fn = dcdb_deliver,
     .dfsm_get_state_fn = dcdb_get_state,
@@ -963,6 +1106,7 @@ static dfsm_callbacks_t dcdb_dfsm_callbacks = {
     .dfsm_commit_fn = dcdb_commit,
     .dfsm_cleanup_fn = dcdb_cleanup,
     .dfsm_checksum_fn = dcdb_checksum,
+    .dfsm_in_sync_fn = dcdb_in_sync,
 };
 
 dfsm_t *dcdb_new(memdb_t *memdb) {
diff --git a/src/pmxcfs/dcdb.h b/src/pmxcfs/dcdb.h
index 988da96..8b32dc9 100644
--- a/src/pmxcfs/dcdb.h
+++ b/src/pmxcfs/dcdb.h
@@ -61,4 +61,9 @@ int dcdb_send_fuse_message(
 
 void dcdb_send_unlock(dfsm_t *dfsm, const char *path, const guchar csum[32], gboolean request);
 
+/* quorum view listener, data is the dcdb dfsm */
+void dcdb_quorum_view_changed(
+    gpointer data, uint32_t quorate, const uint32_t *nodeids, size_t count
+);
+
 #endif /* _PVE_DCDB_H_ */
diff --git a/src/pmxcfs/pmxcfs.c b/src/pmxcfs/pmxcfs.c
index 1c2f857..cc8cec2 100644
--- a/src/pmxcfs/pmxcfs.c
+++ b/src/pmxcfs/pmxcfs.c
@@ -1019,7 +1019,7 @@ int main(int argc, char *argv[]) {
 
     if (dcdb) {
 
-        service_quorum = service_quorum_new(NULL, NULL);
+        service_quorum = service_quorum_new(dcdb_quorum_view_changed, dcdb);
 
         cfs_loop_add_service(corosync_loop, service_quorum, QB_LOOP_HIGH);
 
diff --git a/src/pmxcfs/status.c b/src/pmxcfs/status.c
index 80fa682..4f80641 100644
--- a/src/pmxcfs/status.c
+++ b/src/pmxcfs/status.c
@@ -1999,6 +1999,17 @@ gboolean cfs_is_quorate(void) {
     return res;
 }
 
+guint cfs_clinfo_node_count(void) {
+    g_mutex_lock(&mutex);
+    guint count = 0;
+    if (cfs_status.clinfo && cfs_status.clinfo->nodes_byid) {
+        count = g_hash_table_size(cfs_status.clinfo->nodes_byid);
+    }
+    g_mutex_unlock(&mutex);
+
+    return count;
+}
+
 void cfs_set_quorate(uint32_t quorate, gboolean quiet) {
     g_mutex_lock(&mutex);
 
diff --git a/src/pmxcfs/status.h b/src/pmxcfs/status.h
index 6a6b0a7..7b33726 100644
--- a/src/pmxcfs/status.h
+++ b/src/pmxcfs/status.h
@@ -69,6 +69,9 @@ void cfs_set_quorate(uint32_t quorate, gboolean quiet);
 
 gboolean cfs_is_quorate(void);
 
+/* number of nodes in the corosync configuration, 0 while not known yet */
+guint cfs_clinfo_node_count(void);
+
 GHashTable *vmlist_hash_new(void);
 
 gboolean vmlist_hash_insert_vm(
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH cluster 06/34] cluster: add helper to read the cluster ID
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (4 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH cluster 05/34] pmxcfs: dcdb: generate the cluster ID once the cluster is in sync Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH cluster 07/34] pmxcfs: allow removing the cluster ID file in forced local mode Thomas Lamprecht
                   ` (29 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Consumers such as the API should not need to know the cluster ID file
format. Add get_cluster_id() with the same validation rules as pmxcfs.
It returns undef for missing, empty, or invalid content, treating those
cases as "no ID yet".

Register the file for version tracking so cfs_read_file() refreshes its
cached value when the file changes. Do not provide a writer: pmxcfs
owns the file.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/Cluster.pm          | 16 +++++++++++++
 src/pmxcfs/status.c         |  1 +
 src/test/Makefile           |  6 ++++-
 src/test/test_cluster_id.pl | 47 +++++++++++++++++++++++++++++++++++++
 4 files changed, 69 insertions(+), 1 deletion(-)
 create mode 100644 src/test/test_cluster_id.pl

diff --git a/src/PVE/Cluster.pm b/src/PVE/Cluster.pm
index 10c5686..010956b 100644
--- a/src/PVE/Cluster.pm
+++ b/src/PVE/Cluster.pm
@@ -54,6 +54,7 @@ my $observed = {
     'replication.cfg' => 1,
     'corosync.conf' => 1,
     'corosync.conf.new' => 1,
+    'cluster-id' => 1,
     'firewall/cluster.fw' => 1,
     'user.cfg' => 1,
     'domains.cfg' => 1,
@@ -603,6 +604,21 @@ sub cfs_write_file {
     PVE::Tools::file_set_contents($fsname, $raw, undef, $force_utf8);
 }
 
+my $parse_cluster_id = sub {
+    my ($filename, $raw) = @_;
+
+    return undef if !defined($raw);
+    return $raw =~ m/^([a-z2-7]{20})\n?\z/ ? $1 : undef;
+};
+
+cfs_register_file('cluster-id', $parse_cluster_id);
+
+# Returns the ID of the cluster, or of the node if it is standalone, undef if there is none yet. IPC
+# errors other than a missing file are raised, like for other pmxcfs reads.
+sub get_cluster_id {
+    return cfs_read_file('cluster-id');
+}
+
 my $cfs_lock = sub {
     my ($lockid, $timeout, $code, @param) = @_;
 
diff --git a/src/pmxcfs/status.c b/src/pmxcfs/status.c
index 4f80641..641d807 100644
--- a/src/pmxcfs/status.c
+++ b/src/pmxcfs/status.c
@@ -80,6 +80,7 @@ typedef struct {
 static memdb_change_t memdb_change_array[] = {
     {.path = "corosync.conf"},
     {.path = "corosync.conf.new"},
+    {.path = "cluster-id"},
     {.path = "storage.cfg"},
     {.path = "user.cfg"},
     {.path = "domains.cfg"},
diff --git a/src/test/Makefile b/src/test/Makefile
index cdd37d0..c84c435 100644
--- a/src/test/Makefile
+++ b/src/test/Makefile
@@ -4,7 +4,7 @@ cpgtest: cpgtest.c
 	gcc -Wall cpgtest.c $(shell pkg-config --cflags --libs libcpg libqb) -o cpgtest
 
 .PHONY: check install clean distclean
-check: corosync-parser-test test-mac-prefix
+check: corosync-parser-test test-mac-prefix test-cluster-id
 
 .PHONY: corosync-parser-test
 corosync-parser-test:
@@ -14,5 +14,9 @@ corosync-parser-test:
 test-mac-prefix:
 	perl test_mac_prefix.pl
 
+.PHONY: test-cluster-id
+test-cluster-id:
+	perl test_cluster_id.pl
+
 distclean: clean
 clean:
diff --git a/src/test/test_cluster_id.pl b/src/test/test_cluster_id.pl
new file mode 100644
index 0000000..31a0cbf
--- /dev/null
+++ b/src/test/test_cluster_id.pl
@@ -0,0 +1,47 @@
+use strict;
+use warnings;
+
+use Test::MockModule;
+use Test::More;
+
+use lib ('.', '..');
+
+use PVE::Cluster;
+
+my $raw;
+my $cluster_module = Test::MockModule->new('PVE::Cluster');
+$cluster_module->mock(
+    get_config => sub {
+        my ($path) = @_;
+        die "unexpected path '$path'\n" if $path ne 'cluster-id';
+        return $raw;
+    },
+);
+
+my $cases = [
+    ["abcdefghijklmnopqrst\n", 'abcdefghijklmnopqrst', 'valid ID'],
+    ["uvwxyz234567abcdefgh\n", 'uvwxyz234567abcdefgh', 'valid ID with digits'],
+    ['abcdefghijklmnopqrst', 'abcdefghijklmnopqrst', 'valid ID without newline'],
+    [undef, undef, 'missing file'],
+    ['', undef, 'empty file'],
+    ["\n", undef, 'only a newline'],
+    ["abcdefghijklmnopqrst\n\n", undef, 'trailing empty line'],
+    ["abcdefghijklmnopqrst \n", undef, 'trailing space'],
+    [" abcdefghijklmnopqrst\n", undef, 'leading space'],
+    ["abcdefghijklmnopqrs\n", undef, 'too short'],
+    ["abcdefghijklmnop\n", undef, '16 characters'],
+    ["abcdefghijklmnopqrstu\n", undef, 'too long'],
+    ['abcdefghijklmnopqrstu', undef, 'too long without newline'],
+    ["ABCDEFGHIJKLMNOPQRST\n", undef, 'uppercase'],
+    ["abcdefghijklmnopqr01\n", undef, 'digits outside the base32 alphabet'],
+    ["abcdefghijklmnopqr89\n", undef, 'more digits outside the base32 alphabet'],
+    ["abcdefgh\njklmnopqrst\n", undef, 'embedded newline'],
+];
+
+for my $case ($cases->@*) {
+    my ($content, $expected, $name) = $case->@*;
+    $raw = $content;
+    is(PVE::Cluster::get_cluster_id(), $expected, $name);
+}
+
+done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH cluster 07/34] pmxcfs: allow removing the cluster ID file in forced local mode
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (5 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH cluster 06/34] cluster: add helper to read the cluster ID Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH guest-common 08/34] guest identity: add helpers for the guest uid and registration time Thomas Lamprecht
                   ` (28 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

A node that gets separated from its cluster without reinstalling, or a
cloned installation, keeps the cluster ID it had. With the file
protected against changes from user space, only editing the database by
hand would get it a new one.

Allow unlinking the file while pmxcfs runs in forced local mode (-l),
which the documented procedure for separating a node already uses to
remove the corosync.conf. The next start without a corosync.conf then
generates a new ID, like on any standalone node. Moving the file away
is allowed then too, as libfuse unlinks a file that is still open by
renaming it to a hidden name. Outside of forced local mode both stay
rejected, and nothing can be moved onto the path in any mode.

An unlink done in local mode on a node that later rejoins its cluster
replicates like any other change made in local mode: if the database
of that node wins the sync, the file is gone on all nodes, and the
cluster generates a new ID.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/pmxcfs/cfs-plug-memdb.c |  8 ++++++--
 src/pmxcfs/cfs-utils.h      |  1 +
 src/pmxcfs/check_memdb.c    | 32 ++++++++++++++++++++++++++++++++
 src/pmxcfs/pmxcfs.c         |  2 ++
 4 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/src/pmxcfs/cfs-plug-memdb.c b/src/pmxcfs/cfs-plug-memdb.c
index 6040017..71b3128 100644
--- a/src/pmxcfs/cfs-plug-memdb.c
+++ b/src/pmxcfs/cfs-plug-memdb.c
@@ -387,7 +387,9 @@ static int cfs_plug_memdb_rename(cfs_plug_t *plug, const char *from, const char
     g_return_val_if_fail(from != NULL, PARAM_CHECK_ERRNO);
     g_return_val_if_fail(to != NULL, PARAM_CHECK_ERRNO);
 
-    if (path_is_cluster_id(from) || path_is_cluster_id(to)) {
+    /* moving it away is fine in forced local mode, like unlinking it, which libfuse does that way
+     * while the file is still open */
+    if ((path_is_cluster_id(from) && !cfs.force_local_mode) || path_is_cluster_id(to)) {
         return -EACCES;
     }
 
@@ -410,7 +412,9 @@ static int cfs_plug_memdb_unlink(cfs_plug_t *plug, const char *path) {
     g_return_val_if_fail(plug->ops == &cfs_ops, PARAM_CHECK_ERRNO);
     g_return_val_if_fail(path != NULL, PARAM_CHECK_ERRNO);
 
-    if (path_is_cluster_id(path)) {
+    /* the way to give a node that got separated from its cluster an ID of its own, generated by its
+     * next start without a corosync.conf */
+    if (path_is_cluster_id(path) && !cfs.force_local_mode) {
         return -EACCES;
     }
 
diff --git a/src/pmxcfs/cfs-utils.h b/src/pmxcfs/cfs-utils.h
index 175be38..b44fb24 100644
--- a/src/pmxcfs/cfs-utils.h
+++ b/src/pmxcfs/cfs-utils.h
@@ -44,6 +44,7 @@ typedef struct {
     char *ip;
     gid_t gid;
     int debug;
+    gboolean force_local_mode;
 } cfs_t;
 
 extern cfs_t cfs;
diff --git a/src/pmxcfs/check_memdb.c b/src/pmxcfs/check_memdb.c
index bca6443..f706abd 100644
--- a/src/pmxcfs/check_memdb.c
+++ b/src/pmxcfs/check_memdb.c
@@ -483,6 +483,36 @@ START_TEST(test_cluster_id_standalone_write_failure) {
 }
 END_TEST
 
+START_TEST(test_cluster_id_unlink_forced_local_mode) {
+    cfs_plug_t *plug = (cfs_plug_t *)cfs_plug_memdb_new("memdb", memdb, NULL);
+    ck_assert(plug != NULL);
+
+    ck_assert(memdb_create(memdb, "cluster-id", 0, 1234) == 0);
+    ck_assert(memdb_write(memdb, "cluster-id", 0, 1234, "abcdefghijklmnopqrst\n", 21, 0, 1) == 21);
+
+    ck_assert(memdb_create(memdb, "other", 0, 1234) == 0);
+
+    ck_assert(plug->ops->unlink(plug, "cluster-id") == -EACCES);
+    ck_assert(plug->ops->rename(plug, "cluster-id", ".fuse_hidden01") == -EACCES);
+
+    cfs.force_local_mode = TRUE;
+    ck_assert(plug->ops->truncate(plug, "cluster-id", 0) == -EACCES);
+    ck_assert(plug->ops->rename(plug, "other", "cluster-id") == -EACCES);
+
+    /* what libfuse does on unlink while the file is open */
+    ck_assert(plug->ops->rename(plug, "cluster-id", ".fuse_hidden01") == 0);
+    ck_assert(memdb_getattr(memdb, "cluster-id") == NULL);
+
+    ck_assert(memdb_create(memdb, "cluster-id", 0, 1234) == 0);
+    ck_assert(plug->ops->unlink(plug, "cluster-id") == 0);
+    ck_assert(memdb_getattr(memdb, "cluster-id") == NULL);
+
+    cfs.force_local_mode = FALSE;
+
+    plug->destroy_plug(plug);
+}
+END_TEST
+
 START_TEST(test_truncate_grow) {
     const char *fn = "/f1";
     time_t ctime = 1234;
@@ -771,6 +801,8 @@ static Suite *memdb_suite(void) {
 
     add_test(s, test_cluster_id_fuse_read_only, "cluster_id_fuse_read_only");
 
+    add_test(s, test_cluster_id_unlink_forced_local_mode, "cluster_id_unlink_forced_local_mode");
+
     add_test(s, test_cluster_id_encode, "cluster_id_encode");
 
     add_test(s, test_cluster_id_is_valid, "cluster_id_is_valid");
diff --git a/src/pmxcfs/pmxcfs.c b/src/pmxcfs/pmxcfs.c
index cc8cec2..46b7da7 100644
--- a/src/pmxcfs/pmxcfs.c
+++ b/src/pmxcfs/pmxcfs.c
@@ -812,6 +812,8 @@ int main(int argc, char *argv[]) {
         update_qb_log_settings();
     }
 
+    cfs.force_local_mode = force_local_mode;
+
     struct utsname utsname;
     if (uname(&utsname) != 0) {
         cfs_critical("Unable to read local node name");
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH guest-common 08/34] guest identity: add helpers for the guest uid and registration time
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (6 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH cluster 07/34] pmxcfs: allow removing the cluster ID file in forced local mode Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-17 10:47   ` Dominik Csapak
  2026-11-16  0:46 ` [PATCH guest-common 09/34] abstract config: assign a guest identity and keep it on config writes Thomas Lamprecht
                   ` (27 subsequent siblings)
  35 siblings, 1 reply; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

A VMID can be reused, and a guest can get a different VMID or move
to another cluster after a restore or remote migration. External tools
such as backup products need to recognize the same logical guest
independently of its VMID, as described in bug #7846.

Provide shared helpers for a random 100-bit uid, encoded as 20
lowercase base32 characters, and a registration time in milliseconds.
Both are members of the guest config's 'meta' property. Supply format
definitions for both guest types and extract or merge the identity
without requiring knowledge of other members, including newer ones.

Also provide a minimum node-version check for migration targets.
Older versions drop the identity on config writes. Report the required
and available versions so callers can explain a refusal; missing
version information counts as too old.

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

Note: MIN_PVE_MANAGER_VERSION (9.2.29) is a stand-in. It has to become
the first pve-manager version that depends on the qemu-server and
pve-container versions with this series, see the cover letter.

 debian/control                    |   1 +
 src/Makefile                      |   1 +
 src/PVE/GuestIdentity.pm          | 199 ++++++++++++++++++++
 src/tests/Makefile                |   7 +-
 src/tests/guest-identity-tests.pl | 291 ++++++++++++++++++++++++++++++
 5 files changed, 497 insertions(+), 2 deletions(-)
 create mode 100644 src/PVE/GuestIdentity.pm
 create mode 100755 src/tests/guest-identity-tests.pl

diff --git a/debian/control b/debian/control
index ae80297..57fcdf4 100644
--- a/debian/control
+++ b/debian/control
@@ -6,6 +6,7 @@ Build-Depends: debhelper-compat (= 13),
                libpve-cluster-perl,
                libpve-common-perl (>= 9.2.6),
                libpve-storage-perl (>= 8.3.4),
+               libtest-mockmodule-perl <!nocheck>,
                pve-cluster,
 Standards-Version: 4.6.2
 Homepage: https://www.proxmox.com
diff --git a/src/Makefile b/src/Makefile
index 030e7f7..f3546a9 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -7,6 +7,7 @@ all:
 install: PVE
 	install -d ${PERL5DIR}/PVE
 	install -m 0644 PVE/GuestHelpers.pm ${PERL5DIR}/PVE/
+	install -m 0644 PVE/GuestIdentity.pm ${PERL5DIR}/PVE/
 	install -m 0644 PVE/AbstractConfig.pm ${PERL5DIR}/PVE/
 	install -m 0644 PVE/AbstractMigrate.pm ${PERL5DIR}/PVE/
 	install -m 0644 PVE/ReplicationConfig.pm ${PERL5DIR}/PVE/
diff --git a/src/PVE/GuestIdentity.pm b/src/PVE/GuestIdentity.pm
new file mode 100644
index 0000000..44c9a1f
--- /dev/null
+++ b/src/PVE/GuestIdentity.pm
@@ -0,0 +1,199 @@
+package PVE::GuestIdentity;
+
+use strict;
+use warnings;
+
+use Time::HiRes;
+
+use PVE::Cluster;
+
+# The identity of a guest, VM or container alike, consists of two members of the 'meta' property
+# string in the top-level section of its config: 'uid', a random identifier of the guest's lineage
+# (100 bits as 20 characters of the lowercase RFC 4648 base32 alphabet), and 'rtime', the time the
+# config was registered in this cluster (milliseconds since the epoch). The functions here pass it
+# as a hash with these two keys.
+
+# Must match the first pve-manager release that depends on the qemu-server and pve-container
+# versions handling the identity. Older nodes drop the whole 'meta' property on their next write
+# of a guest config.
+use constant MIN_PVE_MANAGER_VERSION => '9.2.29';
+
+my $UID_LENGTH = 20;
+my $UID_PATTERN = "[a-z2-7]{$UID_LENGTH}";
+# the fewest bytes that hold the 5 bits of every uid character, the 4 bits left over are dropped
+my $UID_BYTES = 13;
+my $BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+
+# 15 digits of milliseconds last until the year 33658
+my $RTIME_MAX = 999_999_999_999_999;
+
+# Returns $len random bytes from the kernel's random number generator.
+sub __random_bytes {
+    my ($len) = @_;
+
+    open(my $fh, '<', '/dev/urandom') or die "unable to open /dev/urandom - $!\n";
+    my $buf = '';
+    my $read = sysread($fh, $buf, $len);
+    die "unable to read from /dev/urandom - $!\n" if !defined($read);
+    die "short read from /dev/urandom\n" if $read != $len;
+    close($fh);
+
+    return $buf;
+}
+
+# Returns the current time in milliseconds since the epoch.
+sub __time_ms {
+    my ($sec, $usec) = Time::HiRes::gettimeofday();
+
+    return $sec * 1000 + int($usec / 1000);
+}
+
+# Encodes the first 5 * $UID_LENGTH bits of $bytes as uid. Every character gets 5 bits of its own,
+# so it is uniformly distributed over the alphabet if the bits are.
+my sub encode_uid {
+    my ($bytes) = @_;
+
+    my $bits = unpack('B*', $bytes);
+    die "internal error: " . length($bytes) . " bytes are too few for a uid\n"
+        if length($bits) < 5 * $UID_LENGTH;
+
+    my @groups = substr($bits, 0, 5 * $UID_LENGTH) =~ m/(.{5})/g;
+    return join('', map { substr($BASE32_ALPHABET, oct("0b$_"), 1) } @groups);
+}
+
+my sub is_valid_uid {
+    my ($uid) = @_;
+
+    return defined($uid) && $uid =~ m/^$UID_PATTERN\z/;
+}
+
+my sub is_valid_rtime {
+    my ($rtime) = @_;
+
+    return defined($rtime) && $rtime =~ m/^[0-9]{1,15}\z/;
+}
+
+# Returns the JSON schema properties of the identity members, for merging into the format of the
+# 'meta' property string of a guest type. Every call returns a new copy.
+sub meta_format_properties {
+    return {
+        uid => {
+            type => 'string',
+            pattern => $UID_PATTERN,
+            description =>
+                "Random identifier of the guest lineage. Restores and migrations from other"
+                . " clusters keep it, unless another guest in the cluster already uses it, the"
+                . " restore sets 'unique', or the restore target already has a uid of its own.",
+            optional => 1,
+        },
+        rtime => {
+            type => 'integer',
+            minimum => 0,
+            maximum => $RTIME_MAX,
+            description => "Time the guest was registered in this cluster, for example by"
+                . " creation, restore, or migration from another cluster, in milliseconds since"
+                . " the UNIX epoch.",
+            optional => 1,
+        },
+    };
+}
+
+# Returns a new identity with the current time as rtime. Its uid is $uid if given, otherwise a
+# random one.
+sub new_identity {
+    my ($uid) = @_;
+
+    die "invalid guest identity uid '$uid'\n" if defined($uid) && !is_valid_uid($uid);
+
+    return {
+        uid => $uid // encode_uid(__random_bytes($UID_BYTES)),
+        rtime => __time_ms(),
+    };
+}
+
+# Extracts the identity from the 'meta' property string $meta, which may contain any other
+# members, including ones unknown to this version.
+#
+# Returns undef if $meta has no valid uid, and an identity otherwise. Its rtime is undef if the
+# rtime member is missing or invalid. A member given more than once counts as invalid.
+sub parse_identity {
+    my ($meta) = @_;
+
+    return undef if !defined($meta);
+
+    my $values = {};
+    for my $part (split(/,/, $meta)) {
+        my ($key, $value) = $part =~ m/^([^=]+)=(.*)\z/ or next;
+        next if $key ne 'uid' && $key ne 'rtime';
+        $values->{$key} = exists($values->{$key}) ? undef : $value;
+    }
+
+    return undef if !is_valid_uid($values->{uid});
+
+    return {
+        uid => $values->{uid},
+        rtime => is_valid_rtime($values->{rtime}) ? $values->{rtime} : undef,
+    };
+}
+
+# Returns the 'meta' property string $meta, which may be undef, with the identity members set to
+# $identity. All other members are kept as they are.
+sub merge_identity {
+    my ($meta, $identity) = @_;
+
+    die "invalid guest identity uid\n" if !is_valid_uid($identity->{uid});
+    die "invalid guest identity rtime\n" if !is_valid_rtime($identity->{rtime});
+
+    my (@plain, @members);
+    for my $part (split(/,/, $meta // '')) {
+        next if $part =~ m/^\s*\z/;
+
+        if (my ($key) = $part =~ m/^([^=]+)=/) {
+            push @members, [$key, $part] if $key ne 'uid' && $key ne 'rtime';
+        } else {
+            push @plain, $part;
+        }
+    }
+    push @members, ['rtime', "rtime=$identity->{rtime}"], ['uid', "uid=$identity->{uid}"];
+
+    # same order as PVE::JSONSchema::print_property_string uses, so that a guest type parsing and
+    # printing the property string again does not change it
+    return join(',', @plain, map { $_->[1] } sort { $a->[0] cmp $b->[0] } @members);
+}
+
+# Returns undef if $node runs a version of Proxmox VE that keeps the identity when writing guest
+# configs, see MIN_PVE_MANAGER_VERSION. Missing or invalid version information counts as too old.
+# Otherwise returns a hash with 'required-version', the minimum version, and 'version', the version
+# the node reports, if any.
+sub node_identity_unsupported {
+    my ($node) = @_;
+
+    my $required = MIN_PVE_MANAGER_VERSION;
+    my ($major, $minor, $release) = split(/\./, $required);
+
+    my $supported =
+        eval { PVE::Cluster::node_pvecfg_version_at_least($node, $major, $minor, $release) };
+    return undef if $supported;
+
+    my $version = eval { PVE::Cluster::get_node_pvecfg_version($node) };
+
+    return { 'required-version' => $required, defined($version) ? (version => $version) : () };
+}
+
+# Dies unless $node runs a version of Proxmox VE that keeps the identity when writing guest
+# configs, see node_identity_unsupported.
+sub assert_node_supports_identity {
+    my ($node) = @_;
+
+    my $unsupported = node_identity_unsupported($node) or return;
+    my ($version, $required) = $unsupported->@{qw(version required-version)};
+
+    die "node '$node' does not report its Proxmox VE version, so it is unknown whether the node"
+        . " keeps the guest identity\n"
+        if !defined($version);
+
+    die "node '$node' runs Proxmox VE $version, keeping the guest identity requires $required or"
+        . " newer - upgrade the node first\n";
+}
+
+1;
diff --git a/src/tests/Makefile b/src/tests/Makefile
index 1b1ddb2..129a57e 100644
--- a/src/tests/Makefile
+++ b/src/tests/Makefile
@@ -1,11 +1,14 @@
 
 all:
 
-.PHONY: check abstract-config hookscript
-check: abstract-config hookscript
+.PHONY: check abstract-config guest-identity hookscript
+check: abstract-config guest-identity hookscript
 
 abstract-config: abstract-config-tests.pl
 	perl -I.. ./abstract-config-tests.pl
 
+guest-identity: guest-identity-tests.pl
+	perl -I.. ./guest-identity-tests.pl
+
 hookscript: hookscript-tests.pl
 	perl -I.. ./hookscript-tests.pl
diff --git a/src/tests/guest-identity-tests.pl b/src/tests/guest-identity-tests.pl
new file mode 100755
index 0000000..fb5167d
--- /dev/null
+++ b/src/tests/guest-identity-tests.pl
@@ -0,0 +1,291 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+use lib qw(..);
+
+use Test::MockModule;
+use Test::More;
+use Time::HiRes;
+
+use PVE::JSONSchema;
+use PVE::Tools;
+
+use PVE::GuestIdentity;
+
+subtest 'generation with fixed random bytes and time' => sub {
+    my $random_bytes = [];
+    my $time_ms = 1_700_000_000_123;
+
+    my $identity_module = Test::MockModule->new('PVE::GuestIdentity');
+    $identity_module->redefine(
+        __random_bytes => sub {
+            my ($len) = @_;
+            my $bytes = shift(@$random_bytes) // die "test error: no random bytes left\n";
+            die "test error: requested $len random bytes\n" if length($bytes) != $len;
+            return $bytes;
+        },
+        __time_ms => sub { return $time_ms; },
+    );
+
+    # the first 100 bits of the given bytes in lowercase RFC 4648 base32, which would encode the 4
+    # bits left over as a 21st character, followed by padding
+    my $vectors = [
+        ["\x00" x 13, 'a' x 20],
+        ["\xff" x 13, '7' x 20],
+        ['0123456789abc', 'gaytemzugu3doobzmfrg'],
+        [pack('C*', 0 .. 12), 'aaaqeayeaudaocajbifq'],
+        [("\x00" x 12) . "\x0f", 'a' x 20],
+    ];
+
+    for my $vector (@$vectors) {
+        my ($bytes, $uid) = @$vector;
+        $random_bytes = [$bytes];
+        is_deeply(
+            PVE::GuestIdentity::new_identity(),
+            { uid => $uid, rtime => $time_ms },
+            "encodes " . unpack('H*', $bytes),
+        );
+    }
+
+    # every symbol is as likely at each position, as each character gets 5 bits of its own
+    my $alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
+    my $mismatches = 0;
+    for my $position (0 .. 19) {
+        for my $value (0 .. 31) {
+            my $bits = '0' x 104;
+            substr($bits, 5 * $position, 5) = sprintf('%05b', $value);
+            $random_bytes = [pack('B104', $bits)];
+            my $expected = 'a' x 20;
+            substr($expected, $position, 1) = substr($alphabet, $value, 1);
+            $mismatches++ if PVE::GuestIdentity::new_identity()->{uid} ne $expected;
+        }
+    }
+    is($mismatches, 0, 'each character encodes 5 bits of its own');
+
+    $random_bytes = [];
+    is_deeply(
+        PVE::GuestIdentity::new_identity('gaytemzugu3doobzmfrg'),
+        { uid => 'gaytemzugu3doobzmfrg', rtime => $time_ms },
+        'given uid is used',
+    );
+    eval { PVE::GuestIdentity::new_identity('GAYTEMZUGU3DOOBZMFRG') };
+    like($@, qr/invalid guest identity uid/, 'invalid given uid is rejected');
+};
+
+subtest 'generation' => sub {
+    my $first = PVE::GuestIdentity::new_identity();
+    my $second = PVE::GuestIdentity::new_identity();
+    like($first->{uid}, qr/^[a-z2-7]{20}\z/, 'uid has the expected format');
+    my @uids = map { PVE::GuestIdentity::new_identity()->{uid} } 1 .. 100;
+    is_deeply([grep { !m/^[a-z2-7]{20}\z/ } @uids], [], 'uids have 20 characters, no padding');
+    isnt($first->{uid}, $second->{uid}, 'uids differ');
+
+    my $before = int(Time::HiRes::time() * 1000);
+    my $rtime = PVE::GuestIdentity::new_identity()->{rtime};
+    my $after = int(Time::HiRes::time() * 1000) + 1;
+    like($rtime, qr/^\d+\z/, 'rtime is an integer');
+    ok($rtime >= $before && $rtime <= $after, 'rtime is the current time in milliseconds');
+};
+
+subtest 'format properties' => sub {
+    my $format = {
+        ctime => { type => 'integer', optional => 1 },
+        PVE::GuestIdentity::meta_format_properties()->%*,
+    };
+
+    is_deeply(
+        PVE::JSONSchema::parse_property_string(
+            $format,
+            'ctime=1700000000,rtime=1700000000123,uid=gaytemzugu3doobzmfrg',
+        ),
+        { ctime => 1700000000, rtime => 1700000000123, uid => 'gaytemzugu3doobzmfrg' },
+        'meta string with identity parses with a merged format',
+    );
+
+    for my $invalid (
+        'uid=GAYTEMZUGU3DOOBZMFRG',
+        'uid=gaytemzugu3doobzmfr',
+        'uid=gaytemzugu3doobzmfrga',
+        'uid=gaytemzugu3doobzmfr0',
+        'uid=' . substr('gaytemzugu3doobzmfrg', 0, 16),
+        'rtime=-1',
+        'rtime=1.5',
+        'rtime=1000000000000000',
+    ) {
+        eval { PVE::JSONSchema::parse_property_string($format, $invalid) };
+        ok($@, "format rejects '$invalid'");
+    }
+
+    my $copy = PVE::GuestIdentity::meta_format_properties();
+    $copy->{uid}->{pattern} = '.*';
+    isnt(
+        PVE::GuestIdentity::meta_format_properties()->{uid}->{pattern},
+        '.*',
+        'callers get their own copy',
+    );
+};
+
+subtest 'parse identity' => sub {
+    my $uid = 'gaytemzugu3doobzmfrg';
+    my $tests = [
+        [undef, undef, 'no meta'],
+        ['', undef, 'empty meta'],
+        ['ctime=1700000000', undef, 'meta without identity'],
+        [
+            "creation-qemu=10.1.2,ctime=1700000000,rtime=123,uid=$uid",
+            { uid => $uid, rtime => 123 },
+            'identity next to other members',
+        ],
+        [
+            "future=a b,uid=$uid,other,rtime=0",
+            { uid => $uid, rtime => 0 },
+            'unknown members and odd parts are ignored',
+        ],
+        ["rtime=123,uid=$uid", { uid => $uid, rtime => 123 }, 'identity only'],
+        ["uid=$uid", { uid => $uid, rtime => undef }, 'missing rtime'],
+        ["uid=$uid,rtime=12a", { uid => $uid, rtime => undef }, 'invalid rtime'],
+        ["uid=$uid,rtime=-5", { uid => $uid, rtime => undef }, 'negative rtime'],
+        [
+            "uid=$uid,rtime=999999999999999",
+            { uid => $uid, rtime => 999999999999999 },
+            'maximum rtime',
+        ],
+        ["uid=$uid,rtime=1000000000000000", { uid => $uid, rtime => undef }, 'too large rtime'],
+        [
+            "uid=$uid,rtime=\x{0661}\x{0662}",
+            { uid => $uid, rtime => undef },
+            'non-ASCII digits',
+        ],
+        ["uid=$uid,rtime=1,rtime=2", { uid => $uid, rtime => undef }, 'duplicate rtime'],
+        ['rtime=123', undef, 'rtime without uid'],
+        ["uid=$uid,uid=$uid,rtime=1", undef, 'duplicate uid'],
+        ['uid=GAYTEMZUGU3DOOBZMFRG,rtime=1', undef, 'uppercase uid'],
+        ['uid=gaytemzugu3doobzmfr,rtime=1', undef, 'short uid'],
+        ['uid=gaytemzugu3doobzmfrga,rtime=1', undef, 'long uid'],
+        ['uid=' . substr($uid, 0, 16) . ',rtime=1', undef, '16-character uid'],
+        ['uid=gaytemzugu3doobzmfr1,rtime=1', undef, 'uid outside of the alphabet'],
+        ["uid= $uid,rtime=1", undef, 'uid with whitespace'],
+    ];
+
+    for my $test (@$tests) {
+        my ($meta, $expected, $name) = @$test;
+        is_deeply(PVE::GuestIdentity::parse_identity($meta), $expected, $name);
+    }
+};
+
+subtest 'merge identity' => sub {
+    my $identity = { uid => 'gaytemzugu3doobzmfrg', rtime => 1700000000123 };
+    my $members = 'rtime=1700000000123,uid=gaytemzugu3doobzmfrg';
+    my $tests = [
+        [undef, $members, 'no meta'],
+        ['', $members, 'empty meta'],
+        [
+            'creation-qemu=10.1.2,ctime=1700000000',
+            "creation-qemu=10.1.2,ctime=1700000000,$members",
+            'other members are kept',
+        ],
+        [
+            'ctime=1,rtime=5,uid=aaaaaaaaaaaaaaaaaaaa',
+            "ctime=1,$members",
+            'existing identity is replaced',
+        ],
+        [
+            'uid=bogus,zz-future=x,rtime=1,uid=aaaaaaaaaaaaaaaaaaaa,ctime=1',
+            "ctime=1,$members,zz-future=x",
+            'invalid and duplicate identity members are dropped, unknown members kept',
+        ],
+        ['plain,ctime=1', "plain,ctime=1,$members", 'parts without key stay first'],
+    ];
+
+    for my $test (@$tests) {
+        my ($meta, $expected, $name) = @$test;
+        my $merged = PVE::GuestIdentity::merge_identity($meta, $identity);
+        is($merged, $expected, $name);
+        is_deeply(PVE::GuestIdentity::parse_identity($merged), $identity, "$name, parses back");
+    }
+
+    for my $invalid (
+        { uid => 'GAYTEMZUGU3DOOBZMFRG', rtime => 1 },
+        { uid => 'gaytemzugu3doobzmfrg', rtime => undef },
+        { uid => 'gaytemzugu3doobzmfrg', rtime => 'now' },
+        { uid => 'gaytemzugu3doobzmfrg', rtime => '1000000000000000' },
+        { uid => 'gaytemzugu3doobzmfrg,ctime=1', rtime => 1 },
+        { rtime => 1 },
+    ) {
+        eval { PVE::GuestIdentity::merge_identity('ctime=1', $invalid) };
+        ok($@, "invalid identity is rejected");
+    }
+};
+
+subtest 'node version check' => sub {
+    my $min = PVE::GuestIdentity::MIN_PVE_MANAGER_VERSION;
+    like($min, qr/^[0-9]+\.[0-9]+\.[0-9]+\z/, 'minimum version is a version string');
+    my ($major, $minor, $release) = split(/\./, $min);
+
+    my $versions = {
+        current => "$major.$minor.$release",
+        newer => "$major." . ($minor + 1) . ".0",
+        older => "$major.$minor." . ($release - 1),
+        invalid => 'invalid',
+    };
+
+    my $cluster_module = Test::MockModule->new('PVE::Cluster');
+    $cluster_module->mock(
+        get_node_pvecfg_version => sub {
+            my ($node) = @_;
+            die "malformed version info\n" if $node eq 'malformed';
+            return $versions->{$node};
+        },
+        node_pvecfg_version_at_least => sub {
+            my ($node, @min) = @_;
+            my $version = PVE::Cluster::get_node_pvecfg_version($node);
+            return $version && PVE::Tools::pvecfg_min_version($version, @min);
+        },
+    );
+
+    for my $node (qw(current newer)) {
+        eval { PVE::GuestIdentity::assert_node_supports_identity($node) };
+        is($@, '', "node with version '$versions->{$node}' is supported");
+        my $unsupported = PVE::GuestIdentity::node_identity_unsupported($node);
+        is($unsupported, undef, "no reason for '$node'");
+    }
+
+    for my $node (qw(older invalid missing malformed)) {
+        eval { PVE::GuestIdentity::assert_node_supports_identity($node) };
+        like($@, qr/node '$node'/, "node '$node' is refused");
+    }
+
+    for my $node (qw(older invalid)) {
+        is_deeply(
+            PVE::GuestIdentity::node_identity_unsupported($node),
+            { version => $versions->{$node}, 'required-version' => $min },
+            "reason for '$node' has both versions",
+        );
+        eval { PVE::GuestIdentity::assert_node_supports_identity($node) };
+        is(
+            $@,
+            "node '$node' runs Proxmox VE $versions->{$node}, keeping the guest identity requires"
+                . " $min or newer - upgrade the node first\n",
+            "refusal of '$node' names both versions",
+        );
+    }
+
+    for my $node (qw(missing malformed)) {
+        is_deeply(
+            PVE::GuestIdentity::node_identity_unsupported($node),
+            { 'required-version' => $min },
+            "reason for '$node' has only the required version",
+        );
+        eval { PVE::GuestIdentity::assert_node_supports_identity($node) };
+        is(
+            $@,
+            "node '$node' does not report its Proxmox VE version, so it is unknown whether the"
+                . " node keeps the guest identity\n",
+            "refusal of '$node' says why",
+        );
+    }
+};
+
+done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH guest-common 09/34] abstract config: assign a guest identity and keep it on config writes
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (7 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH guest-common 08/34] guest identity: add helpers for the guest uid and registration time Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-17 10:47   ` Dominik Csapak
  2026-11-16  0:46 ` [PATCH guest-common 10/34] abstract config: let the VMID reservation return the previous state Thomas Lamprecht
                   ` (26 subsequent siblings)
  35 siblings, 1 reply; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

With identities enabled for a guest type, every config write keeps the
identity that the guest already has, regardless of the identity in the
written config, and assigns a new one if the guest has none. This
covers new guests and guests from older versions without identity
handling in every operation. A stale config, a config copied from a
clone source, or a snapshot rollback can neither change nor duplicate
an identity that way. Taking over the uid of a backup needs a separate
check that no other guest in the cluster uses it.

Read the existing identity directly from the cluster filesystem, as
the parsed config in the cache can be outdated, and abort the write on
read errors. A failed IPC connection can look like a missing or empty
file, so verify such a result against the mounted filesystem before
assigning an identity. A file that cannot be checked does not count as
missing.

Some writers, including the container post-stop hook, do not hold the
guest config lock. Read the identity and write the config under a short
local lock, so that concurrent writers cannot assign different
identities.

Guest types have to enable this explicitly: older qemu-server versions
validate 'meta' strictly on writes and would reject a config with the
identity members.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/AbstractConfig.pm          | 111 ++++++-
 src/tests/Makefile                 |   7 +-
 src/tests/config-identity-tests.pl | 488 +++++++++++++++++++++++++++++
 3 files changed, 603 insertions(+), 3 deletions(-)
 create mode 100755 src/tests/config-identity-tests.pl

diff --git a/src/PVE/AbstractConfig.pm b/src/PVE/AbstractConfig.pm
index 7bcae19..e78b8cc 100644
--- a/src/PVE/AbstractConfig.pm
+++ b/src/PVE/AbstractConfig.pm
@@ -3,6 +3,8 @@ package PVE::AbstractConfig;
 use strict;
 use warnings;
 
+use Errno qw(ENOENT);
+
 use PVE::Cluster;
 use PVE::INotify;
 use PVE::JSONSchema;
@@ -10,6 +12,7 @@ use PVE::Storage;
 use PVE::Tools qw(lock_file lock_file_full);
 
 use PVE::GuestHelpers qw(typesafe_ne);
+use PVE::GuestIdentity;
 use PVE::ReplicationConfig;
 use PVE::Replication;
 
@@ -61,13 +64,119 @@ sub load_config {
     return $conf;
 }
 
+# Guest identity, see PVE::GuestIdentity
+
+# Whether writing a config keeps the published guest identity, or assigns one if there is none,
+# see write_config. Only enable it for a guest type whose config format accepts the identity
+# members, as a strict parser would otherwise reject every written config.
+sub __identity_enabled {
+    my ($class) = @_;
+
+    return 0;
+}
+
+# Returns the guest identity contained in the parsed config $conf, undef if there is none. Guest
+# types can override this and __identity_set for a different representation of 'meta' in parsed
+# configs, but the config file must have the identity in the top-level 'meta' property string, as
+# that is where the published identity gets read from.
+sub __identity_get {
+    my ($class, $conf) = @_;
+
+    return PVE::GuestIdentity::parse_identity($conf->{meta});
+}
+
+# Sets the guest identity $identity in the parsed config $conf, keeping everything else.
+sub __identity_set {
+    my ($class, $conf, $identity) = @_;
+
+    $conf->{meta} = PVE::GuestIdentity::merge_identity($conf->{meta}, $identity);
+}
+
+# Returns the guest identity contained in the parsed config $conf, for example of a backup, undef
+# if there is none.
+sub get_identity {
+    my ($class, $conf) = @_;
+
+    return $class->__identity_get($conf);
+}
+
+# Runs $code with the local identity lock of $vmid held and returns its result. Every config write
+# takes it, also ones without the guest config lock like hooks, so never take another lock while
+# holding it. Tests can override it to run without access to the lock directory.
+sub __identity_lock {
+    my ($class, $vmid, $code, @param) = @_;
+
+    my $lockdir = $PVE::GuestHelpers::lockdir;
+    mkdir $lockdir;
+
+    my $res = lock_file("$lockdir/pve-guest-identity-$vmid", 10, $code, @param);
+    die $@ if $@;
+
+    return $res;
+}
+
+# Returns undef if no config file exists for $vmid on this node, otherwise a hash with the identity
+# published in its top-level section, undef if there is none. Reads the file directly, as the
+# parsed configs in the file cache can be outdated. Dies on other read errors. Tests can override
+# it to run without the cluster filesystem.
+sub __identity_read_published {
+    my ($class, $vmid) = @_;
+
+    my $raw = PVE::Cluster::get_config($class->cfs_config_path($vmid));
+    if (!defined($raw) || $raw eq '') {
+        # a failed connection to pmxcfs returns undef with errno left as it was, which can look
+        # like a missing file (ENOENT) or an empty one (no error)
+        my $path = $class->config_file($vmid);
+        my $size = -s $path;
+        # only a file known not to exist counts as missing, not one that cannot be checked
+        die "unable to check config file '$path' for its guest identity - $!\n"
+            if !defined($size) && $! != ENOENT;
+        die "unable to read config file '$path' to check its guest identity\n"
+            if defined($raw) ? $size : defined($size);
+        return undef if !defined($raw);
+    }
+
+    my $meta;
+    for my $line (split(/\n/, $raw)) {
+        last if $line =~ m/^\[/; # snapshot or other section
+        $meta = $1 if $line =~ m/^meta:\s*(.*?)\s*$/;
+    }
+
+    return { identity => PVE::GuestIdentity::parse_identity($meta) };
+}
+
 # Generate and write config file for this VM/CT
+#
+# With guest identities enabled for the class, the identity published in the existing config file
+# gets set in $conf, whatever $conf contains, or a new one if none is published. So a config write
+# never changes a published identity.
 sub write_config {
     my ($class, $vmid, $conf) = @_;
 
     my $cfspath = $class->cfs_config_path($vmid);
 
-    PVE::Cluster::cfs_write_file($cfspath, $conf);
+    if (!$class->__identity_enabled()) {
+        PVE::Cluster::cfs_write_file($cfspath, $conf);
+        return;
+    }
+
+    $class->__identity_lock(
+        $vmid,
+        sub {
+            my $published = $class->__identity_read_published($vmid);
+            my $identity = $published && $published->{identity};
+
+            # a published uid without valid rtime can only come from a manual edit
+            if (!$identity || !defined($identity->{rtime})) {
+                $identity = PVE::GuestIdentity::new_identity($identity && $identity->{uid});
+            }
+
+            $class->__identity_set($conf, $identity);
+            PVE::Cluster::cfs_write_file($cfspath, $conf);
+        },
+    );
+
+    return;
 }
 
 # Pending changes related
diff --git a/src/tests/Makefile b/src/tests/Makefile
index 129a57e..ae66694 100644
--- a/src/tests/Makefile
+++ b/src/tests/Makefile
@@ -1,12 +1,15 @@
 
 all:
 
-.PHONY: check abstract-config guest-identity hookscript
-check: abstract-config guest-identity hookscript
+.PHONY: check abstract-config config-identity guest-identity hookscript
+check: abstract-config config-identity guest-identity hookscript
 
 abstract-config: abstract-config-tests.pl
 	perl -I.. ./abstract-config-tests.pl
 
+config-identity: config-identity-tests.pl
+	perl -I.. ./config-identity-tests.pl
+
 guest-identity: guest-identity-tests.pl
 	perl -I.. ./guest-identity-tests.pl
 
diff --git a/src/tests/config-identity-tests.pl b/src/tests/config-identity-tests.pl
new file mode 100755
index 0000000..92864ca
--- /dev/null
+++ b/src/tests/config-identity-tests.pl
@@ -0,0 +1,488 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+use lib qw(..);
+
+use Fcntl qw(:flock);
+use File::Path qw(make_path);
+use File::Temp qw(tempdir);
+use Storable qw(dclone);
+use Test::MockModule;
+use Test::More;
+
+use PVE::AbstractConfig;
+use PVE::GuestHelpers;
+use PVE::GuestIdentity;
+
+my $tmpdir = tempdir('config-identity-XXXXXX', DIR => '.', CLEANUP => 1);
+$PVE::GuestHelpers::lockdir = "$tmpdir/lock";
+
+# guest config classes using a minimal config file format, see below
+
+package PVE::TestConfig {
+    use base qw(PVE::AbstractConfig);
+
+    sub guest_type { return 'VM'; }
+
+    sub config_file_lock {
+        my ($class, $vmid) = @_;
+        return "$tmpdir/config-$vmid.lock";
+    }
+
+    sub cfs_config_path {
+        my ($class, $vmid, $node) = @_;
+        return "nodes/local/qemu-server/$vmid.conf";
+    }
+
+    # only checked for existence, the fake cluster filesystem below does not create it
+    sub config_file {
+        my ($class, $vmid, $node) = @_;
+        return "$tmpdir/etc-pve/" . $class->cfs_config_path($vmid, $node);
+    }
+
+    sub __identity_enabled { return 1; }
+
+    # just enough for snapshot rollbacks without volumes
+    sub valid_volume_keys { return (); }
+    sub __snapshot_check_running { return 0; }
+    sub __snapshot_rollback_vm_stop { return; }
+    sub __snapshot_rollback_get_unused { return []; }
+}
+
+package PVE::TestConfig::CT {
+    use base qw(PVE::TestConfig);
+
+    sub guest_type { return 'CT'; }
+
+    sub cfs_config_path {
+        my ($class, $vmid, $node) = @_;
+        return "nodes/local/lxc/$vmid.conf";
+    }
+}
+
+package PVE::TestConfig::NoIdentity {
+    use base qw(PVE::TestConfig);
+
+    sub __identity_enabled { return 0; }
+}
+
+# like the tests of a guest type that run without lock directory and cluster filesystem
+package PVE::TestConfig::Seams {
+    use base qw(PVE::TestConfig);
+
+    our $published = {};
+
+    sub __identity_lock {
+        my ($class, $vmid, $code, @param) = @_;
+        return $code->(@param);
+    }
+
+    sub __identity_read_published {
+        my ($class, $vmid) = @_;
+        return $published->{$vmid};
+    }
+}
+
+package main;
+
+# fake cluster filesystem with raw config files, indexed by their cfs path, and a file cache that
+# behaves like the one of PVE::Cluster: it only reads a config again after a write of this process,
+# or after cfs_update noticed a newer version
+
+my $files = {};
+my $versions = {};
+my $version_counter = 0;
+my $seen_versions = {};
+my $cache = {};
+
+our $get_config_error;
+our $check_identity_lock = 1;
+
+my $reads = 0;
+my $writes = 0;
+
+sub parse_test_config {
+    my ($raw) = @_;
+
+    my $conf = { snapshots => {} };
+    my $section = $conf;
+    for my $line (split(/\n/, $raw)) {
+        next if $line =~ m/^\s*$/;
+        if ($line =~ m/^\[([^\]]+)\]$/) {
+            $section = $conf->{snapshots}->{$1} = {};
+        } elsif ($line =~ m/^([a-z][a-z0-9_\-]*):\s*(.*?)\s*$/) {
+            $section->{$1} = $2;
+        } else {
+            die "test error: unable to parse config line '$line'\n";
+        }
+    }
+
+    return $conf;
+}
+
+sub write_test_config {
+    my ($conf) = @_;
+
+    my $print_section = sub {
+        my ($section) = @_;
+        return join('',
+            map { "$_: $section->{$_}\n" } grep { !ref($section->{$_}) } sort keys %$section);
+    };
+
+    my $raw = $print_section->($conf);
+    for my $snapname (sort keys(($conf->{snapshots} // {})->%*)) {
+        $raw .= "\n[$snapname]\n" . $print_section->($conf->{snapshots}->{$snapname});
+    }
+
+    return $raw;
+}
+
+sub vmid_of_path {
+    my ($path) = @_;
+    return $path =~ m!/(\d+)\.conf$! ? $1 : die "test error: unexpected path '$path'\n";
+}
+
+sub identity_lock_held {
+    my ($vmid) = @_;
+
+    open(my $fh, '>>', "$PVE::GuestHelpers::lockdir/pve-guest-identity-$vmid") or return 0;
+    my $free = flock($fh, LOCK_EX | LOCK_NB);
+    close($fh);
+
+    return !$free;
+}
+
+my $cluster_module = Test::MockModule->new('PVE::Cluster');
+$cluster_module->redefine(
+    cfs_update => sub {
+        $seen_versions = { $versions->%* };
+        return;
+    },
+    cfs_read_file => sub {
+        my ($path) = @_;
+        my $version = $seen_versions->{$path};
+        my $entry = $cache->{$path};
+        if (!$entry || !$entry->{version} || !$version || $entry->{version} != $version) {
+            my $raw = $files->{$path};
+            my $data = defined($raw) ? parse_test_config($raw) : undef;
+            $entry = $cache->{$path} = { version => $version, data => $data };
+        }
+        return defined($entry->{data}) ? dclone($entry->{data}) : undef;
+    },
+    cfs_write_file => sub {
+        my ($path, $conf) = @_;
+        my $vmid = vmid_of_path($path);
+        die "test error: config of $vmid written without identity lock\n"
+            if $check_identity_lock && !identity_lock_held($vmid);
+        $writes++;
+        $files->{$path} = write_test_config($conf);
+        $versions->{$path} = ++$version_counter;
+        $cache->{$path}->{version} = undef if $cache->{$path};
+    },
+    get_config => sub {
+        my ($path) = @_;
+        my $vmid = vmid_of_path($path);
+        die "test error: config of $vmid read without identity lock\n"
+            if !identity_lock_held($vmid);
+        die $get_config_error if $get_config_error;
+        $reads++;
+        return $files->{$path};
+    },
+);
+
+# deterministic identities: uids count up, the time is set by the tests
+
+my $uid_counter = 0;
+my $now = 1_700_000_000_000;
+
+my $identity_module = Test::MockModule->new('PVE::GuestIdentity');
+$identity_module->redefine(
+    __random_bytes => sub {
+        my ($len) = @_;
+        return pack('N', ++$uid_counter) . ("\0" x ($len - 4));
+    },
+    __time_ms => sub { return $now; },
+);
+
+my sub new_uid {
+    return PVE::GuestIdentity::new_identity()->{uid};
+}
+
+my sub file_of {
+    my ($class, $vmid) = @_;
+    return $files->{ $class->cfs_config_path($vmid) };
+}
+
+my sub conf_of {
+    my ($class, $vmid) = @_;
+    my $raw = file_of($class, $vmid);
+    return defined($raw) ? parse_test_config($raw) : undef;
+}
+
+my sub identity_of {
+    my ($class, $vmid) = @_;
+    my $conf = conf_of($class, $vmid) or return undef;
+    return PVE::GuestIdentity::parse_identity($conf->{meta});
+}
+
+# write of another process, the file cache of this process does not notice it
+my sub set_file {
+    my ($class, $vmid, $raw) = @_;
+    my $path = $class->cfs_config_path($vmid);
+    $files->{$path} = $raw;
+    $versions->{$path} = ++$version_counter;
+}
+
+my $foreign_uid = new_uid();
+
+subtest 'disabled by default' => sub {
+    ok(!PVE::AbstractConfig->__identity_enabled(), 'abstract config does not enable it');
+
+    local $check_identity_lock = 0;
+    my $class = 'PVE::TestConfig::NoIdentity';
+    my $reads_before = $reads;
+
+    my $res = [$class->write_config(100, { name => 'a' })];
+    is(file_of($class, 100), "name: a\n", 'config without identity written as is');
+    is_deeply($res, [], 'nothing is returned');
+
+    my $meta = "ctime=1,rtime=5,uid=$foreign_uid";
+    $class->write_config(100, { name => 'a', meta => $meta });
+    is(file_of($class, 100), "meta: $meta\nname: a\n", 'carried identity written as is');
+
+    is($reads, $reads_before, 'published identity is not read');
+};
+
+subtest 'none published' => sub {
+    my $class = 'PVE::TestConfig';
+
+    my $conf = { name => 'new' };
+    my $res = [$class->write_config(101, $conf)];
+    my $identity = identity_of($class, 101);
+    ok($identity, 'new config gets an identity');
+    is($identity->{rtime}, $now, 'rtime is the current time');
+    is_deeply($class->get_identity($conf), $identity, 'identity is set in the written hash');
+    is_deeply($res, [], 'nothing is returned');
+
+    # copied from a clone source, a snapshot, or a backup
+    $class->write_config(102, { name => 'clone', meta => "ctime=7,rtime=5,uid=$foreign_uid" });
+    $identity = identity_of($class, 102);
+    isnt($identity->{uid}, $foreign_uid, 'carried identity is not published');
+    is($identity->{rtime}, $now, 'carried rtime is not published');
+    like(
+        file_of($class, 102),
+        qr/^meta: ctime=7,rtime=$now,uid=[a-z2-7]{20}$/m,
+        'other members are kept',
+    );
+
+    set_file($class, 103, "meta: ctime=1\nname: old\n");
+    $class->write_config(103, conf_of($class, 103));
+    $identity = identity_of($class, 103);
+    ok($identity, 'existing config without identity gets one');
+    like(file_of($class, 103), qr/^meta: ctime=1,rtime=$now,uid=/m, 'other members are kept');
+
+    set_file($class, 104, "name: old\n\n[snap]\nmeta: rtime=1,uid=$foreign_uid\n");
+    $class->write_config(104, conf_of($class, 104));
+    isnt(identity_of($class, 104)->{uid}, $foreign_uid, 'identity of a snapshot is ignored');
+    like(
+        file_of($class, 104),
+        qr/^\[snap\]\nmeta: rtime=1,uid=$foreign_uid$/m,
+        'snapshot keeps its copy',
+    );
+
+    set_file($class, 105, '');
+    $class->write_config(105, { name => 'empty' });
+    ok(identity_of($class, 105), 'existing empty config gets an identity');
+};
+
+subtest 'published identity wins' => sub {
+    my $class = 'PVE::TestConfig';
+
+    $class->write_config(110, { name => 'a', meta => 'ctime=1' });
+    my $published = identity_of($class, 110);
+    my $stale = new_uid();
+
+    $now += 1000;
+
+    my $tests = [
+        [{ name => 'b' }, 'missing identity'],
+        [{ name => 'b', meta => 'ctime=1' }, 'missing identity members'],
+        [{ name => 'b', meta => "ctime=1,rtime=5,uid=$stale" }, 'stale identity'],
+        [{ name => 'b', meta => "ctime=1,rtime=$now,uid=$foreign_uid" }, 'foreign identity'],
+        [{ name => 'b', meta => "ctime=1,rtime=5,uid=bogus" }, 'invalid identity'],
+        [{ name => 'b', meta => "ctime=1,uid=$published->{uid}" }, 'identity without rtime'],
+    ];
+
+    for my $test (@$tests) {
+        my ($conf, $name) = @$test;
+        my $other_members = $conf->{meta} && $conf->{meta} =~ m/ctime=1/;
+
+        $class->write_config(110, $conf);
+        is_deeply(identity_of($class, 110), $published, "$name: published identity is kept");
+        is_deeply($class->get_identity($conf), $published, "$name: hash has it too");
+        like(file_of($class, 110), qr/^meta: ctime=1,/m, "$name: other members are kept")
+            if $other_members;
+    }
+
+    set_file($class, 111, "meta: ctime=1,uid=$stale\nname: old\n");
+    $class->write_config(111, conf_of($class, 111));
+    is_deeply(
+        identity_of($class, 111),
+        { uid => $stale, rtime => $now },
+        'published uid without rtime is kept and gets the current time',
+    );
+
+    my ($first, $last) = (new_uid(), new_uid());
+    set_file($class, 112, "meta: rtime=1,uid=$first\nname: x\nmeta: rtime=2,uid=$last\n");
+    $class->write_config(112, { name => 'y' });
+    is_deeply(
+        identity_of($class, 112),
+        { uid => $last, rtime => 2 },
+        'last top-level meta line counts, like for the config parsers',
+    );
+};
+
+subtest 'read and write under identity lock' => sub {
+    my $class = 'PVE::TestConfig';
+
+    # the cluster filesystem mocks die without the lock, the lock is gone afterwards
+    $class->write_config(120, { name => 'a' });
+    ok(identity_of($class, 120), 'written');
+    ok(!identity_lock_held(120), 'lock is released');
+
+    $class->lock_config(120, sub { $class->write_config(120, conf_of($class, 120)) });
+    ok(!identity_lock_held(120), 'lock is released when nested in config lock');
+};
+
+subtest 'read errors are fatal' => sub {
+    my $class = 'PVE::TestConfig';
+
+    $class->write_config(130, { name => 'a' });
+    my $raw = file_of($class, 130);
+
+    {
+        local $get_config_error = "Connection refused\n";
+        eval { $class->write_config(130, { name => 'b' }) };
+        is($@, "Connection refused\n", 'write dies');
+        is(file_of($class, 130), $raw, 'config is unchanged');
+
+        eval { $class->write_config(131, { name => 'b' }) };
+        is($@, "Connection refused\n", 'write of new config dies');
+        ok(!defined(file_of($class, 131)), 'config is not written');
+    }
+
+    # the read reports a missing file, but the mounted filesystem has it
+    my $path = $class->config_file(132);
+    make_path($path =~ s!/[^/]+$!!r);
+    open(my $fh, '>', $path) or die "unable to create '$path' - $!\n";
+    close($fh);
+    eval { $class->write_config(132, { name => 'b' }) };
+    like(
+        $@,
+        qr/^unable to read config file '\Q$path\E'/,
+        'inconsistent missing file is an error',
+    );
+    ok(!defined(file_of($class, 132)), 'config is not written');
+
+    # the read reports an empty file, but the mounted filesystem has content
+    set_file($class, 133, '');
+    $path = $class->config_file(133);
+    open($fh, '>', $path) or die "unable to create '$path' - $!\n";
+    print $fh "name: a\n";
+    close($fh);
+    eval { $class->write_config(133, { name => 'b' }) };
+    like(
+        $@,
+        qr/^unable to read config file '\Q$path\E'/,
+        'inconsistent empty file is an error',
+    );
+    is(file_of($class, 133), '', 'config is not written');
+
+    # empty for both, a config without identity
+    set_file($class, 134, '');
+    $path = $class->config_file(134);
+    open($fh, '>', $path) or die "unable to create '$path' - $!\n";
+    close($fh);
+    $class->write_config(134, { name => 'b' });
+    ok(identity_of($class, 134), 'empty file gets an identity');
+
+    # the mounted filesystem cannot be checked either, like while pmxcfs restarts
+    my $not_a_dir = "$tmpdir/not-a-dir";
+    open($fh, '>', $not_a_dir) or die "unable to create '$not_a_dir' - $!\n";
+    close($fh);
+    my $config_module = Test::MockModule->new('PVE::TestConfig', no_auto => 1);
+    $config_module->redefine(config_file => sub { return "$not_a_dir/$_[1].conf"; });
+
+    eval { $class->write_config(135, { name => 'b' }) };
+    like(
+        $@,
+        qr/^unable to check config file '\Q$not_a_dir\E\/135\.conf' for its guest identity - /,
+        'missing file that cannot be checked is an error',
+    );
+    ok(!defined(file_of($class, 135)), 'config is not written');
+
+    set_file($class, 136, '');
+    eval { $class->write_config(136, { name => 'b' }) };
+    like(
+        $@,
+        qr/^unable to check config file '\Q$not_a_dir\E\/136\.conf' for its guest identity - /,
+        'empty file that cannot be checked is an error',
+    );
+    is(file_of($class, 136), '', 'config is not written');
+};
+
+subtest 'snapshot rollback' => sub {
+    my $class = 'PVE::TestConfig';
+
+    my $storage_module = Test::MockModule->new('PVE::Storage');
+    $storage_module->redefine(config => sub { return {}; });
+    my $replication_module = Test::MockModule->new('PVE::ReplicationConfig');
+    $replication_module->redefine(
+        new => sub { return bless({}, 'PVE::ReplicationConfig'); },
+        check_for_existing_jobs => sub { return 0; },
+    );
+
+    $class->write_config(140, { name => 'current', meta => 'ctime=2' });
+    my $published = identity_of($class, 140);
+
+    my $conf = conf_of($class, 140);
+    $conf->{snapshots}->{old} = { name => 'old', meta => "ctime=1,rtime=5,uid=$foreign_uid" };
+    $conf->{snapshots}->{none} = { name => 'none' };
+    $class->write_config(140, $conf);
+
+    $now += 1000;
+
+    for my $snapname (qw(old none)) {
+        $class->snapshot_rollback(140, $snapname);
+        $conf = conf_of($class, 140);
+        is($conf->{name}, $snapname, "rolled back to '$snapname'");
+        is_deeply(identity_of($class, 140), $published,
+            "'$snapname': current identity is kept");
+    }
+    is(
+        $conf->{snapshots}->{old}->{meta},
+        "ctime=1,rtime=5,uid=$foreign_uid",
+        'snapshot is unchanged',
+    );
+};
+
+subtest 'overridden lock and published identity read' => sub {
+    my $class = 'PVE::TestConfig::Seams';
+    local $check_identity_lock = 0;
+    my $reads_before = $reads;
+
+    $class->write_config(160, { name => 'a', meta => "rtime=5,uid=$foreign_uid" });
+    my $identity = identity_of($class, 160);
+    isnt($identity->{uid}, $foreign_uid, 'nothing published: new identity');
+
+    local $PVE::TestConfig::Seams::published->{161} = { identity => $identity };
+    $class->write_config(161, { name => 'b' });
+    is_deeply(identity_of($class, 161), $identity, 'published identity is kept');
+
+    is($reads, $reads_before, 'cluster filesystem is not read');
+    ok(!-e "$PVE::GuestHelpers::lockdir/pve-guest-identity-160", 'no lock file is used');
+};
+
+done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH guest-common 10/34] abstract config: let the VMID reservation return the previous state
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (8 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH guest-common 09/34] abstract config: assign a guest identity and keep it on config writes Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH guest-common 11/34] guest identity: allow taking over a uid that is unused in the cluster Thomas Lamprecht
                   ` (25 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

A restore needs to know whether its target existed and had an identity
before the operation, to decide between keeping the identity of the
target and taking over the uid of the backup. With identities enabled,
the reservation already assigns an identity to a target without one,
so reading the config afterwards cannot tell anymore, and reading it
before the locked section races with other writers.

Return that state from within the locked section, together with the
identity that the reservation wrote, so that taking over the uid of
the backup later replaces only that identity. With identities enabled,
the reservation reads the existing identity under the same lock as the
write. A config that fails to parse still counts as existing, with the
identity found in its raw text.

Existing callers ignore the return value.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/AbstractConfig.pm          |  41 ++++++++++-
 src/tests/config-identity-tests.pl | 105 +++++++++++++++++++++++++++++
 2 files changed, 143 insertions(+), 3 deletions(-)

diff --git a/src/PVE/AbstractConfig.pm b/src/PVE/AbstractConfig.pm
index e78b8cc..fbcc930 100644
--- a/src/PVE/AbstractConfig.pm
+++ b/src/PVE/AbstractConfig.pm
@@ -361,19 +361,54 @@ sub load_current_config {
     return $conf;
 }
 
+# Reserves $vmid for an operation by writing its config with the lock $lock, 'create' by default.
+# An existing config is only allowed with $allow_existing and must not be locked.
+#
+# Returns the state of the guest identity around the write, captured under the guest config lock,
+# as the write can assign an identity to a config without one. PVE::GuestIdentity::adopt needs it.
+#   existed  - whether a config existed before
+#   identity - the guest identity of that config, undef if it had none or did not exist
+#   reserved - the guest identity published by the write, undef with identities disabled
 sub create_and_lock_config {
     my ($class, $vmid, $allow_existing, $lock) = @_;
 
-    $class->lock_config_full(
+    return $class->lock_config_full(
         $vmid,
         5,
         sub {
             PVE::Cluster::check_vmid_unused($vmid, $allow_existing);
 
-            my $conf = eval { $class->load_config($vmid) } || {};
+            my $conf = eval { $class->load_config($vmid) };
+            my $state = {
+                existed => defined($conf) ? 1 : 0,
+                identity => defined($conf) ? $class->__identity_get($conf) : undef,
+                reserved => undef,
+            };
+
+            $conf //= {};
             $class->check_lock($conf);
             $conf->{lock} = $lock // 'create';
-            $class->write_config($vmid, $conf);
+
+            if (!$class->__identity_enabled()) {
+                $class->write_config($vmid, $conf);
+                return $state;
+            }
+
+            # use what the write itself sees as published, see write_config
+            $class->__identity_lock(
+                $vmid,
+                sub {
+                    my $published = $class->__identity_read_published($vmid);
+                    $class->write_config($vmid, $conf);
+                    $state = {
+                        existed => defined($published) ? 1 : 0,
+                        identity => $published && $published->{identity},
+                        reserved => $class->__identity_get($conf),
+                    };
+                },
+            );
+
+            return $state;
         },
     );
 }
diff --git a/src/tests/config-identity-tests.pl b/src/tests/config-identity-tests.pl
index 92864ca..8bcc9d8 100755
--- a/src/tests/config-identity-tests.pl
+++ b/src/tests/config-identity-tests.pl
@@ -181,6 +181,12 @@ $cluster_module->redefine(
         $versions->{$path} = ++$version_counter;
         $cache->{$path}->{version} = undef if $cache->{$path};
     },
+    check_vmid_unused => sub {
+        my ($vmid, $noerr) = @_;
+        return 1 if !grep { defined($files->{$_}) && vmid_of_path($_) == $vmid } keys %$files;
+        return undef if $noerr;
+        die "guest $vmid already exists\n";
+    },
     get_config => sub {
         my ($path) = @_;
         my $vmid = vmid_of_path($path);
@@ -485,4 +491,103 @@ subtest 'overridden lock and published identity read' => sub {
     ok(!-e "$PVE::GuestHelpers::lockdir/pve-guest-identity-160", 'no lock file is used');
 };
 
+subtest 'create and lock config' => sub {
+    my $class = 'PVE::TestConfig';
+
+    my $state = $class->create_and_lock_config(150);
+    my $reserved = identity_of($class, 150);
+    ok($reserved, 'free VMID: reservation gets an identity');
+    is_deeply(
+        $state,
+        { existed => 0, identity => undef, reserved => $reserved },
+        'free VMID: no previous identity',
+    );
+    is(conf_of($class, 150)->{lock}, 'create', 'free VMID: reserved');
+
+    eval { $class->create_and_lock_config(150) };
+    like($@, qr/already exists/, 'existing config is refused by default');
+
+    $class->write_config(151, { name => 'target', meta => 'ctime=1' });
+    my $published = identity_of($class, 151);
+    $now += 1000;
+    $state = $class->create_and_lock_config(151, 1, 'restore');
+    is_deeply(
+        $state,
+        { existed => 1, identity => $published, reserved => $published },
+        'in place: previous identity',
+    );
+    my $conf = conf_of($class, 151);
+    is($conf->{lock}, 'restore', 'in place: locked');
+    is($conf->{name}, 'target', 'in place: config is kept');
+    is_deeply(identity_of($class, 151), $published, 'in place: identity is kept');
+
+    eval { $class->create_and_lock_config(151, 1) };
+    like($@, qr/^VM is locked \(restore\)/, 'locked config is refused');
+
+    set_file($class, 152, "meta: ctime=1\nname: old\n");
+    $state = $class->create_and_lock_config(152, 1);
+    is_deeply(
+        $state,
+        { existed => 1, identity => undef, reserved => identity_of($class, 152) },
+        'in place without identity: reservation gets one',
+    );
+    ok($state->{reserved}, 'in place without identity: reserved identity');
+
+    set_file($class, 157, '');
+    $state = $class->create_and_lock_config(157, 1);
+    is_deeply(
+        $state,
+        { existed => 1, identity => undef, reserved => identity_of($class, 157) },
+        'in place with empty config: reservation gets an identity',
+    );
+    ok($state->{reserved}, 'in place with empty config: reserved identity');
+
+    set_file($class, 156, "meta: rtime=5,uid=$foreign_uid\n!unparsable\n");
+    $state = $class->create_and_lock_config(156, 1);
+    my $kept = { uid => $foreign_uid, rtime => 5 };
+    is_deeply(
+        $state,
+        { existed => 1, identity => $kept, reserved => $kept },
+        'in place, config fails to load: published identity',
+    );
+    is_deeply(
+        identity_of($class, 156),
+        $kept,
+        'in place, config fails to load: identity is kept',
+    );
+
+    # clone: the target's first write must not publish the source's identity
+    $state = $class->create_and_lock_config(153);
+    $conf = conf_of($class, 151);
+    delete $conf->{lock};
+    $class->write_config(153, $conf);
+    is_deeply(identity_of($class, 153), $state->{reserved},
+        'clone keeps the reserved identity');
+    like(file_of($class, 153), qr/^meta: ctime=1,/m, 'clone keeps other members of the source');
+
+    local $check_identity_lock = 0;
+    $class = 'PVE::TestConfig::NoIdentity';
+
+    $state = $class->create_and_lock_config(154);
+    is_deeply(
+        $state,
+        { existed => 0, identity => undef, reserved => undef },
+        'disabled, free VMID: no previous identity',
+    );
+    is(file_of($class, 154), "lock: create\n", 'disabled, free VMID: no identity assigned');
+
+    set_file($class, 155, "meta: ctime=1,rtime=5,uid=$foreign_uid\nname: old\n");
+    $state = $class->create_and_lock_config(155, 1);
+    is_deeply(
+        $state,
+        { existed => 1, identity => { uid => $foreign_uid, rtime => 5 }, reserved => undef },
+        'disabled, in place: identity from the config',
+    );
+    is(
+        file_of($class, 155),
+        "lock: create\nmeta: ctime=1,rtime=5,uid=$foreign_uid\nname: old\n",
+        'disabled, in place: config is kept',
+    );
+};
+
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH guest-common 11/34] guest identity: allow taking over a uid that is unused in the cluster
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (9 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH guest-common 10/34] abstract config: let the VMID reservation return the previous state Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-17 13:14   ` Dominik Csapak
  2026-11-16  0:46 ` [PATCH qemu-server 12/34] api: restore: release the VMID if a restore to an unused VMID fails Thomas Lamprecht
                   ` (24 subsequent siblings)
  35 siblings, 1 reply; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Restores and remote migrations should keep the uid of the backup or of
the source guest, but must not duplicate it within the cluster. Config
writes keep the identity a guest already has, so provide a separate
step that takes over a uid after the final config write of the
operation.

The step checks the top-level 'meta' property of all guests and writes
the uid under a cluster-wide lock shared by VMs and containers. A guest
that had an identity before the operation keeps it. Otherwise, the step
only replaces the identity that the reservation of the operation
assigned, and checks right before writing that the guest still has
that identity.

An operation that fails or gets aborted can leave a guest behind with
the identity of its reservation. So the operation records the uid it
wants to take over as a pending change of 'meta'. A retry over such a
guest takes the pending uid over if it matches, under the same
cluster-wide check. A pending uid does not count as in use, so a retry
at another VMID stays possible.

The step removes the pending uid once it decided on an outcome. If the
cluster-wide lock cannot be taken, the pending uid stays for a later
operation. Removing it keeps the identity of the guest, even if the
'meta' property could not be parsed in full. The config view with
pending changes applied shows the identity of the guest, while the list
of pending changes still shows the pending uid.

Taking over the uid a guest already has leaves its registration time
unchanged. Both guest types use the same messages for the outcome. The
source of a remote migration only warns about an outcome it does not
know, as a newer target could report one, because the target accepted
the config at that point.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/AbstractConfig.pm          |  85 ++++-
 src/PVE/GuestIdentity.pm           | 187 ++++++++++-
 src/tests/config-identity-tests.pl | 513 ++++++++++++++++++++++++++++-
 src/tests/guest-identity-tests.pl  | 130 ++++++++
 4 files changed, 904 insertions(+), 11 deletions(-)

diff --git a/src/PVE/AbstractConfig.pm b/src/PVE/AbstractConfig.pm
index fbcc930..7eb8eb5 100644
--- a/src/PVE/AbstractConfig.pm
+++ b/src/PVE/AbstractConfig.pm
@@ -149,7 +149,7 @@ sub __identity_read_published {
 #
 # With guest identities enabled for the class, the identity published in the existing config file
 # gets set in $conf, whatever $conf contains, or a new one if none is published. So a config write
-# never changes a published identity.
+# never changes a published identity, only PVE::GuestIdentity::adopt does.
 sub write_config {
     my ($class, $vmid, $conf) = @_;
 
@@ -179,6 +179,78 @@ sub write_config {
     return;
 }
 
+# Replaces the published identity of the config of $vmid with $identity, but only if the published
+# uid is $expected_uid, and removes its pending uid in the same write. Returns a hash with
+# 'replaced' and 'uid', the uid published afterwards. Only for PVE::GuestIdentity::adopt, which
+# checks that no other guest has the uid.
+sub __identity_replace {
+    my ($class, $vmid, $expected_uid, $identity) = @_;
+
+    die "guest identities are not enabled for this guest type\n" if !$class->__identity_enabled();
+
+    return $class->__identity_lock(
+        $vmid,
+        sub {
+            my $published = $class->__identity_read_published($vmid);
+            die "Configuration file '" . $class->cfs_config_path($vmid) . "' does not exist\n"
+                if !defined($published);
+
+            my $uid = $published->{identity} && $published->{identity}->{uid};
+            return { replaced => 0, uid => $uid } if !defined($uid) || $uid ne $expected_uid;
+
+            # the file cache only notices writes of other processes after an update
+            PVE::Cluster::cfs_update();
+            my $conf = $class->load_config($vmid);
+
+            $class->__identity_set($conf, $identity);
+            PVE::GuestIdentity::set_pending_uid($conf, undef);
+            PVE::Cluster::cfs_write_file($class->cfs_config_path($vmid), $conf);
+
+            return { replaced => 1, uid => $identity->{uid} };
+        },
+    );
+}
+
+# Removes the pending uid from the config of $vmid, if it has one. Only for
+# PVE::GuestIdentity::adopt.
+sub __identity_clear_pending {
+    my ($class, $vmid) = @_;
+
+    $class->__identity_lock(
+        $vmid,
+        sub {
+            return if !defined($class->__identity_read_published($vmid));
+
+            # the file cache only notices writes of other processes after an update
+            PVE::Cluster::cfs_update();
+            my $conf = $class->load_config($vmid);
+            return if !defined(PVE::GuestIdentity::get_pending_uid($conf));
+
+            PVE::GuestIdentity::set_pending_uid($conf, undef);
+            # the parsed config lacks the published identity if the parser could not read the
+            # 'meta' property, but write_config puts it back
+            $class->write_config($vmid, $conf);
+        },
+    );
+
+    return;
+}
+
+# Writes $uid as pending uid into the config of $vmid, keeping everything else, see
+# PVE::GuestIdentity::set_pending_uid. The caller must hold the config lock.
+sub record_pending_uid {
+    my ($class, $vmid, $uid) = @_;
+
+    # the file cache only notices writes of other processes after an update
+    PVE::Cluster::cfs_update();
+    my $conf = $class->load_config($vmid);
+
+    PVE::GuestIdentity::set_pending_uid($conf, $uid);
+    $class->write_config($vmid, $conf);
+
+    return;
+}
+
 # Pending changes related
 
 sub parse_pending_delete {
@@ -343,14 +415,19 @@ sub load_current_config {
 
     # take pending changes in
     if (!$current) {
+        # a guest type with identities never applies a pending change of 'meta', which can hold
+        # the pending uid, see PVE::GuestIdentity::set_pending_uid
+        my $skip = $class->__identity_enabled() ? { meta => 1 } : {};
+
         foreach my $opt (keys %{ $conf->{pending} }) {
-            next if $opt eq 'delete';
+            next if $opt eq 'delete' || $skip->{$opt};
             my $value = $conf->{pending}->{$opt};
             next if ref($value); # just to be sure
             $conf->{$opt} = $value;
         }
         my $pending_delete_hash = $class->parse_pending_delete($conf->{pending}->{delete});
         foreach my $opt (keys %$pending_delete_hash) {
+            next if $skip->{$opt};
             delete $conf->{$opt} if $conf->{$opt};
         }
     }
@@ -368,6 +445,7 @@ sub load_current_config {
 # as the write can assign an identity to a config without one. PVE::GuestIdentity::adopt needs it.
 #   existed  - whether a config existed before
 #   identity - the guest identity of that config, undef if it had none or did not exist
+#   pending  - the pending uid of that config, see PVE::GuestIdentity::set_pending_uid
 #   reserved - the guest identity published by the write, undef with identities disabled
 sub create_and_lock_config {
     my ($class, $vmid, $allow_existing, $lock) = @_;
@@ -379,9 +457,11 @@ sub create_and_lock_config {
             PVE::Cluster::check_vmid_unused($vmid, $allow_existing);
 
             my $conf = eval { $class->load_config($vmid) };
+            my $pending = defined($conf) ? PVE::GuestIdentity::get_pending_uid($conf) : undef;
             my $state = {
                 existed => defined($conf) ? 1 : 0,
                 identity => defined($conf) ? $class->__identity_get($conf) : undef,
+                pending => $pending,
                 reserved => undef,
             };
 
@@ -403,6 +483,7 @@ sub create_and_lock_config {
                     $state = {
                         existed => defined($published) ? 1 : 0,
                         identity => $published && $published->{identity},
+                        pending => $pending,
                         reserved => $class->__identity_get($conf),
                     };
                 },
diff --git a/src/PVE/GuestIdentity.pm b/src/PVE/GuestIdentity.pm
index 44c9a1f..4886764 100644
--- a/src/PVE/GuestIdentity.pm
+++ b/src/PVE/GuestIdentity.pm
@@ -83,7 +83,8 @@ sub meta_format_properties {
             description =>
                 "Random identifier of the guest lineage. Restores and migrations from other"
                 . " clusters keep it, unless another guest in the cluster already uses it, the"
-                . " restore sets 'unique', or the restore target already has a uid of its own.",
+                . " restore sets 'unique', or the restore overwrites a guest that has its own uid"
+                . " and is not left over from an unfinished restore of the same backup.",
             optional => 1,
         },
         rtime => {
@@ -161,6 +162,190 @@ sub merge_identity {
     return join(',', @plain, map { $_->[1] } sort { $a->[0] cmp $b->[0] } @members);
 }
 
+# An operation that takes over a uid at its end, see adopt, keeps it in the config of the guest as
+# pending change of 'meta' with only the uid member until then. A guest that the operation leaves
+# behind after a failure or an abort thus still knows the uid, so that a retry of the operation can
+# take it over. A pending uid is never published: the check whether a uid is in use only looks at
+# the top-level section of guest configs, and only adopt can turn it into the uid of the guest.
+
+# Returns the pending uid in the parsed config $conf, undef if there is none.
+sub get_pending_uid {
+    my ($conf) = @_;
+
+    my $pending = $conf->{pending} && parse_identity($conf->{pending}->{meta});
+
+    return $pending && $pending->{uid};
+}
+
+# Sets $uid as pending uid in the parsed config $conf, replacing any pending change of 'meta', or
+# removes such a change if $uid is undef.
+sub set_pending_uid {
+    my ($conf, $uid) = @_;
+
+    if (defined($uid)) {
+        die "invalid guest identity uid '$uid'\n" if !is_valid_uid($uid);
+        $conf->{pending}->{meta} = "uid=$uid";
+    } elsif ($conf->{pending}) {
+        delete $conf->{pending}->{meta};
+    }
+
+    return;
+}
+
+# Returns $uid if adopt would try to publish it for the guest of the operation with the reservation
+# $reservation, which is the case if the guest had no identity before the operation, or $uid as
+# pending uid. Returns undef otherwise, or if $uid is undef. An operation keeps the uid it returns
+# as pending uid until it calls adopt.
+sub adoptable_uid {
+    my ($reservation, $uid) = @_;
+
+    return undef if !defined($uid) || !$reservation;
+    return $uid if !$reservation->{identity} || ($reservation->{pending} // '') eq $uid;
+
+    return undef;
+}
+
+# Returns whether $uid is the uid of the guest of the operation with the reservation $reservation,
+# published or pending, before the operation. A guest without identity matches any uid.
+sub uid_matches_target {
+    my ($reservation, $uid) = @_;
+
+    my $identity = $reservation->{identity};
+
+    return !$identity || $identity->{uid} eq $uid || ($reservation->{pending} // '') eq $uid;
+}
+
+my sub take_over {
+    my ($class, $vmid, $uid, $reservation) = @_;
+
+    my $result = sub {
+        my ($result, $current_uid, @extra) = @_;
+        return { result => $result, uid => $current_uid, requested => $uid, @extra };
+    };
+
+    my $previous = $reservation->{identity};
+    return $result->('kept', $previous->{uid}) if $previous && !adoptable_uid($reservation, $uid);
+
+    my $reserved_uid = $reservation->{reserved}->{uid};
+    return $result->('skipped', $reserved_uid) if !defined($uid);
+
+    # shared by all guest types, as they share the VMID and uid namespaces
+    my $res = PVE::Cluster::cfs_lock_domain(
+        'guest-identity',
+        undef,
+        sub {
+            my $metas = PVE::Cluster::get_guest_config_properties(['meta']);
+
+            my $current = parse_identity($metas->{$vmid} && $metas->{$vmid}->{meta});
+            if ($current && $current->{uid} eq $uid) {
+                # a uid without valid rtime can only come from a manual edit
+                $class->__identity_replace($vmid, $uid, new_identity($uid))
+                    if !defined($current->{rtime});
+                return $result->('kept', $uid);
+            }
+
+            for my $other (sort { $a <=> $b } keys %$metas) {
+                my $identity = parse_identity($metas->{$other}->{meta});
+                next if !$identity || $identity->{uid} ne $uid;
+
+                return $result->('in-use', $current && $current->{uid}, 'in-use-by' => $other);
+            }
+
+            my $replaced = $class->__identity_replace($vmid, $reserved_uid, new_identity($uid));
+            return $result->('changed', $replaced->{uid}) if !$replaced->{replaced};
+
+            return $result->('adopted', $uid);
+        },
+    );
+    die $@ if $@;
+
+    return $res;
+}
+
+# Publishes $uid, for example the one of a restored backup or of the source guest of a remote
+# migration, as the uid of the guest $vmid with the current time as rtime, where that is allowed.
+#
+# $class is the config class of the guest and must have guest identities enabled. $reservation is
+# what create_and_lock_config returned for the operation. The caller must still hold the config
+# lock of $vmid and call this after the final config write of the operation. $uid can be undef if
+# there is nothing to adopt, for example for a backup without uid.
+#
+# A guest that had an identity before the operation keeps it, unless it had $uid as pending uid,
+# see adoptable_uid. Otherwise, $uid only replaces the identity that the reservation published,
+# and only if no other guest in the cluster has it. Whatever the outcome, the pending uid of the
+# config is removed afterwards, as the operation is done.
+#
+# Dies if the cluster-wide identity lock cannot be taken, for example without quorum. The pending
+# uid then stays, as nothing got decided, so that a later operation can still take it over.
+#
+# Returns a hash with the keys 'result', 'uid' (the uid of $vmid afterwards), 'requested' ($uid)
+# and, for the result 'in-use', 'in-use-by' (the lowest VMID of the other guests with $uid). The
+# result is one of:
+#   kept    - the guest keeps the identity it had before the operation, or already has $uid
+#   adopted - $uid got published for $vmid
+#   in-use  - another guest has $uid, the identity of the reservation stays
+#   changed - the identity of the reservation is not published anymore, nothing got changed
+#   skipped - $uid is undef, the identity of the reservation stays
+sub adopt {
+    my ($class, $vmid, $uid, $reservation) = @_;
+
+    die "guest identities are not enabled for this guest type\n" if !$class->__identity_enabled();
+    die "missing guest identity reservation\n"
+        if ref($reservation) ne 'HASH' || !$reservation->{reserved};
+    die "invalid guest identity uid '$uid'\n" if defined($uid) && !is_valid_uid($uid);
+
+    my $res = take_over($class, $vmid, $uid, $reservation);
+
+    eval { $class->__identity_clear_pending($vmid) };
+    die "unable to remove the pending uid - $@" if $@;
+
+    return $res;
+}
+
+# Returns the task log line for the result $res of adopt(), so that all guest types use the same
+# wording. $origin is where the requested uid comes from, either 'backup' or 'source' for the
+# source guest of a remote migration.
+sub adopt_result_message {
+    my ($res, $origin) = @_;
+
+    my $origin_name = { backup => 'backup', source => 'source guest' }->{$origin}
+        // die "unknown origin of guest identity '$origin'\n";
+
+    my ($result, $requested) = $res->@{qw(result requested)};
+    my $uid = $res->{uid} // 'none';
+
+    if ($result eq 'kept') {
+        return "guest identity: kept uid $uid";
+    } elsif ($result eq 'adopted') {
+        return "guest identity: adopted uid $uid from the $origin_name";
+    } elsif ($result eq 'in-use') {
+        return "guest identity: $origin_name uid $requested is in use by guest"
+            . " $res->{'in-use-by'}, keeping uid $uid";
+    } elsif ($result eq 'changed') {
+        return "guest identity: uid changed during the operation, keeping uid $uid instead of"
+            . " adopting uid $requested from the $origin_name";
+    } elsif ($result eq 'skipped') {
+        return "guest identity: new uid $uid";
+    }
+
+    die "unknown result of guest identity adoption '$result'\n";
+}
+
+# Returns the log level and line for the result $res of adopt that the target of a remote migration
+# reported for the uid of the source guest. A target with a newer version can report results
+# unknown here, which only get a warning, as the target already took over the config by then.
+sub remote_adopt_result_log {
+    my ($res) = @_;
+
+    my $message = eval { adopt_result_message($res, 'source') };
+    if (my $err = $@) {
+        chomp($err);
+        return ('warn', $err);
+    }
+
+    return ('info', $message);
+}
+
 # Returns undef if $node runs a version of Proxmox VE that keeps the identity when writing guest
 # configs, see MIN_PVE_MANAGER_VERSION. Missing or invalid version information counts as too old.
 # Otherwise returns a hash with 'required-version', the minimum version, and 'version', the version
diff --git a/src/tests/config-identity-tests.pl b/src/tests/config-identity-tests.pl
index 8bcc9d8..7138053 100755
--- a/src/tests/config-identity-tests.pl
+++ b/src/tests/config-identity-tests.pl
@@ -99,9 +99,13 @@ my $cache = {};
 
 our $get_config_error;
 our $check_identity_lock = 1;
+our $lock_domain_error;
+our $domain_locked = 0;
+our $on_lookup;
 
 my $reads = 0;
 my $writes = 0;
+my $domain_writes = 0;
 
 sub parse_test_config {
     my ($raw) = @_;
@@ -110,7 +114,9 @@ sub parse_test_config {
     my $section = $conf;
     for my $line (split(/\n/, $raw)) {
         next if $line =~ m/^\s*$/;
-        if ($line =~ m/^\[([^\]]+)\]$/) {
+        if ($line =~ m/^\[PENDING\]$/) {
+            $section = $conf->{pending} = {};
+        } elsif ($line =~ m/^\[([^\]]+)\]$/) {
             $section = $conf->{snapshots}->{$1} = {};
         } elsif ($line =~ m/^([a-z][a-z0-9_\-]*):\s*(.*?)\s*$/) {
             $section->{$1} = $2;
@@ -132,6 +138,8 @@ sub write_test_config {
     };
 
     my $raw = $print_section->($conf);
+    $raw .= "\n[PENDING]\n" . $print_section->($conf->{pending})
+        if scalar(keys(($conf->{pending} // {})->%*));
     for my $snapname (sort keys(($conf->{snapshots} // {})->%*)) {
         $raw .= "\n[$snapname]\n" . $print_section->($conf->{snapshots}->{$snapname});
     }
@@ -177,6 +185,7 @@ $cluster_module->redefine(
         die "test error: config of $vmid written without identity lock\n"
             if $check_identity_lock && !identity_lock_held($vmid);
         $writes++;
+        $domain_writes++ if $domain_locked;
         $files->{$path} = write_test_config($conf);
         $versions->{$path} = ++$version_counter;
         $cache->{$path}->{version} = undef if $cache->{$path};
@@ -187,6 +196,37 @@ $cluster_module->redefine(
         return undef if $noerr;
         die "guest $vmid already exists\n";
     },
+    get_guest_config_properties => sub {
+        my ($properties, $vmid) = @_;
+        die "test error: unexpected arguments\n" if defined($vmid) || "@$properties" ne 'meta';
+
+        my $res = {};
+        for my $path (grep { defined($files->{$_}) } keys %$files) {
+            for my $line (split(/\n/, $files->{$path})) {
+                last if $line =~ m/^\[/;
+                $res->{ vmid_of_path($path) }->{meta} = $1 if $line =~ m/^meta:\s*(.*?)\s*$/;
+            }
+        }
+
+        $on_lookup->() if $on_lookup;
+
+        return $res;
+    },
+    cfs_lock_domain => sub {
+        my ($domain, $timeout, $code, @param) = @_;
+        die "test error: unexpected lock domain '$domain'\n" if $domain ne 'guest-identity';
+        die "test error: nested domain lock\n" if $domain_locked;
+
+        if ($lock_domain_error) {
+            $@ = $lock_domain_error;
+            return undef;
+        }
+
+        local $domain_locked = 1;
+        PVE::Cluster::cfs_update();
+        # like the real one, errors of $code are passed on in $@
+        return eval { $code->(@param) };
+    },
     get_config => sub {
         my ($path) = @_;
         my $vmid = vmid_of_path($path);
@@ -499,7 +539,7 @@ subtest 'create and lock config' => sub {
     ok($reserved, 'free VMID: reservation gets an identity');
     is_deeply(
         $state,
-        { existed => 0, identity => undef, reserved => $reserved },
+        { existed => 0, identity => undef, pending => undef, reserved => $reserved },
         'free VMID: no previous identity',
     );
     is(conf_of($class, 150)->{lock}, 'create', 'free VMID: reserved');
@@ -513,7 +553,7 @@ subtest 'create and lock config' => sub {
     $state = $class->create_and_lock_config(151, 1, 'restore');
     is_deeply(
         $state,
-        { existed => 1, identity => $published, reserved => $published },
+        { existed => 1, identity => $published, pending => undef, reserved => $published },
         'in place: previous identity',
     );
     my $conf = conf_of($class, 151);
@@ -528,7 +568,12 @@ subtest 'create and lock config' => sub {
     $state = $class->create_and_lock_config(152, 1);
     is_deeply(
         $state,
-        { existed => 1, identity => undef, reserved => identity_of($class, 152) },
+        {
+            existed => 1,
+            identity => undef,
+            pending => undef,
+            reserved => identity_of($class, 152),
+        },
         'in place without identity: reservation gets one',
     );
     ok($state->{reserved}, 'in place without identity: reserved identity');
@@ -537,7 +582,12 @@ subtest 'create and lock config' => sub {
     $state = $class->create_and_lock_config(157, 1);
     is_deeply(
         $state,
-        { existed => 1, identity => undef, reserved => identity_of($class, 157) },
+        {
+            existed => 1,
+            identity => undef,
+            pending => undef,
+            reserved => identity_of($class, 157),
+        },
         'in place with empty config: reservation gets an identity',
     );
     ok($state->{reserved}, 'in place with empty config: reserved identity');
@@ -547,7 +597,7 @@ subtest 'create and lock config' => sub {
     my $kept = { uid => $foreign_uid, rtime => 5 };
     is_deeply(
         $state,
-        { existed => 1, identity => $kept, reserved => $kept },
+        { existed => 1, identity => $kept, pending => undef, reserved => $kept },
         'in place, config fails to load: published identity',
     );
     is_deeply(
@@ -571,7 +621,7 @@ subtest 'create and lock config' => sub {
     $state = $class->create_and_lock_config(154);
     is_deeply(
         $state,
-        { existed => 0, identity => undef, reserved => undef },
+        { existed => 0, identity => undef, pending => undef, reserved => undef },
         'disabled, free VMID: no previous identity',
     );
     is(file_of($class, 154), "lock: create\n", 'disabled, free VMID: no identity assigned');
@@ -580,7 +630,12 @@ subtest 'create and lock config' => sub {
     $state = $class->create_and_lock_config(155, 1);
     is_deeply(
         $state,
-        { existed => 1, identity => { uid => $foreign_uid, rtime => 5 }, reserved => undef },
+        {
+            existed => 1,
+            identity => { uid => $foreign_uid, rtime => 5 },
+            pending => undef,
+            reserved => undef,
+        },
         'disabled, in place: identity from the config',
     );
     is(
@@ -590,4 +645,446 @@ subtest 'create and lock config' => sub {
     );
 };
 
+subtest 'adopt' => sub {
+    my $class = 'PVE::TestConfig';
+    my $ct_class = 'PVE::TestConfig::CT';
+
+    my $backup_uid = new_uid();
+
+    # restore to a free VMID, the final write carries the identity of the backup
+    my $reservation = $class->create_and_lock_config(200);
+    my $restored = { name => 'restored', meta => "ctime=1,rtime=5,uid=$backup_uid" };
+    $class->write_config(200, { $restored->%*, lock => 'create' });
+    my $generated = identity_of($class, 200);
+    is_deeply($generated, $reservation->{reserved}, 'final write keeps the reserved identity');
+
+    $now += 1000;
+    my $res = PVE::GuestIdentity::adopt($class, 200, $backup_uid, $reservation);
+    is_deeply(
+        $res,
+        { result => 'adopted', uid => $backup_uid, requested => $backup_uid },
+        'free uid is adopted',
+    );
+    is_deeply(
+        identity_of($class, 200),
+        { uid => $backup_uid, rtime => $now },
+        'adopted uid is published with the current time',
+    );
+    like(
+        file_of($class, 200),
+        qr/^meta: ctime=1,rtime=$now,uid=$backup_uid$/m,
+        'other members are kept',
+    );
+    is(conf_of($class, 200)->{lock}, 'create', 'rest of the config is kept');
+    is($domain_writes, 1, 'published under the cluster-wide lock');
+
+    my $adopted_rtime = $now;
+    $now += 1000;
+
+    my $stale = { $restored->%*, meta => "ctime=1,rtime=5,uid=$generated->{uid}" };
+    $class->write_config(200, $stale);
+    is_deeply(
+        identity_of($class, 200),
+        { uid => $backup_uid, rtime => $adopted_rtime },
+        'later write of a stale hash keeps the adopted identity',
+    );
+
+    my $writes_before = $writes;
+    $res = PVE::GuestIdentity::adopt($class, 200, $backup_uid, $reservation);
+    is_deeply(
+        $res,
+        { result => 'kept', uid => $backup_uid, requested => $backup_uid },
+        'repeated adoption keeps it',
+    );
+    is($writes, $writes_before, 'repeated adoption writes nothing');
+    is(identity_of($class, 200)->{rtime}, $adopted_rtime, 'repeated adoption keeps rtime');
+
+    set_file($class, 200, file_of($class, 200) =~ s/rtime=\d+,//r);
+    $res = PVE::GuestIdentity::adopt($class, 200, $backup_uid, $reservation);
+    is($res->{result}, 'kept', 'repeated adoption with manually removed rtime keeps it');
+    is_deeply(
+        identity_of($class, 200),
+        { uid => $backup_uid, rtime => $now },
+        'repeated adoption sets a missing rtime',
+    );
+
+    # restore in place onto a guest with identity
+    $class->write_config(210, { name => 'target' });
+    my $target = identity_of($class, 210);
+    $reservation = $class->create_and_lock_config(210, 1, 'restore');
+    my $other_uid = new_uid();
+    {
+        local $lock_domain_error = "test error: unexpected lock\n";
+        $res = PVE::GuestIdentity::adopt($class, 210, $other_uid, $reservation);
+    }
+    is_deeply(
+        $res,
+        { result => 'kept', uid => $target->{uid}, requested => $other_uid },
+        'in place: identity from before the operation is kept',
+    );
+    is_deeply(identity_of($class, 210), $target, 'in place: identity is unchanged');
+
+    set_file($class, 211, "meta: ctime=1\nname: old\n");
+    $reservation = $class->create_and_lock_config(211, 1);
+    $other_uid = new_uid();
+    $res = PVE::GuestIdentity::adopt($class, 211, $other_uid, $reservation);
+    is($res->{result}, 'adopted', 'in place without identity: uid is adopted');
+    is(identity_of($class, 211)->{uid}, $other_uid, 'in place without identity: published');
+
+    $reservation = $class->create_and_lock_config(212);
+    {
+        local $lock_domain_error = "test error: unexpected lock\n";
+        $res = PVE::GuestIdentity::adopt($class, 212, undef, $reservation);
+    }
+    is_deeply(
+        $res,
+        { result => 'skipped', uid => $reservation->{reserved}->{uid}, requested => undef },
+        'nothing to adopt',
+    );
+
+    # a wrong call must not replace an identity that the reservation did not publish
+    $class->write_config(213, { name => 'established' });
+    my $established = identity_of($class, 213);
+    my $wrong =
+        { existed => 0, identity => undef, reserved => PVE::GuestIdentity::new_identity() };
+    $other_uid = new_uid();
+    $writes_before = $writes;
+    $res = PVE::GuestIdentity::adopt($class, 213, $other_uid, $wrong);
+    is_deeply(
+        $res,
+        { result => 'changed', uid => $established->{uid}, requested => $other_uid },
+        'reservation of another identity: nothing adopted',
+    );
+    is_deeply(identity_of($class, 213), $established, 'established identity is kept');
+    is($writes, $writes_before, 'nothing is written');
+
+    $reservation = $class->create_and_lock_config(214);
+    my $recreated = new_uid();
+    set_file($class, 214, "meta: rtime=1,uid=$recreated\nname: recreated\n");
+    $res = PVE::GuestIdentity::adopt($class, 214, new_uid(), $reservation);
+    is($res->{result}, 'changed', 'config replaced since the reservation: nothing adopted');
+    is(identity_of($class, 214)->{uid}, $recreated, 'identity of the replaced config stays');
+
+    $reservation = $class->create_and_lock_config(201);
+    $class->write_config(201, { name => 'second restore', lock => 'create' });
+    my $second = identity_of($class, 201);
+    $writes_before = $writes;
+    $res = PVE::GuestIdentity::adopt($class, 201, $backup_uid, $reservation);
+    is_deeply(
+        $res,
+        {
+            result => 'in-use',
+            uid => $second->{uid},
+            requested => $backup_uid,
+            'in-use-by' => 200,
+        },
+        'uid of another VM is not adopted',
+    );
+    is_deeply(identity_of($class, 201), $second, 'reserved identity stays');
+    is($writes, $writes_before, 'nothing is written');
+
+    # manual copies of a config
+    my $copied_uid = new_uid();
+    set_file($class, 220, "meta: rtime=1,uid=$copied_uid\n");
+    set_file($ct_class, 205, "meta: rtime=1,uid=$copied_uid\n");
+    $res = PVE::GuestIdentity::adopt($class, 201, $copied_uid, $reservation);
+    is($res->{'in-use-by'}, 205, 'lowest VMID of several holders is reported');
+
+    my $ct_uid = new_uid();
+    my $ct_reservation = $ct_class->create_and_lock_config(300);
+    $res = PVE::GuestIdentity::adopt($ct_class, 300, $ct_uid, $ct_reservation);
+    is($res->{result}, 'adopted', 'container adopts a free uid');
+    like(file_of($ct_class, 300), qr/^meta: rtime=$now,uid=$ct_uid$/m, 'container config');
+
+    $res = PVE::GuestIdentity::adopt($class, 201, $ct_uid, $reservation);
+    is($res->{'in-use-by'}, 300, 'uid of a container is not adopted for a VM');
+
+    $ct_reservation = $ct_class->create_and_lock_config(301);
+    $res = PVE::GuestIdentity::adopt($ct_class, 301, $backup_uid, $ct_reservation);
+    is($res->{'in-use-by'}, 200, 'uid of a VM is not adopted for a container');
+
+    # another process writes the config after the cluster-wide lookup
+    $reservation = $class->create_and_lock_config(230);
+    $class->write_config(230, { name => 'restored', lock => 'create' });
+    PVE::Cluster::cfs_update();
+    $class->load_config(230);
+    {
+        local $on_lookup = sub {
+            set_file($class, 230, file_of($class, 230) =~ s/^name: .*$/name: hook/mr);
+        };
+        $res = PVE::GuestIdentity::adopt($class, 230, new_uid(), $reservation);
+    }
+    is($res->{result}, 'adopted', 'concurrent write: uid is adopted');
+    is(conf_of($class, 230)->{name}, 'hook', 'concurrent write: its change is kept');
+
+    $reservation = $class->create_and_lock_config(202);
+    my $before = identity_of($class, 202);
+    {
+        local $lock_domain_error = "cfs-lock 'domain-guest-identity' error: no quorum!\n";
+        eval { PVE::GuestIdentity::adopt($class, 202, new_uid(), $reservation) };
+        is($@, $lock_domain_error, 'lock error is passed on');
+        is_deeply(identity_of($class, 202), $before, 'lock error: identity is unchanged');
+    }
+
+    my $missing =
+        { existed => 0, identity => undef, reserved => PVE::GuestIdentity::new_identity() };
+    eval { PVE::GuestIdentity::adopt($class, 299, new_uid(), $missing) };
+    like($@, qr/does not exist/, 'missing config is an error');
+
+    eval { PVE::GuestIdentity::adopt($class, 202, 'GAYTEMZUGU3DOOBZMFRG', $reservation) };
+    like($@, qr/invalid guest identity uid/, 'invalid uid is refused');
+
+    for my $invalid (undef, {}, { existed => 0, identity => undef, reserved => undef }) {
+        eval { PVE::GuestIdentity::adopt($class, 202, new_uid(), $invalid) };
+        like($@, qr/missing guest identity reservation/, 'missing reservation is refused');
+    }
+
+    local $check_identity_lock = 0;
+    eval {
+        PVE::GuestIdentity::adopt('PVE::TestConfig::NoIdentity', 202, new_uid(), $reservation);
+    };
+    like($@, qr/not enabled/, 'guest type without identities is refused');
+};
+
+# like the guest that a failed operation leaves behind, with the lock removed by its error handling
+my sub unlock_config {
+    my ($class, $vmid) = @_;
+    my $conf = conf_of($class, $vmid);
+    delete $conf->{lock};
+    $class->write_config($vmid, $conf);
+}
+
+my sub pending_of {
+    my ($class, $vmid) = @_;
+    my $conf = conf_of($class, $vmid);
+    return $conf->{pending} && $conf->{pending}->{meta};
+}
+
+subtest 'pending uid' => sub {
+    my $class = 'PVE::TestConfig';
+
+    # a restore to a free VMID records the uid of the backup, then fails and leaves the guest
+    my $backup_uid = new_uid();
+    my $first = $class->create_and_lock_config(400);
+    my $leftover = $first->{reserved};
+    is(
+        PVE::GuestIdentity::adoptable_uid($first, $backup_uid),
+        $backup_uid,
+        'free VMID: adoptable',
+    );
+    $class->record_pending_uid(400, $backup_uid);
+    is(pending_of($class, 400), "uid=$backup_uid", 'pending uid is recorded');
+    is_deeply(identity_of($class, 400), $leftover, 'published identity is kept');
+    is(conf_of($class, 400)->{lock}, 'create', 'rest of the config is kept');
+    unlock_config($class, 400);
+    is(pending_of($class, 400), "uid=$backup_uid", 'write of the loaded config keeps it');
+
+    # a retry at another VMID takes over the uid, as a pending uid is not in use
+    my $elsewhere = $class->create_and_lock_config(401);
+    my $res = PVE::GuestIdentity::adopt($class, 401, $backup_uid, $elsewhere);
+    is($res->{result}, 'adopted',
+        'retry elsewhere: pending uid of another guest is not in use');
+    is(pending_of($class, 400), "uid=$backup_uid", 'retry elsewhere: leftover keeps it');
+
+    # a retry over the leftover is a restore of the same backup, but the uid is in use by now
+    my $retry = $class->create_and_lock_config(400, 1);
+    is_deeply(
+        $retry,
+        { existed => 1, identity => $leftover, pending => $backup_uid, reserved => $leftover },
+        'reservation reports the pending uid',
+    );
+    ok(PVE::GuestIdentity::uid_matches_target($retry, $backup_uid), 'pending uid matches');
+    ok(
+        PVE::GuestIdentity::uid_matches_target($retry, $leftover->{uid}),
+        'published uid matches',
+    );
+    ok(!PVE::GuestIdentity::uid_matches_target($retry, new_uid()), 'other uid does not match');
+    is(
+        PVE::GuestIdentity::adoptable_uid($retry, $backup_uid),
+        $backup_uid,
+        'pending: adoptable',
+    );
+    $res = PVE::GuestIdentity::adopt($class, 400, $backup_uid, $retry);
+    is_deeply(
+        $res,
+        {
+            result => 'in-use',
+            uid => $leftover->{uid},
+            requested => $backup_uid,
+            'in-use-by' => 401,
+        },
+        'retry in place after the retry elsewhere: in use',
+    );
+    is_deeply(identity_of($class, 400), $leftover, 'in use: identity is kept');
+    ok(!defined(pending_of($class, 400)), 'in use: pending uid is removed');
+
+    # a failed restore over a guest without identity, then retried in place
+    set_file($class, 410, "name: old\n");
+    $first = $class->create_and_lock_config(410, 1);
+    $backup_uid = new_uid();
+    is(
+        PVE::GuestIdentity::adoptable_uid($first, $backup_uid),
+        $backup_uid,
+        'no identity: adoptable',
+    );
+    $class->record_pending_uid(410, $backup_uid);
+    unlock_config($class, 410);
+
+    $retry = $class->create_and_lock_config(410, 1);
+    is($retry->{pending}, $backup_uid, 'retry in place: pending uid reported');
+    $class->write_config(
+        410,
+        { name => 'restored', lock => 'create', pending => { meta => "uid=$backup_uid" } },
+    );
+    $now += 1000;
+    my $writes_before = $writes;
+    $res = PVE::GuestIdentity::adopt($class, 410, $backup_uid, $retry);
+    is_deeply(
+        $res,
+        { result => 'adopted', uid => $backup_uid, requested => $backup_uid },
+        'retry in place: pending uid is adopted',
+    );
+    is_deeply(identity_of($class, 410), { uid => $backup_uid, rtime => $now }, 'published');
+    ok(!defined(pending_of($class, 410)), 'retry in place: pending uid is removed');
+    is($writes, $writes_before + 1, 'in the same write');
+    is(conf_of($class, 410)->{name}, 'restored', 'rest of the config is kept');
+
+    # the published uid changed since the reservation of the retry
+    set_file($class, 420, "name: old\n");
+    $first = $class->create_and_lock_config(420, 1);
+    $backup_uid = new_uid();
+    $class->record_pending_uid(420, $backup_uid);
+    unlock_config($class, 420);
+    $retry = $class->create_and_lock_config(420, 1);
+    my $replaced = new_uid();
+    set_file(
+        $class,
+        420,
+        "meta: rtime=1,uid=$replaced\nname: new\n\n[PENDING]\nmeta: uid=$backup_uid\n",
+    );
+    $res = PVE::GuestIdentity::adopt($class, 420, $backup_uid, $retry);
+    is($res->{result}, 'changed', 'published uid changed since the retry: not adopted');
+    is(identity_of($class, 420)->{uid}, $replaced, 'published uid changed: it stays');
+    ok(!defined(pending_of($class, 420)), 'published uid changed: pending uid is removed');
+
+    # an in-place restore of another backup keeps the identity, with a pending uid of the earlier
+    # backup
+    set_file($class, 430, "name: old\n");
+    $first = $class->create_and_lock_config(430, 1);
+    my $earlier_uid = new_uid();
+    $class->record_pending_uid(430, $earlier_uid);
+    unlock_config($class, 430);
+    $retry = $class->create_and_lock_config(430, 1);
+    my $target = identity_of($class, 430);
+    my $other_uid = new_uid();
+    ok(
+        !PVE::GuestIdentity::uid_matches_target($retry, $other_uid),
+        'other backup does not match',
+    );
+    ok(!defined(PVE::GuestIdentity::adoptable_uid($retry, $other_uid)), 'other backup: none');
+    {
+        local $lock_domain_error = "test error: unexpected lock\n";
+        $res = PVE::GuestIdentity::adopt($class, 430, $other_uid, $retry);
+    }
+    is($res->{result}, 'kept', 'other backup: identity is kept');
+    is_deeply(identity_of($class, 430), $target, 'other backup: identity is unchanged');
+    ok(!defined(pending_of($class, 430)), 'other backup: pending uid is removed');
+
+    # nothing to adopt, for example with 'unique'
+    $first = $class->create_and_lock_config(440);
+    $class->record_pending_uid(440, new_uid());
+    $res = PVE::GuestIdentity::adopt($class, 440, undef, $first);
+    is($res->{result}, 'skipped', 'nothing to adopt: skipped');
+    ok(!defined(pending_of($class, 440)), 'nothing to adopt: pending uid is removed');
+
+    # adopting fails
+    $first = $class->create_and_lock_config(450);
+    $backup_uid = new_uid();
+    $class->record_pending_uid(450, $backup_uid);
+    {
+        local $lock_domain_error = "cfs-lock 'domain-guest-identity' error: no quorum!\n";
+        eval { PVE::GuestIdentity::adopt($class, 450, $backup_uid, $first) };
+        is($@, $lock_domain_error, 'lock error is passed on');
+    }
+    is_deeply(identity_of($class, 450), $first->{reserved},
+        'lock error: identity is unchanged');
+    is(
+        pending_of($class, 450),
+        "uid=$backup_uid",
+        'lock error: nothing decided, pending uid stays',
+    );
+
+    unlock_config($class, 450);
+    $retry = $class->create_and_lock_config(450, 1);
+    $res = PVE::GuestIdentity::adopt($class, 450, $backup_uid, $retry);
+    is($res->{result}, 'adopted', 'lock error: a later operation takes the pending uid over');
+    ok(!defined(pending_of($class, 450)), 'lock error: then the pending uid is removed');
+
+    # removing the pending uid keeps a published identity that the parser could not read
+    my $config_module = Test::MockModule->new('PVE::TestConfig', no_auto => 1);
+    $config_module->mock(
+        load_config => sub {
+            my $conf = $config_module->original('load_config')->(@_);
+            delete $conf->{meta};
+            return $conf;
+        },
+    );
+    $class->write_config(470, { name => 'target', meta => 'ctime=1' });
+    $target = identity_of($class, 470);
+    $retry = $class->create_and_lock_config(470, 1);
+    $class->record_pending_uid(470, new_uid());
+    {
+        local $lock_domain_error = "test error: unexpected lock\n";
+        $res = PVE::GuestIdentity::adopt($class, 470, new_uid(), $retry);
+    }
+    $config_module->unmock('load_config');
+    is($res->{result}, 'kept', 'unreadable meta: identity is kept');
+    ok(!defined(pending_of($class, 470)), 'unreadable meta: pending uid is removed');
+    is_deeply(identity_of($class, 470), $target, 'unreadable meta: published identity is kept');
+
+    # removing the pending uid fails
+    $class->write_config(460, { name => 'target' });
+    $retry = $class->create_and_lock_config(460, 1);
+    $class->record_pending_uid(460, new_uid());
+    {
+        local $get_config_error = "Connection refused\n";
+        eval { PVE::GuestIdentity::adopt($class, 460, new_uid(), $retry) };
+        is($@, "unable to remove the pending uid - Connection refused\n", 'error is passed on');
+    }
+    ok(defined(pending_of($class, 460)), 'pending uid stays');
+
+    eval { $class->record_pending_uid(460, 'GAYTEMZUGU3DOOBZMFRG') };
+    like($@, qr/invalid guest identity uid/, 'invalid pending uid is refused');
+};
+
+subtest 'config view with pending changes' => sub {
+    my $class = 'PVE::TestConfig';
+
+    my $pending_uid = new_uid();
+    $class->write_config(480, { name => 'old', meta => 'ctime=1' });
+    my $meta = conf_of($class, 480)->{meta};
+    $class->record_pending_uid(480, $pending_uid);
+    my $conf = conf_of($class, 480);
+    $conf->{pending}->{name} = 'new';
+    $class->write_config(480, $conf);
+
+    PVE::Cluster::cfs_update();
+    $conf = $class->load_current_config(480);
+    is($conf->{name}, 'new', 'other pending change is shown');
+    is($conf->{meta}, $meta, 'pending uid is not shown as meta');
+    ok(!exists($conf->{pending}), 'no pending section');
+    is($class->load_current_config(480, 1)->{name}, 'old', 'current values only');
+
+    set_file($class, 481, "meta: $meta\nname: old\n\n[PENDING]\ndelete: meta\n");
+    PVE::Cluster::cfs_update();
+    is($class->load_current_config(481)->{meta}, $meta, 'pending deletion of meta not shown');
+
+    # a guest type without identities may apply pending changes of 'meta'
+    local $check_identity_lock = 0;
+    $class = 'PVE::TestConfig::NoIdentity';
+    set_file($class, 482, "meta: ctime=1\nname: old\n\n[PENDING]\nmeta: ctime=2\n");
+    PVE::Cluster::cfs_update();
+    is($class->load_current_config(482)->{meta}, 'ctime=2', 'without identities: shown');
+};
+
 done_testing();
diff --git a/src/tests/guest-identity-tests.pl b/src/tests/guest-identity-tests.pl
index fb5167d..335b8c6 100755
--- a/src/tests/guest-identity-tests.pl
+++ b/src/tests/guest-identity-tests.pl
@@ -288,4 +288,134 @@ subtest 'node version check' => sub {
     }
 };
 
+subtest 'adopt result message' => sub {
+    my $uid = 'gaytemzugu3doobzmfrg';
+    my $new = 'aaaaaaaaaaaaaaaaaaaa';
+
+    my $tests = [
+        [{ result => 'kept', uid => $uid, requested => $new }, 'backup', "kept uid $uid"],
+        [
+            { result => 'adopted', uid => $uid, requested => $uid },
+            'backup',
+            "adopted uid $uid from the backup",
+        ],
+        [
+            { result => 'adopted', uid => $uid, requested => $uid },
+            'source',
+            "adopted uid $uid from the source guest",
+        ],
+        [
+            { result => 'in-use', uid => $new, requested => $uid, 'in-use-by' => 105 },
+            'backup',
+            "backup uid $uid is in use by guest 105, keeping uid $new",
+        ],
+        [
+            { result => 'in-use', uid => $new, requested => $uid, 'in-use-by' => 105 },
+            'source',
+            "source guest uid $uid is in use by guest 105, keeping uid $new",
+        ],
+        [
+            { result => 'changed', uid => $new, requested => $uid },
+            'source',
+            "uid changed during the operation, keeping uid $new instead of adopting uid $uid"
+                . " from the source guest",
+        ],
+        [
+            { result => 'changed', uid => $new, requested => $uid },
+            'backup',
+            "uid changed during the operation, keeping uid $new instead of adopting uid $uid"
+                . " from the backup",
+        ],
+        [{ result => 'skipped', uid => $new, requested => undef }, 'backup', "new uid $new"],
+    ];
+
+    for my $test (@$tests) {
+        my ($res, $origin, $expected) = @$test;
+        is(
+            PVE::GuestIdentity::adopt_result_message($res, $origin),
+            "guest identity: $expected",
+            "$res->{result} ($origin)",
+        );
+    }
+
+    eval {
+        PVE::GuestIdentity::adopt_result_message({ result => 'kept', uid => $uid }, 'other');
+    };
+    like($@, qr/unknown origin/, 'unknown origin is refused');
+
+    eval {
+        PVE::GuestIdentity::adopt_result_message({ result => 'bogus', uid => $uid }, 'backup');
+    };
+    like($@, qr/unknown result/, 'unknown result is refused');
+
+    is_deeply(
+        [PVE::GuestIdentity::remote_adopt_result_log({ result => 'adopted', uid => $uid })],
+        ['info', "guest identity: adopted uid $uid from the source guest"],
+        'remote result: known result is logged as info',
+    );
+    is_deeply(
+        [PVE::GuestIdentity::remote_adopt_result_log({ result => 'bogus', uid => $uid })],
+        ['warn', "unknown result of guest identity adoption 'bogus'"],
+        'remote result: unknown result is a warning',
+    );
+};
+
+subtest 'pending uid' => sub {
+    my $uid = 'gaytemzugu3doobzmfrg';
+    my $other = 'aaaaaaaaaaaaaaaaaaaa';
+
+    is(PVE::GuestIdentity::get_pending_uid({}), undef, 'none without pending section');
+    is(PVE::GuestIdentity::get_pending_uid({ pending => { memory => 1 } }), undef, 'none');
+    is(
+        PVE::GuestIdentity::get_pending_uid({ pending => { meta => 'uid=' . uc($uid) } }),
+        undef,
+        'invalid pending uid is none',
+    );
+    is(
+        PVE::GuestIdentity::get_pending_uid({ pending => { meta => "ctime=1,uid=$uid" } }),
+        $uid,
+        'other members are ignored',
+    );
+
+    my $conf = { meta => "rtime=1,uid=$other", pending => { memory => 1 } };
+    PVE::GuestIdentity::set_pending_uid($conf, $uid);
+    is_deeply(
+        $conf,
+        { meta => "rtime=1,uid=$other", pending => { memory => 1, meta => "uid=$uid" } },
+        'set: only the uid member, other pending changes are kept',
+    );
+    is(PVE::GuestIdentity::get_pending_uid($conf), $uid, 'set: read back');
+
+    PVE::GuestIdentity::set_pending_uid($conf, undef);
+    is_deeply(
+        $conf,
+        { meta => "rtime=1,uid=$other", pending => { memory => 1 } },
+        'remove: other pending changes are kept',
+    );
+    $conf = {};
+    PVE::GuestIdentity::set_pending_uid($conf, undef);
+    is_deeply($conf, {}, 'remove without pending section changes nothing');
+
+    eval { PVE::GuestIdentity::set_pending_uid({}, 'GAYTEMZUGU3DOOBZMFRG') };
+    like($@, qr/invalid guest identity uid/, 'invalid uid is refused');
+
+    my $reservation = { identity => undef, pending => undef };
+    is(PVE::GuestIdentity::adoptable_uid($reservation, $uid), $uid, 'no identity: adoptable');
+    is(PVE::GuestIdentity::adoptable_uid($reservation, undef), undef, 'nothing to adopt');
+    is(PVE::GuestIdentity::adoptable_uid(undef, $uid), undef, 'no reservation: none');
+    ok(PVE::GuestIdentity::uid_matches_target($reservation, $uid), 'no identity: matches');
+
+    $reservation = { identity => { uid => $other, rtime => 1 }, pending => undef };
+    is(PVE::GuestIdentity::adoptable_uid($reservation, $uid), undef, 'identity: not adoptable');
+    is(PVE::GuestIdentity::adoptable_uid($reservation, $other), undef,
+        'own uid: not adoptable');
+    ok(!PVE::GuestIdentity::uid_matches_target($reservation, $uid), 'identity: no match');
+    ok(PVE::GuestIdentity::uid_matches_target($reservation, $other), 'own uid: matches');
+
+    $reservation->{pending} = $uid;
+    is(PVE::GuestIdentity::adoptable_uid($reservation, $uid), $uid, 'pending uid: adoptable');
+    ok(PVE::GuestIdentity::uid_matches_target($reservation, $uid), 'pending uid: matches');
+    is(PVE::GuestIdentity::adoptable_uid($reservation, $other), undef, 'own uid still not');
+};
+
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH qemu-server 12/34] api: restore: release the VMID if a restore to an unused VMID fails
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (10 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH guest-common 11/34] guest identity: allow taking over a uid that is unused in the cluster Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH qemu-server 13/34] api: migrate, clone: refuse targets that would drop the guest identity Thomas Lamprecht
                   ` (23 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

A failed restore to a previously unused VMID left its temporary or
empty config behind, even when the restore cleaned up the volumes it
had allocated. The VMID stayed taken and a retry needed 'force'.
Containers already remove their config in this case.

Remove the VM config and the restored firewall config if the VMID was
unused before the operation and the restore has not reached the point
from which it keeps the restored volumes. Keep the VM after later
failures, such as a failure in the live phase of a live restore.

Remove the config before releasing the guest config lock. The
temporary config of a VMA restore has no lock property, so removing it
later could delete the config of another restore that took the VMID in
the meantime.

Only warn that the VM was not cleaned up if the restore changed the
target and left it behind. A failure to read the backup should not
produce that warning.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/API2/Qemu.pm                      |  28 +-
 src/PVE/QemuServer.pm                     |   8 +
 src/test/QemuServerTest/FakeCFS.pm        | 194 ++++++++++++
 src/test/run_qemu_restore_config_tests.pl | 358 ++++++++++++++++++++--
 4 files changed, 567 insertions(+), 21 deletions(-)
 create mode 100644 src/test/QemuServerTest/FakeCFS.pm

diff --git a/src/PVE/API2/Qemu.pm b/src/PVE/API2/Qemu.pm
index b9634d20..504c9768 100644
--- a/src/PVE/API2/Qemu.pm
+++ b/src/PVE/API2/Qemu.pm
@@ -1413,10 +1413,12 @@ __PACKAGE__->register_method({
 
         my $emsg = $is_restore ? "unable to restore VM $vmid -" : "unable to create VM $vmid -";
 
-        eval { PVE::QemuConfig->create_and_lock_config($vmid, $force) };
+        my $reservation = eval { PVE::QemuConfig->create_and_lock_config($vmid, $force) };
         die "$emsg $@" if $@;
 
         my $restored_data = 0;
+        # the restore paths record whether they changed the VM and whether restored volumes stay
+        my $restore_progress = {};
         my $restorefn = sub {
             my $conf = PVE::QemuConfig->load_config($vmid);
 
@@ -1432,6 +1434,7 @@ __PACKAGE__->register_method({
                     bwlimit => $bwlimit,
                     live => $live_restore,
                     override_conf => $param,
+                    progress => $restore_progress,
                 };
                 if (my $volid = $archive->{volid}) {
                     # best effort, real check is after restoring!
@@ -1489,7 +1492,24 @@ __PACKAGE__->register_method({
                     if $unique;
             };
 
-            PVE::QemuConfig->lock_config_full($vmid, 1, $realcmd);
+            my $restore_locked = sub {
+                eval { $realcmd->() };
+                my $err = $@ or return;
+
+                if (!$reservation->{existed} && !$restore_progress->{'volumes-kept'}) {
+                    # Remove the reservation before releasing the guest lock, so another
+                    # operation cannot take ownership first.
+                    eval {
+                        PVE::QemuConfig->destroy_config($vmid);
+                        $restore_progress->{'reservation-removed'} = 1;
+                        PVE::Firewall::remove_vmfw_conf($vmid);
+                    };
+                    warn $@ if $@;
+                }
+                die $err;
+            };
+
+            PVE::QemuConfig->lock_config_full($vmid, 1, $restore_locked);
 
             if ($start_after_create && !$live_restore) {
                 print "Execute autostart\n";
@@ -1622,13 +1642,15 @@ __PACKAGE__->register_method({
             $code = sub {
                 eval { $restorefn->() };
                 if (my $err = $@) {
+                    die $err if $restore_progress->{'reservation-removed'};
+
                     eval { PVE::QemuConfig->remove_lock($vmid, 'create') };
                     warn $@ if $@;
                     if ($restored_data) {
                         warn
                             "error after data was restored, VM disks should be OK but config may "
                             . "require adaptions. VM $vmid state is NOT cleaned up.\n";
-                    } else {
+                    } elsif ($restore_progress->{'target-changed'}) {
                         warn "error before or during data restore, some or all disks were not "
                             . "completely restored. VM $vmid state is NOT cleaned up.\n";
                     }
diff --git a/src/PVE/QemuServer.pm b/src/PVE/QemuServer.pm
index dcd439f3..9ffc11e8 100644
--- a/src/PVE/QemuServer.pm
+++ b/src/PVE/QemuServer.pm
@@ -6948,6 +6948,7 @@ sub restore_proxmox_backup_archive {
         $param = [$pbs_backup_name, "qemu-server.conf", $cfgfn];
         PVE::Storage::PBSPlugin::run_raw_client_cmd($scfg, $storeid, $cmd, $param);
 
+        $options->{progress}->{'target-changed'} = 1;
         PVE::ReplicationState::delete_guest_states($vmid);
 
         if ($has_firewall_config) {
@@ -7042,6 +7043,7 @@ sub restore_proxmox_backup_archive {
         $restore_destroy_volumes->($storecfg, $virtdev_hash);
         die $err;
     }
+    $options->{progress}->{'volumes-kept'} = 1;
 
     if ($options->{live}) {
         # keep lock during live-restore
@@ -7129,6 +7131,7 @@ sub restore_external_archive {
         my $data = $backup_provider->archive_get_guest_config($volname)
             or die "backup provider failed to extract guest configuration\n";
 
+        $options->{progress}->{'target-changed'} = 1;
         PVE::ReplicationState::delete_guest_states($vmid);
 
         PVE::Tools::file_set_contents($cfgfn, $data);
@@ -7218,6 +7221,7 @@ sub restore_external_archive {
         $restore_destroy_volumes->($storecfg, $virtdev_hash);
         die $err;
     }
+    $options->{progress}->{'volumes-kept'} = 1;
 
     my $new_conf = restore_merge_config($conffile, $new_conf_raw, $options->{override_conf});
     check_restore_permissions($rpcenv, $user, $new_conf);
@@ -7543,6 +7547,7 @@ sub restore_vma_archive {
     my $print_devmap = sub {
         my $cfgfn = "$tmpdir/qemu-server.conf";
 
+        $opts->{progress}->{'target-changed'} = 1;
         PVE::ReplicationState::delete_guest_states($vmid);
 
         # we can read the config - that is already extracted
@@ -7676,6 +7681,7 @@ sub restore_vma_archive {
         $restore_destroy_volumes->($cfg, $virtdev_hash);
         die $err;
     }
+    $opts->{progress}->{'volumes-kept'} = 1;
 
     my $new_conf = restore_merge_config($conffile, $new_conf_raw, $opts->{override_conf});
     check_restore_permissions($rpcenv, $user, $new_conf);
@@ -7703,6 +7709,7 @@ sub restore_tar_archive {
 
     my $storecfg = PVE::Storage::config();
 
+    $opts->{progress}->{'target-changed'} = 1;
     PVE::ReplicationState::delete_guest_states($vmid);
 
     # avoid zombie disks when restoring over an existing VM -> cleanup first
@@ -7785,6 +7792,7 @@ sub restore_tar_archive {
         tar_restore_cleanup($storecfg, "$tmpdir/qmrestore.stat") if !$opts->{info};
         die $err;
     }
+    $opts->{progress}->{'volumes-kept'} = 1;
 
     rmtree $tmpdir;
 
diff --git a/src/test/QemuServerTest/FakeCFS.pm b/src/test/QemuServerTest/FakeCFS.pm
new file mode 100644
index 00000000..dd9dddec
--- /dev/null
+++ b/src/test/QemuServerTest/FakeCFS.pm
@@ -0,0 +1,194 @@
+package QemuServerTest::FakeCFS;
+
+# Fake cluster filesystem for VM config files, so that tests can use the real config class methods
+# of PVE::QemuConfig, including the guest identity handling of write_config, without pmxcfs.
+#
+# Configs are kept as raw text, indexed by VMID, and an empty file at the path that config_file()
+# returns exists for each, for checks of the file's existence. Generated guest identities are
+# deterministic: the n-th generated uid is 'a' repeated 13 times followed by the base32 encoding of
+# n, and rtime is $now_ms.
+
+use strict;
+use warnings;
+
+use File::Basename qw(dirname);
+use File::Path qw(make_path remove_tree);
+use File::Temp qw(tempdir);
+use Test::MockModule;
+
+use PVE::GuestHelpers;
+use PVE::GuestIdentity;
+use PVE::QemuConfig;
+use PVE::QemuServer;
+
+our $configs = {}; # VMID => raw config, for VMs on the local node
+our $other_guests = {}; # VMID => raw 'meta' property of other guests, like on other nodes or CTs
+our $now_ms = 1700000000000;
+our $generated = 0;
+our $lock_domain_error;
+our $writes = [];
+
+my $tmpdir = tempdir('fake-cfs-XXXXXX', DIR => '.', CLEANUP => 1);
+make_path("$tmpdir/lock");
+$PVE::GuestHelpers::lockdir = "$tmpdir/lock";
+
+sub reset {
+    remove_tree("$tmpdir/etc-pve");
+    $configs = {};
+    $other_guests = {};
+    $now_ms = 1700000000000;
+    $generated = 0;
+    $lock_domain_error = undef;
+    $writes = [];
+}
+
+my sub vmid_of_path {
+    my ($path) = @_;
+
+    return $path =~ m|/qemu-server/(\d+)\.conf$| ? $1 : undef;
+}
+
+# Creates or removes the file at the path of the config of $vmid, matching the stored config.
+my sub sync_config_file {
+    my ($vmid) = @_;
+
+    my $path = PVE::QemuConfig->config_file($vmid);
+    if (defined($configs->{$vmid})) {
+        make_path(dirname($path));
+        open(my $fh, '>', $path) or die "unable to create '$path' - $!\n";
+        close($fh);
+    } else {
+        unlink($path);
+    }
+}
+
+# Stores the raw config $raw for $vmid, like a manual edit of the config file.
+sub set_config {
+    my ($vmid, $raw) = @_;
+
+    $configs->{$vmid} = $raw;
+    sync_config_file($vmid);
+}
+
+# Returns the last 'meta' property of the top-level section of the raw config $raw, like the config
+# class reads the published identity.
+my sub top_level_meta {
+    my ($raw) = @_;
+
+    my $meta;
+    for my $line (split(/\n/, $raw // '')) {
+        last if $line =~ m/^\[/;
+        $meta = $1 if $line =~ m/^meta:\s*(.*?)\s*$/;
+    }
+
+    return $meta;
+}
+
+# Returns the identity published in the raw config of $vmid, undef if there is none.
+sub published_identity {
+    my ($vmid) = @_;
+
+    return PVE::GuestIdentity::parse_identity(top_level_meta($configs->{$vmid}));
+}
+
+# Returns the uid that the $n-th generation of an identity yields.
+sub generated_uid {
+    my ($n) = @_;
+
+    my $alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
+    return ('a' x 17) . join('', map { substr($alphabet, ($n >> (5 * $_)) & 31, 1) } (2, 1, 0));
+}
+
+our $guest_identity_module = Test::MockModule->new('PVE::GuestIdentity');
+$guest_identity_module->mock(
+    __random_bytes => sub {
+        my ($len) = @_;
+        die "unexpected length $len\n" if $len != 13;
+        $generated++;
+        # 85 zero bits encode as 17 'a', then the 15 bits of the counter, the last 4 bits are unused
+        my $counter = substr(unpack('B32', pack('N', $generated)), -15);
+        return pack('B104', ('0' x 85) . $counter . '0000');
+    },
+    __time_ms => sub {
+        return $now_ms;
+    },
+);
+
+our $cluster_module = Test::MockModule->new('PVE::Cluster');
+$cluster_module->mock(
+    get_config => sub {
+        my ($path) = @_;
+        my $vmid = vmid_of_path($path) // die "get_config (mocked) - unexpected path '$path'\n";
+        return $configs->{$vmid};
+    },
+    cfs_read_file => sub {
+        my ($path) = @_;
+        return {} if $path eq 'datacenter.cfg';
+        my $vmid = vmid_of_path($path)
+            // die "cfs_read_file (mocked) - unexpected path '$path'\n";
+        return PVE::QemuServer::parse_vm_config($path, $configs->{$vmid});
+    },
+    cfs_write_file => sub {
+        my ($path, $conf) = @_;
+        my $vmid = vmid_of_path($path)
+            // die "cfs_write_file (mocked) - unexpected path '$path'\n";
+        $configs->{$vmid} = PVE::QemuServer::write_vm_config($path, $conf);
+        sync_config_file($vmid);
+        push $writes->@*, $vmid;
+        return;
+    },
+    cfs_update => sub {
+        return;
+    },
+    check_vmid_unused => sub {
+        my ($vmid, $noerr) = @_;
+        return 1 if !defined($configs->{$vmid}) && !defined($other_guests->{$vmid});
+        return undef if $noerr;
+        die "VM $vmid already exists\n";
+    },
+    cfs_lock_domain => sub {
+        my ($domain, $timeout, $code, @param) = @_;
+        die "cfs_lock_domain (mocked) - unexpected domain '$domain'\n"
+            if $domain ne 'guest-identity';
+        if ($lock_domain_error) {
+            $@ = $lock_domain_error;
+            return undef;
+        }
+        my $res = eval { $code->(@param) };
+        return $res;
+    },
+    get_guest_config_properties => sub {
+        my ($properties) = @_;
+        die "get_guest_config_properties (mocked) - unexpected properties\n"
+            if join(',', $properties->@*) ne 'meta';
+
+        my $res = {};
+        for my $vmid (keys $configs->%*) {
+            my $meta = top_level_meta($configs->{$vmid});
+            $res->{$vmid} = { meta => $meta } if defined($meta);
+        }
+        $res->{$_} = { meta => $other_guests->{$_} } for keys $other_guests->%*;
+        return $res;
+    },
+);
+
+our $qemu_config_module = Test::MockModule->new('PVE::QemuConfig');
+$qemu_config_module->mock(
+    config_file => sub {
+        my ($class, $vmid, $node) = @_;
+        return "$tmpdir/etc-pve/" . $class->cfs_config_path($vmid, $node);
+    },
+    config_file_lock => sub {
+        my ($class, $vmid) = @_;
+        return "$tmpdir/lock/lock-$vmid.conf";
+    },
+    destroy_config => sub {
+        my ($class, $vmid) = @_;
+        die "failed to remove config file: No such file or directory\n"
+            if !defined($configs->{$vmid});
+        delete $configs->{$vmid};
+        sync_config_file($vmid);
+    },
+);
+
+1;
diff --git a/src/test/run_qemu_restore_config_tests.pl b/src/test/run_qemu_restore_config_tests.pl
index 20cb3df0..e6739d66 100755
--- a/src/test/run_qemu_restore_config_tests.pl
+++ b/src/test/run_qemu_restore_config_tests.pl
@@ -3,35 +3,30 @@
 use strict;
 use warnings;
 
-use lib qw(..);
+use lib qw(.. .);
 
+use Fcntl qw(:flock O_RDONLY O_NONBLOCK);
+use File::Path qw(make_path);
+use File::Temp qw(tempdir);
+use JSON;
 use Test::MockModule;
 use Test::More;
 
 use File::Basename;
 
+use PVE::API2::Qemu;
+use PVE::QemuConfig;
 use PVE::QemuServer;
-use PVE::Tools qw(dir_glob_foreach file_get_contents);
+use PVE::QemuServer::Helpers;
+use PVE::RPCEnvironment;
+use PVE::Tools qw(dir_glob_foreach file_get_contents file_set_contents);
+
+# also provides the 'datacenter.cfg' that restore_update_config_line reads
+use QemuServerTest::FakeCFS;
 
 my $INPUT_DIR = './restore-config-input';
 my $EXPECTED_DIR = './restore-config-expected';
 
-# NOTE update when you add/remove tests
-plan tests => 5;
-
-my $pve_cluster_module = Test::MockModule->new("PVE::Cluster");
-$pve_cluster_module->mock(
-    cfs_read_file => sub {
-        my ($file) = @_;
-
-        if ($file eq 'datacenter.cfg') {
-            return {};
-        } else {
-            die "'cfs_read_file' called - missing mock?\n";
-        }
-    },
-);
-
 dir_glob_foreach(
     './restore-config-input',
     '[0-9]+.conf',
@@ -78,4 +73,331 @@ dir_glob_foreach(
     },
 );
 
+# Restores through the create API and the restore paths for PBS, backup providers, VMA and legacy
+# tar archives, against the fake cluster filesystem. Storage, archive tools and other external
+# effects are mocked. The backups have no disks, so that no volumes get allocated.
+
+my $runtime_dir = tempdir('restore-run-XXXXXX', DIR => '.', CLEANUP => 1);
+$PVE::QemuServer::Helpers::var_run_tmpdir = $runtime_dir;
+
+my $rpcenv = PVE::RPCEnvironment->init('cli');
+$rpcenv->set_user('root@pam');
+
+my $ARCHIVES = {
+    pbs => 'pbs:backup/vm/100/2025-01-01T00:00:00Z',
+    provider => 'provider:backup/vm-100-2025-01-01',
+    'vma file' => '/var/lib/vz/dump/vzdump-qemu-100-2025_01_01-00_00_00.vma',
+    'vma stdin' => '-',
+    tar => '/var/lib/vz/dump/vzdump-qemu-100-2025_01_01-00_00_00.tar',
+};
+
+our $current_backup; # raw config of the backup
+our $fail_at = ''; # where the restore fails: 'read-config', 'data', 'after-restore' or 'live'
+my $calls = {}; # calls with effects on the target VM that tests check
+
+sub backup_config {
+    my ($meta) = @_;
+
+    return
+        "boot: order=scsi0\ncores: 1\nmemory: 512\n"
+        . (defined($meta) ? "meta: $meta\n" : '')
+        . "name: backup\n";
+}
+
+package TestBackupProvider {
+
+    sub new {
+        my ($class) = @_;
+        return bless {}, $class;
+    }
+
+    sub restore_get_mechanism { return ('qemu-img', 'qemu'); }
+    sub restore_vm_init { return {}; }
+
+    sub archive_get_guest_config {
+        die "unable to read the backup\n" if $main::fail_at eq 'read-config';
+        return $main::current_backup;
+    }
+    sub archive_get_firewall_config { return "[OPTIONS]\nenable: 1\n"; }
+    sub restore_vm_cleanup { return; }
+}
+
+my $replication_state_module = Test::MockModule->new('PVE::ReplicationState');
+$replication_state_module->mock(delete_guest_states => sub { $calls->{delete_guest_states}++; });
+
+my $firewall_module = Test::MockModule->new('PVE::Firewall');
+$firewall_module->mock(remove_vmfw_conf => sub { $calls->{remove_vmfw_conf}++; });
+
+my $tools_module = Test::MockModule->new('PVE::Tools');
+$tools_module->mock(
+    file_copy => sub {
+        my ($src, $dst) = @_;
+        die "file_copy (mocked) - unexpected destination '$dst'\n" if $dst !~ m|/firewall/|;
+        $calls->{firewall}++;
+    },
+);
+
+my $storage_module = Test::MockModule->new('PVE::Storage');
+$storage_module->mock(
+    abs_filesystem_path => sub {
+        my ($cfg, $path) = @_;
+        return $path;
+    },
+    check_volume_access => sub { return; },
+    config => sub { return {}; },
+    deactivate_volumes => sub { return 1; },
+    extract_vzdump_config => sub { return $current_backup; },
+    new_backup_provider => sub { return TestBackupProvider->new(); },
+    parse_volname => sub {
+        return ('backup', 'vm/100/2025-01-01T00:00:00Z', 100, undef, undef, undef, 'pbs-vm');
+    },
+    parse_volume_id => sub {
+        my ($volid, $noerr) = @_;
+        return ($1, $2) if $volid =~ m/^([a-z]+):(.+)$/;
+        die "unable to parse volume ID '$volid'\n" if !$noerr;
+        return;
+    },
+    path_to_volume_id => sub { return; },
+    storage_config => sub {
+        my ($cfg, $storeid) = @_;
+        return { type => 'pbs', server => 'localhost', datastore => 'ds' } if $storeid eq 'pbs';
+        return { type => 'dir', path => '/mnt/provider' };
+    },
+    storage_has_feature => sub {
+        my ($cfg, $storeid, $feature) = @_;
+        return $storeid eq 'provider' && $feature eq 'backup-provider';
+    },
+);
+
+my $pbs_plugin_module = Test::MockModule->new('PVE::Storage::PBSPlugin');
+$pbs_plugin_module->mock(
+    pbs_encryption_key_file_name => sub { return '/nonexistent/key'; },
+    pbs_get_password => sub { return 'secret'; },
+    run_raw_client_cmd => sub {
+        my ($scfg, $storeid, $cmd, $param) = @_;
+        my (undef, $file, $target) = $param->@*;
+        if ($file eq 'index.json') {
+            my $files =
+                [{ filename => 'qemu-server.conf.blob' }, { filename => 'fw.conf.blob' }];
+            file_set_contents($target, encode_json({ files => $files }));
+        } elsif ($file eq 'qemu-server.conf') {
+            die "unable to read the backup\n" if $fail_at eq 'read-config';
+            file_set_contents($target, $current_backup);
+        } elsif ($file eq 'fw.conf') {
+            file_set_contents($target, "[OPTIONS]\nenable: 1\n");
+        } else {
+            die "run_raw_client_cmd (mocked) - unexpected file '$file'\n";
+        }
+    },
+);
+
+my $network_module = Test::MockModule->new('PVE::QemuServer::Network');
+$network_module->mock(
+    create_ifaces_ipams_ips => sub {
+        die "unable to register IPs\n" if $fail_at eq 'after-restore';
+    },
+);
+
+my $qemu_server_module = Test::MockModule->new('PVE::QemuServer');
+$qemu_server_module->mock(
+    check_running => sub { return 0; },
+    pbs_live_restore => sub {
+        die "live restore failed\n" if $fail_at eq 'live';
+        $calls->{live_restore}++;
+    },
+    rescan => sub { return; },
+    restore_update_config_line => sub {
+        die "restoring the data failed\n" if $fail_at eq 'data';
+        return $qemu_server_module->original('restore_update_config_line')->(@_);
+    },
+    tar_archive_read_firstfile => sub { return 'qemu-server.conf'; },
+    # like 'tar' with qmextract and 'vma extract': write the config and report the VMA header
+    run_command => sub {
+        my ($cmd, %param) = @_;
+
+        if (!ref($cmd) && $cmd =~ m/^zcat -f\|tar xf /) {
+            die "unable to read the backup\n" if $fail_at eq 'read-config';
+            file_set_contents("$ENV{VZDUMP_TMPDIR}/qemu-server.conf", $current_backup);
+            return 0;
+        }
+
+        my $vma = $cmd->[-1];
+        die "run_command (mocked) - unexpected command\n"
+            if ref($vma) ne 'ARRAY' || $vma->[0] ne 'vma';
+        my ($mapfifo, $tmpdir) = $vma->@[4, 6];
+
+        die "unable to read the backup\n" if $fail_at eq 'read-config';
+
+        make_path($tmpdir);
+        file_set_contents("$tmpdir/qemu-server.conf", $current_backup);
+        file_set_contents("$tmpdir/qemu-server.fw", "[OPTIONS]\nenable: 1\n");
+
+        sysopen(my $reader, $mapfifo, O_RDONLY | O_NONBLOCK)
+            or die "unable to open fifo - $!\n";
+        $param{afterfork}->();
+        $param{outfunc}->('CTIME: Wed Jan  1 00:00:00 2025');
+        close($reader);
+
+        return 0;
+    },
+);
+
+my $task_error;
+my $rpcenv_module = Test::MockModule->new('PVE::RPCEnvironment');
+$rpcenv_module->mock(
+    check => sub { return 1; },
+    fork_worker => sub {
+        my ($self, $type, $id, $user, $code) = @_;
+        eval { $code->('UPID:test') };
+        $task_error = $@;
+        return 'UPID:test';
+    },
+);
+
+$QemuServerTest::FakeCFS::cluster_module->mock(check_cfs_quorum => sub { return 1; });
+
+# Restores a backup with the raw config $backup to VMID 100 through the create API, from an archive
+# of type $type with the additional API parameters $param. Returns the error of the API call or the
+# task and the task output.
+sub restore_api {
+    my ($type, $backup, $param) = @_;
+
+    $current_backup = $backup;
+    $calls = {};
+    $task_error = '';
+
+    my ($err, $output) = ('', '');
+    {
+        open(my $out_fh, '>', \$output);
+        local *STDERR = $out_fh;
+        my $oldfh = select($out_fh);
+
+        eval {
+            PVE::API2::Qemu->create_vm({
+                node => 'localhost',
+                vmid => 100,
+                archive => $ARCHIVES->{$type},
+                $param->%*,
+            });
+        };
+        $err = $@ || $task_error;
+
+        select($oldfh);
+        close($out_fh);
+    }
+
+    return ($err, $output);
+}
+
+my $TARGET_CONF = "memory: 1024\nmeta: creation-qemu=10.0.0,ctime=1700000000\nname: target\n";
+my $NOT_CLEANED_UP = qr/VM 100 state is NOT cleaned up/;
+
+for my $type (sort keys $ARCHIVES->%*) {
+    subtest "$type: failed restore to a free VMID" => sub {
+        QemuServerTest::FakeCFS::reset();
+
+        $fail_at = 'data';
+        my ($err, $output) = restore_api($type, backup_config(), {});
+        is($err, "restoring the data failed\n", 'restore failed');
+        ok(!defined($QemuServerTest::FakeCFS::configs->{100}), 'reserved config removed');
+        is($calls->{remove_vmfw_conf}, 1, 'restored firewall config removed');
+        unlike($output, $NOT_CLEANED_UP, 'no warning about a VM left behind');
+
+        $fail_at = '';
+        ($err, $output) = restore_api($type, backup_config(), { force => 1 });
+        is($err, '', 'retry succeeds') or diag($output);
+        like($QemuServerTest::FakeCFS::configs->{100}, qr/^name: backup$/m, 'VM restored');
+    };
+}
+
+subtest 'failed restore to a free VMID before reading the backup' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    $fail_at = 'read-config';
+    my ($err, $output) = restore_api('pbs', backup_config(), {});
+    is($err, "unable to read the backup\n", 'restore failed');
+    ok(!defined($QemuServerTest::FakeCFS::configs->{100}), 'reserved config removed');
+    unlike($output, $NOT_CLEANED_UP, 'no warning about a VM left behind');
+};
+
+subtest 'another restore right after a failed restore to a free VMID' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    # run a second restore with 'force' as soon as the failed one releases the guest lock
+    my $lock_config_full = PVE::QemuConfig->can('lock_config_full');
+    my ($interposed, $lock_free, $second_err) = (0, 0, '');
+    $QemuServerTest::FakeCFS::qemu_config_module->mock(
+        lock_config_full => sub {
+            my ($class, $vmid, @param) = @_;
+            my $res = eval { $lock_config_full->($class, $vmid, @param) };
+            my $err = $@;
+            if ($err && !$interposed++) {
+                open(my $fh, '>>', PVE::QemuConfig->config_file_lock($vmid)) or die "$!\n";
+                $lock_free = flock($fh, LOCK_EX | LOCK_NB);
+                close($fh);
+                local $fail_at = '';
+                ($second_err) = restore_api('pbs', backup_config(), { force => 1 });
+            }
+            die $err if $err;
+            return $res;
+        },
+    );
+
+    # the temporary config of a VMA restore has no lock that would stop the second restore
+    $fail_at = 'data';
+    my ($err) = restore_api('vma file', backup_config(), {});
+    $QemuServerTest::FakeCFS::qemu_config_module->unmock('lock_config_full');
+
+    is($err, "restoring the data failed\n", 'first restore failed');
+    ok($lock_free, 'guest lock was free for the second restore');
+    is($second_err, '', 'second restore succeeded');
+    like($QemuServerTest::FakeCFS::configs->{100}, qr/^name: backup$/m, 'its config stays');
+    is($calls->{firewall}, 1, 'its firewall config was restored');
+    ok(!$calls->{remove_vmfw_conf}, 'and stays');
+};
+
+for my $type ('pbs', 'provider', 'vma file', 'vma stdin') {
+    subtest "$type: failed restore over an existing VM" => sub {
+        QemuServerTest::FakeCFS::reset();
+        QemuServerTest::FakeCFS::set_config(100, $TARGET_CONF);
+
+        $fail_at = 'read-config';
+        my ($err, $output) = restore_api($type, backup_config(), { force => 1 });
+        like($err, qr/unable to read the backup\n$/, 'fails before changing the VM');
+        is($QemuServerTest::FakeCFS::configs->{100}, $TARGET_CONF, 'config unchanged');
+        is_deeply($calls, {}, 'replication state and firewall config untouched');
+        unlike($output, $NOT_CLEANED_UP, 'no warning about a changed VM');
+
+        $fail_at = 'data';
+        ($err, $output) = restore_api($type, backup_config(), { force => 1 });
+        is($err, "restoring the data failed\n", 'fails while restoring');
+        like($QemuServerTest::FakeCFS::configs->{100}, qr/^memory: 128$/m, 'temporary config');
+        unlike($QemuServerTest::FakeCFS::configs->{100}, qr/^lock:/m, 'lock removed');
+        like($output, qr/error before or during data restore/, 'warning about the changed VM');
+    };
+}
+
+subtest 'failed live restore to a free VMID keeps the restored config' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    $fail_at = 'live';
+    my ($err, $output) = restore_api('pbs', backup_config(), { 'live-restore' => 1 });
+    is($err, "live restore failed\n", 'restore failed');
+    like($QemuServerTest::FakeCFS::configs->{100}, qr/^name: backup$/m, 'restored config kept');
+    unlike($QemuServerTest::FakeCFS::configs->{100}, qr/^lock:/m, 'lock removed');
+    like($output, $NOT_CLEANED_UP, 'warning about the VM left behind');
+};
+
+subtest 'failure after the data was restored keeps the VM' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    $fail_at = 'after-restore';
+    my ($err, $output) = restore_api('pbs', backup_config(), { unique => 1 });
+    is($err, "unable to register IPs\n", 'restore failed');
+    like($QemuServerTest::FakeCFS::configs->{100}, qr/^name: backup$/m, 'restored config kept');
+    like($output, qr/error after data was restored/, 'warning about the VM left behind');
+};
+
+$fail_at = '';
+
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH qemu-server 13/34] api: migrate, clone: refuse targets that would drop the guest identity
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (11 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH qemu-server 12/34] api: restore: release the VMID if a restore to an unused VMID fails Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH qemu-server 14/34] fix #7846: config: add a guest identity to the 'meta' property Thomas Lamprecht
                   ` (22 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Older qemu-server versions reject the identity members of 'meta' and
drop the whole property when they write the config. A guest that moves
to such a node loses its identity, and gets a new one with a later
write by an upgraded node.

Refuse online and offline migrations and clones to another node unless
the target reports a Proxmox VE version that keeps the identity. Use
the shared version threshold and treat missing version information as
too old. Report the reason and the versions involved in the migration
preconditions, so that clients can explain the refusal.

Check before starting the task or handing an API migration request to
HA. This does not keep an HA resource plugin from shutting down a VM
for a relocation before it calls the migration API.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/API2/Qemu.pm      |  33 ++++++++++-
 src/test/run_api_tests.pl | 119 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 151 insertions(+), 1 deletion(-)

diff --git a/src/PVE/API2/Qemu.pm b/src/PVE/API2/Qemu.pm
index 504c9768..28e8389a 100644
--- a/src/PVE/API2/Qemu.pm
+++ b/src/PVE/API2/Qemu.pm
@@ -26,6 +26,7 @@ use PVE::JSONSchema qw(get_standard_option);
 use PVE::RESTHandler;
 use PVE::ReplicationConfig;
 use PVE::GuestHelpers qw(assert_tag_permissions);
+use PVE::GuestIdentity;
 use PVE::GuestImport;
 use PVE::QemuConfig;
 use PVE::QemuServer;
@@ -4523,7 +4524,10 @@ __PACKAGE__->register_method({
 
         my $load_and_check = sub {
             $rpcenv->check_pool_exist($pool) if defined($pool);
-            PVE::Cluster::check_node_exists($target) if $target;
+            if ($target) {
+                PVE::Cluster::check_node_exists($target);
+                PVE::GuestIdentity::assert_node_supports_identity($target);
+            }
 
             my $storecfg = PVE::Storage::config();
 
@@ -5400,6 +5404,25 @@ __PACKAGE__->register_method({
                             },
                         },
                     },
+                    'guest-identity-unsupported' => {
+                        description =>
+                            "Set if migrating to the node is refused because the node does not"
+                            . " report a Proxmox VE version that keeps the guest identity.",
+                        type => 'object',
+                        optional => 1,
+                        properties => {
+                            version => {
+                                description => "The Proxmox VE version the node reports.",
+                                type => 'string',
+                                optional => 1,
+                            },
+                            'required-version' => {
+                                description =>
+                                    "The minimum Proxmox VE version that keeps the guest identity.",
+                                type => 'string',
+                            },
+                        },
+                    },
                 },
                 description => "List of not allowed nodes with additional information.",
             },
@@ -5541,6 +5564,12 @@ __PACKAGE__->register_method({
                     $blocking_ha_resources;
             }
 
+            # the migration refuses nodes that would drop the guest identity
+            if (my $unsupported = PVE::GuestIdentity::node_identity_unsupported($node)) {
+                $res->{not_allowed_nodes}->{$node}->{'guest-identity-unsupported'} =
+                    $unsupported;
+            }
+
             # if nothing came up, add it to the allowed nodes
             if (scalar($res->{not_allowed_nodes}->{$node}->%*) == 0) {
                 push $res->{allowed_nodes}->@*, $node;
@@ -5653,6 +5682,8 @@ __PACKAGE__->register_method({
 
         PVE::Cluster::check_node_exists($target);
 
+        PVE::GuestIdentity::assert_node_supports_identity($target);
+
         my $targetip = PVE::Cluster::remote_node_ip($target);
 
         my $vmid = extract_param($param, 'vmid');
diff --git a/src/test/run_api_tests.pl b/src/test/run_api_tests.pl
index 4d5e1cdf..31498fd4 100755
--- a/src/test/run_api_tests.pl
+++ b/src/test/run_api_tests.pl
@@ -13,6 +13,7 @@ use Test::MockModule;
 use Test::More;
 
 use PVE::API2::Qemu;
+use PVE::GuestIdentity;
 use PVE::RPCEnvironment;
 
 my $rpcenv = PVE::RPCEnvironment->init('cli');
@@ -38,6 +39,31 @@ sub mock_unreachable_config {
 }
 mock_unreachable_config();
 
+my $qemu_server_module = Test::MockModule->new('PVE::QemuServer');
+$qemu_server_module->mock(check_running => sub { return 0; });
+
+# Proxmox VE versions the cluster nodes report, undef for none
+my $node_versions = {};
+
+my $cluster_module = Test::MockModule->new('PVE::Cluster');
+$cluster_module->mock(
+    check_cfs_quorum => sub { return 1; },
+    check_node_exists => sub { return 1; },
+    remote_node_ip => sub { return '192.0.2.2'; },
+    get_node_pvecfg_version => sub {
+        my ($node) = @_;
+        return $node_versions->{$node};
+    },
+    node_pvecfg_version_at_least => sub {
+        my ($node, @required) = @_;
+        my @version = split(/\./, $node_versions->{$node} // return 0);
+        for my $i (0 .. 2) {
+            return $version[$i] > $required[$i] if $version[$i] != $required[$i];
+        }
+        return 1;
+    },
+);
+
 # Returns the error of calling the API method $method with $param, either the parameter errors as
 # hash or the error message.
 sub api_error {
@@ -145,4 +171,97 @@ subtest 'pending changes of meta are dropped' => sub {
     mock_unreachable_config();
 };
 
+my $min_version = PVE::GuestIdentity::MIN_PVE_MANAGER_VERSION;
+my $node_cases = [
+    [$min_version, "reached load_config\n"],
+    ['10.0.0', "reached load_config\n"],
+    [
+        '9.2.0',
+        "node 'pve2' runs Proxmox VE 9.2.0, keeping the guest identity requires $min_version or"
+            . " newer - upgrade the node first\n",
+    ],
+    [
+        undef,
+        "node 'pve2' does not report its Proxmox VE version, so it is unknown whether the node"
+            . " keeps the guest identity\n",
+    ],
+];
+
+for my $case ($node_cases->@*) {
+    my ($version, $expected) = $case->@*;
+    $node_versions->{pve2} = $version;
+    my $what = 'target node with ' . ($version // 'no') . ' version';
+
+    is(
+        api_error('migrate_vm', { target => 'pve2' }), $expected, "migrate_vm: offline, $what",
+    );
+    is(
+        api_error('migrate_vm', { target => 'pve2', online => 1 }),
+        $expected,
+        "migrate_vm: online, $what",
+    );
+    is(
+        api_error('clone_vm', { newid => 101, target => 'pve2' }), $expected, "clone_vm: $what",
+    );
+}
+
+$node_versions->{pve2} = undef;
+is(
+    api_error('clone_vm', { newid => 101 }),
+    "reached load_config\n",
+    'clone_vm: no check without target node',
+);
+
+subtest 'migration preconditions' => sub {
+    my $nodes = ['localhost', 'pve2', 'pve3', 'pve4'];
+    $cluster_module->mock(get_nodelist => sub { return $nodes; });
+    my $inotify_module = Test::MockModule->new('PVE::INotify');
+    $inotify_module->mock(nodename => sub { return 'localhost'; });
+
+    $qemu_config_module->mock(load_config => sub { return { memory => 512 }; });
+    my $migrate_helpers_module = Test::MockModule->new('PVE::QemuMigrate::Helpers');
+    $migrate_helpers_module->mock(
+        check_local_resources => sub {
+            return ([], {}, { map { $_ => [] } $nodes->@* });
+        },
+    );
+    my $ha_config_module = Test::MockModule->new('PVE::HA::Config');
+    $ha_config_module->mock(vm_is_ha_managed => sub { return 0; });
+
+    $node_versions->@{ 'pve2', 'pve3', 'pve4' } = ($min_version, '9.2.0', undef);
+
+    my $res = PVE::API2::Qemu->migrate_vm_precondition({ node => 'localhost', vmid => 100 });
+
+    is_deeply($res->{allowed_nodes}, ['pve2'], 'only the node keeping the identity is allowed');
+    is_deeply(
+        $res->{not_allowed_nodes}->{pve3},
+        {
+            'guest-identity-unsupported' => {
+                version => '9.2.0',
+                'required-version' => $min_version,
+            },
+        },
+        'node with an older version is not allowed',
+    );
+    is_deeply(
+        $res->{not_allowed_nodes}->{pve4},
+        { 'guest-identity-unsupported' => { 'required-version' => $min_version } },
+        'node without version is not allowed',
+    );
+
+    my $returns = PVE::API2::Qemu->map_method_by_name('migrate_vm_precondition')->{returns};
+    eval { PVE::JSONSchema::validate($res, $returns) };
+    is($@, '', 'result matches the schema');
+    # the schema documents the reasons of a node as the properties of 'not_allowed_nodes'
+    my $reasons_schema =
+        { $returns->{properties}->{not_allowed_nodes}->%*, additionalProperties => 0 };
+    for my $node ('pve3', 'pve4') {
+        eval { PVE::JSONSchema::validate($res->{not_allowed_nodes}->{$node}, $reasons_schema) };
+        is($@, '', "reason for $node is documented in the schema");
+    }
+
+    $cluster_module->unmock('get_nodelist');
+    mock_unreachable_config();
+};
+
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH qemu-server 14/34] fix #7846: config: add a guest identity to the 'meta' property
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (12 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH qemu-server 13/34] api: migrate, clone: refuse targets that would drop the guest identity Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH qemu-server 15/34] restore: take over the guest uid from the backup where possible Thomas Lamprecht
                   ` (21 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Give VMs a guest identity in the read-only 'meta' property: a random
identifier, 'uid', and a registration time, 'rtime'. Tools can use it
to recognize a guest across restores and migrations, independently of
its VMID.

Enable the identity handling of the config class, so that each config
write keeps the identity a VM already has or assigns one if it has
none. New VMs, clones and imports get an identity when their VMID is
reserved. Existing VMs get one with their next config write. A stale
config, a clone source or a snapshot rollback cannot replace the
identity of a VM.

The other members of 'meta' behave as before. A config without creation
information thus gets a 'meta' property with only the identity. Older
qemu-server versions reject the new members and drop the whole property
on their next config write.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/QemuConfig.pm                         |   7 +
 src/PVE/QemuServer/MetaInfo.pm                |   2 +
 src/test/Makefile                             |   5 +-
 .../q35-windows-pinning-identity-only.conf    |   6 +
 ...q35-windows-pinning-identity-only.conf.cmd |  26 ++
 .../meta-identity-invalid.conf                |   6 +
 .../meta-identity-invalid.conf.strict.error   |   2 +
 .../meta-identity-invalid.conf                |   7 +
 .../parse-config-input/meta-identity.conf     |  20 ++
 src/test/run_guest_identity_tests.pl          | 259 ++++++++++++++++++
 src/test/run_parse_config_tests.pl            |   2 +-
 src/test/run_qemu_restore_config_tests.pl     |   3 +-
 .../create/qemu-server/401.conf               |  31 +++
 .../create/qemu-server/402.conf               |  31 +++
 .../rollback/qemu-server/401.conf             |  36 +++
 .../rollback/qemu-server/402.conf             |  35 +++
 .../create/qemu-server/401.conf               |  13 +
 .../create/qemu-server/402.conf               |  13 +
 .../rollback/qemu-server/401.conf             |  35 +++
 .../rollback/qemu-server/402.conf             |  34 +++
 src/test/snapshot-test.pm                     |  85 +++++-
 21 files changed, 644 insertions(+), 14 deletions(-)
 create mode 100644 src/test/cfg2cmd/q35-windows-pinning-identity-only.conf
 create mode 100644 src/test/cfg2cmd/q35-windows-pinning-identity-only.conf.cmd
 create mode 100644 src/test/parse-config-expected/meta-identity-invalid.conf
 create mode 100644 src/test/parse-config-expected/meta-identity-invalid.conf.strict.error
 create mode 100644 src/test/parse-config-input/meta-identity-invalid.conf
 create mode 100644 src/test/parse-config-input/meta-identity.conf
 create mode 100755 src/test/run_guest_identity_tests.pl
 create mode 100644 src/test/snapshot-expected/create/qemu-server/401.conf
 create mode 100644 src/test/snapshot-expected/create/qemu-server/402.conf
 create mode 100644 src/test/snapshot-expected/rollback/qemu-server/401.conf
 create mode 100644 src/test/snapshot-expected/rollback/qemu-server/402.conf
 create mode 100644 src/test/snapshot-input/create/qemu-server/401.conf
 create mode 100644 src/test/snapshot-input/create/qemu-server/402.conf
 create mode 100644 src/test/snapshot-input/rollback/qemu-server/401.conf
 create mode 100644 src/test/snapshot-input/rollback/qemu-server/402.conf

diff --git a/src/PVE/QemuConfig.pm b/src/PVE/QemuConfig.pm
index c84f10f8..29ec7c86 100644
--- a/src/PVE/QemuConfig.pm
+++ b/src/PVE/QemuConfig.pm
@@ -630,6 +630,13 @@ sub write_config {
     return $class->SUPER::write_config($vmid, $conf);
 }
 
+# the format of the 'meta' property includes the guest identity, see PVE::QemuServer::MetaInfo
+sub __identity_enabled {
+    my ($class) = @_;
+
+    return 1;
+}
+
 # END implemented abstract methods from PVE::AbstractConfig
 
 sub has_cloudinit {
diff --git a/src/PVE/QemuServer/MetaInfo.pm b/src/PVE/QemuServer/MetaInfo.pm
index b69e5a1c..399cd920 100644
--- a/src/PVE/QemuServer/MetaInfo.pm
+++ b/src/PVE/QemuServer/MetaInfo.pm
@@ -3,6 +3,7 @@ package PVE::QemuServer::MetaInfo;
 use strict;
 use warnings;
 
+use PVE::GuestIdentity;
 use PVE::JSONSchema;
 
 use PVE::QemuServer::Helpers;
@@ -20,6 +21,7 @@ our $meta_info_fmt = {
         pattern => '\d+(\.\d+)+',
         optional => 1,
     },
+    PVE::GuestIdentity::meta_format_properties()->%*,
 };
 
 sub parse_meta_info {
diff --git a/src/test/Makefile b/src/test/Makefile
index 3916179e..3c7865e5 100644
--- a/src/test/Makefile
+++ b/src/test/Makefile
@@ -1,6 +1,6 @@
 all: test
 
-test: test_snapshot test_cfg_to_cmd test_cfg_to_cmd_aarch64 test_hotplug test_hotplug_aarch64 test_pci_addr_conflicts test_pci_reservation test_qemu_img_convert test_migration test_restore_config test_parse_config test_memory test_raw_config_write test_api
+test: test_snapshot test_cfg_to_cmd test_cfg_to_cmd_aarch64 test_hotplug test_hotplug_aarch64 test_pci_addr_conflicts test_pci_reservation test_qemu_img_convert test_migration test_restore_config test_parse_config test_memory test_raw_config_write test_api test_guest_identity
 
 test_snapshot: run_snapshot_tests.pl
 	./run_snapshot_tests.pl
@@ -50,6 +50,9 @@ test_raw_config_write: run_raw_config_write_tests.pl
 test_api: run_api_tests.pl
 	./run_api_tests.pl
 
+test_guest_identity: run_guest_identity_tests.pl QemuServerTest/FakeCFS.pm
+	./run_guest_identity_tests.pl
+
 .PHONY: clean
 clean:
 	rm -rf MigrationTest/run
diff --git a/src/test/cfg2cmd/q35-windows-pinning-identity-only.conf b/src/test/cfg2cmd/q35-windows-pinning-identity-only.conf
new file mode 100644
index 00000000..5242ec13
--- /dev/null
+++ b/src/test/cfg2cmd/q35-windows-pinning-identity-only.conf
@@ -0,0 +1,6 @@
+# TEST: Windows without pinned machine and with only the guest identity as meta info stays on 5.1
+machine: q35
+meta: rtime=1762300000000,uid=abcdefghijklmnopqrst
+ostype: win11
+smbios1: uuid=7b10d7af-b932-4c66-b2c3-3996152ec465
+vmgenid: c773c261-d800-4348-9f5d-167fadd53cf8
diff --git a/src/test/cfg2cmd/q35-windows-pinning-identity-only.conf.cmd b/src/test/cfg2cmd/q35-windows-pinning-identity-only.conf.cmd
new file mode 100644
index 00000000..67d20b79
--- /dev/null
+++ b/src/test/cfg2cmd/q35-windows-pinning-identity-only.conf.cmd
@@ -0,0 +1,26 @@
+/usr/bin/kvm \
+  -id 8006 \
+  -name vm8006 \
+  -no-shutdown \
+  -chardev 'socket,id=qmp,path=/var/run/qemu-server/8006.qmp,server=on,wait=off' \
+  -object 'monitor-qmp,chardev=qmp,id=monitor-qmp' \
+  -chardev 'socket,id=qmp-event,path=/var/run/qmeventd.sock,reconnect-ms=5000' \
+  -object 'monitor-qmp,chardev=qmp-event,id=monitor-qmp-event' \
+  -pidfile /var/run/qemu-server/8006.pid \
+  -daemonize \
+  -smbios 'type=1,uuid=7b10d7af-b932-4c66-b2c3-3996152ec465' \
+  -smp '1,sockets=1,cores=1,maxcpus=1' \
+  -nodefaults \
+  -boot 'menu=on,strict=on,reboot-timeout=1000,splash=/usr/share/qemu-server/bootsplash.jpg' \
+  -vnc 'unix:/var/run/qemu-server/8006.vnc,password=on' \
+  -global 'kvm-pit.lost_tick_policy=discard' \
+  -cpu 'kvm64,-cet-ibt,-cet-ss,enforce,hv_ipi,hv_relaxed,hv_reset,hv_runtime,hv_spinlocks=0x1fff,hv_stimer,hv_synic,hv_time,hv_vapic,hv_vpindex,+kvm_pv_eoi,+kvm_pv_unhalt,+lahf_lm,+sep' \
+  -m 512 \
+  -readconfig /usr/share/qemu-server/pve-q35-4.0.cfg \
+  -device 'vmgenid,guid=c773c261-d800-4348-9f5d-167fadd53cf8' \
+  -device 'usb-tablet,id=tablet,bus=ehci.0,port=1' \
+  -device 'VGA,id=vga,bus=pcie.0,addr=0x1,edid=off' \
+  -device 'virtio-balloon-pci,id=balloon0,bus=pci.0,addr=0x3' \
+  -iscsi 'initiator-name=iqn.1993-08.org.debian:01:aabbccddeeff' \
+  -rtc 'driftfix=slew,base=localtime' \
+  -machine 'hpet=off,type=pc-q35-5.1+pve0'
diff --git a/src/test/parse-config-expected/meta-identity-invalid.conf b/src/test/parse-config-expected/meta-identity-invalid.conf
new file mode 100644
index 00000000..195514fa
--- /dev/null
+++ b/src/test/parse-config-expected/meta-identity-invalid.conf
@@ -0,0 +1,6 @@
+# VM with a guest uid that is not valid
+boot: order=scsi0
+cores: 2
+memory: 4096
+name: identity
+scsi0: local-lvm:vm-8006-disk-0,size=32G
diff --git a/src/test/parse-config-expected/meta-identity-invalid.conf.strict.error b/src/test/parse-config-expected/meta-identity-invalid.conf.strict.error
new file mode 100644
index 00000000..ae584c1f
--- /dev/null
+++ b/src/test/parse-config-expected/meta-identity-invalid.conf.strict.error
@@ -0,0 +1,2 @@
+vm 8006 - unable to parse value of 'meta' - format error
+uid: value does not match the regex pattern
diff --git a/src/test/parse-config-input/meta-identity-invalid.conf b/src/test/parse-config-input/meta-identity-invalid.conf
new file mode 100644
index 00000000..90e60197
--- /dev/null
+++ b/src/test/parse-config-input/meta-identity-invalid.conf
@@ -0,0 +1,7 @@
+# VM with a guest uid that is not valid
+boot: order=scsi0
+cores: 2
+memory: 4096
+meta: creation-qemu=10.1.2,ctime=1762000000,rtime=1762000000123,uid=ABCDEFGHIJKLMNOPQRST
+name: identity
+scsi0: local-lvm:vm-8006-disk-0,size=32G
diff --git a/src/test/parse-config-input/meta-identity.conf b/src/test/parse-config-input/meta-identity.conf
new file mode 100644
index 00000000..7a1e03be
--- /dev/null
+++ b/src/test/parse-config-input/meta-identity.conf
@@ -0,0 +1,20 @@
+# VM with guest identity
+boot: order=scsi0
+cores: 2
+memory: 4096
+meta: creation-qemu=10.1.2,ctime=1762000000,rtime=1762000000123,uid=abcdefghijklmnopqrst
+name: identity
+scsi0: local-lvm:vm-8006-disk-0,size=32G
+scsihw: virtio-scsi-single
+smbios1: uuid=7b4f2a1e-3c2d-4e5f-8a9b-0c1d2e3f4a5b
+
+[snap]
+boot: order=scsi0
+cores: 2
+memory: 4096
+meta: creation-qemu=10.1.2,ctime=1762000000,rtime=1762000000123,uid=abcdefghijklmnopqrst
+name: identity
+scsi0: local-lvm:vm-8006-disk-0,size=32G
+scsihw: virtio-scsi-single
+smbios1: uuid=7b4f2a1e-3c2d-4e5f-8a9b-0c1d2e3f4a5b
+snaptime: 1762000100
diff --git a/src/test/run_guest_identity_tests.pl b/src/test/run_guest_identity_tests.pl
new file mode 100755
index 00000000..e80609d9
--- /dev/null
+++ b/src/test/run_guest_identity_tests.pl
@@ -0,0 +1,259 @@
+#!/usr/bin/perl
+
+# Tests the guest identity of VM configs through the real config class methods, with a fake cluster
+# filesystem, see QemuServerTest::FakeCFS.
+
+use strict;
+use warnings;
+
+use lib qw(.. .);
+
+use File::Temp qw(tempdir);
+use Test::MockModule;
+use Test::More;
+
+use PVE::JSONSchema;
+use PVE::QemuConfig;
+use PVE::QemuConfig::NoWrite;
+use PVE::QemuServer;
+use PVE::QemuServer::MetaInfo;
+
+use QemuServerTest::FakeCFS;
+
+my $UID_A = 'abcdefghijklmnopqrst';
+my $UID_B = 'bbbbbbbbbbbbbbbbbbbb';
+
+my $helpers_module = Test::MockModule->new('PVE::QemuServer::Helpers');
+$helpers_module->mock(kvm_user_version => sub { return '10.1.2'; });
+
+sub configs { return $QemuServerTest::FakeCFS::configs; }
+sub generated_uid { return QemuServerTest::FakeCFS::generated_uid(@_); }
+sub published_identity { return QemuServerTest::FakeCFS::published_identity(@_); }
+
+sub load_meta {
+    my ($vmid) = @_;
+    return PVE::QemuServer::MetaInfo::parse_meta_info(PVE::QemuConfig->load_config($vmid)->{meta});
+}
+
+subtest 'meta format' => sub {
+    my $meta =
+        'creation-qemu=10.1.2,ctime=1700000000,rtime=1700000000123,uid=abcdefghijklmnopqrst';
+
+    is_deeply(
+        PVE::QemuServer::MetaInfo::parse_meta_info($meta),
+        {
+            'creation-qemu' => '10.1.2',
+            ctime => 1700000000,
+            rtime => 1700000000123,
+            uid => $UID_A,
+        },
+        'identity members get parsed',
+    );
+    is(
+        PVE::JSONSchema::print_property_string(
+            PVE::QemuServer::MetaInfo::parse_meta_info($meta),
+            $PVE::QemuServer::MetaInfo::meta_info_fmt,
+        ),
+        $meta,
+        'printing the parsed property gives the same string',
+    );
+
+    for my $invalid (
+        'uid=ABCDEFGHIJKLMNOPQRST', 'uid=abcdefghijklmnopqrs', 'rtime=-1', 'rtime=1x',
+    ) {
+        eval {
+            PVE::JSONSchema::parse_property_string(
+                $PVE::QemuServer::MetaInfo::meta_info_fmt, $invalid,
+            );
+        };
+        ok($@, "'$invalid' is rejected");
+    }
+
+    # versions before the identity members only know these two, and drop the whole property
+    my $old_fmt = {
+        ctime => $PVE::QemuServer::MetaInfo::meta_info_fmt->{ctime},
+        'creation-qemu' => $PVE::QemuServer::MetaInfo::meta_info_fmt->{'creation-qemu'},
+    };
+    eval { PVE::JSONSchema::parse_property_string($old_fmt, $meta) };
+    like(
+        $@,
+        qr/property is not defined in schema/,
+        'format without identity members rejects it',
+    );
+};
+
+subtest 'identities are enabled, but not for writing temporary configs' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    ok(PVE::QemuConfig->__identity_enabled(), 'enabled for PVE::QemuConfig');
+
+    my $conf = { name => 'template-cmd' };
+    PVE::QemuConfig::NoWrite->mark_config($conf);
+    eval { PVE::QemuConfig->write_config(100, $conf) };
+    is($@, "refusing to write temporary configuration\n", 'NoWrite refuses');
+    eval { PVE::QemuConfig::NoWrite->write_config(100, $conf) };
+    is(
+        $@,
+        "refusing to write temporary configuration\n",
+        'NoWrite refuses when called directly',
+    );
+    is_deeply(configs(), {}, 'nothing written');
+    is($QemuServerTest::FakeCFS::generated, 0, 'no identity generated');
+};
+
+subtest 'config writes keep the published identity' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    PVE::QemuConfig->write_config(100, { memory => 512, meta => "rtime=1,uid=$UID_B" });
+    is_deeply(
+        published_identity(100),
+        { uid => generated_uid(1), rtime => 1700000000000 },
+        'first write ignores a carried identity and generates one',
+    );
+    like(configs()->{100}, qr/^meta: rtime=1700000000000,uid=\w+$/m,
+        'written as meta property');
+
+    $QemuServerTest::FakeCFS::now_ms = 1800000000000;
+
+    my $conf = PVE::QemuConfig->load_config(100);
+    $conf->{meta} = "creation-qemu=9.2.0,ctime=1600000000,rtime=1,uid=$UID_B";
+    PVE::QemuConfig->write_config(100, $conf);
+    is_deeply(
+        load_meta(100),
+        {
+            'creation-qemu' => '9.2.0',
+            ctime => 1600000000,
+            rtime => 1700000000000,
+            uid => generated_uid(1),
+        },
+        'foreign identity replaced by the published one, other members kept',
+    );
+
+    $conf = PVE::QemuConfig->load_config(100);
+    delete $conf->{meta};
+    PVE::QemuConfig->write_config(100, $conf);
+    is_deeply(
+        load_meta(100),
+        { rtime => 1700000000000, uid => generated_uid(1) },
+        'identity kept when the property is gone',
+    );
+
+    configs()->{101} = "memory: 512\nmeta: creation-qemu=8.0.2,ctime=1500000000\n";
+    $conf = PVE::QemuConfig->load_config(101);
+    $conf->{name} = 'old';
+    PVE::QemuConfig->write_config(101, $conf);
+    is_deeply(
+        load_meta(101),
+        {
+            'creation-qemu' => '8.0.2',
+            ctime => 1500000000,
+            rtime => 1800000000000,
+            uid => generated_uid(2),
+        },
+        'existing guest without identity gets one on its first write',
+    );
+};
+
+subtest 'create' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    my $reservation = PVE::QemuConfig->create_and_lock_config(100);
+    is_deeply(
+        $reservation,
+        {
+            existed => 0,
+            identity => undef,
+            pending => undef,
+            reserved => { uid => generated_uid(1), rtime => 1700000000000 },
+        },
+        'reservation publishes a new identity',
+    );
+
+    $QemuServerTest::FakeCFS::now_ms = 1700000005000;
+
+    my $conf = { memory => 512, meta => PVE::QemuServer::MetaInfo::new_meta_info_string() };
+    PVE::QemuConfig->write_config(100, $conf);
+    my $meta = load_meta(100);
+    is_deeply(
+        [$meta->@{qw(creation-qemu uid rtime)}],
+        ['10.1.2', generated_uid(1), 1700000000000],
+        'final config keeps the reserved identity next to the creation info',
+    );
+    ok($meta->{ctime}, 'creation time set');
+};
+
+subtest 'clone' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    configs()->{100} = "memory: 512\nmeta: creation-qemu=9.2.0,ctime=1600000000,"
+        . "rtime=1600000000000,uid=$UID_A\nname: source\n";
+
+    for my $snapshot (0, 1) {
+        my $newid = 200 + $snapshot;
+        my $source = PVE::QemuConfig->load_config(100);
+        if ($snapshot) {
+            # a snapshot can carry any identity, the clone must not take it over either
+            $source = { memory => 256, meta => "rtime=1,uid=$UID_B" };
+        }
+
+        PVE::QemuConfig->create_and_lock_config($newid, 0, 'clone');
+
+        # like the clone API, which copies everything but some snapshot related keys
+        my $newconf = { $source->%*, lock => 'clone', name => "clone-$newid" };
+        delete $newconf->{digest};
+        PVE::QemuConfig->write_config($newid, $newconf);
+        delete $newconf->{lock};
+        PVE::QemuConfig->write_config($newid, $newconf);
+
+        my $uid = generated_uid(1 + $snapshot);
+        is(published_identity($newid)->{uid}, $uid, "clone $newid has a new uid");
+        is_deeply(
+            load_meta($newid),
+            $snapshot
+            ? { rtime => 1700000000000, uid => $uid }
+            : {
+                'creation-qemu' => '9.2.0',
+                ctime => 1600000000,
+                rtime => 1700000000000,
+                uid => $uid,
+            },
+            "clone $newid keeps the creation info of its source",
+        );
+    }
+    is(published_identity(100)->{uid}, $UID_A, 'source keeps its uid');
+};
+
+subtest 'importovf' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    require PVE::CLI::qm;
+
+    my $tmpdir = tempdir('importovf-XXXXXX', DIR => '.', CLEANUP => 1);
+    my $manifest = "$tmpdir/test.ovf";
+    PVE::Tools::file_set_contents($manifest, "<ovf/>\n");
+
+    my $storage_module = Test::MockModule->new('PVE::Storage');
+    $storage_module->mock(
+        config => sub { return {}; },
+        storage_check_enabled => sub { return {}; },
+    );
+    my $ovf_module = Test::MockModule->new('PVE::GuestImport::OVF');
+    $ovf_module->mock(
+        parse_ovf => sub {
+            return { qm => { name => 'imported', memory => 1024, cores => 2 }, disks => [] };
+        },
+    );
+
+    PVE::CLI::qm->importovf({ vmid => 100, manifest => $manifest, storage => 'local' });
+
+    my $conf = PVE::QemuConfig->load_config(100);
+    is($conf->{name}, 'imported', 'config imported');
+    ok(!defined($conf->{lock}), 'create lock removed');
+    is_deeply(
+        published_identity(100),
+        { uid => generated_uid(1), rtime => 1700000000000 },
+        'imported VM got a new identity on reservation and kept it',
+    );
+};
+
+done_testing();
diff --git a/src/test/run_parse_config_tests.pl b/src/test/run_parse_config_tests.pl
index f68abc06..69bb96ad 100755
--- a/src/test/run_parse_config_tests.pl
+++ b/src/test/run_parse_config_tests.pl
@@ -25,7 +25,7 @@ my $INPUT_DIR = './parse-config-input';
 my $EXPECTED_DIR = './parse-config-expected';
 
 # NOTE update when you add/remove tests
-plan tests => 2 * 10;
+plan tests => 2 * 12;
 
 sub run_tests {
     my ($strict) = @_;
diff --git a/src/test/run_qemu_restore_config_tests.pl b/src/test/run_qemu_restore_config_tests.pl
index e6739d66..dd8629f4 100755
--- a/src/test/run_qemu_restore_config_tests.pl
+++ b/src/test/run_qemu_restore_config_tests.pl
@@ -289,7 +289,8 @@ sub restore_api {
     return ($err, $output);
 }
 
-my $TARGET_CONF = "memory: 1024\nmeta: creation-qemu=10.0.0,ctime=1700000000\nname: target\n";
+my $TARGET_CONF = "memory: 1024\nmeta: creation-qemu=10.0.0,ctime=1700000000,"
+    . "rtime=1700000000000,uid=tttttttttttttttttttt\nname: target\n";
 my $NOT_CLEANED_UP = qr/VM 100 state is NOT cleaned up/;
 
 for my $type (sort keys $ARCHIVES->%*) {
diff --git a/src/test/snapshot-expected/create/qemu-server/401.conf b/src/test/snapshot-expected/create/qemu-server/401.conf
new file mode 100644
index 00000000..87aadf80
--- /dev/null
+++ b/src/test/snapshot-expected/create/qemu-server/401.conf
@@ -0,0 +1,31 @@
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+memory: 8192
+meta: creation-qemu=10.0.0,ctime=1700000000,rtime=1700000000000,uid=abcdefghijklmnopqrst
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+parent: test
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+sockets: 1
+vga: qxl
+
+[test]
+#test comment
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+memory: 8192
+meta: creation-qemu=10.0.0,ctime=1700000000,rtime=1700000000000,uid=abcdefghijklmnopqrst
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+snaptime: 1234567890
+sockets: 1
+vga: qxl
diff --git a/src/test/snapshot-expected/create/qemu-server/402.conf b/src/test/snapshot-expected/create/qemu-server/402.conf
new file mode 100644
index 00000000..f5bccd87
--- /dev/null
+++ b/src/test/snapshot-expected/create/qemu-server/402.conf
@@ -0,0 +1,31 @@
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+memory: 8192
+meta: creation-qemu=8.0.2,ctime=1600000000,rtime=1234567890123,uid=aerukz4jvpg66ajdivty
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+parent: test
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+sockets: 1
+vga: qxl
+
+[test]
+#test comment
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+memory: 8192
+meta: creation-qemu=8.0.2,ctime=1600000000
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+snaptime: 1234567890
+sockets: 1
+vga: qxl
diff --git a/src/test/snapshot-expected/rollback/qemu-server/401.conf b/src/test/snapshot-expected/rollback/qemu-server/401.conf
new file mode 100644
index 00000000..6215ce26
--- /dev/null
+++ b/src/test/snapshot-expected/rollback/qemu-server/401.conf
@@ -0,0 +1,36 @@
+# this is a description
+agent: 1
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+memory: 8192
+meta: creation-qemu=9.2.0,ctime=1600000000,rtime=1700000000000,uid=abcdefghijklmnopqrst
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+parent: test
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+sockets: 1
+vga: qxl
+
+[test]
+#test comment
+agent: 1
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+machine: q35
+memory: 8192
+meta: creation-qemu=9.2.0,ctime=1600000000,rtime=1600000000000,uid=bbbbbbbbbbbbbbbbbbbb
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+snaptime: 1234567890
+sockets: 1
+vga: qxl
+vmstate: somestorage:state-volume
diff --git a/src/test/snapshot-expected/rollback/qemu-server/402.conf b/src/test/snapshot-expected/rollback/qemu-server/402.conf
new file mode 100644
index 00000000..a10bfa13
--- /dev/null
+++ b/src/test/snapshot-expected/rollback/qemu-server/402.conf
@@ -0,0 +1,35 @@
+# this is a description
+agent: 1
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+memory: 8192
+meta: rtime=1700000000000,uid=abcdefghijklmnopqrst
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+parent: test
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+sockets: 1
+vga: qxl
+
+[test]
+#test comment
+agent: 1
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+machine: q35
+memory: 8192
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+snaptime: 1234567890
+sockets: 1
+vga: qxl
+vmstate: somestorage:state-volume
diff --git a/src/test/snapshot-input/create/qemu-server/401.conf b/src/test/snapshot-input/create/qemu-server/401.conf
new file mode 100644
index 00000000..41ccdae5
--- /dev/null
+++ b/src/test/snapshot-input/create/qemu-server/401.conf
@@ -0,0 +1,13 @@
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+memory: 8192
+meta: creation-qemu=10.0.0,ctime=1700000000,rtime=1700000000000,uid=abcdefghijklmnopqrst
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+sockets: 1
+vga: qxl
diff --git a/src/test/snapshot-input/create/qemu-server/402.conf b/src/test/snapshot-input/create/qemu-server/402.conf
new file mode 100644
index 00000000..e03717b6
--- /dev/null
+++ b/src/test/snapshot-input/create/qemu-server/402.conf
@@ -0,0 +1,13 @@
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+memory: 8192
+meta: creation-qemu=8.0.2,ctime=1600000000
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+sockets: 1
+vga: qxl
diff --git a/src/test/snapshot-input/rollback/qemu-server/401.conf b/src/test/snapshot-input/rollback/qemu-server/401.conf
new file mode 100644
index 00000000..7895e0df
--- /dev/null
+++ b/src/test/snapshot-input/rollback/qemu-server/401.conf
@@ -0,0 +1,35 @@
+# this is a description
+agent: 1
+bootdisk: ide2
+cores: 2
+ide0: local:snapshotable-disk-1,size=32G
+ide2: none,media=cdrom
+memory: 4096
+meta: creation-qemu=10.0.0,ctime=1700000000,rtime=1700000000000,uid=abcdefghijklmnopqrst
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+parent: test
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+sockets: 2
+
+[test]
+#test comment
+agent: 1
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+machine: q35
+memory: 8192
+meta: creation-qemu=9.2.0,ctime=1600000000,rtime=1600000000000,uid=bbbbbbbbbbbbbbbbbbbb
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+snaptime: 1234567890
+sockets: 1
+vga: qxl
+vmstate: somestorage:state-volume
diff --git a/src/test/snapshot-input/rollback/qemu-server/402.conf b/src/test/snapshot-input/rollback/qemu-server/402.conf
new file mode 100644
index 00000000..0fa7fe51
--- /dev/null
+++ b/src/test/snapshot-input/rollback/qemu-server/402.conf
@@ -0,0 +1,34 @@
+# this is a description
+agent: 1
+bootdisk: ide2
+cores: 2
+ide0: local:snapshotable-disk-1,size=32G
+ide2: none,media=cdrom
+memory: 4096
+meta: creation-qemu=10.0.0,ctime=1700000000,rtime=1700000000000,uid=abcdefghijklmnopqrst
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+parent: test
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+sockets: 2
+
+[test]
+#test comment
+agent: 1
+bootdisk: ide0
+cores: 4
+ide0: local:snapshotable-disk-1,discard=on,size=32G
+ide2: none,media=cdrom
+machine: q35
+memory: 8192
+name: win
+net0: e1000=12:34:56:78:90:12,bridge=somebr0,firewall=1
+numa: 0
+ostype: win7
+smbios1: uuid=01234567-890a-bcde-f012-34567890abcd
+snaptime: 1234567890
+sockets: 1
+vga: qxl
+vmstate: somestorage:state-volume
diff --git a/src/test/snapshot-test.pm b/src/test/snapshot-test.pm
index 44e55d6a..345accea 100644
--- a/src/test/snapshot-test.pm
+++ b/src/test/snapshot-test.pm
@@ -5,6 +5,7 @@ use warnings;
 
 use lib qw(..);
 
+use PVE::GuestHelpers;
 use PVE::Storage;
 use PVE::Storage::Plugin;
 use PVE::QemuServer;
@@ -30,6 +31,9 @@ my $freeze_possible;
 my $stop_possible;
 my $save_vmstate_works;
 my $vm_mon = {};
+my $real_write_config;
+
+my $original_write_config = \&PVE::QemuConfig::write_config;
 
 # Mocked methods
 
@@ -296,6 +300,13 @@ sub cfs_config_path {
     return "snapshot-working/$node/qemu-server/$vmid.conf";
 }
 
+# the same file that mocked_get_config reads, so that nothing looks at the host's /etc/pve
+sub config_file {
+    my ($class, $vmid, $node) = @_;
+
+    return $class->cfs_config_path($vmid, $node);
+}
+
 sub load_config {
     my ($class, $vmid, $node) = @_;
 
@@ -310,18 +321,10 @@ sub load_config {
 sub write_config {
     my ($class, $vmid, $conf) = @_;
 
-    my $filename = $class->cfs_config_path($vmid);
-
-    if ($conf->{snapshots}) {
-        foreach my $snapname (keys %{ $conf->{snapshots} }) {
-            $conf->{snapshots}->{$snapname}->{snaptime} = "1234567890"
-                if $conf->{snapshots}->{$snapname}->{snaptime};
-        }
-    }
+    # the real method with the guest identity handling, which writes through mocked_cfs_write_file
+    return $original_write_config->($class, $vmid, $conf) if $real_write_config;
 
-    my $raw = PVE::QemuServer::write_vm_config($filename, $conf);
-
-    PVE::Tools::file_set_contents($filename, $raw);
+    mocked_cfs_write_file($class->cfs_config_path($vmid), $conf);
 }
 
 sub has_feature {
@@ -345,6 +348,31 @@ sub assert_config_exists_on_node {
 }
 # END mocked PVE::QemuConfig methods
 
+# BEGIN mocked PVE::Cluster methods
+
+sub mocked_get_config {
+    my ($path) = @_;
+
+    return -e $path ? PVE::Tools::file_get_contents($path) : undef;
+}
+
+sub mocked_cfs_write_file {
+    my ($filename, $conf) = @_;
+
+    if ($conf->{snapshots}) {
+        foreach my $snapname (keys %{ $conf->{snapshots} }) {
+            $conf->{snapshots}->{$snapname}->{snaptime} = "1234567890"
+                if $conf->{snapshots}->{$snapname}->{snaptime};
+        }
+    }
+
+    my $raw = PVE::QemuServer::write_vm_config($filename, $conf);
+
+    PVE::Tools::file_set_contents($filename, $raw);
+}
+
+# END mocked PVE::Cluster methods
+
 # BEGIN mocked PVE::QemuServer::Helpers methods
 
 sub vm_running_locally {
@@ -441,6 +469,19 @@ sub vm_stop {
 PVE::Tools::run_command("rm -rf snapshot-working");
 PVE::Tools::run_command("cp -a snapshot-input snapshot-working");
 
+$PVE::GuestHelpers::lockdir = "snapshot-working/lock";
+
+my $cluster_module = Test::MockModule->new('PVE::Cluster');
+$cluster_module->mock('get_config', \&mocked_get_config);
+$cluster_module->mock('cfs_write_file', \&mocked_cfs_write_file);
+
+my $guest_identity_module = Test::MockModule->new('PVE::GuestIdentity');
+$guest_identity_module->mock(
+    '__random_bytes',
+    sub { return pack('H26', '0123456789abcdef0123456789'); },
+);
+$guest_identity_module->mock('__time_ms', sub { return 1234567890123; });
+
 my $qemu_migrate_helpers_module = Test::MockModule->new('PVE::QemuMigrate::Helpers');
 $qemu_migrate_helpers_module->mock('set_migration_caps', \&set_migration_caps);
 
@@ -453,6 +494,7 @@ $qemu_monitor_module->mock('qmp_cmd', \&qmp_cmd);
 my $qemu_config_module = Test::MockModule->new('PVE::QemuConfig');
 $qemu_config_module->mock('config_file_lock', \&config_file_lock);
 $qemu_config_module->mock('cfs_config_path', \&cfs_config_path);
+$qemu_config_module->mock('config_file', \&config_file);
 $qemu_config_module->mock('load_config', \&load_config);
 $qemu_config_module->mock('write_config', \&write_config);
 $qemu_config_module->mock('has_feature', \&has_feature);
@@ -641,6 +683,16 @@ testcase_create("303", "test", 1, "test comment", "storage activation failed\n\n
 
 $activate_storage_possible = 1;
 
+$real_write_config = 1;
+
+printf("Successful snapshot_create keeping the guest identity\n");
+testcase_create("401", "test", 0, "test comment", "", { "local:snapshotable-disk-1" => "test" });
+
+printf("Successful snapshot_create assigning a guest identity to a config without one\n");
+testcase_create("402", "test", 0, "test comment", "", { "local:snapshotable-disk-1" => "test" });
+
+$real_write_config = 0;
+
 $nodename = "delete";
 printf("\n");
 printf("Running delete tests\n");
@@ -777,6 +829,17 @@ testcase_rollback("303", "test", "storage activation failed\n");
 
 $activate_storage_possible = 1;
 
+$real_write_config = 1;
+
+printf("Successful snapshot_rollback keeping the current guest identity, not the snapshot's\n");
+testcase_rollback("401", "test", "", { "local:snapshotable-disk-1" => "test" });
+
+printf(
+    "Successful snapshot_rollback to a snapshot without meta info, keeping the guest identity\n");
+testcase_rollback("402", "test", "", { "local:snapshotable-disk-1" => "test" });
+
+$real_write_config = 0;
+
 done_testing();
 
 1;
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH qemu-server 15/34] restore: take over the guest uid from the backup where possible
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (13 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH qemu-server 14/34] fix #7846: config: add a guest identity to the 'meta' property Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-17 15:17   ` Dominik Csapak
  2026-11-16  0:46 ` [PATCH qemu-server 16/34] api: remote migration: take over the guest uid from the source Thomas Lamprecht
                   ` (20 subsequent siblings)
  35 siblings, 1 reply; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

A restore to an unused VMID, or over a VM without an identity, should
keep the uid of the backup if no other guest in the cluster uses it.
Take over that uid through the cluster-wide check of pve-guest-common
after the data is restored and the final config is written, while
holding the config lock. A VM that already had an identity keeps it,
and 'unique' prevents taking over the uid. Log the outcome, and only
warn if taking over the uid fails, as the restored VM has an identity
of its own.

Refuse to restore a backup with a different uid over an existing VM
unless 'allow-identity-mismatch' is set in the create API or qmrestore.
This is independent of 'force', which permits overwriting the VM. With
the override, the VM keeps its identity, unless it has the uid of the
backup as pending uid from an unfinished restore.

For PBS, backup providers and VMA, compare the uids before resetting
the replication state, restoring the firewall config or replacing the
data of the target. For VMA this also works for standard input, through
the header callback. Read the uid from the config that the restore
itself uses, not from the best-effort extraction of the API, and ignore
unknown members of 'meta', so that the uid of a backup from a newer
version is not lost when the property fails to parse.

Take over the uid only after the live phase, the conversion to a
template and, with 'unique', the registration of the new MAC addresses.
A failed restore must not take the uid and so keep a retry at another
VMID from getting it.

For a retry over a VM left behind by an unfinished restore to work,
record the uid of the backup as a pending change of 'meta'. Record it
after the uid check if the restore could take the uid over, also with
'unique', and keep it in all configs that the restore writes. A VM
with that pending uid can be restored over without the override, and
without 'unique' the retry takes the uid over if no other guest uses
it. A pending uid does not count as in use.

Taking over the uid removes the pending uid, whatever the outcome. If
the cluster-wide lock cannot be taken, it stays for a retry. Starting
the VM for a live restore keeps it while the 'create' lock is held.
Otherwise, applying pending changes drops it, and a clone does not get
it.

Legacy tar archives predate guest identities and get no uid check.
Their config is only available after the data is restored, so only the
restored config can carry a pending uid.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/API2/Qemu.pm                      |  18 +
 src/PVE/CLI/qmrestore.pm                  |   7 +
 src/PVE/QemuServer.pm                     | 142 +++++-
 src/test/QemuServerTest/FakeCFS.pm        |   3 +
 src/test/restore-config-expected/150.conf |   9 +
 src/test/restore-config-input/150.conf    |  10 +
 src/test/run_api_tests.pl                 |  13 +
 src/test/run_guest_identity_tests.pl      |  77 +++
 src/test/run_qemu_restore_config_tests.pl | 559 +++++++++++++++++++++-
 9 files changed, 828 insertions(+), 10 deletions(-)
 create mode 100644 src/test/restore-config-expected/150.conf
 create mode 100644 src/test/restore-config-input/150.conf

diff --git a/src/PVE/API2/Qemu.pm b/src/PVE/API2/Qemu.pm
index 28e8389a..395dc334 100644
--- a/src/PVE/API2/Qemu.pm
+++ b/src/PVE/API2/Qemu.pm
@@ -1241,6 +1241,15 @@ __PACKAGE__->register_method({
                     description => "Assign a unique random ethernet address.",
                     requires => 'archive',
                 },
+                'allow-identity-mismatch' => {
+                    optional => 1,
+                    type => 'boolean',
+                    description => "Allow to overwrite an existing VM with a backup of another"
+                        . " guest, as detected by a different 'uid' in 'meta'. Unless the VM is"
+                        . " left over from an unfinished restore of the same backup, it keeps its"
+                        . " own uid.",
+                    requires => 'archive',
+                },
                 'live-restore' => {
                     optional => 1,
                     type => 'boolean',
@@ -1309,6 +1318,7 @@ __PACKAGE__->register_method({
         my $ha_managed = extract_param($param, 'ha-managed');
         my $storage = extract_param($param, 'storage');
         my $unique = extract_param($param, 'unique');
+        my $allow_identity_mismatch = extract_param($param, 'allow-identity-mismatch');
         my $live_restore = extract_param($param, 'live-restore');
         my $extraction_storage = extract_param($param, 'import-working-storage');
 
@@ -1436,6 +1446,8 @@ __PACKAGE__->register_method({
                     live => $live_restore,
                     override_conf => $param,
                     progress => $restore_progress,
+                    reservation => $reservation,
+                    'allow-identity-mismatch' => $allow_identity_mismatch,
                 };
                 if (my $volid = $archive->{volid}) {
                     # best effort, real check is after restoring!
@@ -1491,6 +1503,8 @@ __PACKAGE__->register_method({
 
                 PVE::QemuServer::Network::create_ifaces_ipams_ips($restored_conf, $vmid)
                     if $unique;
+
+                PVE::QemuServer::restore_adopt_identity($vmid, $restore_options);
             };
 
             my $restore_locked = sub {
@@ -4652,6 +4666,10 @@ __PACKAGE__->register_method({
                         next if PVE::QemuServer::drive_is_cloudinit($drive);
                         push @$vollist, $volid;
                     }
+                } elsif ($opt eq 'pending') {
+                    # a pending uid only belongs to the source, see PVE::GuestIdentity
+                    $newconf->{pending} = { $value->%* };
+                    PVE::GuestIdentity::set_pending_uid($newconf, undef);
                 } else {
                     # copy everything else
                     $newconf->{$opt} = $value;
diff --git a/src/PVE/CLI/qmrestore.pm b/src/PVE/CLI/qmrestore.pm
index abfa2de7..d49e8332 100755
--- a/src/PVE/CLI/qmrestore.pm
+++ b/src/PVE/CLI/qmrestore.pm
@@ -54,6 +54,13 @@ __PACKAGE__->register_method({
                 type => 'boolean',
                 description => "Assign a unique random ethernet address.",
             },
+            'allow-identity-mismatch' => {
+                optional => 1,
+                type => 'boolean',
+                description => "Allow to overwrite an existing VM with a backup of another"
+                    . " guest, as detected by a different 'uid' in 'meta'. Unless the VM is left"
+                    . " over from an unfinished restore of the same backup, it keeps its own uid.",
+            },
             pool => {
                 optional => 1,
                 type => 'string',
diff --git a/src/PVE/QemuServer.pm b/src/PVE/QemuServer.pm
index 9ffc11e8..86fc4b68 100644
--- a/src/PVE/QemuServer.pm
+++ b/src/PVE/QemuServer.pm
@@ -32,6 +32,7 @@ use PVE::DataCenterConfig;
 use PVE::Exception qw(raise raise_param_exc);
 use PVE::Format qw(render_duration render_bytes);
 use PVE::GuestHelpers qw(safe_string_ne safe_num_ne safe_boolean_ne);
+use PVE::GuestIdentity;
 use PVE::Mapping::Dir;
 use PVE::Mapping::PCI;
 use PVE::Mapping::USB;
@@ -4427,8 +4428,8 @@ for my $opt (keys %$confdesc_cloudinit) {
     $fast_plug_option->{$opt} = 1;
 }
 
-# 'meta' is read-only, so only a manual edit or an older version can have queued a change of it.
-# Drop such a change instead of applying it.
+# 'meta' is read-only, so only a manual edit, an older version, or an unfinished restore, see
+# restore_pending_uid, can have queued a change of it. Drop such a change instead of applying it.
 my sub drop_pending_meta {
     my ($conf) = @_;
 
@@ -4847,6 +4848,12 @@ sub vmconfig_apply_pending {
 
     return if !scalar(keys %{ $conf->{pending} });
 
+    # a restore keeps its pending uid while it holds the 'create' lock, also when it starts the VM
+    # for a live restore, and removes it itself, see restore_pending_uid
+    my $restore_uid =
+        ($conf->{lock} // '') eq 'create' ? PVE::GuestIdentity::get_pending_uid($conf) : undef;
+    PVE::GuestIdentity::set_pending_uid($conf, undef) if defined($restore_uid);
+
     drop_pending_meta($conf);
 
     my $add_apply_error = sub {
@@ -4956,6 +4963,8 @@ sub vmconfig_apply_pending {
         }
     }
 
+    PVE::GuestIdentity::set_pending_uid($conf, $restore_uid) if defined($restore_uid);
+
     # write all changes at once to avoid unnecessary i/o
     PVE::QemuConfig->write_config($vmid, $conf);
     if ($generate_cloudinit) {
@@ -6718,6 +6727,107 @@ sub restore_merge_config {
     return $backup_conf;
 }
 
+# Returns the guest identity in the raw config of a backup, undef if it has none. Only looks at the
+# 'meta' property of the top-level section, so that members unknown to this version, which make the
+# config parser drop the whole property, do not hide the identity.
+my sub restore_backup_identity {
+    my ($backup_conf_raw) = @_;
+
+    my $meta;
+    for my $line (split(/\n/, $backup_conf_raw)) {
+        last if $line =~ m/^\[/;
+        $meta = $1 if $line =~ m/^meta:\s*(.*?)\s*$/;
+    }
+
+    return PVE::GuestIdentity::parse_identity($meta);
+}
+
+# Refuses to restore a backup over a VM that has another guest identity, as that is most likely a
+# backup of another guest, unless 'allow-identity-mismatch' is set. A VM with the uid of the backup
+# as pending uid is a leftover of an earlier restore of it, see restore_pending_uid. Must run before
+# anything of the target VM changes. Returns the guest identity of the backup.
+sub restore_check_identity {
+    my ($vmid, $backup_conf_raw, $opts) = @_;
+
+    my $backup = restore_backup_identity($backup_conf_raw);
+    my $reservation = $opts->{reservation};
+    my $target = $reservation && $reservation->{identity};
+
+    if (
+        $backup
+        && $target
+        && !PVE::GuestIdentity::uid_matches_target($reservation, $backup->{uid})
+    ) {
+        die "backup belongs to another guest: its uid '$backup->{uid}' differs from uid"
+            . " '$target->{uid}' of the existing VM $vmid - use 'allow-identity-mismatch' to"
+            . " overwrite the VM anyway\n"
+            if !$opts->{'allow-identity-mismatch'};
+
+        print "guest identity: ignoring backup uid $backup->{uid}, VM $vmid keeps uid"
+            . " $target->{uid}\n";
+    }
+
+    return $backup;
+}
+
+# Keeps the guest identity of the backup in $opts for restore_adopt_identity. Returns its uid if the
+# restore could take it over at its end, see PVE::GuestIdentity::adoptable_uid. Until then, the
+# restore keeps it as pending uid of the VM, so that a VM left behind by a failure or an abort of
+# the restore still has it for a retry, see restore_write_config. That holds with 'unique' too,
+# which only keeps the restore itself from taking the uid over.
+my sub restore_pending_uid {
+    my ($backup_identity, $opts) = @_;
+
+    my $uid = $backup_identity && $backup_identity->{uid};
+    $opts->{'backup-identity'} = $backup_identity;
+    $opts->{'pending-uid'} = PVE::GuestIdentity::adoptable_uid($opts->{reservation}, $uid);
+
+    return $opts->{'pending-uid'};
+}
+
+# Writes the pending uid of the restore into the config of the VM, if there is one, see
+# restore_pending_uid. Must run right after restore_check_identity.
+my sub restore_record_pending_uid {
+    my ($vmid, $backup_identity, $opts) = @_;
+
+    my $uid = restore_pending_uid($backup_identity, $opts);
+    PVE::QemuConfig->record_pending_uid($vmid, $uid) if defined($uid);
+}
+
+# Writes $conf, a config that the restore assembled itself, like a temporary or the restored one,
+# with the pending uid of the restore, see restore_pending_uid.
+my sub restore_write_config {
+    my ($vmid, $conf, $opts) = @_;
+
+    PVE::GuestIdentity::set_pending_uid($conf, $opts->{'pending-uid'});
+    PVE::QemuConfig->write_config($vmid, $conf);
+}
+
+# Takes over the uid of the backup for the restored VM where the identity rules allow it, see
+# PVE::GuestIdentity::adopt, which also removes the pending uid. Must be the last step of a
+# successful restore, with the config lock still held, so that a failure before leaves the pending
+# uid behind. A failure only warns, as the restored VM keeps the identity of its reservation.
+sub restore_adopt_identity {
+    my ($vmid, $opts) = @_;
+
+    my $backup_identity = $opts->{'backup-identity'};
+    my $uid = $opts->{unique} ? undef : $backup_identity && $backup_identity->{uid};
+
+    my $res =
+        eval { PVE::GuestIdentity::adopt('PVE::QemuConfig', $vmid, $uid, $opts->{reservation}); };
+    if (my $err = $@) {
+        my $kept = $opts->{reservation}->{reserved}->{uid} // 'none';
+        my $msg =
+            defined($uid)
+            ? "unable to adopt backup uid $uid, keeping uid $kept"
+            : "keeping uid $kept";
+        log_warn("guest identity: $msg - $err");
+        return;
+    }
+
+    print PVE::GuestIdentity::adopt_result_message($res, 'backup') . "\n";
+}
+
 sub scan_volids {
     my ($cfg, $vmid) = @_;
 
@@ -6948,6 +7058,10 @@ sub restore_proxmox_backup_archive {
         $param = [$pbs_backup_name, "qemu-server.conf", $cfgfn];
         PVE::Storage::PBSPlugin::run_raw_client_cmd($scfg, $storeid, $cmd, $param);
 
+        my $backup_identity =
+            restore_check_identity($vmid, PVE::Tools::file_get_contents($cfgfn), $options);
+        restore_record_pending_uid($vmid, $backup_identity, $options);
+
         $options->{progress}->{'target-changed'} = 1;
         PVE::ReplicationState::delete_guest_states($vmid);
 
@@ -6969,7 +7083,7 @@ sub restore_proxmox_backup_archive {
         # fixme: rate limit?
 
         # create empty/temp config
-        PVE::QemuConfig->write_config($vmid, { memory => 128, lock => 'create' });
+        restore_write_config($vmid, { memory => 128, lock => 'create' }, $options);
 
         $restore_cleanup_oldconf->($storecfg, $vmid, $oldconf, $virtdev_hash) if $oldconf;
 
@@ -7052,7 +7166,7 @@ sub restore_proxmox_backup_archive {
 
     my $new_conf = restore_merge_config($conffile, $new_conf_raw, $options->{override_conf});
     check_restore_permissions($rpcenv, $user, $new_conf);
-    PVE::QemuConfig->write_config($vmid, $new_conf);
+    restore_write_config($vmid, $new_conf, $options);
 
     eval { rescan($vmid, 1); };
     warn $@ if $@;
@@ -7131,6 +7245,9 @@ sub restore_external_archive {
         my $data = $backup_provider->archive_get_guest_config($volname)
             or die "backup provider failed to extract guest configuration\n";
 
+        my $backup_identity = restore_check_identity($vmid, $data, $options);
+        restore_record_pending_uid($vmid, $backup_identity, $options);
+
         $options->{progress}->{'target-changed'} = 1;
         PVE::ReplicationState::delete_guest_states($vmid);
 
@@ -7149,7 +7266,7 @@ sub restore_external_archive {
             $parse_backup_hints->($rpcenv, $user, $storecfg, $fh, $devinfo, $options);
 
         # create empty/temp config
-        PVE::QemuConfig->write_config($vmid, { memory => 128, lock => 'create' });
+        restore_write_config($vmid, { memory => 128, lock => 'create' }, $options);
 
         $restore_cleanup_oldconf->($storecfg, $vmid, $oldconf, $virtdev_hash) if $oldconf;
 
@@ -7225,7 +7342,7 @@ sub restore_external_archive {
 
     my $new_conf = restore_merge_config($conffile, $new_conf_raw, $options->{override_conf});
     check_restore_permissions($rpcenv, $user, $new_conf);
-    PVE::QemuConfig->write_config($vmid, $new_conf);
+    restore_write_config($vmid, $new_conf, $options);
 
     eval { rescan($vmid, 1); };
     warn $@ if $@;
@@ -7547,6 +7664,10 @@ sub restore_vma_archive {
     my $print_devmap = sub {
         my $cfgfn = "$tmpdir/qemu-server.conf";
 
+        my $backup_identity =
+            restore_check_identity($vmid, PVE::Tools::file_get_contents($cfgfn), $opts);
+        restore_record_pending_uid($vmid, $backup_identity, $opts);
+
         $opts->{progress}->{'target-changed'} = 1;
         PVE::ReplicationState::delete_guest_states($vmid);
 
@@ -7579,7 +7700,7 @@ sub restore_vma_archive {
 
         # create empty/temp config
         if ($oldconf) {
-            PVE::QemuConfig->write_config($vmid, { memory => 128 });
+            restore_write_config($vmid, { memory => 128 }, $opts);
             $restore_cleanup_oldconf->($cfg, $vmid, $oldconf, $virtdev_hash);
         }
 
@@ -7685,7 +7806,7 @@ sub restore_vma_archive {
 
     my $new_conf = restore_merge_config($conffile, $new_conf_raw, $opts->{override_conf});
     check_restore_permissions($rpcenv, $user, $new_conf);
-    PVE::QemuConfig->write_config($vmid, $new_conf);
+    restore_write_config($vmid, $new_conf, $opts);
 
     eval { rescan($vmid, 1); };
     warn $@ if $@;
@@ -7798,7 +7919,10 @@ sub restore_tar_archive {
 
     my $new_conf = restore_merge_config($conffile, $new_conf_raw, {});
     check_restore_permissions(PVE::RPCEnvironment::get(), $user, $new_conf);
-    PVE::QemuConfig->write_config($vmid, $new_conf);
+    # the config of the backup is only known now, so the restored config is the first with the
+    # pending uid
+    restore_pending_uid(restore_backup_identity($new_conf_raw), $opts);
+    restore_write_config($vmid, $new_conf, $opts);
 
     eval { rescan($vmid, 1); };
     warn $@ if $@;
diff --git a/src/test/QemuServerTest/FakeCFS.pm b/src/test/QemuServerTest/FakeCFS.pm
index dd9dddec..5b1501a1 100644
--- a/src/test/QemuServerTest/FakeCFS.pm
+++ b/src/test/QemuServerTest/FakeCFS.pm
@@ -27,6 +27,7 @@ our $now_ms = 1700000000000;
 our $generated = 0;
 our $lock_domain_error;
 our $writes = [];
+our $written = {}; # VMID => the written raw configs, in the order of the writes
 
 my $tmpdir = tempdir('fake-cfs-XXXXXX', DIR => '.', CLEANUP => 1);
 make_path("$tmpdir/lock");
@@ -40,6 +41,7 @@ sub reset {
     $generated = 0;
     $lock_domain_error = undef;
     $writes = [];
+    $written = {};
 }
 
 my sub vmid_of_path {
@@ -135,6 +137,7 @@ $cluster_module->mock(
         $configs->{$vmid} = PVE::QemuServer::write_vm_config($path, $conf);
         sync_config_file($vmid);
         push $writes->@*, $vmid;
+        push $written->{$vmid}->@*, $configs->{$vmid};
         return;
     },
     cfs_update => sub {
diff --git a/src/test/restore-config-expected/150.conf b/src/test/restore-config-expected/150.conf
new file mode 100644
index 00000000..a8e8909c
--- /dev/null
+++ b/src/test/restore-config-expected/150.conf
@@ -0,0 +1,9 @@
+# VM with guest identity
+boot: order=scsi0
+cores: 1
+memory: 512
+meta: creation-qemu=10.1.2,ctime=1762000000,rtime=1762000000123,uid=abcdefghijklmnopqrst
+name: identity
+scsi0: target:150/vm-150-disk-0.qcow2,size=4G
+scsihw: virtio-scsi-pci
+vmgenid: 0
diff --git a/src/test/restore-config-input/150.conf b/src/test/restore-config-input/150.conf
new file mode 100644
index 00000000..927be6dc
--- /dev/null
+++ b/src/test/restore-config-input/150.conf
@@ -0,0 +1,10 @@
+# VM with guest identity
+boot: order=scsi0
+cores: 1
+memory: 512
+meta: creation-qemu=10.1.2,ctime=1762000000,rtime=1762000000123,uid=abcdefghijklmnopqrst
+name: identity
+scsi0: mydir:150/vm-150-disk-0.qcow2,size=4G
+scsihw: virtio-scsi-pci
+vmgenid: 0
+#qmdump#map:scsi0:drive-scsi0:mydir:qcow2:
diff --git a/src/test/run_api_tests.pl b/src/test/run_api_tests.pl
index 31498fd4..334980f0 100755
--- a/src/test/run_api_tests.pl
+++ b/src/test/run_api_tests.pl
@@ -13,6 +13,7 @@ use Test::MockModule;
 use Test::More;
 
 use PVE::API2::Qemu;
+use PVE::CLI::qmrestore;
 use PVE::GuestIdentity;
 use PVE::RPCEnvironment;
 
@@ -132,6 +133,18 @@ is(
     'update_vm: reverting other options passes the parameter checks',
 );
 
+is_deeply(
+    api_error('create_vm', { 'allow-identity-mismatch' => 1 }),
+    { archive => "missing property required by 'allow-identity-mismatch'" },
+    "create_vm: 'allow-identity-mismatch' only for restores",
+);
+my $qmrestore_param = PVE::CLI::qmrestore->map_method_by_name('qmrestore')->{parameters};
+is(
+    $qmrestore_param->{properties}->{'allow-identity-mismatch'}->{type},
+    'boolean',
+    "qmrestore has 'allow-identity-mismatch'",
+);
+
 subtest 'pending changes of meta are dropped' => sub {
     my $meta = 'creation-qemu=10.1.2,ctime=1762000000';
     my $stored;
diff --git a/src/test/run_guest_identity_tests.pl b/src/test/run_guest_identity_tests.pl
index e80609d9..3429fca6 100755
--- a/src/test/run_guest_identity_tests.pl
+++ b/src/test/run_guest_identity_tests.pl
@@ -12,11 +12,13 @@ use File::Temp qw(tempdir);
 use Test::MockModule;
 use Test::More;
 
+use PVE::API2::Qemu;
 use PVE::JSONSchema;
 use PVE::QemuConfig;
 use PVE::QemuConfig::NoWrite;
 use PVE::QemuServer;
 use PVE::QemuServer::MetaInfo;
+use PVE::RPCEnvironment;
 
 use QemuServerTest::FakeCFS;
 
@@ -26,6 +28,9 @@ my $UID_B = 'bbbbbbbbbbbbbbbbbbbb';
 my $helpers_module = Test::MockModule->new('PVE::QemuServer::Helpers');
 $helpers_module->mock(kvm_user_version => sub { return '10.1.2'; });
 
+my $rpcenv = PVE::RPCEnvironment->init('cli');
+$rpcenv->set_user('root@pam');
+
 sub configs { return $QemuServerTest::FakeCFS::configs; }
 sub generated_uid { return QemuServerTest::FakeCFS::generated_uid(@_); }
 sub published_identity { return QemuServerTest::FakeCFS::published_identity(@_); }
@@ -223,6 +228,78 @@ subtest 'clone' => sub {
     is(published_identity(100)->{uid}, $UID_A, 'source keeps its uid');
 };
 
+subtest 'clone does not carry the pending uid of its source' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    # a VM left behind by a restore of a backup with uid B, with another pending change
+    configs()->{100} =
+        "memory: 512\nmeta: rtime=1600000000000,uid=$UID_A\nname: source\n"
+        . "scsi0: local:100/vm-100-disk-0.raw,size=4G\n\n[PENDING]\nmemory: 1024\n"
+        . "meta: uid=$UID_B\n";
+
+    my $rpcenv_module = Test::MockModule->new('PVE::RPCEnvironment');
+    $rpcenv_module->mock(
+        check => sub { return 1; },
+        check_vm_perm => sub { return 1; },
+        fork_worker => sub {
+            my ($self, $type, $id, $user, $code) = @_;
+            $code->('UPID:test');
+            return 'UPID:test';
+        },
+    );
+    $QemuServerTest::FakeCFS::cluster_module->mock(check_cfs_quorum => sub { return 1; });
+    my $storage_module = Test::MockModule->new('PVE::Storage');
+    $storage_module->mock(
+        activate_volumes => sub { return; },
+        config => sub {
+            return {
+                ids => {
+                    local =>
+                        { type => 'dir', path => '/var/lib/vz', content => { images => 1 } },
+                },
+            };
+        },
+        deactivate_volumes => sub { return; },
+        get_bandwidth_limit => sub { return undef; },
+        volume_has_feature => sub { return 1; },
+    );
+    my $qemu_server_module = Test::MockModule->new('PVE::QemuServer');
+    $qemu_server_module->mock(
+        check_running => sub { return 0; },
+        clone_disk => sub {
+            my ($storecfg, $source, $dest) = @_;
+            return { file => "local:$dest->{vmid}/vm-$dest->{vmid}-disk-0.raw", size => '4G' };
+        },
+    );
+    my $firewall_module = Test::MockModule->new('PVE::Firewall');
+    $firewall_module->mock(clone_vmfw_conf => sub { return; });
+    my $network_module = Test::MockModule->new('PVE::QemuServer::Network');
+    $network_module->mock(create_ifaces_ipams_ips => sub { return; });
+
+    my $warnings = '';
+    {
+        local $SIG{__WARN__} = sub { $warnings .= $_[0]; };
+        open(my $out_fh, '>', \my $output);
+        my $oldfh = select($out_fh);
+        eval { PVE::API2::Qemu->clone_vm({ node => 'localhost', vmid => 100, newid => 300 }) };
+        select($oldfh);
+        is($@, '', 'clone succeeds');
+    }
+
+    my $writes = $QemuServerTest::FakeCFS::written->{300};
+    ok(scalar(grep { m/^scsi0: local:300\//m } $writes->@*) >= 2,
+        'clone writes the disk first');
+    ok(!scalar(grep { m/uid=$UID_B/ } $writes->@*),
+        'no write of the clone has the pending uid');
+    like(
+        $warnings,
+        qr/pending changes for 'memory', discarding for clone/,
+        'other pending changes are discarded as before',
+    );
+    unlike(configs()->{300}, qr/^\[PENDING\]/m, 'clone has no pending section');
+    like(configs()->{100}, qr/^meta: uid=$UID_B$/m, 'source keeps its pending uid');
+};
+
 subtest 'importovf' => sub {
     QemuServerTest::FakeCFS::reset();
 
diff --git a/src/test/run_qemu_restore_config_tests.pl b/src/test/run_qemu_restore_config_tests.pl
index dd8629f4..f179635d 100755
--- a/src/test/run_qemu_restore_config_tests.pl
+++ b/src/test/run_qemu_restore_config_tests.pl
@@ -15,9 +15,11 @@ use Test::More;
 use File::Basename;
 
 use PVE::API2::Qemu;
+use PVE::GuestIdentity;
 use PVE::QemuConfig;
 use PVE::QemuServer;
 use PVE::QemuServer::Helpers;
+use PVE::QemuServer::MetaInfo;
 use PVE::RPCEnvironment;
 use PVE::Tools qw(dir_glob_foreach file_get_contents file_set_contents);
 
@@ -92,7 +94,8 @@ my $ARCHIVES = {
 };
 
 our $current_backup; # raw config of the backup
-our $fail_at = ''; # where the restore fails: 'read-config', 'data', 'after-restore' or 'live'
+# where the restore fails: 'read-config', 'firewall', 'data', 'after-restore' or 'live'
+our $fail_at = '';
 my $calls = {}; # calls with effects on the target VM that tests check
 
 sub backup_config {
@@ -133,6 +136,7 @@ $tools_module->mock(
     file_copy => sub {
         my ($src, $dst) = @_;
         die "file_copy (mocked) - unexpected destination '$dst'\n" if $dst !~ m|/firewall/|;
+        die "unable to restore the firewall config\n" if $fail_at eq 'firewall';
         $calls->{firewall}++;
     },
 );
@@ -202,6 +206,10 @@ my $qemu_server_module = Test::MockModule->new('PVE::QemuServer');
 $qemu_server_module->mock(
     check_running => sub { return 0; },
     pbs_live_restore => sub {
+        my ($vmid, $conf, $storecfg) = @_;
+        # like the start of the VM for the live phase
+        PVE::QemuServer::vmconfig_apply_pending($vmid, $conf, $storecfg)
+            if scalar(keys(($conf->{pending} // {})->%*));
         die "live restore failed\n" if $fail_at eq 'live';
         $calls->{live_restore}++;
     },
@@ -401,4 +409,553 @@ subtest 'failure after the data was restored keeps the VM' => sub {
 
 $fail_at = '';
 
+# Guest identity of restored VMs
+
+my $UID_BACKUP = 'bbbbbbbbbbbbbbbbbbbb';
+my $UID_TARGET = 'tttttttttttttttttttt';
+
+my $TARGET_CONF_NO_UID = "memory: 1024\nmeta: creation-qemu=8.0.2,ctime=1500000000\nname: target\n";
+
+my $NOW = 1800000000000;
+my $BACKUP_META = 'creation-qemu=9.2.0,ctime=1600000000';
+my $REFUSED =
+    "backup belongs to another guest: its uid '$UID_BACKUP' differs from uid '$UID_TARGET' of the"
+    . " existing VM 100 - use 'allow-identity-mismatch' to overwrite the VM anyway\n";
+my $IGNORED = "guest identity: ignoring backup uid $UID_BACKUP, VM 100 keeps uid $UID_TARGET";
+# captures the uid that the VM keeps
+my $ADOPT_FAILED = "WARN: guest identity: unable to adopt backup uid $UID_BACKUP, keeping uid"
+    . " ([a-z2-7]{20}) - cfs-lock 'domain-guest-identity' error: no quorum!";
+$ADOPT_FAILED = qr/^$ADOPT_FAILED$/m;
+my $KEPT_TARGET = qr/^guest identity: kept uid $UID_TARGET$/m;
+
+# legacy tar archives get no check, 'tar' gives the result for them where it differs
+my $cases = [
+    {
+        name => 'free VMID, backup uid unused',
+        backup => "$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP",
+        result => { uid => $UID_BACKUP, rtime => $NOW },
+        output => qr/^guest identity: adopted uid $UID_BACKUP from the backup$/m,
+    },
+    {
+        name => 'free VMID, backup uid in use by another guest',
+        backup => "$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP",
+        other => "rtime=1,uid=$UID_BACKUP",
+        result => { uid => 'generated', rtime => $NOW },
+        output => qr/: backup uid $UID_BACKUP is in use by guest 300, keeping uid \w{20}$/m,
+    },
+    {
+        name => 'free VMID, backup without uid',
+        backup => $BACKUP_META,
+        result => { uid => 'generated', rtime => $NOW },
+        output => qr/^guest identity: new uid aaaaaaaaaaaaaaaaaaab$/m,
+    },
+    {
+        name => 'free VMID, unique',
+        backup => "$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP",
+        param => { unique => 1 },
+        result => { uid => 'generated', rtime => $NOW },
+        output => qr/^guest identity: new uid aaaaaaaaaaaaaaaaaaab$/m,
+    },
+    {
+        name => 'free VMID, identity lock fails',
+        backup => "$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP",
+        lock_error => "cfs-lock 'domain-guest-identity' error: no quorum!\n",
+        result => { uid => 'generated', rtime => $NOW },
+        output => $ADOPT_FAILED,
+    },
+    {
+        name => 'free VMID, backup meta with a member unknown to this version',
+        backup => "$BACKUP_META,future=1,rtime=1600000000000,uid=$UID_BACKUP",
+        result => { uid => $UID_BACKUP, rtime => $NOW },
+        # the parser drops the whole property of the backup, as it does for other members
+        meta => { rtime => $NOW, uid => $UID_BACKUP },
+        output => qr/^guest identity: adopted uid $UID_BACKUP from the backup$/m,
+    },
+    {
+        name => 'in place, backup of another guest',
+        target => $TARGET_CONF,
+        backup => "$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP",
+        error => $REFUSED,
+        tar =>
+            { result => { uid => $UID_TARGET, rtime => 1700000000000 }, output => $KEPT_TARGET },
+    },
+    {
+        name => 'in place, backup of another guest, unique',
+        target => $TARGET_CONF,
+        backup => "$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP",
+        param => { unique => 1 },
+        error => $REFUSED,
+        tar =>
+            { result => { uid => $UID_TARGET, rtime => 1700000000000 }, output => $KEPT_TARGET },
+    },
+    {
+        name => 'in place, backup of another guest, override',
+        target => $TARGET_CONF,
+        backup => "$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP",
+        param => { 'allow-identity-mismatch' => 1 },
+        result => { uid => $UID_TARGET, rtime => 1700000000000 },
+        output => qr/^\Q$IGNORED\E\n(?:.*\n)*guest identity: kept uid $UID_TARGET$/m,
+        tar =>
+            { result => { uid => $UID_TARGET, rtime => 1700000000000 }, output => $KEPT_TARGET },
+    },
+    {
+        name => 'in place, backup of the same guest',
+        target => $TARGET_CONF,
+        backup => "$BACKUP_META,rtime=1600000000000,uid=$UID_TARGET",
+        result => { uid => $UID_TARGET, rtime => 1700000000000 },
+        output => $KEPT_TARGET,
+    },
+    {
+        name => 'in place, backup without uid',
+        target => $TARGET_CONF,
+        backup => $BACKUP_META,
+        result => { uid => $UID_TARGET, rtime => 1700000000000 },
+        output => $KEPT_TARGET,
+    },
+    {
+        name => 'in place, target without uid',
+        target => $TARGET_CONF_NO_UID,
+        backup => "$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP",
+        result => { uid => $UID_BACKUP, rtime => $NOW },
+        output => qr/^guest identity: adopted uid $UID_BACKUP from the backup$/m,
+    },
+    {
+        name => 'in place, target without uid, unique',
+        target => $TARGET_CONF_NO_UID,
+        backup => "$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP",
+        param => { unique => 1 },
+        result => { uid => 'generated', rtime => $NOW },
+        output => qr/^guest identity: new uid aaaaaaaaaaaaaaaaaaab$/m,
+    },
+];
+
+sub meta_of {
+    my ($vmid) = @_;
+
+    my $conf = PVE::QemuConfig->load_config($vmid);
+    return PVE::QemuServer::MetaInfo::parse_meta_info($conf->{meta});
+}
+
+for my $type (sort keys $ARCHIVES->%*) {
+    for my $test ($cases->@*) {
+        my $case = { $test->%*, ($type eq 'tar' ? $test->{tar} // {} : {})->%* };
+        delete $case->{error} if $type eq 'tar';
+
+        subtest "$type: $case->{name}" => sub {
+            QemuServerTest::FakeCFS::reset();
+            $QemuServerTest::FakeCFS::now_ms = $NOW;
+            QemuServerTest::FakeCFS::set_config(100, $case->{target}) if $case->{target};
+            $QemuServerTest::FakeCFS::other_guests->{300} = $case->{other} if $case->{other};
+            $QemuServerTest::FakeCFS::lock_domain_error = $case->{lock_error};
+
+            my $param = { ($case->{param} // {})->%* };
+            $param->{force} = 1 if $case->{target};
+            my ($err, $output) = restore_api($type, backup_config($case->{backup}), $param);
+
+            if (my $expected_err = $case->{error}) {
+                is($err, $expected_err, 'restore refused');
+                is(
+                    $QemuServerTest::FakeCFS::configs->{100},
+                    $case->{target},
+                    'config unchanged',
+                );
+                is_deeply($calls, {}, 'replication state and firewall config untouched');
+                unlike($output, $NOT_CLEANED_UP, 'no warning about a changed VM');
+                return;
+            }
+
+            is($err, '', 'restore succeeded') or diag($output);
+            like($output, $case->{output}, 'task log reports the identity');
+
+            my $expected = { $case->{result}->%* };
+            $expected->{uid} = QemuServerTest::FakeCFS::generated_uid(1)
+                if $expected->{uid} eq 'generated';
+            is_deeply(
+                QemuServerTest::FakeCFS::published_identity(100),
+                $expected,
+                'published identity',
+            );
+            is_deeply(
+                meta_of(100),
+                $case->{meta}
+                    // { 'creation-qemu' => '9.2.0', ctime => 1600000000, $expected->%* },
+                'other members of meta come from the backup',
+            );
+        };
+    }
+}
+
+subtest 'identity check on raw backup configs' => sub {
+    my $opts = { reservation => { identity => { uid => $UID_TARGET, rtime => 1 } } };
+
+    my $raw = "memory: 512\nmeta: uid=$UID_TARGET\nmeta: rtime=1,uid=$UID_BACKUP\n";
+    is_deeply(
+        PVE::QemuServer::restore_check_identity(100, $raw, { 'allow-identity-mismatch' => 1 }),
+        { uid => $UID_BACKUP, rtime => 1 },
+        'last top-level meta property counts',
+    );
+    eval { PVE::QemuServer::restore_check_identity(100, $raw, $opts) };
+    is($@, $REFUSED, 'refused');
+
+    $raw = "memory: 512\nmeta: rtime=1,uid=$UID_TARGET\n\n[snap]\nmeta: uid=$UID_BACKUP\n";
+    is_deeply(
+        PVE::QemuServer::restore_check_identity(100, $raw, $opts),
+        { uid => $UID_TARGET, rtime => 1 },
+        'snapshot sections are ignored',
+    );
+
+    is(
+        PVE::QemuServer::restore_check_identity(100, "memory: 512\n", $opts),
+        undef,
+        'backup without meta has no identity',
+    );
+    is_deeply(
+        PVE::QemuServer::restore_check_identity(
+            100,
+            "meta: uid=$UID_BACKUP\n",
+            { reservation => { identity => undef } },
+        ),
+        { uid => $UID_BACKUP, rtime => undef },
+        'no check without identity of the target',
+    );
+};
+
+subtest 'retry of a failed restore to a free VMID keeps the lineage' => sub {
+    QemuServerTest::FakeCFS::reset();
+    my $backup = backup_config("$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP");
+
+    $fail_at = 'data';
+    my ($err) = restore_api('pbs', $backup, {});
+    is($err, "restoring the data failed\n", 'first attempt failed');
+
+    # the web interface sets 'force' for a retry
+    $fail_at = '';
+    ($err) = restore_api('pbs', $backup, { force => 1 });
+    is($err, '', 'retry succeeds');
+    is(QemuServerTest::FakeCFS::published_identity(100)->{uid}, $UID_BACKUP, 'uid adopted');
+};
+
+subtest 'live restore adopts the uid of the backup only when complete' => sub {
+    my $backup = backup_config("$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP");
+    my $template = "$backup" . "template: 1\n";
+
+    for my $failure ('before the live phase', 'during the live phase') {
+        QemuServerTest::FakeCFS::reset();
+
+        $fail_at = $failure eq 'during the live phase' ? 'live' : '';
+        my ($err, $output) = restore_api(
+            'pbs',
+            $failure eq 'before the live phase' ? $template : $backup,
+            { 'live-restore' => 1 },
+        );
+        ok($err, "restore fails $failure");
+        isnt(
+            QemuServerTest::FakeCFS::published_identity(100)->{uid},
+            $UID_BACKUP,
+            "leftover VM does not have the uid of the backup ($failure)",
+        );
+        unlike($output, qr/^guest identity:/m, "no identity reported ($failure)");
+
+        $fail_at = '';
+        ($err, $output) = restore_api('pbs', $backup, { vmid => 101, 'live-restore' => 1 });
+        is($err, '', "retry at another VMID succeeds ($failure)") or diag($output);
+        is($calls->{live_restore}, 1, 'live phase ran');
+        is(
+            QemuServerTest::FakeCFS::published_identity(101)->{uid},
+            $UID_BACKUP,
+            "retry adopts the uid of the backup ($failure)",
+        );
+        like(
+            $output,
+            qr/^guest identity: adopted uid $UID_BACKUP from the backup$/m,
+            "adoption reported ($failure)",
+        );
+    }
+};
+
+# A VM that a restore leaves behind keeps the uid of the backup as pending uid, so that retrying
+# the restore over it takes the uid over.
+
+my $BACKUP_WITH_UID = backup_config("$BACKUP_META,rtime=1600000000000,uid=$UID_BACKUP");
+my $ADOPTED = qr/^guest identity: adopted uid $UID_BACKUP from the backup$/m;
+
+sub pending_uid_of {
+    my ($vmid) = @_;
+
+    return PVE::GuestIdentity::get_pending_uid(PVE::QemuConfig->load_config($vmid));
+}
+
+sub published_uid_of {
+    my ($vmid) = @_;
+
+    my $identity = QemuServerTest::FakeCFS::published_identity($vmid);
+    return $identity && $identity->{uid};
+}
+
+# Fails the live restore of a backup with uid to the free VMID 100 in its live phase.
+sub failed_live_restore {
+    QemuServerTest::FakeCFS::reset();
+    $QemuServerTest::FakeCFS::now_ms = $NOW;
+
+    local $fail_at = 'live';
+    my ($err, $output) = restore_api('pbs', $BACKUP_WITH_UID, { 'live-restore' => 1 });
+    is($err, "live restore failed\n", 'live restore failed in its live phase');
+    unlike($output, qr/ignoring pending change/, 'starting the VM keeps the pending uid');
+    isnt(published_uid_of(100), $UID_BACKUP, 'leftover VM has a uid of its own');
+    is(pending_uid_of(100), $UID_BACKUP, 'leftover VM has the uid of the backup as pending uid');
+    unlike($QemuServerTest::FakeCFS::configs->{100}, qr/^lock:/m, 'leftover VM is not locked');
+}
+
+subtest 'retry in place after a failed live restore' => sub {
+    for my $retry ({ 'live-restore' => 1 }, {}) {
+        my $what = $retry->{'live-restore'} ? 'live' : 'regular';
+
+        failed_live_restore();
+
+        # the web interface restores from the backup list of the VM with 'force'
+        my ($err, $output) = restore_api('pbs', $BACKUP_WITH_UID, { force => 1, $retry->%* });
+        is($err, '', "$what retry succeeds") or diag($output);
+        like($output, $ADOPTED, "$what retry adopts the uid of the backup");
+        is(published_uid_of(100), $UID_BACKUP, "$what retry: published");
+        is(pending_uid_of(100), undef, "$what retry: pending uid is removed");
+    }
+};
+
+subtest 'retry in place after a failure once the restored volumes stay' => sub {
+    QemuServerTest::FakeCFS::reset();
+    my $backup = $BACKUP_WITH_UID . "hostpci0: 0000:01:00.0\n";
+
+    # the permission check needs the restored config, so it runs once the data is restored
+    $rpcenv->set_user('user@pve');
+    my ($err, $output) = restore_api('vma file', $backup, {});
+    $rpcenv->set_user('root@pam');
+    is(
+        $err,
+        "only root can set 'hostpci0' config for non-mapped devices\n",
+        'restore refused after restoring the data',
+    );
+    ok(defined($QemuServerTest::FakeCFS::configs->{100}), 'VM is left behind');
+    is(pending_uid_of(100), $UID_BACKUP,
+        'leftover VM has the uid of the backup as pending uid');
+
+    ($err, $output) = restore_api('vma file', $backup, { force => 1 });
+    is($err, '', 'retry succeeds') or diag($output);
+    is(published_uid_of(100), $UID_BACKUP, 'retry adopts the uid of the backup');
+    is(pending_uid_of(100), undef, 'retry: pending uid is removed');
+};
+
+my $FAILURES = {
+    # right after the check, before the restore writes a config itself
+    firewall => "unable to restore the firewall config\n",
+    data => "restoring the data failed\n",
+};
+
+for my $type ('pbs', 'provider', 'vma file', 'vma stdin') {
+    for my $failure (sort keys $FAILURES->%*) {
+        my $what = "$type: retry in place after a failed restore over a VM without uid";
+
+        subtest "$what ($failure)" => sub {
+            QemuServerTest::FakeCFS::reset();
+            QemuServerTest::FakeCFS::set_config(100, $TARGET_CONF_NO_UID);
+
+            local $fail_at = $failure;
+            my ($err) = restore_api($type, $BACKUP_WITH_UID, { force => 1 });
+            is($err, $FAILURES->{$failure}, 'restore failed');
+            ok(published_uid_of(100), 'VM got a uid of its own');
+            isnt(published_uid_of(100), $UID_BACKUP, 'not the one of the backup');
+            is(pending_uid_of(100), $UID_BACKUP, 'VM has the uid of the backup as pending uid');
+
+            $fail_at = '';
+            ($err, my $output) = restore_api($type, $BACKUP_WITH_UID, { force => 1 });
+            is($err, '', 'retry succeeds') or diag($output);
+            is(published_uid_of(100), $UID_BACKUP, 'retry adopts the uid of the backup');
+            is(pending_uid_of(100), undef, 'retry: pending uid is removed');
+        };
+    }
+}
+
+subtest 'retry elsewhere, then over the VM left behind' => sub {
+    failed_live_restore();
+    my $leftover = published_uid_of(100);
+
+    my ($err, $output) = restore_api('pbs', $BACKUP_WITH_UID, { vmid => 101 });
+    is($err, '', 'restore to another VMID succeeds') or diag($output);
+    is(published_uid_of(101), $UID_BACKUP, 'pending uid of the leftover VM is not in use');
+    is(pending_uid_of(100), $UID_BACKUP, 'leftover VM keeps its pending uid');
+
+    ($err, $output) = restore_api('pbs', $BACKUP_WITH_UID, { force => 1 });
+    is($err, '', 'restore over the leftover VM is not refused') or diag($output);
+    like(
+        $output,
+        qr/^guest identity: backup uid $UID_BACKUP is in use by guest 101, keeping uid $leftover$/m,
+        'uid of the backup is in use by now',
+    );
+    is(published_uid_of(100), $leftover, 'leftover VM keeps its uid');
+    is(pending_uid_of(100), undef, 'pending uid is removed');
+};
+
+subtest 'using the VM left behind drops its pending uid' => sub {
+    failed_live_restore();
+    my $leftover = published_uid_of(100);
+
+    # like a start, or a config change of the stopped VM
+    my $warnings = '';
+    {
+        local $SIG{__WARN__} = sub { $warnings .= $_[0]; };
+        my $conf = PVE::QemuConfig->load_config(100);
+        PVE::QemuServer::vmconfig_apply_pending(100, $conf, {});
+    }
+    like($warnings, qr/^ignoring pending change of read-only option 'meta'$/m, 'dropped');
+    is(pending_uid_of(100), undef, 'pending uid is gone');
+
+    my ($err) = restore_api('pbs', $BACKUP_WITH_UID, { force => 1 });
+    like(
+        $err,
+        qr/^backup belongs to another guest: its uid .$UID_BACKUP. differs/,
+        'retry is refused',
+    );
+    is(published_uid_of(100), $leftover, 'VM stays its own guest');
+};
+
+subtest 'a restore with unique keeps a pending uid, but never takes it over' => sub {
+    for my $retry ({ unique => 1 }, {}) {
+        my $what = $retry->{unique} ? 'retry with unique' : 'retry without unique';
+        QemuServerTest::FakeCFS::reset();
+
+        # registering the addresses of the new MACs is the last step before the adoption
+        local $fail_at = 'after-restore';
+        my ($err) = restore_api('pbs', $BACKUP_WITH_UID, { unique => 1 });
+        is($err, "unable to register IPs\n", 'restore with unique failed at its end');
+        my $leftover = published_uid_of(100);
+        is(pending_uid_of(100), $UID_BACKUP, 'VM left behind has the pending uid');
+
+        $fail_at = '';
+        my $output;
+        ($err, $output) = restore_api('pbs', $BACKUP_WITH_UID, { force => 1, $retry->%* });
+        is($err, '', "$what succeeds") or diag($output);
+        is(pending_uid_of(100), undef, "$what: pending uid is removed");
+        if ($retry->{unique}) {
+            is(published_uid_of(100), $leftover, "$what: uid of the backup is not taken over");
+        } else {
+            is(published_uid_of(100), $UID_BACKUP, "$what: uid of the backup is taken over");
+        }
+    }
+};
+
+subtest 'a failed adoption keeps the pending uid' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    $QemuServerTest::FakeCFS::lock_domain_error =
+        "cfs-lock 'domain-guest-identity' error: no quorum!\n";
+    my ($err, $output) = restore_api('pbs', $BACKUP_WITH_UID, {});
+    $QemuServerTest::FakeCFS::lock_domain_error = undef;
+    is($err, '', 'restore succeeds') or diag($output);
+    my ($kept) = $output =~ $ADOPT_FAILED;
+    ok(defined($kept), 'failed adoption is a warning') or diag($output);
+    isnt(published_uid_of(100), $UID_BACKUP, 'VM has a uid of its own');
+    is($kept, published_uid_of(100), 'warning names the uid that the VM keeps');
+    is(pending_uid_of(100), $UID_BACKUP, 'nothing decided, pending uid stays');
+
+    ($err, $output) = restore_api('pbs', $BACKUP_WITH_UID, { force => 1 });
+    is($err, '', 'restore of the backup again is not refused') or diag($output);
+    is(published_uid_of(100), $UID_BACKUP, 'uid of the backup is taken over');
+};
+
+subtest 'config of a VM left behind shows its published identity' => sub {
+    failed_live_restore();
+    my $meta = PVE::QemuConfig->load_config(100)->{meta};
+
+    my $conf = PVE::API2::Qemu->vm_config({ node => 'localhost', vmid => 100 });
+    is($conf->{meta}, $meta, 'config with pending changes applied: published identity');
+    $conf = PVE::API2::Qemu->vm_config({ node => 'localhost', vmid => 100, current => 1 });
+    is($conf->{meta}, $meta, 'current config: published identity');
+
+    my $pending = PVE::API2::Qemu->vm_pending({ node => 'localhost', vmid => 100 });
+    my ($item) = grep { $_->{key} eq 'meta' } $pending->@*;
+    is($item->{value}, $meta, 'pending view: current value');
+    is($item->{pending}, "uid=$UID_BACKUP", 'pending view: pending uid');
+};
+
+subtest 'removing the pending uid keeps an identity that the parser cannot read' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    # a member of a newer version makes the parser drop the whole property
+    my $target_meta = "creation-qemu=10.0.0,ctime=1700000000,future-member=1,"
+        . "rtime=1700000000000,uid=$UID_TARGET";
+    QemuServerTest::FakeCFS::set_config(
+        100,
+        "memory: 512\nmeta: $target_meta\n\n[PENDING]\nmeta: uid=$UID_BACKUP\n",
+    );
+    my $reservation = {
+        existed => 1,
+        identity => { uid => $UID_TARGET, rtime => 1700000000000 },
+        pending => $UID_BACKUP,
+        reserved => { uid => $UID_TARGET, rtime => 1700000000000 },
+    };
+    my $res;
+    {
+        local $SIG{__WARN__} = sub { };
+        $res =
+            PVE::GuestIdentity::adopt('PVE::QemuConfig', 100, 'cccccccccccccccccccc', $reservation);
+    }
+    is($res->{result}, 'kept', 'identity of another backup is not taken over');
+    is(published_uid_of(100), $UID_TARGET, 'published identity is kept');
+    is(pending_uid_of(100), undef, 'pending uid is removed');
+};
+
+# vzdump never archives pending changes, a crafted backup must not bring any along
+for my $type (sort keys $ARCHIVES->%*) {
+    subtest "$type: pending changes of the backup are dropped" => sub {
+        QemuServerTest::FakeCFS::reset();
+
+        my $crafted = $BACKUP_WITH_UID
+            . "\n[PENDING]\nargs: -device foo\nhostpci0: 0000:01:00.0\nmeta: uid=$UID_TARGET\n";
+        my ($err, $output) = restore_api($type, $crafted, {});
+        is($err, '', 'restore succeeds') or diag($output);
+        my @writes = $QemuServerTest::FakeCFS::written->{100}->@*;
+        ok(!grep({ m/^(args|hostpci0):|uid=$UID_TARGET/m } @writes), 'no write has them');
+        unlike(
+            $QemuServerTest::FakeCFS::configs->{100},
+            qr/^\[PENDING\]/m,
+            'no pending section',
+        );
+    };
+}
+
+# Once a write of the config of VMID 100 has the pending uid of the backup, all later writes of the
+# restore have it, so that the VM keeps it whenever the restore stops. Only the adoption removes it.
+for my $type (sort keys $ARCHIVES->%*, 'pbs live') {
+    for my $target (undef, $TARGET_CONF_NO_UID) {
+        my $what = $type . ($target ? ', in place over a VM without uid' : ', free VMID');
+
+        subtest "$what: every write of the restore keeps the pending uid" => sub {
+            QemuServerTest::FakeCFS::reset();
+            QemuServerTest::FakeCFS::set_config(100, $target) if $target;
+
+            my $param = { $target ? (force => 1) : () };
+            $param->{'live-restore'} = 1 if $type eq 'pbs live';
+            my ($err, $output) = restore_api($type =~ s/ live$//r, $BACKUP_WITH_UID, $param);
+            is($err, '', 'restore succeeds') or diag($output);
+            like($output, $ADOPTED, 'uid of the backup is adopted');
+
+            my @writes = $QemuServerTest::FakeCFS::written->{100}->@*;
+            my $last = pop(@writes);
+            my $first = 0;
+            $first++ while $first < @writes && $writes[$first] !~ m/^\[PENDING\]/m;
+            ok($first < @writes, 'pending uid is written') or return;
+            is(
+                scalar(
+                    grep { m/^\[PENDING\]\nmeta: uid=$UID_BACKUP$/m }
+                        @writes[$first .. $#writes]
+                ),
+                scalar(@writes) - $first,
+                'all later writes keep it',
+            );
+            unlike($last, qr/^\[PENDING\]/m, 'adoption removes it');
+        };
+    }
+}
+
+$fail_at = '';
+
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH qemu-server 16/34] api: remote migration: take over the guest uid from the source
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (14 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH qemu-server 15/34] restore: take over the guest uid from the backup where possible Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-17 15:26   ` Dominik Csapak
  2026-11-16  0:46 ` [PATCH qemu-server 17/34] api: status: return the guest uid Thomas Lamprecht
                   ` (19 subsequent siblings)
  35 siblings, 1 reply; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

A VM migrated to another cluster should keep its uid, unless another
guest there already uses it. Take over the uid of the source through
the cluster-wide check of pve-guest-common after the incoming config is
written. Otherwise, the VM keeps the uid assigned when its VMID was
reserved. The other members of 'meta', including the creation
information, come from the source as before.

Fail the config command if taking over the uid raises an error, for
example because the cluster-wide lock cannot be taken. Finishing a
migration that deletes the source would otherwise lose the uid because
of a transient failure. Update the lock state of the tunnel first, so
that the cleanup after the failure finds the target config. The
existing reply timeout of two minutes covers the wait for the lock.

Report the outcome in the task logs of both sides and in the reply to
the config command. Older sources ignore the added field. An outcome
that the source does not know, as a newer target could report, only
produces a warning, because the target accepted the config at that
point. The existing lock check rejects a repeated config command, so
the registration time cannot be reset.

Bump the tunnel version, so that older targets are refused before
disks are allocated or transferred, and not only when their strict
config parser rejects the identity. Keep accepting the previous tunnel
version from older sources.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/API2/Qemu.pm                 |  20 ++-
 src/PVE/QemuMigrate.pm               |   9 +-
 src/test/run_guest_identity_tests.pl | 197 +++++++++++++++++++++++++++
 3 files changed, 221 insertions(+), 5 deletions(-)

diff --git a/src/PVE/API2/Qemu.pm b/src/PVE/API2/Qemu.pm
index 395dc334..0ac5e14a 100644
--- a/src/PVE/API2/Qemu.pm
+++ b/src/PVE/API2/Qemu.pm
@@ -6867,7 +6867,7 @@ __PACKAGE__->register_method({
         PVE::Cluster::check_cfs_quorum();
 
         my $lock = 'create';
-        eval { PVE::QemuConfig->create_and_lock_config($vmid, 0, $lock); };
+        my $reservation = eval { PVE::QemuConfig->create_and_lock_config($vmid, 0, $lock); };
 
         raise_param_exc({ vmid => "unable to create empty VM config - $@" })
             if $@;
@@ -7006,7 +7006,7 @@ __PACKAGE__->register_method({
                     # bump/bump for opt-in changes
                     return {
                         api => $PVE::QemuMigrate::WS_TUNNEL_VERSION,
-                        age => 0,
+                        age => 1,
                     };
                 },
                 'config' => sub {
@@ -7039,6 +7039,7 @@ __PACKAGE__->register_method({
                     my $conf_fn = "incoming/qemu-server/$state->{vmid}.conf";
                     my $new_conf =
                         PVE::QemuServer::parse_vm_config($conf_fn, $params->{conf}, 1);
+                    my $source_identity = PVE::QemuConfig->get_identity($new_conf);
                     delete $new_conf->{lock};
                     delete $new_conf->{digest};
 
@@ -7093,7 +7094,20 @@ __PACKAGE__->register_method({
 
                     $state->{lock} = 'migrate';
 
-                    return;
+                    # only after the state knows the new lock, so that 'quit' can clean up if
+                    # adopting fails
+                    my $identity = eval {
+                        PVE::GuestIdentity::adopt(
+                            'PVE::QemuConfig',
+                            $state->{vmid},
+                            $source_identity && $source_identity->{uid},
+                            $reservation,
+                        );
+                    };
+                    die "unable to adopt the uid of the source guest - $@" if $@;
+                    print PVE::GuestIdentity::adopt_result_message($identity, 'source') . "\n";
+
+                    return { identity => $identity };
                 },
                 'bwlimit' => sub {
                     my ($params) = @_;
diff --git a/src/PVE/QemuMigrate.pm b/src/PVE/QemuMigrate.pm
index 22f192e6..a2b897d8 100644
--- a/src/PVE/QemuMigrate.pm
+++ b/src/PVE/QemuMigrate.pm
@@ -14,6 +14,7 @@ use PVE::Cmd qw(build_ssh_command);
 use PVE::Format qw(render_bytes);
 use PVE::Firewall::Helpers;
 use PVE::GuestHelpers qw(safe_boolean_ne safe_string_ne);
+use PVE::GuestIdentity;
 use PVE::INotify;
 use PVE::JSONSchema;
 use PVE::RPCEnvironment;
@@ -45,7 +46,8 @@ use PVE::AbstractMigrate;
 use base qw(PVE::AbstractMigrate);
 
 # compared against remote end's minimum version
-our $WS_TUNNEL_VERSION = 2;
+# 3: the target accepts a guest identity in the config and takes over its uid
+our $WS_TUNNEL_VERSION = 3;
 
 sub fork_tunnel {
     my ($self, $ssh_forward_info) = @_;
@@ -953,7 +955,10 @@ sub phase1_remote {
         'firewall-config' => $fw_conf_str,
     };
 
-    PVE::Tunnel::write_tunnel($self->{tunnel}, 120, 'config', $params);
+    my $res = PVE::Tunnel::write_tunnel($self->{tunnel}, 120, 'config', $params);
+    if (my $identity = $res->{identity}) {
+        $self->log(PVE::GuestIdentity::remote_adopt_result_log($identity));
+    }
 }
 
 sub phase1_cleanup {
diff --git a/src/test/run_guest_identity_tests.pl b/src/test/run_guest_identity_tests.pl
index 3429fca6..b201594a 100755
--- a/src/test/run_guest_identity_tests.pl
+++ b/src/test/run_guest_identity_tests.pl
@@ -9,6 +9,9 @@ use warnings;
 use lib qw(.. .);
 
 use File::Temp qw(tempdir);
+use IO::Handle;
+use JSON;
+use Socket;
 use Test::MockModule;
 use Test::More;
 
@@ -16,6 +19,7 @@ use PVE::API2::Qemu;
 use PVE::JSONSchema;
 use PVE::QemuConfig;
 use PVE::QemuConfig::NoWrite;
+use PVE::QemuMigrate;
 use PVE::QemuServer;
 use PVE::QemuServer::MetaInfo;
 use PVE::RPCEnvironment;
@@ -333,4 +337,197 @@ subtest 'importovf' => sub {
     );
 };
 
+# Runs the migration tunnel endpoint for $vmid with the commands @$commands from the source side
+# and returns the decoded replies, the task output and the error of the task.
+sub run_mtunnel {
+    my ($vmid, $commands) = @_;
+
+    socketpair(my $client, my $server, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
+        or die "socketpair failed - $!\n";
+    $client->autoflush(1);
+
+    print $client encode_json($_) . "\n" for $commands->@*;
+    shutdown($client, 1);
+
+    my $rpcenv_module = Test::MockModule->new('PVE::RPCEnvironment');
+    $rpcenv_module->mock(
+        fork_worker => sub {
+            my ($self, $type, $id, $user, $code) = @_;
+            $code->('UPID:test');
+            return 'UPID:test';
+        },
+    );
+    my $access_control_module = Test::MockModule->new('PVE::AccessControl');
+    $access_control_module->mock(assemble_tunnel_ticket => sub { return 'ticket'; });
+    my $socket_module = Test::MockModule->new('IO::Socket::UNIX');
+    $socket_module->mock(new => sub { return bless { conn => $server }, 'TestListenSocket'; });
+
+    my ($output, $err) = ('', '');
+    {
+        open(my $out_fh, '>', \$output);
+        my $oldfh = select($out_fh);
+        eval { PVE::API2::Qemu->mtunnel({ node => 'localhost', vmid => $vmid }) };
+        $err = $@;
+        select($oldfh);
+        close($out_fh);
+    }
+    close($server);
+
+    my $replies = [];
+    while (defined(my $line = <$client>)) {
+        push $replies->@*, decode_json($line);
+    }
+
+    return ($replies, $output, $err);
+}
+
+package TestListenSocket {
+
+    sub accept {
+        my ($self) = @_;
+        return $self->{conn};
+    }
+}
+
+subtest 'remote migration, target side' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    my $cluster_module = Test::MockModule->new('PVE::Cluster');
+    $cluster_module->mock(check_cfs_quorum => sub { return 1; });
+    my $storage_module = Test::MockModule->new('PVE::Storage');
+    $storage_module->mock(config => sub { return {}; });
+    my $replication_config_module = Test::MockModule->new('PVE::ReplicationConfig');
+    $replication_config_module->mock(
+        new => sub { return bless {}, 'PVE::ReplicationConfig'; },
+        check_for_existing_jobs => sub { return; },
+    );
+    my $qemu_server_module = Test::MockModule->new('PVE::QemuServer');
+    $qemu_server_module->mock(check_running => sub { return 0; });
+
+    my $source_conf = "cores: 2\nmemory: 1024\nmeta: creation-qemu=9.2.0,ctime=1600000000,"
+        . "rtime=1600000000000,uid=$UID_A\nname: source\n";
+    my $config_cmd = { cmd => 'config', conf => $source_conf };
+    my $quit_cmd = { cmd => 'quit', cleanup => 0 };
+
+    $QemuServerTest::FakeCFS::now_ms = 1800000000000;
+    my ($replies, $output, $err) = run_mtunnel(100, [$config_cmd, $config_cmd, $quit_cmd]);
+    is($err, '', 'tunnel exits normally');
+
+    ok($replies->[0]->{success}, 'config command succeeds');
+    is_deeply(
+        $replies->[0]->{identity},
+        { result => 'adopted', uid => $UID_A, requested => $UID_A },
+        'config command returns the adopted identity',
+    );
+    like(
+        $output,
+        qr/^guest identity: adopted uid $UID_A from the source guest$/m,
+        'target task logs it',
+    );
+    ok(!$replies->[1]->{success}, 'repeated config command fails');
+    is_deeply(
+        load_meta(100),
+        {
+            'creation-qemu' => '9.2.0',
+            ctime => 1600000000,
+            rtime => 1800000000000,
+            uid => $UID_A,
+        },
+        'source uid with rtime of the first config command, other members from the source',
+    );
+    ok($replies->[2]->{success}, 'tunnel quits');
+
+    QemuServerTest::FakeCFS::reset();
+    $QemuServerTest::FakeCFS::other_guests->{300} = "rtime=1,uid=$UID_A";
+    ($replies) = run_mtunnel(101, [$config_cmd, $quit_cmd]);
+    is_deeply(
+        $replies->[0]->{identity},
+        {
+            result => 'in-use',
+            uid => generated_uid(1),
+            requested => $UID_A,
+            'in-use-by' => 300,
+        },
+        'uid in use by another guest is not adopted',
+    );
+    is(published_identity(101)->{uid}, generated_uid(1), 'new uid stays');
+
+    QemuServerTest::FakeCFS::reset();
+    $QemuServerTest::FakeCFS::lock_domain_error =
+        "cfs-lock 'domain-guest-identity' error: no quorum!\n";
+    ($replies, $output, $err) =
+        run_mtunnel(103, [$config_cmd, { cmd => 'quit', cleanup => 1 }]);
+    is($err, '', 'tunnel exits normally after the failed config command');
+    ok(!$replies->[0]->{success}, 'config command fails if adopting fails');
+    is(
+        $replies->[0]->{msg},
+        "failed to handle 'config' command - unable to adopt the uid of the source guest"
+            . " - cfs-lock 'domain-guest-identity' error: no quorum!\n",
+        'error explains the failure',
+    );
+    ok($replies->[1]->{success}, 'cleanup on quit succeeds');
+    ok(!defined(configs()->{103}), 'config removed by the cleanup');
+
+    QemuServerTest::FakeCFS::reset();
+    $config_cmd->{conf} =~ s/,rtime=\d+,uid=\w+//;
+    ($replies) = run_mtunnel(102, [$config_cmd, $quit_cmd]);
+    is($replies->[0]->{identity}->{result}, 'skipped', 'source without uid');
+    is(published_identity(102)->{uid}, generated_uid(1), 'new uid stays');
+};
+
+subtest 'remote migration, source side' => sub {
+    QemuServerTest::FakeCFS::reset();
+
+    # the source reads the firewall config of the VM from /etc/pve, use a VMID the host lacks
+    my $vmid = 999999999;
+    configs()->{$vmid} = "cores: 2\nmemory: 1024\nmeta: rtime=1600000000000,uid=$UID_A\n";
+
+    my ($sent, $identity);
+    my $tunnel_module = Test::MockModule->new('PVE::Tunnel');
+    $tunnel_module->mock(
+        write_tunnel => sub {
+            my ($tunnel, $timeout, $command, $params) = @_;
+            die "unexpected command '$command'\n" if $command ne 'config';
+            $sent = $params->{conf};
+            return { success => 1, identity => $identity };
+        },
+    );
+
+    my $self = bless {
+        opts => { remote => {} },
+        local_volumes => {},
+        volume_map => {},
+        storecfg => {},
+        tunnel => {},
+        },
+        'PVE::QemuMigrate';
+
+    my $phase1 = sub {
+        my $output = '';
+        open(my $out_fh, '>', \$output);
+        my $oldfh = select($out_fh);
+        eval { $self->phase1_remote($vmid) };
+        my $err = $@;
+        select($oldfh);
+        close($out_fh);
+        return ($err, $output);
+    };
+
+    $identity = { result => 'adopted', uid => $UID_A, requested => $UID_A };
+    my ($err, $output) = $phase1->();
+    is($err, '', 'config sent');
+    like($sent, qr/^meta: rtime=1600000000000,uid=$UID_A$/m, 'source config sent with its uid');
+    like(
+        $output,
+        qr/guest identity: adopted uid $UID_A from the source guest$/m,
+        'source task logs the outcome',
+    );
+
+    # a target with a newer version has already taken over the config at this point
+    $identity = { result => 'future', uid => $UID_A, requested => $UID_A };
+    ($err, $output) = $phase1->();
+    is($err, '', 'unknown outcome does not fail the migration');
+    like($output, qr/unknown result of guest identity adoption 'future'$/m, 'it is logged');
+};
+
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH qemu-server 17/34] api: status: return the guest uid
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (15 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH qemu-server 16/34] api: remote migration: take over the guest uid from the source Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH container 18/34] config: add read-only meta property with the creation time Thomas Lamprecht
                   ` (18 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Tools that follow a guest across restores and migrations need its uid.
It is part of the config already, but the status of a single VM is the
more common entry point for them, so return it there as well.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/API2/Qemu.pm      |  5 +++++
 src/test/run_api_tests.pl | 25 +++++++++++++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/src/PVE/API2/Qemu.pm b/src/PVE/API2/Qemu.pm
index 0ac5e14a..5e1f70a1 100644
--- a/src/PVE/API2/Qemu.pm
+++ b/src/PVE/API2/Qemu.pm
@@ -3555,6 +3555,7 @@ __PACKAGE__->register_method({
                 enum => ['vnc'],
                 optional => 1,
             },
+            uid => PVE::GuestIdentity::meta_format_properties()->{uid},
         },
     },
     code => sub {
@@ -3577,6 +3578,10 @@ __PACKAGE__->register_method({
         }
         $status->{agent} = 1 if PVE::QemuServer::Agent::get_qga_key($conf, 'enabled');
 
+        if (my $identity = PVE::QemuConfig->get_identity($conf)) {
+            $status->{uid} = $identity->{uid};
+        }
+
         return $status;
     },
 });
diff --git a/src/test/run_api_tests.pl b/src/test/run_api_tests.pl
index 334980f0..4a4c10bf 100755
--- a/src/test/run_api_tests.pl
+++ b/src/test/run_api_tests.pl
@@ -277,4 +277,29 @@ subtest 'migration preconditions' => sub {
     mock_unreachable_config();
 };
 
+subtest 'status' => sub {
+    my $vm_conf;
+    $qemu_config_module->mock(load_config => sub { return $vm_conf; });
+    $qemu_server_module->mock(
+        vmstatus => sub { return { 100 => { vmid => 100, status => 'stopped' } }; });
+    my $ha_config_module = Test::MockModule->new('PVE::HA::Config');
+    $ha_config_module->mock(get_service_status => sub { return { managed => 0 }; });
+
+    my $returns = PVE::API2::Qemu->map_method_by_name('vm_status')->{returns};
+
+    $vm_conf =
+        { meta => 'creation-qemu=10.1.2,ctime=1,rtime=1700000000000,uid=abcdefghijklmnopqrst' };
+    my $status = PVE::API2::Qemu->vm_status({ node => 'localhost', vmid => 100 });
+    is($status->{uid}, 'abcdefghijklmnopqrst', 'uid returned');
+    eval { PVE::JSONSchema::validate($status, $returns) };
+    is($@, '', 'result matches the schema');
+
+    $vm_conf = { meta => 'creation-qemu=10.1.2,ctime=1' };
+    $status = PVE::API2::Qemu->vm_status({ node => 'localhost', vmid => 100 });
+    ok(!exists($status->{uid}), 'no uid for config without identity');
+
+    mock_unreachable_config();
+    $qemu_server_module->unmock('vmstatus');
+};
+
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH container 18/34] config: add read-only meta property with the creation time
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (16 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH qemu-server 17/34] api: status: return the guest uid Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH container 19/34] fix #7846: config: add a guest identity to the 'meta' property Thomas Lamprecht
                   ` (17 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Containers need a place for information that the system records about
them, including the guest identity. Add a read-only 'meta' property
with the same 'ctime' member as for VMs. It is set when a container
gets created; a restore takes it from the backup and a clone from the
source.

'meta' is no parameter of the create and update API calls, and
deleting or reverting it is rejected for every user, including root. A
manually queued change gets dropped with a warning instead of applied.
The target of a remote migration takes the property from the source as
it is, bypassing the generic update path, which rejects read-only
properties.

The config API returns 'meta' as a plain string, so that members from
newer versions do not fail the result validation of 'pct config'.
Older pve-container versions drop the property on their next config
write, and their strict parser for remote migrations rejects it after
the volumes were transferred.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/API2/LXC.pm         |   4 +
 src/PVE/API2/LXC/Config.pm  |  29 +-
 src/PVE/LXC/Config.pm       |  55 +++-
 src/test/Makefile           |   8 +-
 src/test/config_tests.pl    |  23 ++
 src/test/lifecycle_tests.pl | 564 ++++++++++++++++++++++++++++++++++++
 6 files changed, 665 insertions(+), 18 deletions(-)
 create mode 100755 src/test/lifecycle_tests.pl

diff --git a/src/PVE/API2/LXC.pm b/src/PVE/API2/LXC.pm
index d736dac..b9a1337 100644
--- a/src/PVE/API2/LXC.pm
+++ b/src/PVE/API2/LXC.pm
@@ -423,6 +423,7 @@ __PACKAGE__->register_method({
         PVE::LXC::Config->update_pct_config($vmid, $conf, 0, $no_disk_param);
 
         $conf->{unprivileged} = 1 if $unprivileged;
+        $conf->{meta} = PVE::LXC::Config->new_meta_info_string() if !$restore;
 
         my $emsg = $restore ? "unable to restore CT $vmid -" : "unable to create CT $vmid -";
 
@@ -3277,6 +3278,8 @@ __PACKAGE__->register_method({
 
                     my $unprivileged = delete $new_conf->{unprivileged};
                     my $arch = delete $new_conf->{arch};
+                    # read-only for the update below, the source's values are kept as they are
+                    my $meta = delete $new_conf->{meta};
 
                     # TODO handle properly?
                     delete $new_conf->{snapshots};
@@ -3311,6 +3314,7 @@ __PACKAGE__->register_method({
                             $state->{vmid}, $conf, 0, $new_conf, [], [],
                         );
                         raise_param_exc($errors) if scalar(keys %$errors);
+                        $conf->{meta} = $meta if defined($meta);
                         PVE::LXC::Config->write_config($state->{vmid}, $conf);
                         PVE::LXC::update_lxc_config($vmid, $conf);
                     };
diff --git a/src/PVE/API2/LXC/Config.pm b/src/PVE/API2/LXC/Config.pm
index 805eac0..3d7529f 100644
--- a/src/PVE/API2/LXC/Config.pm
+++ b/src/PVE/API2/LXC/Config.pm
@@ -57,20 +57,23 @@ __PACKAGE__->register_method({
     },
     returns => {
         type => "object",
-        properties => PVE::LXC::Config->json_config_properties({
-            lxc => {
-                description =>
-                    "Array of lxc low-level configurations ([[key1, value1], [key2, value2] ...]).",
-                type => 'array',
-                items => { type => 'array', items => { type => 'string' } },
-                optional => 1,
-            },
-            digest => {
-                type => 'string',
-                description =>
-                    'SHA1 digest of configuration file. This can be used to prevent concurrent modifications.',
+        properties => PVE::LXC::Config->json_config_properties(
+            {
+                lxc => {
+                    description =>
+                        "Array of lxc low-level configurations ([[key1, value1], [key2, value2] ...]).",
+                    type => 'array',
+                    items => { type => 'array', items => { type => 'string' } },
+                    optional => 1,
+                },
+                digest => {
+                    type => 'string',
+                    description =>
+                        'SHA1 digest of configuration file. This can be used to prevent concurrent modifications.',
+                },
             },
-        }),
+            1,
+        ),
     },
     code => sub {
         my ($param) = @_;
diff --git a/src/PVE/LXC/Config.pm b/src/PVE/LXC/Config.pm
index fadb0f7..7273cf2 100644
--- a/src/PVE/LXC/Config.pm
+++ b/src/PVE/LXC/Config.pm
@@ -504,6 +504,15 @@ my $features_desc = {
     },
 };
 
+my $meta_info_fmt = {
+    ctime => {
+        type => 'integer',
+        description => "The guest creation timestamp as UNIX epoch time",
+        minimum => 0,
+        optional => 1,
+    },
+};
+
 my $confdesc = {
     lock => {
         optional => 1,
@@ -716,6 +725,12 @@ my $confdesc = {
             "Try to be more verbose. For now this only enables debug log-level on start.",
         default => 0,
     },
+    meta => {
+        optional => 1,
+        type => 'string',
+        format => $meta_info_fmt,
+        description => "Some (read-only) meta-information about this container.",
+    },
 };
 
 my $valid_lxc_conf_keys = {
@@ -1309,6 +1324,7 @@ sub queue_pct_config_changes {
     my $storage_cfg = PVE::Storage::config();
 
     foreach my $opt (@$revert) {
+        die "unable to revert read-only option: '$opt'\n" if $opt eq 'meta';
         delete $conf->{pending}->{$opt};
         $class->remove_from_pending_delete($conf, $opt); # also remove from deletion queue
     }
@@ -1317,6 +1333,7 @@ sub queue_pct_config_changes {
     my $modified = {}; # record modified options
 
     foreach my $opt (@$delete) {
+        die "unable to delete read-only option: '$opt'\n" if $opt eq 'meta';
         if (!defined($conf->{$opt}) && !defined($conf->{pending}->{$opt})) {
             warn "cannot delete '$opt' - not set in current configuration!\n";
             next;
@@ -1357,7 +1374,7 @@ sub queue_pct_config_changes {
             $value = PVE::LXC::verify_nameserver_list($value);
         } elsif ($opt eq 'searchdomain') {
             $value = PVE::LXC::verify_searchdomain_list($value);
-        } elsif ($opt eq 'unprivileged') {
+        } elsif ($opt eq 'unprivileged' || $opt eq 'meta') {
             die "unable to modify read-only option: '$opt'\n";
         } elsif ($opt eq 'tags') {
             $value = PVE::GuestHelpers::get_unique_tags($value);
@@ -1448,19 +1465,34 @@ sub check_type {
     }
 }
 
-# add JSON properties for create and set function
+# add JSON properties for create and set function, with $with_meta also the read-only 'meta' for
+# returning the config
 sub json_config_properties {
-    my ($class, $prop) = @_;
+    my ($class, $prop, $with_meta) = @_;
 
     foreach my $opt (keys %$confdesc) {
         next if $opt eq 'parent' || $opt eq 'snaptime';
+        next if $opt eq 'meta' && !$with_meta;
         next if $prop->{$opt};
         $prop->{$opt} = $confdesc->{$opt};
     }
 
+    if ($with_meta) {
+        # without its format, as a config written by a newer version can have unknown members
+        $prop->{meta} = { $prop->{meta}->%* };
+        delete $prop->{meta}->{format};
+    }
+
     return $prop;
 }
 
+# Returns the 'meta' property string for a newly created container.
+sub new_meta_info_string {
+    my ($class) = @_;
+
+    return PVE::JSONSchema::print_property_string({ ctime => int(time()) }, $meta_info_fmt);
+}
+
 my $parse_ct_mountpoint_full = sub {
     my ($class, $desc, $data, $noerr) = @_;
 
@@ -1649,9 +1681,24 @@ my $LXC_FASTPLUG_OPTIONS = {
     'lock' => 1,
 };
 
+# 'meta' is read-only, so only a manual edit can add a pending change of it. Drop such a change
+# instead of applying it, as it cannot be reverted through the API either.
+my sub drop_pending_meta {
+    my ($class, $conf) = @_;
+
+    my $pending_delete_hash = $class->parse_pending_delete($conf->{pending}->{delete});
+    return if !defined($conf->{pending}->{meta}) && !$pending_delete_hash->{meta};
+
+    warn "ignoring pending change of read-only option 'meta'\n";
+    delete $conf->{pending}->{meta};
+    $class->remove_from_pending_delete($conf, 'meta');
+}
+
 sub vmconfig_hotplug_pending {
     my ($class, $vmid, $conf, $storecfg, $selection, $errors) = @_;
 
+    drop_pending_meta($class, $conf);
+
     my $pid = PVE::LXC::find_lxc_pid($vmid);
     my $rootdir = "/proc/$pid/root";
 
@@ -1778,6 +1825,8 @@ sub vmconfig_hotplug_pending {
 sub vmconfig_apply_pending {
     my ($class, $vmid, $conf, $storecfg, $selection, $errors) = @_;
 
+    drop_pending_meta($class, $conf);
+
     my $add_apply_error = sub {
         my ($opt, $msg) = @_;
         my $err_msg = "unable to apply pending change $opt : $msg";
diff --git a/src/test/Makefile b/src/test/Makefile
index c1ff506..456dfb2 100644
--- a/src/test/Makefile
+++ b/src/test/Makefile
@@ -2,7 +2,8 @@ RUN_USERNS := lxc-usernsexec -m "u:0:`id -u`:1" -m "g:0:`id -g`:1" --
 
 all: test
 
-test: test_setup test_snapshot test_bindmount test_idmap test_config test_raw_config_write
+test: test_setup test_snapshot test_bindmount test_idmap test_config test_raw_config_write \
+	test_lifecycle
 
 test_setup: run_setup_tests.pl
 	if test -e /run/lock/sbuild; then \
@@ -30,5 +31,8 @@ test_config: config_tests.pl
 test_raw_config_write: raw_config_write_test.pl
 	./raw_config_write_test.pl
 
+test_lifecycle: lifecycle_tests.pl
+	./lifecycle_tests.pl
+
 clean:
-	rm -rf tmprootfs
+	rm -rf tmprootfs lifecycle-working
diff --git a/src/test/config_tests.pl b/src/test/config_tests.pl
index beb7e37..a37a9ad 100755
--- a/src/test/config_tests.pl
+++ b/src/test/config_tests.pl
@@ -175,4 +175,27 @@ subtest 'restore does not take over pending changes of the backup' => sub {
     }
 };
 
+subtest 'meta property' => sub {
+    like(PVE::LXC::Config->new_meta_info_string(), qr/^ctime=\d+$/, 'creation time is set');
+
+    my $raw = "hostname: ct100\nmeta: ctime=1700000000\n";
+    my $conf = PVE::LXC::Config::parse_pct_config('/lxc/100.conf', $raw, 1);
+    is($conf->{meta}, 'ctime=1700000000', 'meta is parsed');
+    is(PVE::LXC::Config::write_pct_config('/lxc/100.conf', $conf), $raw, 'meta is written');
+
+    $raw = "hostname: ct100\nmeta: ctime=1700000000,unknown=value\n";
+    my $warnings = '';
+    {
+        local $SIG{__WARN__} = sub { $warnings .= $_[0] };
+        $conf = PVE::LXC::Config::parse_pct_config('/lxc/100.conf', $raw);
+    }
+    like($warnings, qr/unable to parse value of 'meta'/, 'unknown member causes a warning');
+    is($conf->{meta}, 'ctime=1700000000,unknown=value', 'meta with unknown member is kept');
+    eval { PVE::LXC::Config::parse_pct_config('/lxc/100.conf', $raw, 1) };
+    like($@, qr/unable to parse value of 'meta'/, 'unknown member fails strict parsing');
+
+    ok(!exists(PVE::LXC::Config->json_config_properties({})->{meta}), 'meta cannot be set');
+    ok(exists(PVE::LXC::Config->json_config_properties({}, 1)->{meta}), 'meta is returned');
+};
+
 done_testing();
diff --git a/src/test/lifecycle_tests.pl b/src/test/lifecycle_tests.pl
new file mode 100755
index 0000000..e6083c9
--- /dev/null
+++ b/src/test/lifecycle_tests.pl
@@ -0,0 +1,564 @@
+#!/usr/bin/perl
+
+# Runs API calls that create, restore, update and migrate containers against a fake cluster
+# filesystem in a working directory, with storage and container runtime operations mocked.
+
+use strict;
+use warnings;
+
+use lib qw(..);
+
+# The API modules load modules of pve-ha-manager, which is no build dependency, so stub them. Tests
+# that call into them mock the functions they need.
+BEGIN {
+    $INC{'PVE/HA/Config.pm'} = $INC{'PVE/HA/Env/PVE2.pm'} = __FILE__;
+}
+
+use File::Path qw(make_path remove_tree);
+use JSON;
+use Socket qw(AF_UNIX SOCK_STREAM PF_UNSPEC);
+use Test::MockModule;
+use Test::More;
+
+use PVE::Cluster;
+use PVE::GuestHelpers;
+use PVE::INotify;
+use PVE::JSONSchema;
+use PVE::Tools qw(file_get_contents file_set_contents);
+
+use PVE::API2::LXC;
+use PVE::API2::LXC::Config;
+use PVE::LXC;
+use PVE::LXC::Config;
+use PVE::LXC::Create;
+
+my $WORKDIR = 'lifecycle-working';
+my $NODENAME = PVE::INotify::nodename();
+my $BACKUP_VOLID = 'local:backup/vzdump-lxc-100-2026_01_01-00_00_00.tar.zst';
+
+remove_tree($WORKDIR);
+make_path("$WORKDIR/lock");
+
+# Fake cluster filesystem
+
+my sub cfs_file {
+    my ($path) = @_;
+
+    return "$WORKDIR/cfs/$path";
+}
+
+my sub ct_config_path {
+    my ($vmid, $node) = @_;
+
+    return "nodes/" . ($node // $NODENAME) . "/lxc/$vmid.conf";
+}
+
+my sub write_raw_config {
+    my ($vmid, $raw, $node) = @_;
+
+    my $file = cfs_file(ct_config_path($vmid, $node));
+    make_path($file =~ s|/[^/]+$||r);
+    file_set_contents($file, $raw);
+}
+
+my sub read_raw_config {
+    my ($vmid, $node) = @_;
+
+    my $file = cfs_file(ct_config_path($vmid, $node));
+    return -f $file ? file_get_contents($file) : undef;
+}
+
+my sub reset_configs {
+    remove_tree("$WORKDIR/cfs", "$WORKDIR/rootfs");
+}
+
+my $storage_cfg = {
+    ids => {
+        local => {
+            type => 'dir',
+            path => '/var/lib/vz',
+            content => { rootdir => 1, images => 1, backup => 1, vztmpl => 1 },
+        },
+    },
+};
+
+my $cluster_module = Test::MockModule->new('PVE::Cluster');
+$cluster_module->mock(
+    cfs_update => sub { },
+    check_cfs_quorum => sub { },
+    check_node_exists => sub { },
+    get_config => sub {
+        my ($path) = @_;
+        my $file = cfs_file($path);
+        return -f $file ? file_get_contents($file) : undef;
+    },
+    cfs_read_file => sub {
+        my ($path) = @_;
+        die "unexpected read of '$path'\n" if $path !~ m|^nodes/[^/]+/lxc/\d+\.conf$|;
+        my $file = cfs_file($path);
+        return undef if !-f $file;
+        return PVE::LXC::Config::parse_pct_config("/etc/pve/$path", file_get_contents($file));
+    },
+    cfs_write_file => sub {
+        my ($path, $conf) = @_;
+        die "unexpected write of '$path'\n" if $path !~ m|^nodes/[^/]+/lxc/\d+\.conf$|;
+        my $raw = PVE::LXC::Config::write_pct_config("/etc/pve/$path", $conf);
+        my $file = cfs_file($path);
+        make_path($file =~ s|/[^/]+$||r);
+        file_set_contents($file, $raw);
+    },
+    check_vmid_unused => sub {
+        my ($vmid, $noerr) = @_;
+        return 1 if !-f cfs_file(ct_config_path($vmid));
+        return undef if $noerr;
+        die "CT $vmid already exists on node '$NODENAME'\n";
+    },
+);
+
+my $api_module = Test::MockModule->new('PVE::API2::LXC');
+$api_module->mock(
+    cfs_read_file => sub {
+        my ($path) = @_;
+        die "unexpected read of '$path'\n" if $path ne 'storage.cfg';
+        return $storage_cfg;
+    },
+);
+
+my $config_module = Test::MockModule->new('PVE::LXC::Config');
+$config_module->mock(
+    config_file => sub {
+        my ($class, $vmid, $node) = @_;
+        return cfs_file(ct_config_path($vmid, $node));
+    },
+    config_file_lock => sub {
+        my ($class, $vmid) = @_;
+        return "$WORKDIR/lock/pve-config-$vmid.lock";
+    },
+);
+
+my $repl_config_module = Test::MockModule->new('PVE::ReplicationConfig');
+$repl_config_module->mock(
+    new => sub { return bless {}, 'PVE::ReplicationConfig' },
+    check_for_existing_jobs => sub { return undef },
+);
+
+# Fake environment, records task output
+
+my $task_log = '';
+
+package PVE::LXC::Test::RPCEnvironment {
+
+    sub new {
+        my ($class, $user) = @_;
+        return bless { user => $user, type => 'cli' }, $class;
+    }
+
+    sub get_user { return $_[0]->{user} }
+    sub check { return 1 }
+    sub check_vm_perm { return 1 }
+    sub check_pool_exist { return 1 }
+
+    sub warn {
+        my ($self, $msg) = @_;
+        $task_log .= "WARN: $msg\n";
+    }
+
+    sub fork_worker {
+        my ($self, $type, $id, $user, $function) = @_;
+        my $upid = "UPID:$NODENAME:$type:$id";
+        $function->($upid);
+        return $upid;
+    }
+}
+
+my $rpcenv = PVE::LXC::Test::RPCEnvironment->new('root@pam');
+
+my $rpcenv_module = Test::MockModule->new('PVE::RPCEnvironment');
+$rpcenv_module->mock(get => sub { return $rpcenv });
+
+my $restenv_module = Test::MockModule->new('PVE::RESTEnvironment');
+$restenv_module->mock(
+    log_warn => sub {
+        my ($msg) = @_;
+        chomp($msg);
+        $task_log .= "WARN: $msg\n";
+    },
+);
+
+# Runs $code like a task, with its output going to the task log. Returns the error, if any.
+my sub run_task {
+    my ($code) = @_;
+
+    $task_log = '';
+    my $output = '';
+    eval {
+        local *STDOUT;
+        open(STDOUT, '>', \$output) or die "unable to capture output - $!\n";
+        local $SIG{__WARN__} = sub { $output .= "WARN: $_[0]" };
+        $code->();
+    };
+    my $err = $@;
+    $task_log = $output . $task_log;
+
+    return $err;
+}
+
+# Fake storage and container runtime
+
+my $backup_raw_config;
+
+my $storage_module = Test::MockModule->new('PVE::Storage');
+$storage_module->mock(
+    config => sub { return $storage_cfg },
+    activate_storage => sub { },
+    activate_volumes => sub { },
+    deactivate_volumes => sub { },
+    check_volume_access => sub { },
+    storage_check_enabled => sub {
+        my ($cfg, $storeid) = @_;
+        return $storage_cfg->{ids}->{$storeid};
+    },
+    storage_config => sub {
+        my ($cfg, $storeid) = @_;
+        return $storage_cfg->{ids}->{$storeid} // die "storage '$storeid' does not exist\n";
+    },
+    storage_has_feature => sub { return 0 },
+    get_bandwidth_limit => sub { return undef },
+);
+
+my $lxc_module = Test::MockModule->new('PVE::LXC');
+$lxc_module->mock(
+    check_running => sub { return 0 },
+    create_disks => sub {
+        my ($storecfg, $vmid, $settings, $conf) = @_;
+        my $vollist = [];
+        for my $ms (sort keys %$settings) {
+            my $volid = "local:$vmid/vm-$vmid-disk-$ms.raw";
+            $conf->{$ms} = "$volid,size=4G";
+            push @$vollist, $volid;
+        }
+        return $vollist;
+    },
+    destroy_disks => sub { },
+    destroy_lxc_container => sub {
+        my ($storecfg, $vmid, $conf, $replacement_conf) = @_;
+        if (defined($replacement_conf)) {
+            PVE::LXC::Config->write_config($vmid, $replacement_conf);
+        } else {
+            PVE::LXC::Config->destroy_config($vmid);
+        }
+    },
+    mount_all => sub {
+        my ($vmid) = @_;
+        my $rootdir = "$WORKDIR/rootfs/$vmid";
+        make_path($rootdir);
+        return $rootdir;
+    },
+    umount_all => sub { },
+    create_ifaces_ipams_ips => sub { },
+    delete_ifaces_ipams_ips => sub { },
+    update_lxc_config => sub { },
+);
+
+my $create_module = Test::MockModule->new('PVE::LXC::Create');
+$create_module->mock(
+    archive_is_oci_format => sub { return 0 },
+    recover_config => sub {
+        my ($storecfg, $volid, $vmid) = @_;
+        my $conf = PVE::LXC::Config::parse_pct_config("/lxc/$vmid.conf", $backup_raw_config);
+        delete $conf->{snapshots};
+        my $mp_param = {};
+        PVE::LXC::Config->foreach_volume($conf,
+            sub { $mp_param->{ $_[0] } = $conf->{ $_[0] } });
+        return wantarray ? ($conf, $mp_param) : $conf;
+    },
+    restore_archive => sub {
+        my ($storecfg, $archive, $rootdir, $conf) = @_;
+        if (defined($backup_raw_config)) {
+            make_path("$rootdir/etc/vzdump");
+            file_set_contents("$rootdir/etc/vzdump/pct.conf", $backup_raw_config);
+        }
+    },
+);
+
+my $setup_module = Test::MockModule->new('PVE::LXC::Setup');
+$setup_module->mock(new => sub { return bless {}, 'PVE::LXC::Test::Setup' });
+
+package PVE::LXC::Test::Setup {
+    sub post_create_hook { }
+    sub post_restore_hook { }
+    sub post_clone_hook { }
+}
+
+my $firewall_module = Test::MockModule->new('PVE::Firewall');
+$firewall_module->mock(remove_vmfw_conf => sub { });
+
+my $access_control_module = Test::MockModule->new('PVE::AccessControl');
+$access_control_module->mock(assemble_tunnel_ticket => sub { return 'ticket' });
+
+# API call helpers
+
+my sub create_ct {
+    my ($vmid, $param) = @_;
+
+    return run_task(sub {
+        PVE::API2::LXC->create_vm({
+            node => $NODENAME,
+            vmid => $vmid,
+            ostemplate => 'local:vztmpl/debian-13-standard_13.1-2_amd64.tar.zst',
+            hostname => "ct$vmid",
+            ($param // {})->%*,
+        });
+    });
+}
+
+my sub restore_ct {
+    my ($vmid, $param) = @_;
+
+    return run_task(sub {
+        PVE::API2::LXC->create_vm({
+            node => $NODENAME,
+            vmid => $vmid,
+            ostemplate => $BACKUP_VOLID,
+            restore => 1,
+            ($param // {})->%*,
+        });
+    });
+}
+
+my sub update_ct {
+    my ($vmid, $param) = @_;
+
+    return run_task(sub {
+        PVE::API2::LXC::Config->update_vm({ node => $NODENAME, vmid => $vmid, $param->%* });
+    });
+}
+
+# Runs the migration tunnel for $vmid with the commands @commands, which are sent at once, and
+# returns the error of the task, if any, and the replies.
+my sub run_mtunnel {
+    my ($vmid, @commands) = @_;
+
+    socketpair(my $tunnel_end, my $client_end, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
+        or die "socketpair failed - $!\n";
+    for my $command (@commands) {
+        print $client_end JSON::encode_json($command) . "\n";
+    }
+    $client_end->flush();
+    shutdown($client_end, 1);
+
+    my $socket_module = Test::MockModule->new('IO::Socket::UNIX');
+    $socket_module->mock(
+        new => sub { return bless { conn => $tunnel_end }, 'PVE::LXC::Test::Socket' });
+
+    my $err = run_task(sub { PVE::API2::LXC->mtunnel({ node => $NODENAME, vmid => $vmid }) });
+
+    close($tunnel_end);
+    my $replies = [map { JSON::decode_json($_) } <$client_end>];
+    close($client_end);
+
+    return ($err, $replies);
+}
+
+package PVE::LXC::Test::Socket {
+    sub accept { return $_[0]->{conn} }
+}
+
+my $INCOMING_CONFIG = <<~'EOF';
+    arch: amd64
+    hostname: incoming
+    memory: 1024
+    meta: ctime=1600000000
+    ostype: debian
+    rootfs: local:300/vm-300-disk-0.raw,size=4G
+    unprivileged: 1
+    EOF
+
+my sub backup_config {
+    my ($meta) = @_;
+
+    my $raw = <<~'EOF';
+        arch: amd64
+        hostname: backup
+        memory: 2048
+        ostype: debian
+        rootfs: local:100/vm-100-disk-0.raw,size=8G
+        unprivileged: 1
+        EOF
+    $raw .= "meta: $meta\n" if defined($meta);
+
+    return $raw;
+}
+
+my sub existing_config {
+    my ($meta) = @_;
+
+    my $raw = <<~'EOF';
+        arch: amd64
+        hostname: existing
+        memory: 512
+        ostype: debian
+        rootfs: local:200/vm-200-disk-0.raw,size=4G
+        unprivileged: 1
+        EOF
+    $raw .= "meta: $meta\n" if defined($meta);
+
+    return $raw;
+}
+
+# Returns the members of the 'meta' property in the config of $vmid.
+my sub meta_of {
+    my ($vmid) = @_;
+
+    my $conf = PVE::LXC::Config->load_config($vmid);
+
+    return { map { split(/=/, $_, 2) } split(/,/, $conf->{meta} // '') };
+}
+
+# Tests
+
+subtest 'meta cannot be changed through the API' => sub {
+    reset_configs();
+    write_raw_config(200, existing_config('ctime=1500000000'));
+    my $raw = read_raw_config(200);
+
+    for my $user ('root@pam', 'admin@pve') {
+        $rpcenv = PVE::LXC::Test::RPCEnvironment->new($user);
+
+        my $err = update_ct(200, { meta => 'ctime=1' });
+        like($err, qr/meta: property is not defined in schema/, "$user cannot set meta");
+
+        $err = update_ct(200, { delete => 'meta' });
+        like($err, qr/unable to delete read-only option: 'meta'/, "$user cannot delete meta");
+
+        $err = update_ct(200, { revert => 'meta' });
+        like($err, qr/unable to revert read-only option: 'meta'/, "$user cannot revert meta");
+
+        $err = create_ct(201, { meta => 'ctime=1' });
+        like($err, qr/meta: property is not defined in schema/,
+            "$user cannot create with meta");
+
+        $err = restore_ct(200, { force => 1, meta => 'ctime=1' });
+        like(
+            $err,
+            qr/meta: property is not defined in schema/,
+            "$user cannot restore with meta",
+        );
+    }
+    $rpcenv = PVE::LXC::Test::RPCEnvironment->new('root@pam');
+
+    is(read_raw_config(200), $raw, 'config is unchanged');
+    ok(!defined(read_raw_config(201)), 'no container got created');
+
+    my $conf = PVE::LXC::Config->load_config(200);
+    eval { PVE::LXC::Config->update_pct_config(200, $conf, 0, { meta => 'ctime=1' }, [], []) };
+    like($@, qr/unable to modify read-only option: 'meta'/, 'update cannot set meta');
+
+    write_raw_config(200, existing_config());
+    my $err = update_ct(200, { delete => 'meta' });
+    like($err, qr/unable to delete read-only option: 'meta'/,
+        'meta cannot be deleted if unset');
+};
+
+subtest 'pending changes of meta are dropped' => sub {
+    my $raw = existing_config('ctime=1500000000') . <<~'EOF';
+
+        [pve:pending]
+        delete: meta
+        meta: ctime=1
+        EOF
+
+    reset_configs();
+    write_raw_config(200, $raw);
+    my $err = update_ct(200, { hostname => 'changed' });
+    is($err, '', 'update succeeds');
+    like($task_log, qr/ignoring pending change of read-only option 'meta'/, 'drop is logged');
+    my $conf = PVE::LXC::Config->load_config(200);
+    is(meta_of(200)->{ctime}, 1500000000, 'ctime is kept');
+    is_deeply($conf->{pending}, {}, 'pending change of meta is dropped');
+
+    for my $pending ('meta: ctime=1', 'delete: meta') {
+        $conf = PVE::LXC::Config::parse_pct_config(
+            '/lxc/200.conf',
+            existing_config('ctime=1500000000') . "\n[pve:pending]\n$pending\n",
+        );
+        {
+            local $SIG{__WARN__} = sub { };
+            PVE::LXC::Config->vmconfig_apply_pending(200, $conf, $storage_cfg);
+        }
+        is($conf->{meta}, 'ctime=1500000000', "applying '$pending' keeps meta");
+        is_deeply($conf->{pending}, {}, "applying drops '$pending'");
+    }
+
+    $conf = PVE::LXC::Config::parse_pct_config('/lxc/200.conf', $raw);
+    my $cgroup_module = Test::MockModule->new('PVE::LXC::CGroup');
+    $cgroup_module->mock(new => sub { return bless {}, 'PVE::LXC::CGroup' });
+    $lxc_module->mock(find_lxc_pid => sub { return 1 });
+    {
+        local $SIG{__WARN__} = sub { };
+        PVE::LXC::Config->vmconfig_hotplug_pending(200, $conf, $storage_cfg, undef, {});
+    }
+    $lxc_module->unmock('find_lxc_pid');
+    is($conf->{meta}, 'ctime=1500000000', 'hotplugging keeps meta');
+    is_deeply($conf->{pending}, {}, 'hotplugging drops the pending change of meta');
+};
+
+subtest 'meta with members unknown to this version can be read' => sub {
+    reset_configs();
+    write_raw_config(200, existing_config('ctime=1500000000,future=value'));
+
+    my $info = PVE::API2::LXC::Config->map_method_by_name('vm_config');
+    my $conf = eval {
+        local $SIG{__WARN__} = sub { };
+        PVE::API2::LXC::Config->handle($info, { node => $NODENAME, vmid => 200 }, 1);
+    };
+    is($@, '', 'config passes the result verification');
+    is($conf->{meta}, 'ctime=1500000000,future=value', 'meta is returned as it is');
+};
+
+subtest 'create sets the creation time' => sub {
+    reset_configs();
+
+    my $before = time();
+    my $err = create_ct(201);
+    my $after = time();
+    is($err, '', 'create succeeds');
+
+    my $ctime = meta_of(201)->{ctime};
+    ok($ctime >= $before && $ctime <= $after, 'ctime is the time of the create');
+};
+
+subtest 'restore keeps the meta information of the backup' => sub {
+    reset_configs();
+
+    $backup_raw_config = backup_config('ctime=1400000000');
+    my $err = restore_ct(201);
+    is($err, '', 'restore to a free VMID succeeds');
+    is(meta_of(201)->{ctime}, 1400000000, 'backup ctime is kept');
+
+    write_raw_config(200, existing_config('ctime=1500000000'));
+    $err = restore_ct(200, { force => 1 });
+    is($err, '', 'restore over an existing container succeeds');
+    is(meta_of(200)->{ctime}, 1400000000, 'backup ctime is used');
+};
+
+subtest 'remote migration keeps the meta information of the source' => sub {
+    reset_configs();
+
+    my ($err, $replies) = run_mtunnel(
+        300,
+        { cmd => 'config', conf => $INCOMING_CONFIG },
+        { cmd => 'quit', cleanup => 0 },
+    );
+    is($err, '', 'tunnel exits normally') or diag(explain($replies), $task_log);
+    ok($replies->[0]->{success}, 'config command succeeds');
+
+    my $conf = PVE::LXC::Config->load_config(300);
+    is(meta_of(300)->{ctime}, 1600000000, 'source ctime is kept');
+    is($conf->{hostname}, 'incoming', 'other options are applied');
+    is($conf->{lock}, 'migrate', 'config is locked for the migration');
+};
+
+remove_tree($WORKDIR);
+
+done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH container 19/34] fix #7846: config: add a guest identity to the 'meta' property
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (17 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH container 18/34] config: add read-only meta property with the creation time Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH container 20/34] api: migrate, clone: refuse targets that would drop the guest identity Thomas Lamprecht
                   ` (16 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Give containers a guest identity in the 'meta' property: a random
identifier, 'uid', and the time the container was registered in the
cluster, 'rtime'.

With identities enabled for the config class, every config write keeps
the identity a container already has, or assigns one if it has none,
whatever the written config carries. So create and clone get a new
identity when the VMID is reserved, while config changes, pending
changes applied by the post-stop hook, snapshot rollback and a restore
over an existing container keep it. A container without identity gets
one with its first config write by an upgraded node.

The post-stop hook writes the config it loaded before, without the
guest lock. As the write reads the existing identity under the
per-VMID identity lock, an identity that another writer assigned in the
meantime is kept and not replaced by a second one.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/LXC/Config.pm       |   8 ++
 src/test/lifecycle_tests.pl | 248 +++++++++++++++++++++++++++++++++++-
 2 files changed, 253 insertions(+), 3 deletions(-)

diff --git a/src/PVE/LXC/Config.pm b/src/PVE/LXC/Config.pm
index 7273cf2..8b6cf1d 100644
--- a/src/PVE/LXC/Config.pm
+++ b/src/PVE/LXC/Config.pm
@@ -9,6 +9,7 @@ use PVE::AbstractConfig;
 use PVE::Cluster qw(cfs_register_file);
 use PVE::DataCenterConfig;
 use PVE::GuestHelpers;
+use PVE::GuestIdentity;
 use PVE::INotify;
 use PVE::JSONSchema qw(get_standard_option);
 use PVE::Network::SDN::Vnets;
@@ -59,6 +60,12 @@ sub cfs_config_path {
     return "nodes/$node/lxc/$vmid.conf";
 }
 
+sub __identity_enabled {
+    my ($class) = @_;
+
+    return 1;
+}
+
 sub mountpoint_backup_enabled {
     my ($class, $mp_key, $mountpoint) = @_;
 
@@ -511,6 +518,7 @@ my $meta_info_fmt = {
         minimum => 0,
         optional => 1,
     },
+    PVE::GuestIdentity::meta_format_properties()->%*,
 };
 
 my $confdesc = {
diff --git a/src/test/lifecycle_tests.pl b/src/test/lifecycle_tests.pl
index e6083c9..2e31984 100755
--- a/src/test/lifecycle_tests.pl
+++ b/src/test/lifecycle_tests.pl
@@ -8,10 +8,12 @@ use warnings;
 
 use lib qw(..);
 
-# The API modules load modules of pve-ha-manager, which is no build dependency, so stub them. Tests
-# that call into them mock the functions they need.
+# The API modules load modules of pve-ha-manager and the backup plugin PVE::VZDump of pve-manager,
+# which are no build dependencies, so stub them. Tests that call into them mock the functions they
+# need.
 BEGIN {
     $INC{'PVE/HA/Config.pm'} = $INC{'PVE/HA/Env/PVE2.pm'} = __FILE__;
+    $INC{'PVE/VZDump.pm'} = __FILE__;
 }
 
 use File::Path qw(make_path remove_tree);
@@ -136,6 +138,24 @@ $config_module->mock(
     },
 );
 
+# Guest identities are generated deterministically, the local identity lock is taken in the working
+# directory.
+
+$PVE::GuestHelpers::lockdir = "$WORKDIR/lock";
+
+my $random_counter = 0;
+my $now_ms = 1_700_000_000_000;
+
+my $identity_module = Test::MockModule->new('PVE::GuestIdentity');
+$identity_module->mock(
+    __random_bytes => sub {
+        my ($len) = @_;
+        die "unexpected length $len\n" if $len != 13;
+        return pack('x6Nx3', ++$random_counter);
+    },
+    __time_ms => sub { return $now_ms },
+);
+
 my $repl_config_module = Test::MockModule->new('PVE::ReplicationConfig');
 $repl_config_module->mock(
     new => sub { return bless {}, 'PVE::ReplicationConfig' },
@@ -183,6 +203,7 @@ $restenv_module->mock(
         chomp($msg);
         $task_log .= "WARN: $msg\n";
     },
+    setup_default_cli_env => sub { },
 );
 
 # Runs $code like a task, with its output going to the task log. Returns the error, if any.
@@ -224,6 +245,8 @@ $storage_module->mock(
     },
     storage_has_feature => sub { return 0 },
     get_bandwidth_limit => sub { return undef },
+    volume_rollback_is_possible => sub { return 1 },
+    volume_snapshot_rollback => sub { },
 );
 
 my $lxc_module = Test::MockModule->new('PVE::LXC');
@@ -255,6 +278,10 @@ $lxc_module->mock(
         return $rootdir;
     },
     umount_all => sub { },
+    copy_volume => sub {
+        my ($mp, $newid) = @_;
+        return "local:$newid/vm-$newid-disk-0.raw";
+    },
     create_ifaces_ipams_ips => sub { },
     delete_ifaces_ipams_ips => sub { },
     update_lxc_config => sub { },
@@ -291,7 +318,10 @@ package PVE::LXC::Test::Setup {
 }
 
 my $firewall_module = Test::MockModule->new('PVE::Firewall');
-$firewall_module->mock(remove_vmfw_conf => sub { });
+$firewall_module->mock(
+    clone_vmfw_conf => sub { },
+    remove_vmfw_conf => sub { },
+);
 
 my $access_control_module = Test::MockModule->new('PVE::AccessControl');
 $access_control_module->mock(assemble_tunnel_ticket => sub { return 'ticket' });
@@ -334,6 +364,19 @@ my sub update_ct {
     });
 }
 
+my sub clone_ct {
+    my ($vmid, $newid, $param) = @_;
+
+    return run_task(sub {
+        PVE::API2::LXC->clone_vm({
+            node => $NODENAME,
+            vmid => $vmid,
+            newid => $newid,
+            ($param // {})->%*,
+        });
+    });
+}
+
 # Runs the migration tunnel for $vmid with the commands @commands, which are sent at once, and
 # returns the error of the task, if any, and the replies.
 my sub run_mtunnel {
@@ -415,6 +458,12 @@ my sub meta_of {
     return { map { split(/=/, $_, 2) } split(/,/, $conf->{meta} // '') };
 }
 
+my sub identity_of {
+    my ($vmid) = @_;
+
+    return PVE::LXC::Config->get_identity(PVE::LXC::Config->load_config($vmid));
+}
+
 # Tests
 
 subtest 'meta cannot be changed through the API' => sub {
@@ -559,6 +608,199 @@ subtest 'remote migration keeps the meta information of the source' => sub {
     is($conf->{lock}, 'migrate', 'config is locked for the migration');
 };
 
+subtest 'create assigns a new guest identity' => sub {
+    reset_configs();
+    $now_ms = 1_700_000_000_000;
+
+    my $err = create_ct(201);
+    is($err, '', 'create succeeds');
+
+    my $meta = meta_of(201);
+    like($meta->{uid}, qr/^[a-z2-7]{20}$/, 'uid is assigned');
+    is($meta->{rtime}, 1_700_000_000_000, 'rtime is the time of the create');
+    ok(defined($meta->{ctime}), 'ctime is kept next to the identity');
+    ok(!defined(PVE::LXC::Config->load_config(201)->{lock}), 'create lock is removed');
+
+    $err = create_ct(202);
+    isnt(identity_of(202)->{uid}, $meta->{uid}, 'another container gets another uid');
+};
+
+subtest 'config changes keep the guest identity' => sub {
+    reset_configs();
+    my $meta = 'ctime=1500000000,rtime=1500000000000,uid=existingexistingexis';
+    write_raw_config(200, existing_config($meta));
+    $now_ms = 1_700_000_000_000;
+
+    my $err = update_ct(200, { hostname => 'changed', memory => 1024 });
+    is($err, '', 'update succeeds');
+    my $conf = PVE::LXC::Config->load_config(200);
+    is($conf->{hostname}, 'changed', 'change is applied');
+    is($conf->{meta}, $meta, 'meta is unchanged');
+
+    write_raw_config(200, existing_config('ctime=1500000000'));
+    $err = update_ct(200, { hostname => 'first-write' });
+    is($err, '', 'update of a container without identity succeeds');
+    my $identity = identity_of(200);
+    like($identity->{uid}, qr/^[a-z2-7]{20}$/, 'first write assigns a uid');
+    is($identity->{rtime}, 1_700_000_000_000, 'first write sets rtime');
+    is(meta_of(200)->{ctime}, 1500000000, 'ctime is kept');
+
+    $now_ms += 1000;
+    $err = update_ct(200, { hostname => 'second-write' });
+    is_deeply(identity_of(200), $identity, 'later writes keep the identity');
+};
+
+subtest 'clone assigns a new guest identity' => sub {
+    reset_configs();
+    write_raw_config(
+        200,
+        existing_config('ctime=1500000000,rtime=1500000000000,uid=existingexistingexis'),
+    );
+    $now_ms = 1_700_000_000_000;
+
+    my $err = clone_ct(200, 201, { hostname => 'clone' });
+    is($err, '', 'clone succeeds') or diag($task_log);
+
+    my $meta = meta_of(201);
+    like($meta->{uid}, qr/^[a-z2-7]{20}$/, 'clone has a uid');
+    isnt($meta->{uid}, 'existingexistingexis', 'clone does not get the uid of the source');
+    is($meta->{rtime}, 1_700_000_000_000, 'rtime is the time of the clone');
+    is($meta->{ctime}, 1500000000, 'ctime of the source is kept');
+    is(identity_of(200)->{uid}, 'existingexistingexis', 'source keeps its uid');
+};
+
+subtest 'snapshot rollback keeps the current guest identity' => sub {
+    reset_configs();
+    write_raw_config(200, <<~'EOF');
+        arch: amd64
+        hostname: existing
+        memory: 512
+        meta: ctime=1500000000,rtime=1600000000000,uid=existingexistingexis
+        ostype: debian
+        parent: snap
+        rootfs: local:200/vm-200-disk-0.raw,size=4G
+        unprivileged: 1
+
+        [snap]
+        arch: amd64
+        hostname: snapshot
+        memory: 512
+        meta: ctime=1500000000,rtime=1500000000000,uid=snapshotsnapshotsnap
+        ostype: debian
+        rootfs: local:200/vm-200-disk-0.raw,size=4G
+        snaptime: 1500000000
+        unprivileged: 1
+        EOF
+
+    my $err = run_task(sub { PVE::LXC::Config->snapshot_rollback(200, 'snap') });
+    is($err, '', 'rollback succeeds') or diag($task_log);
+
+    my $conf = PVE::LXC::Config->load_config(200);
+    is($conf->{hostname}, 'snapshot', 'config of the snapshot is restored');
+    is_deeply(
+        identity_of(200),
+        { uid => 'existingexistingexis', rtime => 1600000000000 },
+        'current identity is kept',
+    );
+};
+
+subtest 'in-place restore keeps the guest identity of the target' => sub {
+    reset_configs();
+    my $meta = 'ctime=1500000000,rtime=1500000000000,uid=existingexistingexis';
+    write_raw_config(200, existing_config($meta));
+
+    for my $backup_meta (
+        undef, 'ctime=1400000000,rtime=1400000000000,uid=existingexistingexis',
+    ) {
+        $backup_raw_config = backup_config($backup_meta);
+        my $err = restore_ct(200, { force => 1 });
+        is($err, '', 'restore succeeds') or diag($task_log);
+        is_deeply(
+            identity_of(200),
+            { uid => 'existingexistingexis', rtime => 1500000000000 },
+            'identity is kept',
+        );
+        is(PVE::LXC::Config->load_config(200)->{hostname}, 'backup', 'backup is restored');
+    }
+};
+
+subtest 'backup assigns the guest identity and includes it' => sub {
+    reset_configs();
+    write_raw_config(987, existing_config('ctime=1500000000'));
+    $now_ms = 1_700_000_000_000;
+
+    require PVE::VZDump::LXC;
+    my $plugin = bless { vzdump => { opts => { pbs => 1 } } }, 'PVE::VZDump::LXC';
+
+    $plugin->lock_vm(987);
+    my $identity = identity_of(987);
+    like($identity->{uid}, qr/^[a-z2-7]{20}$/, 'backup lock assigns a uid');
+    is($identity->{rtime}, $now_ms, 'backup lock sets rtime');
+
+    $plugin->assemble({ tmpdir => "$WORKDIR/backup" }, 987);
+    my $raw = file_get_contents("$WORKDIR/backup/etc/vzdump/pct.conf");
+    my $backup_conf = PVE::LXC::Config::parse_pct_config('/lxc/987.conf', $raw);
+    is_deeply(
+        PVE::LXC::Config->get_identity($backup_conf),
+        $identity,
+        'backup has the identity',
+    );
+
+    $now_ms += 1000;
+    $plugin->unlock_vm(987);
+    is_deeply(identity_of(987), $identity, 'removing the backup lock keeps the identity');
+};
+
+subtest 'post-stop hook keeps an identity published while it ran' => sub {
+    reset_configs();
+    write_raw_config(200, existing_config('ctime=1500000000'));
+    $now_ms = 1_700_000_000_000;
+
+    my $published;
+    $lxc_module->mock(
+        get_staging_tempfs => sub { return "$WORKDIR/staging" },
+        vm_stop_cleanup => sub {
+            # another writer assigns the identity after the hook loaded the config
+            PVE::LXC::Config->lock_config(
+                200,
+                sub {
+                    my $conf = PVE::LXC::Config->load_config(200);
+                    $conf->{description} = 'written while the hook ran';
+                    PVE::LXC::Config->write_config(200, $conf);
+                },
+            );
+            $published = identity_of(200);
+            $now_ms += 1000;
+        },
+    );
+    my $tools_module = Test::MockModule->new('PVE::Tools');
+    $tools_module->mock(run_command => sub { });
+    my $guest_helpers_module = Test::MockModule->new('PVE::GuestHelpers');
+    $guest_helpers_module->mock(exec_hookscript => sub { });
+
+    local $ENV{LXC_HOOK_VERSION} = '1';
+    local $ENV{LXC_NAME} = '200';
+    local $ENV{LXC_HOOK_SECTION} = 'lxc';
+    local $ENV{LXC_HOOK_TYPE} = 'post-stop';
+    local $ENV{LXC_ROOTFS_MOUNT} = "$WORKDIR/rootfs/200";
+    local $ENV{LXC_ROOTFS_PATH} = "$WORKDIR/rootfs/200";
+    local $ENV{LXC_CONFIG_FILE} = "$WORKDIR/lxc-200.config";
+    delete local $ENV{LXC_TARGET};
+
+    my $err = run_task(sub {
+        do '../lxc-pve-poststop-hook';
+        die $@ if $@;
+    });
+    is($err, '', 'hook succeeds') or diag($task_log);
+    unlike($task_log, qr/WARN/, 'hook does not warn') or diag($task_log);
+
+    like($published->{uid}, qr/^[a-z2-7]{20}$/, 'other writer assigned a uid');
+    ok(!defined(PVE::LXC::Config->load_config(200)->{description}), 'hook wrote its config');
+    is_deeply(identity_of(200), $published, 'hook keeps the identity');
+
+    $lxc_module->unmock('get_staging_tempfs', 'vm_stop_cleanup');
+};
+
 remove_tree($WORKDIR);
 
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH container 20/34] api: migrate, clone: refuse targets that would drop the guest identity
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (18 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH container 19/34] fix #7846: config: add a guest identity to the 'meta' property Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH container 21/34] restore: take over the guest uid from the backup where possible Thomas Lamprecht
                   ` (15 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Older pve-container versions drop the 'meta' property when they write a
config, and with it the guest identity. A later write by an upgraded
node then assigns a new identity.

Refuse restart and offline migrations and clones to another node unless
the target reports a version that keeps the identity. Check before the
operation starts, and report such nodes with the versions involved in
the migration preconditions, so that clients can explain the refusal.

The migration API also checks requests that come through HA, but an HA
relocation stops the container before it calls that API. The recovery
of guests from a fenced node moves configs without this check.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/API2/LXC.pm         |  30 ++++++++
 src/test/lifecycle_tests.pl | 147 ++++++++++++++++++++++++++++++++++++
 2 files changed, 177 insertions(+)

diff --git a/src/PVE/API2/LXC.pm b/src/PVE/API2/LXC.pm
index b9a1337..3f9281e 100644
--- a/src/PVE/API2/LXC.pm
+++ b/src/PVE/API2/LXC.pm
@@ -14,6 +14,7 @@ use PVE::DataCenterConfig;
 use PVE::Exception qw(raise raise_param_exc raise_perm_exc);
 use PVE::Firewall;
 use PVE::GuestHelpers;
+use PVE::GuestIdentity;
 use PVE::INotify;
 use PVE::JSONSchema qw(get_standard_option);
 use PVE::RESTHandler;
@@ -1561,6 +1562,25 @@ __PACKAGE__->register_method({
                             },
                         },
                     },
+                    'guest-identity-unsupported' => {
+                        description =>
+                            "Set if migrating to the node is refused because the node does not"
+                            . " report a Proxmox VE version that keeps the guest identity.",
+                        type => 'object',
+                        optional => 1,
+                        properties => {
+                            version => {
+                                description => "The Proxmox VE version the node reports.",
+                                type => 'string',
+                                optional => 1,
+                            },
+                            'required-version' => {
+                                description =>
+                                    "The minimum Proxmox VE version that keeps the guest identity.",
+                                type => 'string',
+                            },
+                        },
+                    },
                 },
                 description => "List of not allowed nodes with additional information.",
             },
@@ -1623,6 +1643,12 @@ __PACKAGE__->register_method({
                     $blocking_ha_resources;
             }
 
+            # the migration refuses nodes that would drop the guest identity
+            if (my $unsupported = PVE::GuestIdentity::node_identity_unsupported($node)) {
+                $res->{'not-allowed-nodes'}->{$node}->{'guest-identity-unsupported'} =
+                    $unsupported;
+            }
+
             # if nothing came up, add it to the allowed nodes
             if (!defined($res->{'not-allowed-nodes'}->{$node})) {
                 push $res->{'allowed-nodes'}->@*, $node;
@@ -1701,6 +1727,8 @@ __PACKAGE__->register_method({
         PVE::Cluster::check_cfs_quorum();
 
         PVE::Cluster::check_node_exists($target);
+        # an older node drops the guest identity on its next write of the config
+        PVE::GuestIdentity::assert_node_supports_identity($target);
 
         my $targetip = PVE::Cluster::remote_node_ip($target);
 
@@ -2013,6 +2041,8 @@ __PACKAGE__->register_method({
         undef $target if $target && ($target eq $localnode || $target eq 'localhost');
 
         PVE::Cluster::check_node_exists($target) if $target;
+        # an older node drops the guest identity on its next write of the config
+        PVE::GuestIdentity::assert_node_supports_identity($target) if $target;
 
         my $storecfg = PVE::Storage::config();
 
diff --git a/src/test/lifecycle_tests.pl b/src/test/lifecycle_tests.pl
index 2e31984..47391c9 100755
--- a/src/test/lifecycle_tests.pl
+++ b/src/test/lifecycle_tests.pl
@@ -24,6 +24,7 @@ use Test::More;
 
 use PVE::Cluster;
 use PVE::GuestHelpers;
+use PVE::GuestIdentity;
 use PVE::INotify;
 use PVE::JSONSchema;
 use PVE::Tools qw(file_get_contents file_set_contents);
@@ -81,9 +82,21 @@ my $storage_cfg = {
             path => '/var/lib/vz',
             content => { rootdir => 1, images => 1, backup => 1, vztmpl => 1 },
         },
+        shared => {
+            type => 'nfs',
+            path => '/mnt/pve/shared',
+            shared => 1,
+            content => { rootdir => 1, images => 1 },
+        },
     },
 };
 
+# reported Proxmox VE versions of the other cluster nodes
+my $node_versions = {
+    'new-node' => '9.2.29',
+    'old-node' => '9.2.28',
+};
+
 my $cluster_module = Test::MockModule->new('PVE::Cluster');
 $cluster_module->mock(
     cfs_update => sub { },
@@ -115,6 +128,19 @@ $cluster_module->mock(
         return undef if $noerr;
         die "CT $vmid already exists on node '$NODENAME'\n";
     },
+    remote_node_ip => sub { return '192.0.2.1' },
+    get_node_pvecfg_version => sub {
+        my ($node) = @_;
+        return $node_versions->{$node};
+    },
+    node_pvecfg_version_at_least => sub {
+        my ($node, @required) = @_;
+        my @version = split(/\./, $node_versions->{$node} // return 0);
+        for my $i (0 .. 2) {
+            return $version[$i] > $required[$i] if $version[$i] != $required[$i];
+        }
+        return 1;
+    },
 );
 
 my $api_module = Test::MockModule->new('PVE::API2::LXC');
@@ -801,6 +827,127 @@ subtest 'post-stop hook keeps an identity published while it ran' => sub {
     $lxc_module->unmock('get_staging_tempfs', 'vm_stop_cleanup');
 };
 
+subtest 'migration is refused to nodes that drop the guest identity' => sub {
+    reset_configs();
+    my $raw = existing_config('ctime=1500000000,rtime=1500000000000,uid=existingexistingexis');
+    write_raw_config(200, $raw);
+
+    my $migrated_to;
+    my $migrate_module = Test::MockModule->new('PVE::LXC::Migrate');
+    $migrate_module->mock(migrate => sub { $migrated_to = $_[1] });
+    my $ha_config_module = Test::MockModule->new('PVE::HA::Config');
+    $ha_config_module->mock(vm_is_ha_managed => sub { return 0 });
+
+    my $migrate = sub {
+        my ($target, $param) = @_;
+        return run_task(sub {
+            PVE::API2::LXC->migrate_vm({
+                node => $NODENAME,
+                vmid => 200,
+                target => $target,
+                ($param // {})->%*,
+            });
+        });
+    };
+
+    my $err = $migrate->('old-node');
+    like($err, qr/node 'old-node' runs Proxmox VE 9\.2\.28/, 'node too old is refused');
+    $err = $migrate->('unknown-node');
+    like($err, qr/does not report its Proxmox VE version/, 'node without version is refused');
+
+    my $stopped = 0;
+    $lxc_module->mock(
+        check_running => sub { return 1 },
+        vm_stop => sub { $stopped = 1 },
+    );
+    $err = $migrate->('old-node', { restart => 1 });
+    $lxc_module->mock(check_running => sub { return 0 });
+    $lxc_module->unmock('vm_stop');
+    like($err, qr/node 'old-node' runs Proxmox VE 9\.2\.28/, 'restart migration is refused');
+    ok(!$stopped, 'running container is not stopped');
+
+    ok(!defined($migrated_to), 'migration does not start');
+    is(read_raw_config(200), $raw, 'config is unchanged');
+
+    $err = $migrate->('new-node');
+    is($err, '', 'migration to an upgraded node starts');
+    is($migrated_to, 'new-node', 'migration goes to the target');
+};
+
+subtest 'migration preconditions list nodes that drop the guest identity' => sub {
+    reset_configs();
+    my $raw = existing_config('ctime=1500000000,rtime=1500000000000,uid=existingexistingexis');
+    write_raw_config(200, $raw);
+
+    my $ha_config_module = Test::MockModule->new('PVE::HA::Config');
+    $ha_config_module->mock(vm_is_ha_managed => sub { return 0 });
+    $cluster_module->mock(
+        get_nodelist => sub { return [$NODENAME, 'new-node', 'old-node', 'unknown-node'] },
+    );
+
+    my $res = PVE::API2::LXC->migrate_vm_precondition({ node => $NODENAME, vmid => 200 });
+    $cluster_module->unmock('get_nodelist');
+
+    my $required = PVE::GuestIdentity::MIN_PVE_MANAGER_VERSION;
+    is_deeply($res->{'allowed-nodes'}, ['new-node'], 'only the upgraded node is allowed');
+    is_deeply(
+        $res->{'not-allowed-nodes'},
+        {
+            'old-node' => {
+                'guest-identity-unsupported' => {
+                    version => '9.2.28',
+                    'required-version' => $required,
+                },
+            },
+            'unknown-node' => {
+                'guest-identity-unsupported' => { 'required-version' => $required },
+            },
+        },
+        'nodes that drop the identity are not allowed',
+    );
+
+    my $returns = PVE::API2::LXC->map_method_by_name('migrate_vm_precondition')->{returns};
+    eval { PVE::JSONSchema::validate($res, $returns) };
+    is($@, '', 'result matches the schema');
+    # the schema documents the reasons of a node as the properties of 'not-allowed-nodes'
+    my $reasons_schema =
+        { $returns->{properties}->{'not-allowed-nodes'}->%*, additionalProperties => 0 };
+    for my $node ('old-node', 'unknown-node') {
+        my $reasons = $res->{'not-allowed-nodes'}->{$node};
+        eval { PVE::JSONSchema::validate($reasons, $reasons_schema) };
+        is($@, '', "reason for $node is documented in the schema");
+    }
+};
+
+subtest 'clone to another node is refused if the node drops the guest identity' => sub {
+    reset_configs();
+    my $raw = <<~'EOF';
+        arch: amd64
+        hostname: existing
+        memory: 512
+        meta: ctime=1500000000,rtime=1500000000000,uid=existingexistingexis
+        ostype: debian
+        rootfs: shared:200/vm-200-disk-0.raw,size=4G
+        unprivileged: 1
+        EOF
+    write_raw_config(200, $raw);
+    make_path(cfs_file("nodes/new-node/lxc"));
+
+    my $err = clone_ct(200, 201, { target => 'old-node' });
+    like($err, qr/node 'old-node' runs Proxmox VE 9\.2\.28/, 'clone is refused');
+    is(read_raw_config(200), $raw, 'source is unchanged');
+    ok(!defined(read_raw_config(201)), 'no clone is created');
+
+    $err = clone_ct(200, 201, { target => 'new-node' });
+    is($err, '', 'clone to an upgraded node succeeds') or diag($task_log);
+    my $clone_raw = read_raw_config(201, 'new-node');
+    ok(defined($clone_raw), 'clone is moved to the target node');
+    my $identity =
+        PVE::GuestIdentity::parse_identity($clone_raw =~ m/^meta: (.*)$/m ? $1 : undef);
+    like($identity->{uid}, qr/^[a-z2-7]{20}$/, 'clone has a uid');
+    isnt($identity->{uid}, 'existingexistingexis', 'clone has a new uid');
+};
+
 remove_tree($WORKDIR);
 
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH container 21/34] restore: take over the guest uid from the backup where possible
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (19 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH container 20/34] api: migrate, clone: refuse targets that would drop the guest identity Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH container 22/34] restore: refuse overwriting a container with another guest's backup Thomas Lamprecht
                   ` (14 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

A restore to an unused VMID, or over a container without an identity,
should keep the uid of the backup if no other guest in the cluster uses
it. Take over that uid after the data is restored and the final config
is written, while holding the config lock. With 'unique', or if the uid
is in use, the container keeps the identity assigned when its VMID was
reserved. In all these cases the registration time is the time of the
restore. A container that already had an identity keeps both its uid
and its registration time.

Taking over the uid only after the restore succeeded means that a
failed restore does not take the uid for a container it leaves behind.
If the cluster-wide lock cannot be taken, warn and do not fail the
completed restore; the container keeps its own identity. Report the
outcome in the task log.

Record the uid of the backup as a pending change of 'meta' until the
restore finished, if the restore could take it over. A retry over a
container left behind by an unfinished restore can then take the uid
over, if no other guest uses it. Record it with 'unique' too, which
only keeps the current restore from taking the uid. If the cluster-wide
lock cannot be taken, the pending uid stays for a later attempt.

A pending uid does not count as in use, so a retry at another VMID
stays possible. Outside of a restore, applying pending changes drops
it.

For restores from a file, PBS or a backup provider, record the pending
uid as soon as the config of the backup is known and keep it in the
configs that the restore writes afterwards. For standard input, the uid
is only known from the restored config, as API parameters cannot set
'meta'. That config carries the pending uid, also if the conversion to
a template writes it first. Archives without a PVE config have no uid.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/API2/LXC.pm         |  58 ++++-
 src/test/lifecycle_tests.pl | 462 +++++++++++++++++++++++++++++++++++-
 2 files changed, 514 insertions(+), 6 deletions(-)

diff --git a/src/PVE/API2/LXC.pm b/src/PVE/API2/LXC.pm
index 3f9281e..b354e9d 100644
--- a/src/PVE/API2/LXC.pm
+++ b/src/PVE/API2/LXC.pm
@@ -60,6 +60,39 @@ my sub assert_not_restore_from_external {
     die "refusing to restore privileged container backup from external source\n";
 }
 
+# Takes over $uid, offered by the backup of a restore, as uid of the container $vmid, after the
+# final config write of the restore, and logs the result. A failure only warns and keeps the
+# identity of the reservation, as the container itself got restored.
+my sub adopt_backup_identity {
+    my ($vmid, $uid, $reservation) = @_;
+
+    my $res = eval { PVE::GuestIdentity::adopt('PVE::LXC::Config', $vmid, $uid, $reservation) };
+    if (my $err = $@) {
+        chomp($err);
+        my $kept = $reservation->{reserved}->{uid} // 'none';
+        my $msg =
+            defined($uid)
+            ? "unable to adopt backup uid $uid, keeping uid $kept"
+            : "keeping uid $kept";
+        PVE::RPCEnvironment::get()->warn("guest identity: $msg - $err");
+        return;
+    }
+
+    print PVE::GuestIdentity::adopt_result_message($res, 'backup') . "\n";
+}
+
+# Returns the uid of the backup if the restore could take it over at its end, see
+# PVE::GuestIdentity::adoptable_uid. Until then, the restore keeps it as pending uid in every config
+# it writes, so that a container left behind by a failure or an abort still has it for a retry.
+# That holds with 'unique' too, which only keeps the restore itself from taking the uid over.
+my sub restore_pending_uid {
+    my ($reservation, $backup_identity) = @_;
+
+    my $uid = $backup_identity && $backup_identity->{uid};
+
+    return PVE::GuestIdentity::adoptable_uid($reservation, $uid);
+}
+
 my $check_storage_access_migrate = sub {
     my ($rpcenv, $authuser, $storecfg, $storage, $node) = @_;
 
@@ -428,7 +461,7 @@ __PACKAGE__->register_method({
 
         my $emsg = $restore ? "unable to restore CT $vmid -" : "unable to create CT $vmid -";
 
-        eval { PVE::LXC::Config->create_and_lock_config($vmid, $force) };
+        my $reservation = eval { PVE::LXC::Config->create_and_lock_config($vmid, $force) };
         die "$emsg $@" if $@;
 
         my $destroy_config_on_error = !$same_container_exists;
@@ -436,6 +469,7 @@ __PACKAGE__->register_method({
         my $code = sub {
             my $old_conf = PVE::LXC::Config->load_config($vmid);
             my $was_template;
+            my ($backup_identity, $pending_uid);
 
             my $vollist = [];
             eval {
@@ -447,6 +481,10 @@ __PACKAGE__->register_method({
                         print "recovering backed-up configuration from '$archive'\n";
                         ($orig_conf, $orig_mp_param) =
                             PVE::LXC::Create::recover_config($storage_cfg, $archive, $vmid);
+                        $backup_identity = PVE::LXC::Config->get_identity($orig_conf);
+                        $pending_uid = restore_pending_uid($reservation, $backup_identity);
+                        PVE::LXC::Config->record_pending_uid($vmid, $pending_uid)
+                            if defined($pending_uid);
 
                         for my $opt (keys %$orig_conf) {
                             # early check before disks are created
@@ -547,12 +585,11 @@ __PACKAGE__->register_method({
 
                 # we always have the 'create' lock so check for more than 1 entry
                 if (scalar(keys %$old_conf) > 1) {
+                    my $replacement_conf = { lock => 'create' };
+                    PVE::GuestIdentity::set_pending_uid($replacement_conf, $pending_uid);
                     # destroy old container volumes
                     PVE::LXC::destroy_lxc_container(
-                        $storage_cfg,
-                        $vmid,
-                        $old_conf,
-                        { lock => 'create' },
+                        $storage_cfg, $vmid, $old_conf, $replacement_conf,
                     );
                 }
 
@@ -594,6 +631,11 @@ __PACKAGE__->register_method({
                             $unique,
                             $skip_fw_config_restore,
                         );
+                        # the API parameters cannot carry 'meta', so it comes from the backup
+                        if ($archive eq '-') {
+                            $backup_identity = PVE::LXC::Config->get_identity($conf);
+                            $pending_uid = restore_pending_uid($reservation, $backup_identity);
+                        }
                         PVE::LXC::create_ifaces_ipams_ips($conf, $vmid) if $unique;
                         my $lxc_setup = PVE::LXC::Setup->new($conf, $rootdir);
                         $lxc_setup->post_restore_hook($password, $ssh_keys);
@@ -617,6 +659,8 @@ __PACKAGE__->register_method({
                 foreach my $mp (keys %$delayed_mp_param) {
                     $conf->{$mp} = $delayed_mp_param->{$mp};
                 }
+                # the template conversion writes the restored config, too
+                PVE::GuestIdentity::set_pending_uid($conf, $pending_uid);
                 # If the template flag was set, we try to convert again to template after restore
                 if ($was_template) {
                     print STDERR "Convert restored container to template...\n";
@@ -640,6 +684,10 @@ __PACKAGE__->register_method({
                 }
                 die "$emsg $err";
             }
+            if ($restore) {
+                my $uid = $backup_identity && $backup_identity->{uid};
+                adopt_backup_identity($vmid, $unique ? undef : $uid, $reservation);
+            }
             PVE::AccessControl::add_vm_to_pool($vmid, $pool) if $pool;
         };
 
diff --git a/src/test/lifecycle_tests.pl b/src/test/lifecycle_tests.pl
index 47391c9..bed9b72 100755
--- a/src/test/lifecycle_tests.pl
+++ b/src/test/lifecycle_tests.pl
@@ -16,6 +16,7 @@ BEGIN {
     $INC{'PVE/VZDump.pm'} = __FILE__;
 }
 
+use Fcntl qw(:flock);
 use File::Path qw(make_path remove_tree);
 use JSON;
 use Socket qw(AF_UNIX SOCK_STREAM PF_UNSPEC);
@@ -64,6 +65,14 @@ my sub write_raw_config {
     file_set_contents($file, $raw);
 }
 
+my sub write_raw_vm_config {
+    my ($vmid, $raw) = @_;
+
+    my $dir = cfs_file("nodes/$NODENAME/qemu-server");
+    make_path($dir);
+    file_set_contents("$dir/$vmid.conf", $raw);
+}
+
 my sub read_raw_config {
     my ($vmid, $node) = @_;
 
@@ -71,8 +80,11 @@ my sub read_raw_config {
     return -f $file ? file_get_contents($file) : undef;
 }
 
+my $written = {}; # VMID => the written raw configs, in the order of the writes
+
 my sub reset_configs {
     remove_tree("$WORKDIR/cfs", "$WORKDIR/rootfs");
+    $written = {};
 }
 
 my $storage_cfg = {
@@ -91,6 +103,9 @@ my $storage_cfg = {
     },
 };
 
+# error of the cluster-wide guest identity lock, if set
+my $domain_lock_error;
+
 # reported Proxmox VE versions of the other cluster nodes
 my $node_versions = {
     'new-node' => '9.2.29',
@@ -121,6 +136,7 @@ $cluster_module->mock(
         my $file = cfs_file($path);
         make_path($file =~ s|/[^/]+$||r);
         file_set_contents($file, $raw);
+        push $written->{ ($path =~ m|/(\d+)\.conf$|)[0] }->@*, $raw;
     },
     check_vmid_unused => sub {
         my ($vmid, $noerr) = @_;
@@ -128,6 +144,30 @@ $cluster_module->mock(
         return undef if $noerr;
         die "CT $vmid already exists on node '$NODENAME'\n";
     },
+    cfs_lock_domain => sub {
+        my ($domain, $timeout, $code, @param) = @_;
+        die "unexpected lock domain '$domain'\n" if $domain ne 'guest-identity';
+        if (defined($domain_lock_error)) {
+            $@ = $domain_lock_error;
+            return undef;
+        }
+        my $res = eval { $code->(@param) };
+        return $res;
+    },
+    get_guest_config_properties => sub {
+        my ($properties) = @_;
+        my $res = {};
+        for my $file (glob("$WORKDIR/cfs/nodes/*/{lxc,qemu-server}/*.conf")) {
+            my ($vmid) = $file =~ m|/(\d+)\.conf$|;
+            for my $line (split(/\n/, file_get_contents($file))) {
+                last if $line =~ m/^\[/;
+                for my $property (@$properties) {
+                    $res->{$vmid}->{$property} = $1 if $line =~ m/^\Q$property\E:\s*(.*?)\s*$/;
+                }
+            }
+        }
+        return $res;
+    },
     remote_node_ip => sub { return '192.0.2.1' },
     get_node_pvecfg_version => sub {
         my ($node) = @_;
@@ -200,7 +240,13 @@ package PVE::LXC::Test::RPCEnvironment {
     }
 
     sub get_user { return $_[0]->{user} }
-    sub check { return 1 }
+
+    sub check {
+        my ($self, $user, $path, $privs, $noerr) = @_;
+        return 1 if !$self->{deny}->{$path};
+        return 0 if $noerr;
+        die "permission check failed ($path, " . join(', ', @$privs) . ")\n";
+    }
     sub check_vm_perm { return 1 }
     sub check_pool_exist { return 1 }
 
@@ -253,6 +299,7 @@ my sub run_task {
 # Fake storage and container runtime
 
 my $backup_raw_config;
+my $backup_read_error;
 
 my $storage_module = Test::MockModule->new('PVE::Storage');
 $storage_module->mock(
@@ -318,6 +365,7 @@ $create_module->mock(
     archive_is_oci_format => sub { return 0 },
     recover_config => sub {
         my ($storecfg, $volid, $vmid) = @_;
+        die $backup_read_error if defined($backup_read_error);
         my $conf = PVE::LXC::Config::parse_pct_config("/lxc/$vmid.conf", $backup_raw_config);
         delete $conf->{snapshots};
         my $mp_param = {};
@@ -948,6 +996,418 @@ subtest 'clone to another node is refused if the node drops the guest identity'
     isnt($identity->{uid}, 'existingexistingexis', 'clone has a new uid');
 };
 
+subtest 'restore takes over the guest identity with the config lock held' => sub {
+    reset_configs();
+    $backup_raw_config =
+        backup_config('ctime=1400000000,rtime=1400000000000,uid=backupbackupbackupba');
+
+    my $real_adopt = \&PVE::GuestIdentity::adopt;
+    my $locked;
+    $identity_module->mock(
+        adopt => sub {
+            my ($class, $vmid) = @_;
+            open(my $fh, '>>', "$WORKDIR/lock/pve-config-$vmid.lock")
+                or die "open failed - $!\n";
+            $locked = !flock($fh, LOCK_EX | LOCK_NB);
+            close($fh);
+            return $real_adopt->(@_);
+        },
+    );
+    my $err = restore_ct(200);
+    $identity_module->unmock('adopt');
+
+    is($err, '', 'restore succeeds') or diag($task_log);
+    ok($locked, 'config lock is held while taking over the identity');
+    is(identity_of(200)->{uid}, 'backupbackupbackupba', 'uid of the backup is taken over');
+};
+
+subtest 'restore takes over the guest identity of the backup' => sub {
+    my $backup_meta = 'ctime=1400000000,rtime=1400000000000,uid=backupbackupbackupba';
+    my $existing_meta = 'ctime=1500000000,rtime=1500000000000,uid=existingexistingexis';
+    $now_ms = 1_700_000_000_000;
+
+    my $in_use_by_ct =
+        "guest identity: backup uid backupbackupbackupba is in use by guest 150, keeping uid ";
+
+    my $run = sub {
+        my ($name, $setup, $param, $expected_uid, $expected_rtime, $expected_log) = @_;
+
+        reset_configs();
+        $setup->();
+        my $err = restore_ct(200, $param);
+        is($err, '', "$name: restore succeeds") or diag($task_log);
+        my $identity = identity_of(200);
+        if (defined($expected_uid)) {
+            is($identity->{uid}, $expected_uid, "$name: uid");
+        } else {
+            like($identity->{uid}, qr/^[a-z2-7]{20}$/, "$name: uid is assigned");
+            isnt(
+                $identity->{uid},
+                'backupbackupbackupba',
+                "$name: uid is not the one of the backup",
+            );
+        }
+        is($identity->{rtime}, $expected_rtime, "$name: rtime");
+        like($task_log, $expected_log, "$name: result is logged");
+    };
+
+    $backup_raw_config = backup_config($backup_meta);
+    $run->(
+        'free VMID',
+        sub { },
+        {},
+        'backupbackupbackupba',
+        $now_ms,
+        qr/^guest identity: adopted uid backupbackupbackupba from the backup$/m,
+    );
+    $run->(
+        'free VMID, uid used by another container',
+        sub { write_raw_config(150, existing_config('uid=backupbackupbackupba')) },
+        {},
+        undef,
+        $now_ms,
+        qr/^\Q$in_use_by_ct\E[a-z2-7]{20}$/m,
+    );
+    $run->(
+        'free VMID, uid used by a VM',
+        sub { write_raw_vm_config(151, "memory: 512\nmeta: uid=backupbackupbackupba\n") },
+        {},
+        undef,
+        $now_ms,
+        qr/^guest identity: backup uid backupbackupbackupba is in use by guest 151, keeping uid /m,
+    );
+    $run->(
+        'free VMID, unique',
+        sub { },
+        { unique => 1 },
+        undef,
+        $now_ms,
+        qr/^guest identity: new uid [a-z2-7]{20}$/m,
+    );
+    $run->(
+        'in place, target without identity',
+        sub { write_raw_config(200, existing_config('ctime=1500000000')) },
+        { force => 1 },
+        'backupbackupbackupba',
+        $now_ms,
+        qr/^guest identity: adopted uid backupbackupbackupba from the backup$/m,
+    );
+    $run->(
+        'in place, target without identity, unique',
+        sub { write_raw_config(200, existing_config('ctime=1500000000')) },
+        { force => 1, unique => 1 },
+        undef,
+        $now_ms,
+        qr/^guest identity: new uid [a-z2-7]{20}$/m,
+    );
+    $run->(
+        'in place, target with the same identity',
+        sub {
+            write_raw_config(
+                200,
+                existing_config(
+                    'ctime=1500000000,rtime=1500000000000,uid=backupbackupbackupba'),
+            );
+        },
+        { force => 1 },
+        'backupbackupbackupba',
+        1500000000000,
+        qr/^guest identity: kept uid backupbackupbackupba$/m,
+    );
+    $run->(
+        'in place, target with the same identity, unique',
+        sub {
+            write_raw_config(
+                200,
+                existing_config(
+                    'ctime=1500000000,rtime=1500000000000,uid=backupbackupbackupba'),
+            );
+        },
+        { force => 1, unique => 1 },
+        'backupbackupbackupba',
+        1500000000000,
+        qr/^guest identity: kept uid backupbackupbackupba$/m,
+    );
+
+    $backup_raw_config = backup_config('ctime=1400000000');
+    $run->(
+        'free VMID, backup without identity',
+        sub { },
+        {},
+        undef,
+        $now_ms,
+        qr/^guest identity: new uid [a-z2-7]{20}$/m,
+    );
+    $run->(
+        'in place, target with identity, backup without identity',
+        sub { write_raw_config(200, existing_config($existing_meta)) },
+        { force => 1 },
+        'existingexistingexis',
+        1500000000000,
+        qr/^guest identity: kept uid existingexistingexis$/m,
+    );
+
+    $backup_raw_config = backup_config($backup_meta);
+    $run->(
+        'free VMID, from STDIN',
+        sub { },
+        { ostemplate => '-', rootfs => 'local:4' },
+        'backupbackupbackupba',
+        $now_ms,
+        qr/^guest identity: adopted uid backupbackupbackupba from the backup$/m,
+    );
+    $backup_raw_config = undef;
+    $run->(
+        'free VMID, from STDIN without config',
+        sub { },
+        { ostemplate => '-', rootfs => 'local:4' },
+        undef,
+        $now_ms,
+        qr/^guest identity: new uid [a-z2-7]{20}$/m,
+    );
+};
+
+subtest 'restore keeps the new guest identity if the identity lock fails' => sub {
+    reset_configs();
+    $now_ms = 1_700_000_000_000;
+    $backup_raw_config =
+        backup_config('ctime=1400000000,rtime=1400000000000,uid=backupbackupbackupba');
+    $domain_lock_error = "cfs-lock 'domain-guest-identity' error: no quorum!\n";
+
+    my $err = restore_ct(200);
+    $domain_lock_error = undef;
+    is($err, '', 'restore succeeds') or diag($task_log);
+    my $identity = identity_of(200);
+    like($identity->{uid}, qr/^[a-z2-7]{20}$/, 'uid is assigned');
+    isnt($identity->{uid}, 'backupbackupbackupba', 'uid of the backup is not taken over');
+    my $warning =
+        "WARN: guest identity: unable to adopt backup uid backupbackupbackupba, keeping"
+        . " uid $identity->{uid} - cfs-lock 'domain-guest-identity' error: no quorum!";
+    like($task_log, qr/^\Q$warning\E$/m, 'failure is logged as warning');
+};
+
+my sub pending_uid_of {
+    my ($vmid) = @_;
+
+    return PVE::GuestIdentity::get_pending_uid(PVE::LXC::Config->load_config($vmid));
+}
+
+subtest 'failed restore keeps the uid of the backup only as pending uid' => sub {
+    reset_configs();
+    $backup_raw_config =
+        backup_config('ctime=1400000000,rtime=1400000000000,uid=backupbackupbackupba');
+
+    my $fake_setup_module = Test::MockModule->new('PVE::LXC::Test::Setup', no_auto => 1);
+    $fake_setup_module->mock(post_restore_hook => sub { die "post-restore hook failed\n" });
+
+    my $err = restore_ct(200);
+    like($err, qr/post-restore hook failed/, 'restore fails');
+    ok(!defined(read_raw_config(200)), 'config of the free VMID is removed');
+
+    $fake_setup_module->unmock('post_restore_hook');
+    $err = restore_ct(200);
+    is($err, '', 'retry restores to a free VMID again') or diag($task_log);
+    like(
+        $task_log,
+        qr/^guest identity: adopted uid backupbackupbackupba from the backup$/m,
+        'retry takes over the uid of the backup',
+    );
+    PVE::LXC::Config->destroy_config(200);
+
+    my $existing_meta = 'ctime=1500000000,rtime=1500000000000,uid=existingexistingexis';
+    write_raw_config(200, existing_config($existing_meta));
+    $backup_read_error = "unable to read backup\n";
+    $err = restore_ct(200, { force => 1 });
+    $backup_read_error = undef;
+    like($err, qr/unable to read backup/, 'restore fails before changing the container');
+    my $conf = PVE::LXC::Config->load_config(200);
+    is($conf->{meta}, $existing_meta, 'target keeps its identity');
+    ok(!defined($conf->{lock}), 'create lock is removed');
+
+    # a privileged backup needs Sys.Modify, which is checked after reading the backup
+    $backup_raw_config =
+        backup_config('ctime=1400000000,rtime=1400000000000,uid=backupbackupbackupba') =~
+        s/^unprivileged: 1\n//mr;
+    write_raw_config(200, existing_config('ctime=1500000000'));
+    $rpcenv->{deny}->{'/'} = 1;
+    $err = restore_ct(200, { force => 1 });
+    delete $rpcenv->{deny};
+    like($err, qr/permission check failed/, 'restore fails after reading the backup');
+    my $identity = identity_of(200);
+    like($identity->{uid}, qr/^[a-z2-7]{20}$/, 'target got an identity with the reservation');
+    isnt($identity->{uid}, 'backupbackupbackupba', 'uid of the backup is not taken over');
+    is(pending_uid_of(200), 'backupbackupbackupba', 'target has it as pending uid');
+    ok(!defined(PVE::LXC::Config->load_config(200)->{lock}), 'create lock is removed');
+
+    $err = restore_ct(200, { force => 1 });
+    is($err, '', 'retry of the same restore succeeds') or diag($task_log);
+    like(
+        $task_log,
+        qr/^guest identity: adopted uid backupbackupbackupba from the backup$/m,
+        'retry takes over the uid of the backup',
+    );
+    is(identity_of(200)->{uid}, 'backupbackupbackupba', 'published');
+    is(pending_uid_of(200), undef, 'pending uid is removed');
+};
+
+# Restores in place over a container without identity, failing after reading the backup.
+my sub failed_restore_in_place {
+    reset_configs();
+    $backup_raw_config =
+        backup_config('ctime=1400000000,rtime=1400000000000,uid=backupbackupbackupba') =~
+        s/^unprivileged: 1\n//mr;
+    write_raw_config(200, existing_config('ctime=1500000000'));
+    $rpcenv->{deny}->{'/'} = 1;
+    my $err = restore_ct(200, { force => 1 });
+    delete $rpcenv->{deny};
+    like($err, qr/permission check failed/, 'restore fails after reading the backup');
+    is(pending_uid_of(200), 'backupbackupbackupba', 'container left behind has the pending uid');
+}
+
+subtest 'retry elsewhere, then over the container left behind' => sub {
+    failed_restore_in_place();
+    my $leftover = identity_of(200)->{uid};
+
+    my $err = restore_ct(201);
+    is($err, '', 'restore to another VMID succeeds') or diag($task_log);
+    is(identity_of(201)->{uid}, 'backupbackupbackupba', 'pending uid is not in use');
+    is(pending_uid_of(200), 'backupbackupbackupba', 'container left behind keeps it');
+
+    $err = restore_ct(200, { force => 1 });
+    is($err, '', 'restore over the container left behind succeeds') or diag($task_log);
+    like(
+        $task_log,
+        qr/: backup uid backupbackupbackupba is in use by guest 201, keeping uid $leftover$/m,
+        'uid of the backup is in use by now',
+    );
+    is(identity_of(200)->{uid}, $leftover, 'container left behind keeps its uid');
+    is(pending_uid_of(200), undef, 'pending uid is removed');
+};
+
+subtest 'using the container left behind drops its pending uid' => sub {
+    failed_restore_in_place();
+
+    my $err = update_ct(200, { description => 'used' });
+    is($err, '', 'config change of the stopped container') or diag($task_log);
+    like($task_log, qr/ignoring pending change of read-only option 'meta'/, 'dropped');
+    is(pending_uid_of(200), undef, 'pending uid is gone');
+};
+
+subtest 'restore with unique keeps a pending uid, but never takes it over' => sub {
+    for my $retry ({ unique => 1 }, {}) {
+        my $what = $retry->{unique} ? 'retry with unique' : 'retry without unique';
+
+        reset_configs();
+        $backup_raw_config =
+            backup_config('ctime=1400000000,rtime=1400000000000,uid=backupbackupbackupba') =~
+            s/^unprivileged: 1\n//mr;
+        write_raw_config(200, existing_config('ctime=1500000000'));
+        $rpcenv->{deny}->{'/'} = 1;
+        my $err = restore_ct(200, { force => 1, unique => 1 });
+        delete $rpcenv->{deny};
+        like(
+            $err,
+            qr/permission check failed/,
+            'restore with unique fails after reading the backup',
+        );
+        my $leftover = identity_of(200)->{uid};
+        is(
+            pending_uid_of(200),
+            'backupbackupbackupba',
+            'container left behind has the pending uid',
+        );
+
+        $err = restore_ct(200, { force => 1, $retry->%* });
+        is($err, '', "$what succeeds") or diag($task_log);
+        is(pending_uid_of(200), undef, "$what: pending uid is removed");
+        is(
+            identity_of(200)->{uid},
+            $retry->{unique} ? $leftover : 'backupbackupbackupba',
+            "$what: "
+                . ($retry->{unique} ? 'keeps its uid' : 'takes over the uid of the backup'),
+        );
+    }
+};
+
+subtest 'failed adoption keeps the pending uid' => sub {
+    reset_configs();
+    $backup_raw_config =
+        backup_config('ctime=1400000000,rtime=1400000000000,uid=backupbackupbackupba');
+    $domain_lock_error = "cfs-lock 'domain-guest-identity' error: no quorum!\n";
+    my $err = restore_ct(200);
+    $domain_lock_error = undef;
+    is($err, '', 'restore succeeds') or diag($task_log);
+    like(
+        $task_log,
+        qr/unable to adopt backup uid backupbackupbackupba, keeping uid /,
+        'warning',
+    );
+    isnt(identity_of(200)->{uid}, 'backupbackupbackupba', 'container has a uid of its own');
+    is(pending_uid_of(200), 'backupbackupbackupba', 'nothing decided, pending uid stays');
+
+    $err = restore_ct(200, { force => 1 });
+    is($err, '', 'restore of the backup again is not refused') or diag($task_log);
+    is(identity_of(200)->{uid}, 'backupbackupbackupba', 'uid of the backup is taken over');
+};
+
+subtest 'config of a container left behind shows its published identity' => sub {
+    failed_restore_in_place();
+    my $meta = PVE::LXC::Config->load_config(200)->{meta};
+
+    my $conf = PVE::API2::LXC::Config->vm_config({ node => $NODENAME, vmid => 200 });
+    is($conf->{meta}, $meta, 'config with pending changes applied: published identity');
+    $conf = PVE::API2::LXC::Config->vm_config({ node => $NODENAME, vmid => 200, current => 1 });
+    is($conf->{meta}, $meta, 'current config: published identity');
+
+    my $pending = PVE::API2::LXC->vm_pending({ node => $NODENAME, vmid => 200 });
+    my ($item) = grep { $_->{key} eq 'meta' } $pending->@*;
+    is($item->{value}, $meta, 'pending view: current value');
+    is($item->{pending}, 'uid=backupbackupbackupba', 'pending view: pending uid');
+};
+
+# Once a write of the config of CT 200 has the pending uid of the backup, all later writes of the
+# restore have it, so that the container keeps it whenever the restore stops. Only the adoption
+# removes it.
+subtest 'every write of a restore keeps the pending uid' => sub {
+    my $backup_meta = 'ctime=1400000000,rtime=1400000000000,uid=backupbackupbackupba';
+    my $cases = [
+        ['free VMID', undef, {}],
+        ['in place over a container without uid', existing_config('ctime=1500000000'), {}],
+        ['free VMID, from STDIN', undef, { ostemplate => '-', rootfs => 'local:4' }],
+        ['free VMID, template', undef, {}, "template: 1\n"],
+    ];
+    $storage_module->mock(volume_has_feature => sub { return 0 });
+
+    for my $case (@$cases) {
+        my ($what, $target, $param, $extra) = @$case;
+
+        reset_configs();
+        $backup_raw_config = backup_config($backup_meta) . ($extra // '');
+        write_raw_config(200, $target) if $target;
+        my $err = restore_ct(200, { $target ? (force => 1) : (), $param->%* });
+        is($err, '', "$what: restore succeeds") or diag($task_log);
+        like(
+            $task_log,
+            qr/^guest identity: adopted uid backupbackupbackupba/m,
+            "$what: adopted",
+        );
+
+        my @writes = $written->{200}->@*;
+        my $last = pop(@writes);
+        my $first = 0;
+        $first++ while $first < @writes && $writes[$first] !~ m/^\[pve:pending\]/m;
+        ok($first < @writes, "$what: pending uid is written") or next;
+        my @later = @writes[$first .. $#writes];
+        is(
+            scalar(grep { m/^\[pve:pending\]\nmeta: uid=backupbackupbackupba$/m } @later),
+            scalar(@later),
+            "$what: all later writes keep it",
+        );
+        unlike($last, qr/^\[pve:pending\]/m, "$what: adoption removes it");
+    }
+    $storage_module->unmock('volume_has_feature');
+};
+
 remove_tree($WORKDIR);
 
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH container 22/34] restore: refuse overwriting a container with another guest's backup
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (20 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH container 21/34] restore: take over the guest uid from the backup where possible Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH container 23/34] migrate: remote: clean up the target on a tunnel version mismatch Thomas Lamprecht
                   ` (13 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Restoring the backup of another guest over an existing container
results in the data of the backup under the identity of the target.
Tools that follow that identity would take the result for the original
guest.

Refuse a restore if the uids differ, unless 'allow-identity-mismatch'
is set through the create API or 'pct restore'. The existing 'force'
option permits overwriting a container but does not override this
check. With the override, a container that already had an identity
keeps it.

A container that has the uid of the backup as pending uid was left
behind by an unfinished restore of that backup, so a retry may proceed.
Without 'unique', the retry takes that uid over if no other guest uses
it.

For standard input, the config of the backup is only known after the
old volumes were destroyed and the archive got extracted. So require
the override whenever the target already has an identity. A target
without identity can still be overwritten without it.

Compare the uids before the restore destroys anything. Apply the
network options only after that as well: applying them can allocate
addresses in the IPAM of SDN, and the cleanup after a failure can
remove mappings for MAC addresses that the existing container still
uses. Validate and queue those options before the worker starts,
without changing the IPAM state.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/API2/LXC.pm         |  56 +++++++++++++-
 src/test/lifecycle_tests.pl | 141 ++++++++++++++++++++++++++++++++++++
 2 files changed, 196 insertions(+), 1 deletion(-)

diff --git a/src/PVE/API2/LXC.pm b/src/PVE/API2/LXC.pm
index b354e9d..06049d7 100644
--- a/src/PVE/API2/LXC.pm
+++ b/src/PVE/API2/LXC.pm
@@ -231,6 +231,16 @@ __PACKAGE__->register_method({
                 description => "Assign a unique random ethernet address.",
                 requires => 'restore',
             },
+            'allow-identity-mismatch' => {
+                optional => 1,
+                type => 'boolean',
+                description => "Allow to overwrite an existing container with a backup of"
+                    . " another guest, as detected by a different 'uid' in 'meta'. A restore from"
+                    . " standard input over a container that has a uid always needs this option,"
+                    . " as the backup cannot be checked beforehand. Unless the container is left"
+                    . " over from an unfinished restore of the same backup, it keeps its own uid.",
+                requires => 'restore',
+            },
             pool => {
                 optional => 1,
                 type => 'string',
@@ -293,6 +303,7 @@ __PACKAGE__->register_method({
         my $unprivileged = extract_param($param, 'unprivileged');
         my $restore = extract_param($param, 'restore');
         my $unique = extract_param($param, 'unique');
+        my $allow_identity_mismatch = extract_param($param, 'allow-identity-mismatch');
 
         $param->{cpuunits} = PVE::CGroup::clamp_cpu_shares($param->{cpuunits})
             if defined($param->{cpuunits}); # clamp value depending on cgroup version
@@ -454,7 +465,13 @@ __PACKAGE__->register_method({
         # check/activate default storage
         &$check_and_activate_storage($storage) if !defined($mp_param->{rootfs});
 
-        PVE::LXC::Config->update_pct_config($vmid, $conf, 0, $no_disk_param);
+        if ($restore) {
+            # applying network options can allocate addresses in the IPAM of SDN, so only check and
+            # queue the options here, and apply them once the restore may overwrite the container
+            PVE::LXC::Config->queue_pct_config_changes($vmid, $conf, $no_disk_param, [], []);
+        } else {
+            PVE::LXC::Config->update_pct_config($vmid, $conf, 0, $no_disk_param);
+        }
 
         $conf->{unprivileged} = 1 if $unprivileged;
         $conf->{meta} = PVE::LXC::Config->new_meta_info_string() if !$restore;
@@ -466,6 +483,36 @@ __PACKAGE__->register_method({
 
         my $destroy_config_on_error = !$same_container_exists;
 
+        # Restoring over an existing container must not turn it into another guest. The identity of
+        # a backup from STDIN is only known once the container got overwritten. A container with the
+        # uid of the backup as pending uid is a leftover of an earlier restore of it.
+        my $assert_identity_matches = sub {
+            my ($backup_identity, $from_stdin) = @_;
+
+            my $target = $reservation->{identity} or return;
+
+            if ($from_stdin) {
+                die "cannot verify the guest identity of a backup from standard input before"
+                    . " overwriting CT $vmid (uid '$target->{uid}') - use 'allow-identity-mismatch'"
+                    . " to overwrite the CT anyway\n"
+                    if !$allow_identity_mismatch;
+                return;
+            }
+
+            return
+                if !$backup_identity
+                || PVE::GuestIdentity::uid_matches_target($reservation, $backup_identity->{uid});
+
+            my $uid = $backup_identity->{uid};
+            die "backup belongs to another guest: its uid '$uid' differs from uid"
+                . " '$target->{uid}' of the existing CT $vmid - use 'allow-identity-mismatch' to"
+                . " overwrite the CT anyway\n"
+                if !$allow_identity_mismatch;
+
+            print "guest identity: ignoring backup uid $uid, CT $vmid keeps uid"
+                . " $target->{uid}\n";
+        };
+
         my $code = sub {
             my $old_conf = PVE::LXC::Config->load_config($vmid);
             my $was_template;
@@ -482,6 +529,7 @@ __PACKAGE__->register_method({
                         ($orig_conf, $orig_mp_param) =
                             PVE::LXC::Create::recover_config($storage_cfg, $archive, $vmid);
                         $backup_identity = PVE::LXC::Config->get_identity($orig_conf);
+                        $assert_identity_matches->($backup_identity);
                         $pending_uid = restore_pending_uid($reservation, $backup_identity);
                         PVE::LXC::Config->record_pending_uid($vmid, $pending_uid)
                             if defined($pending_uid);
@@ -517,7 +565,11 @@ __PACKAGE__->register_method({
                         ) {
                             $rpcenv->check($authuser, '/', ['Sys.Modify']);
                         }
+                    } else {
+                        $assert_identity_matches->(undef, 1);
                     }
+
+                    PVE::LXC::Config->vmconfig_apply_pending($vmid, $conf, $storage_cfg);
                 }
                 if ($storage_only_mode) {
                     if ($restore) {
@@ -634,6 +686,8 @@ __PACKAGE__->register_method({
                         # the API parameters cannot carry 'meta', so it comes from the backup
                         if ($archive eq '-') {
                             $backup_identity = PVE::LXC::Config->get_identity($conf);
+                            # only logs a mismatch, which needed the override already
+                            $assert_identity_matches->($backup_identity);
                             $pending_uid = restore_pending_uid($reservation, $backup_identity);
                         }
                         PVE::LXC::create_ifaces_ipams_ips($conf, $vmid) if $unique;
diff --git a/src/test/lifecycle_tests.pl b/src/test/lifecycle_tests.pl
index bed9b72..d93f24e 100755
--- a/src/test/lifecycle_tests.pl
+++ b/src/test/lifecycle_tests.pl
@@ -32,6 +32,7 @@ use PVE::Tools qw(file_get_contents file_set_contents);
 
 use PVE::API2::LXC;
 use PVE::API2::LXC::Config;
+use PVE::CLI::pct;
 use PVE::LXC;
 use PVE::LXC::Config;
 use PVE::LXC::Create;
@@ -300,6 +301,7 @@ my sub run_task {
 
 my $backup_raw_config;
 my $backup_read_error;
+my $volumes_touched = 0;
 
 my $storage_module = Test::MockModule->new('PVE::Storage');
 $storage_module->mock(
@@ -327,6 +329,7 @@ $lxc_module->mock(
     check_running => sub { return 0 },
     create_disks => sub {
         my ($storecfg, $vmid, $settings, $conf) = @_;
+        $volumes_touched++;
         my $vollist = [];
         for my $ms (sort keys %$settings) {
             my $volid = "local:$vmid/vm-$vmid-disk-$ms.raw";
@@ -338,6 +341,7 @@ $lxc_module->mock(
     destroy_disks => sub { },
     destroy_lxc_container => sub {
         my ($storecfg, $vmid, $conf, $replacement_conf) = @_;
+        $volumes_touched++;
         if (defined($replacement_conf)) {
             PVE::LXC::Config->write_config($vmid, $replacement_conf);
         } else {
@@ -1291,6 +1295,44 @@ subtest 'using the container left behind drops its pending uid' => sub {
     is($err, '', 'config change of the stopped container') or diag($task_log);
     like($task_log, qr/ignoring pending change of read-only option 'meta'/, 'dropped');
     is(pending_uid_of(200), undef, 'pending uid is gone');
+
+    $backup_raw_config =~ s/^arch: amd64$/arch: amd64\nunprivileged: 1/m;
+    $err = restore_ct(200, { force => 1 });
+    like($err, qr/backup belongs to another guest/, 'container stays a guest of its own');
+};
+
+subtest 'retry over the container left behind by a restore of another backup' => sub {
+    failed_restore_in_place();
+
+    $backup_raw_config =
+        backup_config('ctime=1400000000,rtime=1400000000000,uid=anotheranotheranothe');
+    my $err = restore_ct(200, { force => 1 });
+    like(
+        $err,
+        qr/backup belongs to another guest: its uid .anotheranotheranothe. differs/,
+        'refused',
+    );
+    is(pending_uid_of(200), 'backupbackupbackupba', 'pending uid is unchanged');
+};
+
+subtest 'restore from STDIN over the container left behind' => sub {
+    failed_restore_in_place();
+    my $leftover = identity_of(200)->{uid};
+
+    $backup_raw_config =
+        backup_config('ctime=1400000000,rtime=1400000000000,uid=backupbackupbackupba');
+    my $param = { force => 1, ostemplate => '-', rootfs => 'local:4' };
+    my $err = restore_ct(200, $param);
+    like($err, qr/cannot verify the guest identity of a backup from standard input/, 'refused');
+
+    $err = restore_ct(200, { $param->%*, 'allow-identity-mismatch' => 1 });
+    is($err, '', 'restore with override succeeds') or diag($task_log);
+    is(
+        identity_of(200)->{uid},
+        'backupbackupbackupba',
+        'pending uid matches the backup: taken over',
+    );
+    is(pending_uid_of(200), undef, 'pending uid is removed');
 };
 
 subtest 'restore with unique keeps a pending uid, but never takes it over' => sub {
@@ -1408,6 +1450,105 @@ subtest 'every write of a restore keeps the pending uid' => sub {
     $storage_module->unmock('volume_has_feature');
 };
 
+subtest 'restore over a container of another guest needs an override' => sub {
+    my $existing_meta = 'ctime=1500000000,rtime=1500000000000,uid=existingexistingexis';
+    my $existing_raw = existing_config($existing_meta);
+    my $existing_conf = PVE::LXC::Config::parse_pct_config('/lxc/200.conf', $existing_raw);
+    delete $existing_conf->{digest};
+    $backup_raw_config =
+        backup_config('ctime=1400000000,rtime=1400000000000,uid=backupbackupbackupba');
+
+    # network options can change the IPAM of SDN, with the same MAC address as the existing one
+    my $net = 'name=eth0,bridge=vnet0,hwaddr=BC:24:11:00:00:01,ip=dhcp';
+    my @sdn_calls;
+    my $vnets_module = Test::MockModule->new('PVE::Network::SDN::Vnets');
+    $vnets_module->mock(
+        add_next_free_cidr => sub { push @sdn_calls, 'add_next_free_cidr' },
+        del_ips_from_mac => sub { push @sdn_calls, 'del_ips_from_mac' },
+    );
+    $lxc_module->unmock('delete_ifaces_ipams_ips');
+
+    my $refused = sub {
+        my ($name, $param, $expected_err) = @_;
+
+        reset_configs();
+        write_raw_config(200, $existing_raw);
+        $volumes_touched = 0;
+        @sdn_calls = ();
+        my $err = restore_ct(200, { force => 1, $param->%* });
+        like($err, $expected_err, "$name: restore is refused");
+        is($volumes_touched, 0, "$name: volumes are not touched");
+        is_deeply(\@sdn_calls, [], "$name: IPAM is not touched");
+        my $conf = PVE::LXC::Config->load_config(200);
+        delete $conf->{digest};
+        is_deeply($conf, $existing_conf, "$name: config is unchanged");
+    };
+
+    my $mismatch_err =
+        "unable to restore CT 200 - backup belongs to another guest: its uid 'backupbackupbackupba'"
+        . " differs from uid 'existingexistingexis' of the existing CT 200 - use"
+        . " 'allow-identity-mismatch' to overwrite the CT anyway";
+    my $stdin_err =
+        "unable to restore CT 200 - cannot verify the guest identity of a backup from standard"
+        . " input before overwriting CT 200 (uid 'existingexistingexis') - use"
+        . " 'allow-identity-mismatch' to overwrite the CT anyway";
+    my $ignored = "guest identity: ignoring backup uid backupbackupbackupba, CT 200 keeps uid"
+        . " existingexistingexis";
+    my $stdin = { ostemplate => '-', rootfs => 'local:4' };
+    $refused->('different uid', {}, qr/^\Q$mismatch_err\E$/);
+    $refused->('different uid, unique', { unique => 1 }, qr/^\Q$mismatch_err\E$/);
+    $refused->('different uid, network option', { net0 => $net }, qr/^\Q$mismatch_err\E$/);
+    $refused->('from STDIN', $stdin, qr/^\Q$stdin_err\E$/);
+    $refused->('from STDIN, network option', { $stdin->%*, net0 => $net },
+        qr/^\Q$stdin_err\E$/);
+
+    for my $param ({}, $stdin) {
+        my $name = $param->{ostemplate} ? 'from STDIN' : 'from file';
+        reset_configs();
+        write_raw_config(200, $existing_raw);
+        @sdn_calls = ();
+        my $err = restore_ct(
+            200,
+            { force => 1, 'allow-identity-mismatch' => 1, net0 => $net, $param->%* },
+        );
+        is($err, '', "$name: restore with override succeeds") or diag($task_log);
+        is_deeply(\@sdn_calls, ['add_next_free_cidr'], "$name: network option is applied");
+        is(
+            PVE::LXC::Config->load_config(200)->{hostname},
+            'backup',
+            "$name: backup is restored",
+        );
+        is_deeply(
+            identity_of(200),
+            { uid => 'existingexistingexis', rtime => 1500000000000 },
+            "$name: identity of the target is kept",
+        );
+        like(
+            $task_log, qr/^\Q$ignored\E$/m, "$name: override is logged",
+        );
+        like(
+            $task_log,
+            qr/^guest identity: kept uid existingexistingexis$/m,
+            "$name: result is logged",
+        );
+    }
+
+    reset_configs();
+    write_raw_config(200, existing_config('ctime=1500000000'));
+    my $err = restore_ct(200, { force => 1, ostemplate => '-', rootfs => 'local:4' });
+    is($err, '', 'restore from STDIN over a container without identity succeeds');
+    is(identity_of(200)->{uid}, 'backupbackupbackupba', 'uid of the backup is taken over');
+
+    $err = create_ct(201, { 'allow-identity-mismatch' => 1 });
+    like($err, qr/allow-identity-mismatch/, 'override is only allowed for restores');
+
+    my ($class, $method, undef, $fixed) = $PVE::CLI::pct::cmddef->{restore}->@*;
+    is("$class->$method", 'PVE::API2::LXC->create_vm', 'pct restore uses the create API call');
+    ok($fixed->{restore}, 'pct restore sets restore, so it accepts the override');
+
+    $lxc_module->mock(delete_ifaces_ipams_ips => sub { });
+};
+
 remove_tree($WORKDIR);
 
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH container 23/34] migrate: remote: clean up the target on a tunnel version mismatch
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (21 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH container 22/34] restore: refuse overwriting a container with another guest's backup Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH container 24/34] api: remote migration: take over the guest uid from the source Thomas Lamprecht
                   ` (12 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

The target reserves the VMID with a locked config when it starts the
tunnel worker, before the source compares the tunnel versions. On a
mismatch the source failed without telling the target, so that config
stayed behind and blocked the VMID there until an admin removed it.

Ask the target to clean up before failing. If that fails too, log it
and still report the version mismatch as the error.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/LXC/Migrate.pm      | 12 +++++++++--
 src/test/lifecycle_tests.pl | 43 +++++++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+), 2 deletions(-)

diff --git a/src/PVE/LXC/Migrate.pm b/src/PVE/LXC/Migrate.pm
index d243d90..1882e57 100644
--- a/src/PVE/LXC/Migrate.pm
+++ b/src/PVE/LXC/Migrate.pm
@@ -147,11 +147,19 @@ sub prepare {
         $self->log('info', "local WS tunnel version: $WS_TUNNEL_VERSION");
         $self->log('info', "remote WS tunnel version: $tunnel->{version}");
         $self->log('info', "minimum required WS tunnel version: $min_version");
-        die "Remote tunnel endpoint not compatible, upgrade required\n"
+        my $version_err;
+        $version_err = "Remote tunnel endpoint not compatible, upgrade required\n"
             if $WS_TUNNEL_VERSION < $min_version;
-        die "Remote tunnel endpoint too old, upgrade required\n"
+        $version_err = "Remote tunnel endpoint too old, upgrade required\n"
             if $WS_TUNNEL_VERSION > $tunnel->{version};
 
+        if ($version_err) {
+            # the target already reserved the VMID with a locked config
+            eval { PVE::Tunnel::finish_tunnel($tunnel, 1); };
+            $self->log('warn', "cleanup of the target failed - $@") if $@;
+            die $version_err;
+        }
+
         $self->log('info', "websocket tunnel started\n");
         $self->{tunnel} = $tunnel;
     } else {
diff --git a/src/test/lifecycle_tests.pl b/src/test/lifecycle_tests.pl
index d93f24e..e3a86a8 100755
--- a/src/test/lifecycle_tests.pl
+++ b/src/test/lifecycle_tests.pl
@@ -1549,6 +1549,49 @@ subtest 'restore over a container of another guest needs an override' => sub {
     $lxc_module->mock(delete_ifaces_ipams_ips => sub { });
 };
 
+subtest 'remote migration cleans up a target with an incompatible tunnel version' => sub {
+    reset_configs();
+    my $raw = existing_config('ctime=1500000000,rtime=1500000000000,uid=existingexistingexis');
+    write_raw_config(200, $raw);
+
+    my $log = '';
+    my $migrate_module = Test::MockModule->new('PVE::AbstractMigrate');
+    $migrate_module->mock(log => sub { $log .= "$_[1]: $_[2]\n" });
+
+    my $remote_version = { version => $PVE::LXC::Migrate::WS_TUNNEL_VERSION - 1, age => 0 };
+    my ($commands, $cleanup) = (0);
+    my $tunnel_module = Test::MockModule->new('PVE::Tunnel');
+    $tunnel_module->mock(
+        fork_websocket_tunnel => sub { return $remote_version },
+        write_tunnel => sub { $commands++ },
+        finish_tunnel => sub { (undef, $cleanup) = @_ },
+    );
+
+    my $migrate = sub {
+        ($log, $commands, $cleanup) = ('', 0);
+        return run_task(sub {
+            PVE::LXC::Migrate->migrate(
+                'remote-node',
+                '192.0.2.1',
+                200,
+                { remote => { vmid => 300, conn => { host => '192.0.2.1', port => 8006 } } },
+            );
+        });
+    };
+
+    like($migrate->(), qr/migration aborted/, 'migration to an older target fails');
+    like($log, qr/^err: .*Remote tunnel endpoint too old/m, 'target is reported as too old');
+    is($cleanup, 1, 'older target is asked to clean up');
+    is($commands, 0, 'nothing else is sent to the target');
+    is(read_raw_config(200), $raw, 'config of the source is unchanged');
+
+    $remote_version = { version => $PVE::LXC::Migrate::WS_TUNNEL_VERSION + 1, age => 0 };
+    like($migrate->(), qr/migration aborted/, 'migration to an incompatible target fails');
+    like($log, qr/^err: .*Remote tunnel endpoint not compatible/m, 'target is reported');
+    is($cleanup, 1, 'incompatible target is asked to clean up');
+    is(read_raw_config(200), $raw, 'config of the source is unchanged');
+};
+
 remove_tree($WORKDIR);
 
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH container 24/34] api: remote migration: take over the guest uid from the source
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (22 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH container 23/34] migrate: remote: clean up the target on a tunnel version mismatch Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH container 25/34] api: status: return the guest uid Thomas Lamprecht
                   ` (11 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

A container migrated to another cluster should keep its uid, unless
another guest there already uses it. Take over the uid of the source
after the incoming config is written, while holding the config lock.
Otherwise, or if the source has no uid, the container keeps the uid
assigned when its VMID was reserved. The registration time is the time
of the migration.

Unlike for a restore, an error while taking over the uid fails the
config command and aborts the migration. The source is still intact
then and can clean up the target, while finishing the migration, and
possibly deleting the source, would lose the uid because of a transient
failure. Raise the timeout for the reply to the config command to 60
seconds, to cover the wait for the cluster-wide lock.

Return the outcome, so that the task logs of both sides report it. An
outcome that the source does not know, as a newer target could report,
only produces a warning, because the target accepted the config at that
point. The existing lock check keeps a successful config command from
being repeated, so the registration time cannot be reset. An error
while taking over the uid happens after the lock transition and leads
to abort and cleanup, not to a retry of the command.

Bump the tunnel version, so that older targets are refused before
volumes are transferred, and not only when their strict parser rejects
'meta'. Keep accepting the previous version from older sources.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/API2/LXC.pm         |  18 ++-
 src/PVE/LXC/Migrate.pm      |  19 ++-
 src/test/lifecycle_tests.pl | 255 ++++++++++++++++++++++++++++++++++++
 3 files changed, 287 insertions(+), 5 deletions(-)

diff --git a/src/PVE/API2/LXC.pm b/src/PVE/API2/LXC.pm
index 06049d7..60b8802 100644
--- a/src/PVE/API2/LXC.pm
+++ b/src/PVE/API2/LXC.pm
@@ -3305,7 +3305,7 @@ __PACKAGE__->register_method({
         my $socket_addr = "/run/pve/ct-$vmid.mtunnel";
 
         my $lock = 'create';
-        eval { PVE::LXC::Config->create_and_lock_config($vmid, 0, $lock); };
+        my $reservation = eval { PVE::LXC::Config->create_and_lock_config($vmid, 0, $lock) };
 
         raise_param_exc({ vmid => "unable to create empty CT config - $@" })
             if $@;
@@ -3372,7 +3372,7 @@ __PACKAGE__->register_method({
                     # bump/bump for opt-in changes
                     return {
                         api => $PVE::LXC::Migrate::WS_TUNNEL_VERSION,
-                        age => 0,
+                        age => 1,
                     };
                 },
                 'config' => sub {
@@ -3410,6 +3410,7 @@ __PACKAGE__->register_method({
 
                     my $unprivileged = delete $new_conf->{unprivileged};
                     my $arch = delete $new_conf->{arch};
+                    my $source_identity = PVE::LXC::Config->get_identity($new_conf);
                     # read-only for the update below, the source's values are kept as they are
                     my $meta = delete $new_conf->{meta};
 
@@ -3465,7 +3466,18 @@ __PACKAGE__->register_method({
 
                     $state->{lock} = 'migrate';
 
-                    return;
+                    # Failing the command keeps the guest on the source, instead of letting the
+                    # migration finish with a new identity. The source cleans up the target then.
+                    my $uid = $source_identity && $source_identity->{uid};
+                    my $identity = eval {
+                        PVE::GuestIdentity::adopt(
+                            'PVE::LXC::Config', $state->{vmid}, $uid, $reservation,
+                        );
+                    };
+                    die "unable to adopt the uid of the source guest - $@" if $@;
+                    print PVE::GuestIdentity::adopt_result_message($identity, 'source') . "\n";
+
+                    return { identity => $identity };
                 },
                 'bwlimit' => sub {
                     my ($params) = @_;
diff --git a/src/PVE/LXC/Migrate.pm b/src/PVE/LXC/Migrate.pm
index 1882e57..21aedf4 100644
--- a/src/PVE/LXC/Migrate.pm
+++ b/src/PVE/LXC/Migrate.pm
@@ -7,6 +7,7 @@ use File::Basename;
 use File::Copy; # fixme: remove
 
 use PVE::Cluster;
+use PVE::GuestIdentity;
 use PVE::INotify;
 use PVE::JSONSchema;
 use PVE::Replication;
@@ -25,7 +26,8 @@ use PVE::AbstractMigrate;
 use base qw(PVE::AbstractMigrate);
 
 # compared against remote end's minimum version
-our $WS_TUNNEL_VERSION = 2;
+# 3: the target accepts a guest identity in the config and takes over its uid
+our $WS_TUNNEL_VERSION = 3;
 
 sub lock_vm {
     my ($self, $vmid, $code, @param) = @_;
@@ -471,7 +473,9 @@ sub phase1 {
             'firewall-config' => $fw_conf_str,
         };
 
-        PVE::Tunnel::write_tunnel($self->{tunnel}, 10, 'config', $params);
+        # the target takes the cluster-wide guest identity lock in addition to its config writes
+        my $res = PVE::Tunnel::write_tunnel($self->{tunnel}, 60, 'config', $params);
+        $self->log_target_identity($res && $res->{identity});
     } else {
         # transfer replication state before moving config
         $self->transfer_replication_state() if $rep_volumes;
@@ -483,6 +487,17 @@ sub phase1 {
     $self->{conf_migrated} = 1;
 }
 
+# Logs the outcome of taking over the guest identity of the source on the target of a remote
+# migration, as reported by the target.
+sub log_target_identity {
+    my ($self, $identity) = @_;
+
+    return if !$identity;
+
+    my ($level, $msg) = PVE::GuestIdentity::remote_adopt_result_log($identity);
+    $self->log($level, "target CT $self->{opts}->{remote}->{vmid}: $msg");
+}
+
 sub phase1_cleanup {
     my ($self, $vmid, $err) = @_;
 
diff --git a/src/test/lifecycle_tests.pl b/src/test/lifecycle_tests.pl
index e3a86a8..e2fdb9f 100755
--- a/src/test/lifecycle_tests.pl
+++ b/src/test/lifecycle_tests.pl
@@ -36,6 +36,7 @@ use PVE::CLI::pct;
 use PVE::LXC;
 use PVE::LXC::Config;
 use PVE::LXC::Create;
+use PVE::LXC::Migrate;
 
 my $WORKDIR = 'lifecycle-working';
 my $NODENAME = PVE::INotify::nodename();
@@ -101,6 +102,11 @@ my $storage_cfg = {
             shared => 1,
             content => { rootdir => 1, images => 1 },
         },
+        iso => {
+            type => 'dir',
+            path => '/mnt/iso',
+            content => { iso => 1 },
+        },
     },
 };
 
@@ -1592,6 +1598,255 @@ subtest 'remote migration cleans up a target with an incompatible tunnel version
     is(read_raw_config(200), $raw, 'config of the source is unchanged');
 };
 
+subtest 'remote migration takes over the guest identity of the source' => sub {
+    my $source_meta = 'ctime=1600000000,rtime=1600000000000,uid=sourcesourcesourceso';
+    my $incoming = $INCOMING_CONFIG =~ s/^meta: .*$/meta: $source_meta/mr;
+    $now_ms = 1_700_000_000_000;
+
+    my $migrate = sub {
+        my ($name, $setup, $conf, $expected_result, $expected_uid) = @_;
+
+        reset_configs();
+        $setup->();
+        my ($err, $replies) = run_mtunnel(
+            300, { cmd => 'config', conf => $conf }, { cmd => 'quit', cleanup => 0 },
+        );
+        is($err, '', "$name: tunnel exits normally") or diag(explain($replies), $task_log);
+        ok($replies->[0]->{success}, "$name: config command succeeds");
+
+        my $identity = $replies->[0]->{identity};
+        is($identity->{result}, $expected_result, "$name: result is returned");
+        my $published = identity_of(300);
+        is($identity->{uid}, $published->{uid}, "$name: returned uid is the published one");
+        if (defined($expected_uid)) {
+            is($published->{uid}, $expected_uid, "$name: uid");
+        } else {
+            isnt(
+                $published->{uid},
+                'sourcesourcesourceso',
+                "$name: uid is not the one of the source",
+            );
+        }
+        is($published->{rtime}, $now_ms, "$name: rtime is the time of the migration");
+        is(meta_of(300)->{ctime}, 1600000000, "$name: ctime of the source is kept");
+        like(
+            $task_log,
+            qr/^guest identity: .*$identity->{uid}/m,
+            "$name: result is logged on the target",
+        );
+
+        return $identity;
+    };
+
+    $migrate->('free uid', sub { }, $incoming, 'adopted', 'sourcesourcesourceso');
+    $migrate->(
+        'uid used by another container',
+        sub { write_raw_config(150, existing_config('uid=sourcesourcesourceso')) },
+        $incoming,
+        'in-use',
+    );
+    $migrate->(
+        'uid used by a VM',
+        sub { write_raw_vm_config(151, "memory: 512\nmeta: uid=sourcesourcesourceso\n") },
+        $incoming,
+        'in-use',
+    );
+    $migrate->('source without identity', sub { }, $INCOMING_CONFIG, 'skipped');
+
+    my $real_adopt = \&PVE::GuestIdentity::adopt;
+    my ($lock, $locked);
+    $identity_module->mock(
+        adopt => sub {
+            my ($class, $vmid) = @_;
+            $lock = PVE::LXC::Config->load_config($vmid)->{lock};
+            open(my $fh, '>>', "$WORKDIR/lock/pve-config-$vmid.lock")
+                or die "open failed - $!\n";
+            $locked = !flock($fh, LOCK_EX | LOCK_NB);
+            close($fh);
+            return $real_adopt->(@_);
+        },
+    );
+    $migrate->('order of the writes', sub { }, $incoming, 'adopted', 'sourcesourcesourceso');
+    $identity_module->unmock('adopt');
+    is($lock, 'migrate', 'identity is taken over after the final config write');
+    ok($locked, 'config lock is held while taking over the identity');
+
+    reset_configs();
+    $domain_lock_error = "cfs-lock 'domain-guest-identity' error: got lock request timeout\n";
+    my ($err, $replies) = run_mtunnel(
+        300, { cmd => 'config', conf => $incoming }, { cmd => 'quit', cleanup => 1 },
+    );
+    $domain_lock_error = undef;
+    is($err, '', 'identity lock failure: tunnel exits normally') or diag($task_log);
+    ok(!$replies->[0]->{success}, 'identity lock failure: config command fails');
+    is(
+        $replies->[0]->{msg},
+        "failed to handle 'config' command - unable to adopt the uid of the source guest -"
+            . " cfs-lock 'domain-guest-identity' error: got lock request timeout\n",
+        'identity lock failure: error is returned',
+    );
+    ok($replies->[1]->{success}, 'identity lock failure: cleanup succeeds');
+    ok(!defined(read_raw_config(300)), 'identity lock failure: target config is removed');
+
+    reset_configs();
+    my $broken = $incoming =~ s/^rootfs: local:/rootfs: iso:/mr;
+    ($err, $replies) = run_mtunnel(
+        300,
+        { cmd => 'config', conf => $broken },
+        { cmd => 'config', conf => $incoming },
+        { cmd => 'config', conf => $incoming },
+        { cmd => 'quit', cleanup => 0 },
+    );
+    is($err, '', 'repeated config: tunnel exits normally');
+    ok(!$replies->[0]->{success}, 'failing config command fails');
+    is($replies->[1]->{identity}->{result}, 'adopted', 'retry takes over the uid');
+    ok(!$replies->[2]->{success}, 'config command after success fails');
+    is_deeply(
+        identity_of(300),
+        { uid => 'sourcesourcesourceso', rtime => $now_ms },
+        'identity is published once',
+    );
+};
+
+subtest 'remote migration logs the guest identity on the source' => sub {
+    my $source_raw = <<~'EOF';
+        arch: amd64
+        hostname: source
+        memory: 512
+        meta: ctime=1600000000,rtime=1600000000000,uid=sourcesourcesourceso
+        ostype: debian
+        unprivileged: 1
+        EOF
+    reset_configs();
+    write_raw_config(987, $source_raw);
+
+    my $log = '';
+    my $migrate_module = Test::MockModule->new('PVE::AbstractMigrate');
+    $migrate_module->mock(log => sub { $log .= "$_[1]: $_[2]\n" });
+
+    my ($sent_conf, $config_timeout, $reply);
+    my $tunnel_module = Test::MockModule->new('PVE::Tunnel');
+    $tunnel_module->mock(
+        write_tunnel => sub {
+            my ($tunnel, $timeout, $command, $params) = @_;
+            die "unexpected command '$command'\n" if $command ne 'config';
+            ($sent_conf, $config_timeout) = ($params->{conf}, $timeout);
+            return $reply;
+        },
+    );
+
+    my $phase1 = sub {
+        my $self = bless {
+            opts => { remote => { vmid => 300 } },
+            vmid => 987,
+            node => 'remote-node',
+            nodeip => '192.0.2.1',
+            storecfg => $storage_cfg,
+            vmconf => PVE::LXC::Config->load_config(987),
+            tunnel => {},
+            },
+            'PVE::LXC::Migrate';
+        $log = '';
+        return run_task(sub { $self->phase1(987) });
+    };
+
+    $reply = {
+        success => 1,
+        identity => {
+            result => 'adopted',
+            uid => 'sourcesourcesourceso',
+            requested => 'sourcesourcesourceso',
+        },
+    };
+    is($phase1->(), '', 'phase 1 succeeds') or diag($log, $task_log);
+    like($sent_conf, qr/^meta: .*uid=sourcesourcesourceso/m, 'identity is sent to the target');
+    is($config_timeout, 60, 'source waits for the identity lock of the target');
+    my $adopted =
+        'target CT 300: guest identity: adopted uid sourcesourcesourceso from the source guest';
+    like($log, qr/^info: \Q$adopted\E$/m, 'result of the target is logged');
+    is(identity_of(987)->{uid}, 'sourcesourcesourceso', 'source keeps its uid');
+
+    PVE::LXC::Config->remove_lock(987, 'migrate');
+    $reply = { success => 1 };
+    is($phase1->(), '', 'phase 1 with a target without guest identity succeeds');
+    unlike($log, qr/guest identity/, 'nothing is logged about the identity');
+    PVE::LXC::Config->remove_lock(987, 'migrate');
+
+    # a target with a newer version has already taken over the config at this point
+    $reply =
+        { success => 1, identity => { result => 'future', uid => 'sourcesourcesourceso' } };
+    is($phase1->(), '', 'phase 1 with an outcome unknown here succeeds');
+    like(
+        $log,
+        qr/^warn: target CT 300: unknown result of guest identity adoption 'future'$/m,
+        'unknown outcome is a warning',
+    );
+    PVE::LXC::Config->remove_lock(987, 'migrate');
+};
+
+subtest 'remote migration keeps the source if the target fails to take over the identity' => sub {
+    reset_configs();
+    write_raw_config(987, <<~'EOF');
+        arch: amd64
+        hostname: source
+        memory: 512
+        meta: ctime=1600000000,rtime=1600000000000,uid=sourcesourcesourceso
+        ostype: debian
+        unprivileged: 1
+        EOF
+
+    my $log = '';
+    my $migrate_module = Test::MockModule->new('PVE::AbstractMigrate');
+    $migrate_module->mock(log => sub { $log .= "$_[1]: $_[2]\n" });
+
+    my $cleanup;
+    my $tunnel_module = Test::MockModule->new('PVE::Tunnel');
+    $tunnel_module->mock(
+        fork_websocket_tunnel => sub { return { version => 3, age => 1 } },
+        write_tunnel => sub {
+            my ($tunnel, $timeout, $command) = @_;
+            die "error - tunnel command '$command' failed - failed to handle 'config' command"
+                . " - unable to adopt the uid of the source guest - cfs-lock"
+                . " 'domain-guest-identity' error: got lock request timeout\n";
+        },
+        finish_tunnel => sub { (undef, $cleanup) = @_ },
+    );
+
+    my ($running, $started, $destroyed) = (1, 0, 0);
+    my $destroy_ct = \&PVE::LXC::destroy_lxc_container;
+    $lxc_module->mock(
+        check_running => sub { return $running },
+        vm_stop => sub { $running = 0 },
+        vm_start => sub { $started = 1 },
+        destroy_lxc_container => sub { $destroyed = 1 },
+    );
+
+    my $err = run_task(sub {
+        PVE::LXC::Migrate->migrate(
+            'remote-node',
+            '192.0.2.1',
+            987,
+            {
+                remote => { vmid => 300, conn => { host => '192.0.2.1', port => 8006 } },
+                restart => 1,
+                delete => 1,
+            },
+        );
+    });
+
+    $lxc_module->mock(check_running => sub { return 0 }, destroy_lxc_container => $destroy_ct);
+    $lxc_module->unmock('vm_stop', 'vm_start');
+
+    like($err, qr/migration aborted/, 'migration fails');
+    like($log, qr/^err: .*lock request timeout/m, 'error of the target is logged');
+    is($cleanup, 1, 'target gets cleaned up');
+    ok(!$destroyed, 'source is not destroyed');
+    ok($started, 'source is started again');
+    my $conf = PVE::LXC::Config->load_config(987);
+    ok(!defined($conf->{lock}), 'migrate lock of the source is removed');
+    is(identity_of(987)->{uid}, 'sourcesourcesourceso', 'source keeps its uid');
+};
+
 remove_tree($WORKDIR);
 
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH container 25/34] api: status: return the guest uid
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (23 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH container 24/34] api: remote migration: take over the guest uid from the source Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH manager 26/34] api: cluster resources: add guest uid and registration time Thomas Lamprecht
                   ` (10 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Return the uid with the container's current status so tools can follow
the guest across restores and migrations without parsing the 'meta'
property of its config.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 src/PVE/API2/LXC/Status.pm  | 10 ++++++++++
 src/test/lifecycle_tests.pl | 26 ++++++++++++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/src/PVE/API2/LXC/Status.pm b/src/PVE/API2/LXC/Status.pm
index c95fc3c..3972424 100644
--- a/src/PVE/API2/LXC/Status.pm
+++ b/src/PVE/API2/LXC/Status.pm
@@ -98,6 +98,12 @@ __PACKAGE__->register_method({
                 description => "HA manager service status.",
                 type => 'object',
             },
+            uid => {
+                description => "Random identifier of the guest, see the 'uid' member of the"
+                    . " 'meta' config property.",
+                type => 'string',
+                optional => 1,
+            },
         },
     },
     code => sub {
@@ -112,6 +118,10 @@ __PACKAGE__->register_method({
 
         $status->{ha} = PVE::HA::Config::get_service_status("ct:$vmid");
 
+        if (my $identity = PVE::LXC::Config->get_identity($conf)) {
+            $status->{uid} = $identity->{uid};
+        }
+
         return $status;
     },
 });
diff --git a/src/test/lifecycle_tests.pl b/src/test/lifecycle_tests.pl
index e2fdb9f..42497c5 100755
--- a/src/test/lifecycle_tests.pl
+++ b/src/test/lifecycle_tests.pl
@@ -32,6 +32,7 @@ use PVE::Tools qw(file_get_contents file_set_contents);
 
 use PVE::API2::LXC;
 use PVE::API2::LXC::Config;
+use PVE::API2::LXC::Status;
 use PVE::CLI::pct;
 use PVE::LXC;
 use PVE::LXC::Config;
@@ -1847,6 +1848,31 @@ subtest 'remote migration keeps the source if the target fails to take over the
     is(identity_of(987)->{uid}, 'sourcesourcesourceso', 'source keeps its uid');
 };
 
+subtest 'current status reports the uid' => sub {
+    reset_configs();
+    write_raw_config(
+        200,
+        existing_config('ctime=1500000000,rtime=1500000000000,uid=existingexistingexis'),
+    );
+    write_raw_config(201, existing_config('ctime=1500000000'));
+
+    $lxc_module->mock(
+        vmstatus => sub {
+            my ($vmid) = @_;
+            return { $vmid => { vmid => int($vmid), status => 'stopped' } };
+        },
+    );
+    my $ha_config_module = Test::MockModule->new('PVE::HA::Config');
+    $ha_config_module->mock(get_service_status => sub { return { managed => 0 } });
+
+    my $status = PVE::API2::LXC::Status->vm_status({ node => $NODENAME, vmid => 200 });
+    is($status->{uid}, 'existingexistingexis', 'uid is reported');
+    $status = PVE::API2::LXC::Status->vm_status({ node => $NODENAME, vmid => 201 });
+    ok(!exists($status->{uid}), 'no uid is reported for a container without identity');
+
+    $lxc_module->unmock('vmstatus');
+};
+
 remove_tree($WORKDIR);
 
 done_testing();
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH manager 26/34] api: cluster resources: add guest uid and registration time
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (24 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH container 25/34] api: status: return the guest uid Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-17 15:30   ` Dominik Csapak
  2026-11-16  0:46 ` [PATCH manager 27/34] api: cluster status: add cluster ID Thomas Lamprecht
                   ` (9 subsequent siblings)
  35 siblings, 1 reply; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Tools that follow guests across restores and migrations, for example
backup products, need the guest identity. Report the 'uid' and 'rtime'
of guests that have them on their rows, so such tools get both for all
guests with one call instead of reading each guest config. Like lock
and tags, they are only reported to users with VM.Audit on the guest.

Both come from the 'meta' line, which the existing request for lock and
tags now also returns, so there is no extra round trip to pmxcfs. The
line is parsed per guest, and a guest with a missing or malformed
identity only lacks the fields. Neither the raw line nor its other
members are exposed.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 PVE/API2/Cluster.pm           |  25 +++-
 test/ClusterResources_test.pl | 249 ++++++++++++++++++++++++++++++++++
 test/Makefile                 |   6 +-
 3 files changed, 278 insertions(+), 2 deletions(-)
 create mode 100755 test/ClusterResources_test.pl

diff --git a/PVE/API2/Cluster.pm b/PVE/API2/Cluster.pm
index 4e5efbfd..346ecdb2 100644
--- a/PVE/API2/Cluster.pm
+++ b/PVE/API2/Cluster.pm
@@ -11,6 +11,7 @@ use PVE::DataCenterConfig;
 use PVE::Exception qw(raise_param_exc);
 use PVE::Firewall;
 use PVE::GuestHelpers;
+use PVE::GuestIdentity;
 use PVE::HA::Config;
 use PVE::HA::Env::PVE2;
 use PVE::INotify;
@@ -474,6 +475,22 @@ __PACKAGE__->register_method({
                     optional => 1,
                     default => 0,
                 },
+                uid => {
+                    description =>
+                        "Guest lineage identifier, normally kept across restores and migrations"
+                        . " from other clusters (for types 'qemu' and 'lxc').",
+                    type => 'string',
+                    optional => 1,
+                },
+                rtime => {
+                    description =>
+                        "Time the guest was registered in this cluster, for example by"
+                        . " creation, restore, or migration from another cluster, in milliseconds"
+                        . " since the UNIX epoch (for types 'qemu' and 'lxc').",
+                    type => 'integer',
+                    minimum => 0,
+                    optional => 1,
+                },
                 network => {
                     description => "The name of a Network entity (for type 'network').",
                     type => "string",
@@ -552,7 +569,7 @@ __PACKAGE__->register_method({
         # we try to generate 'numbers' by using "$X + 0"
         if (!$param->{type} || $param->{type} eq 'vm') {
             my $prop_list = [qw(lock tags)];
-            my $props = PVE::Cluster::get_guest_config_properties($prop_list);
+            my $props = PVE::Cluster::get_guest_config_properties([@$prop_list, 'meta']);
 
             for my $vmid (sort keys %$idlist) {
 
@@ -593,6 +610,12 @@ __PACKAGE__->register_method({
                     }
                 }
 
+                my $identity = PVE::GuestIdentity::parse_identity($props->{$vmid}->{meta});
+                if ($identity) {
+                    $entry->{uid} = $identity->{uid};
+                    $entry->{rtime} = int($identity->{rtime}) if defined($identity->{rtime});
+                }
+
                 if (
                     defined($entry->{pool})
                     && !$rpcenv->check($authuser, "/pool/$entry->{pool}", ['Pool.Audit'], 1)
diff --git a/test/ClusterResources_test.pl b/test/ClusterResources_test.pl
new file mode 100755
index 00000000..4b981dc7
--- /dev/null
+++ b/test/ClusterResources_test.pl
@@ -0,0 +1,249 @@
+#!/usr/bin/perl
+
+use v5.36;
+
+use lib ('.', '..');
+
+use JSON;
+use Test::MockModule;
+use Test::More;
+
+use PVE::JSONSchema;
+
+use PVE::API2::Cluster;
+
+my $uid_100 = 'k3d7q2mxa5vb4n6pw2fz';
+my $uid_101 = 'r6t2w4y7z3c5e2g4h7jm';
+my $uid_104 = 'q2w3e4r5t6y7u2i3o4pa';
+
+# top-level config values per guest as decoded from the pmxcfs reply, plus whether the user has
+# VM.Audit on it; node2 is offline
+my $guests;
+my $default_guests = {
+    100 => {
+        type => 'qemu',
+        node => 'node1',
+        audit => 1,
+        lock => 'backup',
+        tags => 'prod;web',
+        meta => "creation-qemu=9.2.0,ctime=1700000000,rtime=1731600000123,uid=$uid_100",
+    },
+    101 => { type => 'lxc', node => 'node2', audit => 1, meta => "uid=$uid_101" },
+    102 => {
+        type => 'qemu',
+        node => 'node1',
+        audit => 1,
+        meta => 'rtime=1731600000123,uid=NOT-A-UID',
+    },
+    103 => { type => 'qemu', node => 'node1', audit => 1, lock => 'migrate' },
+    104 => { type => 'qemu', node => 'node2', audit => 1, meta => "rtime=12x,uid=$uid_104" },
+    105 => {
+        type => 'lxc',
+        node => 'node1',
+        audit => 0,
+        meta => "rtime=1731600000123,uid=$uid_100",
+    },
+};
+
+my $default_identities = {
+    100 => { uid => $uid_100, rtime => 1731600000123 },
+    101 => { uid => $uid_101 },
+    102 => {},
+    103 => {},
+    104 => { uid => $uid_104 },
+};
+
+my $property_requests;
+my $ipc_failures = 0;
+
+my $cluster_mock = Test::MockModule->new('PVE::Cluster');
+$cluster_mock->redefine(
+    get_nodelist => sub { return ['node1', 'node2'] },
+    get_members => sub {
+        return { node1 => { id => 1, online => 1 }, node2 => { id => 2, online => 0 } };
+    },
+    rrd_dump => sub { return {} },
+    get_node_kv => sub { return {} },
+    get_vmlist => sub {
+        my $ids = {};
+        for my $vmid (keys %$guests) {
+            my $guest = $guests->{$vmid};
+            $ids->{$vmid} = { node => $guest->{node}, type => $guest->{type}, version => 1 };
+        }
+        return { ids => $ids };
+    },
+    get_guest_config_properties => sub($properties, $vmid = undef) {
+        die "only the request for all guests is expected\n" if defined($vmid);
+        push @$property_requests, [@$properties];
+        die "ipcc_send_rec[11] failed: Connection refused\n" if $ipc_failures-- > 0;
+
+        my $res = {};
+        for my $id (keys %$guests) {
+            for my $prop (@$properties) {
+                my $value = $guests->{$id}->{$prop} // next;
+                $res->{$id}->{$prop} = $value;
+            }
+        }
+        return $res;
+    },
+);
+
+my $ha_config_mock = Test::MockModule->new('PVE::HA::Config');
+$ha_config_mock->redefine(
+    read_manager_status => sub { return {} },
+    read_resources_config => sub { return { ids => {} } },
+);
+
+my $storage_mock = Test::MockModule->new('PVE::Storage');
+$storage_mock->redefine(
+    config => sub { return { ids => {} } },
+    storage_ids => sub { return () },
+);
+
+my $rpcenv = bless { user_cfg => { pools => { p1 => {} }, vms => { 100 => 'p1' } } },
+    'PVE::RPCEnvironment::Test';
+sub PVE::RPCEnvironment::Test::get_user { return 'auditor@pve'; }
+
+sub PVE::RPCEnvironment::Test::check($self, $user, $path, $privs, $noerr) {
+    return 1 if $path eq '/pool/p1' && grep { $_ eq 'Pool.Audit' } @$privs;
+    my ($vmid) = $path =~ m!^/vms/(\d+)$! or return 0;
+    return $guests->{$vmid}->{audit} && grep { $_ eq 'VM.Audit' } @$privs;
+}
+my $rpc_mock = Test::MockModule->new('PVE::RPCEnvironment');
+$rpc_mock->redefine(get => sub { return $rpcenv });
+
+my $method = PVE::API2::Cluster->map_method_by_name('resources');
+
+# returns the rows and their JSON encoding, which is what API clients see
+sub get_rows($param) {
+    $property_requests = [];
+
+    my $res = PVE::API2::Cluster->handle($method, $param);
+    my $json = JSON->new->utf8->canonical->encode($res);
+
+    PVE::JSONSchema::validate($res, $method->{returns}, "return schema violated\n");
+
+    return ($res, $json);
+}
+
+sub guest_rows($res) {
+    return { map { $_->{vmid} => $_ } grep { $_->{type} =~ m/^(?:qemu|lxc)$/ } @$res };
+}
+
+sub identity_view($res) {
+    my $rows = guest_rows($res);
+
+    my $view = {};
+    for my $vmid (keys %$rows) {
+        my $row = $rows->{$vmid};
+        $view->{$vmid} = { map { $_ => $row->{$_} } grep { exists($row->{$_}) } qw(uid rtime) };
+    }
+    return $view;
+}
+
+subtest 'identity of guests with valid, partial, invalid and missing meta' => sub {
+    $guests = {%$default_guests};
+
+    my ($res, $json) = get_rows({ type => 'vm' });
+    my $rows = guest_rows($res);
+
+    is_deeply(
+        $property_requests,
+        [[qw(lock tags meta)]],
+        'meta is fetched together with lock and tags in a single request',
+    );
+
+    is_deeply(
+        identity_view($res),
+        $default_identities,
+        'uid and rtime only where valid, guests without VM.Audit are not listed',
+    );
+
+    like($json, qr/"rtime":1731600000123[,}]/, 'rtime is encoded as JSON number');
+    like($json, qr/"uid":"$uid_100"/, 'uid is encoded as JSON string');
+
+    is($rows->{100}->{lock}, 'backup', 'lock is still reported');
+    is($rows->{100}->{tags}, 'prod;web', 'tags are still reported');
+    is($rows->{103}->{lock}, 'migrate', 'lock of a guest without meta is still reported');
+
+    for my $key (qw(meta ctime creation-qemu)) {
+        ok(!grep({ exists($_->{$key}) } @$res), "no '$key' in any row");
+    }
+};
+
+subtest 'listing of all resource types' => sub {
+    $guests = {%$default_guests};
+
+    my ($res) = get_rows({});
+
+    is(scalar(@$property_requests), 1, 'guest config properties are requested once');
+    is_deeply(identity_view($res), $default_identities, 'same identities as for type vm');
+    is(guest_rows($res)->{101}->{status}, 'unknown', 'guest on offline node is listed');
+
+    my @others = grep { $_->{type} !~ m/^(?:qemu|lxc)$/ } @$res;
+    is_deeply(
+        [sort map { $_->{id} } @others],
+        ['/pool/p1', 'node/node1', 'node/node2'],
+        'pool and node rows are listed',
+    );
+    ok(!grep({ exists($_->{uid}) || exists($_->{rtime}) } @others),
+        'no identity on other rows');
+};
+
+subtest 'control character or replacement character in meta' => sub {
+    # pmxcfs escapes control characters and replaces bytes that are not valid UTF-8 with U+FFFD
+    $guests = {
+        %$default_guests,
+        106 => {
+            type => 'qemu',
+            node => 'node1',
+            audit => 1,
+            lock => 'backup',
+            meta => "rtime=1731600000123,uid=k3d7q2mx\ta5vb4n6p",
+        },
+        107 => {
+            type => 'qemu',
+            node => 'node1',
+            audit => 1,
+            meta => "rtime=1731600000123,uid=k3d7q2mx\x{FFFD}5vb4n6p",
+        },
+        108 => {
+            type => 'lxc',
+            node => 'node1',
+            audit => 1,
+            meta => "ctime=17000\x{1}00000,rtime=1731600000456,uid=z2y3x4w5v6u7t2s3r4qn",
+        },
+    };
+
+    my ($res) = eval { get_rows({ type => 'vm' }) };
+    is($@, '', 'listing does not fail');
+
+    is_deeply(
+        identity_view($res),
+        {
+            %$default_identities,
+            106 => {},
+            107 => {},
+            108 => { uid => 'z2y3x4w5v6u7t2s3r4qn', rtime => 1731600000456 },
+        },
+        'only the guests with a malformed uid lack the identity',
+    );
+    is(guest_rows($res)->{106}->{lock}, 'backup', 'lock of such a guest is still reported');
+};
+
+subtest 'transient IPC failure fails the listing' => sub {
+    $guests = {%$default_guests};
+    $ipc_failures = 1;
+
+    eval { get_rows({ type => 'vm' }) };
+    like(
+        $@,
+        qr/Connection refused/,
+        'error is raised instead of listing guests without identity',
+    );
+    is(scalar(@$property_requests), 1, 'request is not repeated');
+
+    $ipc_failures = 0;
+};
+
+done_testing();
diff --git a/test/Makefile b/test/Makefile
index 2dfd20a4..7eaa46a2 100644
--- a/test/Makefile
+++ b/test/Makefile
@@ -5,7 +5,7 @@ all:
 export PERLLIB=..
 
 .PHONY: check
-check: test-replication test-balloon test-vzdump test-osd test-ceph-health test-ceph-services test-ceph-auth test-ceph-key-migration test-ceph-lockbox-migration test-custom-cpu-models test-pvesh
+check: test-replication test-balloon test-vzdump test-osd test-ceph-health test-ceph-services test-ceph-auth test-ceph-key-migration test-ceph-lockbox-migration test-custom-cpu-models test-pvesh test-cluster-resources
 
 .PHONY: test-balloon
 test-balloon:
@@ -61,6 +61,10 @@ test-custom-cpu-models:
 test-pvesh:
 	./pvesh_test.pl
 
+.PHONY: test-cluster-resources
+test-cluster-resources:
+	./ClusterResources_test.pl
+
 .PHONY: install
 install:
 
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH manager 27/34] api: cluster status: add cluster ID
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (25 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH manager 26/34] api: cluster resources: add guest uid and registration time Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH manager 28/34] ui: restore: allow overwriting a guest with a backup of another guest Thomas Lamprecht
                   ` (8 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Tools need an identifier of the cluster next to the guest uid, to tell
apart guests with the same uid in different clusters. Cluster names are
chosen freely and standalone nodes have none, and the existing 'id'
fields only identify entries within the response.

Return the ID that pmxcfs generates as 'cluster-id' on the cluster
entry, or on the node entry for a standalone node. Omit it while no ID
exists, for example as long as the cluster member with the lowest node
ID runs an older version.

Reading the ID requires Sys.Audit on '/', like the rest of this
endpoint, while the guest uid and rtime in /cluster/resources only need
VM.Audit on the guest. The ID is not a secret; restricting it to this
endpoint is a cautious start, as access is easier to widen than to take
back. Exposing it to less privileged users remains an option, to be
weighed carefully, if a use case needs it.

A failure to read the ID only omits the field, so the status stays
available. It is not logged, as clients poll this endpoint often.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 PVE/API2/Cluster.pm        |  10 ++++
 test/ClusterStatus_test.pl | 114 +++++++++++++++++++++++++++++++++++++
 test/Makefile              |   6 +-
 3 files changed, 129 insertions(+), 1 deletion(-)
 create mode 100755 test/ClusterStatus_test.pl

diff --git a/PVE/API2/Cluster.pm b/PVE/API2/Cluster.pm
index 346ecdb2..bd023c21 100644
--- a/PVE/API2/Cluster.pm
+++ b/PVE/API2/Cluster.pm
@@ -933,6 +933,13 @@ __PACKAGE__->register_method({
                     description =>
                         '[cluster] Indicates if there is a majority of nodes online to make decisions',
                 },
+                'cluster-id' => {
+                    type => 'string',
+                    optional => 1,
+                    description =>
+                        '[cluster] Random identifier of the cluster. A standalone node'
+                        . ' reports its own identifier on its node entry.',
+                },
                 nodeid => {
                     type => 'integer',
                     optional => 1,
@@ -973,6 +980,7 @@ __PACKAGE__->register_method({
         my $members = PVE::Cluster::get_members();
         my $nodename = PVE::INotify::nodename();
         my $rrd = PVE::Cluster::rrd_dump();
+        my $cluster_id = eval { PVE::Cluster::get_cluster_id() };
 
         if ($members) {
             my $res = [];
@@ -986,6 +994,7 @@ __PACKAGE__->register_method({
                         version => $d->{version},
                         name => $d->{name},
                         quorate => $d->{quorate},
+                        defined($cluster_id) ? ('cluster-id' => $cluster_id) : (),
                     };
             }
 
@@ -1027,6 +1036,7 @@ __PACKAGE__->register_method({
                 nodeid => 0,
                 online => 1,
                 level => $sublevel,
+                defined($cluster_id) ? ('cluster-id' => $cluster_id) : (),
             }];
         }
     },
diff --git a/test/ClusterStatus_test.pl b/test/ClusterStatus_test.pl
new file mode 100755
index 00000000..02e9c1d6
--- /dev/null
+++ b/test/ClusterStatus_test.pl
@@ -0,0 +1,114 @@
+#!/usr/bin/perl
+
+use v5.36;
+
+use lib ('.', '..');
+
+use Test::MockModule;
+use Test::More;
+
+use PVE::JSONSchema;
+
+use PVE::API2::Cluster;
+use PVE::API2::Subscription;
+
+my $nodename = 'node1';
+my $cluster_id = 'm4q7z2kd3x6ab5tyw3hc';
+
+my $clinfo;
+my $cluster_id_result; # code returning the result of reading the cluster ID
+
+my $cluster_mock = Test::MockModule->new('PVE::Cluster');
+$cluster_mock->redefine(
+    cfs_update => sub { },
+    get_clinfo => sub { return $clinfo },
+    get_members => sub { return $clinfo->{nodelist} },
+    rrd_dump => sub { return {} },
+    remote_node_ip => sub { return '192.0.2.1' },
+    get_cluster_id => sub { return $cluster_id_result->() },
+);
+
+my $inotify_mock = Test::MockModule->new('PVE::INotify');
+$inotify_mock->redefine(nodename => sub { return $nodename });
+
+my $subscription_mock = Test::MockModule->new('PVE::API2::Subscription');
+$subscription_mock->redefine(read_etc_subscription => sub { return { level => 'c' } });
+
+my $cluster_info = {
+    cluster => { name => 'testcluster', nodes => 2, version => 3, quorate => 1 },
+    nodelist => {
+        node1 => { id => 1, online => 1, ip => '192.0.2.1' },
+        node2 => { id => 2, online => 0, ip => '192.0.2.2' },
+    },
+};
+# what pmxcfs reports without a corosync configuration
+my $standalone_info = { version => 1 };
+
+my $method = PVE::API2::Cluster->map_method_by_name('get_status');
+
+sub get_status() {
+    my $res = PVE::API2::Cluster->handle($method, {});
+    PVE::JSONSchema::validate($res, $method->{returns}, "return schema violated\n");
+    return $res;
+}
+
+sub cluster_ids($res) {
+    return { map { $_->{id} => $_->{'cluster-id'} } grep { exists($_->{'cluster-id'}) } @$res };
+}
+
+for my $case (
+    {
+        name => 'cluster with ID',
+        clinfo => $cluster_info,
+        read => sub { return $cluster_id },
+        expected => { cluster => $cluster_id },
+    },
+    {
+        name => 'cluster without ID',
+        clinfo => $cluster_info,
+        read => sub { return undef },
+        expected => {},
+    },
+    {
+        name => 'cluster, reading the ID fails',
+        clinfo => $cluster_info,
+        read => sub { die "Connection refused\n" },
+        expected => {},
+    },
+    {
+        name => 'standalone node with ID',
+        clinfo => $standalone_info,
+        read => sub { return $cluster_id },
+        expected => { "node/$nodename" => $cluster_id },
+    },
+    {
+        name => 'standalone node without ID',
+        clinfo => $standalone_info,
+        read => sub { return undef },
+        expected => {},
+    },
+    {
+        name => 'standalone node, reading the ID fails',
+        clinfo => $standalone_info,
+        read => sub { die "Connection refused\n" },
+        expected => {},
+    },
+) {
+    subtest $case->{name} => sub {
+        $clinfo = $case->{clinfo};
+        $cluster_id_result = $case->{read};
+
+        my $res = eval { get_status() };
+        is($@, '', 'status does not fail');
+        is_deeply(cluster_ids($res), $case->{expected}, 'cluster ID on the expected entry');
+
+        my $ids = [sort map { $_->{id} } @$res];
+        if ($clinfo->{cluster}) {
+            is_deeply($ids, ['cluster', 'node/node1', 'node/node2'], 'entry IDs unchanged');
+        } else {
+            is_deeply($ids, ["node/$nodename"], 'entry IDs unchanged');
+        }
+    };
+}
+
+done_testing();
diff --git a/test/Makefile b/test/Makefile
index 7eaa46a2..fea9d711 100644
--- a/test/Makefile
+++ b/test/Makefile
@@ -5,7 +5,7 @@ all:
 export PERLLIB=..
 
 .PHONY: check
-check: test-replication test-balloon test-vzdump test-osd test-ceph-health test-ceph-services test-ceph-auth test-ceph-key-migration test-ceph-lockbox-migration test-custom-cpu-models test-pvesh test-cluster-resources
+check: test-replication test-balloon test-vzdump test-osd test-ceph-health test-ceph-services test-ceph-auth test-ceph-key-migration test-ceph-lockbox-migration test-custom-cpu-models test-pvesh test-cluster-resources test-cluster-status
 
 .PHONY: test-balloon
 test-balloon:
@@ -65,6 +65,10 @@ test-pvesh:
 test-cluster-resources:
 	./ClusterResources_test.pl
 
+.PHONY: test-cluster-status
+test-cluster-status:
+	./ClusterStatus_test.pl
+
 .PHONY: install
 install:
 
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH manager 28/34] ui: restore: allow overwriting a guest with a backup of another guest
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (26 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH manager 27/34] api: cluster status: add cluster ID Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH manager 29/34] ui: migrate: refuse target nodes that would drop the guest identity Thomas Lamprecht
                   ` (7 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Restoring a backup with a different uid over an existing guest requires
'allow-identity-mismatch', including backups of a former guest with the
same VMID. The restore task can reject such a backup, but the web UI
could not pass the override, leaving no way to proceed there.

Offer an unchecked checkbox whenever the restore window overwrites an
existing guest. Keep it independent of the overwrite option so an
accidentally selected backup is still rejected by default. The restore
task decides whether the identities match; the UI does not try to
predict that result. With the override, a guest that already had an
identity keeps it.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 www/manager6/window/Restore.js | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/www/manager6/window/Restore.js b/www/manager6/window/Restore.js
index 60266ec1..27df7d53 100644
--- a/www/manager6/window/Restore.js
+++ b/www/manager6/window/Restore.js
@@ -47,6 +47,9 @@ Ext.define('PVE.window.Restore', {
             if (values['live-restore']) {
                 params['live-restore'] = 1;
             }
+            if (values['allow-identity-mismatch']) {
+                params['allow-identity-mismatch'] = 1;
+            }
             if (values.storage) {
                 params.storage = values.storage;
             }
@@ -256,6 +259,21 @@ Ext.define('PVE.window.Restore', {
             },
         ];
 
+        if (me.vmid) {
+            items.push({
+                xtype: 'proxmoxcheckbox',
+                name: 'allow-identity-mismatch',
+                boxLabel: gettext('Allow restoring a backup of another guest'),
+                checked: false,
+                autoEl: {
+                    tag: 'div',
+                    'data-qtip': gettext(
+                        'Also required for a backup of a previous guest with the same VMID. The existing guest keeps its identity.',
+                    ),
+                },
+            });
+        }
+
         if (me.vmtype === 'lxc') {
             items.push({
                 xtype: 'radiogroup',
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH manager 29/34] ui: migrate: refuse target nodes that would drop the guest identity
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (27 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH manager 28/34] ui: restore: allow overwriting a guest with a backup of another guest Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH manager 30/34] ui: guest summary: show " Thomas Lamprecht
                   ` (6 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

The migrate API refuses target nodes that run a Proxmox VE version too
old to keep the guest identity, as they drop it on their next write of
the guest config. The precondition endpoints report such nodes with the
reported and the required version, but the migrate window ignored that:
for a stopped VM, the target was only marked as not allowed without a
reason, while for a running VM and for containers the window offered
the migration and only showed the API error after pressing Migrate.

Show the reason as an error, like for other blocking preconditions, and
disable the Migrate button for such a target. The API has no override
for this check, so the window offers none either.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 www/manager6/window/Migrate.js | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/www/manager6/window/Migrate.js b/www/manager6/window/Migrate.js
index 8cac54ea..e7817708 100644
--- a/www/manager6/window/Migrate.js
+++ b/www/manager6/window/Migrate.js
@@ -214,6 +214,31 @@ Ext.define('PVE.window.Migrate', {
             me.lookup('formPanel').isValid();
         },
 
+        checkGuestIdentitySupport: function (migration, disallowed) {
+            let unsupported = disallowed['guest-identity-unsupported'];
+            if (!unsupported) {
+                return;
+            }
+
+            let text;
+            if (unsupported.version) {
+                text = Ext.String.format(
+                    gettext(
+                        'The selected target node runs Proxmox VE {0}, but keeping the guest identity requires {1} or newer. Upgrade the target node first.',
+                    ),
+                    unsupported.version,
+                    unsupported['required-version'],
+                );
+            } else {
+                text = gettext(
+                    'The selected target node does not report its Proxmox VE version, so support for guest identities cannot be verified.',
+                );
+            }
+
+            migration.possible = false;
+            migration.preconditions.push({ text, severity: 'error' });
+        },
+
         checkQemuPreconditions: async function (resetMigrationPossible) {
             let me = this,
                 vm = me.getViewModel(),
@@ -301,6 +326,8 @@ Ext.define('PVE.window.Migrate', {
                 migration.preconditions.push({ text, severity: 'error' });
             }
 
+            me.checkGuestIdentitySupport(migration, disallowed);
+
             let blockingResources = [];
             let mappedResources = migrateStats['mapped-resource-info'] ?? {};
 
@@ -514,6 +541,8 @@ Ext.define('PVE.window.Migrate', {
             let targetNode = me.lookup('pveNodeSelector').value;
             let disallowed = migrateStats['not-allowed-nodes']?.[targetNode] ?? {};
 
+            me.checkGuestIdentitySupport(migration, disallowed);
+
             let blockingHAResources = disallowed['blocking-ha-resources'] ?? [];
             if (blockingHAResources.length) {
                 migration.possible = false;
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH manager 30/34] ui: guest summary: show the guest identity
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (28 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH manager 29/34] ui: migrate: refuse target nodes that would drop the guest identity Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-17 15:44   ` Dominik Csapak
  2026-11-16  0:46 ` [PATCH docs 31/34] vzdump: describe the guest identity of VMs and containers Thomas Lamprecht
                   ` (5 subsequent siblings)
  35 siblings, 1 reply; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

The 'meta' property of a guest now holds its identity, a unique ID that
restores and migrations from other clusters keep where possible, and
the time the guest was registered in this cluster, next to the creation
time and, for VMs, the QEMU version the VM was created with. The web UI
showed none of it, so comparing a guest with what a backup or monitoring
tool reports for it required reading the config or the API.

Show the unique ID as a quiet row in the status panel of the guest
summary, also for templates, as it is the value such tools report. A
button next to it opens a window with all these values and, for users
with Sys.Audit on '/', the cluster ID. Both IDs are in read-only text
fields, so they can be selected and copied.

The row uses the uid that the guest status already returns, so the
summary makes no extra periodic request, and the window loads the guest
config and the cluster status once when opened. A failure to load the
cluster status only leaves out the cluster ID. Guests without a uid,
for example on nodes that do not handle the identity yet, get no row.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 www/manager6/Makefile                    |   1 +
 www/manager6/panel/GuestIdentity.js      | 142 +++++++++++++++++++++++
 www/manager6/panel/GuestStatusView.js    |   3 +
 www/manager6/panel/TemplateStatusView.js |   3 +
 4 files changed, 149 insertions(+)
 create mode 100644 www/manager6/panel/GuestIdentity.js

diff --git a/www/manager6/Makefile b/www/manager6/Makefile
index d2ea786b..8c4e9ba9 100644
--- a/www/manager6/Makefile
+++ b/www/manager6/Makefile
@@ -113,6 +113,7 @@ JSSRC= 							\
 	panel/IPView.js					\
 	panel/RunningChart.js				\
 	panel/StatusPanel.js				\
+	panel/GuestIdentity.js				\
 	panel/GuestStatusView.js			\
 	panel/GuestSummary.js				\
 	panel/TemplateStatusView.js			\
diff --git a/www/manager6/panel/GuestIdentity.js b/www/manager6/panel/GuestIdentity.js
new file mode 100644
index 00000000..d67ec7d4
--- /dev/null
+++ b/www/manager6/panel/GuestIdentity.js
@@ -0,0 +1,142 @@
+Ext.define('PVE.window.GuestIdentity', {
+    extend: 'Ext.window.Window',
+    alias: 'widget.pveGuestIdentityWindow',
+
+    title: gettext('Guest Identity'),
+    width: 450,
+    modal: true,
+    resizable: false,
+    bodyPadding: 10,
+
+    layout: 'anchor',
+    defaults: {
+        anchor: '100%',
+        labelWidth: 130,
+    },
+
+    // the parsed 'meta' property of the guest config
+    meta: {},
+    clusterId: undefined,
+
+    initComponent: function () {
+        let me = this;
+
+        let meta = me.meta;
+        let renderTime = (seconds) =>
+            Ext.isNumeric(seconds) ? PVE.Utils.render_timestamp_human_readable(seconds) : '';
+
+        let fields = [
+            {
+                xtype: 'textfield',
+                itemId: 'uid',
+                fieldLabel: gettext('Unique ID'),
+                value: meta.uid,
+                editable: false,
+            },
+            {
+                xtype: 'displayfield',
+                itemId: 'rtime',
+                fieldLabel: gettext('Registered'),
+                value: renderTime(meta.rtime / 1000),
+            },
+            {
+                xtype: 'textfield',
+                itemId: 'cluster-id',
+                fieldLabel: gettext('Cluster ID'),
+                value: me.clusterId,
+                editable: false,
+            },
+            {
+                xtype: 'displayfield',
+                itemId: 'ctime',
+                fieldLabel: gettext('Created'),
+                value: renderTime(meta.ctime),
+            },
+            {
+                xtype: 'displayfield',
+                itemId: 'creation-qemu',
+                fieldLabel: gettext('Created with QEMU'),
+                value: meta['creation-qemu'],
+            },
+        ];
+        me.items = fields.filter((field) => (field.value ?? '') !== '');
+
+        me.callParent();
+    },
+});
+
+Ext.define('PVE.panel.GuestIdentityInfo', {
+    extend: 'Ext.container.Container',
+    alias: 'widget.pveGuestIdentityInfo',
+
+    hidden: true,
+    layout: {
+        type: 'hbox',
+        align: 'middle',
+    },
+
+    items: [
+        {
+            xtype: 'pmxInfoWidget',
+            flex: 1,
+            iconCls: 'fa fa-id-card-o fa-fw',
+            title: gettext('Unique ID'),
+            printBar: false,
+            textField: 'uid',
+            // the status view only updates info widgets, so this one shows or hides the whole row
+            renderer: function (uid) {
+                this.up('pveGuestIdentityInfo').setHidden(!uid);
+                return Ext.htmlEncode(uid);
+            },
+        },
+        {
+            xtype: 'button',
+            iconCls: 'fa fa-info-circle',
+            tooltip: gettext('Details'),
+            ariaLabel: gettext('Details'),
+            ui: 'default-toolbar',
+            margin: '0 0 0 5',
+            handler: function () {
+                this.up('pveGuestIdentityInfo').showDetails();
+            },
+        },
+    ],
+
+    showDetails: async function () {
+        let me = this;
+
+        let view = me.up('pmxStatusView');
+        let { node, vmid, type } = view.pveSelNode.data;
+        let caps = Ext.state.Manager.get('GuiCap');
+
+        let [config, status] = await Promise.allSettled([
+            // not the pending values: an unfinished restore queues the uid of its backup there
+            Proxmox.Async.api2({
+                url: `/nodes/${node}/${type}/${vmid}/config`,
+                params: { current: 1 },
+                method: 'GET',
+                waitMsgTarget: view,
+            }),
+            // the cluster ID is optional, so a missing privilege or a failure only omits it
+            caps.dc['Sys.Audit']
+                ? Proxmox.Async.api2({ url: '/cluster/status', method: 'GET', waitMsgTarget: view })
+                : undefined,
+        ]);
+
+        if (config.status === 'rejected') {
+            Ext.Msg.alert(gettext('Error'), config.reason.htmlStatus);
+            return;
+        }
+
+        let meta = PVE.Parser.parsePropertyString(config.value.result.data.meta) ?? {};
+        // a standalone node reports the ID on its node entry, a cluster only on the cluster entry
+        let statusEntries = status.value?.result?.data ?? [];
+        let clusterId = statusEntries.find((entry) => entry['cluster-id'])?.['cluster-id'];
+
+        Ext.create('PVE.window.GuestIdentity', {
+            autoShow: true,
+            meta,
+            clusterId,
+        });
+    },
+});
diff --git a/www/manager6/panel/GuestStatusView.js b/www/manager6/panel/GuestStatusView.js
index 315d3420..00851b07 100644
--- a/www/manager6/panel/GuestStatusView.js
+++ b/www/manager6/panel/GuestStatusView.js
@@ -92,6 +92,9 @@ Ext.define('PVE.panel.GuestStatusView', {
                 hidden: '{isQemu}',
             },
         },
+        {
+            xtype: 'pveGuestIdentityInfo',
+        },
         {
             xtype: 'box',
             height: 10,
diff --git a/www/manager6/panel/TemplateStatusView.js b/www/manager6/panel/TemplateStatusView.js
index 8742cfc2..26732386 100644
--- a/www/manager6/panel/TemplateStatusView.js
+++ b/www/manager6/panel/TemplateStatusView.js
@@ -30,6 +30,9 @@ Ext.define('PVE.panel.TemplateStatusView', {
             iconCls: 'fa fa-fw fa-building',
             title: gettext('Node'),
         },
+        {
+            xtype: 'pveGuestIdentityInfo',
+        },
         {
             xtype: 'box',
             height: 20,
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH docs 31/34] vzdump: describe the guest identity of VMs and containers
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (29 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH manager 30/34] ui: guest summary: show " Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH docs 32/34] pvecm: document the cluster ID and how to get a new one Thomas Lamprecht
                   ` (4 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Since Proxmox VE 9.3, VMs and containers have a guest identity in
'meta': a random uid and a registration time. Backup software and other
tools can distinguish a guest from another that reuses its VMID [0].

Administrators need to understand why restores over a different guest
are refused, when a restore keeps the uid of the backup, and why
migrations and clones to older nodes are blocked. Those nodes drop
'meta', including VM creation information used for hardware defaults.

Document the lifecycle, failed-restore retries, and mixed-version
restrictions in the backup and restore chapter, where users are most
likely to encounter the identity. Include migration and HA behavior
there so the rules can be read together.

[0]: https://bugzilla.proxmox.com/show_bug.cgi?id=7846

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 vzdump.adoc | 256 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 256 insertions(+)

diff --git a/vzdump.adoc b/vzdump.adoc
index 44db027..87136af 100644
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -464,6 +464,13 @@ following CLI tools:
 
 For details see the corresponding manual pages.
 
+When you restore a backup over an existing guest, {pve} compares the guest
+identities of the backup and of the guest. If they differ, the restore is
+refused, unless you set the `allow-identity-mismatch` option. The existing guest
+then keeps its identity. See
+xref:guest_identity_restore[Restore Over an Existing Guest] for details and
+exceptions.
+
 Bandwidth Limit
 ~~~~~~~~~~~~~~~
 
@@ -563,6 +570,255 @@ 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.
 
+[[guest_identity]]
+Guest Identity
+--------------
+
+Since {pve} 9.3, each virtual machine and container has a guest identity: a
+random identifier, `uid`, and a registration time, `rtime`. Unlike a VMID,
+which can be reused after a guest is destroyed, the `uid` lets backup software
+and other tools recognize the same logical guest across restores and
+migrations, even under a different VMID. Whether an operation keeps the `uid`
+depends on the target and the options of the operation, as described in
+xref:guest_identity_lifecycle[Lifecycle].
+
+[[guest_identity_values]]
+Identity Values
+~~~~~~~~~~~~~~~
+
+The guest identity is part of the `meta` property in the guest configuration.
+This property also contains the creation time `ctime` and, for VMs, the QEMU
+version that the VM was created with, `creation-qemu`:
+
+----
+meta: creation-qemu=10.1.2,ctime=1772444467,rtime=1794320571482,uid=w5qczgiem26qnwzwsoil
+----
+
+`uid`::
+
+A random identifier of 20 characters, consisting of the lowercase letters `a` to
+`z` and the digits `2` to `7`.
+
+`rtime`::
+
+The time at which the guest was registered in this cluster, in milliseconds
+since the UNIX epoch. Creating or cloning a guest, restoring it to a free VMID,
+and migrating it from another cluster register the guest in the cluster. A
+guest restored to a free VMID gets a new `rtime`, even if it keeps the backup's
+`uid`. See xref:guest_identity_lifecycle[Lifecycle] for the other operations.
+As a timestamp, the `rtime` is not guaranteed to be unique.
+
+{pve} manages the `meta` property automatically. It is read-only through the
+API, even for `root@pam`.
+
+IMPORTANT: The `uid` helps to correlate a guest with its backups and copies,
+but does not prove where a guest comes from. Whoever restores a backup or
+migrates a guest into the cluster supplies the `uid` of that guest, which {pve}
+takes over if no other guest in the cluster has it. {pve} keeps a `uid` unique
+within a cluster only for operations through its API. A configuration file
+copied by hand has the same `uid` as the original, and guests in different
+clusters can have the same `uid`.
+
+[[guest_identity_read]]
+Reading the Identity
+~~~~~~~~~~~~~~~~~~~~
+
+The following places show the guest identity. All of them require the
+`VM.Audit` privilege on the guest.
+
+* In the web interface, the 'Summary' panel of the guest shows the `uid` as
+  'Unique ID'. The 'Details' button next to it, which has an info icon, opens
+  the 'Guest Identity' window. This window additionally shows the `rtime` as
+  'Registered' and the creation information.
+* The guest configuration, for example with `qm config <vmid>` or
+  `pct config <vmid>`, and through the API paths
+  `/nodes/<node>/qemu/<vmid>/config` and `/nodes/<node>/lxc/<vmid>/config`.
+* The guest status at the API paths `/nodes/<node>/qemu/<vmid>/status/current`
+  and `/nodes/<node>/lxc/<vmid>/status/current`, which contains the `uid`.
+* The cluster resources at the API path `/cluster/resources`, which contain the
+  `uid` and `rtime` of each guest, for example:
++
+----
+# pvesh get /cluster/resources --type vm --output-format json-pretty
+----
+
+The configuration in a backup contains the `meta` property as well. You can
+show it with `pvesm extractconfig <volume>`, for example.
+
+[[guest_identity_lifecycle]]
+Lifecycle
+~~~~~~~~~
+
+The following table shows how operations affect the identity of a guest.
+
+[width="100%",cols="3,4,2",options="header"]
+|===========================================================================
+|Operation |`uid` |`rtime`
+|Create, including import |new |current time
+|Clone, including linked clones and clones from snapshots |new |current time
+|Restore to a free VMID |the backup's `uid` if present and not used by another
+guest in the cluster; otherwise new |current time
+|Restore to a free VMID with `unique` set |new |current time
+|Restore over an existing guest that has a `uid`, with or without `unique` set
+|kept, see xref:guest_identity_restore[Restore Over an Existing Guest] |kept
+|Restore over an existing guest without a `uid` |as for a free VMID |current
+time
+|Migration to another cluster, on the target |the source guest's `uid` if no
+other guest in the target cluster has it; otherwise new |current time
+|Migration to another cluster, on the source if the guest is kept |kept |kept
+|Snapshot rollback |kept, not taken from the snapshot |kept
+|Migration within the cluster, HA recovery, configuration change, backup,
+replication, conversion to a template |kept |kept
+|Destroy |removed |removed
+|===========================================================================
+
+Restores and migrations from another cluster report the outcome in their task
+log, in a line starting with `guest identity:`, for example:
+
+----
+guest identity: backup uid w5qczgiem26qnwzwsoil is in use by guest 100, keeping uid er3n3wqoqgcl362ep3da
+----
+
+When a restore or a migration from another cluster takes over a `uid`, the guest
+first has a newly assigned `uid`. A restore replaces it with the `uid` of the
+backup at its end. A migration from another cluster replaces it with the `uid`
+of the source guest when the target takes over the configuration, which is
+before the migration finishes. Tools that read `/cluster/resources` during such
+a task can therefore see a `uid` that disappears afterwards. A changed `uid`
+does not mean that the task has finished.
+
+Guests that existed before the upgrade to {pve} 9.3 get their identity the
+first time a node running {pve} 9.3 or later writes their configuration. This
+happens, for example, when their configuration changes, when they are backed
+up, or when they are migrated to such a node. Their `rtime` is the time of that
+write. Backups made before that have no `uid`.
+
+When a tool restores a guest by removing it and creating a new one through the
+API, the new guest gets a new `uid`. To keep the identity, a tool has to change
+the existing guest in place, or let {pve} restore the guest.
+
+[[guest_identity_restore]]
+Restore Over an Existing Guest
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the existing guest already has a guest identity, restoring a backup over it
+keeps the `uid` and `rtime` of that guest. When both the guest and the backup
+have a `uid` and the values differ, {pve} treats the backup as belonging to
+another guest. This can happen when a VMID was reused. {pve} refuses such a
+restore before it overwrites the guest:
+
+----
+backup belongs to another guest: its uid 'w5qczgiem26qnwzwsoil' differs from uid 'er3n3wqoqgcl362ep3da' of the existing VM 100 - use 'allow-identity-mismatch' to overwrite the VM anyway
+----
+
+To restore such a backup anyway, set the `allow-identity-mismatch` option. The
+existing guest then keeps its identity. In the web interface, select 'Allow
+restoring a backup of another guest' in the restore window, which you open from
+the 'Backup' panel of the guest. On the command line, use for example:
+
+----
+# qmrestore <archive> <vmid> --force 1 --allow-identity-mismatch 1
+# pct restore <vmid> <archive> --force 1 --allow-identity-mismatch 1
+----
+
+Backups without a `uid`, such as backups made with {pve} versions older than
+9.3, are not refused. Container restores from standard input
+(`pct restore <vmid> -`) are an exception: the `uid` of such a backup is only
+known once the container has been overwritten. A restore from standard input
+over a container with a `uid` therefore always requires
+`allow-identity-mismatch`.
+
+A restore that fails or is stopped can leave the guest behind. If the restore
+was killed, the guest also stays locked. Remove the lock with `qm unlock <vmid>`
+or `pct unlock <vmid>` before you retry the restore or remove the guest.
+
+If the failed restore had already read the configuration of the backup,
+`qm pending <vmid>` or `pct pending <vmid>` lists an entry for `meta` with the
+`uid` of the backup. As long as this entry exists, retrying the same restore
+over the guest left behind is accepted. Starting the guest or changing its
+options removes the entry. The retry is then refused like a restore of another
+guest's backup.
+
+A successful retry takes over the `uid` of the backup and sets a new `rtime`, as
+a restore to a free VMID does. The guest keeps its `uid` and `rtime` instead if
+another guest in the cluster has the `uid` of the backup, or if the retry sets
+`unique`. Restores from standard input still require `allow-identity-mismatch`,
+as described above.
+
+If the failed restore stopped before it read the backup, for example because the
+backup storage was unreachable, the guest left behind is one of the following:
+
+* An empty placeholder of a restore to a free VMID. Unlock it as described
+  above, remove it, for example with `qm destroy <vmid>` or
+  `pct destroy <vmid>`, and restore again.
+* An existing guest that had no `uid` before the restore, now with a new `uid`.
+  Retry with `allow-identity-mismatch`.
+
+A restore can also complete with a warning starting with
+`guest identity: unable to adopt backup uid`, for example if the cluster has no
+quorum at the end of the restore. The guest is then restored completely, but
+keeps its new `uid`. To take over the `uid` of the backup, repeat the restore
+over the guest before you start it or change its configuration.
+
+[[guest_identity_mixed_versions]]
+Mixed Versions in a Cluster
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While some nodes of a cluster still run a {pve} version older than 9.3,
+migrating or cloning a guest to one of these nodes is refused. The guest keeps
+running on its current node. If the target node reports its version, the error
+message shows that version and the minimum required version. If the node does
+not report its version, the operation is refused because {pve} cannot verify
+that the node supports guest identities. The 'Migrate' window of the web
+interface shows the reason for the selected target node.
+
+Moves of HA-managed guests to such nodes are refused in the same way. A running
+VM that the HA stack migrates keeps running. The HA stack stops a container, and
+a VM that it relocates, before it migrates the guest, so such a guest is stopped
+although the move is then refused. The HA stack retries automatic moves until
+they succeed, and such a guest can stay stopped in the meantime. This includes
+moves for:
+
+* the maintenance mode,
+* a node shutdown with the `migrate` shutdown policy,
+* node affinity rules,
+* the CRS load balancer.
+
+Such moves complete only after the target nodes that the HA stack selects run
+{pve} 9.3 or later.
+
+To avoid refused moves while you upgrade a cluster, do one of the following:
+
+* Move all guests away from a node before you upgrade it.
+* Upgrade the packages on all nodes, one node at a time, before you reboot any
+  node or enable the maintenance mode.
+
+The reason for these refusals is that {pve} versions older than 9.3 ignore the
+whole `meta` property of a guest that has a guest identity, including the
+creation information. A VM started on such a node can therefore get different
+virtual hardware, see xref:qm_machine_type[Machine Type]. When such a node
+writes the configuration, the property is lost.
+
+The check covers migrations and clones started on a node running {pve} 9.3 or
+later. It does not cover:
+
+* the HA recovery of guests from a fenced node,
+* configuration files moved by hand,
+* operations started on a node with an older version.
+
+If an older node writes the configuration of a guest in one of these cases, the
+guest loses its `meta` property. It gets a new identity the next time a node
+running {pve} 9.3 or later writes its configuration.
+
+Backups made with {pve} 9.3 or later contain the guest identity. Restore them
+only on nodes running {pve} 9.3 or later, because older versions ignore the
+`meta` property of such backups in the same way.
+
+A migration to another cluster (`qm remote-migrate`, `pct remote-migrate`) is
+refused right after connecting to a target node with a version older than 9.3,
+before any data is transferred. The error is
+`Remote tunnel endpoint too old, upgrade required`.
+
 [[vzdump_configuration]]
 Configuration
 -------------
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH docs 32/34] pvecm: document the cluster ID and how to get a new one
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (30 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH docs 31/34] vzdump: describe the guest identity of VMs and containers Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH docs 33/34] qm: configuration: describe the read-only meta property Thomas Lamprecht
                   ` (3 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Since Proxmox VE 9.3, clusters and standalone nodes have a random ID in
/etc/pve/cluster-id. Tools need it alongside the guest uid because
guests in different clusters can share a uid, for example after a
remote migration that keeps the source guest.

Explain where to read the ID, why generation can be delayed, and how
creating or joining a cluster affects it. pmxcfs protects the file
against ordinary changes from user space.

Cloned installations and nodes separated without reinstalling keep
their old ID. Document removal in forced local mode to get a new
one, and include it in the existing node-separation procedure. Warn
against doing this on a cluster member: the removal can propagate and
cause the entire cluster to generate a new ID.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 pmxcfs.adoc |  1 +
 pvecm.adoc  | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 vzdump.adoc |  3 ++
 3 files changed, 90 insertions(+)

diff --git a/pmxcfs.adoc b/pmxcfs.adoc
index 4a334fd..516d831 100644
--- a/pmxcfs.adoc
+++ b/pmxcfs.adoc
@@ -95,6 +95,7 @@ Files
 |=======
 |`authkey.pub`                          | Public key used by the ticket system
 |`ceph.conf`                            | Ceph configuration file (note: /etc/ceph/ceph.conf is a symbolic link to this)
+|`cluster-id`                           | Random ID of the cluster, generated by pmxcfs and read-only (see xref:guest_identity_cluster_id[Cluster ID])
 |`corosync.conf`                        | Corosync cluster configuration file (prior to {pve} 4.x, this file was called cluster.conf)
 |`datacenter.cfg`                       | {pve} datacenter-wide configuration (keyboard layout, proxy, ...)
 |`domains.cfg`                          | {pve} authentication domains
diff --git a/pvecm.adoc b/pvecm.adoc
index 8309647..41b3c15 100644
--- a/pvecm.adoc
+++ b/pvecm.adoc
@@ -529,6 +529,14 @@ rm /etc/pve/corosync.conf
 rm -r /etc/corosync/*
 ----
 
+Remove the xref:guest_identity_cluster_id[cluster ID], if the cluster has one.
+Without this step, the node keeps the ID of its former cluster instead of
+generating its own when the file system starts again as a normal service:
+[source,bash]
+----
+rm /etc/pve/cluster-id
+----
+
 You can now start the file system again as a normal service:
 [source,bash]
 ----
@@ -572,6 +580,84 @@ authentication. You should fix this by removing the respective keys from the
 '/etc/pve/priv/authorized_keys' file.
 
 
+[[guest_identity_cluster_id]]
+Cluster ID
+----------
+
+Since {pve} 9.3, each cluster has a random cluster ID in the same format as the
+`uid` of a xref:guest_identity[guest identity]. A node that is not part of a
+cluster has an ID of its own. Guests in different clusters can have the same
+`uid`, for example after a migration to another cluster that kept the source
+guest. The cluster ID tells tools to which cluster the `uid` of a guest belongs.
+
+The cluster ID is stored in `/etc/pve/cluster-id`. Through the API,
+`/cluster/status` returns it in the `cluster-id` field of the entry of type
+`cluster`. On a node without a cluster, the field is on the node entry instead.
+Reading the cluster ID through the API requires the `Sys.Audit` privilege on
+`/`. Users with this privilege also see it in the 'Guest Identity' window of a
+guest in the web interface.
+
+----
+# cat /etc/pve/cluster-id
+----
+
+{pve} generates the cluster ID and keeps it unchanged. Creating, changing,
+moving or removing `/etc/pve/cluster-id` fails with `Permission denied`. The
+only exception is removing it in local mode, as described below. Nodes running
+a {pve} version older than 9.3 do not protect the file.
+
+A node without a cluster generates its ID when its cluster file system starts.
+In a cluster, the online node with the lowest node ID generates the ID once all
+of the following apply:
+
+* The cluster is quorate.
+* More than half of the configured nodes are online.
+* The cluster file systems of the online nodes are in sync.
+
+That node must run {pve} 9.3 or later. While a node with an older version has
+the lowest online node ID, the cluster gets no ID. Until an ID exists, the file
+does not exist and the API omits the field. If the node with the lowest online
+node ID runs {pve} 9.3 or later but cannot generate the ID yet, its
+`pve-cluster` service logs the reason in a message starting with
+`not generating a cluster ID yet`.
+
+Creating a cluster with `pvecm create` keeps the ID of the node, which then
+identifies the new cluster. A node that joins a cluster takes over the ID of the
+cluster, because joining replaces the configuration of the node in `/etc/pve`.
+A copy of an installation, such as a cloned disk or a copy of the cluster file
+system database, has the same ID as the original.
+
+To give a node that is not part of a cluster a new ID, for example after cloning
+an installation, follow the steps below. To separate a node from its cluster,
+follow xref:pvecm_separate_node_without_reinstall[Separate a Node Without Reinstalling]
+instead. That procedure includes the removal of the cluster ID.
+
+WARNING: Do not remove `/etc/pve/cluster-id` on a node that is still part of a
+cluster. When that node rejoins the cluster, the removal is either undone, or it
+reaches all nodes and the whole cluster gets a new ID.
+
+. Stop the cluster file system and start it again in local mode:
++
+----
+# systemctl stop pve-cluster
+# pmxcfs -l
+----
+
+. Remove the cluster ID file:
++
+----
+# rm /etc/pve/cluster-id
+----
+
+. Stop the cluster file system and start it again as a normal service, which
+  generates a new ID:
++
+----
+# killall pmxcfs
+# systemctl start pve-cluster
+----
+
+
 Quorum
 ------
 
diff --git a/vzdump.adoc b/vzdump.adoc
index 87136af..98db206 100644
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -645,6 +645,9 @@ The following places show the guest identity. All of them require the
 The configuration in a backup contains the `meta` property as well. You can
 show it with `pvesm extractconfig <volume>`, for example.
 
+To tell apart guests with the same `uid` in different clusters, combine the
+`uid` with the xref:guest_identity_cluster_id[cluster ID].
+
 [[guest_identity_lifecycle]]
 Lifecycle
 ~~~~~~~~~
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH docs 33/34] qm: configuration: describe the read-only meta property
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (31 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH docs 32/34] pvecm: document the cluster ID and how to get a new one Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-16  0:46 ` [PATCH docs 34/34] pct: " Thomas Lamprecht
                   ` (2 subsequent siblings)
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

The 'meta' property of VMs was not documented anywhere, as the generated
option reference leaves it out for being read-only. Since Proxmox VE
9.3, it also holds the guest identity, and it matters for upgrades:
older versions drop the whole property, including 'creation-qemu',
which keeps the machine version of Windows VMs and some other hardware
defaults stable.

Describe its members next to the snapshot properties, refer to the
guest identity section for 'uid' and 'rtime', and state why migrations
and clones to nodes with older versions are refused.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 qm.adoc | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/qm.adoc b/qm.adoc
index 18a4fbe..53615c9 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -2436,6 +2436,44 @@ For details about how the target storage gets chosen for the VM state, see
 xref:qm_vmstatestorage[State storage selection] in the chapter
 xref:qm_hibernate[Hibernation].
 
+[[qm_meta_info]]
+Meta Information
+~~~~~~~~~~~~~~~~
+
+The read-only `meta` property contains information that {pve} records
+automatically about the VM:
+
+`ctime`::
+
+The time the VM was created, in seconds since the UNIX epoch.
+
+`creation-qemu`::
+
+The QEMU version that the VM was created with. For VMs without a fixed machine
+version, {pve} uses it to keep parts of the virtual hardware as they were at
+creation, for example the machine version of Windows VMs, see
+xref:qm_machine_type[Machine Type].
+
+`uid` and `rtime`::
+
+The guest identity of the VM, available since {pve} 9.3, see
+xref:guest_identity[Guest Identity].
+
+.Example `meta` property of a VM
+----
+meta: creation-qemu=10.1.2,ctime=1772444467,rtime=1794320571482,uid=w5qczgiem26qnwzwsoil
+----
+
+A clone keeps its source VM's `ctime` and `creation-qemu` values. A restored VM
+uses the values from the backup. VMs created with older versions of {pve} can
+lack these values.
+
+{pve} versions older than 9.3 ignore the whole `meta` property of a VM with a
+guest identity, including `creation-qemu`, and drop it when they write the
+configuration. A VM started on a node running such a version can therefore get
+different virtual hardware. Migrating or cloning a VM to such a node is refused,
+see xref:guest_identity_mixed_versions[Mixed Versions in a Cluster].
+
 [[qm_options]]
 Options
 ~~~~~~~
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* [PATCH docs 34/34] pct: configuration: describe the read-only meta property
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (32 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH docs 33/34] qm: configuration: describe the read-only meta property Thomas Lamprecht
@ 2026-11-16  0:46 ` Thomas Lamprecht
  2026-11-17 10:47 ` [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Dominik Csapak
  2026-11-17 15:55 ` Dominik Csapak
  35 siblings, 0 replies; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-16  0:46 UTC (permalink / raw)
  To: pve-devel

Since Proxmox VE 9.3, containers have a 'meta' property with their
creation time and guest identity. The generated option reference omits
this read-only property, so document its members alongside the other
configuration metadata.

Explain that containers created with older versions have no recorded
creation time and that migration or cloning to older nodes is refused
to avoid losing the identity.

Also note that restoring from standard input over a container that
already has an identity requires 'allow-identity-mismatch'. The backup
uid is only known after the container has been overwritten, too late
for the normal mismatch check.

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
 pct.adoc | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/pct.adoc b/pct.adoc
index 25dc1fe..b36086b 100644
--- a/pct.adoc
+++ b/pct.adoc
@@ -970,6 +970,10 @@ command line (see the `pct` manual page for details).
 NOTE: `pvesm extractconfig` can be used to view the backed up configuration
 contained in a vzdump archive.
 
+A restore from standard input over an existing container with a guest identity
+always needs the `allow-identity-mismatch` option, see
+xref:guest_identity_restore[Restore Over an Existing Guest].
+
 There are two basic restore modes, only differing by their handling of mount
 points:
 
@@ -1249,6 +1253,37 @@ There are a few snapshot related properties like `parent` and `snaptime`. The
 snapshots. `snaptime` is the snapshot creation time stamp (Unix epoch).
 
 
+[[pct_meta_info]]
+Meta Information
+~~~~~~~~~~~~~~~~
+
+The read-only `meta` property contains information that {pve} records
+automatically about the container:
+
+`ctime`::
+
+The time the container was created, in seconds since the UNIX epoch.
+
+`uid` and `rtime`::
+
+The guest identity of the container, available since {pve} 9.3, see
+xref:guest_identity[Guest Identity].
+
+.Example `meta` property of a container
+----
+meta: ctime=1772444467,rtime=1794320571482,uid=w5qczgiem26qnwzwsoil
+----
+
+A clone keeps its source container's `ctime`. A restored container uses the
+`ctime` from the backup. Containers created with {pve} versions older than 9.3
+have no `ctime`.
+
+{pve} versions older than 9.3 do not know the `meta` property of containers and
+drop it when they write the configuration. Therefore, migrating or cloning a
+container to a node running such a version is refused, see
+xref:guest_identity_mixed_versions[Mixed Versions in a Cluster].
+
+
 [[pct_options]]
 Options
 ~~~~~~~
-- 
2.47.3





^ permalink raw reply related	[flat|nested] 49+ messages in thread

* Re: [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (33 preceding siblings ...)
  2026-11-16  0:46 ` [PATCH docs 34/34] pct: " Thomas Lamprecht
@ 2026-11-17 10:47 ` Dominik Csapak
  2026-11-17 11:29   ` Thomas Lamprecht
  2026-11-17 15:55 ` Dominik Csapak
  35 siblings, 1 reply; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 10:47 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel

I started reviewing this series and wanted to give some early feedback 
on the overall approach. More in depth code review see the individual
patches (might take a bit going through every patch)

Note that i might have overlooked something. If so, please
do tell me.

My high level feedback:

Cluster IDs:

Is there a particular reason why 100bit + base32?
I couldn't find a rationale for the choice (did i overlook it?)
and I think using something 'industry standard' like a
UUIDv7 would be a better choice? I'ts just 28 bit more (
with a bit less randomness) but with a time stamp included and this
should make each cluster uniquely identifiable too.

If we want to stay on base32, maybe 80 or 120 bit is a better choice,
since we then don't have to use half a byte (100bit => 12.5 byte)
and still provide enough randomness.

VM UIDs:

Same question about the rationale behind the format, but with one
change: the 'registering' time is already recorded in
the meta object (as ctime), no? so providing an additional separate
timestamp seems weird to me. Also using UUIDv7 here
would include a timestamp too and also be more 'industry standard'
while only using 1 byte extra (36 vs 20 + 15). Though
we probably would save some space by not having two properties in
the meta object.

UID adoption/checks:

The cluster wide check is necessary, i get it. Handling
it with a cluster lock + reading the cofnig
could make that lookup a bottleneck in big and dynamic clusters?
Or did i misunderstood how we get the meta config out?

Alternatively we could have that lookup in pmxcfs itself and
replicate it like rrd, etc.? having a uuid saved as
a 128bit number (16byte) would mean

160k for 10000 guests
16M for 1000000 guests

which looks reasonable to me?
(we already have to have much more data in pmxcfs
with that many guests...)


Let me know what you think


On 11/16/26 1:48 AM, Thomas Lamprecht wrote:
> A VMID can be reused for another guest, and a guest can get another
> VMID or move to another cluster through a restore or a remote
> migration. So backup software and other tools cannot tell whether they
> still look at the same guest, see [0].
> 
> This series gives every VM and container a guest identity in the
> read-only 'meta' property: a random uid (100 bits as 20 base32
> characters) and the time the guest was registered in the cluster. Create
> and clone get a new uid. Config changes, migration, rollback, backup and
> restore keep it, also under another VMID or in another cluster, as long
> as no other guest there has it. Each cluster or standalone node also
> gets a cluster ID in the same format, generated and protected by pmxcfs.
> The docs patches describe the details.
> 
> Two behavior changes come with it:
> 
> * Restoring over an existing guest whose uid differs from the one of
>    the backup is refused unless 'allow-identity-mismatch' is set. 'force'
>    alone does not override this.
> * Older versions drop the whole 'meta' property of a guest that has an
>    identity. So migration and clone to such nodes is refused, and remote
>    migration bumps the tunnel version. This also hits moves by the HA
>    stack, which stops a container or a relocated VM before the migration
>    gets refused. A target check in the LRM that avoids this will follow
>    separately.
> 
> The patches are in dependency order: guest-common needs a pve-cluster
> newer than 9.1.9, qemu-server and container need guest-common, and
> manager needs all of them. manager also has to depend on the
> qemu-server and container versions with this series, as the migration
> guard takes the pve-manager version of a node as proof that the node
> keeps the identity. MIN_PVE_MANAGER_VERSION in guest-common is a
> stand-in for that pve-manager version.
> 
> Tested with the test suites of the repositories and end to end on a
> nested three-node cluster that was upgraded node by node.
> 
> [0]: https://bugzilla.proxmox.com/show_bug.cgi?id=7846
> 
> cluster:
> 
> Thomas Lamprecht (7):
>    pmxcfs: reject changes to the cluster ID file from user space
>    pmxcfs: generate a cluster ID on standalone nodes
>    pmxcfs: dfsm: add a callback that runs once all members are in sync
>    pmxcfs: quorum: pass the corosync membership to an optional listener
>    pmxcfs: dcdb: generate the cluster ID once the cluster is in sync
>    cluster: add helper to read the cluster ID
>    pmxcfs: allow removing the cluster ID file in forced local mode
> 
>   src/PVE/Cluster.pm          |  16 ++
>   src/pmxcfs/Makefile         |  12 +-
>   src/pmxcfs/cfs-plug-memdb.c |  46 ++++
>   src/pmxcfs/cfs-utils.c      |   8 +
>   src/pmxcfs/cfs-utils.h      |   5 +
>   src/pmxcfs/check_dcdb.c     | 529 ++++++++++++++++++++++++++++++++++++
>   src/pmxcfs/check_memdb.c    | 311 +++++++++++++++++++++
>   src/pmxcfs/cluster-id.c     | 158 +++++++++++
>   src/pmxcfs/cluster-id.h     |  52 ++++
>   src/pmxcfs/dcdb.c           | 144 ++++++++++
>   src/pmxcfs/dcdb.h           |   5 +
>   src/pmxcfs/dfsm.c           |  58 ++++
>   src/pmxcfs/dfsm.h           |  14 +
>   src/pmxcfs/pmxcfs.c         |  10 +-
>   src/pmxcfs/quorum.c         |  26 +-
>   src/pmxcfs/quorum.h         |   8 +-
>   src/pmxcfs/status.c         |  12 +
>   src/pmxcfs/status.h         |   3 +
>   src/test/Makefile           |   6 +-
>   src/test/test_cluster_id.pl |  47 ++++
>   20 files changed, 1458 insertions(+), 12 deletions(-)
>   create mode 100644 src/pmxcfs/check_dcdb.c
>   create mode 100644 src/pmxcfs/cluster-id.c
>   create mode 100644 src/pmxcfs/cluster-id.h
>   create mode 100644 src/test/test_cluster_id.pl
> 
> 
> guest-common:
> 
> Thomas Lamprecht (4):
>    guest identity: add helpers for the guest uid and registration time
>    abstract config: assign a guest identity and keep it on config writes
>    abstract config: let the VMID reservation return the previous state
>    guest identity: allow taking over a uid that is unused in the cluster
> 
>   debian/control                     |    1 +
>   src/Makefile                       |    1 +
>   src/PVE/AbstractConfig.pm          |  235 +++++-
>   src/PVE/GuestIdentity.pm           |  384 ++++++++++
>   src/tests/Makefile                 |   10 +-
>   src/tests/config-identity-tests.pl | 1090 ++++++++++++++++++++++++++++
>   src/tests/guest-identity-tests.pl  |  421 +++++++++++
>   7 files changed, 2135 insertions(+), 7 deletions(-)
>   create mode 100644 src/PVE/GuestIdentity.pm
>   create mode 100755 src/tests/config-identity-tests.pl
>   create mode 100755 src/tests/guest-identity-tests.pl
> 
> 
> qemu-server:
> 
> Thomas Lamprecht (6):
>    api: restore: release the VMID if a restore to an unused VMID fails
>    api: migrate, clone: refuse targets that would drop the guest identity
>    fix #7846: config: add a guest identity to the 'meta' property
>    restore: take over the guest uid from the backup where possible
>    api: remote migration: take over the guest uid from the source
>    api: status: return the guest uid
> 
>   src/PVE/API2/Qemu.pm                          | 104 +-
>   src/PVE/CLI/qmrestore.pm                      |   7 +
>   src/PVE/QemuConfig.pm                         |   7 +
>   src/PVE/QemuMigrate.pm                        |   9 +-
>   src/PVE/QemuServer.pm                         | 150 ++-
>   src/PVE/QemuServer/MetaInfo.pm                |   2 +
>   src/test/Makefile                             |   5 +-
>   src/test/QemuServerTest/FakeCFS.pm            | 197 ++++
>   .../q35-windows-pinning-identity-only.conf    |   6 +
>   ...q35-windows-pinning-identity-only.conf.cmd |  26 +
>   .../meta-identity-invalid.conf                |   6 +
>   .../meta-identity-invalid.conf.strict.error   |   2 +
>   .../meta-identity-invalid.conf                |   7 +
>   .../parse-config-input/meta-identity.conf     |  20 +
>   src/test/restore-config-expected/150.conf     |   9 +
>   src/test/restore-config-input/150.conf        |  10 +
>   src/test/run_api_tests.pl                     | 157 +++
>   src/test/run_guest_identity_tests.pl          | 533 ++++++++++
>   src/test/run_parse_config_tests.pl            |   2 +-
>   src/test/run_qemu_restore_config_tests.pl     | 916 +++++++++++++++++-
>   .../create/qemu-server/401.conf               |  31 +
>   .../create/qemu-server/402.conf               |  31 +
>   .../rollback/qemu-server/401.conf             |  36 +
>   .../rollback/qemu-server/402.conf             |  35 +
>   .../create/qemu-server/401.conf               |  13 +
>   .../create/qemu-server/402.conf               |  13 +
>   .../rollback/qemu-server/401.conf             |  35 +
>   .../rollback/qemu-server/402.conf             |  34 +
>   src/test/snapshot-test.pm                     |  85 +-
>   29 files changed, 2439 insertions(+), 49 deletions(-)
>   create mode 100644 src/test/QemuServerTest/FakeCFS.pm
>   create mode 100644 src/test/cfg2cmd/q35-windows-pinning-identity-only.conf
>   create mode 100644 src/test/cfg2cmd/q35-windows-pinning-identity-only.conf.cmd
>   create mode 100644 src/test/parse-config-expected/meta-identity-invalid.conf
>   create mode 100644 src/test/parse-config-expected/meta-identity-invalid.conf.strict.error
>   create mode 100644 src/test/parse-config-input/meta-identity-invalid.conf
>   create mode 100644 src/test/parse-config-input/meta-identity.conf
>   create mode 100644 src/test/restore-config-expected/150.conf
>   create mode 100644 src/test/restore-config-input/150.conf
>   create mode 100755 src/test/run_guest_identity_tests.pl
>   create mode 100644 src/test/snapshot-expected/create/qemu-server/401.conf
>   create mode 100644 src/test/snapshot-expected/create/qemu-server/402.conf
>   create mode 100644 src/test/snapshot-expected/rollback/qemu-server/401.conf
>   create mode 100644 src/test/snapshot-expected/rollback/qemu-server/402.conf
>   create mode 100644 src/test/snapshot-input/create/qemu-server/401.conf
>   create mode 100644 src/test/snapshot-input/create/qemu-server/402.conf
>   create mode 100644 src/test/snapshot-input/rollback/qemu-server/401.conf
>   create mode 100644 src/test/snapshot-input/rollback/qemu-server/402.conf
> 
> 
> container:
> 
> Thomas Lamprecht (8):
>    config: add read-only meta property with the creation time
>    fix #7846: config: add a guest identity to the 'meta' property
>    api: migrate, clone: refuse targets that would drop the guest identity
>    restore: take over the guest uid from the backup where possible
>    restore: refuse overwriting a container with another guest's backup
>    migrate: remote: clean up the target on a tunnel version mismatch
>    api: remote migration: take over the guest uid from the source
>    api: status: return the guest uid
> 
>   src/PVE/API2/LXC.pm         |  166 +++-
>   src/PVE/API2/LXC/Config.pm  |   29 +-
>   src/PVE/API2/LXC/Status.pm  |   10 +
>   src/PVE/LXC/Config.pm       |   63 +-
>   src/PVE/LXC/Migrate.pm      |   31 +-
>   src/test/Makefile           |    8 +-
>   src/test/config_tests.pl    |   23 +
>   src/test/lifecycle_tests.pl | 1878 +++++++++++++++++++++++++++++++++++
>   8 files changed, 2177 insertions(+), 31 deletions(-)
>   create mode 100755 src/test/lifecycle_tests.pl
> 
> 
> manager:
> 
> Thomas Lamprecht (5):
>    api: cluster resources: add guest uid and registration time
>    api: cluster status: add cluster ID
>    ui: restore: allow overwriting a guest with a backup of another guest
>    ui: migrate: refuse target nodes that would drop the guest identity
>    ui: guest summary: show the guest identity
> 
>   PVE/API2/Cluster.pm                      |  35 +++-
>   test/ClusterResources_test.pl            | 249 +++++++++++++++++++++++
>   test/ClusterStatus_test.pl               | 114 +++++++++++
>   test/Makefile                            |  10 +-
>   www/manager6/Makefile                    |   1 +
>   www/manager6/panel/GuestIdentity.js      | 142 +++++++++++++
>   www/manager6/panel/GuestStatusView.js    |   3 +
>   www/manager6/panel/TemplateStatusView.js |   3 +
>   www/manager6/window/Migrate.js           |  29 +++
>   www/manager6/window/Restore.js           |  18 ++
>   10 files changed, 602 insertions(+), 2 deletions(-)
>   create mode 100755 test/ClusterResources_test.pl
>   create mode 100755 test/ClusterStatus_test.pl
>   create mode 100644 www/manager6/panel/GuestIdentity.js
> 
> 
> docs:
> 
> Thomas Lamprecht (4):
>    vzdump: describe the guest identity of VMs and containers
>    pvecm: document the cluster ID and how to get a new one
>    qm: configuration: describe the read-only meta property
>    pct: configuration: describe the read-only meta property
> 
>   pct.adoc    |  35 +++++++
>   pmxcfs.adoc |   1 +
>   pvecm.adoc  |  86 +++++++++++++++++
>   qm.adoc     |  38 ++++++++
>   vzdump.adoc | 259 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>   5 files changed, 419 insertions(+)
> 
> 
> Summary over all repositories:
>    79 files changed, 9230 insertions(+), 101 deletions(-)
> 





^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH guest-common 08/34] guest identity: add helpers for the guest uid and registration time
  2026-11-16  0:46 ` [PATCH guest-common 08/34] guest identity: add helpers for the guest uid and registration time Thomas Lamprecht
@ 2026-11-17 10:47   ` Dominik Csapak
  0 siblings, 0 replies; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 10:47 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel

some comments inline

On 11/16/26 1:49 AM, Thomas Lamprecht wrote:
> A VMID can be reused, and a guest can get a different VMID or move
> to another cluster after a restore or remote migration. External tools
> such as backup products need to recognize the same logical guest
> independently of its VMID, as described in bug #7846.
> 
> Provide shared helpers for a random 100-bit uid, encoded as 20
> lowercase base32 characters, and a registration time in milliseconds.
> Both are members of the guest config's 'meta' property. Supply format
> definitions for both guest types and extract or merge the identity
> without requiring knowledge of other members, including newer ones.
> 
> Also provide a minimum node-version check for migration targets.
> Older versions drop the identity on config writes. Report the required
> and available versions so callers can explain a refusal; missing
> version information counts as too old.
> 
> Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
> ---
> 
> Note: MIN_PVE_MANAGER_VERSION (9.2.29) is a stand-in. It has to become
> the first pve-manager version that depends on the qemu-server and
> pve-container versions with this series, see the cover letter.
> 
>   debian/control                    |   1 +
>   src/Makefile                      |   1 +
>   src/PVE/GuestIdentity.pm          | 199 ++++++++++++++++++++
>   src/tests/Makefile                |   7 +-
>   src/tests/guest-identity-tests.pl | 291 ++++++++++++++++++++++++++++++
>   5 files changed, 497 insertions(+), 2 deletions(-)
>   create mode 100644 src/PVE/GuestIdentity.pm
>   create mode 100755 src/tests/guest-identity-tests.pl
> 
> diff --git a/debian/control b/debian/control
> index ae80297..57fcdf4 100644
> --- a/debian/control
> +++ b/debian/control
> @@ -6,6 +6,7 @@ Build-Depends: debhelper-compat (= 13),
>                  libpve-cluster-perl,
>                  libpve-common-perl (>= 9.2.6),
>                  libpve-storage-perl (>= 8.3.4),
> +               libtest-mockmodule-perl <!nocheck>,
>                  pve-cluster,
>   Standards-Version: 4.6.2
>   Homepage: https://www.proxmox.com
> diff --git a/src/Makefile b/src/Makefile
> index 030e7f7..f3546a9 100644
> --- a/src/Makefile
> +++ b/src/Makefile
> @@ -7,6 +7,7 @@ all:
>   install: PVE
>   	install -d ${PERL5DIR}/PVE
>   	install -m 0644 PVE/GuestHelpers.pm ${PERL5DIR}/PVE/
> +	install -m 0644 PVE/GuestIdentity.pm ${PERL5DIR}/PVE/
>   	install -m 0644 PVE/AbstractConfig.pm ${PERL5DIR}/PVE/
>   	install -m 0644 PVE/AbstractMigrate.pm ${PERL5DIR}/PVE/
>   	install -m 0644 PVE/ReplicationConfig.pm ${PERL5DIR}/PVE/
> diff --git a/src/PVE/GuestIdentity.pm b/src/PVE/GuestIdentity.pm
> new file mode 100644
> index 0000000..44c9a1f
> --- /dev/null
> +++ b/src/PVE/GuestIdentity.pm
> @@ -0,0 +1,199 @@
> +package PVE::GuestIdentity;
> +
> +use strict;
> +use warnings;
> +
> +use Time::HiRes;
> +
> +use PVE::Cluster;
> +
> +# The identity of a guest, VM or container alike, consists of two members of the 'meta' property
> +# string in the top-level section of its config: 'uid', a random identifier of the guest's lineage
> +# (100 bits as 20 characters of the lowercase RFC 4648 base32 alphabet), and 'rtime', the time the
> +# config was registered in this cluster (milliseconds since the epoch). The functions here pass it
> +# as a hash with these two keys.
> +
> +# Must match the first pve-manager release that depends on the qemu-server and pve-container
> +# versions handling the identity. Older nodes drop the whole 'meta' property on their next write
> +# of a guest config.
> +use constant MIN_PVE_MANAGER_VERSION => '9.2.29';
> +
> +my $UID_LENGTH = 20;
> +my $UID_PATTERN = "[a-z2-7]{$UID_LENGTH}";
> +# the fewest bytes that hold the 5 bits of every uid character, the 4 bits left over are dropped
> +my $UID_BYTES = 13;
> +my $BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
> +
> +# 15 digits of milliseconds last until the year 33658
> +my $RTIME_MAX = 999_999_999_999_999;
> +
> +# Returns $len random bytes from the kernel's random number generator.
> +sub __random_bytes {
> +    my ($len) = @_;
> +
> +    open(my $fh, '<', '/dev/urandom') or die "unable to open /dev/urandom - $!\n";
> +    my $buf = '';
> +    my $read = sysread($fh, $buf, $len);
> +    die "unable to read from /dev/urandom - $!\n" if !defined($read);
> +    die "short read from /dev/urandom\n" if $read != $len;
> +    close($fh);
> +
> +    return $buf;
> +}
> +
> +# Returns the current time in milliseconds since the epoch.
> +sub __time_ms {
> +    my ($sec, $usec) = Time::HiRes::gettimeofday();
> +
> +    return $sec * 1000 + int($usec / 1000);
> +}
> +
> +# Encodes the first 5 * $UID_LENGTH bits of $bytes as uid. Every character gets 5 bits of its own,
> +# so it is uniformly distributed over the alphabet if the bits are.
> +my sub encode_uid {
> +    my ($bytes) = @_;
> +
> +    my $bits = unpack('B*', $bytes);
> +    die "internal error: " . length($bytes) . " bytes are too few for a uid\n"
> +        if length($bits) < 5 * $UID_LENGTH;
> +
> +    my @groups = substr($bits, 0, 5 * $UID_LENGTH) =~ m/(.{5})/g;
> +    return join('', map { substr($BASE32_ALPHABET, oct("0b$_"), 1) } @groups);
> +}

not sure if it makes sense to duplicate these across pmxcfs and perl?
could'nt we expose the pmxcfs ones via an ipcc call?

i know it's easy enough and they don't have to be identical, but
seems wasteful to have it implemented multiple times...

> +
> +my sub is_valid_uid {
> +    my ($uid) = @_;
> +
> +    return defined($uid) && $uid =~ m/^$UID_PATTERN\z/;
> +}
> +
> +my sub is_valid_rtime {
> +    my ($rtime) = @_;
> +
> +    return defined($rtime) && $rtime =~ m/^[0-9]{1,15}\z/;
> +}
> +
> +# Returns the JSON schema properties of the identity members, for merging into the format of the
> +# 'meta' property string of a guest type. Every call returns a new copy.
> +sub meta_format_properties {
> +    return {
> +        uid => {
> +            type => 'string',
> +            pattern => $UID_PATTERN,
> +            description =>
> +                "Random identifier of the guest lineage. Restores and migrations from other"
> +                . " clusters keep it, unless another guest in the cluster already uses it, the"
> +                . " restore sets 'unique', or the restore target already has a uid of its own.",
> +            optional => 1,
> +        },
> +        rtime => {
> +            type => 'integer',
> +            minimum => 0,
> +            maximum => $RTIME_MAX,
> +            description => "Time the guest was registered in this cluster, for example by"
> +                . " creation, restore, or migration from another cluster, in milliseconds since"
> +                . " the UNIX epoch.",
> +            optional => 1,
> +        },
> +    };
> +}
> +
> +# Returns a new identity with the current time as rtime. Its uid is $uid if given, otherwise a
> +# random one.
> +sub new_identity {
> +    my ($uid) = @_;
> +
> +    die "invalid guest identity uid '$uid'\n" if defined($uid) && !is_valid_uid($uid);
> +
> +    return {
> +        uid => $uid // encode_uid(__random_bytes($UID_BYTES)),
> +        rtime => __time_ms(),
> +    };
> +}
> +
> +# Extracts the identity from the 'meta' property string $meta, which may contain any other
> +# members, including ones unknown to this version.
> +#
> +# Returns undef if $meta has no valid uid, and an identity otherwise. Its rtime is undef if the
> +# rtime member is missing or invalid. A member given more than once counts as invalid.
> +sub parse_identity {
> +    my ($meta) = @_;
> +
> +    return undef if !defined($meta);
> +
> +    my $values = {};
> +    for my $part (split(/,/, $meta)) {
> +        my ($key, $value) = $part =~ m/^([^=]+)=(.*)\z/ or next;
> +        next if $key ne 'uid' && $key ne 'rtime';
> +        $values->{$key} = exists($values->{$key}) ? undef : $value;
> +    }
> +
> +    return undef if !is_valid_uid($values->{uid});
> +
> +    return {
> +        uid => $values->{uid},
> +        rtime => is_valid_rtime($values->{rtime}) ? $values->{rtime} : undef,
> +    };
> +}

does it really make sense to have a separate parser for this?
wouldn't adding an optiont to parse_property_string to ignore
other fields be better?

> +
> +# Returns the 'meta' property string $meta, which may be undef, with the identity members set to
> +# $identity. All other members are kept as they are.
> +sub merge_identity {
> +    my ($meta, $identity) = @_;
> +
> +    die "invalid guest identity uid\n" if !is_valid_uid($identity->{uid});
> +    die "invalid guest identity rtime\n" if !is_valid_rtime($identity->{rtime});
> +
> +    my (@plain, @members);
> +    for my $part (split(/,/, $meta // '')) {
> +        next if $part =~ m/^\s*\z/;
> +
> +        if (my ($key) = $part =~ m/^([^=]+)=/) {
> +            push @members, [$key, $part] if $key ne 'uid' && $key ne 'rtime';
> +        } else {
> +            push @plain, $part;
> +        }
> +    }
> +    push @members, ['rtime', "rtime=$identity->{rtime}"], ['uid', "uid=$identity->{uid}"];
> +
> +    # same order as PVE::JSONSchema::print_property_string uses, so that a guest type parsing and
> +    # printing the property string again does not change it

IMO this comment is already a sign that we should reuse the
property_string helpers..

> +    return join(',', @plain, map { $_->[1] } sort { $a->[0] cmp $b->[0] } @members);
> +}
> +
> +# Returns undef if $node runs a version of Proxmox VE that keeps the identity when writing guest
> +# configs, see MIN_PVE_MANAGER_VERSION. Missing or invalid version information counts as too old.
> +# Otherwise returns a hash with 'required-version', the minimum version, and 'version', the version
> +# the node reports, if any.
> +sub node_identity_unsupported {
> +    my ($node) = @_;
> +
> +    my $required = MIN_PVE_MANAGER_VERSION;
> +    my ($major, $minor, $release) = split(/\./, $required);
> +
> +    my $supported =
> +        eval { PVE::Cluster::node_pvecfg_version_at_least($node, $major, $minor, $release) };
> +    return undef if $supported;
> +
> +    my $version = eval { PVE::Cluster::get_node_pvecfg_version($node) };
> +
> +    return { 'required-version' => $required, defined($version) ? (version => $version) : () };
> +}
> +
> +# Dies unless $node runs a version of Proxmox VE that keeps the identity when writing guest
> +# configs, see node_identity_unsupported.
> +sub assert_node_supports_identity {
> +    my ($node) = @_;
> +
> +    my $unsupported = node_identity_unsupported($node) or return;
> +    my ($version, $required) = $unsupported->@{qw(version required-version)};
> +
> +    die "node '$node' does not report its Proxmox VE version, so it is unknown whether the node"
> +        . " keeps the guest identity\n"
> +        if !defined($version);
> +
> +    die "node '$node' runs Proxmox VE $version, keeping the guest identity requires $required or"
> +        . " newer - upgrade the node first\n";
> +}
> +
> +1;
> diff --git a/src/tests/Makefile b/src/tests/Makefile
> index 1b1ddb2..129a57e 100644
> --- a/src/tests/Makefile
> +++ b/src/tests/Makefile
> @@ -1,11 +1,14 @@
>   
>   all:
>   
> -.PHONY: check abstract-config hookscript
> -check: abstract-config hookscript
> +.PHONY: check abstract-config guest-identity hookscript
> +check: abstract-config guest-identity hookscript
>   
>   abstract-config: abstract-config-tests.pl
>   	perl -I.. ./abstract-config-tests.pl
>   
> +guest-identity: guest-identity-tests.pl
> +	perl -I.. ./guest-identity-tests.pl
> +
>   hookscript: hookscript-tests.pl
>   	perl -I.. ./hookscript-tests.pl
> diff --git a/src/tests/guest-identity-tests.pl b/src/tests/guest-identity-tests.pl
> new file mode 100755
> index 0000000..fb5167d
> --- /dev/null
> +++ b/src/tests/guest-identity-tests.pl
> @@ -0,0 +1,291 @@
> +#!/usr/bin/perl
> +
> +use strict;
> +use warnings;
> +
> +use lib qw(..);
> +
> +use Test::MockModule;
> +use Test::More;
> +use Time::HiRes;
> +
> +use PVE::JSONSchema;
> +use PVE::Tools;
> +
> +use PVE::GuestIdentity;
> +
> +subtest 'generation with fixed random bytes and time' => sub {
> +    my $random_bytes = [];
> +    my $time_ms = 1_700_000_000_123;
> +
> +    my $identity_module = Test::MockModule->new('PVE::GuestIdentity');
> +    $identity_module->redefine(
> +        __random_bytes => sub {
> +            my ($len) = @_;
> +            my $bytes = shift(@$random_bytes) // die "test error: no random bytes left\n";
> +            die "test error: requested $len random bytes\n" if length($bytes) != $len;
> +            return $bytes;
> +        },
> +        __time_ms => sub { return $time_ms; },
> +    );
> +
> +    # the first 100 bits of the given bytes in lowercase RFC 4648 base32, which would encode the 4
> +    # bits left over as a 21st character, followed by padding
> +    my $vectors = [
> +        ["\x00" x 13, 'a' x 20],
> +        ["\xff" x 13, '7' x 20],
> +        ['0123456789abc', 'gaytemzugu3doobzmfrg'],
> +        [pack('C*', 0 .. 12), 'aaaqeayeaudaocajbifq'],
> +        [("\x00" x 12) . "\x0f", 'a' x 20],
> +    ];
> +
> +    for my $vector (@$vectors) {
> +        my ($bytes, $uid) = @$vector;
> +        $random_bytes = [$bytes];
> +        is_deeply(
> +            PVE::GuestIdentity::new_identity(),
> +            { uid => $uid, rtime => $time_ms },
> +            "encodes " . unpack('H*', $bytes),
> +        );
> +    }
> +
> +    # every symbol is as likely at each position, as each character gets 5 bits of its own
> +    my $alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
> +    my $mismatches = 0;
> +    for my $position (0 .. 19) {
> +        for my $value (0 .. 31) {
> +            my $bits = '0' x 104;
> +            substr($bits, 5 * $position, 5) = sprintf('%05b', $value);
> +            $random_bytes = [pack('B104', $bits)];
> +            my $expected = 'a' x 20;
> +            substr($expected, $position, 1) = substr($alphabet, $value, 1);
> +            $mismatches++ if PVE::GuestIdentity::new_identity()->{uid} ne $expected;
> +        }
> +    }
> +    is($mismatches, 0, 'each character encodes 5 bits of its own');
> +
> +    $random_bytes = [];
> +    is_deeply(
> +        PVE::GuestIdentity::new_identity('gaytemzugu3doobzmfrg'),
> +        { uid => 'gaytemzugu3doobzmfrg', rtime => $time_ms },
> +        'given uid is used',
> +    );
> +    eval { PVE::GuestIdentity::new_identity('GAYTEMZUGU3DOOBZMFRG') };
> +    like($@, qr/invalid guest identity uid/, 'invalid given uid is rejected');
> +};
> +
> +subtest 'generation' => sub {
> +    my $first = PVE::GuestIdentity::new_identity();
> +    my $second = PVE::GuestIdentity::new_identity();
> +    like($first->{uid}, qr/^[a-z2-7]{20}\z/, 'uid has the expected format');
> +    my @uids = map { PVE::GuestIdentity::new_identity()->{uid} } 1 .. 100;
> +    is_deeply([grep { !m/^[a-z2-7]{20}\z/ } @uids], [], 'uids have 20 characters, no padding');
> +    isnt($first->{uid}, $second->{uid}, 'uids differ');
> +
> +    my $before = int(Time::HiRes::time() * 1000);
> +    my $rtime = PVE::GuestIdentity::new_identity()->{rtime};
> +    my $after = int(Time::HiRes::time() * 1000) + 1;
> +    like($rtime, qr/^\d+\z/, 'rtime is an integer');
> +    ok($rtime >= $before && $rtime <= $after, 'rtime is the current time in milliseconds');
> +};
> +
> +subtest 'format properties' => sub {
> +    my $format = {
> +        ctime => { type => 'integer', optional => 1 },
> +        PVE::GuestIdentity::meta_format_properties()->%*,
> +    };
> +
> +    is_deeply(
> +        PVE::JSONSchema::parse_property_string(
> +            $format,
> +            'ctime=1700000000,rtime=1700000000123,uid=gaytemzugu3doobzmfrg',
> +        ),
> +        { ctime => 1700000000, rtime => 1700000000123, uid => 'gaytemzugu3doobzmfrg' },
> +        'meta string with identity parses with a merged format',
> +    );
> +
> +    for my $invalid (
> +        'uid=GAYTEMZUGU3DOOBZMFRG',
> +        'uid=gaytemzugu3doobzmfr',
> +        'uid=gaytemzugu3doobzmfrga',
> +        'uid=gaytemzugu3doobzmfr0',
> +        'uid=' . substr('gaytemzugu3doobzmfrg', 0, 16),
> +        'rtime=-1',
> +        'rtime=1.5',
> +        'rtime=1000000000000000',
> +    ) {
> +        eval { PVE::JSONSchema::parse_property_string($format, $invalid) };
> +        ok($@, "format rejects '$invalid'");
> +    }
> +
> +    my $copy = PVE::GuestIdentity::meta_format_properties();
> +    $copy->{uid}->{pattern} = '.*';
> +    isnt(
> +        PVE::GuestIdentity::meta_format_properties()->{uid}->{pattern},
> +        '.*',
> +        'callers get their own copy',
> +    );
> +};
> +
> +subtest 'parse identity' => sub {
> +    my $uid = 'gaytemzugu3doobzmfrg';
> +    my $tests = [
> +        [undef, undef, 'no meta'],
> +        ['', undef, 'empty meta'],
> +        ['ctime=1700000000', undef, 'meta without identity'],
> +        [
> +            "creation-qemu=10.1.2,ctime=1700000000,rtime=123,uid=$uid",
> +            { uid => $uid, rtime => 123 },
> +            'identity next to other members',
> +        ],
> +        [
> +            "future=a b,uid=$uid,other,rtime=0",
> +            { uid => $uid, rtime => 0 },
> +            'unknown members and odd parts are ignored',
> +        ],
> +        ["rtime=123,uid=$uid", { uid => $uid, rtime => 123 }, 'identity only'],
> +        ["uid=$uid", { uid => $uid, rtime => undef }, 'missing rtime'],
> +        ["uid=$uid,rtime=12a", { uid => $uid, rtime => undef }, 'invalid rtime'],
> +        ["uid=$uid,rtime=-5", { uid => $uid, rtime => undef }, 'negative rtime'],
> +        [
> +            "uid=$uid,rtime=999999999999999",
> +            { uid => $uid, rtime => 999999999999999 },
> +            'maximum rtime',
> +        ],
> +        ["uid=$uid,rtime=1000000000000000", { uid => $uid, rtime => undef }, 'too large rtime'],
> +        [
> +            "uid=$uid,rtime=\x{0661}\x{0662}",
> +            { uid => $uid, rtime => undef },
> +            'non-ASCII digits',
> +        ],
> +        ["uid=$uid,rtime=1,rtime=2", { uid => $uid, rtime => undef }, 'duplicate rtime'],
> +        ['rtime=123', undef, 'rtime without uid'],
> +        ["uid=$uid,uid=$uid,rtime=1", undef, 'duplicate uid'],
> +        ['uid=GAYTEMZUGU3DOOBZMFRG,rtime=1', undef, 'uppercase uid'],
> +        ['uid=gaytemzugu3doobzmfr,rtime=1', undef, 'short uid'],
> +        ['uid=gaytemzugu3doobzmfrga,rtime=1', undef, 'long uid'],
> +        ['uid=' . substr($uid, 0, 16) . ',rtime=1', undef, '16-character uid'],
> +        ['uid=gaytemzugu3doobzmfr1,rtime=1', undef, 'uid outside of the alphabet'],
> +        ["uid= $uid,rtime=1", undef, 'uid with whitespace'],
> +    ];
> +
> +    for my $test (@$tests) {
> +        my ($meta, $expected, $name) = @$test;
> +        is_deeply(PVE::GuestIdentity::parse_identity($meta), $expected, $name);
> +    }
> +};
> +
> +subtest 'merge identity' => sub {
> +    my $identity = { uid => 'gaytemzugu3doobzmfrg', rtime => 1700000000123 };
> +    my $members = 'rtime=1700000000123,uid=gaytemzugu3doobzmfrg';
> +    my $tests = [
> +        [undef, $members, 'no meta'],
> +        ['', $members, 'empty meta'],
> +        [
> +            'creation-qemu=10.1.2,ctime=1700000000',
> +            "creation-qemu=10.1.2,ctime=1700000000,$members",
> +            'other members are kept',
> +        ],
> +        [
> +            'ctime=1,rtime=5,uid=aaaaaaaaaaaaaaaaaaaa',
> +            "ctime=1,$members",
> +            'existing identity is replaced',
> +        ],
> +        [
> +            'uid=bogus,zz-future=x,rtime=1,uid=aaaaaaaaaaaaaaaaaaaa,ctime=1',
> +            "ctime=1,$members,zz-future=x",
> +            'invalid and duplicate identity members are dropped, unknown members kept',
> +        ],
> +        ['plain,ctime=1', "plain,ctime=1,$members", 'parts without key stay first'],
> +    ];
> +
> +    for my $test (@$tests) {
> +        my ($meta, $expected, $name) = @$test;
> +        my $merged = PVE::GuestIdentity::merge_identity($meta, $identity);
> +        is($merged, $expected, $name);
> +        is_deeply(PVE::GuestIdentity::parse_identity($merged), $identity, "$name, parses back");
> +    }
> +
> +    for my $invalid (
> +        { uid => 'GAYTEMZUGU3DOOBZMFRG', rtime => 1 },
> +        { uid => 'gaytemzugu3doobzmfrg', rtime => undef },
> +        { uid => 'gaytemzugu3doobzmfrg', rtime => 'now' },
> +        { uid => 'gaytemzugu3doobzmfrg', rtime => '1000000000000000' },
> +        { uid => 'gaytemzugu3doobzmfrg,ctime=1', rtime => 1 },
> +        { rtime => 1 },
> +    ) {
> +        eval { PVE::GuestIdentity::merge_identity('ctime=1', $invalid) };
> +        ok($@, "invalid identity is rejected");
> +    }
> +};
> +
> +subtest 'node version check' => sub {
> +    my $min = PVE::GuestIdentity::MIN_PVE_MANAGER_VERSION;
> +    like($min, qr/^[0-9]+\.[0-9]+\.[0-9]+\z/, 'minimum version is a version string');
> +    my ($major, $minor, $release) = split(/\./, $min);
> +
> +    my $versions = {
> +        current => "$major.$minor.$release",
> +        newer => "$major." . ($minor + 1) . ".0",
> +        older => "$major.$minor." . ($release - 1),
> +        invalid => 'invalid',
> +    };
> +
> +    my $cluster_module = Test::MockModule->new('PVE::Cluster');
> +    $cluster_module->mock(
> +        get_node_pvecfg_version => sub {
> +            my ($node) = @_;
> +            die "malformed version info\n" if $node eq 'malformed';
> +            return $versions->{$node};
> +        },
> +        node_pvecfg_version_at_least => sub {
> +            my ($node, @min) = @_;
> +            my $version = PVE::Cluster::get_node_pvecfg_version($node);
> +            return $version && PVE::Tools::pvecfg_min_version($version, @min);
> +        },
> +    );
> +
> +    for my $node (qw(current newer)) {
> +        eval { PVE::GuestIdentity::assert_node_supports_identity($node) };
> +        is($@, '', "node with version '$versions->{$node}' is supported");
> +        my $unsupported = PVE::GuestIdentity::node_identity_unsupported($node);
> +        is($unsupported, undef, "no reason for '$node'");
> +    }
> +
> +    for my $node (qw(older invalid missing malformed)) {
> +        eval { PVE::GuestIdentity::assert_node_supports_identity($node) };
> +        like($@, qr/node '$node'/, "node '$node' is refused");
> +    }
> +
> +    for my $node (qw(older invalid)) {
> +        is_deeply(
> +            PVE::GuestIdentity::node_identity_unsupported($node),
> +            { version => $versions->{$node}, 'required-version' => $min },
> +            "reason for '$node' has both versions",
> +        );
> +        eval { PVE::GuestIdentity::assert_node_supports_identity($node) };
> +        is(
> +            $@,
> +            "node '$node' runs Proxmox VE $versions->{$node}, keeping the guest identity requires"
> +                . " $min or newer - upgrade the node first\n",
> +            "refusal of '$node' names both versions",
> +        );
> +    }
> +
> +    for my $node (qw(missing malformed)) {
> +        is_deeply(
> +            PVE::GuestIdentity::node_identity_unsupported($node),
> +            { 'required-version' => $min },
> +            "reason for '$node' has only the required version",
> +        );
> +        eval { PVE::GuestIdentity::assert_node_supports_identity($node) };
> +        is(
> +            $@,
> +            "node '$node' does not report its Proxmox VE version, so it is unknown whether the"
> +                . " node keeps the guest identity\n",
> +            "refusal of '$node' says why",
> +        );
> +    }
> +};
> +
> +done_testing();





^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH guest-common 09/34] abstract config: assign a guest identity and keep it on config writes
  2026-11-16  0:46 ` [PATCH guest-common 09/34] abstract config: assign a guest identity and keep it on config writes Thomas Lamprecht
@ 2026-11-17 10:47   ` Dominik Csapak
  2026-11-17 12:47     ` Dominik Csapak
  0 siblings, 1 reply; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 10:47 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel

some comments inline

On 11/16/26 1:50 AM, Thomas Lamprecht wrote:
> With identities enabled for a guest type, every config write keeps the
> identity that the guest already has, regardless of the identity in the
> written config, and assigns a new one if the guest has none. This
> covers new guests and guests from older versions without identity
> handling in every operation. A stale config, a config copied from a
> clone source, or a snapshot rollback can neither change nor duplicate
> an identity that way. Taking over the uid of a backup needs a separate
> check that no other guest in the cluster uses it.
> 
> Read the existing identity directly from the cluster filesystem, as
> the parsed config in the cache can be outdated, and abort the write on
> read errors. A failed IPC connection can look like a missing or empty
> file, so verify such a result against the mounted filesystem before
> assigning an identity. A file that cannot be checked does not count as
> missing.
> 
> Some writers, including the container post-stop hook, do not hold the
> guest config lock. Read the identity and write the config under a short
> local lock, so that concurrent writers cannot assign different
> identities.
> 
> Guest types have to enable this explicitly: older qemu-server versions
> validate 'meta' strictly on writes and would reject a config with the
> identity members.
> 
> Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
> ---
>   src/PVE/AbstractConfig.pm          | 111 ++++++-
>   src/tests/Makefile                 |   7 +-
>   src/tests/config-identity-tests.pl | 488 +++++++++++++++++++++++++++++
>   3 files changed, 603 insertions(+), 3 deletions(-)
>   create mode 100755 src/tests/config-identity-tests.pl
> 
> diff --git a/src/PVE/AbstractConfig.pm b/src/PVE/AbstractConfig.pm
> index 7bcae19..e78b8cc 100644
> --- a/src/PVE/AbstractConfig.pm
> +++ b/src/PVE/AbstractConfig.pm
> @@ -3,6 +3,8 @@ package PVE::AbstractConfig;
>   use strict;
>   use warnings;
>   
> +use Errno qw(ENOENT);
> +
>   use PVE::Cluster;
>   use PVE::INotify;
>   use PVE::JSONSchema;
> @@ -10,6 +12,7 @@ use PVE::Storage;
>   use PVE::Tools qw(lock_file lock_file_full);
>   
>   use PVE::GuestHelpers qw(typesafe_ne);
> +use PVE::GuestIdentity;
>   use PVE::ReplicationConfig;
>   use PVE::Replication;
>   
> @@ -61,13 +64,119 @@ sub load_config {
>       return $conf;
>   }
>   
> +# Guest identity, see PVE::GuestIdentity
> +
> +# Whether writing a config keeps the published guest identity, or assigns one if there is none,
> +# see write_config. Only enable it for a guest type whose config format accepts the identity
> +# members, as a strict parser would otherwise reject every written config.
> +sub __identity_enabled {
> +    my ($class) = @_;
> +
> +    return 0;
> +}
> +
> +# Returns the guest identity contained in the parsed config $conf, undef if there is none. Guest
> +# types can override this and __identity_set for a different representation of 'meta' in parsed
> +# configs, but the config file must have the identity in the top-level 'meta' property string, as
> +# that is where the published identity gets read from.
> +sub __identity_get {
> +    my ($class, $conf) = @_;
> +
> +    return PVE::GuestIdentity::parse_identity($conf->{meta});
> +}
> +
> +# Sets the guest identity $identity in the parsed config $conf, keeping everything else.
> +sub __identity_set {
> +    my ($class, $conf, $identity) = @_;
> +
> +    $conf->{meta} = PVE::GuestIdentity::merge_identity($conf->{meta}, $identity);
> +}
> +
> +# Returns the guest identity contained in the parsed config $conf, for example of a backup, undef
> +# if there is none.
> +sub get_identity {
> +    my ($class, $conf) = @_;
> +
> +    return $class->__identity_get($conf);
> +}
> +
> +# Runs $code with the local identity lock of $vmid held and returns its result. Every config write
> +# takes it, also ones without the guest config lock like hooks, so never take another lock while
> +# holding it. Tests can override it to run without access to the lock directory.

a why not simply take the (simple) guest config lock? AFAICS this is 
only taken in the write_config path where we need to have the lock anyway?




> +sub __identity_lock {
> +    my ($class, $vmid, $code, @param) = @_;
> +
> +    my $lockdir = $PVE::GuestHelpers::lockdir;
> +    mkdir $lockdir;
> +
> +    my $res = lock_file("$lockdir/pve-guest-identity-$vmid", 10, $code, @param);
> +    die $@ if $@;
> +
> +    return $res;
> +}
> +
> +# Returns undef if no config file exists for $vmid on this node, otherwise a hash with the identity
> +# published in its top-level section, undef if there is none. Reads the file directly, as the
> +# parsed configs in the file cache can be outdated. Dies on other read errors. Tests can override

how can parsed configs in the file cache be outdated? wouldn't that
break many other parts in the code if our config wouldn't be current?

> +# it to run without the cluster filesystem.
> +sub __identity_read_published {
> +    my ($class, $vmid) = @_;
> +
> +    my $raw = PVE::Cluster::get_config($class->cfs_config_path($vmid));
> +    if (!defined($raw) || $raw eq '') {
> +        # a failed connection to pmxcfs returns undef with errno left as it was, which can look
> +        # like a missing file (ENOENT) or an empty one (no error)
> +        my $path = $class->config_file($vmid);
> +        my $size = -s $path;
> +        # only a file known not to exist counts as missing, not one that cannot be checked
> +        die "unable to check config file '$path' for its guest identity - $!\n"
> +            if !defined($size) && $! != ENOENT;
> +        die "unable to read config file '$path' to check its guest identity\n"
> +            if defined($raw) ? $size : defined($size);
> +        return undef if !defined($raw);
> +    }
> +
> +    my $meta;
> +    for my $line (split(/\n/, $raw)) {
> +        last if $line =~ m/^\[/; # snapshot or other section
> +        $meta = $1 if $line =~ m/^meta:\s*(.*?)\s*$/;

this code implies the re could be multiple `meta: ` lines before
a snapshot or section, but AFAIK this is not the case.

so if $meta is defined we could skip reading the rest of the config?

> +    }
> +
> +    return { identity => PVE::GuestIdentity::parse_identity($meta) };
> +}
> +
>   # Generate and write config file for this VM/CT
> +#
> +# With guest identities enabled for the class, the identity published in the existing config file
> +# gets set in $conf, whatever $conf contains, or a new one if none is published. So a config write
> +# never changes a published identity.
>   sub write_config {
>       my ($class, $vmid, $conf) = @_;
>   
>       my $cfspath = $class->cfs_config_path($vmid);
>   
> -    PVE::Cluster::cfs_write_file($cfspath, $conf);
> +    if (!$class->__identity_enabled()) {
> +        PVE::Cluster::cfs_write_file($cfspath, $conf);
> +        return;
> +    }
> +
> +    $class->__identity_lock(
> +        $vmid,
> +        sub {
> +            my $published = $class->__identity_read_published($vmid);
> +            my $identity = $published && $published->{identity};
> +
> +            # a published uid without valid rtime can only come from a manual edit
> +            if (!$identity || !defined($identity->{rtime})) {

the check for rtime here can't ever work since $identity is a boolean?
i think it's mean to be `!defined($published->{rtime})` , no ?

> +                $identity = PVE::GuestIdentity::new_identity($identity && $identity->{uid});\

same here, the $identity->{uid} access can't work...

> +            }
> +
> +            $class->__identity_set($conf, $identity);
> +            PVE::Cluster::cfs_write_file($cfspath, $conf);
> +        },
> +    );
> +
> +    return;
>   }
>   
>   # Pending changes related
> diff --git a/src/tests/Makefile b/src/tests/Makefile
> index 129a57e..ae66694 100644
> --- a/src/tests/Makefile
> +++ b/src/tests/Makefile
> @@ -1,12 +1,15 @@
>   
>   all:
>   
> -.PHONY: check abstract-config guest-identity hookscript
> -check: abstract-config guest-identity hookscript
> +.PHONY: check abstract-config config-identity guest-identity hookscript
> +check: abstract-config config-identity guest-identity hookscript
>   
>   abstract-config: abstract-config-tests.pl
>   	perl -I.. ./abstract-config-tests.pl
>   
> +config-identity: config-identity-tests.pl
> +	perl -I.. ./config-identity-tests.pl
> +
>   guest-identity: guest-identity-tests.pl
>   	perl -I.. ./guest-identity-tests.pl
>   
> diff --git a/src/tests/config-identity-tests.pl b/src/tests/config-identity-tests.pl
> new file mode 100755
> index 0000000..92864ca
> --- /dev/null
> +++ b/src/tests/config-identity-tests.pl
> @@ -0,0 +1,488 @@
> +#!/usr/bin/perl
> +
> +use strict;
> +use warnings;
> +
> +use lib qw(..);
> +
> +use Fcntl qw(:flock);
> +use File::Path qw(make_path);
> +use File::Temp qw(tempdir);
> +use Storable qw(dclone);
> +use Test::MockModule;
> +use Test::More;
> +
> +use PVE::AbstractConfig;
> +use PVE::GuestHelpers;
> +use PVE::GuestIdentity;
> +
> +my $tmpdir = tempdir('config-identity-XXXXXX', DIR => '.', CLEANUP => 1);
> +$PVE::GuestHelpers::lockdir = "$tmpdir/lock";
> +
> +# guest config classes using a minimal config file format, see below
> +
> +package PVE::TestConfig {
> +    use base qw(PVE::AbstractConfig);
> +
> +    sub guest_type { return 'VM'; }
> +
> +    sub config_file_lock {
> +        my ($class, $vmid) = @_;
> +        return "$tmpdir/config-$vmid.lock";
> +    }
> +
> +    sub cfs_config_path {
> +        my ($class, $vmid, $node) = @_;
> +        return "nodes/local/qemu-server/$vmid.conf";
> +    }
> +
> +    # only checked for existence, the fake cluster filesystem below does not create it
> +    sub config_file {
> +        my ($class, $vmid, $node) = @_;
> +        return "$tmpdir/etc-pve/" . $class->cfs_config_path($vmid, $node);
> +    }
> +
> +    sub __identity_enabled { return 1; }
> +
> +    # just enough for snapshot rollbacks without volumes
> +    sub valid_volume_keys { return (); }
> +    sub __snapshot_check_running { return 0; }
> +    sub __snapshot_rollback_vm_stop { return; }
> +    sub __snapshot_rollback_get_unused { return []; }
> +}
> +
> +package PVE::TestConfig::CT {
> +    use base qw(PVE::TestConfig);
> +
> +    sub guest_type { return 'CT'; }
> +
> +    sub cfs_config_path {
> +        my ($class, $vmid, $node) = @_;
> +        return "nodes/local/lxc/$vmid.conf";
> +    }
> +}
> +
> +package PVE::TestConfig::NoIdentity {
> +    use base qw(PVE::TestConfig);
> +
> +    sub __identity_enabled { return 0; }
> +}
> +
> +# like the tests of a guest type that run without lock directory and cluster filesystem
> +package PVE::TestConfig::Seams {
> +    use base qw(PVE::TestConfig);
> +
> +    our $published = {};
> +
> +    sub __identity_lock {
> +        my ($class, $vmid, $code, @param) = @_;
> +        return $code->(@param);
> +    }
> +
> +    sub __identity_read_published {
> +        my ($class, $vmid) = @_;
> +        return $published->{$vmid};
> +    }
> +}
> +
> +package main;
> +
> +# fake cluster filesystem with raw config files, indexed by their cfs path, and a file cache that
> +# behaves like the one of PVE::Cluster: it only reads a config again after a write of this process,
> +# or after cfs_update noticed a newer version
> +
> +my $files = {};
> +my $versions = {};
> +my $version_counter = 0;
> +my $seen_versions = {};
> +my $cache = {};
> +
> +our $get_config_error;
> +our $check_identity_lock = 1;
> +
> +my $reads = 0;
> +my $writes = 0;
> +
> +sub parse_test_config {
> +    my ($raw) = @_;
> +
> +    my $conf = { snapshots => {} };
> +    my $section = $conf;
> +    for my $line (split(/\n/, $raw)) {
> +        next if $line =~ m/^\s*$/;
> +        if ($line =~ m/^\[([^\]]+)\]$/) {
> +            $section = $conf->{snapshots}->{$1} = {};
> +        } elsif ($line =~ m/^([a-z][a-z0-9_\-]*):\s*(.*?)\s*$/) {
> +            $section->{$1} = $2;
> +        } else {
> +            die "test error: unable to parse config line '$line'\n";
> +        }
> +    }
> +
> +    return $conf;
> +}
> +
> +sub write_test_config {
> +    my ($conf) = @_;
> +
> +    my $print_section = sub {
> +        my ($section) = @_;
> +        return join('',
> +            map { "$_: $section->{$_}\n" } grep { !ref($section->{$_}) } sort keys %$section);
> +    };
> +
> +    my $raw = $print_section->($conf);
> +    for my $snapname (sort keys(($conf->{snapshots} // {})->%*)) {
> +        $raw .= "\n[$snapname]\n" . $print_section->($conf->{snapshots}->{$snapname});
> +    }
> +
> +    return $raw;
> +}
> +
> +sub vmid_of_path {
> +    my ($path) = @_;
> +    return $path =~ m!/(\d+)\.conf$! ? $1 : die "test error: unexpected path '$path'\n";
> +}
> +
> +sub identity_lock_held {
> +    my ($vmid) = @_;
> +
> +    open(my $fh, '>>', "$PVE::GuestHelpers::lockdir/pve-guest-identity-$vmid") or return 0;
> +    my $free = flock($fh, LOCK_EX | LOCK_NB);
> +    close($fh);
> +
> +    return !$free;
> +}
> +
> +my $cluster_module = Test::MockModule->new('PVE::Cluster');
> +$cluster_module->redefine(
> +    cfs_update => sub {
> +        $seen_versions = { $versions->%* };
> +        return;
> +    },
> +    cfs_read_file => sub {
> +        my ($path) = @_;
> +        my $version = $seen_versions->{$path};
> +        my $entry = $cache->{$path};
> +        if (!$entry || !$entry->{version} || !$version || $entry->{version} != $version) {
> +            my $raw = $files->{$path};
> +            my $data = defined($raw) ? parse_test_config($raw) : undef;
> +            $entry = $cache->{$path} = { version => $version, data => $data };
> +        }
> +        return defined($entry->{data}) ? dclone($entry->{data}) : undef;
> +    },
> +    cfs_write_file => sub {
> +        my ($path, $conf) = @_;
> +        my $vmid = vmid_of_path($path);
> +        die "test error: config of $vmid written without identity lock\n"
> +            if $check_identity_lock && !identity_lock_held($vmid);
> +        $writes++;
> +        $files->{$path} = write_test_config($conf);
> +        $versions->{$path} = ++$version_counter;
> +        $cache->{$path}->{version} = undef if $cache->{$path};
> +    },
> +    get_config => sub {
> +        my ($path) = @_;
> +        my $vmid = vmid_of_path($path);
> +        die "test error: config of $vmid read without identity lock\n"
> +            if !identity_lock_held($vmid);
> +        die $get_config_error if $get_config_error;
> +        $reads++;
> +        return $files->{$path};
> +    },
> +);
> +
> +# deterministic identities: uids count up, the time is set by the tests
> +
> +my $uid_counter = 0;
> +my $now = 1_700_000_000_000;
> +
> +my $identity_module = Test::MockModule->new('PVE::GuestIdentity');
> +$identity_module->redefine(
> +    __random_bytes => sub {
> +        my ($len) = @_;
> +        return pack('N', ++$uid_counter) . ("\0" x ($len - 4));
> +    },
> +    __time_ms => sub { return $now; },
> +);
> +
> +my sub new_uid {
> +    return PVE::GuestIdentity::new_identity()->{uid};
> +}
> +
> +my sub file_of {
> +    my ($class, $vmid) = @_;
> +    return $files->{ $class->cfs_config_path($vmid) };
> +}
> +
> +my sub conf_of {
> +    my ($class, $vmid) = @_;
> +    my $raw = file_of($class, $vmid);
> +    return defined($raw) ? parse_test_config($raw) : undef;
> +}
> +
> +my sub identity_of {
> +    my ($class, $vmid) = @_;
> +    my $conf = conf_of($class, $vmid) or return undef;
> +    return PVE::GuestIdentity::parse_identity($conf->{meta});
> +}
> +
> +# write of another process, the file cache of this process does not notice it
> +my sub set_file {
> +    my ($class, $vmid, $raw) = @_;
> +    my $path = $class->cfs_config_path($vmid);
> +    $files->{$path} = $raw;
> +    $versions->{$path} = ++$version_counter;
> +}
> +
> +my $foreign_uid = new_uid();
> +
> +subtest 'disabled by default' => sub {
> +    ok(!PVE::AbstractConfig->__identity_enabled(), 'abstract config does not enable it');
> +
> +    local $check_identity_lock = 0;
> +    my $class = 'PVE::TestConfig::NoIdentity';
> +    my $reads_before = $reads;
> +
> +    my $res = [$class->write_config(100, { name => 'a' })];
> +    is(file_of($class, 100), "name: a\n", 'config without identity written as is');
> +    is_deeply($res, [], 'nothing is returned');
> +
> +    my $meta = "ctime=1,rtime=5,uid=$foreign_uid";
> +    $class->write_config(100, { name => 'a', meta => $meta });
> +    is(file_of($class, 100), "meta: $meta\nname: a\n", 'carried identity written as is');
> +
> +    is($reads, $reads_before, 'published identity is not read');
> +};
> +
> +subtest 'none published' => sub {
> +    my $class = 'PVE::TestConfig';
> +
> +    my $conf = { name => 'new' };
> +    my $res = [$class->write_config(101, $conf)];
> +    my $identity = identity_of($class, 101);
> +    ok($identity, 'new config gets an identity');
> +    is($identity->{rtime}, $now, 'rtime is the current time');
> +    is_deeply($class->get_identity($conf), $identity, 'identity is set in the written hash');
> +    is_deeply($res, [], 'nothing is returned');
> +
> +    # copied from a clone source, a snapshot, or a backup
> +    $class->write_config(102, { name => 'clone', meta => "ctime=7,rtime=5,uid=$foreign_uid" });
> +    $identity = identity_of($class, 102);
> +    isnt($identity->{uid}, $foreign_uid, 'carried identity is not published');
> +    is($identity->{rtime}, $now, 'carried rtime is not published');
> +    like(
> +        file_of($class, 102),
> +        qr/^meta: ctime=7,rtime=$now,uid=[a-z2-7]{20}$/m,
> +        'other members are kept',
> +    );
> +
> +    set_file($class, 103, "meta: ctime=1\nname: old\n");
> +    $class->write_config(103, conf_of($class, 103));
> +    $identity = identity_of($class, 103);
> +    ok($identity, 'existing config without identity gets one');
> +    like(file_of($class, 103), qr/^meta: ctime=1,rtime=$now,uid=/m, 'other members are kept');
> +
> +    set_file($class, 104, "name: old\n\n[snap]\nmeta: rtime=1,uid=$foreign_uid\n");
> +    $class->write_config(104, conf_of($class, 104));
> +    isnt(identity_of($class, 104)->{uid}, $foreign_uid, 'identity of a snapshot is ignored');
> +    like(
> +        file_of($class, 104),
> +        qr/^\[snap\]\nmeta: rtime=1,uid=$foreign_uid$/m,
> +        'snapshot keeps its copy',
> +    );
> +
> +    set_file($class, 105, '');
> +    $class->write_config(105, { name => 'empty' });
> +    ok(identity_of($class, 105), 'existing empty config gets an identity');
> +};
> +
> +subtest 'published identity wins' => sub {
> +    my $class = 'PVE::TestConfig';
> +
> +    $class->write_config(110, { name => 'a', meta => 'ctime=1' });
> +    my $published = identity_of($class, 110);
> +    my $stale = new_uid();
> +
> +    $now += 1000;
> +
> +    my $tests = [
> +        [{ name => 'b' }, 'missing identity'],
> +        [{ name => 'b', meta => 'ctime=1' }, 'missing identity members'],
> +        [{ name => 'b', meta => "ctime=1,rtime=5,uid=$stale" }, 'stale identity'],
> +        [{ name => 'b', meta => "ctime=1,rtime=$now,uid=$foreign_uid" }, 'foreign identity'],
> +        [{ name => 'b', meta => "ctime=1,rtime=5,uid=bogus" }, 'invalid identity'],
> +        [{ name => 'b', meta => "ctime=1,uid=$published->{uid}" }, 'identity without rtime'],
> +    ];
> +
> +    for my $test (@$tests) {
> +        my ($conf, $name) = @$test;
> +        my $other_members = $conf->{meta} && $conf->{meta} =~ m/ctime=1/;
> +
> +        $class->write_config(110, $conf);
> +        is_deeply(identity_of($class, 110), $published, "$name: published identity is kept");
> +        is_deeply($class->get_identity($conf), $published, "$name: hash has it too");
> +        like(file_of($class, 110), qr/^meta: ctime=1,/m, "$name: other members are kept")
> +            if $other_members;
> +    }
> +
> +    set_file($class, 111, "meta: ctime=1,uid=$stale\nname: old\n");
> +    $class->write_config(111, conf_of($class, 111));
> +    is_deeply(
> +        identity_of($class, 111),
> +        { uid => $stale, rtime => $now },
> +        'published uid without rtime is kept and gets the current time',
> +    );
> +
> +    my ($first, $last) = (new_uid(), new_uid());
> +    set_file($class, 112, "meta: rtime=1,uid=$first\nname: x\nmeta: rtime=2,uid=$last\n");
> +    $class->write_config(112, { name => 'y' });
> +    is_deeply(
> +        identity_of($class, 112),
> +        { uid => $last, rtime => 2 },
> +        'last top-level meta line counts, like for the config parsers',
> +    );
> +};
> +
> +subtest 'read and write under identity lock' => sub {
> +    my $class = 'PVE::TestConfig';
> +
> +    # the cluster filesystem mocks die without the lock, the lock is gone afterwards
> +    $class->write_config(120, { name => 'a' });
> +    ok(identity_of($class, 120), 'written');
> +    ok(!identity_lock_held(120), 'lock is released');
> +
> +    $class->lock_config(120, sub { $class->write_config(120, conf_of($class, 120)) });
> +    ok(!identity_lock_held(120), 'lock is released when nested in config lock');
> +};
> +
> +subtest 'read errors are fatal' => sub {
> +    my $class = 'PVE::TestConfig';
> +
> +    $class->write_config(130, { name => 'a' });
> +    my $raw = file_of($class, 130);
> +
> +    {
> +        local $get_config_error = "Connection refused\n";
> +        eval { $class->write_config(130, { name => 'b' }) };
> +        is($@, "Connection refused\n", 'write dies');
> +        is(file_of($class, 130), $raw, 'config is unchanged');
> +
> +        eval { $class->write_config(131, { name => 'b' }) };
> +        is($@, "Connection refused\n", 'write of new config dies');
> +        ok(!defined(file_of($class, 131)), 'config is not written');
> +    }
> +
> +    # the read reports a missing file, but the mounted filesystem has it
> +    my $path = $class->config_file(132);
> +    make_path($path =~ s!/[^/]+$!!r);
> +    open(my $fh, '>', $path) or die "unable to create '$path' - $!\n";
> +    close($fh);
> +    eval { $class->write_config(132, { name => 'b' }) };
> +    like(
> +        $@,
> +        qr/^unable to read config file '\Q$path\E'/,
> +        'inconsistent missing file is an error',
> +    );
> +    ok(!defined(file_of($class, 132)), 'config is not written');
> +
> +    # the read reports an empty file, but the mounted filesystem has content
> +    set_file($class, 133, '');
> +    $path = $class->config_file(133);
> +    open($fh, '>', $path) or die "unable to create '$path' - $!\n";
> +    print $fh "name: a\n";
> +    close($fh);
> +    eval { $class->write_config(133, { name => 'b' }) };
> +    like(
> +        $@,
> +        qr/^unable to read config file '\Q$path\E'/,
> +        'inconsistent empty file is an error',
> +    );
> +    is(file_of($class, 133), '', 'config is not written');
> +
> +    # empty for both, a config without identity
> +    set_file($class, 134, '');
> +    $path = $class->config_file(134);
> +    open($fh, '>', $path) or die "unable to create '$path' - $!\n";
> +    close($fh);
> +    $class->write_config(134, { name => 'b' });
> +    ok(identity_of($class, 134), 'empty file gets an identity');
> +
> +    # the mounted filesystem cannot be checked either, like while pmxcfs restarts
> +    my $not_a_dir = "$tmpdir/not-a-dir";
> +    open($fh, '>', $not_a_dir) or die "unable to create '$not_a_dir' - $!\n";
> +    close($fh);
> +    my $config_module = Test::MockModule->new('PVE::TestConfig', no_auto => 1);
> +    $config_module->redefine(config_file => sub { return "$not_a_dir/$_[1].conf"; });
> +
> +    eval { $class->write_config(135, { name => 'b' }) };
> +    like(
> +        $@,
> +        qr/^unable to check config file '\Q$not_a_dir\E\/135\.conf' for its guest identity - /,
> +        'missing file that cannot be checked is an error',
> +    );
> +    ok(!defined(file_of($class, 135)), 'config is not written');
> +
> +    set_file($class, 136, '');
> +    eval { $class->write_config(136, { name => 'b' }) };
> +    like(
> +        $@,
> +        qr/^unable to check config file '\Q$not_a_dir\E\/136\.conf' for its guest identity - /,
> +        'empty file that cannot be checked is an error',
> +    );
> +    is(file_of($class, 136), '', 'config is not written');
> +};
> +
> +subtest 'snapshot rollback' => sub {
> +    my $class = 'PVE::TestConfig';
> +
> +    my $storage_module = Test::MockModule->new('PVE::Storage');
> +    $storage_module->redefine(config => sub { return {}; });
> +    my $replication_module = Test::MockModule->new('PVE::ReplicationConfig');
> +    $replication_module->redefine(
> +        new => sub { return bless({}, 'PVE::ReplicationConfig'); },
> +        check_for_existing_jobs => sub { return 0; },
> +    );
> +
> +    $class->write_config(140, { name => 'current', meta => 'ctime=2' });
> +    my $published = identity_of($class, 140);
> +
> +    my $conf = conf_of($class, 140);
> +    $conf->{snapshots}->{old} = { name => 'old', meta => "ctime=1,rtime=5,uid=$foreign_uid" };
> +    $conf->{snapshots}->{none} = { name => 'none' };
> +    $class->write_config(140, $conf);
> +
> +    $now += 1000;
> +
> +    for my $snapname (qw(old none)) {
> +        $class->snapshot_rollback(140, $snapname);
> +        $conf = conf_of($class, 140);
> +        is($conf->{name}, $snapname, "rolled back to '$snapname'");
> +        is_deeply(identity_of($class, 140), $published,
> +            "'$snapname': current identity is kept");
> +    }
> +    is(
> +        $conf->{snapshots}->{old}->{meta},
> +        "ctime=1,rtime=5,uid=$foreign_uid",
> +        'snapshot is unchanged',
> +    );
> +};
> +
> +subtest 'overridden lock and published identity read' => sub {
> +    my $class = 'PVE::TestConfig::Seams';
> +    local $check_identity_lock = 0;
> +    my $reads_before = $reads;
> +
> +    $class->write_config(160, { name => 'a', meta => "rtime=5,uid=$foreign_uid" });
> +    my $identity = identity_of($class, 160);
> +    isnt($identity->{uid}, $foreign_uid, 'nothing published: new identity');
> +
> +    local $PVE::TestConfig::Seams::published->{161} = { identity => $identity };
> +    $class->write_config(161, { name => 'b' });
> +    is_deeply(identity_of($class, 161), $identity, 'published identity is kept');
> +
> +    is($reads, $reads_before, 'cluster filesystem is not read');
> +    ok(!-e "$PVE::GuestHelpers::lockdir/pve-guest-identity-160", 'no lock file is used');
> +};
> +
> +done_testing();





^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID
  2026-11-17 10:47 ` [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Dominik Csapak
@ 2026-11-17 11:29   ` Thomas Lamprecht
  2026-11-17 11:55     ` Dominik Csapak
  0 siblings, 1 reply; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-17 11:29 UTC (permalink / raw)
  To: Dominik Csapak, pve-devel

Am 17.11.26 um 11:47 schrieb Dominik Csapak:
> I started reviewing this series and wanted to give some early feedback on the
> overall approach. More in depth code review see the individual patches (might
> take a bit going through every patch)

thank you for taking a look, appreciated!

> Note that i might have overlooked something. If so, please
> do tell me.
>
> My high level feedback:
>
> Cluster IDs:
>
> Is there a particular reason why 100bit + base32?

Yes, they are much shorter serialized (20 chars) and have enough entropy
to make them more than good enough with head room while not getting
larger than needed.

> I couldn't find a rationale for the choice (did i overlook it?)

No, v1 only states the format (module comment in PVE::GuestIdentity,
commit messages, docs), not really the reasoning/rational behind it.
I'll expand on that for a v2 (or on applying) and will add a few
sentences to the cover letter too, as it certainly is something one can
wonder about.

> and I think using something 'industry standard' like a
> UUIDv7 would be a better choice? I'ts just 28 bit more (
> with a bit less randomness) but with a time stamp included and this
> should make each cluster uniquely identifiable too.

While I thought earlier about using snowflake or some other timestamp
influenced uid, they are not ideal here as they do not relate to
anything over the lifetime of a guest w.r.t. restores and such.

> If we want to stay on base32, maybe 80 or 120 bit is a better choice,

I had it at 80 bits, but that is borderline w.r.t. hundreds of billions
of entities and the birthday problem, as we're getting near actual digit
percentages then (1 % chance of a clash at ~150 billion IDs). 100 bits
takes that boundary between practically impossible and a real chance of
clash in the hundreds of trillion range (1 % at ~160 trillion), which
seemed good enough for me.

> since we then don't have to use half a byte (100bit => 12.5 byte)
> and still provide enough randomness.

Base32 has 5 bit per character, so 100 bits are always 20 chars without
padding, that I found nice.

> VM UIDs:
>
> Same question about the rationale behind the format, but with one
> change: the 'registering' time is already recorded in
> the meta object (as ctime), no? so providing an additional separate

ctime is creation time, which is the first creation ever. Registration
time is something else, it's the time the guest got its identity in this
cluster.

E.g. ctime will always be kept as is for a restore to a new VMID. The
uid changes if unique is set or if another guest in the cluster
already has it (e.g. the original still exists), but otherwise stays
the same. The registration time is regenerated in any case – making
the combination of rtime and uid (and cluster ID) unique in practice.
This comes from the model that backup providers use and even if a bit
odd at first it works well for all cases (if this series here
implements it right that is...).

That then allows one to tell apart e.g.:
- Same uid, changed rtime: the guest was registered again, for example
  destroyed and restored, or moved in from another cluster. A tool can
  then tell this from an "untouched" guest.
- Same uid in two clusters, which can happen after a remote migration
  that keeps the source, or a restore elsewhere. The uid together with
  the cluster ID and rtime still tells the instances apart.

I tried hard to do all that's needed to cover all bases but only really
that what's needed here. Ideally we do not touch this ever again from
a principles POV (knocks wood).

> timestamp seems weird to me. Also using UUIDv7 here
> would include a timestamp too and also be more 'industry standard'
> while only using 1 byte extra (36 vs 20 + 15). Though
no v7 for these things for the same reason, it's rather confusing
then. The timestamp of a v7 is fixed when the ID gets generated, while
here the uid must stay the same over restores and remote migrations
and the registration time must change then, so the two cannot be one
value. uid *must* be random, that's a core property and ensures it's
never taken for anything that it really isn't.

FWIW, my format allows to still map all uids into standard uuidv8,
so we're not locked in, but I do not want to use them and their
various versions here, simple random nonce that is formatted such
to be easy to handle (just alphanumerical) and still reasonably short.
That's my core requirement here. I.e., yes uuid might be wide spread,
but there to many tried to hard to add additional meaning to what should
be just a simple random nonce like this use case here.

> we probably would save some space by not having two properties in
> the meta object.

see above, required.

> UID adoption/checks:
>
> The cluster wide check is necessary, i get it. Handling

It's only needed when a guest takes over an existing uid, so once at
the end of a restore or of an incoming remote migration. Without it,
restoring the same backup to two VMIDs, or to a new VMID while the
original still exists, would give two guests with the same uid in one
cluster. Newly generated uids (create, clone, first write of an
existing guest after the upgrade) take no cluster lock and do no
lookup, the randomness is enough there.

> it with a cluster lock + reading the cofnig
> could make that lookup a bottleneck in big and dynamic clusters?
> Or did i misunderstood how we get the meta config out?

The lookup does not read config files one by one, it's a single IPC
call to pmxcfs that collects the 'meta' property from its in-memory
configs, i.e. the same call /cluster/resources already does on every
request for lock and tags. The lock is held for that call plus one
config write. So I don't expect this to become a bottleneck, and once
we have pmxcfs in rust with types for such guest configs we can do
this there on a nice abstraction level while still being really fast.

> Alternatively we could have that lookup in pmxcfs itself and
> replicate it like rrd, etc.? having a uuid saved as
> a 128bit number (16byte) would mean

no, this must IMO not be a sidecar or saved out of band, coupling it
directly to the guest config, the core entity that makes out a guest,
is IMO crucial to get a safe design. The lookup already happens in
pmxcfs as described above, just without a second copy of the data
that could get out of sync with the configs.

> 160k for 10000 guests
> 16M for 1000000 guests
>
> which looks reasonable to me?
> (we already have to have much more data in pmxcfs
> with that many guests...)

Probably not needed, but we can optimize the basic approach here if
needed (special IPC call for check+lock), but that's basically an
implementation detail that won't change the overall design IMO.




^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID
  2026-11-17 11:29   ` Thomas Lamprecht
@ 2026-11-17 11:55     ` Dominik Csapak
  2026-11-17 12:47       ` Thomas Lamprecht
  0 siblings, 1 reply; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 11:55 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel



On 11/17/26 12:29 PM, Thomas Lamprecht wrote:
> Am 17.11.26 um 11:47 schrieb Dominik Csapak:
>> I started reviewing this series and wanted to give some early feedback on the
>> overall approach. More in depth code review see the individual patches (might
>> take a bit going through every patch)
> 
> thank you for taking a look, appreciated!
> 
>> Note that i might have overlooked something. If so, please
>> do tell me.
>>
>> My high level feedback:
>>
>> Cluster IDs:
>>
>> Is there a particular reason why 100bit + base32?
> 
> Yes, they are much shorter serialized (20 chars) and have enough entropy
> to make them more than good enough with head room while not getting
> larger than needed.
> 
>> I couldn't find a rationale for the choice (did i overlook it?)
> 
> No, v1 only states the format (module comment in PVE::GuestIdentity,
> commit messages, docs), not really the reasoning/rational behind it.
> I'll expand on that for a v2 (or on applying) and will add a few
> sentences to the cover letter too, as it certainly is something one can
> wonder about.
> 
>> and I think using something 'industry standard' like a
>> UUIDv7 would be a better choice? I'ts just 28 bit more (
>> with a bit less randomness) but with a time stamp included and this
>> should make each cluster uniquely identifiable too.
> 
> While I thought earlier about using snowflake or some other timestamp
> influenced uid, they are not ideal here as they do not relate to
> anything over the lifetime of a guest w.r.t. restores and such.
> 
>> If we want to stay on base32, maybe 80 or 120 bit is a better choice,
> 
> I had it at 80 bits, but that is borderline w.r.t. hundreds of billions
> of entities and the birthday problem, as we're getting near actual digit
> percentages then (1 % chance of a clash at ~150 billion IDs). 100 bits
> takes that boundary between practically impossible and a real chance of
> clash in the hundreds of trillion range (1 % at ~160 trillion), which
> seemed good enough for me.

but this is about the cluster id, surely there aren't billions of
clusters/nodes ? they also don't have to be globally unique
in practice, just for one provider/customer/etc.

> 
>> since we then don't have to use half a byte (100bit => 12.5 byte)
>> and still provide enough randomness.
> 
> Base32 has 5 bit per character, so 100 bits are always 20 chars without
> padding, that I found nice.

yes i meant the 'raw size' and basically always discarding half a byte
of randomness, but sure.

> 
>> VM UIDs:
>>
>> Same question about the rationale behind the format, but with one
>> change: the 'registering' time is already recorded in
>> the meta object (as ctime), no? so providing an additional separate
> 
> ctime is creation time, which is the first creation ever. Registration
> time is something else, it's the time the guest got its identity in this
> cluster.
> 
> E.g. ctime will always be kept as is for a restore to a new VMID. The
> uid changes if unique is set or if another guest in the cluster
> already has it (e.g. the original still exists), but otherwise stays
> the same. The registration time is regenerated in any case – making
> the combination of rtime and uid (and cluster ID) unique in practice.
> This comes from the model that backup providers use and even if a bit
> odd at first it works well for all cases (if this series here
> implements it right that is...).
> 
> That then allows one to tell apart e.g.:
> - Same uid, changed rtime: the guest was registered again, for example
>    destroyed and restored, or moved in from another cluster. A tool can
>    then tell this from an "untouched" guest.

but this could also be detectable via ctime (except if we don't want
to touch that on restore/migration ofc)

> - Same uid in two clusters, which can happen after a remote migration
>    that keeps the source, or a restore elsewhere. The uid together with
>    the cluster ID and rtime still tells the instances apart.

for this the rtime is not needed though? uid + clusterid should
be enough? (since same uid in one cluster can't happen)

> 
> I tried hard to do all that's needed to cover all bases but only really
> that what's needed here. Ideally we do not touch this ever again from
> a principles POV (knocks wood).
> 

but fair, having a separate rtime can make sense i guess. and with
that having a time encoded in the 'uuid' makes less sense, got it.

>> timestamp seems weird to me. Also using UUIDv7 here
>> would include a timestamp too and also be more 'industry standard'
>> while only using 1 byte extra (36 vs 20 + 15). Though
> no v7 for these things for the same reason, it's rather confusing
> then. The timestamp of a v7 is fixed when the ID gets generated, while
> here the uid must stay the same over restores and remote migrations
> and the registration time must change then, so the two cannot be one
> value. uid *must* be random, that's a core property and ensures it's
> never taken for anything that it really isn't.
> 
> FWIW, my format allows to still map all uids into standard uuidv8,
> so we're not locked in, but I do not want to use them and their
> various versions here, simple random nonce that is formatted such
> to be easy to handle (just alphanumerical) and still reasonably short.
> That's my core requirement here. I.e., yes uuid might be wide spread,
> but there to many tried to hard to add additional meaning to what should
> be just a simple random nonce like this use case here.

makes sense, though i think having 20 vs 36 bytes in a config
that is already ~500 bytes by default wouldn't make much difference IMO.
(also we already have at least 2 uuids in the default config, so
there would be precedent to using that format)

we could also already opt to use a custom uuid format with the
rtime encoded instead of having a separate property, but
that is probably more pain that having it separate...

> 
>> we probably would save some space by not having two properties in
>> the meta object.
> 
> see above, required.
> 
>> UID adoption/checks:
>>
>> The cluster wide check is necessary, i get it. Handling
> 
> It's only needed when a guest takes over an existing uid, so once at
> the end of a restore or of an incoming remote migration. Without it,
> restoring the same backup to two VMIDs, or to a new VMID while the
> original still exists, would give two guests with the same uid in one
> cluster. Newly generated uids (create, clone, first write of an
> existing guest after the upgrade) take no cluster lock and do no
> lookup, the randomness is enough there.

it's also necessary on clone and creation though? otherwise we can't
be sure the random value is not in use? (unlikely but still)

if you argue about billions of clusters/nodes for 100bit randomness,
then i think arguing with a much higher number of vms is fair?

> 
>> it with a cluster lock + reading the cofnig
>> could make that lookup a bottleneck in big and dynamic clusters?
>> Or did i misunderstood how we get the meta config out?
> 
> The lookup does not read config files one by one, it's a single IPC
> call to pmxcfs that collects the 'meta' property from its in-memory
> configs, i.e. the same call /cluster/resources already does on every
> request for lock and tags. The lock is held for that call plus one
> config write. So I don't expect this to become a bottleneck, and once
> we have pmxcfs in rust with types for such guest configs we can do
> this there on a nice abstraction level while still being really fast.

ok sorry must have missed that or not yet read

> 
>> Alternatively we could have that lookup in pmxcfs itself and
>> replicate it like rrd, etc.? having a uuid saved as
>> a 128bit number (16byte) would mean
> 
> no, this must IMO not be a sidecar or saved out of band, coupling it
> directly to the guest config, the core entity that makes out a guest,
> is IMO crucial to get a safe design. The lookup already happens in
> pmxcfs as described above, just without a second copy of the data
> that could get out of sync with the configs.
> 
>> 160k for 10000 guests
>> 16M for 1000000 guests
>>
>> which looks reasonable to me?
>> (we already have to have much more data in pmxcfs
>> with that many guests...)
> 
> Probably not needed, but we can optimize the basic approach here if
> needed (special IPC call for check+lock), but that's basically an
> implementation detail that won't change the overall design IMO.

if the overall reading isn't happening in perl i don't think
we need anything specialized...





^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID
  2026-11-17 11:55     ` Dominik Csapak
@ 2026-11-17 12:47       ` Thomas Lamprecht
  2026-11-17 13:54         ` Dominik Csapak
  0 siblings, 1 reply; 49+ messages in thread
From: Thomas Lamprecht @ 2026-11-17 12:47 UTC (permalink / raw)
  To: Dominik Csapak, pve-devel

Am 17.11.26 um 12:55 schrieb Dominik Csapak:
> On 11/17/26 12:29 PM, Thomas Lamprecht wrote:
>> Am 17.11.26 um 11:47 schrieb Dominik Csapak:
>> I had it at 80 bits, but that is borderline w.r.t. hundreds of billions
>> of entities and the birthday problem, as we're getting near actual digit
>> percentages then (1 % chance of a clash at ~150 billion IDs). 100 bits
>> takes that boundary between practically impossible and a real chance of
>> clash in the hundreds of trillion range (1 % at ~160 trillion), which
>> seemed good enough for me.
> 
> but this is about the cluster id, surely there aren't billions of
> clusters/nodes ?

I want to use the same for clusters and guests, what benefit do I
have in doing that differently? 

> They also don't have to be globally unique in practice, just for one
> provider/customer/etc.

They do, else reality catches up with you fast, companies get bought
and their infra merged, cluster can move from providers (e.g., ceph
moved their whole CI infra from a RH datacenter to an IBM one with
some big trucks about a year ago), PDM can connect all of them. Really
not sure what you're trying to recommend here? Why make these edge
cases harder for anyone that has the bad luck handling them, what's
the benefit.

>>> since we then don't have to use half a byte (100bit => 12.5 byte)
>>> and still provide enough randomness.
>>
>> Base32 has 5 bit per character, so 100 bits are always 20 chars without
>> padding, that I found nice.
> 
> yes i meant the 'raw size' and basically always discarding half a byte
> of randomness, but sure.

What does that matter? 80 bit also doesn't align in word size of 64-bit,
could be also relevant. How many bits are relevant for entropy, that
needs a lower boundary and some upper bounder for practical purposes and
leveraging the chosen serialization of it.

Sure, we can discuss all day about some in a framework of core rules
somewhat arbitrary chosen specifics of our bikeshed color but if there
is not actually a relevant problem (e.g., to continue the methaphor
sun gets reflected and blinds one, or absorbed and heats the shed up)
I rather keep them, I played around with a few different formats and
bit sizes and this here felt best while still fulfilling the core
properties needed for us. base32 is IMO a great tradeof here between
ease of handling the character set and packing bits in single chars,
the non-uuid format ensures this is not ever used (or its generation
transformed to) something it shouldn't be.
I value your skepticism but here I'd rather avoid us derailing into
this to much, as while yes some properties are chosen by me in a way
that might seem arbitrary and might bee done slightly different too
while still fulfilling the core design-framework needs here, just
switching to another flavor for the sake of it doesn't really help us
much either – and IMO a random nonce being really just that and not
looking like something else has its merits.

Adding some more rationale to docs and commit message is certainly
warranted, this will be questioned by others, so from that POV I'm
happy it happens upfront from you.

>> That then allows one to tell apart e.g.:
>> - Same uid, changed rtime: the guest was registered again, for example
>>    destroyed and restored, or moved in from another cluster. A tool can
>>    then tell this from an "untouched" guest.
> 
> but this could also be detectable via ctime (except if we don't want
> to touch that on restore/migration ofc)

With "ctime will always be kept as is for a restore to a new VMID" I
meant that a ctime won't be touched and can't be used for this. Changing
this would also divert from a fixed behavior, i.e. technically a
breaking change. And yes, I do not believe in just technicalities
guiding design and allowing some technical breakage if it's not gonna
cause issues in practice and has some good justification (ROI), here the
ROI of such a change is IMO questionable, and as said, rather than
optimizing to much here I rather have this as complete as it might make
practical sense

> 
>> - Same uid in two clusters, which can happen after a remote migration
>>    that keeps the source, or a restore elsewhere. The uid together with
>>    the cluster ID and rtime still tells the instances apart.
> 
> for this the rtime is not needed though? uid + clusterid should
> be enough? (since same uid in one cluster can't happen)
> 

I was a bit imprecise here, for a single point in time yes that's true, but
backups normally have a history over a longer period of time and there
this ensures one can tell them apart (also potentially in logs or so,
but how/if we use them there is not all too relevant for now IMO, that
can be checked out later, we're not getting worse there in that regard as
the status quo now is after all). I.e., this is to differentiate between
the same guest and cluster uid over time, which is not that far out for us
due to remote migrations.


>> FWIW, my format allows to still map all uids into standard uuidv8,
>> so we're not locked in, but I do not want to use them and their
>> various versions here, simple random nonce that is formatted such
>> to be easy to handle (just alphanumerical) and still reasonably short.
>> That's my core requirement here. I.e., yes uuid might be wide spread,
>> but there to many tried to hard to add additional meaning to what should
>> be just a simple random nonce like this use case here.
> 
> makes sense, though i think having 20 vs 36 bytes in a config
> that is already ~500 bytes by default wouldn't make much difference IMO.
> (also we already have at least 2 uuids in the default config, so
> there would be precedent to using that format)

The uuid were not chosen by us and their (change) meaning is completely
different, so I do not see how we should go down that road just because
they got brought uppon us. Again, uid's are random nonces, the format
reflects that and is roughly optimized for its use case. no uuid.
We might look into deriving the smbios one from the uid by default
in the future though, still allowing manual overriding it as that should
be easily doable just needs a closer check if any change there when
uid changes causes actual issues, that would allow to avoid ~45 chars
by default. Similar we could also default the *initial* vmgenid to be
derived from that and only persist it once actually needed, dropping
like 92 bytes from our default config again, would make more than up
for the ones added here (and no uuid by default in the config anymore).

> we could also already opt to use a custom uuid format with the
> rtime encoded instead of having a separate property, but
> that is probably more pain that having it separate...

That would always mean uid changes if rtime changes, which breaks the
whole design.

>> It's only needed when a guest takes over an existing uid, so once at
>> the end of a restore or of an incoming remote migration. Without it,
>> restoring the same backup to two VMIDs, or to a new VMID while the
>> original still exists, would give two guests with the same uid in one
>> cluster. Newly generated uids (create, clone, first write of an
>> existing guest after the upgrade) take no cluster lock and do no
>> lookup, the randomness is enough there.
> 
> it's also necessary on clone and creation though? otherwise we can't
> be sure the random value is not in use? (unlikely but still)
> 
> if you argue about billions of clusters/nodes for 100bit randomness,
> then i think arguing with a much higher number of vms is fair?

No, I argue that this is safe for guests and the uses cases and reuse
the same for cluster as they get used as tripple for determining the
whole underlying reason of doing this all in the first place. Mixing
those then has no benefit here, on the contrary IMO.




^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH guest-common 09/34] abstract config: assign a guest identity and keep it on config writes
  2026-11-17 10:47   ` Dominik Csapak
@ 2026-11-17 12:47     ` Dominik Csapak
  0 siblings, 0 replies; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 12:47 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel



On 11/17/26 11:48 AM, Dominik Csapak wrote:
[snip]
>> +    }
>> +
>> +    return { identity => PVE::GuestIdentity::parse_identity($meta) };
>> +}
>> +
>>   # Generate and write config file for this VM/CT
>> +#
>> +# With guest identities enabled for the class, the identity published 
>> in the existing config file
>> +# gets set in $conf, whatever $conf contains, or a new one if none is 
>> published. So a config write
>> +# never changes a published identity.
>>   sub write_config {
>>       my ($class, $vmid, $conf) = @_;
>>       my $cfspath = $class->cfs_config_path($vmid);
>> -    PVE::Cluster::cfs_write_file($cfspath, $conf);
>> +    if (!$class->__identity_enabled()) {
>> +        PVE::Cluster::cfs_write_file($cfspath, $conf);
>> +        return;
>> +    }
>> +
>> +    $class->__identity_lock(
>> +        $vmid,
>> +        sub {
>> +            my $published = $class->__identity_read_published($vmid);
>> +            my $identity = $published && $published->{identity};
>> +
>> +            # a published uid without valid rtime can only come from 
>> a manual edit
>> +            if (!$identity || !defined($identity->{rtime})) {
> 
> the check for rtime here can't ever work since $identity is a boolean?
> i think it's mean to be `!defined($published->{rtime})` , no ?
> 
>> +                $identity = 
>> PVE::GuestIdentity::new_identity($identity && $identity->{uid});\
> 
> same here, the $identity->{uid} access can't work...


what i wrote here is actually wrong:

my $foo = 1 && { bar => 2 };

will assign { bar => 2 } into $foo (perl is weird...)
so this works.

It's a very unconvential way to write it IMO
maybe

my $foo;
$foo = $hash if $condition;

would be better? (even though it's a line longer?)

not a big issue, but a reader in the future could be as confused
as i was ^^





^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH guest-common 11/34] guest identity: allow taking over a uid that is unused in the cluster
  2026-11-16  0:46 ` [PATCH guest-common 11/34] guest identity: allow taking over a uid that is unused in the cluster Thomas Lamprecht
@ 2026-11-17 13:14   ` Dominik Csapak
  0 siblings, 0 replies; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 13:14 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel

aside from the whole pending/reservation handling being hard to follow,

some minor comments inline

On 11/16/26 1:53 AM, Thomas Lamprecht wrote:
[snip]
> +
> +# Publishes $uid, for example the one of a restored backup or of the source guest of a remote
> +# migration, as the uid of the guest $vmid with the current time as rtime, where that is allowed.
> +#
> +# $class is the config class of the guest and must have guest identities enabled. $reservation is
> +# what create_and_lock_config returned for the operation. The caller must still hold the config
> +# lock of $vmid and call this after the final config write of the operation. $uid can be undef if
> +# there is nothing to adopt, for example for a backup without uid.
> +#
> +# A guest that had an identity before the operation keeps it, unless it had $uid as pending uid,
> +# see adoptable_uid. Otherwise, $uid only replaces the identity that the reservation published,
> +# and only if no other guest in the cluster has it. Whatever the outcome, the pending uid of the
> +# config is removed afterwards, as the operation is done.
> +#
> +# Dies if the cluster-wide identity lock cannot be taken, for example without quorum. The pending
> +# uid then stays, as nothing got decided, so that a later operation can still take it over.

i find this whole comment a bit hard to read and to follow:

one paragraph says 'whatever the outcome, the pending uid [..] is 
removed [..]', but the next one says: 'dies if [..]. the pending uid 
then stays'

i get that it's about different error scenarios, but the wording is a
bit confusing here

> +#
> +# Returns a hash with the keys 'result', 'uid' (the uid of $vmid afterwards), 'requested' ($uid)
> +# and, for the result 'in-use', 'in-use-by' (the lowest VMID of the other guests with $uid). The
> +# result is one of:
> +#   kept    - the guest keeps the identity it had before the operation, or already has $uid
> +#   adopted - $uid got published for $vmid
> +#   in-use  - another guest has $uid, the identity of the reservation stays
> +#   changed - the identity of the reservation is not published anymore, nothing got changed
> +#   skipped - $uid is undef, the identity of the reservation stays

same here with the wording:

kept: keeps identity
changed: the identity is not published, nothing got changed

so what is the difference? also 'changed' -> 'nothing got changed' seems 
wrong...

> +sub adopt {
> +    my ($class, $vmid, $uid, $reservation) = @_;
> +
> +    die "guest identities are not enabled for this guest type\n" if !$class->__identity_enabled();
> +    die "missing guest identity reservation\n"
> +        if ref($reservation) ne 'HASH' || !$reservation->{reserved};
> +    die "invalid guest identity uid '$uid'\n" if defined($uid) && !is_valid_uid($uid);
> +
> +    my $res = take_over($class, $vmid, $uid, $reservation);
> +
> +    eval { $class->__identity_clear_pending($vmid) };
> +    die "unable to remove the pending uid - $@" if $@;
> +
> +    return $res;
> +}
> +




^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID
  2026-11-17 12:47       ` Thomas Lamprecht
@ 2026-11-17 13:54         ` Dominik Csapak
  0 siblings, 0 replies; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 13:54 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel

Please don't take this the wrong way, i don't want
to bikeshed, just lay out my reasoning.

tl;dr there is nothing wrong with the current approach
from my POV, but I'd have chosen different formats/sizes.

On 11/17/26 1:47 PM, Thomas Lamprecht wrote:
> Am 17.11.26 um 12:55 schrieb Dominik Csapak:
>> On 11/17/26 12:29 PM, Thomas Lamprecht wrote:
>>> Am 17.11.26 um 11:47 schrieb Dominik Csapak:
>>> I had it at 80 bits, but that is borderline w.r.t. hundreds of billions
>>> of entities and the birthday problem, as we're getting near actual digit
>>> percentages then (1 % chance of a clash at ~150 billion IDs). 100 bits
>>> takes that boundary between practically impossible and a real chance of
>>> clash in the hundreds of trillion range (1 % at ~160 trillion), which
>>> seemed good enough for me.
>>
>> but this is about the cluster id, surely there aren't billions of
>> clusters/nodes ?
> 
> I want to use the same for clusters and guests, what benefit do I
> have in doing that differently?

nothing, that's not what i argued. What i meant is that having such
a custom format with "weird" sizes makes the code less maintainable
in my opinion. e.g. using some preexisting library
for generating a uuid here would have saved quite a bit of code
without (again, in my opinion) any practical downside.

The perl code generates the uid on its own (with "duplicated" code).
They're having the same format yes, but that's just a regex line.
Or did i miss something and we reuse the cluster id for the vm uids ?

I'm not again the base32 + some amount of randomness,
just that the sizes chosen here seemed weird to me and at least
warrant some rationale, which you gave. (That I would have chosen
different things shouldn't be interpreted as a blocker,
just giving my opinion)

> 
>> They also don't have to be globally unique in practice, just for one
>> provider/customer/etc.
> 
> They do, else reality catches up with you fast, companies get bought
> and their infra merged, cluster can move from providers (e.g., ceph
> moved their whole CI infra from a RH datacenter to an IBM one with
> some big trucks about a year ago), PDM can connect all of them. Really
> not sure what you're trying to recommend here? Why make these edge
> cases harder for anyone that has the bad luck handling them, what's
> the benefit.

I just argued that e.g. 80 bit would have been enough here, to get a
"round" 10 bytes of randomness, nothing more.
(it still would allow billions of clusters with a chance of < 1% of
collisions)

> 
>>>> since we then don't have to use half a byte (100bit => 12.5 byte)
>>>> and still provide enough randomness.
>>>
>>> Base32 has 5 bit per character, so 100 bits are always 20 chars without
>>> padding, that I found nice.
>>
>> yes i meant the 'raw size' and basically always discarding half a byte
>> of randomness, but sure.
> 
> What does that matter? 80 bit also doesn't align in word size of 64-bit,
> could be also relevant. How many bits are relevant for entropy, that
> needs a lower boundary and some upper bounder for practical purposes and
> leveraging the chosen serialization of it.
> 
> Sure, we can discuss all day about some in a framework of core rules
> somewhat arbitrary chosen specifics of our bikeshed color but if there
> is not actually a relevant problem (e.g., to continue the methaphor
> sun gets reflected and blinds one, or absorbed and heats the shed up)
> I rather keep them, I played around with a few different formats and
> bit sizes and this here felt best while still fulfilling the core
> properties needed for us. base32 is IMO a great tradeof here between
> ease of handling the character set and packing bits in single chars,
> the non-uuid format ensures this is not ever used (or its generation
> transformed to) something it shouldn't be.

Again, I'm not again this format, but I'm not sure that's true?
This not being uuid does not stop anyone from using this in a way
not intended by us? If you didn't mean that, disregard this...

> I value your skepticism but here I'd rather avoid us derailing into
> this to much, as while yes some properties are chosen by me in a way
> that might seem arbitrary and might bee done slightly different too
> while still fulfilling the core design-framework needs here, just
> switching to another flavor for the sake of it doesn't really help us
> much either – and IMO a random nonce being really just that and not
> looking like something else has its merits.
> 
> Adding some more rationale to docs and commit message is certainly
> warranted, this will be questioned by others, so from that POV I'm
> happy it happens upfront from you.>

I agree that the exact format is not that important, so current
is fine by me.

>>> That then allows one to tell apart e.g.:
>>> - Same uid, changed rtime: the guest was registered again, for example
>>>     destroyed and restored, or moved in from another cluster. A tool can
>>>     then tell this from an "untouched" guest.
>>
>> but this could also be detectable via ctime (except if we don't want
>> to touch that on restore/migration ofc)
> 
> With "ctime will always be kept as is for a restore to a new VMID" I
> meant that a ctime won't be touched and can't be used for this. Changing
> this would also divert from a fixed behavior, i.e. technically a
> breaking change. And yes, I do not believe in just technicalities
> guiding design and allowing some technical breakage if it's not gonna
> cause issues in practice and has some good justification (ROI), here the
> ROI of such a change is IMO questionable, and as said, rather than
> optimizing to much here I rather have this as complete as it might make
> practical sense
> 
>>
>>> - Same uid in two clusters, which can happen after a remote migration
>>>     that keeps the source, or a restore elsewhere. The uid together with
>>>     the cluster ID and rtime still tells the instances apart.
>>
>> for this the rtime is not needed though? uid + clusterid should
>> be enough? (since same uid in one cluster can't happen)
>>
> 
> I was a bit imprecise here, for a single point in time yes that's true, but
> backups normally have a history over a longer period of time and there
> this ensures one can tell them apart (also potentially in logs or so,
> but how/if we use them there is not all too relevant for now IMO, that
> can be checked out later, we're not getting worse there in that regard as
> the status quo now is after all). I.e., this is to differentiate between
> the same guest and cluster uid over time, which is not that far out for us
> due to remote migrations.

makes sense

> 
> 
>>> FWIW, my format allows to still map all uids into standard uuidv8,
>>> so we're not locked in, but I do not want to use them and their
>>> various versions here, simple random nonce that is formatted such
>>> to be easy to handle (just alphanumerical) and still reasonably short.
>>> That's my core requirement here. I.e., yes uuid might be wide spread,
>>> but there to many tried to hard to add additional meaning to what should
>>> be just a simple random nonce like this use case here.
>>
>> makes sense, though i think having 20 vs 36 bytes in a config
>> that is already ~500 bytes by default wouldn't make much difference IMO.
>> (also we already have at least 2 uuids in the default config, so
>> there would be precedent to using that format)
> 
> The uuid were not chosen by us and their (change) meaning is completely
> different, so I do not see how we should go down that road just because
> they got brought uppon us. Again, uid's are random nonces, the format
> reflects that and is roughly optimized for its use case. no uuid.
> We might look into deriving the smbios one from the uid by default
> in the future though, still allowing manual overriding it as that should
> be easily doable just needs a closer check if any change there when
> uid changes causes actual issues, that would allow to avoid ~45 chars
> by default. Similar we could also default the *initial* vmgenid to be
> derived from that and only persist it once actually needed, dropping
> like 92 bytes from our default config again, would make more than up
> for the ones added here (and no uuid by default in the config anymore).

yes that sounds like a good plan, even though it could have been
achieved with having a fixed uuid too (and in hindsight, i probably
could have reused the smbios uuid for the initial vmgenid )

> 
>> we could also already opt to use a custom uuid format with the
>> rtime encoded instead of having a separate property, but
>> that is probably more pain that having it separate...
> 
> That would always mean uid changes if rtime changes, which breaks the
> whole design.

depends what part we would have compared, in a uid comparison
we would have to ignore the timestamp part of course,
but as i wrote having that is more pain than having it separated.

> 
>>> It's only needed when a guest takes over an existing uid, so once at
>>> the end of a restore or of an incoming remote migration. Without it,
>>> restoring the same backup to two VMIDs, or to a new VMID while the
>>> original still exists, would give two guests with the same uid in one
>>> cluster. Newly generated uids (create, clone, first write of an
>>> existing guest after the upgrade) take no cluster lock and do no
>>> lookup, the randomness is enough there.
>>
>> it's also necessary on clone and creation though? otherwise we can't
>> be sure the random value is not in use? (unlikely but still)
>>
>> if you argue about billions of clusters/nodes for 100bit randomness,
>> then i think arguing with a much higher number of vms is fair?
> 
> No, I argue that this is safe for guests and the uses cases and reuse
> the same for cluster as they get used as tripple for determining the
> whole underlying reason of doing this all in the first place. Mixing
> those then has no benefit here, on the contrary IMO.





^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH qemu-server 15/34] restore: take over the guest uid from the backup where possible
  2026-11-16  0:46 ` [PATCH qemu-server 15/34] restore: take over the guest uid from the backup where possible Thomas Lamprecht
@ 2026-11-17 15:17   ` Dominik Csapak
  0 siblings, 0 replies; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 15:17 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel

nits inline:

On 11/16/26 1:53 AM, Thomas Lamprecht wrote:
> A restore to an unused VMID, or over a VM without an identity, should
> keep the uid of the backup if no other guest in the cluster uses it.
> Take over that uid through the cluster-wide check of pve-guest-common
> after the data is restored and the final config is written, while
> holding the config lock. A VM that already had an identity keeps it,
> and 'unique' prevents taking over the uid. Log the outcome, and only
> warn if taking over the uid fails, as the restored VM has an identity
> of its own.
> 
> Refuse to restore a backup with a different uid over an existing VM
> unless 'allow-identity-mismatch' is set in the create API or qmrestore.
> This is independent of 'force', which permits overwriting the VM. With
> the override, the VM keeps its identity, unless it has the uid of the
> backup as pending uid from an unfinished restore.
> 
> For PBS, backup providers and VMA, compare the uids before resetting
> the replication state, restoring the firewall config or replacing the
> data of the target. For VMA this also works for standard input, through
> the header callback. Read the uid from the config that the restore
> itself uses, not from the best-effort extraction of the API, and ignore
> unknown members of 'meta', so that the uid of a backup from a newer
> version is not lost when the property fails to parse.
> 
> Take over the uid only after the live phase, the conversion to a
> template and, with 'unique', the registration of the new MAC addresses.
> A failed restore must not take the uid and so keep a retry at another
> VMID from getting it.
> 
> For a retry over a VM left behind by an unfinished restore to work,
> record the uid of the backup as a pending change of 'meta'. Record it
> after the uid check if the restore could take the uid over, also with
> 'unique', and keep it in all configs that the restore writes. A VM
> with that pending uid can be restored over without the override, and
> without 'unique' the retry takes the uid over if no other guest uses
> it. A pending uid does not count as in use.
> 
> Taking over the uid removes the pending uid, whatever the outcome. If
> the cluster-wide lock cannot be taken, it stays for a retry. Starting
> the VM for a live restore keeps it while the 'create' lock is held.
> Otherwise, applying pending changes drops it, and a clone does not get
> it.
> 
> Legacy tar archives predate guest identities and get no uid check.
> Their config is only available after the data is restored, so only the
> restored config can carry a pending uid.
> 
> Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
> ---
>   src/PVE/API2/Qemu.pm                      |  18 +
>   src/PVE/CLI/qmrestore.pm                  |   7 +
>   src/PVE/QemuServer.pm                     | 142 +++++-
>   src/test/QemuServerTest/FakeCFS.pm        |   3 +
>   src/test/restore-config-expected/150.conf |   9 +
>   src/test/restore-config-input/150.conf    |  10 +
>   src/test/run_api_tests.pl                 |  13 +
>   src/test/run_guest_identity_tests.pl      |  77 +++
>   src/test/run_qemu_restore_config_tests.pl | 559 +++++++++++++++++++++-
>   9 files changed, 828 insertions(+), 10 deletions(-)
>   create mode 100644 src/test/restore-config-expected/150.conf
>   create mode 100644 src/test/restore-config-input/150.conf
> 
> diff --git a/src/PVE/API2/Qemu.pm b/src/PVE/API2/Qemu.pm
> index 28e8389a..395dc334 100644
> --- a/src/PVE/API2/Qemu.pm
> +++ b/src/PVE/API2/Qemu.pm
> @@ -1241,6 +1241,15 @@ __PACKAGE__->register_method({
>                       description => "Assign a unique random ethernet address.",
>                       requires => 'archive',
>                   },
> +                'allow-identity-mismatch' => {
> +                    optional => 1,
> +                    type => 'boolean',
> +                    description => "Allow to overwrite an existing VM with a backup of another"
> +                        . " guest, as detected by a different 'uid' in 'meta'. Unless the VM is"
> +                        . " left over from an unfinished restore of the same backup, it keeps its"
> +                        . " own uid.",
> +                    requires => 'archive',

nit: an optional boolean should have a default.

we don't always have that on the existing properties, but
we should add it for new ones.

same nit holds for the equivalent container patch

> +                },




^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH qemu-server 16/34] api: remote migration: take over the guest uid from the source
  2026-11-16  0:46 ` [PATCH qemu-server 16/34] api: remote migration: take over the guest uid from the source Thomas Lamprecht
@ 2026-11-17 15:26   ` Dominik Csapak
  0 siblings, 0 replies; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 15:26 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel

one high level comment

On 11/16/26 1:48 AM, Thomas Lamprecht wrote:
> A VM migrated to another cluster should keep its uid, unless another
> guest there already uses it. Take over the uid of the source through
> the cluster-wide check of pve-guest-common after the incoming config is
> written. Otherwise, the VM keeps the uid assigned when its VMID was
> reserved. The other members of 'meta', including the creation
> information, come from the source as before.

I'd probably favor having the same opt-in flag for this
as with restore: accidentally moving a vm to a cluster
that has the same identity can result in all kind of issues
(e.g. duplicate ips, etc.) and should be prevented by default

for this, would it be possible to add an initial check
for the uid at the beginning? then adopt it initially before
writing the rest of the config.

same holds for the respective container patch

> 
> Fail the config command if taking over the uid raises an error, for
> example because the cluster-wide lock cannot be taken. Finishing a
> migration that deletes the source would otherwise lose the uid because
> of a transient failure. Update the lock state of the tunnel first, so
> that the cleanup after the failure finds the target config. The
> existing reply timeout of two minutes covers the wait for the lock.
> 
> Report the outcome in the task logs of both sides and in the reply to
> the config command. Older sources ignore the added field. An outcome
> that the source does not know, as a newer target could report, only
> produces a warning, because the target accepted the config at that
> point. The existing lock check rejects a repeated config command, so
> the registration time cannot be reset.
> 
> Bump the tunnel version, so that older targets are refused before
> disks are allocated or transferred, and not only when their strict
> config parser rejects the identity. Keep accepting the previous tunnel
> version from older sources.
> 
> Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
> ---
>   src/PVE/API2/Qemu.pm                 |  20 ++-
>   src/PVE/QemuMigrate.pm               |   9 +-
>   src/test/run_guest_identity_tests.pl | 197 +++++++++++++++++++++++++++
>   3 files changed, 221 insertions(+), 5 deletions(-)
> 
> diff --git a/src/PVE/API2/Qemu.pm b/src/PVE/API2/Qemu.pm
> index 395dc334..0ac5e14a 100644
> --- a/src/PVE/API2/Qemu.pm
> +++ b/src/PVE/API2/Qemu.pm
> @@ -6867,7 +6867,7 @@ __PACKAGE__->register_method({
>           PVE::Cluster::check_cfs_quorum();
>   
>           my $lock = 'create';
> -        eval { PVE::QemuConfig->create_and_lock_config($vmid, 0, $lock); };
> +        my $reservation = eval { PVE::QemuConfig->create_and_lock_config($vmid, 0, $lock); };
>   
>           raise_param_exc({ vmid => "unable to create empty VM config - $@" })
>               if $@;
> @@ -7006,7 +7006,7 @@ __PACKAGE__->register_method({
>                       # bump/bump for opt-in changes
>                       return {
>                           api => $PVE::QemuMigrate::WS_TUNNEL_VERSION,
> -                        age => 0,
> +                        age => 1,
>                       };
>                   },
>                   'config' => sub {
> @@ -7039,6 +7039,7 @@ __PACKAGE__->register_method({
>                       my $conf_fn = "incoming/qemu-server/$state->{vmid}.conf";
>                       my $new_conf =
>                           PVE::QemuServer::parse_vm_config($conf_fn, $params->{conf}, 1);
> +                    my $source_identity = PVE::QemuConfig->get_identity($new_conf);
>                       delete $new_conf->{lock};
>                       delete $new_conf->{digest};
>   
> @@ -7093,7 +7094,20 @@ __PACKAGE__->register_method({
>   
>                       $state->{lock} = 'migrate';
>   
> -                    return;
> +                    # only after the state knows the new lock, so that 'quit' can clean up if
> +                    # adopting fails
> +                    my $identity = eval {
> +                        PVE::GuestIdentity::adopt(
> +                            'PVE::QemuConfig',
> +                            $state->{vmid},
> +                            $source_identity && $source_identity->{uid},
> +                            $reservation,
> +                        );
> +                    };
> +                    die "unable to adopt the uid of the source guest - $@" if $@;
> +                    print PVE::GuestIdentity::adopt_result_message($identity, 'source') . "\n";
> +
> +                    return { identity => $identity };
>                   },
>                   'bwlimit' => sub {
>                       my ($params) = @_;
> diff --git a/src/PVE/QemuMigrate.pm b/src/PVE/QemuMigrate.pm
> index 22f192e6..a2b897d8 100644
> --- a/src/PVE/QemuMigrate.pm
> +++ b/src/PVE/QemuMigrate.pm
> @@ -14,6 +14,7 @@ use PVE::Cmd qw(build_ssh_command);
>   use PVE::Format qw(render_bytes);
>   use PVE::Firewall::Helpers;
>   use PVE::GuestHelpers qw(safe_boolean_ne safe_string_ne);
> +use PVE::GuestIdentity;
>   use PVE::INotify;
>   use PVE::JSONSchema;
>   use PVE::RPCEnvironment;
> @@ -45,7 +46,8 @@ use PVE::AbstractMigrate;
>   use base qw(PVE::AbstractMigrate);
>   
>   # compared against remote end's minimum version
> -our $WS_TUNNEL_VERSION = 2;
> +# 3: the target accepts a guest identity in the config and takes over its uid
> +our $WS_TUNNEL_VERSION = 3;
>   
>   sub fork_tunnel {
>       my ($self, $ssh_forward_info) = @_;
> @@ -953,7 +955,10 @@ sub phase1_remote {
>           'firewall-config' => $fw_conf_str,
>       };
>   
> -    PVE::Tunnel::write_tunnel($self->{tunnel}, 120, 'config', $params);
> +    my $res = PVE::Tunnel::write_tunnel($self->{tunnel}, 120, 'config', $params);
> +    if (my $identity = $res->{identity}) {
> +        $self->log(PVE::GuestIdentity::remote_adopt_result_log($identity));
> +    }
>   }
>   
>   sub phase1_cleanup {
> diff --git a/src/test/run_guest_identity_tests.pl b/src/test/run_guest_identity_tests.pl
> index 3429fca6..b201594a 100755
> --- a/src/test/run_guest_identity_tests.pl
> +++ b/src/test/run_guest_identity_tests.pl
> @@ -9,6 +9,9 @@ use warnings;
>   use lib qw(.. .);
>   
>   use File::Temp qw(tempdir);
> +use IO::Handle;
> +use JSON;
> +use Socket;
>   use Test::MockModule;
>   use Test::More;
>   
> @@ -16,6 +19,7 @@ use PVE::API2::Qemu;
>   use PVE::JSONSchema;
>   use PVE::QemuConfig;
>   use PVE::QemuConfig::NoWrite;
> +use PVE::QemuMigrate;
>   use PVE::QemuServer;
>   use PVE::QemuServer::MetaInfo;
>   use PVE::RPCEnvironment;
> @@ -333,4 +337,197 @@ subtest 'importovf' => sub {
>       );
>   };
>   
> +# Runs the migration tunnel endpoint for $vmid with the commands @$commands from the source side
> +# and returns the decoded replies, the task output and the error of the task.
> +sub run_mtunnel {
> +    my ($vmid, $commands) = @_;
> +
> +    socketpair(my $client, my $server, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
> +        or die "socketpair failed - $!\n";
> +    $client->autoflush(1);
> +
> +    print $client encode_json($_) . "\n" for $commands->@*;
> +    shutdown($client, 1);
> +
> +    my $rpcenv_module = Test::MockModule->new('PVE::RPCEnvironment');
> +    $rpcenv_module->mock(
> +        fork_worker => sub {
> +            my ($self, $type, $id, $user, $code) = @_;
> +            $code->('UPID:test');
> +            return 'UPID:test';
> +        },
> +    );
> +    my $access_control_module = Test::MockModule->new('PVE::AccessControl');
> +    $access_control_module->mock(assemble_tunnel_ticket => sub { return 'ticket'; });
> +    my $socket_module = Test::MockModule->new('IO::Socket::UNIX');
> +    $socket_module->mock(new => sub { return bless { conn => $server }, 'TestListenSocket'; });
> +
> +    my ($output, $err) = ('', '');
> +    {
> +        open(my $out_fh, '>', \$output);
> +        my $oldfh = select($out_fh);
> +        eval { PVE::API2::Qemu->mtunnel({ node => 'localhost', vmid => $vmid }) };
> +        $err = $@;
> +        select($oldfh);
> +        close($out_fh);
> +    }
> +    close($server);
> +
> +    my $replies = [];
> +    while (defined(my $line = <$client>)) {
> +        push $replies->@*, decode_json($line);
> +    }
> +
> +    return ($replies, $output, $err);
> +}
> +
> +package TestListenSocket {
> +
> +    sub accept {
> +        my ($self) = @_;
> +        return $self->{conn};
> +    }
> +}
> +
> +subtest 'remote migration, target side' => sub {
> +    QemuServerTest::FakeCFS::reset();
> +
> +    my $cluster_module = Test::MockModule->new('PVE::Cluster');
> +    $cluster_module->mock(check_cfs_quorum => sub { return 1; });
> +    my $storage_module = Test::MockModule->new('PVE::Storage');
> +    $storage_module->mock(config => sub { return {}; });
> +    my $replication_config_module = Test::MockModule->new('PVE::ReplicationConfig');
> +    $replication_config_module->mock(
> +        new => sub { return bless {}, 'PVE::ReplicationConfig'; },
> +        check_for_existing_jobs => sub { return; },
> +    );
> +    my $qemu_server_module = Test::MockModule->new('PVE::QemuServer');
> +    $qemu_server_module->mock(check_running => sub { return 0; });
> +
> +    my $source_conf = "cores: 2\nmemory: 1024\nmeta: creation-qemu=9.2.0,ctime=1600000000,"
> +        . "rtime=1600000000000,uid=$UID_A\nname: source\n";
> +    my $config_cmd = { cmd => 'config', conf => $source_conf };
> +    my $quit_cmd = { cmd => 'quit', cleanup => 0 };
> +
> +    $QemuServerTest::FakeCFS::now_ms = 1800000000000;
> +    my ($replies, $output, $err) = run_mtunnel(100, [$config_cmd, $config_cmd, $quit_cmd]);
> +    is($err, '', 'tunnel exits normally');
> +
> +    ok($replies->[0]->{success}, 'config command succeeds');
> +    is_deeply(
> +        $replies->[0]->{identity},
> +        { result => 'adopted', uid => $UID_A, requested => $UID_A },
> +        'config command returns the adopted identity',
> +    );
> +    like(
> +        $output,
> +        qr/^guest identity: adopted uid $UID_A from the source guest$/m,
> +        'target task logs it',
> +    );
> +    ok(!$replies->[1]->{success}, 'repeated config command fails');
> +    is_deeply(
> +        load_meta(100),
> +        {
> +            'creation-qemu' => '9.2.0',
> +            ctime => 1600000000,
> +            rtime => 1800000000000,
> +            uid => $UID_A,
> +        },
> +        'source uid with rtime of the first config command, other members from the source',
> +    );
> +    ok($replies->[2]->{success}, 'tunnel quits');
> +
> +    QemuServerTest::FakeCFS::reset();
> +    $QemuServerTest::FakeCFS::other_guests->{300} = "rtime=1,uid=$UID_A";
> +    ($replies) = run_mtunnel(101, [$config_cmd, $quit_cmd]);
> +    is_deeply(
> +        $replies->[0]->{identity},
> +        {
> +            result => 'in-use',
> +            uid => generated_uid(1),
> +            requested => $UID_A,
> +            'in-use-by' => 300,
> +        },
> +        'uid in use by another guest is not adopted',
> +    );
> +    is(published_identity(101)->{uid}, generated_uid(1), 'new uid stays');
> +
> +    QemuServerTest::FakeCFS::reset();
> +    $QemuServerTest::FakeCFS::lock_domain_error =
> +        "cfs-lock 'domain-guest-identity' error: no quorum!\n";
> +    ($replies, $output, $err) =
> +        run_mtunnel(103, [$config_cmd, { cmd => 'quit', cleanup => 1 }]);
> +    is($err, '', 'tunnel exits normally after the failed config command');
> +    ok(!$replies->[0]->{success}, 'config command fails if adopting fails');
> +    is(
> +        $replies->[0]->{msg},
> +        "failed to handle 'config' command - unable to adopt the uid of the source guest"
> +            . " - cfs-lock 'domain-guest-identity' error: no quorum!\n",
> +        'error explains the failure',
> +    );
> +    ok($replies->[1]->{success}, 'cleanup on quit succeeds');
> +    ok(!defined(configs()->{103}), 'config removed by the cleanup');
> +
> +    QemuServerTest::FakeCFS::reset();
> +    $config_cmd->{conf} =~ s/,rtime=\d+,uid=\w+//;
> +    ($replies) = run_mtunnel(102, [$config_cmd, $quit_cmd]);
> +    is($replies->[0]->{identity}->{result}, 'skipped', 'source without uid');
> +    is(published_identity(102)->{uid}, generated_uid(1), 'new uid stays');
> +};
> +
> +subtest 'remote migration, source side' => sub {
> +    QemuServerTest::FakeCFS::reset();
> +
> +    # the source reads the firewall config of the VM from /etc/pve, use a VMID the host lacks
> +    my $vmid = 999999999;
> +    configs()->{$vmid} = "cores: 2\nmemory: 1024\nmeta: rtime=1600000000000,uid=$UID_A\n";
> +
> +    my ($sent, $identity);
> +    my $tunnel_module = Test::MockModule->new('PVE::Tunnel');
> +    $tunnel_module->mock(
> +        write_tunnel => sub {
> +            my ($tunnel, $timeout, $command, $params) = @_;
> +            die "unexpected command '$command'\n" if $command ne 'config';
> +            $sent = $params->{conf};
> +            return { success => 1, identity => $identity };
> +        },
> +    );
> +
> +    my $self = bless {
> +        opts => { remote => {} },
> +        local_volumes => {},
> +        volume_map => {},
> +        storecfg => {},
> +        tunnel => {},
> +        },
> +        'PVE::QemuMigrate';
> +
> +    my $phase1 = sub {
> +        my $output = '';
> +        open(my $out_fh, '>', \$output);
> +        my $oldfh = select($out_fh);
> +        eval { $self->phase1_remote($vmid) };
> +        my $err = $@;
> +        select($oldfh);
> +        close($out_fh);
> +        return ($err, $output);
> +    };
> +
> +    $identity = { result => 'adopted', uid => $UID_A, requested => $UID_A };
> +    my ($err, $output) = $phase1->();
> +    is($err, '', 'config sent');
> +    like($sent, qr/^meta: rtime=1600000000000,uid=$UID_A$/m, 'source config sent with its uid');
> +    like(
> +        $output,
> +        qr/guest identity: adopted uid $UID_A from the source guest$/m,
> +        'source task logs the outcome',
> +    );
> +
> +    # a target with a newer version has already taken over the config at this point
> +    $identity = { result => 'future', uid => $UID_A, requested => $UID_A };
> +    ($err, $output) = $phase1->();
> +    is($err, '', 'unknown outcome does not fail the migration');
> +    like($output, qr/unknown result of guest identity adoption 'future'$/m, 'it is logged');
> +};
> +
>   done_testing();





^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH manager 26/34] api: cluster resources: add guest uid and registration time
  2026-11-16  0:46 ` [PATCH manager 26/34] api: cluster resources: add guest uid and registration time Thomas Lamprecht
@ 2026-11-17 15:30   ` Dominik Csapak
  0 siblings, 0 replies; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 15:30 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel

nit inline

On 11/16/26 1:51 AM, Thomas Lamprecht wrote:
> Tools that follow guests across restores and migrations, for example
> backup products, need the guest identity. Report the 'uid' and 'rtime'
> of guests that have them on their rows, so such tools get both for all
> guests with one call instead of reading each guest config. Like lock
> and tags, they are only reported to users with VM.Audit on the guest.
> 
> Both come from the 'meta' line, which the existing request for lock and
> tags now also returns, so there is no extra round trip to pmxcfs. The
> line is parsed per guest, and a guest with a missing or malformed
> identity only lacks the fields. Neither the raw line nor its other
> members are exposed.
> 
> Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
> ---
>   PVE/API2/Cluster.pm           |  25 +++-
>   test/ClusterResources_test.pl | 249 ++++++++++++++++++++++++++++++++++
>   test/Makefile                 |   6 +-
>   3 files changed, 278 insertions(+), 2 deletions(-)
>   create mode 100755 test/ClusterResources_test.pl
> 
> diff --git a/PVE/API2/Cluster.pm b/PVE/API2/Cluster.pm
> index 4e5efbfd..346ecdb2 100644
> --- a/PVE/API2/Cluster.pm
> +++ b/PVE/API2/Cluster.pm
> @@ -11,6 +11,7 @@ use PVE::DataCenterConfig;
>   use PVE::Exception qw(raise_param_exc);
>   use PVE::Firewall;
>   use PVE::GuestHelpers;
> +use PVE::GuestIdentity;
>   use PVE::HA::Config;
>   use PVE::HA::Env::PVE2;
>   use PVE::INotify;
> @@ -474,6 +475,22 @@ __PACKAGE__->register_method({
>                       optional => 1,
>                       default => 0,
>                   },
> +                uid => {
> +                    description =>
> +                        "Guest lineage identifier, normally kept across restores and migrations"
> +                        . " from other clusters (for types 'qemu' and 'lxc').",
> +                    type => 'string',
> +                    optional => 1,
> +                },
> +                rtime => {
> +                    description =>
> +                        "Time the guest was registered in this cluster, for example by"
> +                        . " creation, restore, or migration from another cluster, in milliseconds"
> +                        . " since the UNIX epoch (for types 'qemu' and 'lxc').",
> +                    type => 'integer',
> +                    minimum => 0,
> +                    optional => 1,
> +                },
>                   network => {
>                       description => "The name of a Network entity (for type 'network').",
>                       type => "string",
> @@ -552,7 +569,7 @@ __PACKAGE__->register_method({
>           # we try to generate 'numbers' by using "$X + 0"
>           if (!$param->{type} || $param->{type} eq 'vm') {
>               my $prop_list = [qw(lock tags)];
> -            my $props = PVE::Cluster::get_guest_config_properties($prop_list);
> +            my $props = PVE::Cluster::get_guest_config_properties([@$prop_list, 'meta']);
>   

nit: this could simply add 'meta' to the prop_list

>               for my $vmid (sort keys %$idlist) {
>   
> @@ -593,6 +610,12 @@ __PACKAGE__->register_method({
>                       }
>                   }
>   
> +                my $identity = PVE::GuestIdentity::parse_identity($props->{$vmid}->{meta});
> +                if ($identity) {
> +                    $entry->{uid} = $identity->{uid};
> +                    $entry->{rtime} = int($identity->{rtime}) if defined($identity->{rtime});
> +                }
> +

and here we'd instead do

if (my $meta = parse_identity(delete $entry->{meta})) {
     $entry->{...}

}

but this is more of a taste question

>                   if (
>                       defined($entry->{pool})
>                       && !$rpcenv->check($authuser, "/pool/$entry->{pool}", ['Pool.Audit'], 1)




^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH manager 30/34] ui: guest summary: show the guest identity
  2026-11-16  0:46 ` [PATCH manager 30/34] ui: guest summary: show " Thomas Lamprecht
@ 2026-11-17 15:44   ` Dominik Csapak
  0 siblings, 0 replies; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 15:44 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel

comment inline:

On 11/16/26 1:50 AM, Thomas Lamprecht wrote:
> The 'meta' property of a guest now holds its identity, a unique ID that
> restores and migrations from other clusters keep where possible, and
> the time the guest was registered in this cluster, next to the creation
> time and, for VMs, the QEMU version the VM was created with. The web UI
> showed none of it, so comparing a guest with what a backup or monitoring
> tool reports for it required reading the config or the API.
> 
> Show the unique ID as a quiet row in the status panel of the guest
> summary, also for templates, as it is the value such tools report. A
> button next to it opens a window with all these values and, for users
> with Sys.Audit on '/', the cluster ID. Both IDs are in read-only text
> fields, so they can be selected and copied.
> 
> The row uses the uid that the guest status already returns, so the
> summary makes no extra periodic request, and the window loads the guest
> config and the cluster status once when opened. A failure to load the
> cluster status only leaves out the cluster ID. Guests without a uid,
> for example on nodes that do not handle the identity yet, get no row.
> 
> Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
> ---
>   www/manager6/Makefile                    |   1 +
>   www/manager6/panel/GuestIdentity.js      | 142 +++++++++++++++++++++++
>   www/manager6/panel/GuestStatusView.js    |   3 +
>   www/manager6/panel/TemplateStatusView.js |   3 +
>   4 files changed, 149 insertions(+)
>   create mode 100644 www/manager6/panel/GuestIdentity.js
> 
> diff --git a/www/manager6/Makefile b/www/manager6/Makefile
> index d2ea786b..8c4e9ba9 100644
> --- a/www/manager6/Makefile
> +++ b/www/manager6/Makefile
> @@ -113,6 +113,7 @@ JSSRC= 							\
>   	panel/IPView.js					\
>   	panel/RunningChart.js				\
>   	panel/StatusPanel.js				\
> +	panel/GuestIdentity.js				\
>   	panel/GuestStatusView.js			\
>   	panel/GuestSummary.js				\
>   	panel/TemplateStatusView.js			\
> diff --git a/www/manager6/panel/GuestIdentity.js b/www/manager6/panel/GuestIdentity.js
> new file mode 100644
> index 00000000..d67ec7d4
> --- /dev/null
> +++ b/www/manager6/panel/GuestIdentity.js
> @@ -0,0 +1,142 @@
> +Ext.define('PVE.window.GuestIdentity', {
> +    extend: 'Ext.window.Window',
> +    alias: 'widget.pveGuestIdentityWindow',
> +
> +    title: gettext('Guest Identity'),
> +    width: 450,
> +    modal: true,
> +    resizable: false,
> +    bodyPadding: 10,
> +
> +    layout: 'anchor',
> +    defaults: {
> +        anchor: '100%',
> +        labelWidth: 130,
> +    },
> +
> +    // the parsed 'meta' property of the guest config
> +    meta: {},
> +    clusterId: undefined,
> +
> +    initComponent: function () {
> +        let me = this;
> +
> +        let meta = me.meta;
> +        let renderTime = (seconds) =>
> +            Ext.isNumeric(seconds) ? PVE.Utils.render_timestamp_human_readable(seconds) : '';
> +
> +        let fields = [
> +            {
> +                xtype: 'textfield',
> +                itemId: 'uid',
> +                fieldLabel: gettext('Unique ID'),
> +                value: meta.uid,
> +                editable: false,
> +            },
> +            {
> +                xtype: 'displayfield',
> +                itemId: 'rtime',
> +                fieldLabel: gettext('Registered'),
> +                value: renderTime(meta.rtime / 1000),
> +            },
> +            {
> +                xtype: 'textfield',
> +                itemId: 'cluster-id',
> +                fieldLabel: gettext('Cluster ID'),
> +                value: me.clusterId,
> +                editable: false,
> +            },
> +            {
> +                xtype: 'displayfield',
> +                itemId: 'ctime',
> +                fieldLabel: gettext('Created'),
> +                value: renderTime(meta.ctime),
> +            },
> +            {
> +                xtype: 'displayfield',
> +                itemId: 'creation-qemu',
> +                fieldLabel: gettext('Created with QEMU'),
> +                value: meta['creation-qemu'],
> +            },
> +        ];
> +        me.items = fields.filter((field) => (field.value ?? '') !== '');
> +
> +        me.callParent();
> +    },
> +});
> +
> +Ext.define('PVE.panel.GuestIdentityInfo', {
> +    extend: 'Ext.container.Container',
> +    alias: 'widget.pveGuestIdentityInfo',
> +
> +    hidden: true,
> +    layout: {
> +        type: 'hbox',
> +        align: 'middle',
> +    },
> +
> +    items: [
> +        {
> +            xtype: 'pmxInfoWidget',
> +            flex: 1,
> +            iconCls: 'fa fa-id-card-o fa-fw',
> +            title: gettext('Unique ID'),
> +            printBar: false,
> +            textField: 'uid',
> +            // the status view only updates info widgets, so this one shows or hides the whole row
> +            renderer: function (uid) {
> +                this.up('pveGuestIdentityInfo').setHidden(!uid);
> +                return Ext.htmlEncode(uid);
> +            },
> +        },
> +        {
> +            xtype: 'button',
> +            iconCls: 'fa fa-info-circle',
> +            tooltip: gettext('Details'),
> +            ariaLabel: gettext('Details'),
> +            ui: 'default-toolbar',
> +            margin: '0 0 0 5',
> +            handler: function () {
> +                this.up('pveGuestIdentityInfo').showDetails();
> +            },
> +        },
> +    ],
> +
> +    showDetails: async function () {
> +        let me = this;
> +
> +        let view = me.up('pmxStatusView');
> +        let { node, vmid, type } = view.pveSelNode.data;
> +        let caps = Ext.state.Manager.get('GuiCap');
> +
> +        let [config, status] = await Promise.allSettled([
> +            // not the pending values: an unfinished restore queues the uid of its backup there
> +            Proxmox.Async.api2({
> +                url: `/nodes/${node}/${type}/${vmid}/config`,
> +                params: { current: 1 },
> +                method: 'GET',
> +                waitMsgTarget: view,
> +            }),
> +            // the cluster ID is optional, so a missing privilege or a failure only omits it
> +            caps.dc['Sys.Audit']
> +                ? Proxmox.Async.api2({ url: '/cluster/status', method: 'GET', waitMsgTarget: view })
> +                : undefined,
> +        ]);

both api calls have the view as waitMsgTarget. Since they run in
parallel, i think the first one finishing will unmask the view again.

In this case, manually (un)masking would be better i think.

> +
> +        if (config.status === 'rejected') {
> +            Ext.Msg.alert(gettext('Error'), config.reason.htmlStatus);
> +            return;
> +        }
> +
> +        let meta = PVE.Parser.parsePropertyString(config.value.result.data.meta) ?? {};
> +        // a standalone node reports the ID on its node entry, a cluster only on the cluster entry
> +        let statusEntries = status.value?.result?.data ?? [];
> +        let clusterId = statusEntries.find((entry) => entry['cluster-id'])?.['cluster-id'];

noticed just now, couldn't standalone nodes publish their uid
in /cluster/resources ? then we'd have that always available for
standalone nodes

(maybe even for clusters, but we probably don't want it to have
on every node?)

> +
> +        Ext.create('PVE.window.GuestIdentity', {
> +            autoShow: true,
> +            meta,
> +            clusterId,
> +        });
> +    },
> +});
> diff --git a/www/manager6/panel/GuestStatusView.js b/www/manager6/panel/GuestStatusView.js
> index 315d3420..00851b07 100644
> --- a/www/manager6/panel/GuestStatusView.js
> +++ b/www/manager6/panel/GuestStatusView.js
> @@ -92,6 +92,9 @@ Ext.define('PVE.panel.GuestStatusView', {
>                   hidden: '{isQemu}',
>               },
>           },
> +        {
> +            xtype: 'pveGuestIdentityInfo',
> +        },
>           {
>               xtype: 'box',
>               height: 10,
> diff --git a/www/manager6/panel/TemplateStatusView.js b/www/manager6/panel/TemplateStatusView.js
> index 8742cfc2..26732386 100644
> --- a/www/manager6/panel/TemplateStatusView.js
> +++ b/www/manager6/panel/TemplateStatusView.js
> @@ -30,6 +30,9 @@ Ext.define('PVE.panel.TemplateStatusView', {
>               iconCls: 'fa fa-fw fa-building',
>               title: gettext('Node'),
>           },
> +        {
> +            xtype: 'pveGuestIdentityInfo',
> +        },
>           {
>               xtype: 'box',
>               height: 20,





^ permalink raw reply	[flat|nested] 49+ messages in thread

* Re: [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID
  2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
                   ` (34 preceding siblings ...)
  2026-11-17 10:47 ` [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Dominik Csapak
@ 2026-11-17 15:55 ` Dominik Csapak
  35 siblings, 0 replies; 49+ messages in thread
From: Dominik Csapak @ 2026-11-17 15:55 UTC (permalink / raw)
  To: Thomas Lamprecht, pve-devel

looked over the rest of the patches and did notice too
problematic (see details on the individual patches though).

maybe the auto new uid on remote-migration is worth
thinking about.

couldn't test it for now since most do not apply anymore,
but will try tomorrow to fix the conficts if you
don't send another version by then




^ permalink raw reply	[flat|nested] 49+ messages in thread

end of thread, other threads:[~2026-11-17 15:55 UTC | newest]

Thread overview: 49+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-16  0:46 [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Thomas Lamprecht
2026-11-16  0:46 ` [PATCH cluster 01/34] pmxcfs: reject changes to the cluster ID file from user space Thomas Lamprecht
2026-11-16  0:46 ` [PATCH cluster 02/34] pmxcfs: generate a cluster ID on standalone nodes Thomas Lamprecht
2026-11-16  0:46 ` [PATCH cluster 03/34] pmxcfs: dfsm: add a callback that runs once all members are in sync Thomas Lamprecht
2026-11-16  0:46 ` [PATCH cluster 04/34] pmxcfs: quorum: pass the corosync membership to an optional listener Thomas Lamprecht
2026-11-16  0:46 ` [PATCH cluster 05/34] pmxcfs: dcdb: generate the cluster ID once the cluster is in sync Thomas Lamprecht
2026-11-16  0:46 ` [PATCH cluster 06/34] cluster: add helper to read the cluster ID Thomas Lamprecht
2026-11-16  0:46 ` [PATCH cluster 07/34] pmxcfs: allow removing the cluster ID file in forced local mode Thomas Lamprecht
2026-11-16  0:46 ` [PATCH guest-common 08/34] guest identity: add helpers for the guest uid and registration time Thomas Lamprecht
2026-11-17 10:47   ` Dominik Csapak
2026-11-16  0:46 ` [PATCH guest-common 09/34] abstract config: assign a guest identity and keep it on config writes Thomas Lamprecht
2026-11-17 10:47   ` Dominik Csapak
2026-11-17 12:47     ` Dominik Csapak
2026-11-16  0:46 ` [PATCH guest-common 10/34] abstract config: let the VMID reservation return the previous state Thomas Lamprecht
2026-11-16  0:46 ` [PATCH guest-common 11/34] guest identity: allow taking over a uid that is unused in the cluster Thomas Lamprecht
2026-11-17 13:14   ` Dominik Csapak
2026-11-16  0:46 ` [PATCH qemu-server 12/34] api: restore: release the VMID if a restore to an unused VMID fails Thomas Lamprecht
2026-11-16  0:46 ` [PATCH qemu-server 13/34] api: migrate, clone: refuse targets that would drop the guest identity Thomas Lamprecht
2026-11-16  0:46 ` [PATCH qemu-server 14/34] fix #7846: config: add a guest identity to the 'meta' property Thomas Lamprecht
2026-11-16  0:46 ` [PATCH qemu-server 15/34] restore: take over the guest uid from the backup where possible Thomas Lamprecht
2026-11-17 15:17   ` Dominik Csapak
2026-11-16  0:46 ` [PATCH qemu-server 16/34] api: remote migration: take over the guest uid from the source Thomas Lamprecht
2026-11-17 15:26   ` Dominik Csapak
2026-11-16  0:46 ` [PATCH qemu-server 17/34] api: status: return the guest uid Thomas Lamprecht
2026-11-16  0:46 ` [PATCH container 18/34] config: add read-only meta property with the creation time Thomas Lamprecht
2026-11-16  0:46 ` [PATCH container 19/34] fix #7846: config: add a guest identity to the 'meta' property Thomas Lamprecht
2026-11-16  0:46 ` [PATCH container 20/34] api: migrate, clone: refuse targets that would drop the guest identity Thomas Lamprecht
2026-11-16  0:46 ` [PATCH container 21/34] restore: take over the guest uid from the backup where possible Thomas Lamprecht
2026-11-16  0:46 ` [PATCH container 22/34] restore: refuse overwriting a container with another guest's backup Thomas Lamprecht
2026-11-16  0:46 ` [PATCH container 23/34] migrate: remote: clean up the target on a tunnel version mismatch Thomas Lamprecht
2026-11-16  0:46 ` [PATCH container 24/34] api: remote migration: take over the guest uid from the source Thomas Lamprecht
2026-11-16  0:46 ` [PATCH container 25/34] api: status: return the guest uid Thomas Lamprecht
2026-11-16  0:46 ` [PATCH manager 26/34] api: cluster resources: add guest uid and registration time Thomas Lamprecht
2026-11-17 15:30   ` Dominik Csapak
2026-11-16  0:46 ` [PATCH manager 27/34] api: cluster status: add cluster ID Thomas Lamprecht
2026-11-16  0:46 ` [PATCH manager 28/34] ui: restore: allow overwriting a guest with a backup of another guest Thomas Lamprecht
2026-11-16  0:46 ` [PATCH manager 29/34] ui: migrate: refuse target nodes that would drop the guest identity Thomas Lamprecht
2026-11-16  0:46 ` [PATCH manager 30/34] ui: guest summary: show " Thomas Lamprecht
2026-11-17 15:44   ` Dominik Csapak
2026-11-16  0:46 ` [PATCH docs 31/34] vzdump: describe the guest identity of VMs and containers Thomas Lamprecht
2026-11-16  0:46 ` [PATCH docs 32/34] pvecm: document the cluster ID and how to get a new one Thomas Lamprecht
2026-11-16  0:46 ` [PATCH docs 33/34] qm: configuration: describe the read-only meta property Thomas Lamprecht
2026-11-16  0:46 ` [PATCH docs 34/34] pct: " Thomas Lamprecht
2026-11-17 10:47 ` [PATCH cluster/guest-common/qemu-server/container/manager/docs 00/34] fix #7846: guest identity (uid) and cluster ID Dominik Csapak
2026-11-17 11:29   ` Thomas Lamprecht
2026-11-17 11:55     ` Dominik Csapak
2026-11-17 12:47       ` Thomas Lamprecht
2026-11-17 13:54         ` Dominik Csapak
2026-11-17 15:55 ` Dominik Csapak

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal