Skip to content

Installing a Log Forwarder

A Log Forwarder installs in one command and needs no further attention once it’s running. It’s a small, self-contained agent — installing it doesn’t download anything, and it never reaches out to the internet on its own.

  • A stable hostname for your GridNMS collector — not a raw IP address. Use a hostname your network resolves consistently (your own DNS, or the collector’s own address if the forwarder runs on the same machine); avoid a numeric address that can change when the collector’s host is recreated or moved. And network access to it from the machine you’re installing on. The forwarder only makes outbound connections — it opens no network-reachable port on the host it runs on.
  • The collector’s log-receiving port must be enabled. In GridNMS, go to Configure → Collectors, open your collector, and check its listen ports.
  • Administrator/root access on the machine you’re installing on.
  • An access token for this host. A first-time install needs one — see Get an access token below.

Every new forwarder authenticates to its collector with a one-time access token, so you create the host in GridNMS before you install on it.

  1. In GridNMS, go to Configure → Log Forwarders and select Add Forwarder.

  2. Enter the machine’s hostname exactly as the machine reports it, pick its site, and select Add.

  3. Open the new forwarder and select Rotate credential. GridNMS shows the access token once — copy it immediately, it isn’t shown again.

If a host already appears in the list waiting for approval, select Approve instead; hosts GridNMS has discovered sending logs can be added with Adopt.

If you regularly install forwarders on new hosts, you can generate a shared install token instead of creating each host ahead of time. Go to Configure → Log Forwarders → Settings, generate a token, and turn on Auto-approve new forwarders with an install token. A host installed with that token connects and starts sending logs immediately, without waiting in the approval queue. Turning the token off (or generating a new one) stops any further installs from skipping the queue — it doesn’t affect forwarders already approved.

Requires: a 64-bit Linux server running systemd (Debian, Ubuntu, RHEL, Rocky, SUSE, and their derivatives all qualify).

  1. Download GridNMS Log Forwarder (Linux) from the Customer Portal → Downloads (sign-in required).

  2. Unpack the bundle and run the installer, naming your collector:

    Terminal window
    tar xzf gridnms-forwarder-<version>-linux-<arch>.tar.gz
    cd gridnms-forwarder-<version>-linux-<arch>
    sudo ./linux/install.sh collector.example.com --credential=<token>

    That’s the whole installation. The forwarder starts immediately and restarts automatically on reboot.

Everyday commands:

Terminal window
sudo gridnms-forwarder status # is it running and healthy?
sudo systemctl status gridnms-forwarder
sudo journalctl -u gridnms-forwarder -f # live agent log
sudo gridnms-forwarder update_config --collector-host=<new-host> # point it at a different collector

Uninstall with sudo ./linux/uninstall.sh from the bundle directory.

The access token is what lets the forwarder connect to its collector, so a forwarder installed with one sends everything over an encrypted connection from its first message. The token is stored in a file only an administrator on that host can read.

If you ever need a new token for an installed host, open it under Configure → Log Forwarders, select Rotate credential, and apply the new token on the host:

Terminal window
sudo gridnms-forwarder update_config --credential=<token>

A new token only reaches a forwarder on its own when that forwarder already holds the previous one. A token issued for a forwarder that doesn’t hold it — the first token for a host that has been sending logs without one, or a host installed with a different token — has to be applied on the host with the command above. Until then the collector refuses the forwarder’s connection, so the forwarder can’t receive configuration and keeps sending logs exactly as it was last set up, which may be unencrypted. GridNMS flags this in the forwarder’s status checks: the Agent process and Credential checks fail and say the collector is rejecting the forwarder’s connection.

Rotate credential is also available for a forwarder in that state, even when GridNMS has not been able to confirm which version the forwarder is running (the version is reported over the very connection the collector is refusing). Because the forwarder isn’t accepted with its current token, the previous token is retired immediately and the new one is not delivered automatically: apply it on the host with the command above.

If a host has lost its token altogether — for example it was reinstalled without --credential — the collector turns it away for presenting nothing, and GridNMS cannot learn which version it runs. Rotate credential then declines and says the host is not presenting a credential; updating the forwarder will not change that. Reinstall the forwarder on that host with --credential=<token> (your install token works), then select Rotate credential again. The collector now sees a token that is not the enrolled one, which is the state above, and the rotation issues the host its own token to apply with update_config.

Pointing a forwarder at a different collector

Section titled “Pointing a forwarder at a different collector”

You can point an enrolled forwarder at another collector in the same site without issuing a new token. Change the collector it connects to on the host, then approve the forwarder if it appears in the list waiting for approval. GridNMS keeps the token the forwarder already has, so there is nothing new to copy across and no new token is shown. Moving a forwarder to a collector in a different site is a new enrollment and issues a new token.

Run the platform’s status command (see the tabs above) — a healthy forwarder reports that it’s running, and exits with a success code so you can use it in your own monitoring.

Then open GridNMS and go to Configure → Log Forwarders — the host should be listed, and log entries from it should appear in Log Search within a minute or two.

Host performance metrics start on their own. Every log source is turned on centrally from GridNMS — including local log files — so a freshly approved forwarder is connected and quiet until you give it a profile. See Forwarder Management.

Linux macOS Windows
Log files ✅ Linux Host Logs, suggested /var/log/syslog and /var/log/*.log ✅ via System Logs ✅ Linux Host Logs despite the name, suggested IIS, Windows component logs, and a folder for your own app logs
System log ✅ systemd journal ✅ Unified log ✅ Windows Event Log
Host performance metrics ✅ automatic ✅ automatic ✅ automatic
Docker container logs ✅ — —
Container stats ✅ ✅ —
NVIDIA GPU metrics ✅ — —
Centrally managed from GridNMS ✅ ✅ ✅
Option What it does
<collector-host> The collector to send logs to. Required, given first.
<port> The collector’s log-receiving port. Defaults to 601. Given second.
--opamp-port=<n> The collector’s management port. Defaults to 4320.
--credential=<token> The host’s access token. Required on a first install; a re-install of an already-enrolled host can leave it out.
--install-dir=<dir> Install under <dir> instead of /usr/local/gridnms/forwarder. See Installing somewhere other than the default.

Installing somewhere other than the default

Section titled “Installing somewhere other than the default”

By default the forwarder installs under /usr/local/gridnms/forwarder on Linux and macOS, and under C:\ProgramData\GridNMS\forwarder on Windows. To put it on another volume, name the directory when you install:

Terminal window
sudo ./linux/install.sh collector.example.com --credential=<token> --install-dir=/data/gridnms-forwarder

Everything the forwarder keeps — its program, its settings and access token, and its queue of logs waiting to be delivered — lives under that directory. The directory must be an absolute path, and on Linux and macOS it must not contain spaces. It must not be writable by other users (the forwarder runs with administrator rights), and it must be on a filesystem that allows programs to run.

A few things stay outside it, because the operating system expects them there: the service registration, the gridnms-forwarder command, and links at the usual locations that lead to your directory — GridNMS refers to the usual locations when it configures the forwarder, and the links make that 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 forwarder in one place, asking for a different place is refused and nothing is changed — a forwarder installed in a new place would not find its access token and would come up unenrolled. To move one, uninstall it first, then install it again in the new place with a fresh credential.

A collector can be installed anywhere in the same way; see Installing a Collector.

Every platform queues collected logs on disk and delivers them once the connection to the collector comes back — a network blip or a collector restart doesn’t lose anything already collected. Queued logs survive a restart of the forwarder or of the host.

A Linux or macOS forwarder can update itself through the collector it reports to — no download or reinstall on the host. Open the forwarder under Configure → Log Forwarders and find Software Update:

  • Auto-upgrade — turn it on and the forwarder installs each new release as it becomes available. It only takes effect once the forwarder has been approved — until then the panel says so, and nothing is installed. Approve it under Configure → Log Forwarders.
  • Release group — chooses when a new release becomes available to this forwarder: as soon as it’s published, or one, three or five days after. Forwarders you add from now on start in the slowest group, so a release is proven on the earlier groups first. Forwarders that were already set up keep updating as soon as a release is published until you pick a group for them. A release that is still waiting for the forwarder’s group is shown with the date it becomes available. The group only sets the wait — Auto-upgrade still decides whether the forwarder updates at all.
  • Upgrade now — asks the forwarder to take the latest release right away, without waiting for its release group: the wait only applies to automatic updates. It installs the release that is available when you click; a release published later waits for the group like any other. GridNMS checks the conditions it can see from here — approval, entitlement, a release for this platform, a fleet hold — and tells you when one of those would stop the update, instead of reporting success.
  • Offered version — the release this forwarder would move to, for its own operating system and processor type. If no version is listed, there’s nothing newer published for that combination yet.

The forwarder downloads the new release in the background while it keeps running, then restarts once to switch over. If the new version doesn’t start cleanly, it goes back to the previous version on its own. Log delivery continues through the update — anything collected in the meantime is queued and sent once the forwarder is back.

If the version doesn’t move. Some conditions are only visible on the host itself, and the panel reports no problem while one of them applies. The most common is a check that began in the moments just after a release was published, before the collector had finished storing the new files: the check can’t complete, and the forwarder then waits several hours before looking again rather than retrying in a tight loop. Nothing reads as unhealthy — the only sign is Running version staying where it was while Offered version shows something newer. Upgrade now does not shorten that wait on a forwarder that has auto-upgrade switched on. The forwarder picks the release up by itself on a later check; if you need it sooner, install it on the host by reinstalling with the newer bundle. The forwarder’s own log on the host records which check it is waiting on.

Running version on the same panel shows what’s installed; you can also run sudo gridnms-forwarder version on the host. From the host itself, sudo gridnms-forwarder upgrade forces an immediate check — the same thing Upgrade now does, for when you’re already on the machine. Keep the collector the forwarder reports to on a current version — the collector is what delivers the update.

If the forwarder runs on a different host from its collector, the collector needs one more inbound port open for updates to land: the management port plus one, so 4321 by default. The forwarder fetches the new release over that port, and renews its access token there too. A forwarder installed on the same host as its collector needs nothing extra. See Ports & firewall.

Set the default for every new forwarder. Under Configure → Log Forwarders → Settings, turn on Keep forwarders up to date automatically to have every newly approved forwarder start with auto-upgrade on, so you don’t have to flip it per host. It only changes what a new approval starts with — use Apply to every forwarder now on the same page to update every forwarder you’ve already approved in one step.

Limit automatic updates to a time window. On the same Settings page, turn on Only update automatically during a time window and set a start and end time in UTC. Outside that window, an automatic update waits for the next window instead of applying right away. This doesn’t affect an update you start yourself with Upgrade now.

Hold the fleet at a version. Enter a version under Hold the fleet at a version and no forwarder installs anything newer than it, whether the update happens automatically or you start it yourself with Upgrade now. Leave it blank to allow every released version.

Windows forwarders, and any forwarder you prefer to update by hand, upgrade by reinstalling. Download the newer bundle from the Customer Portal → Downloads and run the installer again with the same collector and options you used before. The access token is already stored on the host, so you can leave --credential (or -Credential) out — your enrollment carries over.

docs built 2026-11-12 · 945a2dec2