Skip to content

NetBox with NetDoc installation

Jump to bottom
Andrea Dainese edited this page Mar 27, 2024 · 8 revisions

The installation of NetBox is covered in the official documentation. The following paragraphs provide a summary of the installation process for NetBox with FWAdmin on Ubuntu Linux 22.04.

Prerequisites

To ensure the proper functioning of NetBox, you need to install some additional packages:

sudo apt install -y git sudo apache2 python3 python3-pip python3-venv python3-dev build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev libssl-dev zlib1g-dev postgresql redis

NetBox will run as the netbox user and will be installed in the /opt directory:

sudo useradd -M -U -d /opt/netbox netbox

Download the NetBox sources from GitHub and adjust the permissions:

sudo git clone -b v3.5.8 https://github.com/netbox-community/netbox /opt/netbox
sudo chown netbox:netbox /opt/netbox/ -R
sudo find /opt/netbox/ -type d -exec chmod a+xr {} \;

Optionally, you can choose a different NetBox release.

Download also NTC templates:

sudo git clone --depth=1 https://github.com/networktocode/ntc-templates /opt/ntc-templates
sudo chown netbox:netbox /opt/ntc-templates -R

Creating the NetBox database

NetBox uses PostgreSQL as the database backend. Execute the following commands:

sudo -u postgres psql
create database netbox;
create user netbox with password '0123456789abcdef';
grant all privileges on database netbox to netbox;

Remember to replace the password with a strong one.

Configuring NetBox

The following commands perform the configuration steps for NetBox:

  • Clone the NetBox default configuration.
  • Create a self-signed certificate.
  • Configure Apache as a reverse proxy and Gunicorn.
sudo -u netbox cp -a /opt/netbox/netbox/netbox/configuration_example.py /opt/netbox/netbox/netbox/configuration.py
sudo -u netbox cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
sudo -u netbox chmod 600 /opt/netbox/netbox/netbox/configuration.py
sudo openssl req -x509 -newkey rsa:4096 -keyout /etc/ssl/private/netbox.key -nodes -out /etc/ssl/certs/netbox.crt -sha256 -days 3650
sudo cp /opt/netbox/contrib/apache.conf /etc/apache2/sites-available/001-netbox.conf
sudo a2enmod proxy ssl headers proxy_http rewrite
sudo a2dissite 000-default
sudo a2ensite 001-netbox

Edit the configuration file (configuration.py) as follows:

ALLOWED_HOSTS = ['*']
DEBUG = False     # True for developers
DEVELOPER = False # True for developers
DATABASE = {
    'NAME': 'netbox',
    'USER': 'netbox',
    'PASSWORD': '0123456789abcdef',
    'HOST': 'localhost',
    'PORT': '',
    'CONN_MAX_AGE': 300,
}
REDIS = {
    'tasks': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 0,
        'SSL': False,
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 1,
        'SSL': False,
    }
}
PLUGINS = ['netdoc']
PLUGINS_CONFIG = {
    'netdoc': {
        # 'MAX_INGESTED_LOGS': 50,
        'NTC_TEMPLATES_DIR': '/opt/ntc-templates/ntc_templates/templates',
        # 'NORNIR_LOG': f'{settings.BASE_DIR}/nornir.log',
        # 'NORNIR_TIMEOUT': 300,
        # 'RAISE_ON_CDP_FAIL': True,
        # 'RAISE_ON_LLDP_FAIL': True,
        # 'ROLE_MAP': {},
    },
}
RQ_DEFAULT_TIMEOUT = 600
SECRET_KEY = '01234567890123456789012345678901234567890123456789'

Make sure to:

  • Set a strong password for PostgreSQL.
  • Use a random secret key (use /opt/netbox/netbox/generate_secret_key.py to generate a key).
  • Secure the Redis configuration.

Optionally, you can:

  • Use a custom path for parding templates (NTC_TEMPLATES_DIR). By default templates embedded within NetDoc will be used.
  • Limit the allowed hosts.
  • Increase how many logs are ingester per time (MAX_INGESTED_LOGS).
  • Change where nornir store logs (NORNIR_LOG).
  • Increase nornir timeout (NORNIR_TIMEOUT).
  • Skip exception on CDP discovery (RAISE_ON_CDP_FAIL).
  • Skip exception on LLDP discovery (RAISE_ON_LLDP_FAIL).
  • Custom role-icon mapping (e.g. ROLE_MAP: {'custom-role-slug': 'router'}).

Finally, upgrade the NetBox environment, including NetDoc:

sudo -u netbox echo netdoc >> /opt/netbox/local_requirements.txt
sudo -u netbox /opt/netbox/upgrade.sh

Creation of the initial administrative user

Prior to starting NetBox, it is necessary to generate the initial administrative user account:

sudo -u netbox /opt/netbox/venv/bin/python3 /opt/netbox/netbox/manage.py createsuperuser

Starting NetBox

Start NetBox and set the services to start during boot:

sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable netbox netbox-rq apache2
sudo systemctl start netbox netbox-rq apache2

Installing using Docker compose

NetDoc can also be installed using Docker Compose. To begin, clone the official repository and refer to the documentation:

git clone https://github.com/netbox-community/netbox-docker

Make the necessary adjustments to the following files:

  • configuration/configuration.py
  • env/netbox.env
  • Dockerfile-Plugins
  • plugin_requirements.txt

You can find example configuration files in the NetDoc repository.

Once the files have been adjusted, proceed to build the containers:

docker-compose build --no-cache

Afterward, start the containers:

docker-compose up -d

To check for any errors, monitor the output using the following command:

docker-compose logs -t -f

In case of permission denied errors, fix the permissions of Docker volumes:

docker volume inspect netbox-docker_netbox-scripts-files netbox-docker_netbox-reports-files | grep Mountpoint
        "Mountpoint": "/var/lib/docker/volumes/netbox-docker_netbox-scripts-files/_data",
        "Mountpoint": "/var/lib/docker/volumes/netbox-docker_netbox-reports-files/_data",
chown 101:0 -R /var/lib/docker/volumes/netbox-docker_netbox-scripts-files/_data /var/lib/docker/volumes/netbox-docker_netbox-reports-files/_data

Within containers, files must be owned by init:root:

docker exec netbox-docker_netbox_1 ls -l /opt/netbox/netbox/scripts /opt/netbox/netbox/reports
/opt/netbox/netbox/reports:
total 8
-rw-r--r-- 1 unit root 5880 Jun 12 06:50 NetDoc.py
-rw-r--r-- 1 unit root    0 Apr 27 16:05 __init__.py

/opt/netbox/netbox/scripts:
total 20
-rw-r--r-- 1 unit root 13852 Jun 12 06:50 NetDoc.py
-rw-r--r-- 1 unit root     0 Apr 27 16:05 __init__.py
drwxrwxr-x 2 unit root  4096 Jun 12 06:50 __pycache__

Introduction | Device configuration | NetBox installation | Utilizing NetDoc | Developing NetDoc | FAQ | Issues | Sponsorship

Clone this wiki locally