From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [45.144.208.40]) by lore.proxmox.com (Postfix) with ESMTPS id 4A60A1FF0E1 for ; Mon, 16 Nov 2026 01:49:08 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id DF7C32171C; Mon, 16 Nov 2026 01:48:30 +0100 (CET) From: Thomas Lamprecht To: pve-devel@lists.proxmox.com Subject: [PATCH guest-common 08/34] guest identity: add helpers for the guest uid and registration time Date: Mon, 16 Nov 2026 01:46:20 +0100 Message-ID: <20261116004703.2908294-9-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261116004703.2908294-1-t.lamprecht@proxmox.com> References: <20261116004703.2908294-1-t.lamprecht@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1794790029211 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.218 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: QCI7WSCE5WT2LTUUKT6IHAQTIB3XM6GZ X-Message-ID-Hash: QCI7WSCE5WT2LTUUKT6IHAQTIB3XM6GZ X-MailFrom: t.lamprecht@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: A 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 --- 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 , 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