From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id 83C0D1FF0DE for ; Thu, 19 Nov 2026 11:41:19 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id C736721B6C; Thu, 19 Nov 2026 11:37:05 +0100 (CET) From: Thomas Lamprecht To: pve-devel@lists.proxmox.com Subject: [PATCH docs v4 40/41] pct: configuration: describe the read-only meta property Date: Thu, 19 Nov 2026 11:34:26 +0100 Message-ID: <20261119103551.1666964-41-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261119103551.1666964-1-t.lamprecht@proxmox.com> References: <20261119103551.1666964-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: 1795084557855 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.160 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: SJAVIUQMMQ3ZWRPCM5K5BHAHAR7PEYKJ X-Message-ID-Hash: SJAVIUQMMQ3ZWRPCM5K5BHAHAR7PEYKJ 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: 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, and point to them from pct.conf(5). 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 Reviewed-by: Dominik Csapak Tested-by: Dominik Csapak --- no changes since v3 changes v2 -> v3: * point to the description from pct.conf(5) pct.adoc | 35 +++++++++++++++++++++++++++++++++++ pct.conf.adoc | 3 +++ 2 files changed, 38 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 ~~~~~~~ diff --git a/pct.conf.adoc b/pct.conf.adoc index 103b1ef..eaf568d 100644 --- a/pct.conf.adoc +++ b/pct.conf.adoc @@ -62,6 +62,9 @@ Those settings are directly passed to the LXC low-level tools. Options ------- +The read-only `meta` property is described in +xref:pct_meta_info[Meta Information]. + include::generated/pct.conf.5-opts.adoc[] -- 2.47.3