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
Section titled “Before you start”- In GridNMS, go to Configure → Collectors and select Register collector.
- 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.
- If you’re connecting to a self-hosted 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
Section titled “Prerequisites”- 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, 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
Section titled “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. (A self-hosted deployment uses its own certificate instead — see Certificates below.)
Install
Section titled “Install”Unpack the bundle and run the installer with sudo, passing your enrollment
token from Before you start.
tar xzf gridnms-collector-distro-<version>-linux-<arch>.tar.gzcd 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>tar xzf gridnms-collector-distro-<version>-darwin-<arch>.tar.gzcd 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.
All install options
Section titled “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. |
--install-dir=<dir> |
No | Install under <dir> instead of the default locations — see Installing somewhere other than the default. |
-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.
Installing somewhere other than the default
Section titled “Installing somewhere other than the default”To keep the collector on another volume, name a directory when you install:
sudo ./linux/install.sh --join-token=<your-enrollment-token> --install-dir=/data/gridnms-collectorsudo ./macos/install.sh --join-token=<your-enrollment-token> --install-dir=/Volumes/Data/gridnms-collectorEverything the collector keeps lives under that directory: its programs in
bin/, its settings, certificates and enrollment credential in etc/, and its
state and queued data in var/. The directory must be an absolute path with no
spaces, and neither it nor any directory above it may be writable by other
users — the collector runs with administrator rights, so anyone who could write
there could replace the program it runs. It must also be on a filesystem that
allows programs to run.
A few things stay outside it, because the operating system or GridNMS expects
them there: the service definition, the gridnms-collector command, and links
at /etc/gridnms-collector, /var/lib/gridnms-collector-distro and
/usr/local/gridnms/collector-distro that lead to your directory. GridNMS
refers to those usual locations when it configures the collector, and the links
make them land in your directory.
Running the installer again without the option keeps using your directory.
The option does not move an existing install. If the host already has a
collector in one place, asking for a different place is refused and nothing is
changed — a collector installed in a new place would not find its enrollment
credential and would come up unenrolled. To move one, run the uninstaller, move
the /etc/gridnms-collector folder it leaves behind into the new directory as
etc (the installer tells you the exact command), and install again with
--install-dir; or start fresh with a new --join-token.
Certificates
Section titled “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
Section titled “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:
- The installer stages a temporary, self-signed one immediately, so the service can start right away.
- 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
Section titled “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>:
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>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>Verify it’s running
Section titled “Verify it’s running”sudo gridnms-collector statusThis 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
Section titled “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. |
For lower-level detail, the service also runs under systemd:
sudo systemctl status gridnms-collector-distrosudo journalctl -u gridnms-collector-distro -fFor lower-level detail:
sudo launchctl print system/io.gridnms.collector-distro.opamp-supervisorsudo tail -f /var/log/gridnms-collector-distro/opamp-supervisor.logsudo tail -f /var/log/gridnms-collector-distro/opamp-supervisor.errRe-enrolling
Section titled “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.
gridnms-collector enroll restarts the collector automatically once
re-enrollment succeeds, so there’s no separate restart step.
After it’s online
Section titled “After it’s online”- On Configure → Collectors, confirm the collector shows online.
- Assign the networks it should watch — see Networks & Sites.
- Turn on the services you want it to run — every service starts switched off. See Collector Services.
- 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.
Ports & firewall
Section titled “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 |
| Inbound | 4321 | Log Forwarder updates and credential renewal | Only if Log Forwarders on other hosts 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.
Configuration and trust material for a collector live under
/etc/gridnms-collector/ on the host.
Updating
Section titled “Updating”A collector installed from the current download can update itself. It’s off until you turn it on, one collector at a time:
- Go to Configure → Collectors and open the collector.
- On the Settings tab, find Software and turn on Automatic upgrades.
Below the switch, Release group chooses when a new release becomes available to this collector: as soon as it’s published, or one, three or five days after. Collectors start in the slowest group, so a release is proven on the earlier groups first. The group only sets the wait for automatic upgrades. Upgrade now asks a collector to take the latest release straight away, without waiting for its release group, and works whether or not automatic upgrades are on.
The Software section also shows the version the collector is running, the latest release, and a plain reason whenever nothing will be installed — for example that automatic upgrades are off, or that the release is still waiting for this collector’s group (Upgrade now installs it without the wait).
If a release has been on offer to a collector that is online for a few hours and the collector is still on its old version, the Software section says so, with the time the offer was made. The usual cause is an update that failed to download or did not pass its checks, after which the collector may stop trying on its own. On a collector that can be retried from GridNMS, Upgrade now makes it try again. On an older install that can’t, the section asks for a reinstall from the current download instead. A collector that is running the latest release but whose supporting components were not updated with it is shown the same way.
Two kinds of collector can’t update themselves, and the Software section says so instead of offering the switch:
- A collector installed before self-upgrade was available needs one reinstall from the current download; after that it can keep itself up to date. A collector that has fallen several releases behind can be told the same thing even if it has updated itself before, because moving up more than one release in a single step relies on a newer updater that only a reinstall puts in place. Installing the new version without it would leave parts of the collector sitting at the old one, reporting a version it is not wholly running, so the Software section asks for the reinstall instead.
- A collector running in a container — the one included with a self-hosted or air-gapped install — is updated with the rest of the stack by re-running the bundle installer. It isn’t covered by the in-app server update, and on an air-gapped network there is no image to fetch. See Updating a Self-Hosted Instance.
To move a collector by hand — including one that can’t update itself yet:
- Download the newer bundle from the Customer Portal → Downloads.
- 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
Section titled “Uninstalling”Run the uninstaller from the same unpacked bundle you installed from, with
sudo:
sudo ./linux/uninstall.shsudo ./macos/uninstall.shThis stops the service and removes the installed program files. Your
enrollment credential and trust material are left in place under
/etc/gridnms-collector/ (or etc/ inside your install directory, if you used
--install-dir) 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.
docs built 2026-11-12 · 945a2dec2