Unitrends PowerShell Toolkit

Last month we introduced 9.0 REST APIs and how you can use them for automation. We also announced a community project to provide Unitrends PowerShell Cmdlets that is hosted in Unitrends GitHub Repo and that you can contribute to.

In this post I am going to explain how you can use Unitrends PowerShell Cmdlets that are currently available and also how you can query any other Unitrends UEB/RS API for which we don’t provide PowerShell Cmdlets yet.

Getting started with Unitrends PowerShell Toolkit:

1. Open PowerShell Console.

2. Allow Execution of unsigned PowerShell scripts as Administrator if not already enabled.

PS> Set-ExecutionPolicy Bypass

3. Download and install

PS> iwr https://raw.githubusercontent.com/Unitrends/unitrends-pstoolkit/master/Unitrends/Install.ps1 | iex

4. Once installed everytime you want to use it, you just need to open a powershell console and import the module

Import-Module Unitrends

5. Connect to the UEB/RS using Connect-UebServer Cmdlet.

Connect-UebServer –Server ueb01 –User root –Password password

6. Start using other Unitrends PowerShell Cmdlets like Get-UebJob.

PS> Get-UebJob
Name                          type                          last_status                   status
----                          ----                          -----------                   ------
Backup Domain Controller      backup                        Success                       Idle
Backup Job                    backup                        Success                       Idle

Querying any other Unitrends UEB/RS API with Get-UebApi Cmdlet

As today the number of Cmdlets is limited but we have included a generic Get-UebApi Cmdlet that you can use to query (GET) any Unitrends RS/UEB API available in the system.

To use Get-UebApi you need to know which API you want to query. You can use two options to find out:

• Check Unitrends API Guide Document available in GitHub.
• Use Chrome DevTools (F12) and navigate to UEB UI to see all API requests.

In this sample we are going to use the second option (Chrome) to find out how to get a list of all protected assets in our Unitrends appliance:

1. Open Chrome and login into UEB/RS Satori UI.

2. Hit F12 in Chrome to Open DevTools Window.

3. Navigate to Configure -> Protected Assets in Satori UI

At the bottom of your browser you will see all requests that are invoked by Satori UI while you are browsing, you can filter by /api/ requests to filter and see only API calls and don’t get HTML, CSS, images requests.

In this sample as you see in the screenshot the API that is invoked by Satori UI to retrieve Protected Assets is “/api/assets”.

Now we can go back to our PowerShell Console and invoke that API using Get-UebApi Cmdlet.

PS> Get-UebApi -uri "/api/assets"

The first thing you realize is that this API returns only a data object, this is common on many Unitrends APIs so let’s explore this data object.

PS> (Get-UebApi -uri /api/assets).data

Now you will see you get a list of objects with all your protected assets and all their properties that is difficult to read because it contains too many information and properties and is not formatted.

Let’s retrieve only some properties that we need and format it in a table

PS> (Get-UebApi -uri /api/assets).data | Select-Object name,os_type,system_name

Let’s retrieve VMware assets only.

PS> (Get-UebApi -uri /api/assets).data| Where-Object { $_.type –eq "VMware" }| %{ $_.name }

Do you prefer to see JSON document? Just run this command and redirect to a file or copy and paste in a JSON formatter.

Get-UebApi -uri "/api/assets" | ConvertTo-Json -Depth 30

Let’s explore another different API to query backup catalog (/api/catalog).

This Catalog API returns the backup catalog and we want to filter by VMware app_type and also we want to use a PowerShell property expression to calculate the number of backups returned for each protected VM instance.

PS> (Get-UebApi -uri /api/catalog).catalog.instances|Where-Object {$_.app_type -eq "VMware"}|Select-Object database_name, system_name, @{Name="Backups";Expression={$_.backups.count}}

As you see you can query any information from RS/UEB and manipulate it to create your own reports. You can export all this to CSV using ConvertTo-Csv and then import into Excel or other tools to create advance reports or charts.

PS> (Get-UebApi -uri /api/catalog).catalog.instances|Where-Object {$_.app_type -eq "VMware"}|Select-Object database_name, system_name, @{Name="Backups";Expression={$_.backups.count}} | ConvertTo-Csv

Next Steps

In this article I have shown you simple use cases to retrieve information from Unitrends appliances but you can extend this to create powerful custom reports mixing information from different APIs and processing it with PowerShell.

In next blog post I will explore how you can create your own PowerShell Cmdlets using what we have learned today and how you can commit your Cmdlets to our GitHub repository to share them with other users.