Troubleshooting

This is a collection of some common issues and how to resolve them. If your issue is not here, look through the existing issues and eventually create a new issue.

Docker Compose basics

See all running containers:

docker-compose ps

See all logs:

docker-compose logs -f

See just the NetBox logs:

docker-compose logs -f netbox

Stop it all:

docker-compose stop

Reset the project:

⚠️ This will remove any Netbox-related data.

docker-compose down -v --remove-orphans
git reset --hard origin/release

Bash

Start the Netbox Container shell, e.g. to get access to ./manage.py or look for files:

docker-compose exec netbox /bin/bash

To load the Python environment for Netbox run:

source /opt/netbox/venv/bin/activate

Database Operations

Access the database:

docker-compose exec postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'

Take a database backup

docker-compose exec -T postgres sh -c 'pg_dump -cU $POSTGRES_USER $POSTGRES_DB' | gzip > db_dump.sql.gz

Restore that database:

# Stop all NetBox instances that access the db
docker-compose stop netbox netbox-worker netbox-housekeeping

# Restore the DB dump
gunzip -c db_dump.sql.gz | docker-compose exec -T postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'

File Operations

Backup of the media directory, which contains uploaded images.

docker-compose exec -T netbox tar c -jf - -C /opt/netbox/netbox/media ./ > media-backup.tar.bz2

Restore of the media directory:

⚠️ This may overwrite files in the media directory!

docker-compose exec -T netbox tar x -jvf - -C /opt/netbox/netbox/media < media-backup.tar.bz2 

Netbox Worker Operations

See the status of the worker queue:

docker-compose run --rm netbox-worker /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py rqstats

Netbox Shell (nbshell)

The nbshell is a way to quickly get programmatic access to Netbox. It offers about the same interface as the Netbox REST API.

docker-compose run --rm netbox /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py nbshell

Frequently Asked Questions (FAQ) and Common Problems

Getting to "process X exited with code 0"

You find yourself with a NetBox Docker instance that tells you something like:

[notice] 7#7 process 14 exited with code 0

Congratulations! Your NetBox Docker instance most definitely started successfully. Your problem is probably somewhere else, if there's even a problem.

While starting, Django (the Python framework that powers NetBox) creates several child processes. After a successful start, some of these child processes do exit. As long as it states that the exit code is 0, all is well: The exit code 0 in Unix/Linux-land (usually) indicates a success.

Getting a "Bad Request (400)"

When connecting to the Netbox instance, I get a "Bad Request (400)" error.

This usually happens when the ALLOWED_HOSTS variable is not set correctly.

How to upgrade

How do I update to a newer version of netbox?

⚠️ Make sure to take a database backup first.

💡 Read the release notes. They include important update information.

Update your local installation:

# Update the configuration files
git pull origin release

# Fetch the newest containers
docker-compose rm -fs netbox netbox-worker
docker-compose pull
docker-compose up -d netbox netbox-worker

Webhooks don't work

First make sure that the webhooks feature is enabled in your Netbox configuration and that a redis host is defined. Check netbox.env if the following variables are defined:

WEBHOOKS_ENABLED=true
REDIS_HOST=redis

Then make sure that the redis container and at least one netbox-worker are running.

# check the container status
$ docker-compose ps

Name                           Command               State                Ports
--------------------------------------------------------------------------------------------------------
netbox-docker_netbox-worker_1   /opt/netbox/docker-entrypo ...   Up
netbox-docker_netbox_1          /opt/netbox/docker-entrypo ...   Up      80/tcp, 0.0.0.0:32776->8080/tcp
netbox-docker_postgres_1        docker-entrypoint.sh postgres    Up      5432/tcp
netbox-docker_redis_1           docker-entrypoint.sh redis ...   Up      6379/tcp

# connect to redis and send PING command:
$ docker-compose run --rm -T redis sh -c 'redis-cli -h redis -a $REDIS_PASSWORD ping'
Warning: Using a password with '-a' option on the command line interface may not be safe.
PONG

If redis and the netbox-worker are not available, make sure you have updated your docker-compose.yml file!

Everything's up and running? Then check the log of netbox-worker and/or redis:

docker-compose logs -f netbox-worker
docker-compose logs -f redis

Still no clue? You can connect to the redis container and have it report any command that is currently executed on the server:

docker-compose run --rm -T redis sh -c 'redis-cli -h redis -a $REDIS_PASSWORD monitor'

# Hit CTRL-C a few times to leave

If you don't see anything happening after you triggered a webhook, double-check the configuration of the netbox and the netbox-worker containers, and also check the configuration of your webhook in the admin interface of NetBox.

DBShell in Netbox container doesn't work

We don't install psql into the Netbox container. Because of this the command ./manage.py dbshell will not work. To access the database shell directly use the command mentioned under the section Database Operations.