{"id":45782464,"url":"https://github.com/patricklind/proxmox2netbox","last_synced_at":"2026-04-20T11:10:04.412Z","repository":{"id":340415381,"uuid":"1165952980","full_name":"patricklind/Proxmox2Netbox","owner":"patricklind","description":"Netbox Plugin for integration between Proxmox and Netbox","archived":false,"fork":false,"pushed_at":"2026-03-01T14:49:15.000Z","size":5746,"stargazers_count":2,"open_issues_count":2,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T19:30:43.792Z","etag":null,"topics":["netbox-plugin","proxmox"],"latest_commit_sha":null,"homepage":"","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/patricklind.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":null,"dco":null,"cla":null},"funding":{"github":"emersonfelipesp"}},"created_at":"2026-02-24T18:11:15.000Z","updated_at":"2026-03-01T14:49:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"83845728-6e05-4450-9eef-7a7960e3619b","html_url":"https://github.com/patricklind/Proxmox2Netbox","commit_stats":null,"previous_names":["patricklind/netbox-proxbox","patricklind/proxmox2netbox"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/patricklind/Proxmox2Netbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patricklind%2FProxmox2Netbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patricklind%2FProxmox2Netbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patricklind%2FProxmox2Netbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patricklind%2FProxmox2Netbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patricklind","download_url":"https://codeload.github.com/patricklind/Proxmox2Netbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patricklind%2FProxmox2Netbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30018497,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T17:00:27.440Z","status":"ssl_error","status_checked_at":"2026-03-02T17:00:03.402Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["netbox-plugin","proxmox"],"created_at":"2026-02-26T11:12:30.731Z","updated_at":"2026-04-20T11:10:04.402Z","avatar_url":"https://github.com/patricklind.png","language":"Python","funding_links":["https://github.com/sponsors/emersonfelipesp"],"categories":[],"sub_categories":[],"readme":"# Proxmox2NetBox\n\nNetBox plugin for synchronizing Proxmox inventory data into NetBox (NetBox v4).\n\n\u003e [!WARNING]\n\u003e We are aware that there are issues in the codebase.\n\u003e This is a hobby project maintained in spare time.\n\u003e Fixes and improvements are implemented when time allows.\n\u003e Do not deploy in production without proper validation.\n\n## Compatibility\n\n- NetBox: `\u003e=4.2.0, \u003c5.0.0`\n- Python: `\u003e=3.11`\n- Plugin package version in this repository: `1.2.10`\n\n## What Works (Current Runtime)\n\nOut-of-the-box sync requires only a configured **Proxmox Endpoint** in NetBox.\n\nImplemented sync flows:\n\n- Proxmox nodes → NetBox `dcim.Device`\n- Proxmox QEMU/LXC VMs → NetBox `virtualization.VirtualMachine`\n- VM interfaces from Proxmox config → NetBox `virtualization.VMInterface`, with per-interface IP assignment\n- QEMU guest-agent IPs as fallback when static config lacks IPs (MAC-based interface matching)\n- Endpoint-level **Site** and **VRF** mapping — devices and IPs are placed in the correct NetBox Site/VRF\n- Endpoint-level **Node Device Type** — select a real NetBox DeviceType (e.g. Dell PowerEdge R740) for synced nodes; falls back to generic *Proxmox Node* type\n- **Per-node Device Type Mapping** — override device type per individual node name via *Node Type Mappings* UI (`Plugins → Proxmox2NetBox → Configuration → Node Type Mappings`)\n- **Per-endpoint sync controls** — enable/disable each endpoint and choose nodes, QEMU VMs, LXC containers, VM interfaces, VM IPs, guest-agent IP fallback, virtual disks, and stale-object pruning\n- Endpoint metadata refresh (`mode`, `version`, `repoid`, cluster name)\n- Sync process tracking in `SyncProcess`\n- Stale IP cleanup — plugin-managed IPs removed from Proxmox config are removed from NetBox interfaces when endpoint pruning is enabled\n\n## Runtime Architecture (Source of Truth)\n\nCore sync logic is consolidated in:\n\n- `proxmox2netbox/services/proxmox_sync.py`\n\nBackward-compatible import shim (kept intentionally):\n\n- `proxmox2netbox/proxmox_sync.py`\n\nPrimary runtime entrypoints:\n\n- UI endpoints: `proxmox2netbox/views/sync.py`\n- Connection/status badge: `proxmox2netbox/views/keepalive_status.py`\n- Proxmox card data: `proxmox2netbox/views/cards.py`\n- Job wrapper: `proxmox2netbox/jobs.py` (`Proxmox2NetBoxSyncJob`)\n\n## Installation (NetBox v4)\n\n### 1. Install plugin package\n\nInside NetBox environment:\n\n```bash\npip install proxmox2netbox\n```\n\nIf you run `netbox-docker`, also pin the package in your Docker requirements file so it survives rebuilds/redeploys:\n\n```text\n# local_requirements.txt\nproxmox2netbox==1.2.10\n```\n\n### 2. Enable plugin\n\nIn NetBox `configuration.py`:\n\n```python\nPLUGINS = [\"proxmox2netbox\"]\n```\n\n### 3. Run migrations/static\n\n```bash\npython manage.py migrate\npython manage.py collectstatic --no-input\n```\n\n## Configure and Run Sync\n\n### Configure Proxmox Endpoint\n\nIn NetBox UI:\n\n- `Plugins -\u003e Proxmox2NetBox -\u003e Endpoints -\u003e Proxmox Endpoints`\n- Create at least one endpoint with:\n  - `username`\n  - either `password` **or** (`token_name` + `token_value`)\n  - host via `domain` and/or `ip_address`\n  - optional NetBox Site/VRF/Node Device Type mapping\n  - optional sync controls for what this endpoint may create, update, and prune\n\nPer-endpoint sync controls default to the previous behavior: endpoint enabled,\nnodes enabled, QEMU and LXC VM sync enabled, VM interfaces/IPs/disks enabled,\nguest-agent IP fallback enabled, and stale plugin-managed interfaces/IPs/disks\npruned when Proxmox no longer reports them.\n\n### NetBox Permissions\n\nFor regular NetBox users, use object permissions:\n\n- `view` on `proxmox2netbox.ProxmoxEndpoint` to open the plugin home page and\n  endpoint status cards\n- `change` on `proxmox2netbox.ProxmoxEndpoint` to run manual sync actions or\n  change the sync schedule\n- `view` on `proxmox2netbox.SyncProcess` to view sync history\n- `view/add/change/delete` on `proxmox2netbox.ProxmoxNodeTypeMapping` to manage\n  per-node device type mappings\n\n### Run sync from UI\n\n- `Plugins -\u003e Proxmox2NetBox -\u003e Full Update`\n- Available actions:\n  - `Sync Nodes`\n  - `Sync Virtual Machines`\n  - `Full Update Sync`\n\n### Run sync as NetBox Job (wrapper)\n\n`jobs.py` provides a queue-compatible wrapper around the existing service layer.\n\nExample from NetBox shell:\n\n```python\nfrom proxmox2netbox.jobs import Proxmox2NetBoxSyncJob\nfrom proxmox2netbox.choices import SyncTypeChoices\n\n# Full sync\nProxmox2NetBoxSyncJob.enqueue(sync_type=SyncTypeChoices.ALL)\n\n# Devices only\nProxmox2NetBoxSyncJob.enqueue(sync_type=SyncTypeChoices.DEVICES)\n\n# Virtual machines only\nProxmox2NetBoxSyncJob.enqueue(sync_type=SyncTypeChoices.VIRTUAL_MACHINES)\n```\n\nBehavior note:\n\n- Job class is an orchestrator only.\n- Sync mapping, payloads, and upsert logic remain in `services/proxmox_sync.py`.\n\n## Development \u0026 Validation\n\n### Static checks\n\n```bash\nruff check proxmox2netbox --select F401,F403,F811,F821,F841,E712\npython -m compileall -q proxmox2netbox\n```\n\n### Django checks (inside NetBox runtime)\n\n```bash\npython manage.py check\npython manage.py makemigrations --check --dry-run\n```\n\n### Tests\n\nThe repository includes pytest coverage for the sync services, parsers, API\nviews, and UI views.\n\n```bash\npytest\n```\n\n## Publish to PyPI\n\n### Prerequisites\n\n- You must have access to the [`proxmox2netbox`](https://pypi.org/project/proxmox2netbox/) project on PyPI.\n- If the name is unavailable for your account, change `project.name` in `pyproject.toml` to a unique name before publishing.\n- Configure a matching Trusted Publisher in PyPI for this GitHub repository/workflow:\n- Owner: `patricklind`\n- Repository: `Proxmox2Netbox`\n- Workflow file: `.github/workflows/publish-python-package.yml`\n- Environment name: `pypi`\n\n### Local preflight\n\n```bash\npython -m build\ntwine check dist/*\n```\n\n### Publish via GitHub Actions\n\n- Bump `version` in `pyproject.toml` and plugin config version in source.\n- Create and push a tag:\n\n```bash\ngit tag -a vX.Y.Z -m \"Release vX.Y.Z\"\ngit push origin vX.Y.Z\n```\n\n- `release.yml` creates the GitHub Release from the tag after lint/tests pass.\n- `publish-python-package.yml` publishes to PyPI using GitHub OIDC Trusted Publisher.\n- If no publish run appears after the release is created, run **Publish Python Package** manually from Actions for the same tag. GitHub releases created by Actions with `GITHUB_TOKEN` do not always emit a follow-up event that starts another workflow.\n- After publish:\n\n```bash\npip install proxmox2netbox\n```\n\n## Repository Layout (Relevant Runtime Files)\n\n```text\nproxmox2netbox/\n  __init__.py\n  jobs.py\n  choices.py\n  filtersets.py\n  navigation.py\n  models/\n    __init__.py              # ProxmoxEndpoint, ProxmoxNodeTypeMapping, SyncProcess\n  services/\n    proxmox_sync.py          # Core sync logic (nodes, VMs, interfaces, IPs)\n  proxmox_sync.py            # Backward-compat import shim\n  views/\n    __init__.py\n    sync.py\n    keepalive_status.py\n    cards.py\n    node_type_mapping.py     # CRUD views for ProxmoxNodeTypeMapping\n  forms/\n    __init__.py\n    proxmox.py               # Endpoint + NodeTypeMapping forms\n  tables/\n    __init__.py\n  api/\n    serializers.py           # Endpoint, node type mapping, and sync process serializers\n    views.py                 # NetBox REST API viewsets\n  migrations/\n    0001_initial.py … 0020_endpoint_sync_controls.py\n  templates/\n    proxmox2netbox/\n      home.html\n      proxmoxendpoint.html\n      proxmoxnodetypemapping.html\n      syncprocess.html\n      inc/\n  urls.py\n```\n\n## Scope\n\nThis repository ships a NetBox plugin runtime only.  \nLegacy FastAPI/backend-service components are removed from runtime, docs, and packaging scope.\n\n## Wiki\n\n- GitHub Wiki URL: `https://github.com/patricklind/Proxmox2Netbox/wiki`\n- Wiki source files in this repository: `wiki/`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatricklind%2Fproxmox2netbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatricklind%2Fproxmox2netbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatricklind%2Fproxmox2netbox/lists"}