Netbox

Install

Upgrading to a New NetBox Release

Install

PostgreSQL Database
Installation
This section entails the installation and configuration of a local PostgreSQL database. If you already
have a PostgreSQL database service in place, skip to the next section.

PostgreSQL 10 or later required

NetBox requires PostgreSQL 10 or later. Please note that MySQL and other relational databases are
not supported.

Installation
◉○
UbuntuCentOS

sudo apt update

sudo apt install -y postgresql

Once PostgreSQL has been installed, start the service and enable it to run at boot:

sudo systemctl start postgresql

sudo systemctl enable postgresql

Before continuing, verify that you have installed PostgreSQL 10 or later:

psql -V
Database Creation
At a minimum, we need to create a database for NetBox and assign it a username and password
for authentication. Start by invoking the PostgreSQL shell as the system Postgres user.

sudo -u postgres psql

Within the shell, enter the following commands to create the database and user (role), substituting
your own value for the password:

CREATE DATABASE netbox;

CREATE USER netbox WITH PASSWORD 'J5brHrAXFLQSif0K';

GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox;

Use a strong password

Do not use the password from the example. Choose a strong, random password to ensure
secure database authentication for your NetBox installation.

Once complete, enter \q to exit the PostgreSQL shell.

Verify Service Status

You can verify that authentication works by executing the psql command and passing the
configured username and password. (Replace localhost with your database server if using a
remote database.)

$ psql --username netbox --password --host localhost netbox

Password for user netbox:

psql (12.5 (Ubuntu 12.5-0ubuntu0.20.04.1))

SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression:

off)

Type "help" for help.

netbox=> \conninfo
 You are connected to database "netbox" as user "netbox" on host "localhost" (address

"127.0.0.1") at port "5432".

SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression:

off)

netbox=> \q

If successful, you will enter a netbox prompt. Type \conninfo to confirm your connection, or type
\q to exit.

Redis Installation

Install Redis
Redis is an in-memory key-value store which NetBox employs for caching and queuing. This section
entails the installation and configuration of a local Redis instance. If you already have a Redis
service in place, skip to the next section.

Redis v4.0 or later required

NetBox v2.9.0 and later require Redis v4.0 or higher. If your distribution does not offer a recent
enough release, you will need to build Redis from source. Please see the Redis installation

documentation for further details.

◉○
UbuntuCentOS

sudo apt install -y redis-server

Before continuing, verify that your installed version of Redis is at least v4.0:

redis-server -v

You may wish to modify the Redis configuration at /etc/redis.conf or /etc/redis/redis.conf ,

however in most cases the default configuration is sufficient.
Verify Service Status
Use the redis-cli utility to ensure the Redis service is functional:

redis-cli ping

If successful, you should receive a PONG response from the server.

NetBox Installation
This section of the documentation discusses installing and configuring the NetBox application itself.

Install System Packages

Begin by installing all system packages required by NetBox and its dependencies.

Python 3.8 or later required

NetBox v3.2 requires Python 3.8, 3.9, or 3.10.

◉○
UbuntuCentOS

sudo apt install -y python3 python3-pip python3-venv python3-dev build-essential libxml2-dev

libxslt1-dev libffi-dev libpq-dev libssl-dev zlib1g-dev

Before continuing, check that your installed Python version is at least 3.8:

python3 -V

Download NetBox
This documentation provides two options for installing NetBox: from a downloadable archive, or
from the git repository. Installing from a package (option A below) requires manually fetching and
extracting the archive for every future update, whereas installation via git (option B) allows for
seamless upgrades by re-pulling the master branch.

Option A: Download a Release Archive

Download the latest stable release from GitHub as a tarball or ZIP archive and extract it to your
desired path. In this example, we'll use /opt/netbox as the NetBox root.

sudo wget https://github.com/netbox-community/netbox/archive/vX.Y.Z.tar.gz

sudo tar -xzf vX.Y.Z.tar.gz -C /opt

sudo ln -s /opt/netbox-X.Y.Z/ /opt/netbox

Note

It is recommended to install NetBox in a directory named for its version number. For example,
NetBox v3.0.0 would be installed into /opt/netbox-3.0.0 , and a symlink from /opt/netbox/ would
point to this location. (You can verify this configuration with the command ls -l /opt | grep
netbox .) This allows for future releases to be installed in parallel without interrupting the current
installation. When changing to the new release, only the symlink needs to be updated.

Option B: Clone the Git Repository

Create the base directory for the NetBox installation. For this guide, we'll use /opt/netbox .

sudo mkdir -p /opt/netbox/

cd /opt/netbox/

If git is not already installed, install it:

◉○
UbuntuCentOS

sudo apt install -y git

Next, clone the master branch of the NetBox GitHub repository into the current directory. (This
branch always holds the current stable release.)
 sudo git clone -b master --depth 1 https://github.com/netbox-community/netbox.git .

Note

The git clone command above utilizes a "shallow clone" to retrieve only the most recent commit.
If you need to download the entire history, omit the --depth 1 argument.

The git clone command should generate output similar to the following:

Cloning into '.'...

remote: Enumerating objects: 996, done.

remote: Counting objects: 100% (996/996), done.

remote: Compressing objects: 100% (935/935), done.

remote: Total 996 (delta 148), reused 386 (delta 34), pack-reused 0

Receiving objects: 100% (996/996), 4.26 MiB | 9.81 MiB/s, done.

Resolving deltas: 100% (148/148), done.

Note

Installation via git also allows you to easily try out different versions of NetBox. To check out a
specific NetBox release, use the git checkout command with the desired release tag. For example,
git checkout v3.0.8 .

Create the NetBox System User

Create a system user account named netbox . We'll configure the WSGI and HTTP services to run
under this account. We'll also assign this user ownership of the media directory. This ensures that
NetBox will be able to save uploaded files.

◉○
UbuntuCentOS

sudo adduser --system --group netbox

sudo chown --recursive netbox /opt/netbox/netbox/media/

Configuration
Move into the NetBox configuration directory and make a copy of configuration_example.py named
configuration.py . This file will hold all of your local configuration parameters.

cd /opt/netbox/netbox/netbox/

sudo cp configuration_example.py configuration.py

Open configuration.py with your preferred editor to begin configuring NetBox. NetBox offers many

configuration parameters, but only the following four are required for new installations:

ALLOWED_HOSTS
DATABASE
REDIS
SECRET_KEY

ALLOWED_HOSTS
This is a list of the valid hostnames and IP addresses by which this server can be reached. You
must specify at least one name or IP address. (Note that this does not restrict the locations from
which NetBox may be accessed: It is merely for HTTP host header validation.)

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

If you are not yet sure what the domain name and/or IP address of the NetBox installation will be,
you can set this to a wildcard (asterisk) to allow all host values:

ALLOWED_HOSTS = ['*']

DATABASE
This parameter holds the database configuration details. You must define the username and
password used when you configured PostgreSQL. If the service is running on a remote host, update
the HOST and PORT parameters accordingly. See the configuration documentation for more detail
on individual parameters.
 DATABASE = {

'NAME': 'netbox', # Database name

'USER': 'netbox', # PostgreSQL username

'PASSWORD': 'J5brHrAXFLQSif0K', # PostgreSQL password

'HOST': 'localhost', # Database server

'PORT': '', # Database port (leave blank for default)

'CONN_MAX_AGE': 300, # Max database connection age (seconds)

REDIS
Redis is a in-memory key-value store used by NetBox for caching and background task queuing.
Redis typically requires minimal configuration; the values below should suffice for most
installations. See the configuration documentation for more detail on individual parameters.

Note that NetBox requires the specification of two separate Redis databases: tasks and caching .
These may both be provided by the same Redis service, however each should have a unique
numeric database ID.

REDIS = {

'tasks': {

'HOST': 'localhost', # Redis server

'PORT': 6379, # Redis port

'PASSWORD': '', # Redis password (optional)

'DATABASE': 0, # Database ID

'SSL': False, # Use SSL (optional)

},

'caching': {

'HOST': 'localhost',

'PORT': 6379,

'PASSWORD': '',

'DATABASE': 1, # Unique ID for second database

'SSL': False,

}
SECRET_KEY
This parameter must be assigned a randomly-generated key employed as a salt for hashing and
related cryptographic functions. (Note, however, that it is never directly used in the encryption of
secret data.) This key must be unique to this installation and is recommended to be at least 50
characters long. It should not be shared outside the local system.

A simple Python script named generate_secret_key.py is provided in the parent directory to assist in
generating a suitable key:

python3 ../generate_secret_key.py

SECRET_KEY values must match

In the case of a highly available installation with multiple web servers, SECRET_KEY must be
identical among all servers in order to maintain a persistent user session state.

When you have finished modifying the configuration, remember to save the file.

Optional Requirements
All Python packages required by NetBox are listed in requirements.txt and will be installed
automatically. NetBox also supports some optional packages. If desired, these packages must be
listed in local_requirements.txt within the NetBox root directory.

NAPALM
Integration with the NAPALM automation library allows NetBox to fetch live data from devices and
return it to a requester via its REST API. The NAPALM_USERNAME and NAPALM_PASSWORD configuration
parameters define the credentials to be used when connecting to a device.

sudo sh -c "echo 'napalm' >> /opt/netbox/local_requirements.txt"

Remote File Storage

By default, NetBox will use the local filesystem to store uploaded files. To use a remote filesystem,
install the django-storages library and configure your desired storage backend in configuration.py .

sudo sh -c "echo 'django-storages' >> /opt/netbox/local_requirements.txt"

Run the Upgrade Script

Once NetBox has been configured, we're ready to proceed with the actual installation. We'll run the
packaged upgrade script ( upgrade.sh ) to perform the following actions:

Create a Python virtual environment

Installs all required Python packages
Run database schema migrations
Builds the documentation locally (for offline use)
Aggregate static resource files on disk

sudo /opt/netbox/upgrade.sh

Note that Python 3.8 or later is required for NetBox v3.2 and later releases. If the default
Python installation on your server is set to a lesser version, pass the path to the supported
installation as an environment variable named PYTHON . (Note that the environment variable must
be passed after the sudo command.)

sudo PYTHON=/usr/bin/python3.8 /opt/netbox/upgrade.sh

Note

Upon completion, the upgrade script may warn that no existing virtual environment was detected.
As this is a new installation, this warning can be safely ignored.

Create a Super User

NetBox does not come with any predefined user accounts. You'll need to create a super user
(administrative account) to be able to log into NetBox. First, enter the Python virtual environment
created by the upgrade script:
 source /opt/netbox/venv/bin/activate

Once the virtual environment has been activated, you should notice the string (venv) prepended
to your console prompt.

Next, we'll create a superuser account using the createsuperuser Django management command
(via manage.py ). Specifying an email address for the user is not required, but be sure to use a very
strong password.

cd /opt/netbox/netbox

python3 manage.py createsuperuser

Schedule the Housekeeping Task

NetBox includes a housekeeping management command that handles some recurring cleanup
tasks, such as clearing out old sessions and expired change records. Although this command may
be run manually, it is recommended to configure a scheduled job using the system's cron daemon
or a similar utility.

A shell script which invokes this command is included at contrib/netbox-housekeeping.sh . It can be

copied to or linked from your system's daily cron task directory, or included within the crontab
directly. (If installing NetBox into a nonstandard path, be sure to update the system paths within
this script first.)

sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping

See the housekeeping documentation for further details.

Test the Application

At this point, we should be able to run NetBox's development server for testing. We can check by
starting a development instance:

python3 manage.py runserver 0.0.0.0:8000 --insecure

If successful, you should see output similar to the following:

Watching for file changes with StatReloader

Performing system checks...

System check identified no issues (0 silenced).

August 30, 2021 - 18:02:23

Django version 3.2.6, using settings 'netbox.settings'

Starting development server at http://127.0.0.1:8000/

Quit the server with CONTROL-C.

Next, connect to the name or IP of the server (as defined in ALLOWED_HOSTS ) on port 8000; for
example, http://127.0.0.1:8000/. You should be greeted with the NetBox home page. Try logging in
using the username and password specified when creating a superuser.

Note

By default RHEL based distros will likely block your testing attempts with firewalld. The
development server port can be opened with firewall-cmd (add --permanent if you want the rule to
survive server restarts):

firewall-cmd --zone=public --add-port=8000/tcp

Not for production use

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.

Warning

If the test service does not run, or you cannot reach the NetBox home page, something has gone
wrong. Do not proceed with the rest of this guide until the installation has been corrected.

Type Ctrl+c to stop the development server.

Gunicorn
Like most Django applications, NetBox runs as a WSGI application behind an HTTP server. This

documentation shows how to install and configure gunicorn (which is automatically installed with
NetBox) for this role, however other WSGI servers are available and should work similarly well.
uWSGI is a popular alternative.

Configuration
NetBox ships with a default configuration file for gunicorn. To use it, copy
/opt/netbox/contrib/gunicorn.py to /opt/netbox/gunicorn.py . (We make a copy of this file rather
than pointing to it directly to ensure that any local changes to it do not get overwritten by a future
upgrade.)

sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py

While the provided configuration should suffice for most initial installations, you may wish to edit
this file to change the bound IP address and/or port number, or to make performance-related
adjustments. See the Gunicorn documentation for the available configuration parameters.

systemd Setup
We'll use systemd to control both gunicorn and NetBox's background worker process. First, copy
contrib/netbox.service and contrib/netbox-rq.service to the /etc/systemd/system/ directory and
reload the systemd daemon:

sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/

sudo systemctl daemon-reload

Then, start the netbox and netbox-rq services and enable them to initiate at boot time:

sudo systemctl start netbox netbox-rq

sudo systemctl enable netbox netbox-rq

You can use the command systemctl status netbox to verify that the WSGI service is running:
 systemctl status netbox.service

You should see output similar to the following:

● netbox.service - NetBox WSGI Service

Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)

Active: active (running) since Mon 2021-08-30 04:02:36 UTC; 14h ago

Docs: https://docs.netbox.dev/

Main PID: 1140492 (gunicorn)

Tasks: 19 (limit: 4683)

Memory: 666.2M

CGroup: /system.slice/netbox.service

├─1140492 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>

├─1140513 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>

├─1140514 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>

...

Note

If the NetBox service fails to start, issue the command journalctl -eu netbox to check for log
messages that may indicate the problem.

Once you've verified that the WSGI workers are up and running, move on to HTTP server setup.

HTTP Server Setup

This documentation provides example configurations for both nginx and Apache, though any HTTP
server which supports WSGI should be compatible.

Info

For the sake of brevity, only Ubuntu 20.04 instructions are provided here. These tasks are not
unique to NetBox and should carry over to other distributions with minimal changes. Please consult
your distribution's documentation for assistance if needed.

Obtain an SSL Certificate

To enable HTTPS access to NetBox, you'll need a valid SSL certificate. You can purchase one from a
trusted commercial provider, obtain one for free from Let's Encrypt, or generate your own
(although self-signed certificates are generally untrusted). Both the public certificate and private
key files need to be installed on your NetBox server in a location that is readable by the netbox
user.

The command below can be used to generate a self-signed certificate for testing purposes,
however it is strongly recommended to use a certificate from a trusted authority in production. Two
files will be created: the public certificate ( netbox.crt ) and the private key ( netbox.key ). The
certificate is published to the world, whereas the private key must be kept secret at all times.

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \

-keyout /etc/ssl/private/netbox.key \

-out /etc/ssl/certs/netbox.crt

The above command will prompt you for additional details of the certificate; all of these are
optional.

HTTP Server Installation

Option A: nginx
Begin by installing nginx:

sudo apt install -y nginx

Once nginx is installed, copy the nginx configuration file provided by NetBox to /etc/nginx/sites-
available/netbox . Be sure to replace netbox.example.com with the domain name or IP address of
your installation. (This should match the value configured for ALLOWED_HOSTS in configuration.py .)

sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox

Then, delete /etc/nginx/sites-enabled/default and create a symlink in the sites-enabled directory

to the configuration file you just created.
 sudo rm /etc/nginx/sites-enabled/default

sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox

Finally, restart the nginx service to use the new configuration.

sudo systemctl restart nginx

Option B: Apache
Begin by installing Apache:

sudo apt install -y apache2

Next, copy the default configuration file to /etc/apache2/sites-available/ . Be sure to modify the
ServerName parameter appropriately.

sudo cp /opt/netbox/contrib/apache.conf /etc/apache2/sites-available/netbox.conf

Finally, ensure that the required Apache modules are enabled, enable the netbox site, and reload
Apache:

sudo a2enmod ssl proxy proxy_http headers

sudo a2ensite netbox

sudo systemctl restart apache2

Confirm Connectivity
At this point, you should be able to connect to the HTTPS service at the server name or IP address
you provided.

Info

Please keep in mind that the configurations provided here are bare minimums required to get
NetBox up and running. You may want to make adjustments to better suit your production
environment.

Warning

Certain components of NetBox (such as the display of rack elevation diagrams) rely on the use of
embedded objects. Ensure that your HTTP server configuration does not override the X-Frame-
Options response header set by NetBox.

Troubleshooting
If you are unable to connect to the HTTP server, check that:

Nginx/Apache is running and configured to listen on the correct port.

Access is not being blocked by a firewall somewhere along the path. (Try connecting
locally from the server itself.)

If you are able to connect but receive a 502 (bad gateway) error, check the following:

The WSGI worker processes (gunicorn) are running ( systemctl status netbox should show
a status of "active (running)")
Nginx/Apache is configured to connect to the port on which gunicorn is listening (default is
8001).
SELinux is not preventing the reverse proxy connection. You may need to allow HTTP
network connections with the command setsebool -P httpd_can_network_connect 1
Upgrading to a New NetBox
Release

Review the Release Notes

Prior to upgrading your NetBox instance, be sure to carefully review all release notes that have
been published since your current version was released. Although the upgrade process typically
does not involve additional work, certain releases may introduce breaking or backward-
incompatible changes. These are called out in the release notes under the release in which the
change went into effect.

Update Dependencies to Required

Versions
NetBox v3.0 and later require the following:

Dependency Minimum Version

Python 3.8

PostgreSQL 10

Redis 4.0

Install the Latest Release

As with the initial installation, you can upgrade NetBox by either downloading the latest release
package or by cloning the master branch of the git repository.

Option A: Download a Release

Download the latest stable release from GitHub as a tarball or ZIP archive. Extract it to your desired
path. In this example, we'll use /opt/netbox .

Download and extract the latest version:

wget https://github.com/netbox-community/netbox/archive/vX.Y.Z.tar.gz

sudo tar -xzf vX.Y.Z.tar.gz -C /opt

sudo ln -sfn /opt/netbox-X.Y.Z/ /opt/netbox

Copy local_requirements.txt , configuration.py , and ldap_config.py (if present) from the current
installation to the new version:

sudo cp /opt/netbox-X.Y.Z/local_requirements.txt /opt/netbox/

sudo cp /opt/netbox-X.Y.Z/netbox/netbox/configuration.py /opt/netbox/netbox/netbox/

sudo cp /opt/netbox-X.Y.Z/netbox/netbox/ldap_config.py /opt/netbox/netbox/netbox/

Be sure to replicate your uploaded media as well. (The exact action necessary will depend on
where you choose to store your media, but in general moving or copying the media directory will
suffice.)

sudo cp -pr /opt/netbox-X.Y.Z/netbox/media/ /opt/netbox/netbox/

Also make sure to copy or link any custom scripts and reports that you've made. Note that if these
are stored outside the project root, you will not need to copy them. (Check the SCRIPTS_ROOT and
REPORTS_ROOT parameters in the configuration file above if you're unsure.)

sudo cp -r /opt/netbox-X.Y.Z/netbox/scripts /opt/netbox/netbox/

sudo cp -r /opt/netbox-X.Y.Z/netbox/reports /opt/netbox/netbox/

If you followed the original installation guide to set up gunicorn, be sure to copy its configuration as
well:

sudo cp /opt/netbox-X.Y.Z/gunicorn.py /opt/netbox/

Option B: Clone the Git Repository
This guide assumes that NetBox is installed at /opt/netbox . Pull down the most recent iteration of
the master branch:

cd /opt/netbox

sudo git checkout master

sudo git pull origin master

Checking out an older release

If you need to upgrade to an older version rather than the current stable release, you can check
out any valid git tag, each of which represents a release. For example, to checkout the code for
NetBox v2.11.11, do:

sudo git checkout v2.11.11

Run the Upgrade Script

Once the new code is in place, verify that any optional Python packages required by your
deployment (e.g. napalm or django-auth-ldap ) are listed in local_requirements.txt . Then, run the
upgrade script:

sudo ./upgrade.sh

Warning

If the default version of Python is not at least 3.8, you'll need to pass the path to a supported
Python version as an environment variable when calling the upgrade script. For example:

sudo PYTHON=/usr/bin/python3.8 ./upgrade.sh

This script performs the following actions:

Destroys and rebuilds the Python virtual environment

 Installs all required Python packages (listed in requirements.txt )
Installs any additional packages from local_requirements.txt
Applies any database migrations that were included in the release
Builds the documentation locally (for offline use)
Collects all static files to be served by the HTTP service
Deletes stale content types from the database
Deletes all expired user sessions from the database

Note

If the upgrade script prompts a warning about unreflected database migrations, this indicates that
some change has been made to your local codebase and should be investigated. Never attempt to
create new migrations unless you are intentionally modifying the database schema.

Restart the NetBox Services

Warning

If you are upgrading from an installation that does not use a Python virtual environment (any
release prior to v2.7.9), you'll need to update the systemd service files to reference the new Python
and gunicorn executables before restarting the services. These are located in
/opt/netbox/venv/bin/ . See the example service files in /opt/netbox/contrib/ for reference.

Finally, restart the gunicorn and RQ services:

sudo systemctl restart netbox netbox-rq

Verify Housekeeping Scheduling

If upgrading from a release prior to NetBox v3.0, check that a cron task (or similar scheduled
process) has been configured to run NetBox's nightly housekeeping command. A shell script which
invokes this command is included at contrib/netbox-housekeeping.sh . It can be linked from your
system's daily cron task directory, or included within the crontab directly. (If NetBox has been
installed in a nonstandard path, be sure to update the system paths within this script first.)

sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping

See the housekeeping documentation for further details.