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.

Versions

Windows Server 2012 and later with the DHCP Server role and its module DhcpServer, and Windows PowerShell 3.0 or later, as the prerequisites name them. Generic: no folder of version. That every release answers alike is assumed, not yet checked on a real DHCP Server.

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.