{"id":50073954,"url":"https://github.com/emersonfelipesp/netbox-proxbox","last_synced_at":"2026-07-02T00:00:19.075Z","repository":{"id":38401561,"uuid":"355673550","full_name":"emersonfelipesp/netbox-proxbox","owner":"emersonfelipesp","description":"Netbox Plugin for integration between Proxmox and Netbox","archived":false,"fork":false,"pushed_at":"2026-06-27T00:33:59.000Z","size":56095,"stargazers_count":568,"open_issues_count":0,"forks_count":64,"subscribers_count":16,"default_branch":"develop","last_synced_at":"2026-06-27T01:22:41.556Z","etag":null,"topics":["api","best-effort","community","community-driven","containers","docs","fastapi","hypervisor","kvm","netbox","netbox-plugin","opensource","proxmox","proxmoxer","pynetbox","python","qemu","virtual-machine","virtualization"],"latest_commit_sha":null,"homepage":"https://emersonfelipesp.com/netbox-proxbox","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emersonfelipesp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"emersonfelipesp","patreon":"emersonfelipesp","buy_me_a_coffee":"emersonfelipesp"}},"created_at":"2021-04-07T20:26:30.000Z","updated_at":"2026-06-26T06:02:30.000Z","dependencies_parsed_at":"2023-10-10T22:47:25.831Z","dependency_job_id":"d666ca37-3051-4d25-9fdd-3749dfa52790","html_url":"https://github.com/emersonfelipesp/netbox-proxbox","commit_stats":{"total_commits":368,"total_committers":24,"mean_commits":"15.333333333333334","dds":0.375,"last_synced_commit":"cf2d999492534277abcc0437e4bd1421317eeaad"},"previous_names":["emersonfelipesp/netbox-proxbox","netdevopsbr/netbox-proxbox"],"tags_count":66,"template":false,"template_full_name":null,"purl":"pkg:github/emersonfelipesp/netbox-proxbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emersonfelipesp%2Fnetbox-proxbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emersonfelipesp%2Fnetbox-proxbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emersonfelipesp%2Fnetbox-proxbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emersonfelipesp%2Fnetbox-proxbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emersonfelipesp","download_url":"https://codeload.github.com/emersonfelipesp/netbox-proxbox/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emersonfelipesp%2Fnetbox-proxbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35027341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","best-effort","community","community-driven","containers","docs","fastapi","hypervisor","kvm","netbox","netbox-plugin","opensource","proxmox","proxmoxer","pynetbox","python","qemu","virtual-machine","virtualization"],"created_at":"2026-05-22T04:10:14.523Z","updated_at":"2026-07-02T00:00:19.064Z","avatar_url":"https://github.com/emersonfelipesp.png","language":"Python","funding_links":["https://github.com/sponsors/emersonfelipesp","https://patreon.com/emersonfelipesp","https://buymeacoffee.com/emersonfelipesp"],"categories":[],"sub_categories":[],"readme":"# Proxbox\n\nProxbox 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.\n\n![netbox-proxbox architecture](docs/assets/netbox-proxbox-architecture.svg)\n\n## What It Does\n\nProxbox discovers and syncs the following from Proxmox into NetBox:\n\n- **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.\n- **Virtual Machines** — VM status, resources, and configuration\n- **Containers (LXC)** — Container details and settings\n- **Firecracker Cloud inventory** — Host pools, host-agent VMs, image templates, and provisioned micro-VMs exposed separately from QEMU/LXC for NMS Cloud provisioning\n- **VM Snapshots** — Point-in-time snapshots for recovery\n- **VM Backups** — Backup jobs and restore points\n- **Storage** — Datastores and storage content\n- **Network Interfaces and IPs** — Network interfaces and IP addresses assigned to VMs and containers\n- **Backup Routines** — Backup job definitions from Proxmox\n- **Replications** — Replication job status and configuration\n\n\u003e **Note:** All metrics (CPU, memory, uptime, etc.) are captured as point-in-time snapshots at sync time, not continuous monitoring.\n\nSync runs on-demand from the NetBox UI or scheduled automatically via NetBox's job system.\n\n## Additional Optional Plugins\n\nProxbox can be extended with standalone companion plugins. Install only the\nplugins you need; `netbox-proxbox` remains the base plugin and must be enabled\nbefore any companion plugin. The infrastructure inventory plugins declare\n`netbox-proxbox\u003e=0.0.18` as a dependency, while `netbox-packer` and\n`netbox-rpc` follow the same operational conventions for the Proxbox plugin\nfamily. `netbox-rpc` is an *operational* companion: when it is installed,\nnetbox-proxbox can run audited SSH procedures against Proxmox hosts (for\nexample installing the proxbox-api cloud-image-build SSH key on a node) through\nthe netbox-rpc engine instead of handling SSH itself. The integration is a soft\ndependency — see `netbox_proxbox/integrations/rpc.py`.\n\n| Package | NetBox plugin | What it adds |\n|---------|---------------|--------------|\n| [`netbox-pdm`](https://github.com/emersonfelipesp/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. |\n| [`netbox-pbs`](https://github.com/emersonfelipesp/netbox-pbs) | `netbox_pbs` | Inventories Proxmox Backup Server infrastructure, including PBS servers, datastores, backup snapshots, and scheduled job history. |\n| [`netbox-ceph`](https://github.com/emersonfelipesp/netbox-ceph) | `netbox_ceph` | Adds read-only Ceph cluster inventory for Proxmox-managed Ceph: clusters, daemons, OSDs, pools, filesystems, CRUSH rules, flags, and health checks. |\n| [`netbox-packer`](https://github.com/emersonfelipesp/netbox-packer) | `netbox_packer` | Tracks HashiCorp Packer image definitions and build execution records for Proxmox VM templates and image-factory workflows. |\n| [`netbox-rpc`](https://github.com/emersonfelipesp/netbox-rpc) | `netbox_rpc` | Audited SSH/RPC procedure engine. netbox-proxbox optionally uses it to install SSH keys on Proxmox hosts (e.g. for the cloud-image build pipeline) via `netbox_proxbox.integrations.rpc`. |\n\nFor a standard NetBox virtualenv install, activate the NetBox environment and\ninstall the packages you want:\n\n```bash\nsource /opt/netbox/venv/bin/activate\npip install netbox-pbs netbox-pdm netbox-ceph netbox-packer\n```\n\nEnable the selected plugins in `netbox/netbox/configuration.py`. Keep\n`netbox_proxbox` first. If you enable `netbox_pdm`, enable `netbox_pbs` before\nit because PDM can link to PBS server records.\n\n```python\nPLUGINS = [\n    \"netbox_proxbox\",\n    \"netbox_pbs\",\n    \"netbox_pdm\",\n    \"netbox_ceph\",\n    \"netbox_packer\",\n]\n```\n\nRun migrations for the selected plugins, preserving the same order:\n\n```bash\ncd /opt/netbox/netbox\npython3 manage.py migrate netbox_proxbox\npython3 manage.py migrate netbox_pbs\npython3 manage.py migrate netbox_pdm\npython3 manage.py migrate netbox_ceph\npython3 manage.py migrate netbox_packer\npython3 manage.py collectstatic --no-input\nsudo systemctl restart netbox netbox-rq\n```\n\nFor `netbox-docker`, add the selected packages to `plugin_requirements.txt`,\nenable the matching plugin module names in `configuration/plugins.py`, rebuild,\nand run migrations:\n\n```txt\nnetbox-pbs\nnetbox-pdm\nnetbox-ceph\nnetbox-packer\n```\n\n```bash\ndocker compose build\ndocker compose up -d\ndocker compose exec netbox /opt/netbox/netbox/manage.py migrate\n```\n\nFull companion-plugin details live under\n[docs/companion-plugins/](./docs/companion-plugins/).\n\n### Endpoint Enablement\n\nEndpoint records are inventory/configuration objects even when disabled. For\n`ProxmoxEndpoint`, `NetBoxEndpoint`, `FastAPIEndpoint`, `PBSEndpoint`,\n`PDMEndpoint`, and companion endpoint objects that expose an `enabled` field,\n`enabled=False` is a hard operational gate: netbox-proxbox keeps the row visible\nin UI/API output, but status checks, backend registration, OpenAPI fetches,\nsync scopes, keepalive probes, and startup/signal pushes must return before any\nproxbox-api or remote-service connection attempt.\n\nThe Proxmox Endpoints list shows the `Enabled` column by default. Operators can\nselect multiple rows and use **Enable Selected** or **Disable Selected** to\ntoggle the local `ProxmoxEndpoint.enabled` flag in bulk; those list actions do\nnot call proxbox-api or Proxmox.\n\nDisabled Proxmox endpoints render as a gray **Disabled** status badge on the\nlist, detail page, and dashboard card. These UI surfaces do not attach live\nstatus polling metadata for disabled rows, so the browser does not repaint an\nadministratively disabled endpoint as a red error.\n\n### Cloud Portal Endpoint Allowlists\n\n`ProxmoxEndpoint.allowed_tenants` controls which Proxmox endpoint rows are\neligible for tenant-scoped NMS Cloud callers. An empty allow-list means the\nendpoint stays in the default/global pool. A non-empty allow-list pins that\nendpoint to the listed tenants.\n\nThe paired `nms-backend` contract is intentionally asymmetric: if a tenant has\nno explicit endpoint grants, it may still see global/default endpoints; once\nthat tenant matches any explicitly granted endpoint, the backend hides the\nglobal pool and returns only the explicit matches. Use this to pin a tenant\nsuch as Confitec to a single cluster without changing the default pool for\nother tenants.\n\n## What's New in v0.0.22\n\nCurrent pairing: netbox-proxbox 0.0.22 \u003c-\u003e proxbox-api 0.0.19.post5 \u003c-\u003e proxmox-sdk 0.0.12 \u003c-\u003e netbox-sdk 0.0.10.\n\nPaired with backend [`proxbox-api 0.0.19.post5`](https://github.com/emersonfelipesp/proxbox-api).\n\n- **Per-endpoint access methods.** Proxmox endpoints now expose API-only vs API+SSH transport selection, with the selected `access_methods` value sent to the backend registration payload so backend SSH paths can enforce the same gate.\n- **Endpoint operator controls.** The form includes the Proxmox-side write-permission toggle, SSH credential-source selection, and a **Fetch host key** flow for pinned SSH fingerprints.\n- **Inventory and API coverage.** This release includes tenant allowlists, bulk endpoint enablement, PDM endpoint sync, SDN inventory, Firecracker serializer hardening, and REST coverage for PBS/PDM endpoints plus read-only DeletionRequest and ProxmoxApplyJob audit endpoints.\n- **Certification refresh.** NetBox compatibility remains `4.5.8` through `4.6.99`, now validated through NetBox `v4.6.4`.\n\nFull notes: [Release Notes - v0.0.22](docs/release-notes/version-0.0.22.md).\n\n## What's New in v0.0.21\n\nPaired with backend [`proxbox-api 0.0.18.post5`](https://github.com/emersonfelipesp/proxbox-api).\n\n- **Sync-mode filtering at source.** Per-record VM and VM-template filtering is enforced by the paired backend through `sync_mode_vm` and `sync_mode_vm_template` query params, so disabled modes no longer create dependent NetBox objects for skipped VMs.\n- **Batch and stream hardening.** VM sync uses two-phase batch processing, isolates per-VM dispatch failures, matches interface-dense guest aliases by name, and emits partial-failure stream frames for operator visibility.\n- **Current SDK pairing.** This release pairs with `proxmox-sdk 0.0.12` and `netbox-sdk 0.0.10` through the separate backend runtime.\n\nFull notes: [Release Notes - v0.0.21](docs/release-notes/version-0.0.21.md).\n\n## What's New in v0.0.20.post3\n\nPaired with backend [`proxbox-api 0.0.17.post1`](https://github.com/emersonfelipesp/proxbox-api).\n\n- **Disabled endpoints never connect.** Endpoint-like rows with `enabled=False` remain visible as inventory/configuration records, but Proxbox status, keepalive, backend registration, OpenAPI, sync, startup, signal, PBS, PDM, and companion endpoint paths now return before any proxbox-api or remote-service connection attempt.\n- **Maintenance guardrails.** LLM and developer docs now describe the all-endpoint enabled-field invariant, and the regression suite covers PBSEndpoint/PDMEndpoint shared `EndpointBase.enabled` behavior plus shared guard wiring.\n\nFull notes: [Release Notes - v0.0.20.post3](docs/release-notes/version-0.0.20.post3.md).\n\n## What's New in v0.0.20.post2\n\nPaired with backend [`proxbox-api 0.0.17.post1`](https://github.com/emersonfelipesp/proxbox-api).\n\n- **Latest Sync Jobs on the homepage.** The plugin homepage now includes a read-only table with the five latest Proxbox sync jobs and a **View all sync jobs** button after the additional plugin endpoint cards.\n\nFull notes: [Release Notes - v0.0.20.post2](docs/release-notes/version-0.0.20.post2.md).\n\n## What's New in v0.0.20.post1\n\nPaired with backend [`proxbox-api 0.0.17.post1`](https://github.com/emersonfelipesp/proxbox-api).\n\n- **VM-template sync job wiring.** `ProxboxSyncJob` now calls the existing `sync_vm_templates()` stage, so `ProxmoxVMTemplate` inventory is populated during full/scheduled syncs instead of staying empty.\n\nFull notes: [Release Notes - v0.0.20.post1](docs/release-notes/version-0.0.20.post1.md).\n\n## What's New in v0.0.20\n\nPaired with backend [`proxbox-api 0.0.17`](https://github.com/emersonfelipesp/proxbox-api).\n\n- **IP-address ownership safety.** The paired backend prevents VM-interface IP sync from taking over an address that already belongs to another interface.\n- **Interface-batch settings persistence.** `interface_batch_size` and `interface_batch_delay_ms` entered on the plugin Settings page now persist to the database.\n\nFull notes: [Release Notes - v0.0.20](docs/release-notes/version-0.0.20.md).\n\n## What's New in v0.0.19\n\nPaired with backend [`proxbox-api 0.0.16`](https://github.com/emersonfelipesp/proxbox-api).\n\n- **FastAPI endpoint token drift fix.** `FastAPIEndpoint.save()` now detects explicit token changes on existing rows and calls `_register_key_with_backend(skip_bootstrap_check=True)` so operators can recover from a proxbox-api key rotation without direct database surgery.\n- **PBS/PDM `host` compatibility property.** `PBSEndpoint` and `PDMEndpoint` now expose a `host` property bridging the field-name difference with proxbox-api's SQLite column.\n- **PBS/PDM `timeout_seconds` compatibility property.** Both models now expose a `timeout_seconds` property to match the proxbox-api SQLite column name.\n\nFull notes: [Release Notes — v0.0.19](docs/release-notes/version-0.0.19.md).\n\n## What's New in v0.0.18\n\nPaired with backend [`proxbox-api 0.0.14`](https://github.com/emersonfelipesp/proxbox-api).\n\n- **Full PVE 9.2 support.** New models for SDN fabrics, route maps, prefix lists, and custom datacenter CPU models, plus automated sync services. Completed per-node firewall sync. HA arm/disarm action views. `ProxmoxNode.location` field.\n\nFull notes: [Release Notes — v0.0.18](https://emersonfelipesp.github.io/netbox-proxbox/release-notes/version-0.0.18/).\n\n## Compatibility Matrix\n\n| NetBox | netbox-proxbox | proxbox-api | netbox-sdk | proxmox-sdk |\n|--------|----------------|-------------|------------|-------------|\n| \u003e=4.5.8 | v0.0.22 | v0.0.19.post5 | v0.0.10 | v0.0.12 |\n| \u003e=4.5.8 | v0.0.21 | v0.0.18.post5 | v0.0.10 | v0.0.12 |\n| \u003e=4.5.8 | v0.0.20.post3 | v0.0.17.post1 | v0.0.9.post1 | v0.0.11.post1 |\n| \u003e=4.5.8 | v0.0.20.post2 | v0.0.17.post1 | v0.0.9.post1 | v0.0.11.post1 |\n| \u003e=4.5.8 | v0.0.20.post1 | v0.0.17.post1 | v0.0.9.post1 | v0.0.11.post1 |\n| \u003e=4.5.8 | v0.0.20 | v0.0.17 | v0.0.8.post1 | v0.0.11 |\n| \u003e=4.5.8 | v0.0.19 | v0.0.16 | v0.0.8.post1 | v0.0.9 |\n| \u003e=4.5.8 | v0.0.18.post1 | v0.0.14 | v0.0.8.post1 | v0.0.3.post1 |\n| \u003e=4.5.8 | v0.0.18 | v0.0.14 | v0.0.8.post1 | v0.0.3.post1 |\n| \u003e=4.5.8 | v0.0.17 | v0.0.13 | v0.0.8.post1 | v0.0.3.post1 |\n\nSee [COMPATIBILITY.md](COMPATIBILITY.md) for the full version compatibility table.\n\n## Requirements\n\n- NetBox 4.5.8, 4.5.9, or 4.6.x\n- Verified with NetBox v4.5.8, v4.5.9, and v4.6.0 through v4.6.4\n- Python 3.12+\n- 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)\n- Proxbox API backend as a separately deployed service (see below)\n\n## Quick Start\n\nChoose the installation path that matches your NetBox deployment:\n\n- **Standard NetBox install (venv on host):** follow steps below.\n- **NetBox Docker install (`netbox-docker`):** use the Docker-specific workflow in [Installing the Plugin in Docker-Based NetBox Deployments](./docs/installation/3-installing-plugin-docker.md).\n\n1. **Install the plugin** into your NetBox virtual environment (host/venv deployment):\n\n   ```bash\n   cd /opt/netbox/netbox\n   git clone https://github.com/emersonfelipesp/netbox-proxbox.git\n   source /opt/netbox/venv/bin/activate\n   pip install -e ./netbox-proxbox\n   ```\n\n2. **Enable the plugin** in `netbox/netbox/configuration.py`:\n\n   ```python\n   PLUGINS = [\"netbox_proxbox\"]\n   ```\n\n3. **Run migrations and collect static files:**\n\n   ```bash\n   python3 manage.py migrate netbox_proxbox\n   python3 manage.py collectstatic --no-input\n   sudo systemctl restart netbox\n   ```\n\n4. **Install the Proxbox API backend:**\n\n   ```bash\n   mkdir -p /opt/proxbox-api\n   cd /opt/proxbox-api\n   python3 -m venv venv\n   source venv/bin/activate\n   pip install proxbox-api\n   uvicorn proxbox_api.main:app --host 0.0.0.0 --port 8800\n   ```\n\n   Or use Docker (the published image runs **nginx** on port **8000** inside the container, in front of **uvicorn**):\n\n   ```bash\n   docker run -d --name proxbox-api -p 8800:8000 emersonfelipesp/proxbox-api:latest\n   ```\n\n   **HTTPS with mkcert (optional):** the backend also publishes **`emersonfelipesp/proxbox-api:latest-mkcert`** (and `:\u003cversion\u003e-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:\n\n   ```bash\n   docker run -d --name proxbox-api-tls \\\n     -p 8800:8000 \\\n     -e MKCERT_EXTRA_NAMES='proxbox.backend.local' \\\n     emersonfelipesp/proxbox-api:latest-mkcert\n   ```\n\n   Point your NetBox **ProxBox API** endpoint at `https://\u003chost\u003e:8800` (or your mapped port). Trust the mkcert root on clients if needed; see the [proxbox-api README](https://github.com/emersonfelipesp/proxbox-api/blob/main/README.md) for build flags, `CAROOT`, and details.\n\n5. **Configure endpoints in NetBox:**\n\n   - Go to **Plugins \u003e Proxbox**\n   - Create a **Proxmox API** endpoint (your Proxmox host URL and token).\n     The Proxmox user/token must hold a role with `Datastore.Audit`,\n     `Sys.Audit`, `VM.Audit`, `VM.Monitor`, **and `VM.GuestAgent.Audit`**.\n     `VM.GuestAgent.Audit` is required on Proxmox VE \u003e= 9 for the backend to\n     pull VM IPs through the QEMU guest agent — without it, VMs sync but\n     their IP addresses are missing from NetBox. See the proxbox-api docs\n     [Required Proxmox role privileges](https://github.com/emersonfelipesp/proxbox-api/blob/main/docs/getting-started/configuration.md#required-proxmox-role-privileges)\n     for the `pveum role add` command.\n   - Create a **NetBox API** endpoint (your NetBox URL and token)\n   - Create a **ProxBox API** endpoint (the backend from step 4)\n\n6. **Run your first sync:**\n\n    Click **Full Update** on the Proxbox home page. Progress appears in real-time.\n\n## NetBox Docker Install Option\n\nIf your NetBox runs with `netbox-community/netbox-docker`, install the plugin through the Docker plugin files in your NetBox Docker project:\n\n1. Add plugin requirements to `plugin_requirements.txt` (PyPI or Git):\n\n   ```txt\n   netbox-proxbox\n   # or\n   # netbox-proxbox @ git+https://github.com/emersonfelipesp/netbox-proxbox.git\n   ```\n\n2. Enable the plugin in `configuration/plugins.py`:\n\n   ```python\n   PLUGINS = [\"netbox_proxbox\"]\n   ```\n\n3. Rebuild and restart NetBox:\n\n   ```bash\n   docker compose build\n   docker compose up -d\n   ```\n\n4. Run migrations in the NetBox container:\n\n   ```bash\n   docker compose exec netbox /opt/netbox/netbox/manage.py migrate\n   ```\n\nFor complete Docker installation instructions, validation checks, and Git/source install examples, see [docs/installation/3-installing-plugin-docker.md](./docs/installation/3-installing-plugin-docker.md).\n\n## Scheduled Sync\n\nProxbox sync jobs run on NetBox's **`default`** RQ queue. A standard NetBox installation already ships a `netbox-rq` systemd service that runs:\n\n```\nmanage.py rqworker high default low\n```\n\nCheck whether it is running before doing anything else:\n\n```bash\nsudo systemctl status netbox-rq\n```\n\nIf it is **active (running)**, you have nothing extra to configure — Proxbox jobs will be picked up automatically.\n\nIf the service is **inactive or missing**, enable it:\n\n```bash\nsudo systemctl enable --now netbox-rq\n```\n\nThe 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:\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now netbox-rq\n```\n\n\u003e **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.\n\nDisabled `ProxmoxEndpoint` rows are hard-excluded from operational reads and\nsync jobs. The scheduler, CLI sync command, dashboard cards, keepalive checks,\nHA/storage/firewall/SDN/datacenter live reads, backend endpoint preflight, and\nstale scheduled job parameters all filter to `enabled=True` before contacting\nproxbox-api or Proxmox. To pause a production endpoint, set **Enabled** to\nfalse; the row remains visible in the API and UI but no connection attempt is\nmade for that endpoint.\n\n### Schedule a sync\n\n1. In NetBox, go to **Proxbox \u003e Schedule Sync**.\n2. Choose one or more sync types (**All**, Devices, VMs, Storage, etc.).\n3. Optionally set a **Schedule at** time and a **Recurs every** interval in minutes (e.g. `1440` for daily).\n4. Click **Schedule**.\n\nTrack job status under **Proxbox \u003e Sync Jobs** or **Operations \u003e Background Jobs**.\n\n### Job timeout\n\nProxbox 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`.\n\n### Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---------|-------------|-----|\n| Job stays **`pending`** | No RQ worker running, or worker not listening to `default` queue | Start/restart `manage.py rqworker` |\n| 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 |\n| Job **`errored: JobTimeoutException`** | RQ wall-clock limit exceeded | Increase `PROXBOX_SYNC_JOB_TIMEOUT` in `netbox_proxbox/jobs.py` |\n| Disabled endpoint still appears in `/api/plugins/proxbox/endpoints/proxmox/` | Expected API behavior; disabled rows remain inventory records | Leave it disabled to prevent all connection attempts. Re-enable only when the endpoint should participate in cards, checks, and sync jobs again. |\n| VM IP addresses stay empty after upgrade | The separate `proxbox-api` backend is too old, is on the v0.0.13/v0.0.14 agent-flag warning window, existing VMs still lack `proxmox_vm_id`, or the Proxmox role lacks guest-agent privileges | Check the FastAPI card warning on the Proxbox home page. Run `proxbox-api \u003e= 0.0.13` at minimum; if the warning references PR #156, install a backend build containing that fix or the next fixed backend release. Then run **Full Update** so existing VMs get `proxmox_vm_id` before the IP-address stage runs. For PVE 9, also confirm `VM.GuestAgent.Audit`. |\n| **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. |\n\n#### Switching credentials cleanly (PVE 9 friendly)\n\nThe Proxmox endpoint edit form preserves the stored password and token value\nwhen you submit blank masked fields — that is intentional for partial edits.\nWhen you genuinely want to **switch** auth modes (for example, password → token\nor vice versa, or rotate a leaked secret), tick the matching **\"Clear\nstored …\"** checkbox so the unused credential is wiped on save. Clearing the\ntoken always clears **both** `token name` and `token value` together so the row\nnever persists in a half-token state.\n\n## Documentation\n\nFull documentation is available at [emersonfelipesp.github.io/netbox-proxbox](https://emersonfelipesp.github.io/netbox-proxbox/).\n\nKey pages:\n\n- [Installation Guide](https://emersonfelipesp.github.io/netbox-proxbox/installation/2-installing-plugin-git/)\n- [Backend Setup](https://emersonfelipesp.github.io/netbox-proxbox/installation/backend-setup/)\n- [Scheduled Sync](https://emersonfelipesp.github.io/netbox-proxbox/features/scheduled-sync/)\n- [Certification Evidence](https://emersonfelipesp.github.io/netbox-proxbox/certification/)\n- [Application Packet](https://emersonfelipesp.github.io/netbox-proxbox/application-packet/)\n\n## Community\n\n- GitHub Discussions: https://github.com/orgs/emersonfelipesp/discussions\n\n## LLM Agent Safety\n\n\u003e **Before any destruction-adjacent operation, read `AGENTS.md` §\"LLM Agent Safety Guardrails\".**\n\nProxbox protects VM destruction behind a five-lock chain. LLM agents **MUST NOT**:\n- Autonomously set `apply_destroy_confirmed=True`\n- Submit the confirmation phrase `\"allow-edit-and-add-actions\"` on a user's behalf\n- Approve a `DeletionRequest` as the same user who created it (`self_approve_allowed=False`)\n\nThe `DeletionRequest` REST endpoint (`/api/plugins/proxbox/deletion-requests/`) is read-only — enforced by `netbox_proxbox/api/views.py::DeletionRequestViewSet.http_method_names = [\"get\", \"head\", \"options\"]`. Pinned by `tests/test_static_guardrails.py`.\n\n## Contributing\n\nSee [DEVELOP.md](./DEVELOP.md) for development setup and contribution guidelines.\n\n## Support the Project\n\nIf Proxbox has been useful for you, consider supporting the project on GitHub Sponsors:\n\n[Sponsor Me!](https://github.com/sponsors/emersonfelipesp)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femersonfelipesp%2Fnetbox-proxbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femersonfelipesp%2Fnetbox-proxbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femersonfelipesp%2Fnetbox-proxbox/lists"}