banshee/linux-collection/linux/ssh/interfaces

Network interfaces of a Linux, by SSH

Returns, for each network interface, the link state, the negotiated speed and duplex, the MTU, the traffic, errors and drops, its IP addresses, and the members of a bond. Thirteen watches are offered, each one set on the probe.

Versions

Generic: /sys/class/net is written by the kernel the same way on Alpine, Debian and Fedora; -s and -H are options of BusyBox as of GNU grep; ip -o … scope global is understood by iproute2 (Debian, Fedora) and by the ip applet of BusyBox (Alpine). A kernel older than 3.15, without carrier_changes, is read too, without link changes.

How it works

The collector reads in one command the files of /sys/class/net (state, speed, duplex, MTU, bond members, bridge port, counters) with grep -s -H, then counts the global addresses of each interface with ip -o addr show scope global.

Traffic comes from the counters over the interval between two runs: there is none on the first run.
A file a driver does not serve (the speed of a link that is down, of a Wi-Fi card) is silenced by grep -s, and its value is missing.
The members of a bond or of a bridge are not judged on their addresses: they carry none.
A missing ip command stops the collector, with its error; nothing readable in /sys/class/net stops it misconfigured.
Nothing is written on the target.

Prerequisites

an SSH account for monitoring, without write rights;
the fingerprint of the server's host key, set in protocol:ssh:fingerprint (not needed when the Security settings trust the first SSH fingerprint presented).

Outputs

Name	Label	Unit	Per instance
`link`	Link state	—	yes, per interface
`carrier-changes`	Link changes since boot	—	yes, per interface
`speed`	Negotiated speed	Mbit/s	yes, per interface
`duplex`	Duplex	—	yes, per interface
`mtu`	MTU	—	yes, per interface
`traffic-in`	Inbound traffic	bit/s	yes, per interface
`traffic-out`	Outbound traffic	bit/s	yes, per interface
`traffic`	Total traffic	bit/s	yes, per interface
`in-percent`	Inbound usage	%	yes, per interface
`out-percent`	Outbound usage	%	yes, per interface
`packets`	Packets	packets/s	yes, per interface
`errors`	Errors	errors/s	yes, per interface
`drops`	Drops	packets/s	yes, per interface
`drop-percent`	Share of packets dropped	%	yes, per interface
`addresses`	IP addresses	—	yes, per interface
`bond-members`	Bond members	—	yes, per bond
`bond-members-up`	Active bond members	—	yes, per bond

The link state is up, down, lowerlayerdown…, the duplex full or half; the usage is the traffic over the negotiated speed; packets, errors and drops count both ways; the addresses are the global ones; an active bond member is one whose link is up. By default, lo, docker* and veth* are left out; the selection is changed on the probe.

Watches

Name	Title	Kind	Defaults	Checked by default
`link-down`	Link down	state, on `link`	critical on `down`, `lowerlayerdown`	yes
`link-flapping`	Link flapping	increase, on `carrier-changes`	warning beyond 3 in 1 h	yes
`speed-degraded`	Negotiated speed degraded	custom	warning below the expected speed, 1000 Mbit/s; critical when half duplex	no
`saturation-in`	Inbound saturation	above a threshold, on `in-percent`	warning above 70 %, critical above 90 %, for 5 min	yes
`saturation-out`	Outbound saturation	above a threshold, on `out-percent`	warning above 70 %, critical above 90 %, for 5 min	yes
`errors`	Errors	custom	warning beyond 1 error/min, critical beyond 0.1 % of traffic	yes
`drops`	Packets dropped	above a threshold, on `drop-percent`	warning above 0.5 %, critical above 2 %	yes
`traffic-unusual`	Unusual traffic	habit, on `traffic`	sensitivity normal, floor 10,000,000 bit/s	no
`mute`	Silent interface	silence, on `packets`	warning after 10 min	no
`missing`	Interface missing	expected instances, on `link`	no interface named: it raises nothing until names are set on the probe	no
`bond-degraded`	Bond degraded	custom	warning when a member is down, critical when 1 is left	yes
`mtu`	Unexpected MTU	expected value, on `mtu`	warning when not 1500	no
`no-address`	No IP address left	below a threshold, on `addresses`	critical below 1	no

Limits

Virtual interfaces (virtio, most cloud NICs) report no speed: they have no usage percent and no speed-degraded.
The counters of a bond add up those of its members: the traffic shows on both.