NetBox on AWS User Guide

Overview

This image runs NetBox 4.6.5, the leading open source Network Source of Truth, on Ubuntu 24.04 LTS. NetBox is a combined IP address management (IPAM) and data centre infrastructure management (DCIM) platform: it holds the authoritative record of your IP space, VLANs and VRFs, devices, racks, sites, cabling, circuits and virtualisation, and exposes all of it through a full REST and GraphQL API, change logging, custom fields and a webhook automation engine.

cloudimg delivers NetBox fully installed and reverse proxied behind nginx, with the gunicorn application server, the background task worker, PostgreSQL 16 and Redis 7 already configured and managed by systemd, so a complete Network Source of Truth is operational within minutes of launch.

What is included:

• NetBox 4.6.5 installed from the official release into /opt/netbox, running in a dedicated Python virtual environment
• PostgreSQL 16 as the primary database and Redis 7 as the task queue and cache backend
• gunicorn serving the Django application on 127.0.0.1:8001, fronted by nginx on port 80
• A background request queue worker (netbox-rq.service) for webhooks and long running jobs
• Five systemd units enabled and active: postgresql, redis-server, netbox, netbox-rq and nginx
• Secure by default: no administrator account and no shared secret ship in the image. On first boot a unique Django secret key, a unique database password, a unique administrator account and a REST API token are generated and written to a root only file
• The database tier (/var/lib/postgresql) and the application tier (/opt) each sit on their own dedicated, independently resizable EBS volume
• A daily housekeeping task that keeps the database tidy automatically
• A fully patched Ubuntu 24.04 LTS base with unattended security upgrades enabled
• 24/7 cloudimg support

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access
• A VPC and subnet, with a security group allowing inbound 22/tcp from your management network and inbound 80/tcp (and 443/tcp once you add TLS) from the network you will reach the web interface from
• The AWS CLI version 2 installed locally if you plan to deploy from the command line

m5.large (2 vCPU / 8 GiB RAM) is the recommended instance type: NetBox runs gunicorn, a background worker, PostgreSQL and Redis together, so it benefits from at least two vCPUs and 8 GiB of memory. NetBox serves plain HTTP on port 80; for production or shared access, terminate TLS in front of it with your own domain (see the final step).

Connecting to your instance

SSH in as the default login user for the operating system variant you launched. The build itself logs in as this user on every phase, so it is the correct account for your variant.

Step 1: Launch the instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for NetBox. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound port 80 from the network you will reach the web interface from. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes approximately one to two minutes after the instance state becomes Running and the status checks pass.

Step 2: Launch the instance from the AWS CLI

The following block launches an instance from the cloudimg NetBox Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=netbox}]'

Step 3: Retrieve the per instance admin credentials

Nothing secret is baked into the image. On the very first boot, a one shot service (netbox-firstboot.service) generates a fresh Django secret key, a fresh database password, a unique administrator account and a REST API token, all unique to your instance. It writes them to /root/netbox-credentials.txt, readable only by root. SSH in as ubuntu and read them:

$ sudo cat /root/netbox-credentials.txt
# NetBox - generated on first boot by netbox-firstboot.service.
# These credentials are unique to THIS instance. Store them somewhere safe.

netbox.url=http://203.0.113.42/
netbox.admin.user=admin
netbox.admin.pass=<NETBOX_ADMIN_PASSWORD>
netbox.api.token=<NETBOX_API_TOKEN>

# Canonical keys consumed by the cloudimg smoke verifier + guide substitution:
NETBOX_ADMIN_PASSWORD=<NETBOX_ADMIN_PASSWORD>
NETBOX_API_TOKEN=<NETBOX_API_TOKEN>

The netbox-firstboot.service one shot is ordered before the application services, so the web UI only ever starts once every per instance secret has been generated. The values above are an example; your instance will have its own unique credentials.

Step 4: Confirm the services are running

Check that PostgreSQL, Redis, the NetBox application, the request queue worker and nginx are all active:

sudo systemctl is-active postgresql redis-server netbox netbox-rq nginx

All five report active. gunicorn binds to loopback only (127.0.0.1:8001) and nginx publishes the interface on port 80:

sudo ss -tlnp | grep -E ':80 |:8001 '

Step 5: Confirm the web endpoints

The sign in page is public and returns 200. NetBox requires authentication for everything else, so the REST API returns 403 without a token. This is the secure default.

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost/login/

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost/api/dcim/devices/

Step 6: Sign in to the web UI

Browse to http://<instance-public-ip>/ and sign in as admin with the password from /root/netbox-credentials.txt. NetBox opens on the login page.

After signing in you land on your personal dashboard, with widgets summarising your organisation, IP space, devices, circuits and more. The screenshots in this guide show NetBox populated with a small set of example objects; a freshly deployed instance starts empty and ready for you to model your own network.

Step 7: Model your network - IPAM and DCIM

Under IPAM > Prefixes you record your IP space: aggregates, prefixes, IP ranges and individual addresses, each with a status, VRF, tenant, role and description. NetBox validates hierarchy and utilisation automatically.

Under Devices you record your physical and virtual infrastructure: sites, racks, manufacturers, device types and the devices themselves, with roles, interfaces, cabling and console connections.

Step 8: Use the REST API

NetBox exposes a complete REST API under /api/. Use the token from /root/netbox-credentials.txt in the Authorization: Token <token> header to call any endpoint. Read the token into a shell variable and query your devices and prefixes:

TOKEN=$(sudo grep '^NETBOX_API_TOKEN=' /root/netbox-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'devices HTTP %{http_code}\n' -H "Authorization: Token $TOKEN" http://localhost/api/dcim/devices/

A GraphQL endpoint is also available at /graphql/, and you can create additional scoped tokens from Admin > API Tokens in the web UI.

Step 9: Enable HTTPS with your own domain

NetBox ships on plain HTTP on port 80 so it works immediately. For production, point a DNS record at the instance's public IP, add the hostname to ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS in /opt/netbox/netbox/netbox/configuration.py, and terminate TLS with a certificate. A common approach is to obtain a certificate with certbot and reverse proxy through nginx, or to place an Application Load Balancer with an ACM certificate in front of the instance. Open port 443 in your security group, then restart the application after editing the configuration:

$ sudo systemctl restart netbox netbox-rq

Administration and support

The NetBox manage.py command is wrapped for convenience: run sudo netbox-manage <command> (for example sudo netbox-manage createsuperuser to add another administrator, or sudo netbox-manage housekeeping to run maintenance on demand). The application configuration lives in /opt/netbox/netbox/netbox/configuration.py, and NetBox and its request queue worker are managed with sudo systemctl restart netbox netbox-rq.

This image is a repackaged open source software product with additional charges for cloudimg support services. Our engineers provide 24/7 support for deployment, upgrades, TLS termination, LDAP and SSO integration, API automation and scaling. NetBox is a trademark of its respective owner; use of the name here is purely to identify the software this image packages.