Get Started with Diode

This guide will help you set up and start using Diode to ingest data into NetBox.

Prerequisites

Before you begin, ensure you have:

NetBox version 4.2.3 or later
Docker version 27.0.3 or newer
bash 4.x or newer
jq
Network connectivity between your NetBox server and the Diode server
Sufficient permissions to run Docker commands

Installation Steps

Deploy Diode server

Host: These steps should be performed on the host where you want to run the Diode server.

Note: For the complete installation instructions, please refer to the official Diode Server documentation.

We provide a quickstart.sh script to automate the setup process. The script will download and configure all necessary files:

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

Create a working directory:
```
mkdir -p /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 with your NetBox server address:
```
./quickstart.sh https://\<netbox-server\>
```
Note: Replace <netbox-server> with your actual NetBox server address. Do not include a trailing slash. Example: ./quickstart.sh https://netbox.example.com

This should have created an .env file for your environment.
Start the Diode server:
```
docker compose up -d
```
Verify the Diode server is running:
```
docker compose ps
```
All services should show as "running" or "healthy".
Extract the netbox-to-diode client secret. This will be needed for the Diode NetBox plugin installation:
```
echo $(jq -r '.[] | select(.client_id == "netbox-to-diode") | .client_secret' /opt/diode/oauth2/client/client-credentials.json)
```
Note: This will return a credential that will be used by the Diode NetBox plugin to connect to the Diode server. Store it safely.

Install Diode NetBox Plugin

Host: These steps should be performed on the host where NetBox is installed.

Note: For the complete installation instructions, please refer to the official Diode NetBox Plugin documentation.

Source the NetBox Python Virtual Environment
```
cd /opt/netbox
source venv/bin/activate
```

Install the Plugin Package

pip install netboxlabs-diode-netbox-plugin

Configure NetBox Settings Add the following to your configuration.py:

PLUGINS = [
    "netbox_diode_plugin",
]

PLUGINS_CONFIG = \{
    "netbox_diode_plugin": \{
        # Diode gRPC target for communication with Diode server
        "diode_target_override": "grpc://\<diode-server:port\>/diode",
        # NetBox username associated with changes applied via plugin
        "diode_username": "diode",
        # netbox-to-diode client secret from earlier step
        "netbox_to_diode_client_secret": "\<netbox-to-diode-secret\>"
    \},
\}

Note: Replace <diode-server:port> with your Diode server address and port (default: 8080) Example: grpc://diode.example.com:8080/diode

Apply Database Migrations

cd /opt/netbox/netbox
./manage.py migrate netbox_diode_plugin

Restart NetBox Services
```
sudo systemctl restart netbox netbox-rq
```
Generate Diode Client Credentials

Note: These credentials will be used by the Orb agent to send discovery results to NetBox via Diode.
1. Go to your NetBox instance (https://<netbox-server>)
2. In the left-hand pane, navigate to Diode -> Client Credentials
3. Click on + Add a Credential
4. For Client Name, enter any name and click Create
5. IMPORTANT: Copy the Client ID and Client Secret and save them securely
6. Click Return to List
You have now created your Diode client credentials. These will be used as environment variables when running the Orb agent.

Ingest Data with Orb Agent

Host: These steps should be performed on the host where you want to run the Orb agent for network discovery.

Note: For the complete installation instructions, please refer to the official Orb Agent documentation.

Export Client Credentials

# Export the client credentials you generated in NetBox
export DIODE_CLIENT_ID="\<your-client-id\>"
export DIODE_CLIENT_SECRET="\<your-client-secret\>"

Create Agent Configuration File Create an agent.yaml file with the following content:

orb:
  config_manager:
    active: local
  backends:
    network_discovery:  # Enable network discovery backend
    common:
      diode:
        target: grpc://\<diode-server:port\>/diode
        client_id: $\{DIODE_CLIENT_ID\}
        client_secret: $\{DIODE_CLIENT_SECRET\}
        agent_name: my_agent
  policies:
    network_discovery:
      loopback_policy:
        config:
        scope:
          targets: 
            - 127.0.0.1

Note: Replace <diode-server:port> with your Diode server address and port (default: 8080) Example: grpc://diode.example.com:8080/diode

Run the Agent

Using host network mode (recommended):

docker run --net=host \
  -v $(pwd):/opt/orb/ \
  -e DIODE_CLIENT_ID \
  -e DIODE_CLIENT_SECRET \
  netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml

Alternative using root user:

docker run -u root \
  -v $(pwd):/opt/orb/ \
  -e DIODE_CLIENT_ID \
  -e DIODE_CLIENT_SECRET \
  netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml

Note: The container needs sufficient permissions to send ICMP and TCP packets. This can be achieved either by:

Setting the network mode to host (recommended)

Running the container as root user

Verify Agent Operation
- Check the agent logs for successful startup
- Verify data appears in NetBox

Troubleshooting

Common Issues

Connection Issues
- Verify network connectivity between Diode and NetBox:
```
# From Diode server
curl -v https://\<netbox-server\>
# From NetBox server
curl -v grpc://\<diode-server:port\>/diode
```
- Check firewall rules:
```
# Check if required ports are open
netstat -tulpn | grep -E '8080|443'
```
- Validate URLs and ports in configuration files:
  - Diode server .env
  - NetBox configuration.py
  - Orb agent agent.yaml
Docker Issues
- Check Docker service status:
```
systemctl status docker
```
- Verify Docker container logs:
```
docker compose logs
```
Permission Issues
- Ensure proper file permissions:
```
ls -la /opt/diode/
ls -la /opt/netbox/
```
- Check Docker socket permissions:
```
ls -l /var/run/docker.sock
```

Getting Help

If you encounter issues:

Search GitHub: Issues
Find us in Slack: NetDev Community #orb
Check the logs:
- Diode server logs: docker compose logs

Prerequisites​

Installation Steps​

Deploy Diode server​

Install Diode NetBox Plugin​

Ingest Data with Orb Agent​

Troubleshooting​

Common Issues​

Getting Help​