The Diode server is a required component of the Diode ingestion service.

Diode is a data ingestion service for NetBox that greatly simplifies and enhances the process of adding and updating data in NetBox, ensuring your network source of truth is always accurate and up to date. Our guiding principle in designing Diode has been to make it as easy as possible to get data into NetBox, removing as much burden as possible from the user while shifting that effort to technology.

The Diode server is composed of three core services:

• Issues and introspects OAuth2 tokens

• Accepts and pushes ingested data into Redis streams for further processing

• Processes and reconciles ingested data against existing NetBox objects, detecting and storing any changes

The Diode server has been tested with NetBox version 4.2.3.
It also requires the Diode NetBox Plugin 1.1.0.

• Docker version 27.0.3 or newer
• bash 4.x or newer
• jq

We provide a quickstart.sh script to automate the setup process.

The following files will be downloaded:

• docker-compose.yaml — Defines Diode server containers
• .env — Environment settings for customization
• nginx.conf — Nginx configuration for routing Diode endpoints
• client-credentials.json — Defines OAuth2 clients for secure communication between the Orb Agent, Diode SDK, Diode server, and Diode NetBox plugin

We recommend placing these files in a clean working directory, for example:

mkdir /opt/diode
cd /opt/diode

Download and prepare the quickstart script:

curl -sSfLo quickstart.sh https://raw.githubusercontent.com/netboxlabs/diode/release/diode-server/docker/scripts/quickstart.sh
chmod +x quickstart.sh

Run the script to download and configure required files with your NetBox server address:

./quickstart.sh http://my.netbox:8080

Once setup is complete, start the Diode server:

docker compose up -d

Edit the .env file to adjust Diode server settings as needed:

Note that pprof profiling endpoints can be enabled for the reconciler, ingester, and auth services via the environnment variable PPROF_ADDR (using host:port addresses)

When NETBOX_DIODE_PLUGIN_API_BASE_URL points at a NetBox served over HTTPS with a certificate issued by a private/internal CA, the reconciler fails with:

tls: failed to verify certificate: x509: certificate signed by unknown authority

The reconciler uses Go's system certificate pool, which honors the standard SSL_CERT_FILE environment variable — including in the distroless container image. Mount your CA bundle and point SSL_CERT_FILE at it with a docker-compose.override.yaml:

services:
  diode-reconciler:
    volumes:
      - /path/to/your/ca.pem:/certs/ca.pem:ro
    environment:
      - SSL_CERT_FILE=/certs/ca.pem

Keep NETBOX_DIODE_PLUGIN_SKIP_TLS_VERIFY=false — certificate verification stays enabled, validated against your CA. To trust a directory of CA certificates instead of a single bundle, mount the directory and use SSL_CERT_DIR.

Setting NETBOX_DIODE_PLUGIN_SKIP_TLS_VERIFY=true disables certificate verification entirely and should be a last resort.

To stop the Diode:

docker compose down

To stop the Diode and also delete PostgeSQL and Redis volumes:

docker compose down --volumes

Additional agent credentials may be provisioned by calling the authmanager command in the auth service container.

Create a new client with the right to ingest

docker compose run --rm --no-deps diode-auth authmanager create-client --client-id my-agent-001 --allow-ingest

** NOTE: The client secret is only displayed once and cannot be retrieved later.
  Store credentials in a secure location. If you lose them, you will need to
  destroy and regenerate the client.
{
  "client_id": "my-agent-001",
  "scope": "diode:ingest",
  "client_secret": "a_new_generated_secret"
}

Create a client with a supplied secret (in this case the secret is not returned)

docker compose run --rm --no-deps diode-auth authmanager create-client --client-id my-agent-002 --allow-ingest --client-secret="a_secret_key_from_some_other_source"

client created successfully.
{
  "client_id": "my-agent-002",
  "scope": "diode:ingest"
}

Retrieve info of an existing client

docker compose run --rm --no-deps diode-auth authmanager get-client --client-id my-agent-001

{
  "client_id": "my-agent-001",
  "scope": "diode:ingest"
}

List existing clients

docker compose run --rm --no-deps diode-auth authmanager list-clients

[
  {
    "client_id": "diode-ingest",
    "scope": "diode:ingest"
  },
  {
    "client_id": "diode-to-netbox",
    "scope": "netbox:read netbox:write"
  },
  {
    "client_id": "my-agent-001",
    "scope": "diode:ingest"
  },
  {
    "client_id": "my-agent-002",
    "scope": "diode:ingest"
  },
  {
    "client_id": "netbox-to-diode",
    "scope": "diode:read diode:write"
  }
]

Delete an existing client

docker compose run --rm --no-deps diode-auth authmanager delete-client --client-id my-agent-002

client my-agent-002 deleted successfully

List auth utility subcommands

docker compose run --rm --no-deps diode-auth authmanager

usage: authmanager <subcommand>
subcommands: list-clients get-client delete-client create-client

Additional help on a subcommand

docker compose run --rm --no-deps diode-auth authmanager create-client --help

Usage of create-client:
  -allow-ingest
    	include scopes that allow the client to ingest data
  -client-id string
    	client id
  -client-secret string
    	client secret [generated if not provided]
  -scope string
    	space separated list of scopes to allow

Distributed under the NetBox Limited Use License 1.0.
See LICENSE.md for more information.