Forwarder Management
Once a forwarder is installed, you never configure it on the host again. What it collects — which log sources are on, whether host metrics ship, whether Docker data is included — is set centrally in GridNMS under Configure → Log Forwarders, using two building blocks: Groups and Profiles.
That section has four tabs: Forwarders (the hosts themselves), Groups, Profiles, and Settings (fleet-wide policies covered below).
Groups
Section titled “Groups”A Group is a set of forwarders that share the same configuration. Every forwarder belongs to exactly one group. A group is where you:
- Set its operating system — a group is for Linux hosts, macOS hosts, or Windows hosts. See One group, one operating system below.
- Choose which forwarders belong to it, either by picking them directly or with targeting rules (by network, IP range, hostname pattern, or operating system) so new forwarders that match join automatically.
- Choose the collector that group’s forwarders send to.
- Apply one or more Profiles, in order, to define what the group’s forwarders collect.
A forwarder with no group assigned collects only its platform’s default log files — nothing extra turns on until you assign it to a group with a Profile applied.
One group, one operating system
Section titled “One group, one operating system”A group carries its own operating system, chosen when you create it and changeable later from the group’s detail panel. It belongs to the group itself, not to whichever hosts happen to be in it right now, so an empty group still knows what it is for.
The operating system decides which Profiles may be applied: only Profiles for that operating system, plus Profiles that specify no operating system at all, are offered. This is what stops a set of Linux log paths being applied to a group of Macs.
Two cases show up in the group list as not set:
- A group created before operating systems were stored, whose members all run the same one. You’ll see a prompt to confirm it; until you do, every Profile stays eligible.
- A group whose members don’t all run the same operating system. The group’s detail panel names the mismatch and flags the odd hosts out. Move them to a group of their own and then set this group’s operating system.
Changing a Profile’s operating system is checked the same way, from the other direction: if the change would leave a group it’s already applied to with an incompatible Profile, the save is refused and tells you which group.
Profiles
Section titled “Profiles”A Profile is a named, reusable bundle of settings — a set of collection modules, each of which you can turn on or off independently. Create one profile per collection need (for example, “Standard Linux hosts” or “Docker hosts — verbose”), then apply it to as many groups as you like.
Each module in a Profile has its own Include switch — a profile only affects a module when it’s explicitly included. A profile that doesn’t mention a module leaves it alone, so the group (or the platform default) shows through untouched. This lets you build small, focused profiles that each turn on exactly one thing, and combine several on a group.
Switching a module’s Include switch on opens the module so you can see what it needs. For modules that are simply on or off — GPU Metrics, Container Stats, Docker Logs, System Logs and Windows Event Log — it also turns collection on, so one click is enough. A module that still needs something from you before it collects anything, such as a log path or an event channel, says so right under its name while it’s on and empty. Switching the module off again collapses it and returns it to inheriting.
If a group applies more than one profile, they’re combined in the order you list them — a later profile’s included modules take precedence over an earlier one’s for anything both touch.
The modules
Section titled “The modules”| Module | Platform | What it does | Default |
|---|---|---|---|
| macOS Unified Log | macOS | Which categories of system log events to capture, from a curated catalog, or a custom filter. | Standard coverage |
| Linux Host Logs | Linux, Windows | The primary log-file source — a list of file paths to tail. Despite the name it drives Windows hosts too; only the suggested paths differ. | Off — no paths |
| System Logs | Any | A second, independent source over the standard distro log files. | Off |
| Docker Logs | Linux | Tails container logs via the host’s systemd journal — no listening port, no file mount. The switch is offered on macOS too, but a Mac has no systemd journal, so it collects nothing there. | Off |
| Container Stats | Linux, macOS | Reads container CPU, memory, and network usage from the local Docker socket — read-only, never mutates a container. | Off |
| GPU Metrics | Linux | Reads NVIDIA GPU utilization, memory, temperature, and power draw from the host’s NVIDIA drivers. | Off |
| Windows Event Log | Windows | Collects the named Windows Event Log channels you pick — the Windows counterpart to macOS Unified Log and Linux syslog. Use recommended selects Security and System for you. | Off — no channels |
Turning System Logs on tails /var/log/messages, /var/log/secure,
/var/log/syslog, /var/log/auth.log, and /var/log/kern.log unless you
replace that list; on Windows it starts empty, so add the paths you want.
Two things aren’t modules you turn on. Host performance metrics (CPU, memory, disk) and the host’s hardware and operating system identity — its manufacturer, model, and operating system name and version — are reported on every platform without any module being enabled for them.
Both do depend on one thing, because both describe a machine and GridNMS needs to know which machine that is: the forwarder has to be linked to a device. GridNMS usually makes that link itself, but a host that isn’t a device — a log relay nothing else monitors, say — never gets one, and then the Metrics tab stays empty and the Overview tab shows no identity, on an otherwise perfectly healthy forwarder.
A forwarder on an older release simply reports no identity until it’s updated — one more reason to leave automatic updates on.
Turning on Docker container logs
Section titled “Turning on Docker container logs”The Docker Logs module tails your containers’ logs through the host’s
systemd journal — it never opens a port or mounts a container’s files.
Point each service’s logging at journald in its docker-compose.yml:
logging: driver: journald options: tag: "{{.Name}}"Or set it daemon-wide in /etc/docker/daemon.json if you want every
container on the host covered.
If any container on that host is itself part of a logging or storage pipeline of your own, read Recommended Docker Host Configuration before turning this on for it — there’s a feedback loop worth avoiding.
Turning on container stats
Section titled “Turning on container stats”The Container Stats module reads usage data from the local Docker socket.
The account the forwarder runs as needs read access to
/var/run/docker.sock — typically membership in the host’s docker group.
Without that access, the module simply reports no data; it never blocks the
rest of the forwarder.
Together, Docker Logs and Container Stats are what power Container Monitoring for hosts that don’t have a managed device entry of their own — their logs and resource usage show up in GridNMS alongside everything else you monitor.
Turning on GPU metrics
Section titled “Turning on GPU metrics”The GPU Metrics module reports each NVIDIA GPU in a Linux host: how hard it is working, how much of its memory is in use, how hot it is running, and how much power it is drawing.
It needs the host’s NVIDIA drivers installed and usable by the account the
forwarder runs as — the same drivers that provide nvidia-smi. A host with
no NVIDIA GPU, or one running macOS or Windows, simply reports no GPU data;
it never holds up the rest of the forwarder.
Once the module is on, open the host under Configure → Log Forwarders and select its Metrics tab, under GPUs. Each GPU gets its own card showing current utilization, memory, temperature, and power, with charts over the last hour, 6 hours, or 24 hours. A host with several GPUs shows a card per GPU, each labelled with the card’s model.
GPU monitoring is part of the Advanced Server add-on. If it isn’t included in your plan the Metrics tab says so and links you to your plan, rather than showing empty charts — see Your License.
Saving your changes
Section titled “Saving your changes”Group and Profile panels each have one Save and one Cancel at the bottom, covering everything in the panel. Picking an item from a list — a profile to apply, a forwarder to target, a targeting rule — adds it straight away; nothing is stored until you press Save. Cancel discards your changes and closes the panel. If you close the panel, click away, or leave the page with unsaved changes, you’re asked to confirm first.
Checking what a forwarder actually runs
Section titled “Checking what a forwarder actually runs”Profiles describe what you want. To see what a particular host has, open it under Configure → Log Forwarders and select its Configuration tab. The As configured (resolved) card is the same configuration the host is sent — its group, with every applied profile folded in order — and it is read-only, so there is one answer rather than a second place to edit.
The card names the group and the profiles applied to it, then lists the modules. Only modules that are on and apply to this host are listed, so the list is what the host is set up to do and nothing else. If a host is connected but quiet, this card is the first place to look: a module you expected to see missing from the list means no applied profile turns it on.
Each listed module carries a coloured dot, and the three states say different things:
- Green — on and collecting. The line under the name says what it is reading, such as the log paths or the event channels in use.
- Amber — on, but it cannot collect anything yet, and the line under the name says why. A Windows Event Log module with no channels selected reads this way, as does System Logs on a Windows host with no paths given (on Linux and macOS that module falls back to the default paths, so it collects). This is the state worth hunting for: the module is switched on, so nothing looks wrong on the Forwarders page, and it is shipping nothing.
- Hollow, dashed — nobody has chosen. No applied profile touches this module, so it is running the platform default. This is deliberately not drawn the same as an explicit off, so you can tell “we decided against it” from “we never said”.
Under each module the card names the profile that set it, so a surprising value tells you which profile to go and edit.
A forwarder that has not reported in yet is a special case. Until it reports, it has not told us which operating system it runs, and no log sources are sent to a host whose operating system is unknown — so log modules that are on are listed as waiting for this forwarder’s first report rather than claiming to collect. Metric and identity modules are unaffected. Once the host reports, the card fills in on its own.
If the card lists nothing at all, no module is on for this host: turn one on in a Forwarder Profile and apply that profile to the forwarder’s group.
Everyday workflow
Section titled “Everyday workflow”- Add the host under Configure → Log Forwarders and get its access token, then install the forwarder on it with that token — see Installing a Log Forwarder.
- Approve any host that appears in the list waiting for a decision.
- Assign it to a Group — either directly, or automatically via a targeting rule on the group.
- Apply a Profile to that group with the modules you want turned on.
Every host in a group picks up the group’s applied profiles the moment you save — nothing to re-run on the host itself.
Requests marked “Orphaned”
Section titled “Requests marked “Orphaned””Occasionally a request in the list is greyed out and badged Orphaned, with the note “Approved but never linked to a forwarder.” It means the approval went through, but the host never came back to complete its side — usually because it was rebuilt, renamed, or decommissioned between the request and the approval.
Nothing is wrong with your other forwarders, and there is no forwarder waiting to be fixed. Click Clear to remove the leftover entry. If that host should be reporting, install the forwarder on it again and approve the new request that appears.
Linking a forwarder to a device
Section titled “Linking a forwarder to a device”A Log Forwarder and a managed device are two separate records, and a lot of what the forwarder reports only shows up once the two are linked: the host’s performance metrics and its GPUs appear on the device’s own tabs, and the hardware and operating system identity fills in its Overview. An unlinked forwarder keeps collecting and delivering logs normally — it just has no device page to put the rest on.
GridNMS tries to make the link itself when a forwarder is approved, and keeps trying every few minutes for as long as the forwarder is unlinked, using two pieces of evidence in order:
- Its address. If the address the forwarder connected from is the address of a live device at the same site (its main address or one of its additional addresses), that device is the link. A device that has been deleted never counts, and neither does a device at another site that happens to use the same private address.
- Its name. Otherwise the name the host reports for itself is compared
with the device’s name, DNS name, and external hostname at that site —
ignoring case, and also comparing just the first part of a name before the
first dot. So a host reporting
WEB-NODE-01links to a device recorded asweb-node-01.corp.example.
Both comparisons only link when exactly one device at the site qualifies, and an exact name beats a first-part match. If two devices are equally good candidates, GridNMS links neither rather than guessing — the forwarder stays unlinked and you can pick the right one yourself. A device you add after the forwarder was approved is picked up the same way, on a later attempt; a link that already exists is never replaced.
The Device column on the Forwarders tab shows the link. An unlinked forwarder shows Unlinked with a Link to device… button; open the forwarder and click it. The dialog opens with the devices at the site that most likely belong to the forwarder, best match first, each tagged with why it was suggested: Same IP address, Same hostname, Same name, different domain or Similar name. Pick one and click Link, or search for a different device below the list.
If nothing matches the forwarder’s name or address, the dialog says so and offers Add as managed device. It creates the device from what the forwarder reported — its hostname and IP address, which you can edit, and an optional class — and links the forwarder to it in the same step. You need permission to add devices to see this button.
A link you made by hand can be removed again with Unlink; a link GridNMS worked out on its own has no Unlink button, so if it picked the wrong device, link it to the right one instead.
Names after linking
Section titled “Names after linking”A linked forwarder is listed under its device’s name, so one machine reads one way across GridNMS. The name the host reported for itself is not lost: it stays on the forwarder’s System Info card (labelled Hostname reported by the agent) and on the device’s Overview, next to the Log Forwarder field. Unlinking puts the forwarder back under the name the host reported.
Search on the Forwarders tab matches either name, so a linked host is found by the device name shown on its row as well as by the name the host reports for itself.
Fleet-wide settings
Section titled “Fleet-wide settings”The Settings tab holds the policies that apply to every Log Forwarder on your account, rather than to one group. Update delivery — automatic updates, an update time window, and holding the fleet at a version — is covered in Installing a Log Forwarder.
Keep forwarders up to date automatically
Section titled “Keep forwarders up to date automatically”Turn this on and every newly approved forwarder starts with automatic updates enabled, so you don’t have to set it per host. It deliberately leaves forwarders you’ve already approved alone — use Apply to every forwarder now when you want the current setting pushed across the whole fleet in one action. You can still override any individual forwarder afterwards from its own settings.
Rotate forwarder credentials automatically
Section titled “Rotate forwarder credentials automatically”Each Log Forwarder authenticates to its collector with its own credential. You can replace those on a schedule instead of doing it by hand: turn on Rotate forwarder credentials automatically and set Rotate every (days). It’s off by default.
GridNMS then replaces any credential older than that interval, one forwarder at a time. The old credential keeps working until the forwarder confirms it has picked up the new one, so a rotation doesn’t interrupt log delivery. A forwarder that’s offline is simply rotated later, once it’s back.
This doesn’t change Rotate credential on an individual forwarder, which still works at any time — use it when you need to replace one credential immediately rather than waiting for the schedule.
Confirm forwarder credentials are stored with each forwarder
Section titled “Confirm forwarder credentials are stored with each forwarder”A forwarder’s credential is kept with the forwarder itself, so replacing or removing a collector doesn’t leave a forwarder without one. When you update GridNMS, the credentials your forwarders already hold are copied across automatically. To confirm that has finished for your account, ask for the status with an administrator’s API token:
curl -H "Authorization: Bearer $GNMS_TOKEN" \ https://app.gridnms.io/api/v1/log-forwarders/credential-backfillThe answer reports state and a few counts. applied means every forwarder
that has a credential holds it itself. pending means at least one doesn’t yet
(unfilled says how many), and it clears on its own at the next restart.
nothing_to_backfill means none of your forwarders has a credential to copy.
diverged counts forwarders whose own credential differs from the one they had
before the update, which should be zero. Once the update has finished with the
old storage, enrollmentCopiesRemoved is true and the counts that compared
against it are zero because there is nothing left to compare. While it is
false, a non-zero diverged is the one thing that keeps GridNMS from
removing the old storage; it is left untouched until the forwarder concerned has
been checked. The answer never includes a credential. Self-hosted installs use their own address in place of
app.gridnms.io.
Auto-approve new forwarders with an install token
Section titled “Auto-approve new forwarders with an install token”Generate a shared install token and new hosts installed with it are approved the moment they connect, instead of queuing for a decision on the Forwarders tab. Your plan’s forwarder allowance still applies — an over-allowance host waits for a decision exactly as it would have. Generating a new token immediately replaces the old one, and turning the token off stops any further automatic approvals. Full walkthrough in Installing a Log Forwarder.
If a host installed with the token is not approved, it waits on the Forwarders tab and the line under its name says why:
- The host did not present an install token. It was installed without one. Reinstall it with the install token.
- The credential it presented is not the current install token. The token may be out of date, for example if a new one was generated after the host was installed.
- No install token has been generated. Auto-approve is on but there is no token to check against — generate one on the Settings tab.
- The collector the host connected through is not assigned to a site, so the token could not be checked. Give that collector a site under Sites & Networks and the host is checked again on its next check-in.
- The install token matched, but your plan has no free forwarder seats. The host waits for a decision, and is approved on its own once a seat frees up or the plan allows more.
- The install token matched, but approval could not be completed. It is retried on the host’s next check-in.
No line is shown while the install token is turned off.
Plan limits
Section titled “Plan limits”A Log Forwarder counts against your plan’s Log Forwarder allowance for as long as it exists, and keeps its place if you remove or replace the collector it connected through. A forwarder tied to a monitored device does not count — it is part of that device rather than a source of its own. To free an allowance, delete the forwarder. Raw syslog and SNMP trap traffic sent directly to a collector is never limited this way — it’s covered by your plan’s log storage instead. See Pricing for current allowances, or Configure → Log Forwarders for how many you have in use.
Next steps
Section titled “Next steps”docs built 2026-11-12 · 945a2dec2