netbox-proxbox 0.0.15

Netbox Plugin - Integrate Proxmox and Netbox

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, and backups.

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
• VM Snapshots — Point-in-time snapshots for recovery
• VM Backups — Backup jobs and restore points
• Storage — Datastores and storage content
• Network Interfaces and IPs — Network interfaces and IP addresses assigned to VMs and containers
• Backup Routines — Backup job definitions from Proxmox
• Replications — Replication job status and configuration

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.

What's New in v0.0.15

Paired with backend proxbox-api 0.0.11; the new /intent/* HTTP surface pairs with proxbox-api 0.0.12:

• Opt-in NetBox → Proxmox intent path (issue #377, twelve sub-PRs A–L). Operators declare desired VM/LXC state on a NetBox branch; merging the branch triggers proxbox-api to apply CREATE / UPDATE / DELETE against Proxmox. Gated by ProxboxPluginSettings.netbox_to_proxmox_enabled (default False) plus the typed-confirmation phrase allow-edit-and-add-actions.
• Safe-delete via DeletionRequest — merging a branch with VM DELETE diffs never calls Proxmox destroy. The plugin creates a DeletionRequest, tags the VM proxbox-pending-deletion, and waits for a separate user holding authorize_deletion_request to approve. Self-approval is rejected unless intent_apply_authorization_self_approve_allowed=True.
• Cloud-Init payload — four new VM custom fields (cloud_init_user, cloud_init_ssh_keys, cloud_init_user_data, cloud_init_network) map to Proxmox ciuser, sshkeys (URL-encoded), cicustom, and ipconfig0. Plain-text passwords in cloud_init_user_data are flagged at plan time and scrubbed from every journal entry.
• Apply-Jobs and Deletion-Requests UI — /plugins/proxbox/intent/apply-jobs/ and /plugins/proxbox/intent/deletion-requests/ with live SSE log streaming, audit-chain rendering, and a plan-summary view per branch.
• Cluster HA visibility — new per-VM HA tab and cluster-wide HA Status page, both fetched live from proxbox-api (no persistence, no migration). See HA feature.
• Use HTTPS decoupled from Verify SSL on FastAPIEndpoint — supports the *-nginx image's self-signed mkcert TLS without disabling cert verification globally. See Backend Setup.
• proxbox_sync headless command — python manage.py proxbox_sync enqueues the same full-update job as the UI button; usable from cron, systemd timers, or CI. See Headless Sync.
• Runtime sync tunables on ProxboxPluginSettings (bulk_batch_size, bulk_batch_delay_ms, backup_batch_size, backup_batch_delay_ms, vm_sync_max_concurrency) plus the new overwrite_vm_type and overwrite_ip_address_dns_name flags. See Plugin Settings and Sync Overwrite Flags.
• NetBox 4.6 auto-detect — the VM type plugin pages branch automatically on the presence of NetBox 4.6's VirtualMachineType relation, keeping a working path for both 4.5.x and 4.6.x.
• Read-only reflection path is unchanged. With netbox_to_proxmox_enabled=False (default), the historic Proxmox → NetBox sync behaves exactly as in v0.0.14.

Full notes: Release Notes — v0.0.15.

Compatibility Matrix

NetBox	netbox-proxbox	proxbox-api	netbox-sdk	proxmox-sdk
>=4.5.8	v0.0.15	v0.0.11	v0.0.8.post1	v0.0.3.post1
>=4.5.8	v0.0.14	v0.0.10.post2	v0.0.8.post1	v0.0.3.post1
>=4.5.8	v0.0.13.post4	v0.0.9.post2	v0.0.7.post6	v0.0.3.post1
>=4.6.0-beta2	v0.0.13.post2	v0.0.9.post1	v0.0.7.post6	v0.0.3.post1
>=4.6.0-beta2	v0.0.13.post1	v0.0.9	v0.0.7.post6	v0.0.3.post1
>=4.6.0-beta1	v0.0.12	v0.0.8.post1	v0.0.7.post6	v0.0.3.post1
>=4.5.7	v0.0.11	v0.0.7	v0.0.7.post4	v0.0.2.post2

proxbox-api is a separate backend service in this matrix, not a Python dependency of the NetBox plugin. netbox-proxbox communicates with it over REST, SSE, and WebSocket.

Requirements

• NetBox 4.5.8, 4.5.9, or 4.6.x
• Verified with NetBox v4.5.8, v4.5.9, and official v4.6.0
• Python 3.12+
• Proxmox VE 7.x, 8.x, or 9.x (PVE 9 requires VM.GuestAgent.Audit on the API role; see "Troubleshooting" below for the PVE 9 auth checklist)
• Proxbox API backend as a separately deployed service (see below)

Quick Start

Choose the installation path that matches your NetBox deployment:

• Standard NetBox install (venv on host): follow steps below.
• NetBox Docker install (netbox-docker): use the Docker-specific workflow in Installing the Plugin in Docker-Based NetBox Deployments.

1. Install the plugin into your NetBox virtual environment (host/venv deployment):

   cd /opt/netbox/netbox
   git clone https://github.com/emersonfelipesp/netbox-proxbox.git
   source /opt/netbox/venv/bin/activate
   pip install -e ./netbox-proxbox
   

2. Enable the plugin in netbox/netbox/configuration.py:

   PLUGINS = ["netbox_proxbox"]
   

3. Run migrations and collect static files:

   python3 manage.py migrate netbox_proxbox
   python3 manage.py collectstatic --no-input
   sudo systemctl restart netbox
   

4. Install the Proxbox API backend:

   mkdir -p /opt/proxbox-api
   cd /opt/proxbox-api
   python3 -m venv venv
   source venv/bin/activate
   pip install proxbox-api
   uvicorn proxbox_api.main:app --host 0.0.0.0 --port 8800
   

   Or use Docker (the published image runs nginx on port 8000 inside the container, in front of uvicorn):

   docker run -d --name proxbox-api -p 8800:8000 emersonfelipesp/proxbox-api:latest
   

   HTTPS with mkcert (optional): the backend also publishes emersonfelipesp/proxbox-api:latest-mkcert (and :<version>-mkcert). nginx terminates TLS there (mkcert certs) on PORT (default 8000); add more certificate names or IPs with MKCERT_EXTRA_NAMES (comma- or space-separated). Example:

   docker run -d --name proxbox-api-tls \
     -p 8800:8000 \
     -e MKCERT_EXTRA_NAMES='proxbox.backend.local' \
     emersonfelipesp/proxbox-api:latest-mkcert
   

   Point your NetBox ProxBox API endpoint at https://<host>:8800 (or your mapped port). Trust the mkcert root on clients if needed; see the proxbox-api README for build flags, CAROOT, and details.

5. Configure endpoints in NetBox:

   • Go to Plugins > Proxbox
   • Create a Proxmox API endpoint (your Proxmox host URL and token). The Proxmox user/token must hold a role with Datastore.Audit, Sys.Audit, VM.Audit, VM.Monitor, and VM.GuestAgent.Audit. VM.GuestAgent.Audit is required on Proxmox VE >= 9 for the backend to pull VM IPs through the QEMU guest agent — without it, VMs sync but their IP addresses are missing from NetBox. See the proxbox-api docs Required Proxmox role privileges for the pveum role add command.
   • Create a NetBox API endpoint (your NetBox URL and token)
   • Create a ProxBox API endpoint (the backend from step 4)

6. Run your first sync:

   Click Full Update on the Proxbox home page. Progress appears in real-time.

NetBox Docker Install Option

If your NetBox runs with netbox-community/netbox-docker, install the plugin through the Docker plugin files in your NetBox Docker project:

1. Add plugin requirements to plugin_requirements.txt (PyPI or Git):

   netbox-proxbox
   # or
   # netbox-proxbox @ git+https://github.com/emersonfelipesp/netbox-proxbox.git
   

2. Enable the plugin in configuration/plugins.py:

   PLUGINS = ["netbox_proxbox"]
   

3. Rebuild and restart NetBox:

   docker compose build
   docker compose up -d
   

4. Run migrations in the NetBox container:

   docker compose exec netbox /opt/netbox/netbox/manage.py migrate
   

For complete Docker installation instructions, validation checks, and Git/source install examples, see docs/installation/3-installing-plugin-docker.md.

Scheduled Sync

Proxbox sync jobs run on NetBox's default RQ queue. A standard NetBox installation already ships a netbox-rq systemd service that runs:

manage.py rqworker high default low

Check whether it is running before doing anything else:

sudo systemctl status netbox-rq

If it is active (running), you have nothing extra to configure — Proxbox jobs will be picked up automatically.

If the service is inactive or missing, enable it:

sudo systemctl enable --now netbox-rq

The unit file is provided by NetBox at contrib/netbox-rq.service in the NetBox repository. If you need to create it manually, copy it from there and run:

sudo systemctl daemon-reload
sudo systemctl enable --now netbox-rq

Upgrading from an older Proxbox release? Jobs used to be enqueued on the netbox_proxbox.sync queue. The stock netbox-rq service does not listen to that queue, so old-style jobs will not run. New jobs always use default and are picked up without any changes.

Schedule a sync

1. In NetBox, go to Proxbox > Schedule Sync.
2. Choose one or more sync types (All, Devices, VMs, Storage, etc.).
3. Optionally set a Schedule at time and a Recurs every interval in minutes (e.g. 1440 for daily).
4. Click Schedule.

Track job status under Proxbox > Sync Jobs or Operations > Background Jobs.

Job timeout

Proxbox sync jobs default to a 7200-second (2-hour) RQ wall-clock limit (PROXBOX_SYNC_JOB_TIMEOUT). NetBox's default RQ_DEFAULT_TIMEOUT is only 300 s, which would kill long syncs. No configuration is needed unless your syncs routinely take longer than two hours; if they do, override the constant in netbox_proxbox/jobs.py.

Troubleshooting

Symptom	Likely cause	Fix
Job stays pending	No RQ worker running, or worker not listening to default queue	Start/restart manage.py rqworker
Job stays running for a long time	Proxbox API is still syncing or stream is slow	Check the job Log tab; wait or inspect the backend
Job errored: JobTimeoutException	RQ wall-clock limit exceeded	Increase PROXBOX_SYNC_JOB_TIMEOUT in netbox_proxbox/jobs.py
HTTP 401 Authentication failed! against Proxmox VE 9.x	A stale stored token is overriding fresh password credentials, or the role is missing PVE 9 permissions	On the Proxmox endpoint edit page, tick "Clear stored API token on save" (and/or "Clear stored password on save") to wipe the unused secret. The form rejects rows that end up with neither a password nor a complete (token name, token value) pair. Confirm the role on Proxmox grants Datastore.Audit, Sys.Audit, VM.Audit, and on PVE 9 also VM.GuestAgent.Audit. The plugin now surfaces the upstream PVE 9 error message in the UI instead of "Unknown error.", which makes "no such realm" / "expired token" / "missing privilege" failures self-diagnosing.

Switching credentials cleanly (PVE 9 friendly)

The Proxmox endpoint edit form preserves the stored password and token value when you submit blank masked fields — that is intentional for partial edits. When you genuinely want to switch auth modes (for example, password → token or vice versa, or rotate a leaked secret), tick the matching "Clear stored …" checkbox so the unused credential is wiped on save. Clearing the token always clears both token name and token value together so the row never persists in a half-token state.

Documentation

Full documentation is available at emersonfelipesp.github.io/netbox-proxbox.

Key pages:

• Installation Guide
• Backend Setup
• Scheduled Sync

Community

• GitHub Discussions: https://github.com/orgs/emersonfelipesp/discussions
• Discord: https://discord.gg/X6FudvXW
• Telegram: https://t.me/netboxbr

Contributing

See DEVELOP.md for development setup and contribution guidelines.

Support the Project

If Proxbox has been useful for you, consider supporting the project on GitHub Sponsors:

Sponsor Me!