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

Enter the Netbox shell, e.g. to get access to ./manage.py:

docker-compose exec netbox /bin/bash

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:

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 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 ./manage.py nbshell

Frequently Asked Questions (FAQ) and Common Problems

Nginx doesn't start

As a first step, stop your docker-compose setup. Then locate the netbox-nginx-config volume and remove it:

# Stop your local netbox-docker installation
$ docker-compose down

# Find the volume
$ docker volume ls | grep netbox-nginx-config
local               netbox-docker_netbox-nginx-config

# Remove the volume
$ docker volume rm netbox-docker_netbox-nginx-config
netbox-docker_netbox-nginx-config

Now start everything up again.

If this didn't help, try to see if there's anything in the logs indicating why nginx doesn't start:

docker-compose logs -f nginx

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
netbox-docker_nginx_1           nginx -c /etc/netbox-nginx ...   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.