NetBox for efficient infrastructure modeling

NetBox has been implemented in my environment for some time and has quickly become one of my favorite tools. It provides a comprehensive, structured, and view of networks, racks, devices, and IP addresses. Since then, it has allowed maintaining clean and current documentation that is actively used and refined.

NetBox is an open-source infrastructure resource modeling (IRM) tool that lets you document networks, racks, devices, and IP addresses in a structured and centralized way. Learn more on the official NetBox website.

This guide walks you through a practical installation of NetBox on a RHEL-based system using examplecorp.io as the domain and netbox as the hostname. The instructions assume a tech-savvy user familiar with Linux, PostgreSQL, and basic networking.

Installing PostgreSQL

Install PostgreSQL and initialize the database:

dnf install postgresql-server -y
postgresql-setup --initdb

Edit PostgreSQL configuration to use scram-sha-256 encryption:

cp /var/lib/pgsql/data/postgresql.conf /var/lib/pgsql/data/postgresql.conf.default
vi /var/lib/pgsql/data/postgresql.conf
# Set:
password_encryption = scram-sha-256

Update authentication for local connections:

cp /var/lib/pgsql/data/pg_hba.conf /var/lib/pgsql/data/pg_hba.conf.default
vi /var/lib/pgsql/data/pg_hba.conf
# Set:
# NetBox specific connections
host    netboxdb    netbox    127.0.0.1/32    scram-sha-256
host    netboxdb    netbox    ::1/128         scram-sha-256

# Default local connections
local   all         all       peer
host    all         all       127.0.0.1/32    ident
host    all         all       ::1/128         ident

Note: Make sure to place the NetBox-specific entries above the default authentication block in pg_hba.conf. This ensures NetBox uses scram-sha-256 without affecting other PostgreSQL users or services.

Start and enable PostgreSQL:

systemctl enable --now postgresql
systemctl status postgresql

Create the NetBox database and user:

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

Test the connection and change password if needed:

sudo -u postgres psql --username netbox --password --host localhost netboxdb
ALTER ROLE netbox WITH PASSWORD '{NEW_PASSWORD}';
\conninfo

Set up periodic backups using a tool like autopgsqlbackup.

Installing Redis

Redis serves as a fast in-memory store for caching and background task processing, helping NetBox run efficiently and handle asynchronous operations.

NetBox requires Redis for caching and background tasks:

dnf install redis -y
cp /etc/redis/redis.conf /etc/redis/redis.conf.default
vi /etc/redis/redis.conf
# Set:
requirepass {REDIS_PASSWORD}

systemctl enable --now redis
systemctl status redis

Note: You need to create a secure password for Redis yourself. A strong, 32-character password ensures your Redis instance is protected. On Linux, you can generate one using a command like openssl rand -base64 24. Make sure to use this same password in both the Redis configuration (requirepass) and the NetBox configuration.py file.

Verify Redis:

redis-cli
AUTH {REDIS_PASSWORD}
ping

Installing NetBox

Install required dependencies:

dnf install gcc libxml2-devel libxslt-devel libffi-devel libpq-devel openssl-devel redhat-rpm-config git -y

Create a dedicated NetBox user and directory:

useradd -r -d /opt/netbox -s /usr/sbin/nologin netbox
mkdir -p /opt/netbox
cd /opt/netbox
git clone -b master --depth 1 https://github.com/netbox-community/netbox.git .
chown -R netbox:netbox /opt/netbox

Copy the example configuration and generate a secret key:

cd /opt/netbox/netbox/netbox
sudo -u netbox cp configuration_example.py configuration.py
sudo -u netbox python3 ../generate_secret_key.py

Edit configuration.py to set domain, database, and Redis configuration:

ALLOWED_HOSTS = ['*']
CSRF_TRUSTED_ORIGINS = ['http://127.0.0.1']

DATABASE = {
    'NAME': 'netboxdb',
    'USER': 'netbox',
    'PASSWORD': '{POSTGRESQL_PASSWORD}',
    'HOST': 'localhost',
    'PORT': '',
    'CONN_MAX_AGE': 300,
}

REDIS = {
    'tasks': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '{REDIS_PASSWORD}',
        'DATABASE': 0,
        'SSL': False,
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '{REDIS_PASSWORD}',
        'DATABASE': 1,
        'SSL': False,
    }
}

SECRET_KEY = '{SECRET_KEY_CREATED_IN_LAST_STEP}'

Run the upgrade script to initialize NetBox:

sudo -u netbox /opt/netbox/upgrade.sh

Activate the Python virtual environment and create an admin user:

source /opt/netbox/venv/bin/activate
cd /opt/netbox/netbox
python3 manage.py createsuperuser
# Follow prompts for username, email, and password

Set up daily housekeeping via cron:

ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping

Configure Gunicorn:

sudo -u netbox cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
sudo -u netbox vi /opt/netbox/gunicorn.py
# bind = '127.0.0.1:8001'

Enable and start NetBox services:

cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now netbox netbox-rq
systemctl status netbox
systemctl status netbox-rq

Configuring NGINX as a Reverse Proxy

Install NGINX:

dnf install nginx -y
systemctl enable --now nginx

Create a configuration file /etc/nginx/conf.d/netbox.conf:

server {
   listen 80;
   listen 443 ssl;
   server_name netbox.examplecorp.io;

   ssl_certificate /etc/nginx/conf.d/netbox.examplecorp.io.crt;
   ssl_certificate_key /etc/nginx/conf.d/netbox.examplecorp.io.key;

   client_max_body_size 25m;

   location /static/ {
       alias /opt/netbox/netbox/static/;
   }

   location / {
       proxy_pass http://127.0.0.1:8001;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header Host $host;
       proxy_pass_header X-XSRF-TOKEN;
   }
}

Test and restart NGINX:

nginx -t
systemctl restart nginx

Troubleshooting

  • Database does not exist: Ensure DATABASE['NAME'] matches the database you created.
  • 502 Bad Gateway: Check ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS in configuration.py.
  • CSRF verification failed: Ensure NGINX headers and CSRF_TRUSTED_ORIGINS are correct.

Upgrading NetBox

When upgrading, check the release notes and follow multi-step upgrades for major version jumps (e.g., 3.x → 4.x). Use Git tags to check out releases:

sudo git fetch --tags
git describe --tags $(git rev-list --tags --max-count=1)
sudo git checkout v3.7.8   # Step 1
sudo git checkout v4.2.3   # Step 2

Ensure the correct Python version is used:

python3 --version
sudo dnf install python3.12
sudo alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1
sudo alternatives --config python3

Run the upgrade script:

sudo ./upgrade.sh
sudo systemctl restart netbox netbox-rq

This setup has become a core part of my home lab, providing an organized, overview of all devices, IPs, and attributes. Its active maintenance ensures my infrastructure documentation is always accurate and easy to navigate.

Related Posts