Documenting a Network

In this post I will focus on the installation process of a product that I am a great fan of, Digital Ocean’s Netbox. From their documentation, Netbox is an open source web-based application designed to help manage and document computer networks. It’s been designed and built by network engineers, for network engineers.

Netbox in its current incarnation (v2.6.2) has the following features:

• IP Address Management (IPAM)
• Equipment racks
• Devices
• Connections
• Virtualisation
• Data Circuits
• Secrets (encrypted storage of sensitive credentials).

Netbox is a static repository for the above information, intended to be a source of truth for this information. It is not a solution for Network monitoring, DNS, RADIUS, config management or facilities management.

Installation Requirements

Before you begin, you will need the following:

• Either PC/server hardware, or a virtual machine (For this, I have used VMware Workstation Pro)
• Ubuntu 18.04.01 LTS Server Install iso
• An internet connection that the PC/server/VM can access

Step 1:

Install Ubuntu Server 18.04 LTS. I won’t go through this step in detail, there are plenty of resources available else where that will guide you through this, all we need to be sure of, is that you have used a static IP address on your VMnet NAT range and you can ping this IP from your host PC.

Step 2:

First thing we’ll do is we’ll update our package lists and upgrade the packages that have come pre-installed with Ubuntu 18.04 LTS. Run the following commands:

sudo apt-get update
sudo apt-get dist-upgrade

Next, we will install PostgresSQL:

sudo apt-get install -y postgresql libpq-dev

Step 3:

Now that PostgresSQL is installed, we need to create the database that Netbox will use. To do this, run the following commands:

sudo -u postgres psql
CREATE DATABASE netbox;
CREATE USER netbox WITH PASSWORD 'netbox';
GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox;
\q

*** PLEASE NOTE *** If you are deploying to a live environment, do not use the password above. Please use a password of your own choosing, that fits the security policy of your environment.

Verify you can connect to your database instance:

psql -U netbox -W -h localhost netbox

If successful, use the same ‘\q’ command to quit back to the normal prompt.

Step 4:

With the database successfully set up, we will now install Python3 and other libraries and dependencies that Netbox will run on.

sudo apt-get install -y python3 python3-pip python3-dev build-essential libxml2-dev libxslt1-dev libffi-dev graphviz libpq-dev libssl-dev redis-server zlib1g-dev

We have two documented methods of downloading the Netbox application onto our server, one is to use ‘wget’, and unpack the download into an application folder, but for the purpose of this guide, I will use the far easier ‘git’ clone method.

Make sure Git is installed;

sudo apt-get install -y git

Then clone the master repository;

sudo mkdir /opt/netbox/ && cd /opt/netbox/
sudo git clone -b master https://github.com/netbox-community/netbox.git .
sudo chown -R netbox:netbox /opt/netbox/netbox/media/

Step 5:

This step will focus on installing and configuring additional Python3 packages for Netbox.

pip3 install -r requirements.txt
cd netbox/netbox
sudo cp configuration.example.py configuration.py

Now, we must configure the file we’ve just created;

sudo nano configuration.py

As a minimum, the following fields need to be populated; ALLOWED_HOSTS, DATABASE and SECRET_KEY.

The following are examples of how each field should be presented;
ALLOWED_HOSTS = ['netbox.example.com', '192.168.0.1']

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

SECRET_KEY is a random string of 50 characters. Digital Ocean have provided a python script which will generate this for you at ‘/opt/netbox/generate_secret_key.py’. I recommend using Strong Password Generator setting the password length to 50, this will allow you to simply copy/paste the key into place on the configuration.py file.

Ctrl + O in Nano will save the changes to a file, confirm the file location, then use Ctrl + X to quit back to the command prompt.

Step 6

Next, we will run the database migrations script, this will populate the database we created earlier in step 3, with the tables and fields that Netbox requires.

cd /opt/netbox/netbox/
python3 manage.py migrate

If you run into PostgresSQL errors at this point, please ensure that your username, password and IP address details are correct in the DATABASE section of your configuration.py file.

Step 7

Create Superuser;

python3 manage.py createsuperuser
Username: netbox
Email address: netbox@netbox.com
Password: netbox
Password (again): netbox

*** PLEASE NOTE *** As before, if you are deploying to a live environment, do not use the password above. Please use a password of your own choosing, that fits the security policy of your environment.

Step 8

Collect static files;

sudo python3 manage.py collectstatic --no-input

Step 9 (Optional)

Netbox comes with some initial data e.g. RFC1918 RIR definitions, device roles etc. This step loads this optional data;

python3 manage.py loaddata initial_data

Step 10

Once you reach this step, Netbox should be in a state where it can run, and we can connect to the front web page;

python3 manage.py runserver 0.0.0.0:8000 --insecure

On your host machine, browse to the IP address you set in step 1, when you installed the operating system. You will need to append port 8000, as above to the end of the address. If you see the following web page, congratulations, you’ve got Netbox working!

If you don’t see the webpage above, please review steps 1 – 10, and look for mistakes in configuration. Do not proceed past this point, until you do see the webpage above.

Step 11

Now that we can access the application, we need to install and configure a web server and WSGI to serve up the application in a consistent, reliable manner. For the following steps we will install Apache2, Gunicorn and Supervisor.

sudo apt-get install -y apache2 libapache2-mod-wsgi-py3
cd /etc/apache2/sites-available/
sudo nano

Save the following content to a file called netbox.conf, replacing the content of the field; ServerName with the name or IP address that will be used to access the application;

<VirtualHost *:80>
       ProxyPreserveHost On
       ServerName netbox.example.com

       Alias /static /opt/netbox/netbox/static

# Needed to allow token-based API authentication
WSGIPassAuthorization on

<Directory /opt/netbox/netbox/static>
    Options Indexes FollowSymLinks MultiViews
    AllowOverride None
    Require all granted
</Directory>

<Location /static>
    ProxyPass !
</Location>

#    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
    ProxyPass / http://127.0.0.1:8001/
    ProxyPassReverse / http://127.0.0.1:8001/
</VirtualHost>

Once saved, enable the following apache modules, and restart Apache.

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod headers
sudo a2ensite netbox
sudo service apache2 restart

Step 12

Install Green Unicorn (gunicorn);

pip3 install gunicorn
sudo -H pip3 install gunicorn uwsgi
sudo reboot

Once server has rebooted, run the following command:

which gunicorn

This will tell you where gunicorn has installed to, which you will need for the next part.

Create the following file in the location /opt/netbox/gunicorn_config.py using Nano:

command = '/usr/bin/gunicorn'
pythonpath = '/opt/netbox/netbox'
bind = '127.0.0.1:8001'
workers = 3
user = 'www-data'

Update the ‘command’ field with the location you found using the ‘which gunicorn’ command earlier.

Step 13

Install Supervisord

sudo apt-get install -y supervisor

Save the following config (using Nano again) to the following location; /etc/supervisor/conf.d/netbox.conf

[program:netbox]
command = gunicorn -c /opt/netbox/gunicorn_config.py netbox.wsgi
directory = /opt/netbox/netbox/
user = www-data

Restart Supervisor;

sudo service supervisor restart

If you’ve reached this stage, you should be able to reach your Netbox application on the address of your machine set in step 1, but this time, on port 80. Congratulations, you now have a consistent, reliably served Netbox application!