Skip to content

Proxbox Configuration

Configuration in current Proxbox releases is split across three endpoint models plus one plugin settings object inside NetBox.

Required Endpoint Objects

Create these objects under Plugins > Proxbox before running a sync:

  1. Proxmox API: the Proxmox cluster or node you want to discover.
  2. NetBox API: the NetBox API credentials the backend will use.
  3. ProxBox API (FastAPI): the separate proxbox-api backend service.

Plugin Settings

The plugin exposes a singleton-style Proxbox plugin settings object for runtime behavior, organized into three groups:

  • Core behavior — guest-agent interface naming, Proxmox fetch concurrency, IPv6 link-local filtering.
  • NetBox integration — concurrency limits, retry policy, GET cache TTL, bulk-batch tuning, VM sync parallelism, and plugin-controlled VM reconciliation-engine selection.
  • SSRF protection — enable/disable endpoint IP validation, private IP allowances, and explicit CIDR block/allow lists.

See Plugin Settings for the full field reference. For estates with many Proxmox clusters, start with Large multi-cluster deployments.

Sync Overwrite Flags

Every overwrite_* toggle (device fields, VM fields, tags, primary IP, status) is now configurable both globally on the plugin settings object and per-endpoint on the Settings tab of each ProxmoxEndpoint. Per-endpoint values use tri-state semantics: Use plugin default, Always overwrite, or Never overwrite.

See Sync Overwrite Flags for the full flag matrix and merge-vs-replace semantics.

Node Network Topology

PLUGINS_CONFIG["netbox_proxbox"]["sync_node_interfaces"] is a strict Python boolean that defaults to False. Set it to True to make the Network Interfaces stage and full update request complete Proxmox node network topology reconciliation. This includes physical interfaces, Linux and Open vSwitch bridges and bonds, Open vSwitch internal ports, VLAN interfaces, and their NetBox Bridge, LAG, and Parent relationships. Linux bond membership additionally depends on the backend network parser recognizing the source configuration.

The option requires proxbox-api 0.0.20 or later. Non-boolean values are invalid and fail closed. Restart all NetBox application and worker processes after changing it.

Next Steps