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

Do not use the password from the above example.


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

The contains sensitive information (e.g. the PostgreSQL password, etc.) so please make sure it isn't world-readable.

  1. Edit with an editor of your choice.

  2. Configure the variables ALLOWED_HOSTS, DATABASE, SECRET_KEY and DOCS_ROOT with the respective values:



DATABASE variable


REDIS variable

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


SECRET_KEY variable

  1. Generate a secret key and add the value to the SECRET_KEY variable. The supplied script 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/
  2. Configure the SECRET_KEY variable:
    SECRET_KEY = 'dfIOdfa<dfOs0KxxjSb[ddljLfdghSSs9AsldxzZsajSoyssls'

Do not use the SECRET_KEY from the above example.


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.

Finalizing the installation

  1. Run database migrations
    # cd /usr/local/share/netbox
    # python3.9 migrate
  2. Build embedded documentation for offline use (available since NetBox >= 3.2.0)

    # mkdocs build
  3. Collect static files
    # python3.9 collectstatic --no-input
  4. Create an administrative account
    # python3.9 createsuperuser

Test NetBox in developer mode

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.


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:

Start the netbox rc script and verify that www/py-gunicorn listens on . 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/ configuration file

  2. Tell the netbox rc script that it should read the parameters for www/py-gunicorn from a configuration file.

    sysrc netbox_use_config="YES"
  3. If the configuration file exists in another directory the rc script needs also the location to it:
    sysrc netbox_config="/your/own/path/to/"

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:

Using supervisor

  1. Install and enable sysutils/py-supervisor

  2. Create a /usr/local/etc/ configuration file

Run gunicorn via supervisor
  1. Edit /usr/local/share/etc/supervisord.conf:

    command = /usr/local/bin/gunicorn -c /usr/local/etc/ netbox.wsgi
    directory = /usr/local/share/netbox/
    user = www
  2. Start supervisord and verify that www/py-gunicorn gunicorn listens on . 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:

    command = /usr/local/bin/python3.9 rqworker
    directory = /usr/local/share/netbox
    user = www

Configure gunicorn

Using a separate configuration file
  1. Create /usr/local/etc/ (the sample 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 = ''
    # If NetBox should listen on multiple interfaces, e.g. with a IPv4/IPv6
    # dualstack configuration, use the following line instead
    # bind = ['','[::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'


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.

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:

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:

Please change the parameters and permissions that suit your environment.



  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
            <Location /static>
                    ProxyPass !
            RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
            ProxyPass /
            ProxyPassReverse /
  4. Start the Apache server
  5. You should be able to reach NetBox on port 443



  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_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 
            # return 308 https://$host$request_uri;
            # Note: This might break some old browsers, e.g. IE11 on Win7
  3. Start the nginx server
  4. You should be able to reach NetBox on port 443


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 migrate
  2. Trace any missing cable paths
    # python3.9 trace_paths --no-input
  3. Build the embedded documentation (only required for NetBox >= 3.2.0)

    # mkdocs build
  4. Collect static files
    # python3.9 collectstatic --no-input
  5. Remove stale content types
    # python3.9 remove_stale_contenttypes --no-input
  6. Rebuild the search cache (lazily) (only required for NetBox >= 3.4.5)

    # python3.9 reindex --lazy
  7. Delete any expired user sessions (only required for NetBox <= 2.11.12)

    # python3.9 clearsessions
  8. Clear the cache (only required for NetBox >= 3.2.3)

    # python3.9 clearcache
  9. Restart WSGI/httpd environment (Apache/Nginx/etc.)


Common pitfalls

CategoryHowTo CategoryPorts

Ports/net-mgmt/netbox (last edited 2023-06-29T13:09:36+0000 by KaiKnoblich)