Managing Altaro VM Backup with PowerShell
Recently, I decided to try to determine if there was a way to manage Altaro VM Backup with PowerShell. I figured there must be some database, files, or something that I could at least query with PowerShell.
What I found is Altaro has a RESTful API and they have numerous PowerShell scripts for working with it. In Altaro version 7, there are 33 PowerShell scripts located in the "C:\Program Files\Altaro\Altaro Backup\Cmdlets" folder if you took the defaults during the installation, otherwise they're wherever you installed Altaro. Altaro has a blog article on their website announcing the API in March of 2016.
After taking a look at Altaro's PowerShell scripts, I decided not to use them. I started writing my own PowerShell module with functions for working with their API.
Although their API has a limitation that it only works locally on the actual Altaro VM Backup server, that doesn't mean that you can't use it with PowerShell remoting. Working remotely is always better from a manageability standpoint since using remote desktop to connect to the server only to run PowerShell on it locally defeats the whole purpose of using PowerShell.
I'll start out by storing my credentials in a variable named Cred:
1$Cred = Get-Credential
Use one-to-one remoting to access my Altaro VM Backup server:
1Enter-PSSession -ComputerName mr101 -Credential $Cred
The Altaro API service is disabled by default. Set it to start automatically and then start the service:
1Get-Service -DisplayName 'Altaro VM Backup API Service' |
2Set-Service -StartupType Automatic -PassThru |
3Start-Service -PassThru
The Start-MrAltaroSession function shown in the following code example is used to start a session
with the API on an Altaro VM Backup server:
1#Requires -Version 3.0
2function Start-MrAltaroSession {
3
4<#
5.SYNOPSIS
6 Starts a new session with the RESTful API of an Altaro VM Backup server.
7
8.DESCRIPTION
9 Start-MrAltaroSession is an advanced function that starts a new session with the RESTful API of an
10 Altaro VM Backup server. In it current interation, the Altaro RESTful API can only be used locally
11 on the Altaro VM Backup server.
12
13.PARAMETER ComputerName
14 Name of the Altaro VM Backup server. The default is localhost. Currently, the Altaro API only works
15 with localhost. $env:COMPUTERNAME or the actual computer name does not work.
16
17.PARAMETER Port
18 Port number that the Altaro VM Backup API is listening on. The default is 35113.
19
20.PARAMETER Credential
21 The credentials for connecting to the Altaro VM Backup API.
22
23.EXAMPLE
24 Start-MrAltaroSession -Credential (Get-Credential)
25
26.EXAMPLE
27 Start-MrAltaroSession -ComputerName localhost -Credential (Get-Credential)
28
29.EXAMPLE
30 Start-MrAltaroSession -ComputerName localhost -Port 35113 -Credential (Get-Credential)
31
32.INPUTS
33 None
34
35.OUTPUTS
36 PSCustomObject
37
38.NOTES
39 Author: Mike F Robbins
40 Website: http://mikefrobbins.com
41 Twitter: @mikefrobbins
42#>
43
44 [CmdletBinding()]
45 param (
46 [ValidateNotNullOrEmpty()]
47 [Alias('ServerName')]
48 [string]$ComputerName = 'localhost',
49
50 [ValidateNotNullOrEmpty()]
51 [int]$Port = 35113,
52
53 [Parameter(Mandatory)]
54 [System.Management.Automation.Credential()]$Credential
55 )
56
57 $Uri = "http://$ComputerName`:$Port/api/sessions/start"
58
59 $Body = @{
60 ServerAddress = $ComputerName
61 ServerPort = '35107'
62 Username = $Credential.UserName -replace '^.*\\'
63 Password = $Credential.GetNetworkCredential().Password
64 Domain = $Credential.UserName -replace '\\.*$'
65 } | ConvertTo-Json
66
67 try {
68 $Results = Invoke-RestMethod -Uri $uri -Method Post -ContentType 'application/json' -Body $Body
69 }
70 catch {
71 Write-Error -Message "Unable to connect to Altaro API at: $Uri"
72 }
73
74 if ($Results.Success -eq $true) {
75 [PSCustomObject]@{
76 SessionId = [guid]$Results.Data
77 }
78 }
79 elseif ($Results.Success -eq $false) {
80 Write-Error -Message "$($Results.ErrorMessage). Error Code: $($Results.ErrorCode). $($Results.ErrorAdditionalDetails)"
81 }
82}
From this point forward, I can use the Using variable scope modifier with the credentials I stored in the local variable named Cred on the remote server.
Use the Start-MrAltaroSession function to start a new session with the API:
1Start-MrAltaroSession -Credential $Using:Cred
Errors are returned as an actual error:
1Start-MrAltaroSession -Credential $Using:Cred
The Get-MrAltaroOperationStatus function is used to retrieve the status of operations that are currently running:
1#Requires -Version 3.0
2function Get-MrAltaroOperationStatus {
3
4<#
5.SYNOPSIS
6 Retrieves the status and progress for Altaro VM Backup jobs which are currently running.
7
8.DESCRIPTION
9 Get-MrAltaroOperationStatus is an advanced function that retrieves the status and progress for Altaro
10 VM Backup jobs (backups, offsite copies, restores, seed to disks) which are currently running.
11
12.PARAMETER ComputerName
13 Name of the Altaro VM Backup server. The default is localhost. Currently, the Altaro API only works
14 with localhost. $env:COMPUTERNAME or the actual computer name does not work.
15
16.PARAMETER Port
17 Port number that the Altaro VM Backup API is listening on. The default is 35113.
18
19.PARAMETER SessionId
20 The Id in the form of a GUID for the sesison created by Start-MrAltaroSession.
21
22.PARAMETER OperationId
23 The Id in the form of a GUID for the specific operation to return results for.
24
25.EXAMPLE
26 Get-MrAltaroOperationStatus -SessionId b3019809-cfbe-4ac6-93df-a24c91b5b28e
27
28.EXAMPLE
29 Get-MrAltaroOperationStatus -SessionId b3019809-cfbe-4ac6-93df-a24c91b5b28e -OperationId 1351d928-0391-4a45-8d5a-ae4b806bea66
30
31.EXAMPLE
32 Get-MrAltaroOperationStatus -ComputerName localhost -Port 35113 -SessionId b3019809-cfbe-4ac6-93df-a24c91b5b28e
33
34.INPUTS
35 Guid
36
37.OUTPUTS
38 PSCustomObject
39
40.NOTES
41 Author: Mike F Robbins
42 Website: http://mikefrobbins.com
43 Twitter: @mikefrobbins
44#>
45
46 [CmdletBinding()]
47 param (
48 [ValidateNotNullOrEmpty()]
49 [Alias('ServerName')]
50 [string]$ComputerName = 'localhost',
51
52 [ValidateNotNullOrEmpty()]
53 [int]$Port = 35113,
54
55 [Parameter(Mandatory,
56 ValueFromPipeline,
57 ValueFromPipelineByPropertyName)]
58 [guid]$SessionId,
59
60 [guid]$OperationId
61 )
62
63 PROCESS {
64 $uri = "http://$ComputerName`:$Port/api/activity/operation-status/$SessionId"
65
66 Invoke-RestMethod -Uri $uri -Method Get -ContentType 'application/json' |
67 Select-Object -ExpandProperty Statuses
68 }
69
70}
These include backups, offsite copies, restores, and seed to disks operations:
1Get-MrAltaroOperationStatus -SessionId fe0a7c65-1fab-474c-bf2f-4a2a2f8f2b89
You can also pipe Start-MrAltaroSession directly to Get-MrAltaroOperationStatus:
1Start-MrAltaroSession -Credential $Using:Cred | Get-MrAltaroOperationStatus
The Stop-MrAltaroSession function gracefully closes out of one or more sessions that were previously opened:
1#Requires -Version 3.0
2function Stop-MrAltaroSession {
3
4<#
5.SYNOPSIS
6 Stops one or more sessions with the RESTful API of an Altaro VM Backup server.
7
8.DESCRIPTION
9 Stop-MrAltaroSession is an advanced function that stops one or more sessions with the RESTful API of
10 an Altaro VM Backup server. In it current interation, the Altaro RESTful API can only be used locally
11 on the Altaro VM Backup server.
12
13.PARAMETER ComputerName
14 Name of the Altaro VM Backup server. The default is localhost. Currently, the Altaro API only works
15 with localhost. $env:COMPUTERNAME or the actual computer name does not work.
16
17.PARAMETER Port
18 Port number that the Altaro VM Backup API is listening on. The default is 35113.
19
20.PARAMETER SessionId
21 The Id in the form of a GUID for the sesison created by Start-MrAltaroSession.
22
23.EXAMPLE
24 Stop-MrAltaroSession
25
26.EXAMPLE
27 Stop-MrAltaroSession -SessionId 6d2d22ef-06df-4bb0-976b-bb6a8b3f2683
28
29.EXAMPLE
30 Stop-MrAltaroSession -ComputerName localhost -Port 35113 -SessionId 66c09e7d-e10c-4608-b9cd-d35579784e70
31
32.INPUTS
33 None
34
35.OUTPUTS
36 PSCustomObject
37
38.NOTES
39 Author: Mike F Robbins
40 Website: http://mikefrobbins.com
41 Twitter: @mikefrobbins
42#>
43
44 [CmdletBinding()]
45 param (
46 [ValidateNotNullOrEmpty()]
47 [Alias('ServerName')]
48 [string]$ComputerName = 'localhost',
49
50 [ValidateNotNullOrEmpty()]
51 [int]$Port = 35113,
52
53 [Parameter(ValueFromPipeline,
54 ValueFromPipelineByPropertyName)]
55 [guid]$SessionId
56 )
57
58 PROCESS {
59 $uri = "http://$ComputerName`:$Port/api/sessions/end"
60
61 if ($PSBoundParameters.SessionId){
62 $uri = "$uri/$SessionId"
63 }
64
65 try {
66 $Results = Invoke-RestMethod -Uri $uri -Method Post -ContentType 'application/json'
67 }
68 catch {
69 Write-Error -Message "Unable to connect to Altaro API at: $Uri"
70 }
71
72 if ($Results.Success -eq $true -and $Results.ClosedSessions.SessionToken -ne $null) {
73 foreach ($Result in $Results.ClosedSessions) {
74 [PSCustomObject]@{
75 SessionId = [guid]$Result.SessionToken
76 }
77 }
78 }
79 elseif ($Results.Success -eq $true -and $Results.ClosedSessions.SessionToken -eq $null){
80 Write-Warning -Message 'There are no open sessions.'
81 }
82 elseif ($Results.Success -eq $false) {
83 Write-Error -Message "$($Results.ErrorMessage). Error Code: $($Results.ErrorCode). $($Results.ErrorAdditionalDetails)"
84 }
85 }
86
87}
It can be used to stop a single session. If multiple sessions existed, the SessionId parameter could be specified to stop a single session.
1Stop-MrAltaroSession
By default, if multiple sessions exist, it stops all of them:
1Stop-MrAltaroSession
A warning is returned if no sessions exist:
1Stop-MrAltaroSession
The functions shown in this blog article are part of my MrAltaro PowerShell script module which can be downloaded from my Altaro repository on GitHub.
For more information about the Altaro RESTful API, see their documentation page.
µ