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. If you haven’t read What Is a Collector? yet, start there for the bigger picture.

Before you start

1. In GridNMS, go to Configure → Collectors and select Register collector.
2. Copy the one-time enrollment token it shows — it’s single-use, so if it expires or gets used elsewhere, come back here for a fresh one.
3. If you’re connecting to a self-hosted or air-gapped GridNMS server (not the standard cloud service), also note your server address — for example https://your-server.example.com. On the standard GridNMS cloud service you can skip this; the installer connects there by default.

Make sure the collector host has outbound HTTPS (443) to your GridNMS instance — that’s the only network access required to get a collector online. No certificate of any kind is required to install, enroll, or connect a collector on the standard GridNMS cloud service — see Certificates below for what they’re for and who needs them.

Prerequisites

Linux

• A Linux host running systemd — Ubuntu, Debian, RHEL, Rocky, Alma, SUSE, and their derivatives all qualify.
• x86-64 or ARM64.
• Administrator access (you’ll run the installer with sudo).

macOS

• macOS, Apple Silicon or Intel.
• Administrator access (you’ll run the installer with sudo).
• No Gatekeeper warning — the installer is signed and notarized. An Intel build run on an Apple Silicon Mac also works (via Rosetta), the installer just lets you know the native Apple Silicon build would be faster to grab next time.

Download the bundle

Sign in to the Customer Portal → Downloads and download the collector build for your host, under Collector:

Host	Download
Linux, x86-64	linux-amd64
Linux, ARM64	linux-arm64
macOS, Apple Silicon	darwin-arm64
macOS, Intel	darwin-amd64

Not sure which architecture you have? On Linux, run uname -m — x86_64 means amd64, aarch64 means arm64. The installer checks this for you and stops with a clear, specific message if you picked the wrong one, rather than failing with a confusing error partway through.

Everything the installer needs to run — the collector binary, its supervisor process, and the certificate that lets it trust the standard GridNMS cloud service — ships inside the bundle you downloaded. Nothing is fetched from the internet during install, which is what makes this work identically on a locked-down or fully offline network. (Self-hosted and air-gapped deployments use their own certificate instead — see Certificates below.)

Install

Unpack the bundle and run the installer with sudo, passing your enrollment token from Before you start.

Linux

tar xzf gridnms-collector-distro-<version>-linux-<arch>.tar.gz
cd gridnms-collector-distro-<version>-linux-<arch>

sudo ./linux/install.sh --join-token=<your-enrollment-token>

Connecting to a self-hosted or air-gapped GridNMS server instead? Add --control-plane=<your-server-address> — leave it out and the installer connects to the standard GridNMS cloud service by default.

sudo ./linux/install.sh \
  --control-plane=https://your-server.example.com \
  --join-token=<your-enrollment-token>

macOS

tar xzf gridnms-collector-distro-<version>-darwin-<arch>.tar.gz
cd gridnms-collector-distro-<version>-darwin-<arch>

sudo ./macos/install.sh --join-token=<your-enrollment-token>

Connecting to a self-hosted or air-gapped GridNMS server instead? Add --control-plane=<your-server-address> — leave it out and the installer connects to the standard GridNMS cloud service by default.

sudo ./macos/install.sh \
  --control-plane=https://your-server.example.com \
  --join-token=<your-enrollment-token>

The installer prints a summary when it finishes, including whether the service started successfully and whether it enrolled with your GridNMS server. If something didn’t come up, the summary tells you exactly what command to run next to see why.

Re-running the installer is always safe

Run it again at any time on an already-installed collector — to pick up a newer version, to add a listener certificate, or to add the trust certificate described below. It never loses your existing enrollment, and it never regenerates an already-issued listener certificate out from under connected Log Forwarders.

All install options

Option	Required?	What it does
--join-token=<token>	Yes	The one-time enrollment token from Configure → Collectors. Each token works once — a used or expired one needs a fresh one from that page.
--control-plane=<url>	No	Your GridNMS server address. Leave it out to connect to the standard GridNMS cloud service. Self-hosted and air-gapped deployments pass their own server’s URL here, for example https://your-server.example.com.
--label=<name>	No	A friendly name for this collector, shown alongside it in GridNMS.
--tls-cert=<path> and --tls-key=<path>	No — but required together	A certificate and matching private key for the collector’s own listening ports (used if you’ll receive data from Log Forwarders). Leave both out and GridNMS handles this automatically — see Certificates.
--local-address=<ip> and --local-hostname=<name>	On a fresh install — unless you answer the prompt	This collector’s local (LAN) address and hostname, used by Log Forwarders and the collector’s own listeners. On a fresh install the installer asks you to pick them; pass both to skip the prompt.
--non-interactive	No	Never prompt. A fresh install without --local-address and --local-hostname fails immediately instead of waiting for input — use this for scripted installs.
--tls-ca=<path>	No — standard cloud service never needs this	The certificate authority the collector uses to trust your GridNMS server for onward delivery. Already built into the download for the standard GridNMS cloud service. Self-hosted and air-gapped deployments pass their own here — see Certificates.
-h, --help	—	Print the short help summary.

Run sudo ./linux/install.sh --help (or the macOS equivalent) at any time to see this list on the host itself.

Certificates

Two different certificates can come up when you’re installing a collector. On the standard GridNMS cloud service, you don’t need to provide either one — both are handled automatically. They only become something you manage yourself on a self-hosted or air-gapped GridNMS server, and only in the specific situations described below.

Listener certificate

If Log Forwarders will send data to this collector, its listening ports need their own server certificate. You never need to arrange this yourself:

1. The installer stages a temporary, self-signed one immediately, so the service can start right away.
2. Once the collector finishes enrolling, GridNMS issues it a real certificate and delivers it automatically — no reinstall, no manual step, and no interruption to any Log Forwarder already connected.

--tls-cert=<path> and --tls-key=<path> exist only to override this with a certificate and key pair from your own PKI — most installs never need them.

Trust certificate for onward delivery

Before a collector can hand off the logs and metrics it receives to your GridNMS server, it has to trust that server’s certificate.

Standard GridNMS cloud service: nothing to do. This certificate ships inside the bundle you downloaded and installs itself — every collector trusts the standard cloud service out of the box.

Self-hosted or air-gapped: get the trust certificate for your server from your GridNMS administrator, then pass it with --tls-ca=<path>:

Linux

sudo ./linux/install.sh \
  --control-plane=https://your-server.example.com \
  --join-token=<your-enrollment-token> \
  --tls-ca=<path-to-the-trust-certificate>

Already enrolled and just adding the certificate? Re-run with only --tls-ca (no need to pass --join-token again):

sudo ./linux/install.sh --tls-ca=<path-to-the-trust-certificate>

macOS

sudo ./macos/install.sh \
  --control-plane=https://your-server.example.com \
  --join-token=<your-enrollment-token> \
  --tls-ca=<path-to-the-trust-certificate>

Already enrolled and just adding the certificate? Re-run with only --tls-ca (no need to pass --join-token again):

sudo ./macos/install.sh --tls-ca=<path-to-the-trust-certificate>

Tip

Don’t have the certificate yet? That’s fine — install and enroll the collector now, and add --tls-ca later once your administrator has it for you. Nothing about the collector’s connection to your server, or its ability to receive from devices and Log Forwarders, depends on this step. Until it’s added, the collector shows as connected but holds onto what it collects instead of forwarding it on — its summary output says so plainly.

Verify it’s running

sudo gridnms-collector status

This reports whether the service is running, when it last received updated settings from your GridNMS server, whether its listening ports are open, and the health of its data pipeline.

Managing the collector

Once installed, gridnms-collector is on the host’s $PATH and is the primary tool for day-to-day management:

Command	What it does
sudo gridnms-collector status	Reports service state, remote-configuration recency, listener ports, and pipeline health. Exits with a non-zero status if anything’s unhealthy, so it’s safe to script.
sudo gridnms-collector start	Start it.
sudo gridnms-collector stop	Stop it.
sudo gridnms-collector restart	Restart it in place (or start it, if it isn’t running).
sudo gridnms-collector enroll ...	Re-enroll — see the next section.
gridnms-collector version	Print the installed version.

Linux

For lower-level detail, the service also runs under systemd:

sudo systemctl status gridnms-collector-distro
sudo journalctl -u gridnms-collector-distro -f

macOS

For lower-level detail:

sudo launchctl print system/io.gridnms.collector-distro.opamp-supervisor
sudo tail -f /var/log/gridnms-collector-distro/opamp-supervisor.log
sudo tail -f /var/log/gridnms-collector-distro/opamp-supervisor.err

Re-enrolling

If you need to point a collector at a different GridNMS server, or its enrollment token expired before you used it, get a fresh one-time token from Configure → Collectors and run:

sudo gridnms-collector enroll \
  --control-plane=https://app.gridnms.io \
  --join-token=<your-new-enrollment-token>

Use your self-hosted or air-gapped server’s address in place of https://app.gridnms.io if that’s what this collector connects to.

Note

enroll also accepts --tenant-server as another name for --control-plane.

gridnms-collector enroll restarts the collector automatically once re-enrollment succeeds, so there’s no separate restart step.

After it’s online

1. On Configure → Collectors, confirm the collector shows online.
2. Assign the networks it should watch — see Networks & Sites.
3. Turn on the services you want it to run — every service starts switched off. See Collector Services.
4. 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.

A collector with no assigned network monitors nothing

Installing a collector doesn’t automatically put it to work — it only watches the networks you explicitly assign to it. If devices aren’t showing up after install, this is the first thing to check: open the collector under Configure → Collectors and confirm its Overview tab lists at least one assigned network. Networks are assigned under Configure → Sites & Networks.

Ports & firewall

Direction	Port	Purpose	When you need it
Outbound	443 (HTTPS)	Connects to your GridNMS instance	Always
Inbound	514 (UDP)	Device syslog	Only if devices send syslog directly to this collector
Inbound	162 (UDP)	SNMP traps	Only if devices send traps directly to this collector
Inbound	24742	Log Forwarder data (plain)	Only if Log Forwarders send to this collector
Inbound	24743	Log Forwarder data (encrypted)	Only if Log Forwarders send to this collector
Inbound	24744	Log Forwarder metrics	Only if Log Forwarders send to this collector
Inbound	4320	Log Forwarder management	Only if Log Forwarders send to this collector

Open an inbound port only for the lanes you actually plan to use — none of them are required just to get the collector running and connected. The service runs with administrator privileges, which is what lets it use these ports without any extra host configuration.

Allowlisting specific destinations instead of all outbound HTTPS

If your firewall permits all outbound HTTPS, there’s nothing more to do here — this only applies if you allowlist outbound destinations explicitly. On the standard GridNMS cloud service, a collector reaches three destinations, all on port 443: tunnel.gridnms.io, app.gridnms.io, and ingest.gridnms.io. Allow all three — a collector that can only reach one or two will come online but won’t be able to send everything it collects.

ingest.gridnms.io authenticates with a certificate issued to your specific collector, which a TLS-inspecting firewall or proxy can’t re-sign the way it can for ordinary HTTPS traffic. If you inspect outbound HTTPS, add an inspection exception for that hostname — otherwise logs and metrics won’t get through even though the collector shows online.

Self-hosted and air-gapped deployments don’t have this: the collector only ever talks to the one server address you gave it during install.

Configuration and trust material for a collector live under /etc/gridnms-collector/ on the host.

Updating

There’s no automatic in-place upgrade — a collector doesn’t fetch or apply a newer version on its own. To move a collector to a newer version:

1. Download the newer bundle from the Customer Portal → Downloads.
2. Unpack it and re-run the installer on that host, the same way you did the first time.

It’s safe to run on an already-installed collector: it upgrades the running version in place and never loses the collector’s existing enrollment. If you’re on a self-hosted or air-gapped server and skipped --tls-ca during the original install, this is also a good moment to add it — see Certificates.

Uninstalling

Run the uninstaller from the same unpacked bundle you installed from, with sudo:

Linux

sudo ./linux/uninstall.sh

macOS

sudo ./macos/uninstall.sh

This stops the service and removes the installed program files. Your enrollment credential and trust material are left in place under /etc/gridnms-collector/ in case you’re reinstalling — delete that folder yourself if you’re fully removing the collector from this host, and delete the collector’s entry on Configure → Collectors so it doesn’t linger as offline.

Trouble getting a collector online? See Troubleshooting.