Netdisco Network Management on AWS User Guide

Overview

Netdisco is an open source, web based network management and discovery tool for small to very large networks. It polls your switches, routers and access points over SNMP (and CLI or device APIs), collects IP and MAC address data into a PostgreSQL database, and presents a web interface to inventory every device, browse and search ports and nodes, locate where a given MAC or IP address is connected, and view how devices link together.

The cloudimg image runs Netdisco 2.101000 from the official netdisco/netdisco container images (a web frontend and a backend poller daemon) behind an nginx reverse proxy on port 80. It bundles its own local PostgreSQL 16 database preloaded with the MAC vendor (OUI) reference data, and, because Netdisco ships by default with an anonymous full access guest, disables that guest and generates a unique admin login on the first boot of every instance. A fresh database password and a fresh SNMP read only community are also generated per instance. The PostgreSQL data lives on a dedicated EBS volume you can resize and snapshot independently. Backed by 24/7 cloudimg support.

What is included:

• Netdisco 2.101000 (BSD-3-Clause) run from the official netdisco/netdisco container images, managed by netdisco-web.service and netdisco-backend.service
• Netdisco published on port 80 via nginx, so the web interface is reachable without exposing the container port
• A bundled local PostgreSQL 16 database holding Netdisco's schema plus MAC vendor (OUI) reference data, ready to identify devices out of the box
• A required login: the default anonymous guest is disabled (no_auth: false), and a per-instance admin user is seeded so nothing is open to the network
• A unique admin password, a unique PostgreSQL password and a unique SNMP read only community generated on first boot, written to a root only credentials file
• The PostgreSQL data tier on its own dedicated EBS volume, independently resizable and snapshottable
• postgresql@16-main.service, netdisco-web.service, netdisco-backend.service and nginx.service as systemd units, enabled and active

Connecting to your instance

Connect over SSH on port 22 as the login user for your operating system variant:

ssh ubuntu@<instance-ip>

The bundled PostgreSQL listens only on loopback (127.0.0.1:5432) and is never exposed. Netdisco reaches your network devices over 161/udp (SNMP) outbound, so make sure your devices permit SNMP from this instance.

Step 1 - Launch from AWS Marketplace

In the AWS Marketplace console, open the Netdisco listing by cloudimg and choose Continue to Subscribe, then Continue to Configuration and Continue to Launch. Pick your region, an m5.large instance type (a good starting point), a key pair, a VPC subnet, and a security group that allows TCP 22 (SSH) from your management network and TCP 80 (the web interface). Then Launch.

Step 2 - Launch from the AWS CLI

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

Replace <netdisco-ami-id> with the AMI ID shown on the Marketplace launch page for your region.

Step 3 - Confirm the services are running

After connecting over SSH, confirm the stack is up:

systemctl is-active postgresql@16-main.service netdisco-web.service netdisco-backend.service nginx.service

All four report active. On first boot the image generates a unique admin password, a unique database password and a unique SNMP read only community, then starts the web frontend and the backend poller.

Step 4 - Retrieve your admin credentials

The first boot writes a root only credentials file. Read it with sudo:

sudo cat /root/netdisco-credentials.txt

You will see the web URL, the admin username (admin) and its unique password, and the per-instance SNMP read only community. Keep this file safe - it is the only copy of the generated password.

Step 5 - Check the health endpoint

nginx proxies Netdisco's own health endpoint, which needs no authentication and is ideal for a load balancer target group health check. It returns 200 when the database is reachable:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/health

Step 6 - Confirm your login gates the tool

Because the anonymous guest is disabled, an unauthenticated request to a page such as the inventory is answered with the login form rather than the data. Confirm the tool is not open:

curl -s -m 10 http://127.0.0.1/inventory -o /tmp/nd-inventory.html
if grep -q 'name="password"' /tmp/nd-inventory.html; then echo "login required - not open"; else echo "unexpected: login form not served"; fi
rm -f /tmp/nd-inventory.html

The login required - not open result confirms the login form is served to unauthenticated visitors, so nothing is exposed without signing in.

Step 7 - Open Netdisco in your browser

Browse to http://<instance-ip>/ and sign in with the admin username and the password from your credentials file.

After signing in you land on the dashboard, with a Find Anything search box and a Discover box to add your first device.

Step 8 - Discover your first device

Netdisco discovers a device over SNMP and then follows its neighbours. In the Discover box on the dashboard, enter the hostname or IP address of a switch or router that permits SNMP from this instance, and select Discover. Netdisco uses the per-instance read only community from your credentials file by default; you can also set a per-device community under Admin. Discovery and later polling run as background jobs on the backend daemon, which you can watch under Admin -> Job Queue.

Once devices are discovered they appear under Inventory and in device search, with vendor, model, software version, location and management IP for each:

Select any device to open its detail page - ports, modules, neighbours, addresses and VLANs, plus per-device admin tasks such as re-discover, arpnip and macsuck:

Step 9 - Locate a MAC or IP address

Under the Node tab of search you can find which switch port a given MAC or IP address is connected to, when it was first and last seen, and the VLAN it is on - the core troubleshooting workflow for "where is this device plugged in?":

Step 10 - Manage users

Under Admin -> User Management you can see the per-instance admin account and add further users, each with their own password, allowed source addresses, and optional administrator or port control rights.

The bundled database and MAC vendor data

The image ships PostgreSQL 16 with Netdisco's schema already deployed and the MAC vendor (OUI) reference data loaded, so device and node vendors are identified from the moment your first device is discovered. The data lives on a dedicated EBS volume. You can inspect the bundled database directly on the instance:

sudo -u postgres psql -d netdisco -c "SELECT count(*) AS mac_vendor_ouis FROM oui;"

sudo -u postgres psql -d netdisco -c "SELECT username, admin, port_control FROM users ORDER BY username;"

Security notes

• The default Netdisco anonymous guest with full admin rights is disabled in this image (no_auth: false). A real login is always required.
• The admin password, the PostgreSQL application role password and the SNMP read only community are generated uniquely on the first boot of every instance and written to /root/netdisco-credentials.txt (mode 0600). No usable login ships inside the image.
• The bundled PostgreSQL listens only on 127.0.0.1:5432 and is never exposed to the network.
• Change or add web users under Admin -> User Management. To rotate the admin password later, edit the user there.
• Only ports 22, 80 and 443 need to be open to the instance. Netdisco reaches your devices outbound over SNMP.

Enabling HTTPS

For public exposure, put the instance behind a certificate. Point a DNS name at the instance, open 443/tcp in the security group, install a certificate with your preferred tool (for example Certbot with the nginx plugin), and let nginx terminate TLS in front of the reverse proxy:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

Certbot edits the existing nginx site to serve HTTPS and set up automatic renewal.

Maintenance

• Service status: systemctl status netdisco-web.service netdisco-backend.service
• Logs: journalctl -u netdisco-web.service and journalctl -u netdisco-backend.service, plus sudo ls /var/lib/netdisco/logs
• Configuration: static policy lives in /var/lib/netdisco/config/deployment.yml; per-instance secrets are in /var/lib/netdisco/netdisco.env
• Database backups: the data volume can be snapshotted through Amazon EBS, or dump the database on the instance:

sudo -u postgres pg_dump netdisco > netdisco-backup.sql

• OS updates: unattended security upgrades are enabled; the base is fully patched at build time

Support

Every cloudimg image is backed by 24/7 support. If you have a question about this image or need help with a deployment, contact the cloudimg team.