Proposal: reusable CTID ranges and CTID-derived MAC/IP defaults #142

Proposal

Draft implementation: core#143, with configuration examples, executable regression tests, and explicit runtime-validation limits.

Add opt-in defaults for selecting a free Proxmox container ID within a configured range, then deriving network values from that ID. Keep existing defaults unchanged when these settings are absent.

My use case is a homelab where container IDs, MAC suffixes, and addresses are deliberately related:

Minimum automatic CTID: 604
Selected CTID:          612
MAC suffix:            06:12
IPv4 suffix:           .6.12
VLAN:                  6

The range, network prefix, and VLAN are administrator supplied; 6xx is only this example. A different profile can start at 3001, select CTID 3042, and map it to MAC suffix 30:42 and IPv4 suffix .30.42. Allocation bounds and address-template representability are validated separately. The MAC example uses decimal digits as visible hexadecimal characters: 612 becomes 06:12, not the hexadecimal conversion 02:64.

Deleting a container should make its ID reusable. The next installation should choose the lowest available ID at or above the configured minimum, considering both VMs and containers throughout the cluster. An optional upper bound prevents a profile spilling into another address range.

Why this belongs in core

This affects shared defaults, ID selection, and the final container network configuration rather than any application installer. The contribution guide routes engine changes here.

There is related demand in the Container Defaults System discussion: users asked about deriving IP addresses from CTIDs and using a CTID prefix with an address suffix. This proposal would extend the existing defaults mechanism.

Existing alternatives

Proxmox already supports a datacenter-wide automatic VMID range through next-id.lower and next-id.upper. Its nextid implementation searches from the lower bound and reuses holes. That is sufficient when every automatic guest allocation should share one range. Passing --vmid checks that exact ID; it is not a starting-point argument.

A Community Scripts profile would instead scope the range to these installations or to an app-specific defaults file, without changing datacenter policy. Network templates are useful with either approach.

Proposed behavior

• Optional minimum/maximum CTID settings in the existing defaults system; an explicitly chosen CTID remains possible.
• Optional MAC, IPv4, and IPv6 templates with a small documented token vocabulary. No shell expressions, eval, or arbitrary formatting programs.
• Keep VLAN, bridge, gateway, DNS, and IPv6 mode in their existing settings.
• Support MAC template + DHCP for an existing OPNsense/router reservation. Static address templates are optional; this feature must not create or modify DHCP reservations.
• Validate the expanded values before creating a container. Reject unknown tokens, invalid addresses, and IDs that cannot fit the selected representation without truncation.
• Explicit network values take precedence. Persist templates as templates, not as the generated address of one container.
• If a concurrent installer claims the selected ID, either regenerate all derived settings consistently or stop with a clear error. Never create a different ID with the previous ID's addresses.
• Make backend support explicit. Proxmox-only settings must not silently affect Incus.

Validation and limits

An isolated Bash harness exercised the actual defaults parser, allocation helper, network-option builder, and extracted collision branch at core commit fbc2e15c848d11010a9d0e82c55e99d1dfe40e97. It confirmed that literal CTID/MAC/IPv4/VLAN settings reach the builder; placeholder MAC/IP values are rejected and unknown template/minimum keys are ignored. Searching from 604 with CT 604 and VM 605 occupied returns 606, and an orphan LVM volume for 606 makes it return 607.

The collision fixture also demonstrates why templates need lifecycle handling: the existing retry changes CTID 612 to 613 while passing the unchanged MAC suffix 06:12 and IPv4 .6.12. The PoC must prevent that mismatch for generated addresses. These are executed command-boundary fixtures with external operations stubbed, not provisioned containers.

I executed the upstream Proxmox nextid callback from the pinned revision above with isolated cluster/config fixtures. Five checks passed: lower 604 with occupied 604/605/607 selects 606; freeing 604 selects 604; vmid=604 rejects an occupied exact ID; absent range settings start at 100; and native upper 606 excludes 606. This checks the upstream algorithm, not a live Proxmox API call.

The accompanying draft PoC at e6e29df has 40 passing isolated scenarios on macOS and Debian 13 ARM64, covering hole reuse, cluster-wide VM/CT occupancy, API failures, template expansion, literal overrides, defaults round trips, wizard navigation, and collision handling. Generic cases include IDs 1201, 3042, and 20012 with compatible templates and overflow rejection. Three independent review rounds resolved all reproduced findings; seven injected networking faults are detected by the tests. Upstream executable CI still awaits maintainer authorization, and real Proxmox provisioning remains unverified.

This is not an IP address manager: a free CTID does not prove that the generated IP/MAC is unused on the network. Administrators still own subnet design, DHCP exclusions/reservations, routing, and uniqueness across separate clusters. No live infrastructure changes are part of this proposal.

The configuration names and token syntax are proposed for discussion, not an established public API.