Netdisco is a web-based network management tool suitable for small to very large networks. IP and MAC address data is collected into a PostgreSQL database using SNMP, CLI, or device APIs. Some of the things you can do with Netdisco:
- Locate a machine on the network by MAC or IP and show the switch port it lives at
- Turn off a switch port, or change the VLAN or PoE status of a port
- Inventory your network hardware by model, vendor, software and operating system
- Pretty pictures of your network
See the demo at: https://netdisco2-demo.herokuapp.com/
Netdisco includes a lightweight web server for the interface, a backend daemon to gather data from your network, and a command line interface for troubleshooting. There is a simple configuration file in YAML format.
Container images are provided for linux/arm64 and linux/amd64.
The following commands use docker compose but you can use docker-compose instead if that's what you installed.
On Linux hosts, create these directories and allow the service uid (901) to write into it:
(this step is only necessary on Linux hosts and can be omitted in the macOS and Windows versions of Docker)
mkdir -p netdisco/{logs,config,nd-site-local}
sudo chown -R 901:901 netdisco
Download compose.yaml and start everything:
curl -Ls -o compose.yaml https://tinyurl.com/nd2-dockercompose
docker compose up --detach
This runs the database, backend daemon, and web frontend listening on port 5000. If you have a device using the SNMP community public, enter it in the Netdisco homepage and click "Discover".
The default configuration is available in netdisco/config/deployment.yml. The daemons automatically restart when you save changes to this file. Logs are available in netdisco/logs/.
The web frontend is initally configured to allow unauthenticated access with full admin rights. We suggest you visit the Admin -> User Management menu item, and set no_auth: false in deployment.yml, to remove this guest account and set up authenticated user access.
Pull new images and recreate the containers:
docker compose pull
docker compose down
curl -Ls --clobber -o compose.yaml https://tinyurl.com/nd2-dockercompose
docker compose --profile with-pg-upgrade up --force-recreate --detach
Note carefully the commands used. The PostgreSQL database, and Netdisco's schema, will both be upgraded.
We have a mix-in Docker Compose file for this. It stops our own database container from running and will look to either environment variables or a local deployment.yml configuration file for connection details.
Download the mix-in and start the services:
curl -Ls -O https://raw.githubusercontent.com/netdisco/netdisco-docker/refs/heads/master/compose.mixin.extpg.yaml
docker compose -f compose.yaml -f compose.mixin.extpg.yaml up --detach
If the database is on the same host as your Docker service, then use host.docker.internal for its hostname (either in the configuration file or with the NETDISCO_DB_HOST environment variable).
The with-pg-upgrade profile isn't designed for an external database; you'll need to take care of PostgreSQL upgrades yourself. Netdisco will still manage schema updates every time it starts, though.
We have an example mix-in Docker Compose file for this. The example points to deployment.yml in a user's home directory.
Download the mix-in and start the services:
curl -Ls -O https://raw.githubusercontent.com/netdisco/netdisco-docker/refs/heads/master/compose.mixin.homeenv.yaml
docker compose -f compose.yaml -f compose.mixin.homeenv.yaml up --detach
Edit the mix-in to point to another location.
The following command will download and update the MAC vendor database:
curl -Ls https://raw.githubusercontent.com/netdisco/upstream-sources/refs/heads/master/bootstrap/netdisco-lookup-tables.sql | docker compose exec -T netdisco-backend /home/netdisco/bin/netdisco-env psql
Each containerised Netdisco release also includes the latest MAC vendors, and automatically updates them when starting.
The netdisco-do utility can be run like this (or without <action> to get help):
docker compose exec netdisco-backend netdisco-do <action> ...
If you're unable to download the compose.yaml file using our TinyURL above, it can be found here: https://raw.githubusercontent.com/netdisco/netdisco-docker/master/docker-compose.yml
Local web or backend plugins can be installed into netdisco/nd-site-local/ as per our documentation. The PostgreSQL data files are stored in netdisco/postgresql/ or netdisco/pgdata/ and we do not advise touching them (unless you wish to reinitialize the system).
The NETDISCO_RO_COMMUNITY environment variable allows you to override the default of public (and avoiding the need to edit the configuration file).
If you wish to build the images locally, use this compose file (it's not a mix-in):
docker compose -f compose.build.yaml build --no-cache
We have several other pages with tips for understanding and troubleshooting Netdisco, tips and tricks for specific platforms, and all the configuration options.
You can also speak to someone in the #netdisco@libera IRC channel, or on the community email list.
Thanks to Ira W. Snyder and LBegnaud for inspiration. Thanks also to the PostgreSQL project for great examples of docker magic. We build with the support of the excellent GitHub Actions service.