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 3E6D81FF0C0 for ; Wed, 18 Nov 2026 05:42:18 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id C5B02219A8; Wed, 18 Nov 2026 05:39:32 +0100 (CET) From: Thomas Lamprecht To: pve-devel@lists.proxmox.com Subject: [PATCH docs v3 38/38] pct: configuration: describe the read-only meta property Date: Wed, 18 Nov 2026 05:37:50 +0100 Message-ID: <20261118043817.1659212-39-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261118043817.1659212-1-t.lamprecht@proxmox.com> References: <20261118043817.1659212-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: 1794976703876 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.187 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: 6MTQDP7PDPO6A6R7JMBFL7CMEEO2GZRK X-Message-ID-Hash: 6MTQDP7PDPO6A6R7JMBFL7CMEEO2GZRK 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 --- changes v2 -> v3: * point to the description from pct.conf(5) no changes from v1 to v2 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