Installing NetBox on Ubuntu 20.04

The following software and services are needed to run the NetBox.

• PostgreSQL database
• Redis
• NetBox components
• Gunicorn
• HTTP server

NetBox requires PostgreSQL 10 or later. Please note that MySQL and other relational databases are not supported.

PostgreSQL Database Installation

# sudo apt update
# sudo apt install -y postgresql

Once PostgreSQL has been installed, start the service and enable it to run at boot:

# sudo systemctl start postgresql
# sudo systemctl enable postgresql

Database Creation

At a minimum, we need to create a database for NetBox and assign it a username and password for authentication. Start by invoking the PostgreSQL shell as the system Postgres user.

# sudo -u postgres psql

Within the shell, enter the following commands to create the database and user (role), substituting your own value for the password:

CREATE DATABASE netbox;
CREATE USER netbox WITH PASSWORD 'netbox123';
GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox;

Do not use the password from the example. Choose a strong, random password to ensure secure database authentication for your NetBox installation.

Once complete, enter \q to exit the PostgreSQL shell.

Redis Installation

Redis is an in-memory key-value store which NetBox employs for caching and queuing. This section entails the installation and configuration of a local Redis instance. Redis v4.0 or later required.

# sudo apt install -y redis-server

Before continuing, verify that your installed version of Redis is at least v4.0:

# redis-server -v

You may wish to modify the Redis configuration at /etc/redis.conf or /etc/redis/redis.conf , however in most cases the default configuration is sufficient.

# sudo systemctl start redis-server.service

Verify Service Status

Use the redis-cli utility to ensure the Redis service is functional:

# redis-cli ping

If successful, you should receive a PONG response from the server.

NetBox Installation

This section of the documentation discusses installing and configuring the NetBox application itself.

Install System Packages

Begin by installing all system packages required by NetBox and its dependencies. Python 3.8 or later required

# sudo apt install -y python3 python3-pip python3-venv python3-dev build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev libssl-dev zlib1g-dev

Before continuing, check that your installed Python version is at least 3.8:

# python3 -V

Download NetBox

This documentation provides two options for installing NetBox: from a downloadable archive, or from the git repository. Installing from a package (option A below) requires manually fetching and extracting the archive for every future update, whereas installation via git (option B) allows for seamless upgrades by re-pulling the master branch.

Option A: Download a Release Archive

Download the latest stable release from GitHub as a tarball or ZIP archive and extract it to your desired path. In this example, we'll use /opt/netbox as the NetBox root.

# sudo wget https://github.com/netbox-community/netbox/archive/vX.Y.Z.tar.gz
# sudo tar -xzf vX.Y.Z.tar.gz -C /opt
# sudo ln -s /opt/netbox-X.Y.Z/ /opt/netbox

Option B: Clone the Git Repository

Create the base directory for the NetBox installation. For this guide, we'll use /opt/netbox.

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

if git is not already installed, install it:

# sudo apt install -y git

Next, clone the master branch of the NetBox GitHub repository into the current directory. (This branch always holds the current stable release.)

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

The git clone command should generate output similar to the following:

Cloning into '.'...
remote: Enumerating objects: 996, done.
remote: Counting objects: 100% (996/996), done.
remote: Compressing objects: 100% (935/935), done.
remote: Total 996 (delta 148), reused 386 (delta 34), pack-reused 0
Receiving objects: 100% (996/996), 4.26 MiB | 9.81 MiB/s, done.
Resolving deltas: 100% (148/148), done.

Create the NetBox System User

Create a system user account named netbox . We'll configure the WSGI and HTTP services to run under this account. We'll also assign this user ownership of the media directory. This ensures that NetBox will be able to save uploaded files.

# sudo adduser --system --group netbox
# sudo chown --recursive netbox /opt/netbox/netbox/media/

Configuration

Move into the NetBox configuration directory and make a copy of configuration_example.py named configuration.py. This file will hold all of your local configuration parameters.

# cd /opt/netbox/netbox/netbox/
# sudo cp configuration_example.py configuration.py

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

# vim configuration.py

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.

DATABASE = {
    'NAME': 'netbox',               # Database name
    'USER': 'netbox',               # PostgreSQL username
    'PASSWORD': 'netbox123',        # 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.

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

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

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
• Installs all required Python packages
• Run database schema migrations
• Builds the documentation locally (for offline use)
• Aggregate static resource files on disk

# sudo /opt/netbox/upgrade.sh

Note that Python 3.8 or later is required for NetBox v3.2 and later releases.

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.

# cd /opt/netbox/netbox
# python3 manage.py createsuperuser

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:

# python3 manage.py runserver 0.0.0.0:8000 --insecure

If successful, you should see output similar to the following:

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
August 30, 2021 - 18:02:23
Django version 3.2.6, using settings 'netbox.settings'
Starting development server at http://127.0.0.1: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. Try logging in using the username and password specified when creating a superuser.

Type Ctrl+c to stop the development server.

Gunicorn

Like most Django applications, NetBox runs as a WSGI application behind an HTTP server. This documentation shows how to install and configure gunicorn (which is automatically installed with NetBox) for this role, however other WSGI servers are available and should work similarly well. uWSGI is a popular alternative.

Configuration

NetBox ships with a default configuration file for gunicorn. To use it, copy /opt/netbox/contrib/gunicorn.py to /opt/netbox/gunicorn.py. (We make a copy of this file rather than pointing to it directly to ensure that any local changes to it do not get overwritten by a future upgrade.)

# sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py

systemd Setup We'll use systemd to control both gunicorn and NetBox's background worker process. First, copy contrib/netbox.service and contrib/netbox-rq.service to the /etc/systemd/system/ directory and reload the systemd daemon:

# sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
# sudo systemctl daemon-reload

Then, start the netbox and netbox-rq services and enable them to initiate at boot time:

# sudo systemctl start netbox netbox-rq
# sudo systemctl enable netbox netbox-rq

You can use the command systemctl status netbox to verify that the WSGI service is running:

systemctl status netbox.service

You should see output similar to the following:

● netbox.service - NetBox WSGI Service
     Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2021-08-30 04:02:36 UTC; 14h ago
       Docs: https://docs.netbox.dev/
   Main PID: 1140492 (gunicorn)
      Tasks: 19 (limit: 4683)
     Memory: 666.2M
     CGroup: /system.slice/netbox.service
             ├─1140492 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
             ├─1140513 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
             ├─1140514 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
...

Once you've verified that the WSGI workers are up and running, move on to HTTP server setup.

HTTP Server Setup

Obtain an SSL Certificate

To enable HTTPS access to NetBox, you'll need a valid SSL certificate. You can purchase one from a trusted commercial provider, obtain one for free from Let's Encrypt, or generate your own (although self-signed certificates are generally untrusted). Both the public certificate and private key files need to be installed on your NetBox server in a location that is readable by the netbox user.

The command below can be used to generate a self-signed certificate for testing purposes, however it is strongly recommended to use a certificate from a trusted authority in production. Two files will be created: the public certificate (netbox.crt) and the private key (netbox.key). The certificate is published to the world, whereas the private key must be kept secret at all times.

# sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/ssl/private/netbox.key \
-out /etc/ssl/certs/netbox.crt

The above command will prompt you for additional details of the certificate; all of these are optional. So you can press Enter and keep continue.

HTTP Server Installation

Installing nginx

Begin by installing nginx:

# sudo apt install -y nginx

Once nginx is installed, copy the nginx configuration file provided by NetBox to /etc/nginx/sites-available/netbox. Be sure to replace netbox.example.com with the domain name or IP address of your installation. (This should match the value configured for ALLOWED_HOSTS in configuration.py.)

# sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox

Then, delete /etc/nginx/sites-enabled/default and create a symlink in the sites-enabled directory to the configuration file you just created.

# sudo rm /etc/nginx/sites-enabled/default
# sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox

Finally, restart the nginx service to use the new configuration.

# sudo systemctl restart nginx

At this point, you should be able to connect to the HTTPS service at the server name or IP address you provided.