Two days ago, I received my new Ubiquiti UISP Console, an eight-port switch/router with 10Gbit SFP+ slots managed by the Ubiquiti UISP software running on my VPS in Docker. In this blog post, I will show you a few examples of how to query it using PowerShell.

What is Ubiquiti UISP?

“UISP is a software application which allows you to manage, configure, upgrade, and monitor all the ISP and provider devices Ubiquiti makes. This includes, UISP, airMAX, airCube, airFiber, EdgeMAX, UFiber and sunMAX devices families. While the ethos is similar, UISP and UniFi are completely separate platforms and cannot be interchangeable. UniFi devices cannot be managed by UISP and UISP devices cannot be managed by UniFi.

UISP devices have their own separate user interfaces and can generally be used with or without the UISP application. However, like UniFi – without the cloud connected application in place, the devices lose out on alerts, remote configurations and access via the UISP app.”

Source: https://support.hostifi.com/en/articles/6395230-how-to-get-started-with-uisp

Creating an API key

Connection to your UISP installation is done using an API key, which can be created in the Settings/Users section following these steps:

• Select Create new API token
• Enter a Name, PowerShellisfunRead, for example (It has a 20 characters maximum length)
• Select a Role from the dropdown menu and select Read Only
• Select Save and copy the New API Token to your clipboard using the Copy to clipboard button and save it somewhere safe.
• Exit by clicking the X in the top right.

You should now see your API token in the API tokens with your username, the scope (Read Only in our case), and when it was created.

Also, create an Admin account (PowerShellisfunAdmin, for example) by repeating the steps above and selecting the Admin role instead of the Read Only role. Also, create a Super Admin account (PowerShellisfunSuper, for example) by repeating the steps above and selecting the Super Admin role instead of the Read Only role.

Examples

Listing your devices

You can retrieve all your devices and information from UISP using this snippet below with at least an API key with Read Only access. (I changed the server URL of my VPS to x.com. Change it to your own FDQN, of course)

$token = '60b4b770-ef3d-4930-8476-dd792f4b358b'
$headers = @{
    Accept         = "application/json"
    'x-auth-token' = "$token"
}
$devices = Invoke-RestMethod -uri 'https://x.com/nms/api/v2.1/devices' -Method Get -ContentType application/json -Headers $headers
$total = foreach ($device in $devices) {
    [PSCustomObject]@{
        DisplayName     = $device.identification.displayName
        Name            = $device.identification.name
        Hostname        = $device.identification.hostname
        ipAddress       = $device.ipAddress
        Firmwareversion = $device.identification.firmwareVersion
        Model           = $device.identification.model
        ModelName       = $device.identification.modelName
    }
}

$total | Export-Csv -NoTypeInformation -Encoding UTF8 -Delimiter ';' -Path C:\Data\UISP_Devices.csv

This will export the results to c:\data\UISP_Devices.csv, which will look like this: (This is a screenshot of a small part of my devices.)

There are other identification fields you can add to the PSCustomObject, and it depends on which fields you want and if they are populated in UISP:

bridgeVersion   
category        
displayName     
firmwareVersion 
hostname        
id              
mac             
model           
modelName       
name            
platformId      
platformName    
role            
serialNumber    
site            
started         
subsystemId     
systemName      
type            
udapiVersion    
updated         
vendor          
vendorName      
wanInterfaceId  

Also, you can use these next to the identification object:

attributes     
configuration  
discovery      
enabled        
features       
firmware       
ipAddress      
ipAddressList  
latestBackup   
location    
meta           
mode           
overview       
upgrade        
uplinkDevice   

Retrieving outage information

You can retrieve information about the past outages with the snippet below, and this needs to be run with an API key with at least an Admin role API key. (I used https://x.com/nms/api-docs/#/Outages for the correct URL. Replace x.com with your FQDN)

$token = 'b828e6be-9174-4bf0-9e55-d6bd93d51767'
$headers = @{
    Accept         = "application/json"
    'x-auth-token' = "$token"
}
$outages = Invoke-RestMethod -uri 'https://x.com/nms/api/v2.1/outages?count=99&page=1&type=outage&type=unreachable' -Method Get -ContentType application/json -Headers $headers
$total = foreach ($outage in $outages.items) {
    [PSCustomObject]@{
        StartTimeStamp = $outage.startTimestamp
        EndTimeStamp   = $outage.startTimestamp
        InProgress     = $outage.inProgress
        Type           = $outage.type
        Device         = $outage.device.name
        Firmwware      = $outage.device.firmwareVersion
        Role           = $outage.device.role
        IP             = $outage.device.ip

    }
}

$total | Sort-Object StartTimeStamp | Export-Csv -NoTypeInformation -Encoding UTF8 -Delimiter ';' -Path C:\Data\UISP_Outages.csv

This will export the results to c:\data\UISP_Outages.csv and will look like this:

Checkings UISP backups

The snippet below lets you check how many backups and when they were created. You need to check this with a Super Admin API key. (I changed the server URL of my VPS to x.com. Change it to your own FDQN, of course)

$token = '22e241db-da7a-4b9d-9af3-2c117f4382ae'
$headers = @{
    Accept         = "application/json"
    'x-auth-token' = "$token"
}
$backups = Invoke-RestMethod -uri 'https://x.com/nms/api/v2.1/nms/backups' -Method Get -ContentType application/json -Headers $headers
$total = foreach ($backup in $backups) {
    [PSCustomObject]@{
        createdAt   = $backup.createdAt
        Origin      = $backup.Origin
        Compatible  = $backup.Compatible
        unmsVersion = "$($backup.unmsVersion.major).$($backup.unmsVersion.minor).$($backup.unmsVersion.patch).$($backup.unmsVersion.order)"
        Size        = "$([math]::Round($backup.Size / 1Mb, 2))Mb"
    }
}

$total | Sort-Object createdAt | Export-Csv -NoTypeInformation -Encoding UTF8 -Delimiter ';' -Path C:\Data\UISP_Backups.csv

This will export the results to c:\data\UISP_Backups.csv and will look like this:

Wrapping up

In this blog post, I showed you how to connect to the UISP software and retrieve data from it to a .csv file, but you can use it for other purposes, too. Important is that you always connect with the lowest possible API key and that you don’t leave those keys somewhere unsafe 😉

More information about the API

The API reference is here: https://x.com/nms/api-docs/ (replace x.com with your own FQDN). You can browse the different endpoints and run tests efficiently with your API key in there! The screenshot below is from the outages endpoint. I used the API-docs to get the correct syntax in the URL: