165 lines
5.0 KiB
Markdown
165 lines
5.0 KiB
Markdown
# NetBox Better IPs
|
||
|
||
Automatic IP ranges from IP addresses and an IP network overview with
|
||
organisational filters.
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Plugin name** | `netbox_better_ips` |
|
||
| **Package** | `netbox-better-ips` |
|
||
| **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
|
||
|
||
All paths assume a standard installation under `/opt/netbox`.
|
||
|
||
### 1. Install the package
|
||
|
||
```bash
|
||
/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
|
||
"git+https://git.mrblake.cc/MrBlake/Netbox-Better-IPs.git@main"
|
||
```
|
||
|
||
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
|
||
PLUGINS = [
|
||
"netbox_better_ips",
|
||
]
|
||
|
||
PLUGINS_CONFIG = {
|
||
"netbox_better_ips": {
|
||
"auto_create_range": True,
|
||
"range_status": "active",
|
||
"inherit_tenant": True,
|
||
"ignore_host_prefixes": True,
|
||
},
|
||
}
|
||
```
|
||
|
||
If other plugins are already configured, add `netbox_better_ips` to the existing
|
||
list and dictionary instead of replacing them.
|
||
|
||
### 4. Collect static files, restart
|
||
|
||
The plugin has no database models, so no migration is required.
|
||
|
||
```bash
|
||
cd /opt/netbox/netbox
|
||
/opt/netbox/venv/bin/python manage.py collectstatic --no-input
|
||
sudo systemctl restart netbox netbox-rq
|
||
```
|
||
|
||
## Update
|
||
|
||
```bash
|
||
/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
|
||
"git+https://git.mrblake.cc/MrBlake/Netbox-Better-IPs.git@main"
|
||
|
||
cd /opt/netbox/netbox
|
||
/opt/netbox/venv/bin/python manage.py collectstatic --no-input
|
||
sudo systemctl restart netbox netbox-rq
|
||
```
|
||
|
||
`--force-reinstall` makes pip pick up branch changes even if the package
|
||
version has not been bumped.
|
||
|
||
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).
|