Table of Contents

NetBox

net-mgmt/netbox

IP address management tool

Set up NetBox on FreeBSD

Prerequisites for the database

NetBox requires a PostgreSQL database located on a local or remote server. The PostgreSQL server must be in Version 11.0 or higher. Because NetBox makes heavy usage of its built-in network address datatypes other RDBMS's like MySQL, MariaDB, etc. are not supported.

Create the PostgreSQL database

$ psql -U postgres postgres
postgres=# CREATE DATABASE netbox;
CREATE DATABASE
postgres=# CREATE USER netbox WITH PASSWORD 'S4mpleP4ssw0rd';
CREATE ROLE
postgres=# ALTER DATABASE netbox OWNER TO netbox;
GRANT
postgres=# \q
Do not use the password from the above example.

References

Install and setup a Redis server

Netbox requires a Redis server (databases/redis) instance (local or remote) for background tasks and caching objects.

Configure NetBox

Create the configuration file

  1. Move into the NetBox directory, create a new configuration from the shipped example configuration and tighten the permissions of it:
# cd /usr/local/share/netbox/netbox/
# install -m 0640 -o www configuration_example.py configuration.py
The configuration.py contains sensitive information (e.g. the PostgreSQL password, etc.) so please make sure it isn't world-readable.
  1. Edit configuration.py with an editor of your choice.
  1. Configure the variables ALLOWED_HOSTS, DATABASE, SECRET_KEY and DOCS_ROOT with the respective values:

ALLOWED_HOST variable

ALLOWED_HOSTS = ['netbox.example.com', 'anotherhost.example.com' ]

References

DATABASE variable

DATABASE = {
    'NAME': 'netbox',             # Database name
    'USER': 'netbox',             # PostgreSQL username
    'PASSWORD': 'S4mpleP4ssw0rd', # PostgreSQL password you used in
                                  # step "Create the PostgreSQL database"
    'HOST': 'localhost',          # Database server
    'PORT': '',                   # Database port (leave blank for default)
    'CONN_MAX_AGE': 300,          # Max database connection age (seconds)
}

References

REDIS variable

  1. The following parameters need to be configured to enable the tasks, webhooks and caching features:
REDIS = {
    'tasks': {
        'HOST': 'tasks-redis-server.example.com', # Redis server
        'PORT': 6379,                             # Redis port
        'PASSWORD': '',                           # Redis password (optional)
        'DATABASE': 0,                            # Database ID
        'SSL': False,                             # Use SSL (optional)
    },
    'caching': {
        'HOST': 'caching-redis-server.example.com',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 1,                            # Unique ID for second database
        'SSL': False,
    }
}
  1. It's also fine to use the same Redis service for both functions, although the database identifiers should be different.

References

SECRET_KEY variable

  1. Generate a secret key and add the value to the SECRET_KEY variable. The supplied script generate_secret_key.py can be used for this task. Of course you can also generate your own key which must contain at least 50 alpha-numeric characters then.
# python3.9 /usr/local/share/netbox/generate_secret_key.py
  1. Configure the SECRET_KEY variable:
SECRET_KEY = 'dfIOdfa<dfOs0KxxjSb[ddljLfdghSSs9AsldxzZsajSoyssls'
Do not use the SECRET_KEY from the above example.

References

DOCS_ROOT variable (only required for NetBox <= 2.11.12)

To be able to access the embedded documentation, the DOCS_ROOT variable must be set accordingly. 

DOCS_ROOT = '/usr/local/share/doc/netbox'

Finalizing the installation

  1. Run database migrations
# cd /usr/local/share/netbox
# python3.9 manage.py migrate
  1. Build embedded documentation for offline use (available since NetBox >= 3.2.0)
# mkdocs build
  1. Collect static files
# python3.9 manage.py collectstatic --no-input
  1. Create an administrative account
# python3.9 manage.py createsuperuser

Test NetBox in developer mode

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

You should reach NetBox at port 8000 and should be greeted with the NetBox home page. Try logging in using the username and password specified when creating a superuser.

If the test service does not run, or you cannot reach the NetBox home page, something has gone wrong. Please check the previous steps for errors in that case
The development server is for development and testing purposes only. It is neither performant nor secure enough for production use. Do not use it in production.

References

Run NetBox as service

NetBox can be run as a service by using either the supplied rc scripts that are installed by default via the EXAMPLES option or sysutils/py-supervisor.

Using rc scripts

Run gunicorn via rc script

Since 24c244e70f76 NetBox installs a sample script by default (kudos to Thomas Kurschel!). Using the rc script can be used nearly out of the box and eliminates the need of supervisord: 

# cp /usr/local/share/examples/netbox/netboxrc.sample /usr/local/etc/rc.d/netbox
# chmod 555 /usr/local/etc/rc.d/netbox
# sysrc netbox_enable="YES"
# service netbox start

Start the netbox rc script and verify that www/py-gunicorn listens on 127.0.0.1:8001 . Please see this chapter how to configure www/py-gunicorn for multiple interfaces/addresses, e.g. if using an IPv4/IPv6 dualstack configuration.

Configure gunicorn to use a separate configuration file (optional)

The script already uses various default values for www/py-gunicorn that are defined by upstream and should cause no issues on most installations. You can configure those values either by setting the appropriate rc variables (see the script for further details) or using a separate configuration file.

  1. Create a /usr/local/etc/netbox.conf.py configuration file
  1. Tell the netbox rc script that it should read the parameters for www/py-gunicorn from a configuration file.
sysrc netbox_use_config="YES"
  1. If the configuration file exists in another directory the rc script needs also the location to it:
sysrc netbox_config="/your/own/path/to/netbox.conf.py"
Run the RQ worker via rc script

The RQ worker service is required for background tasks and webhooks. The sample rc script that is installed via the EXAMPLES option can be set up quickly for this task: 

# cp /usr/local/share/examples/netbox/netbox_rq.sample /usr/local/etc/rc.d/netbox_rq
# chmod 555 /usr/local/etc/rc.d/netbox_rq
# sysrc netbox_rq_enable="YES"
# service netbox_rq start

Using supervisor

  1. Install and enable sysutils/py-supervisor
  2. Create a /usr/local/etc/netbox.conf.py configuration file
Run gunicorn via supervisor
  1. Edit /usr/local/share/etc/supervisord.conf:
[program:netbox]
command = /usr/local/bin/gunicorn -c /usr/local/etc/netbox.conf.py netbox.wsgi
directory = /usr/local/share/netbox/
user = www
  1. Start supervisord and verify that www/py-gunicorn gunicorn listens on 127.0.0.1:8001 . Please see below how to configure www/py-gunicorn for multiple interfaces/addresses, e.g. if using an IPv4/IPv6 dualstack configuration.
Run the RQ worker via supervisor
  1. Edit /usr/local/share/etc/supervisord.conf:
[program:netbox_rq]
command = /usr/local/bin/python3.9 manage.py rqworker
directory = /usr/local/share/netbox
user = www

Configure gunicorn

Using a separate configuration file
  1. Create /usr/local/etc/netbox.conf.py (the sample gunicorn.py that is installed via the EXAMPLES option can also be used as template for it). Please note that the configuration file should have a valid Python extension (= “.py”) otherwise gunicorn will emit a warning:
command = '/usr/local/bin/gunicorn'
pythonpath = '/usr/local/share/netbox'

# The IP address (typically localhost) and port that the Netbox WSGI process should listen on
bind = '127.0.0.1:8001'

# If NetBox should listen on multiple interfaces, e.g. with a IPv4/IPv6
# dualstack configuration, use the following line instead
# bind = ['127.0.0.1:8001','[::1]:8001']

# Number of gunicorn workers to spawn. This should typically be 2n+1, where
# n is the number of CPU cores present.
workers = 5

# Number of threads per worker process
threads = 3

# Timeout (in seconds) for a request to complete
timeout = 120

# The maximum number of requests a worker can handle before being respawned
max_requests = 5000
max_requests_jitter = 500

# The user to run gunicorn with
user = 'www'

References

Using multiple interfaces with www/gunicorn

If www/py-gunicorn should listen on multiple interfaces/addresses, e.g. with an IPv4/IPv6 dualstack, some small tweaks are required. 

sysrc netbox_extra_args="-b '[::1]:8001'"
bind = ['127.0.0.1:8001','[::1]:8001']

Run periodic housekeeping tasks (NetBox v3.x only)

A new “housekeeping” command has been introduced since NetBox 3.0 and a corresponding periodic script (via the default EXAMPLES option) has been added in 0627700a0bbe, which can be enabled via the following steps: 

# cp /usr/local/share/examples/netbox/850.netbox-housekeeping.sample /usr/local/etc/periodic/daily/850.netbox-housekeeping
# chmod 555 /usr/local/etc/periodic/daily/850.netbox-housekeeping
# sysrc -f /etc/periodic.conf daily_netbox_housekeeping_enable="YES"

Configure a HTTP server

The following sections describes the setup using the Apache HTTP server to communicate with the gunicorn WSGI. It's also possible to use www/nginx as HTTP server instead of Apache.

Obtain a SSL certificate

If a self-signed certificate should be used the following command can be used: 

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /usr/local/etc/ssl/netbox.key -out /usr/local/etc/ssl/netbox.crt

Please change the parameters and permissions that suit your environment.

References

Apache

  1. Install and enable www/apache24
  2. Enable the following modules in /usr/local/etc/apache24/httpd.conf:
    • headers
    • proxy
    • proxy_http
  3. Create a new configuration file, e.g /usr/local/etc/apache24/Includes/netbox.conf . The sample configuration apache.conf that is installed via the EXAMPLES option can be used as an example:
<VirtualHost *:443>
        ProxyPreserveHost On
        
        ServerName netbox

        Alias /static /usr/local/share/netbox/static

        SSLEngine on
        SSLCertificateFile /usr/local/etc/ssl/netbox.crt
        SSLCertificateKeyFile /usr/local/etc/ssl/netbox.key

        <Directory /usr/local/share/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>
  1. Start the Apache server
  2. You should be able to reach NetBox on port 443

References

nginx

  1. Install and enable www/nginx
  2. Edit the nginx configuration file /usr/local/etc/nginx.conf . The snippets of the sample nginx.conf configuration that is installed via the EXAMPLES option can be used as an example:
server {
        listen 443 ssl;

        server_name netbox;

        ssl_certificate /usr/local/etc/ssl/netbox.crt;
        ssl_certificate_key /usr/local/etc/ssl/netbox.key;

        client_max_body_size 25m;

        location /static/ {
                alias /usr/local/share/netbox/netbox/static/;
        }

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

server {
        # Redirect HTTP traffic to HTTPS
        listen 80;
        server_name _;
        return 301 https://$host$request_uri;
        
        # Stricter and more correct type of redirect
        # See also https://datatracker.ietf.org/doc/html/rfc7538 
        #
        # return 308 https://$host$request_uri;
        #
        # Note: This might break some old browsers, e.g. IE11 on Win7
}
  1. Start the nginx server
  2. You should be able to reach NetBox on port 443

References

Notes and further information

Upgrading NetBox

As always it is strongly encouraged to make a backup before the upgrade is started. After the port has been updated the following steps are required to finish the upgrade:

  1. Run database migrations
# cd /usr/local/share/netbox
# python3.9 manage.py migrate
  1. Trace any missing cable paths
# python3.9 manage.py trace_paths --no-input
  1. Build the embedded documentation (only required for NetBox >= 3.2.0)
# mkdocs build
  1. Collect static files
# python3.9 manage.py collectstatic --no-input
  1. Remove stale content types
# python3.9 manage.py remove_stale_contenttypes --no-input
  1. Rebuild the search cache (lazily) (only required for NetBox >= 3.4.5)
# python3.9 manage.py reindex --lazy
  1. Delete any expired user sessions (only required for NetBox ⇐ 2.11.12)
# python3.9 manage.py clearsessions
  1. Clear the cache (only required for NetBox >= 3.2.3)
# python3.9 manage.py clearcache
  1. Restart WSGI/httpd environment (Apache/Nginx/etc.)

References

Common pitfalls

,