====== NetBox ======

| [[https://www.freshports.org/net-mgmt/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 ====

  * Before %%NetBox%% can be configured a new %%PostgreSQL%% database must be created:

<code>
$ psql -U postgres postgres
</code>

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

<code>
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
</code>

<callout type="warning">
Do not use the password from the above example.
</callout>

**References**

  * [[https://docs.netbox.dev/en/stable/installation/1-postgresql/#database-creation|Database creation]]

==== Install and setup a Redis server ====

Netbox requires a Redis server ([[https://www.freshports.org/databases/redis/|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:

<code>
# cd /usr/local/share/netbox/netbox/
# install -m 0640 -o www configuration_example.py configuration.py
</code>

<callout type="warning">
The **configuration.py** contains sensitive information (e.g. the %%PostgreSQL%% password, etc.) so please make sure it isn't world-readable.
</callout>

  - 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 ===

<code>
ALLOWED_HOSTS = ['netbox.example.com', 'anotherhost.example.com' ]
</code>

**References**

  * [[https://docs.netbox.dev/en/stable/installation/3-netbox/#allowed_hosts|ALLOWED_HOSTS]]

=== DATABASE variable ===

<code>
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)
}
</code>

**References**

  * [[https://docs.netbox.dev/en/stable/installation/3-netbox/#database|DATABASE]]

=== REDIS variable ===

  - The following parameters need to be configured to enable the tasks, webhooks and caching features:

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

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

**References**

  * [[https://docs.netbox.dev/en/stable/installation/3-netbox/#redis|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.

<code>
# python3.9 /usr/local/share/netbox/generate_secret_key.py
</code>

  - Configure the SECRET_KEY variable:

<code>
SECRET_KEY = 'dfIOdfa<dfOs0KxxjSb[ddljLfdghSSs9AsldxzZsajSoyssls'
</code>

<callout type="warning">
Do not use the SECRET_KEY from the above example.
</callout>

**References**

  * [[https://docs.netbox.dev/en/stable/installation/3-netbox/#secret_key|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.

<code>
DOCS_ROOT = '/usr/local/share/doc/netbox'
</code>

=== Finalizing the installation ===

  - Run database migrations

<code>
# cd /usr/local/share/netbox
# python3.9 manage.py migrate
</code>

  - Build embedded documentation for offline use (available since %%NetBox%% >= 3.2.0)

<code>
# mkdocs build
</code>

  - Collect static files

<code>
# python3.9 manage.py collectstatic --no-input
</code>

  - Create an administrative account

<code>
# python3.9 manage.py createsuperuser
</code>

==== Test NetBox in developer mode ====

<code>
# python3.9 manage.py runserver 0.0.0.0:8000 --insecure
</code>

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.

<callout type="warning">
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
</callout>

<callout type="warning">
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.
</callout>

**References**

  * [[https://docs.netbox.dev/en/stable/installation/3-netbox/#test-the-application|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 [[https://www.freshports.org/sysutils/py-supervisor/|sysutils/py-supervisor]].

=== Using rc scripts ===

== Run gunicorn via rc script ==

Since [[https://cgit.freebsd.org/ports/commit?id=24c244e70f76d84259e9c734c72448dd7e4c4a86|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:

<code>
# 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
</code>

Start the netbox rc script and verify that [[https://www.freshports.org/www/py-gunicorn/|www/py-gunicorn]] listens on 127.0.0.1:8001 . Please see [[#a_multi_interfaces|this chapter]] how to configure [[https://www.freshports.org/www/py-gunicorn/|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 [[https://www.freshports.org/www/py-gunicorn/|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 [[#a_using_configfile|configuration file]].

  - Create a **/usr/local/etc/netbox.conf.py** [[#a_using_configfile|configuration file]]

  - Tell the netbox rc script that it should read the parameters for [[https://www.freshports.org/www/py-gunicorn/|www/py-gunicorn]] from a configuration file.

<code>
sysrc netbox_use_config="YES"
</code>

  - If the configuration file exists in another directory the rc script needs also the location to it:

<code>
sysrc netbox_config="/your/own/path/to/netbox.conf.py"
</code>

== 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:

<code>
# 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
</code>

=== Using supervisor ===

  - Install and enable [[https://www.freshports.org/sysutils/py-supervisor/|sysutils/py-supervisor]]
  - Create a **/usr/local/etc/netbox.conf.py** [[#a_using_configfile|configuration file]]

== Run gunicorn via supervisor ==

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

<code>
[program:netbox]
command = /usr/local/bin/gunicorn -c /usr/local/etc/netbox.conf.py netbox.wsgi
directory = /usr/local/share/netbox/
user = www
</code>

  - Start supervisord and verify that [[https://www.freshports.org/www/py-gunicorn/|www/py-gunicorn]] gunicorn listens on 127.0.0.1:8001 . Please see [[#a_multi_interfaces|below]] how to configure [[https://www.freshports.org/www/py-gunicorn/|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**:

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

=== 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:

<code>
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'
</code>

**References**

  * [[https://docs.netbox.dev/en/stable/installation/4-gunicorn/#configuration|gunicorn configuration]]
  * [[https://github.com/netbox-community/netbox/blob/develop/contrib/gunicorn.py|Sample gunicorn.py configuration]]

== Using multiple interfaces with www/gunicorn ==

If [[https://www.freshports.org/www/py-gunicorn/|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:

<code>
sysrc netbox_extra_args="-b '[::1]:8001'"
</code>

  * If using a configuration file the **bind** variable should be set like this:

<code>
bind = ['127.0.0.1:8001','[::1]:8001']
</code>

=== 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 [[https://cgit.freebsd.org/ports/commit?id=0627700a0bbe12ba86c7c4e636ebb434c2d326a7|0627700a0bbe]], which can be enabled via the following steps:

<code>
# 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"
</code>

==== 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 [[https://www.freshports.org/www/nginx/|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:

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

Please change the parameters and permissions that suit your environment.

**References**

  * [[https://docs.netbox.dev/en/stable/installation/5-http-server/#obtain-an-ssl-certificate|Obtain a SSL certificate]]

=== Apache ===

  - Install and enable [[https://www.freshports.org/www/apache24/|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:

<code>
<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>
</code>

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

**References**

  * [[https://docs.netbox.dev/en/stable/installation/5-http-server/#option-b-apache|HTTP server installation (Apache)]]
  * [[https://github.com/netbox-community/netbox/blob/develop/contrib/apache.conf|Sample apache.conf]]

=== nginx ===

  - Install and enable [[https://www.freshports.org/www/nginx/|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:

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

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

**References**

  * [[https://docs.netbox.dev/en/stable/installation/5-http-server/#option-a-nginx|HTTP server installation (nginx)]]
  * [[https://github.com/netbox-community/netbox/blob/develop/contrib/nginx.conf|Sample nginx.conf]]

==== 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 [[https://www.freshports.org/net-mgmt/py-napalm|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

<code>
# cd /usr/local/share/netbox
# python3.9 manage.py migrate
</code>

  - Trace any missing cable paths

<code>
# python3.9 manage.py trace_paths --no-input
</code>

  - Build the embedded documentation (only required for %%NetBox%% >= 3.2.0)

<code>
# mkdocs build
</code>

  - Collect static files

<code>
# python3.9 manage.py collectstatic --no-input
</code>

  - Remove stale content types

<code>
# python3.9 manage.py remove_stale_contenttypes --no-input
</code>

  - Rebuild the search cache (lazily) (only required for %%NetBox%% >= 3.4.5)

<code>
# python3.9 manage.py reindex --lazy
</code>

  - Delete any expired user sessions (only required for %%NetBox%% <= 2.11.12)

<code>
# python3.9 manage.py clearsessions
</code>

  - Clear the cache (only required for %%NetBox%% >= 3.2.3)

<code>
# python3.9 manage.py clearcache
</code>

  - Restart WSGI/httpd environment (Apache/Nginx/etc.)

**References**

  * [[https://docs.netbox.dev/en/stable/installation/upgrading/#run-the-upgrade-script|Upgrading NetBox]]
  * [[https://github.com/netbox-community/netbox/blob/develop/upgrade.sh|Upgrade script]]

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

----

{{tag>HowTo Ports}}