dhcp-scopes

DHCP scopes, by WinRM

Returns, for each IPv4 scope of the DHCP Server of a Windows, the share of its addresses in use, and the addresses free and leased. Two watches are proposed, both checked: a scope nearly full, and a scope that is no longer there.

How it works

The collector runs one PowerShell script, by WinRM, that reads the statistics of every IPv4 scope of the local DHCP Server:

$ErrorActionPreference = 'Stop'; [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding; ConvertTo-Json -Compress -Depth 4 -InputObject @{scopes = @(Get-DhcpServerv4ScopeStatistics | ForEach-Object { @{scope = [string]$_.ScopeId; used = $_.PercentageInUse; free = $_.AddressesFree; inuse = $_.AddressesInUse} })}

• WinRM hands the script to PowerShell itself: the script is the one of active-directory/ssh/dhcp-scopes, without the powershell -Command "…" that cmd.exe needs there.
• Get-DhcpServerv4ScopeStatistics, without a scope, returns the statistics of every IPv4 scope (Microsoft, DhcpServer module). Its objects are those of the WMI class DhcpServerv4ScopeStatistics (namespace root\Microsoft\Windows\DHCP), whose properties Microsoft documents: ScopeId, the identifier of the scope; PercentageInUse, the share of its addresses in use; AddressesFree; AddressesInUse.
• A scope is named by its identifier, the address of its network: 192.0.2.0. used is rounded to a tenth.
• The state of a failover relationship between two DHCP Servers is the dhcp-failover collector.
• No IPv4 scope stops the collector as misconfigured, as does an answer that is not the expected JSON: a DHCP Server that is stopped, or a module that is missing, among them.

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

Prerequisites

• A Windows Server 2012 or later with the DHCP Server role and its PowerShell module (DhcpServer, installed with the management tools of the role), with Windows PowerShell 3.0 or later.
• The WinRM service listening in HTTPS, on TCP 5986 or the port set in protocol:winrm:port, open in the Windows firewall to the poller, with a certificate the poller judges by the TLS profile of the probe or pins in protocol:winrm:fingerprint: the steps are those of the windows/winrm/services collector of banshee/windows-collection. NTLM authentication, which the WinRM service accepts as installed.
• An account for monitoring, without administrator rights, set in protocol:winrm:user (DOMAIN\account or account@domain) with its password in protocol:winrm:password, member of the group "Remote Management Users" and of the group "DHCP Users", which the role creates (of the domain on a domain controller, local elsewhere): Microsoft documents it as read-only access to the DHCP Server, its configuration and its leases. Never "DHCP Administrators".

Outputs

Watches

Limits

• IPv6 scopes are not read.
• Not yet checked on a real DHCP Server: the execution; that "DHCP Users" is enough for the cmdlet, through WinRM, as it is for the DHCP console.