Table of Contents
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
(Press Ctrl+C to return to the shell prompt.)
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.
Netbox Container doesn't start when IPv6 is disabled
You can disable the IPv6 listener in the container by replacing the Nginx Unit configuration. Make a copy of the the nginx-unit.json from our repository (from the tag you are using) and remove the IPv6 listener section:
"[::]:8080": {
"pass": "routes"
}
NOTE: Also remove the trailing comma
After the section is removed you need to mount the new configuration file into the container. This can be done in a volumes section in docker-compose.override.yml with the following line:
- /opt/netbox/configuration/nginx-unit.json:/etc/unit/nginx-unit.json:ro