NetBox Quickstart for IPv4 Address Management

Run NetBox with Docker Compose

git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
docker compose pull
docker compose up -d

The stack takes a couple of minutes to initialise on first run because it applies database migrations. Watch it complete:

docker compose logs -f netbox

Create an administrative user once the logs settle:

docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser

NetBox is now on http://localhost:8000. For anything beyond evaluation, put it behind TLS and change the SECRET_KEY in env/netbox.env before exposing it.

Create a RIR and an aggregate

NetBox models held space top-down, so register the source first. Under IPAM → RIRs, add the registry your space came from — RIPE NCC, ARIN, APNIC, LACNIC, or AFRINIC. Add a separate RIR entry marked private for RFC 1918 space, so internal and public allocations do not share a utilization figure.

Then under IPAM → Aggregates, add each block you hold, for example 198.51.100.0/22, and attach it to the RIR. An aggregate is a statement that you hold this space; everything below it is how you use it.

Do not create aggregates for space you merely route on behalf of someone else. That belongs in prefixes with an appropriate role, and keeping it out of aggregates prevents it from inflating your utilization.

Define roles and sites

Under IPAM → Prefix Roles, create the roles you actually allocate by. A workable starting set is management, customer, loadbalancer, point-to-point, and reserved.

Under Organization → Sites, create the physical or logical locations you allocate to.

Doing this before entering prefixes is what makes utilization reporting useful later. A prefix with a role and a site answers “what is this for” without anyone reading a free-text description.

Add prefixes under the aggregate

Under IPAM → Prefixes, create a child prefix such as 198.51.100.0/24, assign the role and site, and set its status. NetBox places it under the aggregate automatically based on the addresses — there is no parent field to set.

Set status deliberately, because it drives utilization:

• Container — space subdivided further, not assigned directly.
• Active — in use.
• Reserved — held deliberately, counted as used.
• Deprecated — being retired, still recorded.

Mark your intended growth headroom as Reserved rather than leaving it absent. Space that is not recorded is space someone will assign.

Import existing allocations in bulk

Entering an existing estate by hand is where these projects stall. Use IPAM → Prefixes → Import with CSV instead:

prefix,status,role,site,description
198.51.100.0/26,active,management,ams-01,Out-of-band management
198.51.100.64/26,active,customer,ams-01,Customer VLAN 101
198.51.100.128/25,reserved,,ams-01,Growth headroom

Import in one pass per site so a rejected row is easy to locate. NetBox validates the whole file before committing, so a single malformed prefix fails the batch rather than importing half of it.

Verify utilization and query the API

Open the aggregate view. The utilization column should now reflect the child prefixes you loaded. If it reads 0%, the prefixes were created outside the aggregate’s range — check for a typo in the aggregate itself.

Confirm the same data is reachable programmatically. Create a token under Admin → API Tokens, then:

curl -s -H "Authorization: Token $NETBOX_TOKEN" \
  "http://localhost:8000/api/ipam/prefixes/?within=198.51.100.0/22&status=active" \
  | jq '.results[] | {prefix, role: .role.name, site: .site.name}'

If that returns your allocations, NetBox is a source of truth rather than a second place to look things up.