# 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).