Installing a Collector

This page covers installing a collector on its own — for a new site, an extra network segment, or to replace a collector. (Self-hosted instances already start with one collector built in; you only need this when adding more.)

Before you start

1. In GridNMS, go to Configure → Collectors and select Add collector.
2. Copy the instance address and the one-time join token it shows — both appear in the install snippets below.

Make sure the collector machine has outbound HTTPS (443) to your GridNMS instance.

Choose how to run it

Docker on Linux

The recommended option for most sites. Use host networking so the collector sees the real source IP of syslog and SNMP traps:

docker run -d --name gridnms-collector --restart unless-stopped \
  --network host \
  -e GRIDNMS_TUNNEL_URL="https://<your-instance>/api/tunnel/ws" \
  -e GRIDNMS_JOIN_TOKEN="<your-join-token>" \
  -e GRIDNMS_STATE_DIR=/var/lib/gridnms \
  -v gridnms-collector-state:/var/lib/gridnms \
  gridnms/collector:latest

The collector appears as online on the Collectors page within a few seconds.

Caution

Plain Docker bridge networking (-p 514:514/udp) hides the real sender behind the Docker gateway address. On Linux, prefer --network host. See Getting the Real Source IP.

Kubernetes

Run the collector as a Deployment or DaemonSet. To preserve real source IPs for syslog and traps, give the collector pod host networking:

spec:
  hostNetwork: true        # so syslog/trap source IPs are preserved
  containers:
    - name: gridnms-collector
      image: gridnms/collector:latest
      env:
        - name: GRIDNMS_TUNNEL_URL
          value: "https://<your-instance>/api/tunnel/ws"
        - name: GRIDNMS_JOIN_TOKEN
          valueFrom:
            secretKeyRef: { name: gridnms-collector, key: joinToken }
        - name: GRIDNMS_STATE_DIR
          value: /var/lib/gridnms

Alternatively, expose the syslog/trap service with externalTrafficPolicy: Local so the client IP is kept.

Desktop app (Mac/Windows)

For a small on-prem site, the GridNMS Collector desktop app runs the collector natively on the machine’s own network — point-and-click, and it preserves real source IPs.

1. Download the installer: macOS .dmg · Windows .msi
2. Install and launch it.
3. Paste your instance address and join token when prompted, then start it.

After it’s online

1. On Configure → Collectors, confirm the collector shows online.
2. Assign the networks it should watch — see Networks & Sites.
3. Point your devices’ syslog and SNMP traps at the collector’s address if you want to collect them — first read Getting the Real Source IP.

Updating and removing

• Updates happen automatically over the collector’s existing connection — nothing to do.
• To remove a collector, delete it on Configure → Collectors, then stop the container or quit the desktop app on the host.

Trouble getting a collector online? See Troubleshooting.