banshee/windows-collection/windows/ssh/interfaces

Network interfaces of a Windows, by SSH

Returns the state, the speed, the traffic, the errors and the IPv4 addresses of each network adapter of a Windows. Eleven watches are proposed, each one set on the probe.

Versions

Windows Server 2012 and later, Windows 8 and later: Windows PowerShell 3.0 and the modules NetAdapter and NetTCPIP, which the collector needs, ship with each of them; the OpenSSH server is built in from Windows Server 2019 and Windows 10 1809, installed from Win32-OpenSSH before. Generic: no folder of version. That every release answers alike is assumed, not yet checked on a real Windows.

How it works

The collector runs one PowerShell command that reads three lists, joined by the name of the adapter:

powershell -NoProfile -NonInteractive -Command "[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding; ConvertTo-Json -Compress -Depth 4 -InputObject @{adapters = @(Get-NetAdapter | Select-Object Name, State, InterfaceOperationalStatus, ReceiveLinkSpeed, TransmitLinkSpeed, MtuSize); statistics = @(Get-NetAdapterStatistics | Select-Object Name, ReceivedBytes, SentBytes, ReceivedUnicastPackets, ReceivedMulticastPackets, ReceivedBroadcastPackets, SentUnicastPackets, SentMulticastPackets, SentBroadcastPackets, ReceivedPacketErrors, OutboundPacketErrors, ReceivedDiscardedPackets, OutboundDiscardedPackets); addresses = @(Get-NetIPAddress -AddressFamily IPv4 | Select-Object InterfaceAlias)}"

Get-NetAdapter, Get-NetAdapterStatistics and Get-NetIPAddress read the CIM classes MSFT_NetAdapter, MSFT_NetAdapterStatisticsSettingData and MSFT_NetIPAddress; their modules, NetAdapter and NetTCPIP, ship with every Windows from Server 2012 and Windows 8 on.
An adapter is named as in "Network Connections" (Ethernet, vEthernet (Default Switch)). The hidden adapters of the network stack (WAN Miniport, filters, tunnels) are not listed by Get-NetAdapter.
The link state is InterfaceOperationalStatus in the words of IF-MIB: up, down, testing, unknown, dormant, notpresent, lowerlayerdown. A disabled adapter (State 3) is said disabled, so that it does not pass for a link down.
The negotiated speed is the slower of the two directions, in Mbit/s; an adapter that is down has none.
The traffic, the packets, the errors and the drops are the rates of the counters between two runs: nothing at the first run.
The output is written in UTF-8 without a byte order mark, so that an adapter name outside ASCII reads right.
No adapter at all, or an answer that is not the expected JSON, stops the collector as misconfigured.

Nothing is written to the Windows: the command only reads.

Prerequisites

The OpenSSH server of Windows, installed and started: - on Windows Server 2019 and later, Windows 10 (version 1809 and later) and Windows 11, where it is built in: the optional feature "OpenSSH Server" (Settings, Optional features; or Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0 in PowerShell), then the service sshd started and set to start automatically; - on Windows Server 2012, 2012 R2 and 2016, Windows 8, 8.1 and the earlier Windows 10, where it is not built in: OpenSSH for Windows installed from its Microsoft release (Win32-OpenSSH), then the service sshd started and set to start automatically.
The default shell of the OpenSSH server left at cmd.exe, as it is installed: the collector starts PowerShell itself, and a command meant for cmd.exe would be read differently by a PowerShell default shell.
Windows PowerShell 3.0 or later, as shipped with every Windows from Server 2012 and Windows 8 on (3.0 on Server 2012, 4.0 on 2012 R2, 5.1 from 2016 on).
An account for monitoring, without administrator rights, member of the local groups "Performance Monitor Users" and "Event Log Readers", so that the performance counters and the System log are not refused to it. banshee reads it in protocol:ssh:user, with its password in protocol:ssh:password or its key in protocol:ssh:private-key (the public key then in C:\Users\<account>.ssh\authorized_keys).
The fingerprint of the server's host key, set in protocol:ssh:fingerprint (on the server, C:\ProgramData\ssh\ssh_host_ed25519_key.pub); not needed when the Security settings trust the first SSH fingerprint presented.
The Windows firewall open to the poller on TCP 22 (the rule "OpenSSH SSH Server (sshd)", created with the feature).

Outputs

Name	Label	Unit	Per instance
`link`	Link state	—	yes, per interface
`speed`	Negotiated speed	Mbit/s	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`	IPv4 addresses	—	yes, per interface

Watches

Name	Title	Kind	Defaults	Checked by default
`link-down`	Link down	state to avoid, on `link`	critical on `down` and `lowerlayerdown`; no warning	yes
`speed-degraded`	Negotiated speed degraded	judged by the collector	warning when the negotiated speed is below the expected speed, 1000 Mbit/s	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	judged by the collector	warning above 1 error per minute; critical above 0.1 % of the traffic	yes
`drops`	Packets dropped	above a threshold, on `drop-percent`	warning above 0.5 %, critical above 2 %	yes
`traffic-unusual`	Unusual traffic	off its habit, on `traffic`	normal sensitivity, never under 10,000,000 bit/s (10 Mbit/s)	no
`mute`	Silent interface	no activity, on `packets`	warning after 10 min at zero packets; no critical	no
`missing`	Interface missing	expected instances, on `link`	no interface named: it raises nothing until names are set on the probe	no
`mtu`	Unexpected MTU	expected value, on `mtu`	warning when the MTU is anything but 1500; no critical	no
`no-address`	No IPv4 address left	below a threshold, on `addresses`	critical below 1; no warning	no

"Unusual traffic" needs the history of the measure: until the poller has learnt it, the watch says it is learning and raises nothing.

Limits

A cable unplugged from a port that is not used raises "Link down": disable the adapter, or leave it out of the selection.
Neither the duplex nor the changes of a link are served: a link that flaps between two runs is not seen.
Only IPv4 addresses are counted.
An adapter renamed is a new instance, and the former one goes missing.
Not yet checked on a real Windows: the property State of MSFT_NetAdapter and its value 3 for a disabled adapter, and the commands Get-NetAdapter* run by an account without administrator rights.