banshee/windows-collection/windows/winrm/interfaces

Network interfaces of a Windows, by WinRM

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.

How it works

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

[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)}

WinRM hands the script to PowerShell itself: no shell stands in between, and the script is the one of windows/ssh/interfaces, without the powershell -Command "…" that cmd.exe needs there. The default shell of an OpenSSH server does not matter here.
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 script only reads.

Prerequisites

The WinRM service of Windows listening in HTTPS. The service runs by default on every Windows Server from 2012 on (on a desktop Windows, winrm quickconfig starts it), with an HTTP listener only; the HTTPS listener needs a certificate: - a certificate for server authentication in the store of the computer (Cert:\LocalMachine\My), bearing the name the poller connects to: issued by the authority of the company, or made on the server by New-SelfSignedCertificate -DnsName <name> -CertStoreLocation Cert:\LocalMachine\My from Windows Server 2012 R2 on (Windows Server 2012 does not have this command); - then the listener: winrm quickconfig -transport:https finds a certificate of an authority by itself, but refuses a self-signed one; the command that takes either, on every Windows from Server 2012 on, is winrm create winrm/config/Listener?Address=*+Transport=HTTPS @{Hostname="<name>";CertificateThumbprint="<thumbprint>"} in cmd.exe, the thumbprint being the one Windows shows for the certificate.
The Windows firewall open to the poller on TCP 5986, which creating the listener does not do: New-NetFirewallRule -DisplayName "WinRM HTTPS" -Direction Inbound -Protocol TCP -LocalPort 5986 -Action Allow in PowerShell. A listener on another port is set in protocol:winrm:port.
The certificate judged by the poller before the account is sent, by the TLS profile of the probe: issued by an authority the system of the poller knows, by an authority added in protocol:tls:authorities, or pinned in protocol:winrm:fingerprint, the way for a self-signed certificate; the pin is not needed when the Security settings trust the first WinRM fingerprint presented. The fingerprint is sha256: followed by the SHA-256 of the certificate in 64 lower-case hexadecimal characters; from a machine that reaches the port, openssl s_client -connect <name>:5986 </dev/null | openssl x509 -noout -fingerprint -sha256 prints it, in capitals, with colons to take off. A certificate whose name is not the address of the host is judged on the name set in protocol:tls:server-name.
NTLM authentication, which the WinRM service accepts as installed (Negotiate = true in winrm get winrm/config/service/auth): the password never travels, only an answer computed with it. A domain that refuses NTLM is not served.
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, local or of the domain, set in protocol:winrm:user (account, DOMAIN\account or account@domain) with its password in protocol:winrm:password, member of the local group "Remote Management Users", which opens WinRM to an account that is not an administrator. No other group is asked for: the network modules read what any account may read, which is not yet checked (Limits).

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 certificate of the listener that expires, or a pinned one that is renewed, stops every WinRM collector of the host: the network/tls/certificate collector of banshee/web-collection, deployed on port 5986, watches it.
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; that setting the output encoding is accepted where WinRM runs PowerShell without a console (a refusal is an error beside the answer, which still arrives, with a name outside ASCII possibly misread).