MrBlake/Netbox-Better-IPs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README in English with standard structure

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
MrBlake
2026-09-30 13:36:51 +02:00
co-authored by Claude Opus 5.5
parent d904d335a9
commit 8d53a4cdb3
1 changed files with 132 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+132 -27
View File
@@ -1,27 +1,62 @@
# NetBox Better IPs # NetBox Better IPs
Plugin für **NetBox 4.6.5** mit zwei Funktionen: Automatic IP ranges from IP addresses and an IP network overview with
organisational filters.
- Beim Speichern einer IP-Adresse wird der durch deren CIDR-Maske beschriebene nutzbare IP-Bereich gesucht und, falls er fehlt, automatisch erstellt. Bei normalen IPv4-Subnetzen werden Netzwerk- und Broadcastadresse nicht in den Bereich aufgenommen. | | |
- Eine zusätzliche IP-Netzübersicht kann nach Organisation/Region, Standortgruppe, Standort, Lokation, Mandantengruppe und Mandant gefiltert werden. |---|---|
- Unter **IPAM → IP-Bereiche** legt die Aktion **Alle fehlenden Bereiche anlegen** die Bereiche für sämtliche bereits vorhandenen, sichtbaren IP-Adressen an. | **Plugin name** | `netbox_better_ips` |
- Unter **IP-Bereich → IP-Adressen** wird das zugehörige Gerät beziehungsweise die VM standardmäßig als eigene Spalte angezeigt. | **Package** | `netbox-better-ips` |
- Die **IP-Netzübersicht** ist als eigener Eintrag direkt im Menü **IPAM** verfügbar. | **NetBox** | `4.6.5` |
| **Python** | `>=3.12` |
| **Repository** | <https://git.mrblake.cc/MrBlake/Netbox-Better-IPs> |
## Features
- When an IP address is saved, the usable IP range described by its CIDR mask is looked up and created automatically if missing. For regular IPv4 subnets, network and broadcast addresses are excluded.
- An additional **IP network overview** can be filtered by organisation/region, site group, site, location, tenant group and tenant. It is available directly in the **IPAM** menu.
- Under **IPAM → IP Ranges**, the action **Create all missing ranges** creates ranges for all existing, visible IP addresses.
- Under **IP Range → IP Addresses**, the assigned device or VM is shown as its own column by default.
## Compatibility
- NetBox `4.6.5`
- Python `>=3.12`
## Installation ## Installation
```bash All paths assume a standard installation under `/opt/netbox`.
/opt/netbox/venv/bin/pip install git+https://git.mrblake.cc/MrBlake/Netbox-Better-IPs.git
``` ### 1. Install the package
```bash ```bash
echo "git+https://git.mrblake.cc/MrBlake/Netbox-Better-IPs.git" >> /opt/netbox/local_requirements.txt /opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
"git+https://git.mrblake.cc/MrBlake/Netbox-Better-IPs.git@main"
``` ```
In `configuration.py`: For reproducible production installs, replace `main` with a release tag or a
full commit ID.
### 2. Add the plugin to `local_requirements.txt`
This makes `upgrade.sh` reinstall the plugin automatically on every NetBox upgrade:
```bash
grep -qxF "git+https://git.mrblake.cc/MrBlake/Netbox-Better-IPs.git@main" /opt/netbox/local_requirements.txt \
|| echo "git+https://git.mrblake.cc/MrBlake/Netbox-Better-IPs.git@main" | sudo tee -a /opt/netbox/local_requirements.txt
```
If the repository is private, the NetBox server needs a read-only deploy token
or an SSH key. Do not store credentials in `local_requirements.txt`.
### 3. Enable the plugin
In `/opt/netbox/netbox/netbox/configuration.py`:
```python ```python
PLUGINS = ["netbox_better_ips"] PLUGINS = [
"netbox_better_ips",
]
PLUGINS_CONFIG = { PLUGINS_CONFIG = {
"netbox_better_ips": { "netbox_better_ips": {
@@ -29,31 +64,101 @@ PLUGINS_CONFIG = {
"range_status": "active", "range_status": "active",
"inherit_tenant": True, "inherit_tenant": True,
"ignore_host_prefixes": True, "ignore_host_prefixes": True,
} },
} }
``` ```
Danach NetBox neu starten. Das Plugin hat keine eigenen Datenbankmodelle und benötigt daher keine Migration. If other plugins are already configured, add `netbox_better_ips` to the existing
list and dictionary instead of replacing them.
## Verhalten ### 4. Collect static files, restart
Aus `192.0.2.17/24` wird bei Bedarf der IP-Bereich `192.0.2.1/24` bis `192.0.2.254/24` in derselben VRF erstellt. Der Mandant wird von der IP oder dem zugewiesenen Gerät/der VM übernommen. Vorhandene Bereichsmetadaten werden nie überschrieben. The plugin has no database models, so no migration is required.
Hostmasken (`/32`, `/128`) werden standardmäßig nicht als eigener Bereich erstellt. Dies kann mit `ignore_host_prefixes=False` geändert werden.
Bereits vorhandene IP-Adressen lassen sich abgleichen:
```bash ```bash
python /opt/netbox/netbox/manage.py reconcile_ip_ranges --dry-run cd /opt/netbox/netbox
python /opt/netbox/netbox/manage.py reconcile_ip_ranges /opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq
``` ```
## Berechtigungen ## Update
Für die Übersicht ist die NetBox-Berechtigung `ipam.view_prefix` erforderlich. Die automatische Erstellung läuft serverseitig; stellen Sie sicher, dass dies zu Ihrem Berechtigungs- und Change-Control-Konzept passt. ```bash
/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
"git+https://git.mrblake.cc/MrBlake/Netbox-Better-IPs.git@main"
Die Aktion für Bestandsdaten benötigt `ipam.view_ipaddress` und `ipam.add_iprange`. Sie verarbeitet nur IP-Adressen, die der ausführende Benutzer sehen darf. cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq
```
## Hinweis zu „Organisation" `--force-reinstall` makes pip pick up branch changes even if the package
version has not been bumped.
NetBox besitzt kein separates Core-Modell namens Organisation. Die Übersicht bildet Organisation auf NetBox-`Region` ab und bezieht untergeordnete Regionen sowie deren Standorte und Lokationen ein. When NetBox itself is upgraded, `upgrade.sh` reinstalls the plugin from
`local_requirements.txt`:
```bash
sudo /opt/netbox/upgrade.sh
sudo systemctl restart netbox netbox-rq
```
## Uninstall
1. Remove `"netbox_better_ips"` from `PLUGINS` and `PLUGINS_CONFIG`.
2. Remove the line from `/opt/netbox/local_requirements.txt`.
3. Uninstall the package and restart NetBox:
```bash
/opt/netbox/venv/bin/pip uninstall netbox-better-ips
sudo systemctl restart netbox netbox-rq
```
IP ranges that were created by the plugin remain in NetBox.
## Configuration
| Key | Default | Description |
|---|---|---|
| `auto_create_range` | `True` | Create the IP range automatically when an IP address is saved |
| `range_status` | `"active"` | Status of newly created ranges |
| `inherit_tenant` | `True` | Take the tenant from the IP address or its assigned device/VM |
| `ignore_host_prefixes` | `True` | Do not create ranges for host masks (`/32`, `/128`) |
## Usage
### Behaviour
For `192.0.2.17/24`, the IP range `192.0.2.1/24` – `192.0.2.254/24` is created
in the same VRF if needed. The tenant is taken from the IP address or the
assigned device/VM. Existing range metadata is never overwritten.
Host masks (`/32`, `/128`) do not get their own range by default; change this
with `ignore_host_prefixes = False`.
### Reconciling existing IP addresses
```bash
cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py reconcile_ip_ranges --dry-run
/opt/netbox/venv/bin/python manage.py reconcile_ip_ranges
```
### Permissions
The overview requires the NetBox permission `ipam.view_prefix`. Automatic range
creation runs server-side — make sure this fits your permission and change
control concept.
The action for existing data requires `ipam.view_ipaddress` and
`ipam.add_iprange`, and only processes IP addresses the executing user can see.
### Note on "Organisation"
NetBox has no separate core model called organisation. The overview maps
organisation to NetBox `Region` and includes child regions and their sites and
locations.
## License
Apache License 2.0 — see [LICENSE](LICENSE).