Skip to content

Upgrading Proxbox

Plugin Upgrade Checklist

Use this flow when upgrading an existing Proxbox installation in NetBox:

cd /opt/netbox/netbox
source /opt/netbox/venv/bin/activate
pip install -U netbox-proxbox
python3 manage.py migrate netbox_proxbox
python3 manage.py collectstatic --no-input
python3 manage.py audit_node_ssh_credentials --fail-on-missing
sudo systemctl restart netbox

The SSH credential audit is a mandatory 0.0.27 upgrade gate because the retired external credential fallback no longer exists. Create a local NodeSSHCredential for every enabled API + SSH node reported as blocking, then rerun the command and proceed only after it exits successfully with zero blockers. Disabled nodes and API-only nodes are reported separately and do not block restart. After the upgrade, a request for a node without a local credential returns HTTP 404 with an actionable provisioning message; it never falls back to another credential service.

If you install from a Git checkout instead of PyPI, replace the install step with:

pip install -e /opt/netbox/netbox/netbox-proxbox

Important Notes

Reflection custom-field retirement (migrations 0085, 0086, and 0087)

Migration 0085_remove_vm_reflection_custom_fields removes the twelve VM-only reflection definitions, and migration 0086_remove_other_reflection_custom_fields removes the remaining thirty reflection definitions. Migration 0086 strips only those named keys from custom_field_data on the fourteen affected core object types; it performs no data backfill because production values were confirmed empty and the typed sidecars are already authoritative. Rows without those keys are not rewritten.

Migration 0087_remove_hardware_discovery_custom_fields removes the six hardware-discovery definitions that 0086 skipped -- hardware_chassis_manufacturer, hardware_chassis_product, hardware_chassis_serial, nic_duplex, nic_link, and nic_speed_gbps. 0086 refuses a field whose label differs from the one it expects, and proxbox-api's inventory reconcile had rewritten these six.

0087 does not try to prove which field is ours, because NetBox records nothing that could. It takes the fields of the original data type that are not operator-editable as candidates, and then leaves alone, completely, any field that still holds a value on any device or interface -- definition, bindings and stored values -- no matter who wrote that value. If you have reused one of these names for your own data, or an integration of yours populates one through the API, nothing about it changes. Only a null or an empty string counts as blank: a stored empty list or object is treated as a value and protects the field. A key present with a null or blank value is stale metadata from the retired reflection pipeline and is removed.

The check is not a single snapshot. The definitions are locked for the duration of the migration, the scan is repeated under that lock, and each key is re-tested as it is removed, so a value written while the migration runs is not lost.

Reversing 0087 restores the six definitions and their bindings with the metadata they carried, and leaves any field it skipped untouched. As with 0085 and 0086, values stripped from custom_field_data are not restored; only fields that held no value are stripped.

FastAPI key target adoption (migration 0075)

Migration 0075_fastapi_backend_key_target_fingerprint adds a durable binding between each encrypted FastAPI key and every authority that may receive it: the primary HTTP URL, fallback IP URL, TLS verification policy, and WebSocket host/port flags. Existing rows intentionally receive a blank fingerprint. New plugin code therefore blocks authenticated HTTP and server-side WebSocket traffic until an operator reviews and adopts the current target.

Before upgrading, retain the currently valid proxbox-api key in your approved secret store and record the intended domain, fallback IP, ports, HTTPS/TLS, and WebSocket settings. For the strongest cutover, stop NetBox web and RQ processes, install the package, and run the migration before restarting them.

After migration:

# Blank legacy fingerprints are reported without sending the stored key.
python manage.py proxbox_fix_tokens

# After reviewing the configured target, explicitly adopt the retained key.
python manage.py proxbox_fix_tokens --fix

--fix is the operator's consent to contact the reviewed target. It records the fingerprint when the stored key already authenticates and performs the one-time bootstrap POST only when proxbox-api proves that it has no keys. A nonblank fingerprint that no longer matches its target remains runtime-blocked. Restart NetBox to let bounded auto-configuration re-authenticate the retained key against that exact saved target, or run proxbox_fix_tokens --fix as an operator-controlled repair.

Verify that the diagnostic reports the key as registered, that the FastAPI status card can complete an authenticated version check, and that one scoped sync succeeds. If adoption fails, the local ciphertext/fingerprint remains unchanged. Correct the target and retry with the same retained key. If the remote bootstrap succeeded but the local transaction rolled back, retrying that same key is recoverable because the backend can now authenticate it. Do not create a replacement hidden key or delete the accepted remote key as a rollback tactic.

  • Proxbox 0.0.29 source supports NetBox 4.5.8 through 4.7.99, including official v4.7.0 GA and later 4.7 patch releases such as v4.7.2. It is validated against v4.5.8 through v4.5.10, v4.6.0 through v4.6.6, and exact v4.7.0 source commit 5f06007e4c9bacc93ce17c1e645fc1143d60df3d. The current sibling source and released runtime stack is proxbox-api 0.0.27.post4, proxmox-sdk 0.0.15, and netbox-sdk 0.0.13.

Current released runtime requirement: netbox-proxbox 0.0.31 requires proxbox-api 0.0.29 or later (the release that adds endpoint-owned cluster bindings). Deploy that backend before upgrading the plugin. The proxmox-sdk and netbox-sdk versions remain 0.0.15 and 0.0.13 respectively. The netbox-sdk dependency is REST-only and does not provide the semantic MCP bridge.

  • Upgrading to 0.0.31 applies 0108_v0_0_31_schema_validation after the immutable 0107_v0_0_30_release. A database already at the 0.0.30rc1 candidate applies only 0108; a database at 0106_device_sync_scope_and_netbox_token_approval applies 0107 and then 0108 in separate atomic transactions. Deploy proxbox-api 0.0.29 first, then install the plugin, run migrations and collectstatic, and restart the deployment-owned NetBox application and worker processes. Installations already at 0.0.31rc1 or 0.0.31rc2 apply no new migration.

  • Databases that applied the unpublished development migration 0107_endpoint_native_cluster_binding adopt the existing column, constraint, and data through 0107. Reversing the older 0107_v0_0_30_release migration removes the Cloud Image and SSH-service schema but keeps the native cluster ownership column and values. Reversing validation-only 0108 is a no-op that preserves all 0107 objects and data.

  • Upgrading to 0.0.29.post6 adds no migration. Upgrade to proxbox-api 0.0.27.post4 and netbox-proxbox 0.0.29.post6 in either order, then run collectstatic and restart every NetBox application and worker process.

  • Upgrading to 0.0.26.post2 retains the 0075_fastapi_backend_key_target_fingerprint trust boundary, the exact NetBox 4.7.0 GA compatibility ceiling, and adds the browser-console handoff. Run the normal manage.py migrate and collectstatic steps. Existing backend rows trust only their exact stored URL/IP, port, and TLS policy; startup discovery without a row is limited to configured or same-site targets derived from NetBox's trusted public origin. The operational state machine and verification matrix are maintained in Endpoint Auto-Configuration.
  • The vendor-neutral cloud-init credential transition is additive. Migration 0064_proxmoxvmcloudinit_intent is the sanitized fresh-install source for credential_reference_id; migration 0097_add_cloudinit_credential_reference adds that generic column on existing schemas, copies populated values from the one structurally identified historical credential column, and retains the historical column unchanged for downgrade compatibility. Upgrade producers first so they dual-write their currently deployed field and credential_reference_id, then upgrade every consumer and run the plugin migration. Verify a serialized cloud-init row preserves the reference before stopping writes to the retired field. If more than one historical *_credential_id column exists, the migration fails closed and requires an operator to resolve the schema ambiguity.
  • Upgrading to 0.0.23.post1 switches existing installs from vm_interface_sync_strategy=legacy_rename to vm_interface_sync_strategy=guest_os_model. Proxmox netX interfaces stay named netX as core VMInterface rows, and guest OS names such as ens18 are stored in GuestVMInterface rows. Operators who want the old core-interface renaming behavior can re-select vm_interface_sync_strategy=legacy_rename in plugin settings after the upgrade.
  • Disabled endpoint-like rows with enabled=False are inventory-only in 0.0.20.post3: they remain visible in UI/API output, but status, keepalive, backend registration, OpenAPI, startup/signal, sync, PBS, PDM, and companion endpoint paths return before any backend or remote-service connection attempt.
  • This release includes the PVE 9.2 schema migration plus 0045_repair_pbs_pdm_endpoint_enabled, a database-only repair for affected 0.0.18 installs where PBSEndpoint and PDMEndpoint were missing the shared endpoint enabled column. Run python manage.py migrate netbox_proxbox after upgrade.
  • If you operate the proxbox-api *-nginx image and previously could not connect, edit the FastAPI endpoint after upgrade and tick Use HTTPS (and untick Verify SSL if you use the bundled mkcert cert).
  • Recent releases moved sync execution to NetBox Jobs and the default RQ queue, so keep a standard NetBox RQ worker running after upgrade.
  • Review the release notes before jumping from older 0.0.7 or early 0.0.9 installs; the 0.0.15 line continues the NetBox 4.5.8 / 4.5.9 / 4.6 compatibility path established in 0.0.13.post4 and 0.0.14. For 0.0.15 specifically, the new NetBox→Proxmox intent path is opt-in via ProxboxPluginSettings.netbox_to_proxmox_enabled plus a typed-confirmation phrase; nothing changes for existing installs unless an operator explicitly opts in.
  • If you run proxbox-api >= 0.0.10 behind a reverse proxy and want per-client rate-limiting and brute-force lockout to track real client IPs, set PROXBOX_TRUSTED_PROXIES (CIDR list) on the backend container. Without it, X-Forwarded-For is ignored and limits apply to the proxy's IP. This is a backend-side configuration; the plugin itself does not care.
  • Upgrading from a pre-0.0.13 install introduces 16 new per-endpoint overwrite_* columns on ProxmoxEndpoint. That migration shipped in 0.0.13; 0.0.15 adds the new overwrite_ip_address_dns_name column on top.

Backend Upgrade

Upgrade the separate proxbox-api service independently of the plugin:

source /opt/proxbox-api/venv/bin/activate
pip install -U proxbox-api
sudo systemctl restart proxbox

If you run the backend in Docker, pull the new image tag and recreate the container.

After upgrading from a backend older than 0.0.13, run a Full Update from the Proxbox home page. That pass rebuilds ProxboxVirtualMachineSyncState, including proxmox_vm_id, for VMs created before the VM config fix. If the FastAPI card shows the PR #156 advisory for proxbox-api 0.0.13 or 0.0.14, install a backend build containing that fix, or the next fixed backend release, before re-testing VM IP sync.

Current release: netbox-proxbox 0.0.31 supports NetBox 4.5.8-4.7.99 stable, including v4.7.0 GA and later 4.7 patch releases. It requires proxbox-api 0.0.29 or later (the release that adds endpoint-owned cluster bindings), deployed before the plugin, with proxmox-sdk 0.0.15 and netbox-sdk 0.0.13. The netbox-sdk dependency is REST-only and does not provide the semantic MCP bridge.

Post-candidate validation boundary

Release 0.0.31rc1 adds only 0108_v0_0_31_schema_validation after the applied, immutable 0107_v0_0_30_release. Keep every numbered migration through 0107 byte- and mode-identical. The unchanged private _release_0107_schema.py checks objects introduced by 0107; its marker identifies that invariant while the actual migration executing it is 0108. It must remain 0108's last operation. The source-bound full function audit and native qualification belong to this new migration boundary, not a relabeling of the earlier pre-candidate experiment.

The 0107 and 0108 transactions commit separately. A failure in 0108 preserves an already committed 0107 and leaves 0108 unrecorded. Do not claim joint rollback, rewrite deployed history, or silently repair an unexpected schema. Reverse of 0108 is a no-op for schema/data; reapply validates again. Preserve actual recorder and data evidence for explicit reviewed recovery. The original 0107 reverse controls remain historical and do not prove that 0108 removes those objects.

The released runtime pairing is netbox-proxbox 0.0.31 with proxbox-api 0.0.29, proxmox-sdk 0.0.15, and netbox-sdk 0.0.13. Deploy and qualify the backend before the plugin.