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

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

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

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.

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

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.

Every module starts switched off

Nothing is collected until a profile turns it on — including host log files. A forwarder whose profiles never mention Linux Host Logs ships no log files at all, however healthy it looks on the Forwarders page. If a host is connected but quiet, the module list on its profile is the first place to look.

Two things aren’t modules you turn on. Host performance metrics (CPU, memory, disk) ship automatically on every platform once a forwarder is connected. So does the host’s hardware and operating system identity — its manufacturer, model, and operating system name and version — which fills in the Overview tab of the host’s entry in Devices & Inventory. Neither needs any configuration. 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

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

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

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.

Everyday workflow

1. 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.
2. Approve any host that appears in the list waiting for a decision.
3. Assign it to a Group — either directly, or automatically via a targeting rule on the group.
4. 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”

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.

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

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

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.

Note

Rotation needs a forwarder and collector recent enough to hold two credentials at once during the handover. On older versions GridNMS declines the rotation and tells you which versions it compared, rather than replacing a credential the host can’t fall back from. Updating the host clears it.

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.

Plan limits

Each approved Log Forwarder counts against your plan’s Log Forwarder allowance. 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

• Installing a Log Forwarder
• Monitoring Your Forwarders
• Container Monitoring