Skip to content

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.

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

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

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

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

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

Terminal window
sudo ./linux/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.

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:

Terminal window
sudo ./linux/install.sh --join-token=<your-enrollment-token> --install-dir=/data/gridnms-collector

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

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.

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.

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

Terminal window
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):

Terminal window
sudo ./linux/install.sh --tls-ca=<path-to-the-trust-certificate>
Terminal window
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.

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:

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

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:

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

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

A collector installed from the current download can update itself. It’s off until you turn it on, one collector at a time:

  1. Go to Configure → Collectors and open the collector.
  2. 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:

  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.

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

Terminal window
sudo ./linux/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/ (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