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. First download the collector image from the Customer Portal → Downloads (pick Collector (Docker image) for your CPU) and load it:

docker load < collector-image-amd64.tar.gz   # restores gridnms/collector:latest

Note

Self-hosted instances already ship the collector image inside their install bundle — it’s loaded for you, so there’s nothing to download here.

Then run it with 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="wss://tunnel.gridnms.io/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

Self-hosted? Your URL is different

wss://tunnel.gridnms.io/api/tunnel/ws is the GridNMS Cloud address. A self-hosted instance uses its own — wss://<your-instance>/api/tunnel/ws. You don’t have to work it out: Configure → Collectors → Add collector shows the exact GRIDNMS_TUNNEL_URL value for your instance alongside the join token, plus a ready-to-paste install command.

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. Download the collector image tarball from the Customer Portal → Downloads, docker load (or ctr images import) it, and push it to a registry your cluster can pull from — it references gridnms/collector:latest, so tag and push it there. 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
          # GridNMS Cloud shown; self-hosted uses wss://<your-instance>/api/tunnel/ws —
          # the exact value is shown at Configure → Collectors → Add collector.
          value: "wss://tunnel.gridnms.io/api/tunnel/ws"
        - name: GRIDNMS_JOIN_TOKEN
          valueFrom:
            secretKeyRef: { name: gridnms-collector, key: joinToken }
        - name: GRIDNMS_STATE_DIR
          value: /var/lib/gridnms
      volumeMounts:
        - name: gridnms-collector-state
          mountPath: /var/lib/gridnms
  volumes:
    - name: gridnms-collector-state
      persistentVolumeClaim:
        claimName: gridnms-collector-state

Caution

Mount a volume at GRIDNMS_STATE_DIR — a PersistentVolumeClaim as shown, not emptyDir. Without persistent storage, a pod reschedule (node drain, rollout, crash restart) re-registers as a brand-new collector and drops its queued-event buffer, the same way an un-mounted docker run does on the Docker tab.

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 from the Customer Portal → Downloads — macOS .dmg or Windows .msi (sign-in required). On macOS, pick the build that matches your Mac: Apple Silicon (M-series) or Intel. Not sure which you have? Check ** → About This Mac** — “Chip: Apple M…” means Apple Silicon; “Processor: … Intel …” means Intel.
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 are delivered over the collector’s existing connection, but they are not automatic by default — when a new version is available, open the collector on Configure → Collectors and click Upgrade now, or set its per-collector auto-upgrade policy. See Monitoring & Managing Collectors.
• To remove a collector, delete it on Configure → Collectors, then stop the container or quit the desktop app on the host.

Re-enroll or reset the desktop app

The desktop app keeps the collector’s identity on disk, so a saved collector reconnects automatically and ignores an old join token. To change that:

• Re-enroll with a new join token (for example after the collector was deleted or revoked in the console): open the app window, paste the new token into the Join token field, and press Start. The app replaces the saved identity and joins with the new token — no manual cleanup needed.
• Full reset to first-run: open Reset / purge local configuration at the bottom of the app window and confirm. This stops the collector and removes its saved identity, queued (not-yet-sent) messages, and configuration. The app returns to its first-run screen, ready for a fresh join token from Configure → Collectors. Also delete the old collector entry there — the machine re-registers as a brand-new collector.

If the app itself is broken and can’t be opened, delete the data folder by hand instead — see the manual steps under Uninstall the desktop app below.

Uninstall the desktop app

Quitting the app and dragging it to the Trash (macOS) or running the uninstaller (Windows) removes the application, but leaves behind a local data folder — the collector’s saved state, queued messages, and identity. Use the in-app Reset / purge local configuration button (above) before uninstalling, or remove that folder by hand as described below.

Caution

Deleting the data folder is permanent. It erases the collector’s local queue of not-yet-sent logs and its saved identity. After this, the machine re-registers as a brand-new collector the next time you install and start the app — so also delete the old collector entry on Configure → Collectors.

macOS

1. Quit GridNMS Collector (and remove it from System Settings → General → Login Items if it’s there).

2. Drag GridNMS Collector from Applications to the Trash.

3. Delete the leftover data and cache folders. Open Terminal and run:

   rm -rf ~/Library/Application\ Support/io.gridnms.collector \
          ~/Library/Caches/io.gridnms.collector \
          ~/Library/WebKit/io.gridnms.collector \
          ~/Library/Saved\ Application\ State/io.gridnms.collector.savedState \
          ~/Library/Preferences/io.gridnms.collector.plist \
          ~/Library/Logs/io.gridnms.collector

The main folder is ~/Library/Application Support/io.gridnms.collector — that’s where the collector keeps its state and message queue. The others are cache and window-state files macOS creates automatically.

Windows

1. Quit GridNMS Collector (right-click the tray icon → Quit). If it’s set to start with Windows, remove it from Task Manager → Startup apps.

2. Uninstall it: Settings → Apps → Installed apps → GridNMS Collector → Uninstall (or Add or Remove Programs).

3. Delete the leftover data folders. Open File Explorer, paste each path into the address bar, and delete the io.gridnms.collector folder you find:

   %APPDATA%\io.gridnms.collector
   %LOCALAPPDATA%\io.gridnms.collector

   Or, in PowerShell:

   Remove-Item -Recurse -Force "$env:APPDATA\io.gridnms.collector", `
                               "$env:LOCALAPPDATA\io.gridnms.collector"

%APPDATA%\io.gridnms.collector holds the collector’s state and message queue; %LOCALAPPDATA%\io.gridnms.collector holds the cache and the embedded browser data (EBWebView). The uninstaller removes the program files but leaves both of these behind.

Trouble getting a collector online? See Troubleshooting.