{"id":13585632,"url":"https://github.com/netdevopsbr/netbox-proxbox","last_synced_at":"2025-05-14T19:07:10.871Z","repository":{"id":38401561,"uuid":"355673550","full_name":"netdevopsbr/netbox-proxbox","owner":"netdevopsbr","description":"Netbox Plugin for integration between Proxmox and Netbox","archived":false,"fork":false,"pushed_at":"2025-04-10T21:22:14.000Z","size":4840,"stargazers_count":433,"open_issues_count":43,"forks_count":55,"subscribers_count":19,"default_branch":"develop","last_synced_at":"2025-04-14T01:58:16.282Z","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":"","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/netdevopsbr.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},"funding":{"github":"emersonfelipesp"}},"created_at":"2021-04-07T20:26:30.000Z","updated_at":"2025-04-13T22:54:01.000Z","dependencies_parsed_at":"2023-10-10T22:47:25.831Z","dependency_job_id":"d666ca37-3051-4d25-9fdd-3749dfa52790","html_url":"https://github.com/netdevopsbr/netbox-proxbox","commit_stats":{"total_commits":368,"total_committers":24,"mean_commits":"15.333333333333334","dds":0.375,"last_synced_commit":"cf2d999492534277abcc0437e4bd1421317eeaad"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netdevopsbr%2Fnetbox-proxbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netdevopsbr%2Fnetbox-proxbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netdevopsbr%2Fnetbox-proxbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netdevopsbr%2Fnetbox-proxbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netdevopsbr","download_url":"https://codeload.github.com/netdevopsbr/netbox-proxbox/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248809032,"owners_count":21164895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-08-01T15:05:03.165Z","updated_at":"2025-04-14T01:58:21.871Z","avatar_url":"https://github.com/netdevopsbr.png","language":"Python","readme":"\u003e Although **Proxbox is under constant development**, I do it with **best effort** and **spare time**. I have no financial gain with this and hope you guys understand, as I know it is pretty useful to some people. If you want to **speed up its development**, solve the problem or create new features with your own code and create a **[Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)** so that I can **review** it. **I also would like to appreciate the people who already contributed with code or/and bug reports.** Without this help, surely Proxbox would be much less useful as it is already today to several environments!\n\n\n# Plugin is not currently supported on NetBox \u003ev4.0\n\nThere's already a beta release **[v0.0.6b1](https://pypi.org/project/netbox-proxbox/0.0.6b1/)** launched and I'm working on **[v0.0.6b2](https://github.com/netdevopsbr/netbox-proxbox/milestone/10)**. I hope this to be the last beta release before releasing a stable **v0.0.6** that will actually work with latest NetBox and Proxmox versions.\n\nIf you want to follow my progress, the issue **[Support for netbox 4.x](https://github.com/netdevopsbr/netbox-proxbox/issues/176)** contains all sub-issues that I'm working on and the already completed ones.\n\n\n## Netbox Plugin which integrates [Proxmox](https://www.proxmox.com/) and [Netbox](https://netbox.readthedocs.io/)!\n\n\u003e **NOTE:** Although the Proxbox plugin is in development, it only use **GET requests** and there is **no risk to harm your Proxmox environment** by changing things incorrectly.\n\n\u003cbr\u003e\n\nProxbox is currently able to get the following information from Proxmox:\n- Clusters\n- Nodes and its interfaces\n- Virtual Machines/Containers, the network interfaces and IP address (when LXC)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### Proxbox current environment and future plan.\n\n![proxbox services image](/etc/img/proxbox-services.png)\n\n### Versions\n\n\nThe following table shows the Netbox and Proxmox versions compatible (tested) with Proxbox plugin.\n\n| netbox version   | proxmox version | proxbox version | proxbox-api | pynetbox-api |\n|------------------|-----------------|-----------------|-------------|--------------|\n|------------------|-----------------|-----------------|-------------|--------------|\n| =v4.2.6          | \u003e=8.3.0         | v0.0.6b2        | v0.0.2      | v0.0.2       | \n| =v4.2.0          | \u003e=8.3.0         | v0.0.6b1        | v0.0.1      | v0.0.1       | \n| \u003e= v3.4.0        | \u003e= v6.2.0       | =v0.0.5         |             |              |\n| \u003e= v3.2.0        | \u003e= v6.2.0       | =v0.0.4         |             |              |\n| \u003e= v3.0.0 \u003c v3.2 | \u003e= v6.2.0       |  =v0.0.3        |             |              |\n\n\n\u003c/div\u003e\n\n---\n\n### Summary\n[0. Pre-Installation](#0-pre-installation)\n[1. Installation](#1-installation)\n- [1.1. Install package](#11-install-package)\n  - [1.1.1. Using pip (production use)](#111-using-pip-production-use)\n  - [1.1.2. Using git (development use)](#112-using-git-development-use)\n- [1.2. Enable the Plugin](#12-enable-the-plugin)\n- [1.3. Configure Plugin](#13-configure-plugin)\n- [1.4. Run Database Migrations](#14-run-database-migrations)\n- [1.5. systemd Setup](#15-systemd-setup-proxbox-backend)\n- [1.6 Restart WSGI Service](#15-restart-wsgi-service)\n\n[2. Usage](#3-usage)\n\n[3. Enable Logs](#4-enable-logs)\n\n[4. Roadmap](#6-roadmap)\n\n[5. Get Help from Community!](#7-get-help-from-community)\n\n---\n\n## 0. Pre-Installation\n\n### Enable HTMX Navigation on NetBox User Preferences.\n\n\u003e If not enabled, this will cause visual bugs on Proxbox GUI. For more details, [check this issue](https://github.com/netdevopsbr/netbox-proxbox/issues/277).\n\nGo to **/user/preferences** path and change enable HTMX navigation like below:\n\n![image](https://github.com/user-attachments/assets/f29d13c1-4933-4e25-b97b-81b5f3e76fe7)\n\n\n## 1. Installation\n\nThe instructions below detail the process for installing and enabling Proxbox plugin.\nThe plugin is available as a Python package in pypi and can be installed with pip.\n\n### 1.1. Install package\n\n#### 1.1.1. Using pip (production use)\n\n\u003e The latest release is a beta release, so you may find bugs.\n\nEnter Netbox's virtual environment.\n```\nsource /opt/netbox/venv/bin/activate\n```\n\nInstall the plugin package.\n\n```\npip install netbox-proxbox==0.0.6b1\n```\n\nInstall the plugin backend using docker:\n\n```\ndocker pull emersonfelipesp/proxbox-api:latest\ndocker run -d -p 8800:8800 --name proxbox-api emersonfelipesp/proxbox-api:latest\n```\n\nIf docker is not a option for you,  [click here](https://github.com/netdevopsbr/netbox-proxbox/blob/develop/proxbox_api/README.md) to see all other possible ways.\n\n\n\n#### 1.1.2. Using git (development use)\n\n**OBS:** This method is recommend for testing and development purposes and is not for production use.\n\n**TL'DR:**\n\nInstall the plugin.\n\n```\ncd /opt/netbox\nsource venv/bin/activate\ncd ./netbox\n\n# Install Netbox Plugin (netbox_proxbox package)\ngit clone https://github.com/netdevopsbr/netbox-proxbox\ncd ./netbox-proxbox\npython3 -m pip install -r requirements.txt\nuv pip install -e .\n\n# Install backend (FastAPI)\ndeactivate\ncd ./proxbox_api\npython3 -m venv venv\nsource venv/bin/activate\npython3 -m pip install uv\nuv pip install -e .\n\n# Install pynetbox-api (backend depends on it)\ngit clone https://github.com/emersonfelipesp/pynetbox-api\ncd ./pynetbox-api\nuv pip install -e .\n\n# Start Proxbox Backend\ncd ../proxbox_api\nuvicorn main:app --host 0.0.0.0 --port 8800\n\n#\n# Enable the plugin int /opt/netbox/netbox/netbox/configuration.py\n#\n\n# Finish plugin setup\ncd /opt/netbox/netbox\npython3 manage.py migrate netbox_proxbox\npython3 manage.py collectstatic --no-input\n\n\n\n\n```\n\nEnable the plugin in **/opt/netbox/netbox/netbox/configuration.py**:\n```python\nPLUGINS = ['netbox_proxbox']\n```\n\nFinish installation:\n\n```\n\n```\n\n\n\nMove to netbox main folder\n```\ncd /opt/netbox/netbox\n```\n\nClone netbox-proxbox repository\n```\ngit clone https://github.com/netdevopsbr/netbox-proxbox.git\n```\n\nInstall required packages\n\n```\ncd /opt/netbox\nsource venv/bin/activate\ncd netbox/netbox-proxbox\n\npip3 install -r requirements.txt\n```\n\nRun pynetbox-api on [develop mode (editable)](https://docs.astral.sh/uv/concepts/projects/dependencies/#editable-dependencies) using astral-uv\n```\nuv add --editable ./your-path-to-package/pynetbox-api\n```\n\nRun netbox-proxbox on develop mode\n\n```\npython3 -m pip install -e .\n```\n\n**(NEW) Install pynetbox-api package in development mode**\n\n- You must be on `netbox-proxbox` root folder.\n\n```\ngit clone https://github.com/emersonfelipesp/pynetbox-api.git\npython3 -m pip install pynetbox-api/ -e .\n```\n\nOr clone it to a totally different repository like `/opt` and use `uv` to build it as development\n```\nuv pip install -e \"pynetbox_api @ /opt/pynetbox-api\"\n```\n\n**OBS:** For now, you must manually configure `.env` on `pynetbox-api` root folder with NetBox URL and Token\n\n---\n\n### 1.2. Enable the Plugin\n\nEnable the plugin in **/opt/netbox/netbox/netbox/configuration.py**:\n```python\nPLUGINS = ['netbox_proxbox']\n```\n\n\n### 1.3. Configure Plugin\n\nAll plugin configuration is now done using NetBox GUI or its API. You can check the old configuration way [here](./PAST_CONFIG.md).\n\n---\n\n### 1.4. Run Database Migrations\n\n```\n(venv) $ cd /opt/netbox/netbox/\n(venv) $ python3 manage.py migrate netbox_proxbox\n(venv) $ python3 manage.py collectstatic --no-input\n```\n\n---\n\n### 1.5. systemd Setup (Proxbox Backend)\n\n**OBS:** It is possible to change Proxbox Backend Port (`8800`), you need to edit `proxbox.service` file and `configuration.py`\n\nEnables **read/exec permission** for **Uvicorn** use **Netbox certificates**. This is a generic way of doing it and probably **not** the **safe** option.\n```\nsudo chmod +rx -R /etc/ssl/private/\nsudo chmod +rx -R /etc/ssl/certs/\n```\n\nCopies `proxbox.service` from repository to **systemd folder** and enables it.\n```\nsudo cp -v /opt/netbox/netbox/netbox-proxbox/contrib/*.service /etc/systemd/system/\nsudo systemctl daemon-reload\nsudo systemctl enable --now proxbox\n\nsudo systemctl start proxbox\nsudo systemctl status proxbox\n```\n\nThe commands above creates the service file, enables it to run at boot time and starts it immediately.\n\n#### Optional way for developing use:\n\nThe certificates used are from Netbox, considering both applications are on the same machine.\nIf you plan to put Proxbox Backend in another host, I recommend creating another pair of certificates and enabling NGINX in front ot it.\n\n```\n/opt/netbox/venv/bin/uvicorn netbox-proxbox.proxbox_api.main:app --host 0.0.0.0 --port 8800 --app-dir /opt/netbox/netbox --ssl-keyfile=/etc/ssl/private/netbox.key --ssl-certfile=/etc/ssl/certs/netbox.crt --reload\n```\n\n#### (Developer Use Only) Creating self-signed certificates so Proxbox Backend (FastAPI) runs both HTTP and WS (Websocket) via TLS.\n\nIf you need to test the plugin without reusing Netbox certificates, you can create your own self-signed certificates and change systemd file.\n\n```\nsudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \\\n-keyout /etc/ssl/proxbox.key \\\n-out /etc/ssl/proxbox.crt\n```\n\n\u003e The certificate files created are by default located at `/etc/ssl`.\n\u003e Proxbox SystemD file needs to be changed to link to this path to find `proxbox.key` and `proxbox.crt` files.\n\u003e Consider use some HTTP Proxy like NGINX to serve FastAPI.\n\n---\n\n### 1.6. Restart WSGI Service\n\nRestart the WSGI service to load the new plugin:\n```\n# sudo systemctl restart netbox\n```\n\n---\n\n## 2. Usage\n\nIf everything is working correctly, you should see in Netbox's navigation the **Proxmox VM/CT** button in **Plugins** dropdown list.\n\nOn **Proxmox VM/CT** page, click button ![full update button](etc/img/proxbox_full_update_button.png?raw=true \"preview\")\n\nIt will redirect you to a new page and you just have to wait until the plugin runs through all Proxmox Cluster and create the VMs and CTs in Netbox.\n\n**OBS:** Due the time it takes to full update the information, your web brouse might show a timeout page (like HTTP Code 504) even though it actually worked.\n\n---\n\n## 3. Enable Logs\n\nSo that Proxbox plugin logs what is happening to the terminal, copy the following code and paste to `configuration.py` Netbox configuration file:\n\n```python\nLOGGING = {\n    'version': 1,\n    'disable_existing_loggers': False,\n    'handlers': {\n        'console': {\n            'class': 'logging.StreamHandler',\n        },\n    },\n    'root': {\n        'handlers': ['console'],\n        'level': 'INFO',\n    },\n}\n```\n\nYou can customize this using the following link: [Django Docs - Logging](https://docs.djangoproject.com/en/4.1/topics/logging/).\nAlthough the above standard configuration should do the trick to things work.\n\n---\n\n## 4. Roadmap\n- [X] Start using custom models to optimize the use of the Plugin and stop using 'Custom Fields'\n- [ ] Automatically remove Nodes on Netbox when removed on Promox (as it already happens with Virtual Machines and Containers)\n- [ ] Add individual update of VM/CT's and Nodes (currently is only possible to update all at once)\n- [ ] Add periodic update of the whole environment so that the user does not need to manually click the update button.\n- [ ] Create virtual machines and containers directly on Netbox, having no need to access Proxmox.\n- [ ] Add 'Console' button to enable console access to virtual machines\n\n---\n\n## 5. Get Help from Community!\nIf you are struggling to get Proxbox working, feel free to contact someone from community (including me) to help you.\nBelow some of the communities available:\n- **[Official - Slack Community (english)](https://netdev.chat/)**\n- **[Community Discord Channel - 🇧🇷 (pt-br)](https://discord.gg/X6FudvXW)**\n- **[Community Telegram Chat - 🇧🇷 (pt-br)](https://t.me/netboxbr)**\n\n---\n\n## Installing and using Proxbox Plugin (pt-br video)\n[![Watch the video](https://img.youtube.com/vi/Op-4MQjDf6A/maxresdefault.jpg)](https://www.youtube.com/watch?v=Op-4MQjDf6A)\n\n## Stars History 📈\n\n[![Star History Chart](https://api.star-history.com/svg?repos=netdevopsbr/netbox-proxbox\u0026type=Timeline)](https://star-history.com/#netdevopsbr/netbox-proxbox\u0026Timeline)\n","funding_links":["https://github.com/sponsors/emersonfelipesp"],"categories":["Python","Integrations"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetdevopsbr%2Fnetbox-proxbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetdevopsbr%2Fnetbox-proxbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetdevopsbr%2Fnetbox-proxbox/lists"}