NetBox Cheat Sheet

Overview

NetBox is an open-source web application designed to help manage and document computer networks. Originally developed by DigitalOcean, it combines IP address management (IPAM), data center infrastructure management (DCIM), circuit tracking, and network automation into a single platform. NetBox serves as a source of truth for network infrastructure, maintaining an authoritative record of devices, racks, cables, IP addresses, VLANs, prefixes, and their relationships. Its comprehensive REST and GraphQL APIs make it ideal for driving network automation.

NetBox models the physical world (sites, racks, devices, cables) alongside the logical network (IP addresses, prefixes, VLANs, VRFs, ASNs). It supports custom fields, tags, config contexts for device-specific variables, webhooks for event-driven automation, and a plugin system for extending functionality. NetBox integrates with tools like Ansible, Terraform, Nautobot, and custom scripts to automate network provisioning and configuration management. It uses PostgreSQL for data storage and Redis for caching and task queuing.

Installation

Docker Compose (Recommended)

# Clone the netbox-docker repository
git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker

# Create override file
cat > docker-compose.override.yml <<EOF
services:
  netbox:
    ports:
      - "8000:8080"
EOF

# Start NetBox
docker compose up -d

# Default credentials: admin / admin

Package Installation (Ubuntu)

# Prerequisites
sudo apt install -y python3 python3-pip python3-venv python3-dev \
  build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev \
  libssl-dev redis-server postgresql

# Create database
sudo -u postgres psql -c "CREATE DATABASE netbox;"
sudo -u postgres psql -c "CREATE USER netbox WITH PASSWORD 'changeme';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox;"

# Download and install
wget https://github.com/netbox-community/netbox/archive/refs/tags/v4.0.0.tar.gz
tar xzf v4.0.0.tar.gz -C /opt
ln -s /opt/netbox-4.0.0 /opt/netbox

cd /opt/netbox
pip3 install -r requirements.txt
python3 manage.py migrate
python3 manage.py createsuperuser
python3 manage.py collectstatic

Configuration

configuration.py

# /opt/netbox/netbox/netbox/configuration.py
ALLOWED_HOSTS = ['netbox.example.com', 'localhost']

DATABASE = {
    'NAME': 'netbox',
    'USER': 'netbox',
    'PASSWORD': 'changeme',
    'HOST': 'localhost',
    'PORT': '',
}

REDIS = {
    'tasks': {
        'HOST': 'localhost',
        'PORT': 6379,
        'DATABASE': 0,
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        'DATABASE': 1,
    }
}

SECRET_KEY = 'your-secret-key-here'
LOGIN_REQUIRED = True
PLUGINS = ['netbox_bgp', 'netbox_topology_views']

REMOTE_AUTH_ENABLED = True
REMOTE_AUTH_BACKEND = 'netbox.authentication.LDAPBackend'

REST API

Endpoint	Description
/api/dcim/sites/	Sites
/api/dcim/racks/	Racks
/api/dcim/devices/	Devices
/api/dcim/interfaces/	Interfaces
/api/dcim/cables/	Cables
/api/ipam/prefixes/	IP prefixes
/api/ipam/ip-addresses/	IP addresses
/api/ipam/vlans/	VLANs
/api/ipam/vrfs/	VRFs
/api/circuits/circuits/	Circuits
/api/tenancy/tenants/	Tenants

API Usage

# Set API token
export NETBOX_TOKEN="your-api-token"
export NETBOX_URL="http://netbox.example.com"

# List sites
curl -s -H "Authorization: Token $NETBOX_TOKEN" \
  "$NETBOX_URL/api/dcim/sites/" | jq

# Create a device
curl -X POST -H "Authorization: Token $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  "$NETBOX_URL/api/dcim/devices/" \
  -d '{
    "name": "switch-01",
    "device_type": 1,
    "role": 1,
    "site": 1,
    "status": "active"
  }'

# Assign IP address
curl -X POST -H "Authorization: Token $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  "$NETBOX_URL/api/ipam/ip-addresses/" \
  -d '{
    "address": "10.0.1.1/24",
    "status": "active",
    "assigned_object_type": "dcim.interface",
    "assigned_object_id": 1
  }'

# Search devices
curl -s -H "Authorization: Token $NETBOX_TOKEN" \
  "$NETBOX_URL/api/dcim/devices/?name__ic=switch" | jq '.results[].name'

# Get available IPs in prefix
curl -s -H "Authorization: Token $NETBOX_TOKEN" \
  "$NETBOX_URL/api/ipam/prefixes/1/available-ips/" | jq

Python pynetbox Client

import pynetbox

nb = pynetbox.api('http://netbox.example.com', token='your-token')

# List all devices at a site
devices = nb.dcim.devices.filter(site='dc1')
for device in devices:
    print(f"{device.name}: {device.primary_ip}")

# Create a prefix
prefix = nb.ipam.prefixes.create(
    prefix='10.0.100.0/24',
    site=1,
    status='active',
    description='Server network'
)

# Get next available IP
available = nb.ipam.prefixes.get(prefix='10.0.100.0/24')
next_ip = available.available_ips.create({})
print(f"Assigned: {next_ip.address}")

# Bulk create VLANs
vlans = [
    {'vid': vid, 'name': f'VLAN-{vid}', 'site': 1}
    for vid in range(100, 110)
]
nb.ipam.vlans.create(vlans)

DCIM Operations

Device Management

# List device types
curl -s -H "Authorization: Token $NETBOX_TOKEN" \
  "$NETBOX_URL/api/dcim/device-types/" | jq '.results[] | {id, model, manufacturer: .manufacturer.name}'

# List interfaces for a device
curl -s -H "Authorization: Token $NETBOX_TOKEN" \
  "$NETBOX_URL/api/dcim/interfaces/?device_id=1" | jq '.results[].name'

# Create cable connection
curl -X POST -H "Authorization: Token $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  "$NETBOX_URL/api/dcim/cables/" \
  -d '{
    "a_terminations": [{"object_type": "dcim.interface", "object_id": 1}],
    "b_terminations": [{"object_type": "dcim.interface", "object_id": 5}],
    "type": "cat6a",
    "status": "connected"
  }'

Advanced Usage

Ansible Integration

# inventory plugin: netbox.netbox.nb_inventory
plugin: netbox.netbox.nb_inventory
api_endpoint: http://netbox.example.com
token: your-api-token
validate_certs: false
group_by:
  - site
  - device_role
  - platform
query_filters:
  - status: active
  - has_primary_ip: true

Config Contexts

{
  "dns_servers": ["10.0.0.53", "10.0.0.54"],
  "ntp_servers": ["10.0.0.123"],
  "snmp_community": "public",
  "syslog_server": "10.0.0.100",
  "ospf": {
    "area": "0.0.0.0",
    "router_id": "{{ primary_ip }}"
  }
}

Custom Scripts

from netbox.scripts import Script, ObjectVar, IntegerVar
from dcim.models import Device, Site

class ProvisionSwitch(Script):
    class Meta:
        name = "Provision Switch"
        description = "Create switch with standard interfaces"

    site = ObjectVar(model=Site)
    switch_number = IntegerVar(min_value=1, max_value=99)

    def run(self, data, commit):
        site = data['site']
        num = data['switch_number']
        name = f"{site.slug}-sw-{num:02d}"

        device = Device(
            name=name,
            site=site,
            device_type_id=1,
            role_id=1,
            status='planned'
        )
        device.save()
        self.log_success(f"Created device: {name}")

Webhooks

{
  "name": "Device Created",
  "type_create": true,
  "payload_url": "https://automation.example.com/hooks/netbox",
  "http_method": "POST",
  "http_content_type": "application/json",
  "body_template": "{{ data | tojson }}",
  "conditions": {
    "and": [{"attr": "status.value", "value": "active"}]
  }
}

Troubleshooting

Issue	Solution
Slow page loads	Enable Redis caching; check PostgreSQL query performance
API returns 403	Verify API token permissions; check LOGIN_REQUIRED setting
Migration errors	Run python3 manage.py migrate --run-syncdb; check PostgreSQL version
Plugin not loading	Add to PLUGINS list in configuration.py; run pip install <plugin>
Search not working	Rebuild search cache: python3 manage.py reindex
Webhook not firing	Check webhook conditions and URL; review NetBox logs
Docker permissions	Ensure volumes are owned by the netbox user (UID 999)