Skip to content

Devices & Inventory

Devices are the heart of GridNMS. Every switch, router, firewall, server, access point, and storage array you monitor lives in your inventory. This page explains how to browse that inventory, add new devices, organize them, and inspect a single device in depth.

The device inventory list The device list with status badges, filters, and summary cards across the top.

Open Explore → Devices to see everything GridNMS is tracking. At the top, summary cards give you a running count of Total, Up, Down, and Unknown devices — click any card to filter the list to just those devices.

The list itself shows one row per device. Typical columns include:

Column Description
Name The device’s display name (often its hostname).
IP Address The address GridNMS uses to reach it (or its hostname, for a device with no IP).
Make / Model The manufacturer and model, when known.
Location The device’s location note.
Class The device type — Router, Switch, Firewall, Access Point, and so on.
Collector The collector that monitors it.
Last Seen When the device was last confirmed reachable.
Status A colored badge: Up, Down, Unknown, or Unmonitored.
  • Up — reachable and responding to monitoring. A device also reads Up when it fails the reachability check but a service monitor aimed at that same device has answered in the last few minutes (a host that blocks ping is still plainly there). Its Last seen time is then the time of that check.
  • Down — failed its reachability check and is not answering any service monitor aimed at it. A monitor that reports a service Down does not mark the device Down — that can mean only that service has stopped.
  • Unknown — state not yet determined: newly added, its collector is offline, or that collector has the Monitor service switched off so nothing is pinging the device (more).
  • Unmonitored — the device is in your inventory but monitoring is turned off, so GridNMS isn’t checking it.

Use the search box to find a device by name or IP. Use the Make and Location boxes and the Filters rail to narrow the list by class, collector, status, or network layer; the Site selector narrows it to one site. Filters and the status cards stack, so you can quickly answer questions like “show me every Down switch in the East datacenter.”

Click a column heading — Name, IP Address, Class, Collector, Last Seen, or Status — to sort the list by it, and click it again to reverse the order. The arrow beside the heading shows the current direction. Sorting covers the whole list, not just the page you’re looking at, and the order is kept in the page address, so a refresh or a shared link shows the same view.

IP Address sorts numerically, so 192.0.2.5 comes before 192.0.2.39. A device with no IP address (one added by hostname only) always stays at the end of the list, whichever way you sort. Status puts the devices that need attention first — Down, then Stale, Unknown, Up and Unmonitored — and Last Seen lists devices that have never been seen last.

Click Add Device in the top-right of the device list and choose how:

  • Use the Discovery Tool — scan your network and onboard what it finds (see the tip below).

  • Manually Add a Device — add a record yourself:

    1. Enter the device’s name (required) and its IP address or External Hostname.
    2. Pick the site, and optionally the make, model and class (Router, Switch, Firewall, etc.). The class determines which monitoring packs apply and which detail tabs appear.
    3. Click Add Device.

A manually added device is created unmonitored — no scans or checks run until you open it, add its monitoring credentials (see below) and turn monitoring on with the Monitor toggle. GridNMS picks the collector from the networks your collectors cover (see Sites and collectors).

Every device belongs to a class that describes what kind of device it is. Classes are arranged in a hierarchy (for example, a specific switch model can sit under a general Switch class), and monitoring settings flow down that hierarchy. Assigning the right class means a device automatically inherits the correct checks and detail tabs without you configuring anything per device.

  • Site groups devices by physical location and drives the Site selector used across GridNMS.
  • Collector is the GridNMS component that actually reaches out and polls the device. GridNMS can usually pick the right collector automatically based on the device’s network, but you can pin a device to a specific one if needed. See Collectors for how this works.

To poll a device for detailed metrics, GridNMS needs credentials:

  • SNMP — a community string (v2c) or username/auth/privacy settings (v3), used for interface counters, CPU, memory, and other metrics.
  • SSH — a username with either a password or a private key, used for command-based collection on devices that support it. Paste a PEM-encoded key into the Private Key (PEM) box to use key-based login, leave it blank to use the password, or let GridNMS create the key pair for you. Appliances whose SSH login only answers interactive prompts are handled automatically; you don’t need to configure anything for them.

You can set credentials globally and override them per device when a particular device uses a different community string or login. Open the device, go to its settings, and enter the override there — it takes precedence over the global default for that one device.

Key-based login is usually the better choice for SSH collection: nothing has to store a reusable password for the device, and the key can be restricted to read-only use.

You can paste a key you already have, or have GridNMS make one:

  1. Open the device and select Configure to open Collection & Credential Overrides.
  2. Under Credentials → SSH, select Generate a key for me.
  3. GridNMS creates a new key pair, keeps the private half in its encrypted credential store, and shows you the matching public key. Copy it — this is the only time it’s shown. If you lose it, generate a new one.
  4. Add that public key to the device’s allowed logins and save the device’s SSH username alongside it.

The private half is never displayed and never leaves GridNMS. Generating a new key does not remove the old one from the device — if you’re replacing a key because it may have been exposed, delete the old key’s entry on the device too.

SSH collection only ever reads; it never changes anything on the device. Give it a dedicated account rather than reusing an administrator login, and set that account up so it can do no more than it needs:

  • No password login — lock or disable the account’s password so the key is the only way in.
  • No administrative rights. GridNMS’s built-in Linux, macOS and Windows collection reads values any ordinary logged-in account can already see, so the account needs no sudo, no admin group, and no elevation.
  • Restrict the key itself. Most SSH servers let you attach restrictions to a single key — no interactive terminal, and no port, agent or X11 forwarding. Collection issues one-off commands and needs none of those.
  • Keep a working shell. A “no login” shell such as nologin or false refuses every command, including the short non-interactive ones collection runs, so the account would fail to collect anything. The restrictions above are what limit the account, not the shell.

On macOS and Windows, SSH is off by default — turn on Remote Login (macOS) or install the OpenSSH server feature (Windows) before the device will answer.

Rather than creating and locking down that account by hand, copy the script below for the device’s operating system, save it on the device, and run it there with the public key GridNMS gave you. It creates the account, disables password login, installs the key with the restrictions described above, and prints a short summary when it’s done. Re-running it later — to rotate the key, for example — updates the existing account instead of failing.

Save as provision-ro-linux.sh, then run as root with the public key GridNMS gave you:

Terminal window
sudo ./provision-ro-linux.sh "ssh-ed25519 AAAA... gridnms-device-42"
#!/usr/bin/env bash
# provision-ro-linux.sh — read-only account provisioning for GridNMS agentless
# SSH monitoring.
#
# Creates a dedicated, non-privileged system account this Linux host's SSH
# collection will authenticate as. Run this on the TARGET host you want
# GridNMS to interrogate over SSH — not on the collector or the server.
#
# Usage:
# sudo ./provision-ro-linux.sh "ssh-ed25519 AAAA... gridnms-device-42"
# sudo ./provision-ro-linux.sh --user my-ro-user "ssh-ed25519 AAAA..."
#
# The public key argument is exactly what GridNMS gives you after
# Device → Configure → SSH → "Generate a key for me" (or your own public key,
# if you configured a private key manually instead).
#
# What this does, and why:
# - Creates the account with a REAL shell (default: /bin/bash), never
# /usr/sbin/nologin or /bin/false. This is intentional, not an oversight:
# those "no-login" shells refuse EVERY command the SSH server tries to run
# on the account's behalf, including the one-shot, non-interactive
# commands GridNMS's SSH collection issues (`cat /proc/loadavg`, `df -kP`,
# …) — not just an interactive login. A read-only account still needs a
# working shell to run those; the restriction that matters is everything
# else below, not the shell.
# - Locks the password (`passwd -l`) — no password login is possible at all.
# - Installs ONLY the public key you provide into a dedicated
# ~/.ssh/authorized_keys, with SSH's own key-level restrictions
# (no-pty, no-port-forwarding, no-X11-forwarding, no-agent-forwarding) —
# the key can run a command, but never open an interactive session or
# tunnel through the host.
# - Grants NO sudo/elevated rights. GridNMS's current Linux SSH pack
# (os_release, hw identity via /sys/class/dmi/id/*, /proc/*, df) reads
# files that are world-readable on every mainstream distro by default —
# verified against the shipped pack's own command list. There is
# currently nothing this account needs elevated access for. If a FUTURE
# collector needs one specific privileged command, add a narrowly-scoped
# sudoers NOPASSWD entry for that exact command at that time — never a
# blanket sudo grant "just in case" (see the commented example at the
# bottom of this file).
# - Is idempotent: re-running it (e.g. to rotate the key) updates the
# existing account instead of failing on "user already exists".
#
# This script does NOT install or download anything at runtime (no
# curl/wget/apt/yum calls) — it only uses standard tools already on the box
# (useradd/usermod, passwd, install, id).
set -euo pipefail
PROG="$(basename "$0")"
GRIDNMS_USER="gridnms-ro"
HOME_DIR=""
PUBKEY=""
usage() {
cat >&2 <<EOF
Usage: sudo $PROG [--user NAME] [--home DIR] "<ssh public key line>"
--user NAME account name to create/update (default: gridnms-ro)
--home DIR home directory for the account (default: /var/lib/<user>)
EOF
exit 1
}
while [ $# -gt 0 ]; do
case "$1" in
--user) GRIDNMS_USER="${2:?--user requires a value}"; shift 2 ;;
--home) HOME_DIR="${2:?--home requires a value}"; shift 2 ;;
-h|--help) usage ;;
--) shift; break ;;
-*) echo "$PROG: unknown option: $1" >&2; usage ;;
*) break ;;
esac
done
PUBKEY="${1:-}"
if [ -z "$PUBKEY" ]; then
echo "$PROG: missing required <ssh public key line> argument" >&2
usage
fi
case "$PUBKEY" in
*$'\n'*|*$'\r'*)
echo "$PROG: the public key argument contains a newline or carriage return —" >&2
echo " refusing to use it. A multi-line value would write a SECOND, unrestricted" >&2
echo " authorized_keys entry (only the first line gets the no-pty/no-forwarding" >&2
echo " restrictions below). Paste exactly one key line, with no embedded newlines." >&2
exit 1
;;
esac
case "$PUBKEY" in
ssh-ed25519\ *|ssh-rsa\ *|ecdsa-sha2-*\ *) ;;
*)
echo "$PROG: that doesn't look like an SSH public key line (expected it to start with" >&2
echo " ssh-ed25519 / ssh-rsa / ecdsa-sha2-...) — paste the PUBLIC key GridNMS gave you," >&2
echo " never a private key." >&2
exit 1
;;
esac
if [ -z "$HOME_DIR" ]; then
HOME_DIR="/var/lib/${GRIDNMS_USER}"
fi
if [ "$(id -u)" != "0" ]; then
echo "$PROG: must be run as root (sudo)" >&2
exit 1
fi
if id "$GRIDNMS_USER" >/dev/null 2>&1; then
echo "== ${GRIDNMS_USER} already exists — updating its key and lockdown, not recreating it =="
else
echo "== creating system account ${GRIDNMS_USER} =="
useradd --system --no-create-home --home-dir "$HOME_DIR" --shell /bin/bash "$GRIDNMS_USER"
fi
# No password, ever — key-only. `passwd -l` on an account with no password set
# yet is a harmless no-op (there's nothing to lock beyond marking it locked).
passwd -l "$GRIDNMS_USER" >/dev/null
mkdir -p "${HOME_DIR}/.ssh"
chmod 700 "$HOME_DIR" "${HOME_DIR}/.ssh"
# The key-level restriction options are the actual boundary here — they hold
# even if this account's shell or filesystem posture ever loosens by mistake.
{
printf 'no-pty,no-port-forwarding,no-X11-forwarding,no-agent-forwarding %s\n' "$PUBKEY"
} > "${HOME_DIR}/.ssh/authorized_keys"
chmod 600 "${HOME_DIR}/.ssh/authorized_keys"
chown -R "${GRIDNMS_USER}:${GRIDNMS_USER}" "$HOME_DIR" 2>/dev/null || \
chown -R "${GRIDNMS_USER}" "$HOME_DIR"
echo "== done =="
echo "Account: ${GRIDNMS_USER}"
echo "Home: ${HOME_DIR}"
echo "Auth: SSH key only (password login disabled)"
echo "Privileges: none (no sudo, no group membership beyond its own)"
echo
echo "In GridNMS, set this device's SSH username to '${GRIDNMS_USER}' — the private key"
echo "half already lives on the server from when the public key above was generated/pasted."
# ── If a future collector genuinely needs one privileged command ───────────
# Add a narrowly-scoped sudoers entry for THAT command only, e.g.:
# echo '${GRIDNMS_USER} ALL=(root) NOPASSWD: /usr/sbin/dmidecode -s system-manufacturer' \
# > /etc/sudoers.d/gridnms-ro
# chmod 440 /etc/sudoers.d/gridnms-ro
# Never grant blanket sudo, and never grant a command with arguments the
# account itself can influence (a bare `NOPASSWD: /usr/sbin/dmidecode` with no
# fixed arguments is enough to read arbitrary hardware info this account has
# no other reason to have).

Each device has a Monitor on/off toggle (Monitored / Unmonitored) in the device’s Edit panel; to change several devices at once use Set Monitored in the bulk actions. Turn it off to stop all checks for a device — useful for gear that’s being decommissioned, lab equipment, or a device you don’t want generating alerts. While monitoring is off, the device shows the Unmonitored badge and raises no events. Turn it back on to resume.

When a monitored device still isn’t being checked

Section titled “When a monitored device still isn’t being checked”

Turning the toggle on asks for the device to be checked; the collector that covers it has to be running the Monitor service for that to happen. If it isn’t, the device is never pinged — it stays Unknown, never reports as seen, and looks exactly like a device that just hasn’t been reached yet.

Rather than leave you guessing, the device’s page says so directly: a note under the device name tells you the Monitor service is turned off, names the collector, and links to that collector’s settings so you can switch it on under Plugins. See Collector Services.

The absence of that note is not a promise that the device is being checked — it means GridNMS has no known reason why it wouldn’t be.

Click any device in the list to open its detail page — a focused view of everything GridNMS knows about that one device.

A single device’s detail page The device detail page, with tabs for overview, system stats, interfaces, events, and more.

The detail page is organized into tabs. Which tabs appear depends on the device’s class and the monitoring packs that apply to it, but you’ll commonly see:

Tab What it shows
Overview Key facts — status, address (with the MAC address beside each IP when it is known — hover it to see whether the device reported it or it was learned from the network), class, site, uptime, vendor/model, operating system, and current health summary. Collection and credential settings for this device open from the bottom of this tab, alongside a Reachability Alerts switch for silencing up/down alerts from a noisy device without hiding its events.
System Stats Every system chart for the device in one place — CPU, memory, load, disk, temperature, and anything else its packs report — with a Chart range picker. Device metric thresholds are set here, next to the charts they apply to.
GPU The device’s NVIDIA GPUs — each card’s utilization, memory, temperature, power and ECC errors, with a chart per reading and the device’s GPU thresholds. Only appears when the device’s host reports GPUs.
Interfaces Every port on the device with its status, speed, and live traffic. You can set per-interface bandwidth thresholds here.
Neighbors Directly connected neighbors the device reports, the basis of the topology map.
Applications Services found listening on the device.
Actions Run a check against the device on demand — poll it, scan it, or probe it — and see the result of recent runs. You can also run a single collector from one of its packs (for example Run Config Backup) rather than a full cycle, which is the quickest way to test a change you just made.
Maintenance Maintenance windows scheduled for this device.
Events The history of events for this device.
Logs Raw log messages received from or about this device.
Config Saved configuration backups captured over time, so you can see what changed and when.
Packs The monitoring packs applied to this device, and any collection you have turned off for it.
Discover OIDs Walk the device over SNMP to see what it actually exposes — useful when building a pack.

A tab that counts things shows the count in its label, so you can see there are twelve interfaces without opening the tab. Specialized device classes add their own tabs as well (for example, an access point might show connected clients, and a storage array might show volume capacity).

One System section, whichever way the device is monitored

Section titled “One System section, whichever way the device is monitored”

On System Stats and on Explore → Device Metrics, CPU, load, memory, disk and uptime appear once, in a single System section, however they are collected — by a Log Forwarder, over SSH, or over SNMP. Both pages use the same time range, so there is one range picker, not one per source.

When several methods collect the same reading, GridNMS shows the one closest to the host (Log Forwarder, then SSH, then SNMP) and switches to the next automatically if it goes quiet. The card says which method it is showing and which others also collect it. If the method changes partway through the range you are looking at, each method is drawn as its own line, with a marker and a note at the moment it changed, so you can see where the switch happened.

  • Compare methods draws every method that collects a reading as its own line on the same chart, so you can see how the sources differ. A method that collects the reading but reported nothing in the range is named under the chart. Readings from monitoring packs, as the pack reports them, open underneath. It adds ?compare=1 to the page address, so a link keeps it open.
  • No recent readings on a card means a method does collect that reading but none has reported lately. The card says who reported last and when — check that collection is still running and the host is reachable.
  • Not collected on this device lists readings no method collects here. Attach a monitoring pack that reports them, or link a Log Forwarder.
  • Readings that are specific to a vendor or pack, and that do not map onto the standard set, stay below the System section under More system metrics.

A device whose host has NVIDIA GPUs gets a GPU tab, and the same readings appear as a GPUs section on Explore → Device Metrics. GPU readings come from the Log Forwarder running on the device’s host, so the forwarder must be linked to the device and have the GPU Metrics module turned on — see Turning on GPU metrics.

The tab shows one card per GPU with its current utilization, temperature, power draw, fan speed, memory and ECC error counts, then a chart for each reading with one line per GPU, named by its index and product (for example GPU 2 · Tesla V100). The charts follow the Chart range picker, and each can be pinned to a dashboard. The numbers match what the forwarder’s own Metrics tab shows for the same host.

If the tab says No host is reporting GPUs for this device, no Log Forwarder is linked to the device — see Linking a forwarder to a device. If it says No GPUs reported yet, a forwarder is linked but has not reported a GPU in the last 15 minutes. GPU monitoring is part of the Advanced Server add-on; without it the tab does not appear.

If one device flaps up and down in a way you’ve decided not to be paged about, turn off Reachability Alerts on its Overview tab rather than turning off its monitoring. The up/down events — and everything that depends on them — keep being recorded; only the email or page stops, and only for reachability. Every other alert about that device still reaches you. See Notifications.

When you need to act on many devices at once, select multiple rows in the device list using the checkboxes. A bulk-action bar appears, letting you:

  • Turn monitoring on or off for all selected devices.
  • Reassign them to a different site or collector.
  • Change their class.
  • Delete them from inventory.

This is the fastest way to onboard or reorganize a batch of devices after a discovery scan.

  • Find devices automatically with Network Discovery.
  • See what your network gear has spotted nearby that isn’t in your inventory yet on the Hosts page.
  • See how devices connect on the Graph Explorer page.
  • Learn what GridNMS checks and how often in Monitoring.

docs built 2026-11-12 · 945a2dec2