How to Install NetBox Network Documentation and Management Tool on Ubuntu 22.04

Prerequisites
Step 1 - Configure Firewall
Step 2 - Install and Configure PostgreSQL
Step 3 - Install and Configure Redis
Step 4 - Download NetBox
Step 5 - Configure NetBox
Step 6 - Install NetBox
Step 7 - Configure Gunicorn and Create a Service File
Step 8 - Install Nginx
Step 9 - Install SSL
Step 10 - Configure Nginx
Step 11 - Upgrade NetBox
Conclusion

NetBox is an open-source IP address (IPAM) and datacentre infrastructure management (DCIM) web application used to manage and document computer networks and IP addresses. The network engineering team at DigitalOcean initially conceived it. It is written using the Django Python framework and uses the PostgreSQL database for data storage. It also uses the Redis database for caching queries.

This tutorial will teach you how to install the NetBox tool on a Ubuntu 22.04 server and Nginx as a reverse proxy server.

Prerequisites

A server running Ubuntu 22.04.
A non-root user with sudo privileges.
A fully qualified domain name (FQDN) like netbox.example.com.
Make sure everything is updated.
```
$ sudo apt update
$ sudo apt upgrade
```

Few packages that your system needs.

$ sudo apt install wget curl nano software-properties-common dirmngr apt-transport-https gnupg2 ca-certificates lsb-release ubuntu-keyring unzip -y

Some of these packages may already be installed on your system.

Step 1 - Configure Firewall

The first step is to configure the firewall. Ubuntu comes with ufw (Uncomplicated Firewall) by default.

Check if the firewall is running.

$ sudo ufw status

You should get the following output.

Status: inactive

Allow SSH port so the firewall doesn't break the current connection on enabling it.

$ sudo ufw allow OpenSSH

Allow HTTP and HTTPS ports as well.

$ sudo ufw allow http
$ sudo ufw allow https

Enable the Firewall

$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

Check the status of the firewall again.

$ sudo ufw status

You should see a similar output.

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80/tcp                     ALLOW       Anywhere
443                        ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80/tcp (v6)                ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)

Step 2 - Install and Configure PostgreSQL

NetBox works with PostgreSQL 11 and above. Ubuntu 22.04 ships with PostgreSQL 14 by default. We will use PostgreSQL 15 for our tutorial.

Run the following command to add the PostgreSQL GPG key.

$ curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor | sudo tee /usr/share/keyrings/postgresql-key.gpg >/dev/null

Add the APT repository to your sources list.

$ sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/postgresql-key.gpg arch=amd64] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

Update the system repository.

$ sudo apt update

Now, you can install PostgreSQL using the command below.

$ sudo apt install postgresql postgresql-contrib

The postgresql-contrib package contains some extra utilities.

Check the status of the PostgreSQL service.

$ sudo systemctl status postgresql
? postgresql.service - PostgreSQL RDBMS
     Loaded: loaded (/lib/systemd/system/postgresql.service; enabled; vendor preset: enabled)
     Active: active (exited) since Tue 2022-11-27 9:10:35 UTC; 5s ago
    Process: 30544 ExecStart=/bin/true (code=exited, status=0/SUCCESS)
   Main PID: 30544 (code=exited, status=0/SUCCESS)
        CPU: 2ms

Dec 27 9:10:35 netbox systemd[1]: Starting PostgreSQL RDBMS...
Dec 27 9:10:35 netbox systemd[1]: Finished PostgreSQL RDBMS.

You can see that the service is enabled and running by default.

Launch the PostgreSQL shell.

$ sudo -i -u postgres psql

Create the NetBox database.

postgres=# CREATE DATABASE netbox;

Create the NetBox user and choose a strong password.

postgres-# CREATE USER netbox WITH PASSWORD 'Your_Password';

Change the database owner to NetBox user.

postgres-# ALTER DATABASE netbox OWNER TO netbox;

Exit the shell.

postgres-# \q

Verify that your credentials work.

$ psql --username netbox --password --host localhost netbox
Password for user netbox:
psql (15.1 (Ubuntu 15.1-1.pgdg22.04+1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.

netbox=>

Exit the shell by typing \q.

Step 3 - Install and Configure Redis

Ubuntu ships with Redis 6.0.16. For our tutorial, we will install the latest version from the official repository.

Import the official Redis GPG key.

$ curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg

Add the APT repository to your sources list.

echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list

Update the system repository list.

$ sudo apt update

Issue the following command to install the Redis server.

$ sudo apt install redis

Confirm the Redis version.

$ redis-server -v
Redis server v=7.0.7 sha=00000000:0 malloc=jemalloc-5.2.1 bits=64 build=2260280010e18db8

Let us verify the service connection by using the following command.

$ redis-cli

You will be switched to the Redis shell.

The first step is to set the password for the Redis default user. Replace Your_Redis_Password with a strong password of your choice.

127.0.0.1:6379> acl setuser default >Your_Redis_Password

Test the Redis Authentication.

127.0.0.1:6379> AUTH Your_Redis_Password
OK

Ping the service.

127.0.0.1:6379> ping
PONG

Exit the service by typing exit.

Step 4 - Download NetBox

NetBox requires Python Django to work. The first step in installing NetBox is to install the required Python packages. Run the following command to install the required Python packages.

$ 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

Check the Python version.

$ python3 -V
Python 3.10.6

Create the base directory for the NetBox install.

$ sudo mkdir -p /opt/netbox/

Switch to the directory.

$ cd /opt/netbox

Clone the master branch of the NetBox's GitHub repository into the current directory.

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

The --depth 1 flag retrieves only the most recent commit of the repository. If you want to download the entire commit history, you can omit the flag.

Check the latest version of NetBox from the releases page and check it out using Git. At the time of writing the tutorial, 3.4.1 is the latest version available.

$ git config --global --add safe.directory /opt/netbox
$ sudo git checkout v3.4.1

Before checking it out, you need to add the directory to Git's safe directory list. This is a new security feature available in the recent Git versions.

The next step is to create a system user and group for NetBox.

$ sudo adduser --system --group netbox

Give the user permission on NetBox's media directory.

$ sudo chown --recursive netbox /opt/netbox/netbox/media/

Step 5 - Configure NetBox

Switch to the NetBox configuration directory.

$ cd /opt/netbox/netbox/netbox/

Copy the example configuration file to create the actual file.

$ sudo cp configuration_example.py configuration.py

Before proceeding with the configuration, we need to create a secret key for NetBox. Note down the key because we need it for the configuration.

$ python3 ../generate_secret_key.py
dSSWi$Ar2cVvu1)V!B82sY1tJAQK9r)vzM8ReQRF7@C^+$=1+(

Open the configuration file for editing.

$ sudo nano configuration.py

Find the ALLOWED_HOSTS variable and set its values as follows. This variable holds a list of the valid hostnames and IP addresses by which this server can be reached.

ALLOWED_HOSTS = ['netbox.example.com', '<yourserverIP>']

The next step is to edit the database details. Configure the database details as follows.

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

Configure the Redis configuration as shown. Enter the Redis password you set in step 3.

REDIS = {
    'tasks': {
        'HOST': 'localhost',
        'PORT': 6379,
        # Comment out `HOST` and `PORT` lines and uncomment the following if using Redis Sentinel
        # 'SENTINELS': [('mysentinel.redis.example.com', 6379)],
        # 'SENTINEL_SERVICE': 'netbox',
        'PASSWORD': 'Your_Redis_Password',
        'DATABASE': 0,
        'SSL': False,
        # Set this to True to skip TLS certificate verification
        # This can expose the connection to attacks, be careful
        # 'INSECURE_SKIP_TLS_VERIFY': False,
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        # Comment out `HOST` and `PORT` lines and uncomment the following if using Redis Sentinel
        # 'SENTINELS': [('mysentinel.redis.example.com', 6379)],
        # 'SENTINEL_SERVICE': 'netbox',
        'PASSWORD': 'Your_Redis_Password',
        'DATABASE': 1,
        'SSL': False,
        # Set this to True to skip TLS certificate verification
        # This can expose the connection to attacks, be careful
        # 'INSECURE_SKIP_TLS_VERIFY': False,
    }
}

Add the secret key's value to the variable.

SECRET_KEY = 'dSSWi$Ar2cVvu1)V!B82sY1tJAQK9r)vzM8ReQRF7@C^+$=1+('

By default, NetBox uses the local filesystem to store uploaded files. You can store files on a remote filesystem by installing the django-storages library. Run the following command to add the django-storages package to the NetBox's requirements.txt which will then get installed in a later step. We also need to configure the storage parameters. Uncomment the storage section of the configuration file and proceed as follows.

STORAGE_BACKEND = 'storages.backends.s3boto3.S3Boto3Storage'
STORAGE_CONFIG = {
    'AWS_ACCESS_KEY_ID': 'Key ID',
    'AWS_SECRET_ACCESS_KEY': 'Secret',
    'AWS_STORAGE_BUCKET_NAME': 'netbox',
    'AWS_S3_REGION_NAME': 'eu-west-1',
}

Other storage types are also supported including FTP, SFTP, Dropbox, and other S3 providers. To learn how to configure them, you can read up the django-storages help page.

Save the file by pressing Ctrl + X and entering Y when prompted.

Step 6 - Install NetBox

Run the NetBox upgrade script.

$ sudo /opt/netbox/upgrade.sh

The upgrade script performs the following tasks.

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

Activate the virtual environment created by the upgrade script.

$ source /opt/netbox/venv/bin/activate

The next step is to create a superuser to access NetBox. But first, switch to the required directory.

(venv) $ cd /opt/netbox/netbox

Create the superuser.

(venv) $ python3 manage.py createsuperuser

You will get the following output.

Username (leave blank to use 'navjot'):
Email address: [email protected]
Password:
Password (again):
Superuser created successfully.

NetBox includes a housekeeping management command that handles recurring cleanup tasks, such as clearing out old sessions and expired change records. You can either run the command manually or use cron to run it at regular intervals. NetBox provides a shell script to run the housekeeping tasks. Run the following command to create a soft link for the script in the Cron daily directory. This will ensure that the command will run daily.

(venv) $ sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping

The final step is to test whether the NetBox application works. But first, we need to open port 8000 for testing. You can use any port though.

(venv) $ sudo ufw allow 8000

Start a development instance of NetBox.

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

If successful, you will get the following output.

Performing system checks...

System check identified no issues (0 silenced).
December 27, 2022 - 09:27:37
Django version 4.1.4, using settings 'netbox.settings'
Starting development server at http://0.0.0.0:8000/
Quit the server with CONTROL-C.

You should be able to access NetBox via the URL http://<yourserverIP>:8000/. You will get the following screen.

Click the Log In button to open the Login page and enter the superuser credentials created earlier.

You will be taken back to the NetBox dashboard.

Press Ctrl + C key to stop the server. Deactivate the Python virtual environment.

(venv) $ deactivate

Step 7 - Configure Gunicorn and Create a Service File

NetBox runs as a WSGI application behind an HTTP server. NetBox automatically installs the Gunicorn server. In this step, we will configure Gunicorn and create a service file for NetBox so that it can be run in the background and across system reboots.

NetBox ships with a default Gunicorn configuration file. Create a copy of it.

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

The default configuration should suffice for our purposes. Depending upon your needs, you can edit the file to change the hostname, and port number or make performance improvements by changing threads, workers, and the number of requests.

The next step is to copy both NetBox and Gunicorn service files to the /etc/systemd/system directory.

$ sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/

Reload the service daemon.

$ sudo systemctl daemon-reload

Start and enable the netbox and netbox-rq services.

$ sudo systemctl start netbox netbox-rq
$ sudo systemctl enable netbox netbox-rq

Check the status of the WSGI service.

$ sudo systemctl status netbox

You will get a similar output.

? netbox.service - NetBox WSGI Service
     Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2022-12-27 09:28:23 UTC; 17s ago
       Docs: https://docs.netbox.dev/
   Main PID: 4180 (gunicorn)
      Tasks: 6 (limit: 1030)
     Memory: 357.9M
        CPU: 7.747s
     CGroup: /system.slice/netbox.service
             ??4180 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi
             ??4181 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi
             ??4182 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi
             ??4183 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi
             ??4184 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi
             ??4185 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /var/tmp/netbox.pid --pythonpath /opt/netbox/netbox --config /opt/netbox/gunicorn.py netbox.wsgi

Dec 27 09:28:23 netbox systemd[1]: Started NetBox WSGI Service.
Dec 27 09:28:24 netbox gunicorn[4180]: [2022-12-27 09:28:24 +0000] [4180] [INFO] Starting gunicorn 20.1.0
Dec 27 09:28:24 netbox gunicorn[4180]: [2022-12-27 09:28:24 +0000] [4180] [INFO] Listening at: http://127.0.0.1:8001 (4180)
Dec 27 09:28:24 netbox gunicorn[4180]: [2022-12-27 09:28:24 +0000] [4180] [INFO] Using worker: gthread
Dec 27 09:28:24 netbox gunicorn[4181]: [2022-12-27 09:28:24 +0000] [4181] [INFO] Booting worker with pid: 4181
Dec 27 09:28:24 netbox gunicorn[4182]: [2022-12-27 09:28:24 +0000] [4182] [INFO] Booting worker with pid: 4182
Dec 27 09:28:24 netbox gunicorn[4183]: [2022-12-27 09:28:24 +0000] [4183] [INFO] Booting worker with pid: 4183
Dec 27 09:28:24 netbox gunicorn[4184]: [2022-12-27 09:28:24 +0000] [4184] [INFO] Booting worker with pid: 4184
Dec 27 09:28:24 netbox gunicorn[4185]: [2022-12-27 09:28:24 +0000] [4185] [INFO] Booting worker with pid: 4185

As you can see, Gunicorn listens at port 8001 by default. This information will be useful when configuring Nginx as a reverse proxy server.

Step 8 - Install Nginx

Ubuntu 22.04 ships with an older version of Nginx. To install the latest version, you need to download the official Nginx repository.

Import Nginx's signing key.

$ curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
	| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

Add the repository for Nginx's stable version.

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

Update the system repositories.

$ sudo apt update

Install Nginx.

$ sudo apt install nginx

Verify the installation.

$ nginx -v
nginx version: nginx/1.22.1

Start the Nginx server.

$ sudo systemctl start nginx

Step 9 - Install SSL

We need to install Certbot to generate the SSL certificate. You can either install Certbot using Ubuntu's repository or grab the latest version using the Snapd tool. We will be using the Snapd version.

Ubuntu 22.04 comes with Snapd installed by default. Run the following commands to ensure that your version of Snapd is up to date. Ensure that your version of Snapd is up to date.

$ sudo snap install core
$ sudo snap refresh core

Install Certbot.

$ sudo snap install --classic certbot

Use the following command to ensure that the Certbot command runs by creating a symbolic link to the /usr/bin directory.

$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

Run the following command to generate an SSL Certificate.

$ sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d netbox.example.com

The above command will download a certificate to the /etc/letsencrypt/live/netbox.example.com directory on your server.

Generate a Diffie-Hellman group certificate.

$ sudo openssl dhparam -dsaparam -out /etc/ssl/certs/dhparam.pem 4096

To check whether the SSL renewal is working fine, do a dry run of the process.

$ sudo certbot renew --dry-run

If you see no errors, you are all set. Your certificate will renew automatically.

Step 10 - Configure Nginx

Open the file /etc/nginx/nginx.conf for editing.

$ sudo nano /etc/nginx/nginx.conf

Add the following line before the line include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size  64;

Save the file by pressing Ctrl + X and entering Y when prompted.

Create and open the file /etc/nginx/conf.d/netbox.conf for editing.

$ sudo nano /etc/nginx/conf.d/netbox.conf

Paste the following code in it.

server {
  # Redirect any http requests to https
  listen         80;
  listen         [::]:80;
  server_name    netbox.example.com;
  return 301     https://$host$request_uri;
}

server {
  listen                    443 ssl http2;
  listen                    [::]:443 ssl http2;
  server_name               netbox.example.com;

  access_log                /var/log/nginx/netbox.access.log;
  error_log                 /var/log/nginx/netbox.error.log;

  # TLS configuration
  ssl_certificate           /etc/letsencrypt/live/netbox.example.com/fullchain.pem;
  ssl_certificate_key       /etc/letsencrypt/live/netbox.example.com/privkey.pem;
  ssl_trusted_certificate   /etc/letsencrypt/live/netbox.example.com/chain.pem;
  ssl_protocols             TLSv1.2 TLSv1.3;

  ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384';
  ssl_prefer_server_ciphers on;
  ssl_session_cache         shared:SSL:50m;
  ssl_session_timeout       1d;

  # OCSP Stapling ---
  # fetch OCSP records from URL in ssl_certificate and cache them
  ssl_stapling on;
  ssl_stapling_verify on;
  ssl_dhparam /etc/ssl/certs/dhparam.pem;

  client_max_body_size 25m;

  # Proxy everything over to the netbox server
  location /static/ {
    alias /opt/netbox/netbox/static/;
  }

  location / {
    proxy_set_header        X-Real-IP $remote_addr;
    proxy_set_header        X-Forwarded-Proto $scheme;
    proxy_set_header	    X-Forwarded-Host $http_host;
    proxy_pass              http://127.0.0.1:8001;
  }
}

Save the file by pressing Ctrl + X and entering Y when prompted once finished.

Verify the Nginx configuration file syntax.

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Restart the Nginx service.

$ sudo systemctl restart nginx

You can now access the NetBox Dashboard via the URL https://netbox.example.com.

Step 11 - Upgrade NetBox

Upgrading NetBox is quite easy. The steps involve checking out the master branch of the Git repository, pulling the latest commits, and then checking out the new stable version.

Switch to the NetBox directory.

$ cd /opt/netbox

Checkout the master branch.

$ sudo git checkout master

Pull the latest commits from the repository.

$ sudo git pull origin master

Checkout the new version. If 3.4.2 is the newer version, you can check that out.

$ sudo git checkout v3.4.2

Run the upgrade script.

$ sudo ./upgrade.sh

For the upgrade process, the script performs the following functions.

Destroys and rebuilds the Python virtual environment
Installs all required Python packages (listed in requirements.txt)
Installs any additional packages from local_requirements.txt
Applies any database migrations that were included in the release
Builds the documentation locally (for offline use)
Collects all static files to be served by the HTTP service
Deletes stale content types from the database
Deletes all expired user sessions from the database

Restart the Gunicorn and NetBox service.

$ sudo systemctl restart netbox netbox-rq

Conclusion

This concludes our tutorial about installing NetBox Network Documentation and Management Tool on a Ubuntu 22.04 server along with NGinx as a reverse proxy server. If you have any questions, post them in the comments below.