Skip to content
GridNMS Docs

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.

Before you start

Section titled “Before you start”
  • 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.

Get an access token

Section titled “Get an access token”

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.

Skip the approval queue for new installs

Section titled “Skip the approval queue for new installs”

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.

Install

Section titled “Install”

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.

Encrypted from the start

Section titled “Encrypted from the start”

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>

Check that it’s working

Section titled “Check that it’s working”

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.

What it collects, by platform

Section titled “What it collects, by platform”

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

Options reference

Section titled “Options reference”
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.

If the collector is unreachable

Section titled “If the collector is unreachable”

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.

Upgrading

Section titled “Upgrading”

Automatic updates (Linux and macOS)

Section titled “Automatic updates (Linux and macOS)”

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.
  • Upgrade now — asks the forwarder to check for a newer release right away, whether or not auto-upgrade is on. If something would stop the update from landing, GridNMS tells you what when you click it 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.

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.

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 — that always runs immediately.

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.

Reinstalling with a newer bundle

Section titled “Reinstalling with a newer bundle”

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.

Next steps

Section titled “Next steps”

docs built 2026-09-26 · 195c6d00