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 504D61FF09C for ; Mon, 05 Oct 2026 16:51:39 +0200 (CEST) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 30B46219A0; Mon, 05 Oct 2026 16:49:01 +0200 (CEST) From: =?UTF-8?q?Michael=20K=C3=B6ppl?= To: pve-devel@lists.proxmox.com Subject: [PATCH docs v7 24/24] pvecm: next-id: document unique and enforce options Date: Mon, 5 Oct 2026 16:48:05 +0200 Message-ID: <20261005144805.825538-25-m.koeppl@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261005144805.825538-1-m.koeppl@proxmox.com> References: <20261005144805.825538-1-m.koeppl@proxmox.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1791211690825 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.319 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: NDSEPULHHVCZQNV2EXOR7E6XBY2XDY6M X-Message-ID-Hash: NDSEPULHHVCZQNV2EXOR7E6XBY2XDY6M X-MailFrom: m.koeppl@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: The next-id datacenter option can now optionally only suggest guest IDs that have never been in use (through 'unique') and turn its range and uniqueness into a hart limit for new guests (through 'enforce'). Describe both options, why avoiding the reuse of guest IDs can be desirable, and how th elist of used IDs is kept small. Drop the note that the range is not a hart limit since that no longer holds with 'enforce' set. Signed-off-by: Michael Köppl --- pvecm.adoc | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/pvecm.adoc b/pvecm.adoc index 8309647a..cd5a0fb8 100644 --- a/pvecm.adoc +++ b/pvecm.adoc @@ -1566,8 +1566,37 @@ To accommodate this use case one can set either lower, upper or both boundaries via the `datacenter.cfg` configuration file, which can be edited in the web interface under 'Datacenter' -> 'Options'. -NOTE: The range is only used for the next-id API call, so it isn't a hard -limit. +By default, the lowest free VMID in the range is suggested, so the VMIDs of +destroyed guests get reused. This can be undesirable, for example, if external +backup or monitoring systems identify guests by their VMID. With the `unique` +option set, only VMIDs that have never been in use are suggested. For this, +{pve} records the VMID of every guest on creation and destruction in +`/etc/pve/virtual-guest/used-guest-ids`, independent of whether `unique` is +set. VMIDs of guests that were removed before {pve} started recording them are +not known and may still be suggested. + +The range and the `unique` option only affect which VMID is suggested. Any +other free VMID can still be chosen manually. With the `enforce` option set, +they become a hard limit instead. New guests can then only use VMIDs from the +range and, if `unique` is set as well, only VMIDs that have never been in use. +Operations on existing guests, like destroying them or restoring a backup over +them, are not restricted. + +---- +next-id: lower=10000,upper=20000,unique=1,enforce=1 +---- + +NOTE: Consecutive VMIDs are stored as a single range, so the list of used VMIDs +usually stays small. It only grows large if many VMIDs with gaps between them +are used. If the list reaches 512 KiB, a warning is logged whenever it is +updated. The list shrinks again as gaps get filled, since the ranges on both +sides of a gap are merged into a single entry once all VMIDs in it have been +used. With `unique` set, auto-selection suggests the lowest VMID that has never +been used and thereby fills the gaps from the bottom up. To stay within the file +size limit of the cluster file system, the smallest gaps between recorded VMIDs +are marked as used once the list would exceed 768 KiB. As a result, they are no +longer suggested with `unique` set and cannot be used for new guests anymore +with `enforce` set as well. Guest Migration --------------- -- 2.47.3