public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
From: Thomas Lamprecht <t.lamprecht@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH guest-common v2 08/36] guest identity: add helpers for the guest uid and registration time
Date: Tue, 17 Nov 2026 23:34:18 +0100	[thread overview]
Message-ID: <20261117223945.862914-9-t.lamprecht@proxmox.com> (raw)
In-Reply-To: <20261117223945.862914-1-t.lamprecht@proxmox.com>

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 uid of 20 characters from the
lowercase base32 alphabet, which is 100 random bits, 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 read it from a raw config, as the parser of a
guest type can drop a 'meta' property with members it does not know.

100 bits make a duplicate practically impossible, and the uid still fits
into a 128-bit value with 28 bits to spare, for example for a format
version and extra data, should a later format need them. Base32 keeps it
at 20 characters, about half the width of a UUID in its usual notation,
and only uses lowercase letters and digits. Each character comes from a
random byte of its own, so no encoder is needed.

The registration time is the time a guest got its uid in this cluster.
Unlike the creation time, which a clone, a restore and a migration from
another cluster copy along with the guest, it changes when a guest is
registered again. Tools can use it to tell a restored guest from the one
they knew, also if both have the same uid.

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, with a shared
schema for API results; missing version information counts as too old.

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

changes v1 -> v2:
* use v5.36 and signatures
* take each character of the uid from a random byte of its own, without
  an encoder (Dominik)
* add a helper to read the identity from a raw config, shared by the
  config write and the VM restore, which picks the 'meta' line like
  pmxcfs does
* add the schema of the migration precondition result, shared by both
  guest types
* explain the format, the difference between rtime and ctime, and why
  the generic property string helpers are not used (Dominik)
* shorter description of the uid

NOTE: MIN_PVE_MANAGER_VERSION (9.2.31) 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.

 src/Makefile                      |   1 +
 src/PVE/GuestIdentity.pm          | 235 +++++++++++++++++++++
 src/tests/Makefile                |   7 +-
 src/tests/guest-identity-tests.pl | 338 ++++++++++++++++++++++++++++++
 4 files changed, 579 insertions(+), 2 deletions(-)
 create mode 100644 src/PVE/GuestIdentity.pm
 create mode 100755 src/tests/guest-identity-tests.pl

diff --git a/src/Makefile b/src/Makefile
index 161dbe5..af4c277 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -10,6 +10,7 @@ install: PVE
 	install -m 0644 PVE/AbstractMigrate.pm ${PERL5DIR}/PVE/
 	install -m 0644 PVE/GuestHelpers.pm ${PERL5DIR}/PVE/
 	install -m 0644 PVE/GuestID.pm ${PERL5DIR}/PVE/
+	install -m 0644 PVE/GuestIdentity.pm ${PERL5DIR}/PVE/
 	install -m 0644 PVE/Replication.pm ${PERL5DIR}/PVE/
 	install -m 0644 PVE/ReplicationConfig.pm ${PERL5DIR}/PVE/
 	install -m 0644 PVE/ReplicationState.pm ${PERL5DIR}/PVE/
diff --git a/src/PVE/GuestIdentity.pm b/src/PVE/GuestIdentity.pm
new file mode 100644
index 0000000..b4e3582
--- /dev/null
+++ b/src/PVE/GuestIdentity.pm
@@ -0,0 +1,235 @@
+package PVE::GuestIdentity;
+
+use v5.36;
+
+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.
+#
+# 100 random bits make a duplicate uid practically impossible, a billion uids contain one with a
+# probability of about 4 * 10^-13, and still leave 28 bits of a 128-bit value free, for example for
+# a format version and extra data, should a later format need them. Base32 keeps the uid at 20
+# characters, about half the width of a UUID in its usual notation, and only uses lowercase letters
+# and digits, which need no quoting in a property string.
+#
+# Unlike the creation time 'ctime' of the same property, which a clone, a restore and a migration
+# from another cluster copy along with the guest, the rtime belongs to the uid of the guest in this
+# cluster: it is the time the guest got its uid here, be it a new one or one it took over. So a
+# changed rtime tells that a guest was registered again, even if its uid is the same as before.
+
+# 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.31';
+
+my $UID_LENGTH = 20;
+my $UID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+my $UID_PATTERN = "[a-z2-7]{$UID_LENGTH}";
+
+# 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($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);
+}
+
+# Returns a random uid. Each character comes from the lowest 5 bits of a random byte of its own, so
+# it is uniformly distributed over the alphabet.
+my sub random_uid() {
+    my $bytes = __random_bytes($UID_LENGTH);
+
+    return join('', map { substr($UID_ALPHABET, ord($_) & 31, 1) } split(//, $bytes));
+}
+
+my sub is_valid_uid($uid) {
+    return defined($uid) && $uid =~ m/^$UID_PATTERN\z/;
+}
+
+my sub is_valid_rtime($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. A restore or a migration from another"
+                . " cluster keeps it if no other guest in the cluster uses it. A restore also does"
+                . " not take it over with 'unique', or when it overwrites a guest that 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($uid = undef) {
+    die "invalid guest identity uid '$uid'\n" if defined($uid) && !is_valid_uid($uid);
+
+    return {
+        uid => $uid // random_uid(),
+        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.
+#
+# This does not use PVE::JSONSchema::parse_property_string on purpose. That parser rejects the
+# whole string if one member is unknown or invalid. A guest without a readable identity gets a new
+# one with the next config write, so a problem with another member must not hide the uid.
+sub parse_identity($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, also ones unknown to this version, which
+# PVE::JSONSchema::print_property_string would reject.
+sub merge_identity($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 the identity in the top-level section of the raw guest config $raw, undef if it has none.
+# Only looks at the 'meta' property, so this also finds the identity in a config that the parser of
+# the guest type rejects or reads without 'meta', for example because of members from a newer
+# version.
+#
+# If a manual edit left more than one 'meta' line, the last one with anything after the colon
+# counts, also if that is only whitespace. The property lookup of pmxcfs does the same, and the
+# cluster-wide check of adopt uses it.
+sub parse_identity_from_raw_config($raw) {
+    my $meta;
+    for my $line (split(/\n/, $raw)) {
+        last if $line =~ m/^\[/; # snapshot or other section
+        $meta = $1 =~ s/^\s+|\s+$//gr if $line =~ m/^meta:(.+)$/;
+    }
+
+    return parse_identity($meta);
+}
+
+# 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($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) : () };
+}
+
+# Returns the JSON schema of what node_identity_unsupported returns for a refused node, for the
+# result of API calls that report why a node is not allowed as migration target. Every call returns
+# a new copy.
+sub node_identity_unsupported_schema() {
+    return {
+        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',
+            },
+        },
+    };
+}
+
+# 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($node) {
+    my $unsupported = node_identity_unsupported($node) or return;
+    my ($version, $required) = $unsupported->@{qw(version required-version)};
+
+    if (!defined($version)) {
+        die "node '$node' does not report its Proxmox VE version, so it is unknown whether the node"
+            . " keeps the guest identity\n";
+    }
+
+    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 8eb38a8..e2c3d01 100644
--- a/src/tests/Makefile
+++ b/src/tests/Makefile
@@ -1,8 +1,8 @@
 
 all:
 
-.PHONY: check abstract-config guest-id hookscript
-check: abstract-config guest-id hookscript
+.PHONY: check abstract-config guest-id guest-identity hookscript
+check: abstract-config guest-id guest-identity hookscript
 
 abstract-config: abstract-config-tests.pl
 	perl -I.. ./abstract-config-tests.pl
@@ -10,5 +10,8 @@ abstract-config: abstract-config-tests.pl
 guest-id: guest-id-tests.pl
 	perl -I.. ./guest-id-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..241e18c
--- /dev/null
+++ b/src/tests/guest-identity-tests.pl
@@ -0,0 +1,338 @@
+#!/usr/bin/perl
+
+use v5.36;
+
+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; },
+    );
+
+    # each byte gives one character, its lowest 5 bits select it from the lowercase RFC 4648 base32
+    # alphabet
+    my $vectors = [
+        ["\x00" x 20, 'a' x 20],
+        ["\xff" x 20, '7' x 20],
+        ['0123456789abcdefghij', 'qrstuvwxyzbcdefghijk'],
+        [pack('C*', 0 .. 19), 'abcdefghijklmnopqrst'],
+        [pack('C*', 12 .. 31), 'mnopqrstuvwxyz234567'],
+        [pack('C*', map { $_ | 0xe0 } 0 .. 19), 'abcdefghijklmnopqrst'],
+    ];
+
+    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 of them comes from 8 of the 256 values of
+    # the byte at that position
+    my $alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
+    my $mismatches = 0;
+    for my $position (0 .. 19) {
+        for my $value (0 .. 255) {
+            my $bytes = "\x00" x 20;
+            substr($bytes, $position, 1) = chr($value);
+            $random_bytes = [$bytes];
+            my $expected = 'a' x 20;
+            substr($expected, $position, 1) = substr($alphabet, $value % 32, 1);
+            $mismatches++ if PVE::GuestIdentity::new_identity()->{uid} ne $expected;
+        }
+    }
+    is($mismatches, 0, 'each character comes from the byte at its position');
+
+    $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 'parse identity from raw config' => sub {
+    my $uid = 'gaytemzugu3doobzmfrg';
+    my $other = 'aaaqeayeaudaocajbifq';
+    my $identity = { uid => $uid, rtime => 123 };
+    my $tests = [
+        ['', undef, 'empty config'],
+        ["memory: 512\n", undef, 'no meta'],
+        [
+            "memory: 512\nmeta: ctime=1,rtime=123,uid=$uid\ncores: 2\n",
+            $identity,
+            'top-level meta',
+        ],
+        ["meta:   rtime=123,uid=$uid  \n", $identity, 'surrounding whitespace'],
+        ["meta: rtime=1,uid=$other\nmeta: rtime=123,uid=$uid\n", $identity, 'last meta wins'],
+        ["meta: future=a b,rtime=123,uid=$uid\n", $identity, 'unknown members'],
+        ["meta: rtime=123,uid=$uid\nmeta:\n", $identity, 'meta line without value is ignored'],
+        [
+            "meta: rtime=123,uid=$uid\nmeta:   \n", undef, 'meta line with only spaces counts',
+        ],
+        ["#meta: rtime=123,uid=$uid\n", undef, 'description line'],
+        ["memory: 512\n\n[PENDING]\nmeta: uid=$uid\n", undef, 'pending section is ignored'],
+        [
+            "meta: rtime=123,uid=$uid\n\n[snap]\nmeta: rtime=1,uid=$other\n",
+            $identity,
+            'snapshot section is ignored',
+        ],
+    ];
+
+    for my $test (@$tests) {
+        my ($raw, $expected, $name) = @$test;
+        is_deeply(PVE::GuestIdentity::parse_identity_from_raw_config($raw), $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");
+    }
+
+    my $schema = PVE::GuestIdentity::node_identity_unsupported_schema();
+    isnt(
+        $schema,
+        PVE::GuestIdentity::node_identity_unsupported_schema(),
+        'schema is a new copy',
+    );
+    for my $node (qw(older invalid missing malformed)) {
+        my $unsupported = PVE::GuestIdentity::node_identity_unsupported($node);
+        eval { PVE::JSONSchema::validate($unsupported, $schema) };
+        is($@, '', "reason for '$node' matches the schema");
+    }
+
+    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





  parent reply	other threads:[~2026-11-17 22:42 UTC|newest]

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

Reply instructions:

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

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

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

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

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

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

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