| single |
# Proxbox
Proxbox is a NetBox plugin that synchronizes Proxmox infrastructure data
into NetBox. It keeps your DCIM up-to-date with real Proxmox clusters,
nodes, virtual machines, containers, backups, and Firecracker micro-VM
inventory used by the NMS Cloud runtime.
![netbox-proxbox architecture]
## What It Does
Proxbox discovers and syncs the following from Proxmox into NetBox:
- **Clusters and Nodes** — Proxmox cluster name, mode
(cluster/standalone), quorum status, node count, and Proxmox VE version.
Each node includes online status, IP address, CPU usage, memory usage, and
uptime at sync time. Optionally link to NetBox Cluster and Device objects.
- **Virtual Machines** — VM status, resources, and configuration
- **Containers (LXC)** — Container details and settings
- **Firecracker Cloud inventory** — Host pools, host-agent VMs, image
templates, and provisioned micro-VMs exposed separately from QEMU/LXC for
NMS Cloud provisioning
- **VM Snapshots** — Point-in-time snapshots for recovery
- **VM Backups** — Backup jobs and restore points
- **Storage** — Datastores and storage content
- **Network Interfaces and IPs** — Proxmox NICs (`net0`, `net1`) as core
NetBox VM interfaces, optional guest-OS interfaces (`ens18`, `eth0`) as
plugin `GuestVMInterface` rows, and IP addresses assigned to VMs and
containers
- **Backup Routines** — Backup job definitions from Proxmox
- **Replications** — Replication job status and configuration
- **Opt-in service monitoring** — Proxmox endpoint systemd service state
collected through the optional `netbox-rpc` procedure
`os.linux.proxmox.show_systemctl_services`
> **Note:** All metrics (CPU, memory, uptime, etc.) are captured as
point-in-time snapshots at sync time, not continuous monitoring.
Sync runs on-demand from the NetBox UI or scheduled automatically via
NetBox's job system.
Backend API keys are adopted fail-closed without making the token field
mandatory. The exact URL/IP, port, and TLS policy saved in the NetBox UI is
the
automatic-discovery allowlist: the plugin probes only that configured
target,
never follows redirects, reuses an encrypted key only after the target
accepts
it, and generates a key only for an empty backend's one-time bootstrap.
With no
endpoint row, discovery is bounded to `PLUGINS_CONFIG` and same-site names
derived from NetBox's trusted public origin; it never scans the network. An
initialized backend whose key is not locally recoverable remains
fail-closed
and pending. Disabled endpoint rows make no network calls. Operators can
still
submit a key explicitly for manual rotation or recovery.
## Additional Optional Plugins
Proxbox can be extended with standalone companion plugins. Install only the
plugins you need; `netbox-proxbox` remains the base plugin and must be
enabled
before any companion plugin. The infrastructure inventory plugins declare
`netbox-proxbox>=0.0.18` as a dependency, while `netbox-packer` and
`netbox-rpc` follow the same operational conventions for the Proxbox plugin
family. `netbox-rpc` is an *operational* companion: when it is installed,
netbox-proxbox can run audited SSH procedures against Proxmox hosts (for
example installing the proxbox-api cloud-image-build SSH key on a node, or
collecting systemd service status for an endpoint) through the netbox-rpc
engine
instead of handling SSH itself. The integration is a soft dependency —
see
`netbox_proxbox/integrations/rpc.py`.
A companion package being present in the virtual environment does not
enable
its Django app. Proxbox registers branching signals and PDM URL overrides
only
when `netbox_branching` or `netbox_pdm`, respectively, is listed in
`PLUGINS`;
installed-but-disabled companions therefore remain inert. Once a companion
is
enabled, its imports are mandatory and startup fails if the installation is
broken. Encryption recovery is the one fail-closed maintenance exception:
netbox-pbs older than `0.0.1.post1` may start so its migrations can run,
but
recovery and key mutation remain blocked until its encrypted-field schema
is
upgraded.
| Package | NetBox plugin | What it adds |
|---------|---------------|--------------|
| [`netbox-pdm`] | `netbox_pdm` | Inventories Proxmox Datacenter Manager
endpoints and the PVE/PBS remotes managed by PDM. It links PDM remotes back
to Proxbox Proxmox endpoints and, when installed, `netbox-pbs` backup
servers. |
| [`netbox-pbs`] | `netbox_pbs` | Inventories Proxmox Backup Server
infrastructure, including PBS servers, datastores, backup snapshots, and
scheduled job history. |
|