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 9.6 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 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 and create a new configuration from the shipped example configuration

    # cd /usr/local/share/netbox/netbox/
    # cp configuration.example.py configuration.py
  2. Edit configuration.py with an editor of your choice.

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

ALLOWED_HOST variable

DATABASE variable

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,
        }
    }
  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 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.7 /usr/local/share/netbox/generate_secret_key.py
  2. Configure the SECRET_KEY variable:
    SECRET_KEY = 'dfIOdfa<dfOs0KxxjSb[ddljLfdghSSs9AsldxzZsajSoyssls'

Do not use the SECRET_KEY from the above example.

Finalizing the installation

  1. Run database migrations
    # cd /usr/local/share/netbox
    # python3.7 manage.py migrate
  2. Collect static files
    # python3.7 manage.py collectstatic --no-input
  3. Create an administrative account
    # python3.7 manage.py createsuperuser
  4. Load Initial Data (optional)
    # python3.7 manage.py loaddata initial_data

Test NetBox in developer mode

You should reach NetBox at port 8000 . If not, please check the previous steps for errors.

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 r513395 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 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 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/netbox.conf"

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/netbox.conf 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 netbox.wsgi
    directory = /usr/local/share/netbox/
    user = www
  2. 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.7 manage.py rqworker
    directory = /usr/local/share/netbox
    user = www

Configure gunicorn

Using a separate configuration file
  1. Create /usr/local/etc/netbox.conf (the sample gunicorn.py that is installed via the EXAMPLES option can also be used as template for it):

    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.

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.

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>
  4. Start the Apache server
  5. 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;
    }
  3. Start the nginx server
  4. 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.7 manage.py migrate
  2. Collect static files
    # python3.7 manage.py collectstatic --no-input
  3. Remove stale content types
    # python3.7 manage.py remove_stale_contenttypes --no-input
  4. Delete any expired user sessions
    # python3.7 manage.py clearsessions
  5. Clear all cached data
    # python3.7 manage.py invalidate all
  6. Restart WSGI/httpd environment (Apache/Nginx/etc.)

References

Common pitfalls


CategoryHowTo CategoryPorts

Ports/net-mgmt/netbox (last edited 2021-04-06 16:00:46 by KaiKnoblich)