What is NetBox?

NetBox is an open source web application designed to help manage and document computer networks. Initially conceived by the network engineering team at DigitalOcean, NetBox was developed specifically to address the needs of network and infrastructure engineers. It encompasses the following aspects of network management:

• IP address management (IPAM) – IP networks and addresses, VRFs, and VLANs
• Equipment racks – Organized by group and site
• Devices – Types of devices and where they are installed
• Connections – Network, console, and power connections among devices
• Virtualization – Virtual machines and clusters
• Data circuits – Long-haul communications circuits and providers
• Secrets – Encrypted storage of sensitive credentials

What NetBox Is Not

While NetBox strives to cover many areas of network management, the scope of its feature set is necessarily limited. This ensures that development focuses on core functionality and that scope creep is reasonably contained. To that end, it might help to provide some examples of functionality that NetBox does not provide:

• Network monitoring
• DNS server
• RADIUS server
• Configuration management
• Facilities management

That said, NetBox can be used to great effect in populating external tools with the data they need to perform these functions.

Design Philosophy

NetBox was designed with the following tenets foremost in mind.

Replicate the Real World

Careful consideration has been given to the data model to ensure that it can accurately reflect a real-world network. For instance, IP addresses are assigned not to devices, but to specific interfaces attached to a device, and an interface may have multiple IP addresses assigned to it.

Serve as a “Source of Truth”

NetBox intends to represent the desired state of a network versus its operational state. As such, automated import of live network state is strongly discouraged. All data created in NetBox should first be vetted by a human to ensure its integrity. NetBox can then be used to populate monitoring and provisioning systems with a high degree of confidence.

Keep it Simple

When given a choice between a relatively simple 80% solution and a much more complex complete solution, the former will typically be favored. This ensures a lean codebase with a low learning curve.

Application Stack

NetBox is built on the Django Python framework and utilizes a PostgreSQL database. It runs as a WSGI service behind your choice of HTTP server.

Function	Component
HTTP service	nginx or Apache
WSGI service	gunicorn or uWSGI
Application	Django/Python
Database	PostgreSQL 9.6+
Task queuing	Redis/django-rq
Live device access	NAPALM

Supported Python Versions

NetBox supports Python 3.6, 3.7, and 3.8 environments currently. (Support for Python 3.5 was removed in NetBox v2.8.)

Installation

# yum update -y

# yum install -y postgresql95-server.x86_64 postgresql95-contrib.x86_64 postgresql95-libs.x86_64

https://netbox.readthedocs.io/en/stable/installation/

# /usr/pgsql-9.5/bin/postgresql95-setup initdb

# nano /var/lib/pgsql/data/pg_hba.conf

host    all             all             127.0.0.1/32            md5
host    all             all             ::1/128                 md5

# systemctl enable postgresql-9.5.service
# systemctl start postgresql-9.5.service 

$ sudo -u postgres psql
psql (12.5 (Ubuntu 12.5-0ubuntu0.20.04.1))
Type “help” for help.

postgres=# CREATE DATABASE netbox;
CREATE DATABASE
postgres=# CREATE USER netbox WITH PASSWORD ‘J5brHrAXFLQSif0K’;
CREATE ROLE
postgres=# GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox;
GRANT
postgres=# \q

# yum install -y redis

# sudo systemctl start redis

# sudo systemctl enable redis

# sudo yum install -y gcc python36 python36-devel python3-pip libxml2-devel libxslt-devel libffi-devel openssl-devel redhat-rpm-config

# sudo pip3 install –upgrade pip

# sudo mkdir -p /opt/netbox/ && cd /opt/netbox/

# sudo yum install -y git

# sudo git clone -b master https://github.com/netbox-community/netbox.git .

# sudo groupadd —system netbox

# sudo adduser —system -g netbox netbox

# sudo chown –recursive netbox /opt/netbox/netbox/media/

Open configuration.py with your preferred editor to begin configuring NetBox. NetBox offers many configuration parameters, but only the following four are required for new installations:

• ALLOWED_HOSTS
• DATABASE
• REDIS
• SECRET_KEY

ALLOWED_HOSTS

This is a list of the valid hostnames and IP addresses by which this server can be reached. You must specify at least one name or IP address. (Note that this does not restrict the locations from which NetBox may be accessed: It is merely for HTTP host header validation.)

ALLOWED_HOSTS = ['netbox.example.com', '192.0.2.123'

If you are not yet sure what the domain name and/or IP address of the NetBox installation will be, you can set this to a wildcard (asterisk) to allow all host values:

ALLOWED_HOSTS = ['*']

DATABASE

This parameter holds the database configuration details. You must define the username and password used when you configured PostgreSQL. If the service is running on a remote host, update the HOST and PORT parameters accordingly. See the configuration documentation for more detail on individual parameters.

DATABASE = {
    'NAME': 'netbox',               # Database name
    'USER': 'netbox',               # PostgreSQL username
    'PASSWORD': 'J5brHrAXFLQSif0K', # PostgreSQL password
    'HOST': 'localhost',            # Database server
    'PORT': '',                     # Database port (leave blank for default)
    'CONN_MAX_AGE': 300,            # Max database connection age (seconds)
}

REDIS

Redis is a in-memory key-value store used by NetBox for caching and background task queuing. Redis typically requires minimal configuration; the values below should suffice for most installations. See the configuration documentation for more detail on individual parameters.

Note that NetBox requires the specification of two separate Redis databases: tasks and caching. These may both be provided by the same Redis service, however each should have a unique numeric database ID.

REDIS = {
    'tasks': {
        'HOST': 'localhost',      # Redis server
        'PORT': 6379,             # Redis port
        'PASSWORD': '',           # Redis password (optional)
        'DATABASE': 0,            # Database ID
        'SSL': False,             # Use SSL (optional)
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 1,            # Unique ID for second database
        'SSL': False,
    }
}

SECRET_KEY

This parameter must be assigned a randomly-generated key employed as a salt for hashing and related cryptographic functions. (Note, however, that it is never directly used in the encryption of secret data.) This key must be unique to this installation and is recommended to be at least 50 characters long. It should not be shared outside the local system.

A simple Python script named generate_secret_key.py is provided in the parent directory to assist in generating a suitable key:

python3 ../generate_secret_key.py

Warning

In the case of a highly available installation with multiple web servers, SECRET_KEY must be identical among all servers in order to maintain a persistent user session state.

When you have finished modifying the configuration, remember to save the file.

Optional Requirements

All Python packages required by NetBox are listed in requirements.txt and will be installed automatically. NetBox also supports some optional packages. If desired, these packages must be listed in local_requirements.txt within the NetBox root directory.

NAPALM

The NAPALM automation library allows NetBox to fetch live data from devices and return it to a requester via its REST API. The NAPALM_USERNAME and NAPALM_PASSWORD configuration parameters define the credentials to be used when connecting to a device.

sudo echo napalm >> /opt/netbox/local_requirements.txt

Remote File Storage

By default, NetBox will use the local filesystem to store uploaded files. To use a remote filesystem, install the django-storages library and configure your desired storage backend in configuration.py.

sudo echo django-storages >> /opt/netbox/local_requirements.txt

Run the Upgrade Script

Once NetBox has been configured, we’re ready to proceed with the actual installation. We’ll run the packaged upgrade script (upgrade.sh) to perform the following actions:

• Create a Python virtual environment
• Install all required Python packages
• Run database schema migrations
• Aggregate static resource files on disk

sudo /opt/netbox/upgrade.sh

Note

Upon completion, the upgrade script may warn that no existing virtual environment was detected. As this is a new installation, this warning can be safely ignored.

Create a Super User

NetBox does not come with any predefined user accounts. You’ll need to create a super user (administrative account) to be able to log into NetBox. First, enter the Python virtual environment created by the upgrade script:

source /opt/netbox/venv/bin/activate

Once the virtual environment has been activated, you should notice the string (venv) prepended to your console prompt.

Next, we’ll create a superuser account using the createsuperuser Django management command (via manage.py). Specifying an email address for the user is not required, but be sure to use a very strong password.

(venv) $ cd /opt/netbox/netbox
(venv) $ python3 manage.py createsuperuser
Username: admin
Email address: admin@example.com
Password:
Password (again):
Superuser created successfully.

Test the Application

At this point, we should be able to run NetBox’s development server for testing. We can check by starting a development instance:

(venv) $ python3 manage.py runserver 0.0.0.0:8000 --insecure
Performing system checks...

System check identified no issues (0 silenced).
November 17, 2020 - 16:08:13
Django version 3.1.3, using settings 'netbox.settings'
Starting development server at http://0.0.0.0:8000/
Quit the server with CONTROL-C.

Next, connect to the name or IP of the server (as defined in ALLOWED_HOSTS) on port 8000; for example, http://127.0.0.1:8000/. You should be greeted with the NetBox home page.

Warning

The development server is for development and testing purposes only. It is neither performant nor secure enough for production use. Do not use it in production.

Warning

If the test service does not run, or you cannot reach the NetBox home page, something has gone wrong. Do not proceed with the rest of this guide until the installation has been corrected.

Note that the initial user interface will be locked down for non-authenticated users.

Try logging in using the superuser account we just created. Once authenticated, you’ll be able to access all areas of the UI:

Type Ctrl+c to stop the development server.