At Slingshot, we’ve moved our Managed clients over to Unifi networking systems, and I wanted to use our RMM to directly monitor the Unifi Controller. The API isn’t officially documented, but I did find other resources: the community’s API documentation, CyberDrain’s examples, and the Unifi API browser. Add tons of other research and trial/error, and I finally accomplished a Powershell RMM script that monitors Device connections, resources/ports, and Alerts, and reports on a ton more.
Enough with the intros. Here’s an instance currently alerting in Solarwinds RMM:
…and More Info gives the full report (looks better in console — I wish SWRMM preserved whitespace):
Before I forget, some quick notes:
- Needs a local account (limited admin/readonly) on controller
- For UDMPs with firmware 1.6 or greater, use port 443; For older controllers, use port 8443
- It defaults the Controller IP to the detected Gateway IP (we do a lot of UDMPs).
- Several of the Device Status codes are documented nowhere, so this script might have the only public record of them (for posterity, I’ve figured out 2=pending adoption, 9=inform error, and 11=isolated).
And finally the Powershell — (self-consciously) still in progress with plenty of debug stubs, BUT with lots of useful production miles already under its belt:
<# checkHealth-UnifiController.ps1
Purpose: for all sites on a controller, checks device connections, resources, ports, alerts
Author: Slingshot Solutions, www.slingfive.com
Params: $IP (or hostname) of controller (default: detected gateway), [int]$PortNum (default:443), Username, PASSWORD
Notes:
* needs a local account (limited admin/readonly) on controller
* For UDMPs with firmware 1.6 or greater, use port 443; For older controllers, use port 8443
#>
# PREP SCRIPT:
param(
$IP = (Get-wmiObject Win32_networkAdapterConfiguration |where-object{$_.IPEnabled -and $_.DefaultIPGateway}).DefaultIPGateway[0],
$PortNum = 443, # or 8443 depending on controller version
$Username,
$Password
)
# tweaks:
trap { $_; exit 1 } # force RMM to treat unhandled runtime errors as ERROR!
#widen host buffer for better output on old PS versions:
$pswindow=(Get-Host).UI.RawUI
$newsize=$pswindow.BufferSize; if($newsize.width -lt 100){$newsize.width=100}; $pswindow.BufferSize=$newsize
$newsize=$pswindow.WindowSize; if($newsize.width -lt 100){$newsize.width=100;$newsize.height=20}; $pswindow.WindowSize=$newsize
function short([string]$str,[int]$size){if($str.length -gt $size){return ($str.substring(0,$size-3)+"...")}else{ return $str}}
# vars:
$exitcode = 0
$report = ""
$FullRpt = ""
$StopWatch = [system.diagnostics.stopwatch]::startNew()
if(!$Password){
write-host "PARAMETERS:"
foreach ( $key in ((Get-Command -Name $MyInvocation.InvocationName).Parameters).Keys ) {
$val = ((Get-Variable $key -ea SilentlyContinue).Value) -join ", "
Write-Host " $($key): $val"
}
write-error "Hey dummy, set your params!"
exit 1000
}
$Credential = @{ username="$Username"; password="$Password"; remember=$True; strict=$True; } |ConvertTo-Json
if($PortNum -eq 443){ # UnifiOS 1.6 or newer:
$BaseURI = "https://$($IP):$($PortNum)/proxy/network"
$LoginURI = "https://$($IP):$($PortNum)/api/auth/login"
}elseif($PortNum -eq 8443){ # EdgeOS 1.5 firmware or older:
$BaseURI = "https://$($IP):$($PortNum)"
$LoginURI = "https://$($IP):$($PortNum)/api/login"
}
# CONNECT TO CONTROLLER
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11, tls"
[Net.ServicePointManager]::ServerCertificateValidationCallback = { $True }
#$LoginURI
Try {
$login = Invoke-RestMethod -uri $LoginURI -Method POST -Body $Credential -ContentType "application/json" -SessionVariable UniFiSession | out-null
}catch{ #wrong username/password = "The remote server returned an error: (400) Bad Request"
write-error "* ERROR - Api Connection Error: $($_.Exception.Message)"
$exitcode = 1010
}
if($exitcode -eq 0){
#write-host "CONNECTED`r`n"
}
# GET ALL SITES
if($exitcode -eq 0){
try {
$urlSites = "$($BaseURI)/api/stat/sites"
$sites = Invoke-Restmethod -Uri $urlSites -Method GET -WebSession $UniFiSession
}catch{
#$report += "* ERROR - Sites Query Failed: $($_.Exception.Message)`r`n"
write-error "* ERROR - Sites Query Failed: $($_.Exception.Message)`r`n"
$exitcode = 1011
}
}
# LOOP THROUGH SITES
if($exitcode -eq 0){
# DIRTY HACK: UDMPs lose their auth on the second call (Something ServerCertificateValidationCallback related), so just pound it back every time:
Invoke-RestMethod -uri $LoginURI -Method POST -Body $Credential -ContentType "application/json" -SessionVariable UniFiSession | out-null
$rptDevices = ""
$rptAlarms = ""
Foreach ($site in $sites.data){ # SITE
try {
$urlDevices = "$($BaseURI)/api/s/$($site.name)/stat/device/"
$devices = Invoke-Restmethod -Uri $urlDevices -Method GET -ContentType "application/json" -Headers @{"Accept"="application/json"} -WebSession $UniFiSession
}catch{
write-error "* ERROR - Device Query Failed: $($_.Exception.Message)`r`n"
}
$shortsitename = short $site.desc 7
$FullRpt += "`r`nSITE '$($site.desc)' - $urlDevices :`r`n"
$DeviceStateNames = @{0="disconnected"; 1="connected"; 2="pending adoption"; 3="3(?)"; 4="upgrading"; 5="provisioning"; 6="heartbeat missed"; 9="inform error"; 11="isolated" }
#https://ubntwiki.com/products/software/unifi-controller/api:
$DeviceModelNames = @{"BZ2"="UniFi AP"; "BZ2LR"="UniFi AP-LR"; "U2HSR"="UniFi AP-Outdoor+"; "U2IW"="UniFi AP-In Wall"; "U2L48"="UniFi AP-LR"; "U2Lv2"="UniFi AP-LR v2"; "U2M"="UniFi AP-Mini"; "U2O"="UniFi AP-Outdoor"; "U2S48"="UniFi AP"; "U2Sv2"="UniFi AP v2"; "U5O"="UniFi AP-Outdoor 5G"; "U7E"="UniFi AP-AC"; "U7EDU"="UniFi AP-AC-EDU"; "U7Ev2"="UniFi AP-AC v2"; "U7HD"="UniFi AP-HD"; "U7SHD"="UniFi AP-SHD"; "U7NHD"="UniFi AP-nanoHD"; "UFLHD"="UniFi AP-Flex-HD"; "UHDIW"="UniFi AP-HD-In Wall"; "UCXG"="UniFi AP-XG"; "UXSDM"="UniFi AP-BaseStationXG"; "UCMSH"="UniFi AP-MeshXG"; "U7IW"="UniFi AP-AC-In Wall"; "U7IWP"="UniFi AP-AC-In Wall Pro"; "U7MP"="UniFi AP-AC-Mesh-Pro"; "U7LR"="UniFi AP-AC-LR"; "U7LT"="UniFi AP-AC-Lite"; "U7O"="UniFi AP-AC Outdoor"; "U7P"="UniFi AP-Pro"; "U7MSH"="UniFi AP-AC-Mesh"; "U7PG2"="UniFi AP-AC-Pro"; "p2N"="PicoStation M2"; "US48PRO"="UniFi Switch Pro 48"; "US8"="UniFi Switch 8"; "US8P60"="UniFi Switch 8 POE-60W"; "US8P150"="UniFi Switch 8 POE-150W"; "S28150"="UniFi Switch 8 AT-150W"; "USC8"="UniFi Switch 8"; "US16P150"="UniFi Switch 16 POE-150W"; "S216150"="UniFi Switch 16 AT-150W"; "US24"="UniFi Switch 24"; "US24P250"="UniFi Switch 24 POE-250W"; "US24PL2"="UniFi Switch 24 L2 POE"; "US24P500"="UniFi Switch 24 POE-500W"; "S224250"="UniFi Switch 24 AT-250W"; "S224500"="UniFi Switch 24 AT-500W"; "US48"="UniFi Switch 48"; "US48P500"="UniFi Switch 48 POE-500W"; "US48PL2"="UniFi Switch 48 L2 POE"; "US48P750"="UniFi Switch 48 POE-750W"; "S248500"="UniFi Switch 48 AT-500W"; "S248750"="UniFi Switch 48 AT-750W"; "US6XG150"="UniFi Switch 6XG POE-150W"; "USXG"="UniFi Switch 16XG"; "UGW3"="UniFi Security Gateway 3P"; "UGW4"="UniFi Security Gateway 4P"; "UGWHD4"="UniFi Security Gateway HD"; "UGWXG"="UniFi Security Gateway XG-8"; "UP4"="UniFi Phone-X"; "UP5"="UniFi Phone"; "UP5t"="UniFi Phone-Pro"; "UP7"="UniFi Phone-Executive"; "UP5c"="UniFi Phone"; "UP5tc"="UniFi Phone-Pro"; "UP7c"="UniFi Phone-Executive";
"UDMPRO"="UniFi Dream Machine Pro"}
# LOOP THROUGH DEVICES FOR SITE
Foreach ($device in ($devices.data)){
$DeviceModelName = $DeviceModelNames[$($device.model)]
$DeviceStateName = $DeviceStateNames[$device.state]
if( $device.default -eq $True){ # PENDING ADOPTION:
$vwireEnabled = ($device.vwireEnabled -eq $True)
$discovered_via = $device.discovered_via #scan or l2
$FullRpt += "* $($device.type) $DeviceModelName, ip:$($device.ip), mac:$($device.mac), state:$DeviceStateName $($device.state), discovered_via:$discovered_via, wireless:$vwireEnabled`r`n"
$rptDevices += "* PENDING ADOPTION$(if($vwireEnabled){" (WIRELESS)"}): $shortsitename > ($DeviceModelName)`r`n"
$exitcode = 1010
}elseif ($device.adopted -eq $True){
if($device.state -eq 0 -or $device.state -eq 9 -or $device.state -eq 11){ # DISCONNECTED, INFORM ERROR, ISOLATED:
$FullRpt += "* '$($device.NAME)' - $($device.type) $DeviceModelName, ip:$($device.ip), mac:$($device.mac),`r`n state:$($device.state) $DeviceStateName, adopted:$($device.adopted), disabled:$($device.disabled -eq $True)`r`n"
if($device.disabled -ne $True){ # don't care if it's disabled
$rptDevices += "* $($DeviceStateName.toUpper()): $shortsitename > '$($device.name)'`r`n"
$exitcode = 1011
}
}else{ # OTHERWISE:
$uptime = new-TimeSpan -Seconds (0+ $device.'system-stats'.uptime)
$FullRpt += "* '$($device.NAME)' - $($device.type) $DeviceModelName, ip:$($device.ip), mac:$($device.mac),`r`n state:$($device.state) $DeviceStateName, uptime:$uptime, cpu:$([int]$device.'system-stats'.cpu)%, mem:$([int]$device.'system-stats'.mem)%, current:$(!$device.upgradable) (FW v$($device.version))`r`n"
if( [math]::Round($device.'system-stats'.uptime) -lt "300") {
$rptDevices += "* $shortsitename > $($device.name) : Disconnected `r`n"
$exitcode = 1010
}
if( [math]::Round($device.'system-stats'.cpu) -gt "90.0") {
$rptDevices += "* $shortsitename > $($device.name) : CPU usage of $($device.'system-stats'.cpu)% `r`n"
$exitcode = 1012
}
if( [math]::Round($device.'system-stats'.mem) -gt "90.0") {
$rptDevices += "* $shortsitename > $($device.name) : Memory usage of $($device.'system-stats'.mem)% `r`n"
$exitcode = 1013
}
if( $device.upgradable -eq $true ) {
# $rptDevices += "* $shortsitename > $($device.name) : Firmware upgrade available <-- IGNORING til QA recovers`r`n"
# $exitcode = 1014
}
#PORTS:
#if($device.port_table.count -gt 0){ #don't need to see AP Pros' secondary ports
if($device.type -eq 'usw'){
$FullRpt += " "+ ($device.port_table |ft port_idx,name,enable,up,is_uplink,port_poe,autoneg,speed,full_duplex,network_name -AutoSize |out-string).trim().replace("`n", "`n ") +"`r`n"
}
Foreach ($port in $device.port_table.data){
if($port.stp_state -eq "discard"){
$rptDevices += "* $shortsitename > $($device.desc) > PORT $($device.name) : blocked due to STP issues `r`n"
$exitcode = 1017
}
}
}
}
}
Foreach ($device in $devices.data.wan1 |where-object {$_.name}){ #weirdly duplicates with blanks otherwise
$FullRpt += "* FW WAN1 '$($device.name)' - is_uplink:$($device.is_uplink), up:$($device.up), ip:$($device.ip), netmask:$($device.netmask), gateway:$($device.gateway) `r`n"
if($device.is_uplink -and $device.up -ne $True) {
$rptDevices += "* $shortsitename > WAN1 $($device.name) : link down `r`n"
$exitcode = 1015
}
}
Foreach ($device in $devices.data.wan2 |where-object {$_.name}){#weirdly duplicates with blanks otherwise
$FullRpt += "* FW WAN2 '$($device.name)' - is_uplink:$($device.is_uplink), up:$($device.up), ip:$($device.ip), netmask:$($device.netmask), gateway:$($device.gateway) `r`n"
if($device.is_uplink -and $device.up -ne $True) {
$rptDevices += "* $shortsitename > WAN2 $($device.name) : link down`r`n"
$exitcode = 1016
}
}
# DIRTY HACK: UDMPs lose their auth on the second call (Something ServerCertificateValidationCallback related), so just pound it back every time:
Invoke-RestMethod -uri $LoginURI -Method POST -Body $Credential -ContentType "application/json" -SessionVariable UniFiSession | out-null
try {
$urlAlarms = "$($BaseURI)/api/s/$($site.name)/stat/alarm/"
$alarms = Invoke-Restmethod -Uri $urlAlarms -Method GET -ContentType "application/json" -Headers @{"Accept"="application/json"} -WebSession $UniFiSession
}catch{
$report += "* ERROR - Alarm Query Failed: $($_.Exception.Message)"
write-error "* ERROR - Alarm Query Failed: $($_.Exception.Message)"
}
Foreach ($alarm in ($alarms.data)){
if(! $($alarm.handled_time)) { # ???
$rptAlarms += "* ALERT: $shortsitename > '$($alarm.ap_name)' : $($alarm.msg) @$([datetime]$alarm.datetime -f "yyyy-MM-dd-Hmmss") `r`n"
$exitcode = 1018
}
}
}
}
if($rptDevices){
$report += "$rptDevices `r`n"
}
if($rptAlarms){
$report += "$rptAlarms `r`n"
}
# REPORT PASS/FAIL
if($exitcode -gt 0){
write-host "FAIL - problems found:"
}else{
write-host "OK - no problems found!"
}
$report
# REPORT REST:
write-host "CHECKED DATA:"
write-host " "($FullRpt.replace("`n", "`n ")).trim() #format
write-host
write-host "PARAMETERS:"
foreach ( $key in ((Get-Command -Name $MyInvocation.InvocationName).Parameters).Keys ) {
$val = ((Get-Variable $key -ea SilentlyContinue).Value) -join ", "
Write-Host " $($key): $val"
}
write-host
write-host "CONTEXT:"
write-host " Script Path:" (get-item $MyInvocation.InvocationName)
write-host " Script Last Updated:" (get-item $MyInvocation.InvocationName).LastWriteTime " (try -5hrs [SW saves as UTC])"
write-host " Execution Time: Total $($elapsed_Total)sec"
# WRAP UP:
write-host
write-host "exitcode: $exitcode"
exit $exitcode
NOTE: updates since publishing this have so far added:
* proper detection of the “pending adoption” state
* awareness of the undocumented “adopting” state
* awareness of the undocumented UBB, USP and USW-Flex-Mini models
If anyone’s dying to see the latest version, let me know in the comments.