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 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 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.

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. To fully purge a machine, remove that folder too.

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.