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 v5 08/41] guest identity: add helpers for the guest uid and registration time
Date: Thu, 19 Nov 2026 20:18:40 +0100	[thread overview]
Message-ID: <20261119191914.2336934-9-t.lamprecht@proxmox.com> (raw)
In-Reply-To: <20261119191914.2336934-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, for example by a restore to a free VMID. Tools can use
it to tell such a 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>
Reviewed-by: Dominik Csapak <d.csapak@proxmox.com>
Tested-by: Dominik Csapak <d.csapak@proxmox.com>
---

changes v4 -> v5:
* the description of 'uid' and a comment no longer say 'lineage', which
  suggested that clones share the uid

changes v3 -> v4:
* the stand-in MIN_PVE_MANAGER_VERSION is 9.2.33, as 9.2.31 and 9.2.32
  got released without this series
* tests: control and replacement characters in 'meta', moved here from
  the resource API test of pve-manager
* rebase (test Makefile), and 'adopt' instead of 'take over' in a
  comment

changes v2 -> v3:
* shorter description of the uid, which the status and resource APIs
  show too
* reword the comment about the size and the commit message about rtime:
  an in-place restore keeps the rtime

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.33) 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          | 232 ++++++++++++++++++++
 src/tests/Makefile                |   7 +-
 src/tests/guest-identity-tests.pl | 346 ++++++++++++++++++++++++++++++
 4 files changed, 584 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..01102ea
--- /dev/null
+++ b/src/PVE/GuestIdentity.pm
@@ -0,0 +1,232 @@
+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 (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. They also 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 adopted. 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.33';
+
+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, kept across restores and migrations"
+                . " and independent of the VMID.",
+            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 11820bf..778b296 100644
--- a/src/tests/Makefile
+++ b/src/tests/Makefile
@@ -1,8 +1,8 @@
 
 all:
 
-.PHONY: check abstract-config config-reservation firewall-config guest-id hookscript storage-tunnel
-check: abstract-config config-reservation firewall-config guest-id hookscript storage-tunnel
+.PHONY: check abstract-config config-reservation firewall-config guest-id guest-identity hookscript storage-tunnel
+check: abstract-config config-reservation firewall-config guest-id guest-identity hookscript storage-tunnel
 
 abstract-config: abstract-config-tests.pl
 	perl -I.. ./abstract-config-tests.pl
@@ -16,6 +16,9 @@ firewall-config: firewall-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..b6a7c85
--- /dev/null
+++ b/src/tests/guest-identity-tests.pl
@@ -0,0 +1,346 @@
+#!/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'],
+        # pmxcfs passes control characters on and replaces invalid UTF-8 with U+FFFD
+        ["uid=gaytemzugu\tdoobzmfrg,rtime=1", undef, 'control character in the uid'],
+        ["uid=gaytemzugu\x{FFFD}doobzmfrg,rtime=1", undef, 'replacement character in the uid'],
+        [
+            "ctime=17000\x{1}00000,rtime=1,uid=$uid",
+            { uid => $uid, rtime => 1 },
+            'control character in another member',
+        ],
+    ];
+
+    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-19 19:22 UTC|newest]

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

Reply instructions:

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

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

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

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

  git send-email \
    --in-reply-to=20261119191914.2336934-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