NetBox

IP address management tool

Contents

NetBox

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 12.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

Before NetBox can be configured a new PostgreSQL database must be created:
```
$ psql -U postgres postgres
```

Create the database, an user with a password and assign the permissions:

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

Database creation

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

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.

Edit configuration.py with an editor of your choice.
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

ALLOWED_HOSTS

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

DATABASE

REDIS variable

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,
    }
}

It's also fine to use the same Redis service for both functions, although the database identifiers should be different.

References

REDIS

SECRET_KEY variable

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.11 /usr/local/share/netbox/generate_secret_key.py
```

Configure the SECRET_KEY variable:

SECRET_KEY = 'dfIOdfa<dfOs0KxxjSb[ddljLfdghSSs9AsldxzZsajSoyssls'

Do not use the SECRET_KEY from the above example.

References

SECRET_KEY

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

Run database migrations

# cd /usr/local/share/netbox
# python3.11 manage.py migrate

Build embedded documentation for offline use (available since NetBox >= 3.2.0)
```
# mkdocs build
```

Collect static files

# python3.11 manage.py collectstatic --no-input

Create an administrative account
```
# python3.11 manage.py createsuperuser
```

Test NetBox in developer mode

# python3.11 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

Test the Application

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.

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

Install and enable sysutils/py-supervisor
Create a /usr/local/etc/netbox.conf.py configuration file

Run gunicorn via supervisor

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

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

Edit /usr/local/share/etc/supervisord.conf:

[program:netbox_rq]
command = /usr/local/bin/python3.11 manage.py rqworker
directory = /usr/local/share/netbox
user = www

Using NGINX Unit

Another way to run NetBox as a service is to use www/unit in conjunction with www/nginx (kudos to Peter of Flytrace for the hint and sample configs!).

Configure unit to run the NetBox application

Install and enable www/unit
Install and enable www/unit-python

Create a JSON configuration file for unitd, e.g. unitd.conf.json:

{
    "listeners": {
        "*:8001": {
        "pass": "routes"
        }
    },
    "routes": [
        {
            "match": {
                "uri": "/static/*"
            },
            "action": {
                "share": "/usr/local/share/netbox$uri"
            }
        },
        {
            "action": {
                "pass": "applications/django"
            }
        }
    ],
    "applications": {
        "django": {
            "type": "python 3",
            "user": "www",
            "group": "www",
            "path": "/usr/local/share/netbox/",
            "module": "netbox.wsgi"
        }
    }
}

Import the newly created configuration

curl -X PUT --data-binary @unitd.conf.json --unix-socket /var/run/unit/control.unit.sock http://localhost/config/

Restart unitd
Configure www/nginx as described in the chapter nginx.

References

Django with NGINX Unit

Run the RQ worker via rc script

The RQ worker service is required for background tasks and webhooks. See the chapter Run the RQ worker via rc script how to setup up the RQ worker via rc script.

Configure gunicorn

Using a separate configuration file

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'

Tell the netbox rc script that it should read the parameters for www/py-gunicorn from a configuration file.
```
sysrc netbox_use_config="YES"
```
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"
```

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.

If using the rc script those addresses need to be passed as extra arguments:
```
sysrc netbox_extra_args="-b '[::1]:8001'"
```
If using a configuration file the bind variable should be set like this:
```
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

Obtain a SSL certificate

nginx

Install and enable www/nginx

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;
        # Uncomment if NetBox is served via NGINX Unit
        #http2 on;

        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/;
        }

        # NB: For some setups it may also be necessary to configure CSRF_TRUSTED_ORIGINS.
        # See also https://github.com/netbox-community/netbox/discussions/9043 and
        # https://netboxlabs.com/docs/netbox/en/stable/configuration/security/#csrf_trusted_origins

        # Default setup if NetBox is served via gunicorn
        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;
        }

        # If NGINX Unit is used, comment out the above "location" block and uncomment
        # the "location" block below.
        #location / {
        #        proxy_pass      http://127.0.0.1:8001/;
        #        proxy_redirect  http:// https://;
        #        proxy_read_timeout      120;
        #        sub_filter      'http://' 'https://';
        #        sub_filter_once off;
        #        proxy_set_header X-Forwarded-Host $host;
        #        proxy_set_header X-Forwarded-Proto $scheme;
        #        proxy_set_header X-Real-IP $remote_addr;
        #}
}

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
}

Start the nginx server
You should be able to reach NetBox on port 443

References

Apache

Install and enable www/apache24
Enable the following modules in /usr/local/etc/apache24/httpd.conf:
- headers
- proxy
- proxy_http

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>

Start the Apache server
You should be able to reach NetBox on port 443

References

Notes and further information

If you want to upload files the folder /usr/local/share/netbox/media must be writeable.
NetBox can also be used together with net-mgmt/py-napalm for network automation.

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:

Run database migrations

# cd /usr/local/share/netbox
# python3.11 manage.py migrate

Trace any missing cable paths

# python3.11 manage.py trace_paths --no-input

Build the embedded documentation (only required for NetBox >= 3.2.0)
```
# mkdocs build
```

Collect static files

# python3.11 manage.py collectstatic --no-input

Remove stale content types

# python3.11 manage.py remove_stale_contenttypes --no-input

Rebuild the search cache (lazily) (only required for NetBox >= 3.4.5)
```
# python3.11 manage.py reindex --lazy
```
Delete any expired user sessions (only required for NetBox <= 2.11.12)
```
# python3.11 manage.py clearsessions
```
Clear the cache (only required for NetBox >= 3.2.3)
```
# python3.11 manage.py clearcache
```
Restart WSGI/httpd environment (Apache/Nginx/etc.)

References

Common pitfalls

If you replicate NetBox to another location (e.g. for tests), make sure that the directory /usr/share/netbox/media/image-attachments is also copied.

CategoryHowTo CategoryPorts