Data Protection for Microsoft Hyper-V cmdlet examples

Examples of Data Protection for Microsoft Hyper-V cmdlets are provided to help you protect your Hyper-V virtual machines (VMs).

Before you use the cmdlets, ensure that you complete the steps in Preparing to use PowerShell cmdlets with Data Protection for Microsoft Hyper-V.

Examples are provided for commonly used Data Protection for Microsoft Hyper-V tasks.

Tips:
  • Each cmdlet provides parameters. To view the parameters, issue the following help command:
    help cmdlet_name -ShowWindow
  • Online help is available for the cmdlets. For more information, see Getting help information for PowerShell cmdlets.
  • Unless stated otherwise in the examples, user_name specifies the account that you use to log in to the computer where Data Protection for Microsoft Hyper-V is installed. computer_name specifies the server where Data Protection for Microsoft Hyper-V is installed.

Examples

Example 1: Back up one or more VMs

Run an incremental-forever incremental backup of one or more VMs.

$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred
$vmList = @("vm1","vm2")
$task = Backup-DpHvVm -Session $session -VmName $vmList -mode IFINCREMENTAL
$taskInfo = Get-DpHvTask -Session $session -TaskId $task.taskId
while ("running" -eq $taskInfo.taskState) {
    start-sleep -seconds 30
    $taskInfo = Get-DpHvTask -Session $session -TaskId $task.taskId
    if ($taskInfo.hasMoreData) {
        $results = Receive-DpHvTask -Session $session -TaskId $task.taskId
        write-verbose -verbose ("Started {0} Duration {1:g} Transferred `
            {2:N2} MB" -f $results.startTime, ((Get-Date)-$results.startTime),`
            ($results.totalBytesTransferred/1MB))
    }
}

$results = Receive-DpHvTask -Session $session -TaskId $task.taskId
$results

Remove-DpHvSession -Session $session

This example starts a PowerShell cmdlet session with Data Protection for Microsoft Hyper-V, backs up the VMs, queries the VM backup, monitors the backup job, and ends the session when the backup is completed.

Example 2: Query a VM backup

Query the IBM Spectrum Protect™ server file space and show general information about all VM backups.

$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred
$bks = Get-DpHvBackup -Session $session
$bks
Remove-DpHvSession -Session $session

Example 3: Verify whether a Hyper-V host is configured for Data Protection for Microsoft Hyper-V operations

$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred
Get-DpHvHostConfiguration -Session $session
Remove-DpHvSession -Session $session

Example 4: Store IBM Spectrum Protect server connection information on the Hyper-V host and verify the connection

$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred
Set-ServerConnection -Session $session -SPServerName server_name -SPAdmin `
  admin_name -SPAdminPwd admin_password -SPServerSSLPort port
Remove-DpHvSession -Session $session

Example 5: Display the policy information on the IBM Spectrum Protect server

Display information such as the domain name, default management class, description, and the duration of backup and archive retention:
$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred
Get-DpHvPolicyDomain -Session $session
Remove-DpHvSession -Session $session

Example 6: Configure a Hyper-V host for Data Protection for Microsoft Hyper-V operations

The following example configures a Hyper-V host by completing the following tasks:
  • Register the target node (cluster node).
  • Register the data mover node and configure it for backup operations (configure the options file, and create the client acceptor and scheduler services).
  • Configure the file restore environment if requested (register the Windows and Linux mount proxy nodes, and create the options file and client acceptor services). If the file restore feature is enabled, the file restore credential must be the domain user and password.
$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred
Set-ServerConnection -Session $session -SPServerName server_name -SPAdmin `
  admin_name -SPAdminPwd admin_password -SPServerSSLPort port
$nodesList = @(New-DpHvNodeInfo -NodeName node_name -NodeType node_type)
Set-DpHvHostConfiguration -Session $session -PolicyDomain policy_domain_name `
  -RegisterTargetNode -TargetNode target_node -NodeList $nodesList -EnableFR `
  -FRDomainUser domain_name\user_name -FRDomainPwd password
Remove-DpHvSession -Session $session

Example 7: Show the VM inventory on the Hyper-V host

$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred
$vms = Get-DpHvVm -Session $session
$vms
Remove-DpHvSession -Session $session

Example 8: Show the backup status of VMs on a host or cluster

The following example returns information about the last VM backups on a host or cluster. 

$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred
$lastBackups = Get-DpHvLastSuccessfulBackup -Session $session
$vmName = $lastBackups | select -first 1 -ExpandProperty name
$vmBackupHistory = Get-DpHvVMBackupHistory -Session $session -vmName $vmName
$vmBackupHistory
Remove-DpHvSession -Session $session

Example 9: Set the at-risk policy for a VM

The at-risk policy determines that a VM is at risk of being unprotected if a scheduled backup operation did not occur within a specified time interval.

The first half of the following example displays at-risk information for all VMs that have been backed up. The second half of the example updates the at-risk value for all VMs that begin with "SQL" to 12 hours. 

$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred

$lastBackups = Get-DpHvLastSuccessfulBackup -Session $session

# 1 - display the current at risk value for all vms

$i = 0
$atRiskList = @()
foreach ($backup in $lastBackups) {
  $activity = "Checking at risk value for {0}" -f $backup.name
  Write-Progress -activity $activity -status "Progress:" -percentcomplete `
    ($i++/$lastBackups.count*100)
  $atRisk = Get-DpHvVmAtRisk -session $session -VmName $backup.name
  $atRiskList += [pscustomobject]@{VM=$backup.name;AtRiskType=`
    $atRisk.AtRiskType;AtRiskInterval=$atRisk.AtRiskInterval}
}
$atRiskList | Out-GridView -Title "VM Risk Status" -PassThru

# 2 - set the at-risk value for all VMS that begin with SQL to a custom interval 
# of 12 hours

$sqlVms = $lastBackups | where name -like "sql*"
$fsList = @()
foreach ($vm in $sqlVms) {
   $fsList += New-DpHvFsInfo -vmName $vm.Name -fsId $vm.FileSpaceId
}
Set-DpHvVmAtRisk -session $session -AtRiskType CUSTOM -AtRiskInterval 12 `
   -FsList $fsList

Remove-DpHvSession -Session $sess

Example 10: Show the history of schedule runs

The following example displays a summary of scheduled activity followed by the details of the most current scheduled activity.

$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred

$schedHistory = Get-DpHvScheduleHistory -Session $session
$sh = $schedHistory | Sort-Object actualstarttime -Descending | Select-Object `
  -First 1
$schedHistoryDetail = Get-DpHvScheduleHistoryDetail -Session $session -ScheduleName 
  $sh.Name -StartTime $sh.ActualStartTime -EndTime $sh.EndTime -NodeList `
    $sh.NodeList

#"Schedule History Summary"
$schedHistory |
    select actualstarttime,name,status,vmsucceeded,vmfailures,duration,nodelist | `
      sort actualstarttime -desc | ft -AutoSize

#"Details of most recent scheduled activity"
$schedHistoryDetail | 
    select starttime,datamover,targetnode,name,status,duration,datatransmitted,`
    backuptype| ft -AutoSize

Remove-DpHvSession -Session $session

Example 11: Associate a schedule with a data mover on a host or cluster

You can verify a schedule association by running the QUERY ASSOCIATION command on the IBM Spectrum Protect server.

$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred

# Get a list of schedules from the IBM Spectrum Protect server
$scheduleList = Get-DpHvBackupSchedule -Session $session
$scheduleList | format-table -autosize

# Associate the schedule with the data mover node
Set-DpHvBackupSchedule -Session $sess -ScheduleName "sched0" -Operation define `
  -DmNodesList hyperv1_HV_DM

# Remove the schedule association
Set-DpHvBackupSchedule -Session $sess -ScheduleName "sched0" -Operation remove `
  -DmNodesList hyperv1_HV_DM

Remove-DpHvSession -Session $sess

Example 12: Restore one or more VMs

Restore multiple VMs by referencing the backupIDs and restore them with new names and new restore destinations.

$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred

# Restore a single VM with default parameters
$task = Restore-DpHvVm -Session $session -vmname "vm1"
$taskInfo = Get-DpHvTask -Session $session -TaskId $task.taskId
while ("running" -eq $taskInfo.taskState) {
    start-sleep -seconds 30
    $taskInfo = Get-DpHvTask -Session $session -TaskId $task.taskId
    if ($taskInfo.hasMoreData) {
        $results = Receive-DpHvTask -Session $session -TaskId $task.taskId
        write-verbose -verbose ("Started {0} Duration {1:g} Transferred `
            {2:N2} MB" -f $results.startTime, ((Get-Date)-$results.startTime),`
            ($results.totalBytesTransferred/1MB))
    }
}

$results = Receive-DpHvTask -Session $session -TaskId $task.taskId
$results

# restore multiple vms
$task = Restore-DpHvVm -Session $session -vmname vm1,vm2 -backupId 111111,222222 `
 -newVmName vm1_restored,vm2_restored -targethPath c:\restored,c:\restored
$taskInfo = Get-DpHvTask -Session $session -TaskId $task.taskId
while ("running" -eq $taskInfo.taskState) {
    start-sleep -seconds 30
    $taskInfo = Get-DpHvTask -Session $session -TaskId $task.taskId
    if ($taskInfo.hasMoreData) {
        $results = Receive-DpHvTask -Session $session -TaskId $task.taskId
        write-verbose -verbose ("Started {0} Duration {1:g} Transferred `
            {2:N2} MB" -f $results.startTime, ((Get-Date)-$results.startTime),`
            ($results.totalBytesTransferred/1MB))
    }
}
$results = Receive-DpHvTask -Session $session -taskId $task.taskId
$results

# Get the restore history of VMs
$vmRestoreHistory = Get-DpHvVmRestoreTaskHistory -Session $session
$vmRestoreHistory

Remove-DpHvSession -Session $session

Example 13: Verify the configuration of Data Protection for Microsoft Hyper-V

After you run the configuration wizard, you can view the following configuration information by using the Test-DpHvConfiguration cmdlet:
  • Information about the default data mover node such as the computer name, operating system, and location of the error log
  • Information about the default mount proxy nodes such as the computer name, operating system, location of the error log, the state of the recovery agent, and the iSCSI status of the mount proxy nodes
$cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred

$out1 = Test-DpHvConfiguration -session $session -nodetype DMNODE
$out2 = Test-DpHvConfiguration -session $session -nodetype MPNODE

Remove-DpHvSession -Session $session

Example 14: Verify the integrity of a VM backup by running cmdlets

After you back up a VM, you can verify the integrity of the VM backup by running instant access operations. You can automate the verification process by using the InstantAccess parameters in the Restore-DpHvVm cmdlet.

The following examples show the steps for verifying the integrity of a backup image for the VM named Ganymede.

  1. Verify that the backup image of the VM named Ganymede can be used for restore operations. Run the following cmdlet to prepare a VM named Ganymede_verify for instant access operations and to automatically power on the new instant access VM.
    $cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred

$vmName = "Ganymede"
$newVmName = "Ganymede_verify"
$restoreType = "InstantAccess"
$TargetPath = "D:\SSD1\RecoveryAgent\mount"

Restore-DpHvVm -Session $session -VmName $vmName -NewVmName $newVmName `
  -TargetPath $targetPath -restoreType $restoreType -AutoStart

Remove-DpHvSession -Session $session
    Important: If the VM that you are restoring is using a static IP address, a network IP address conflict will occur between the original VM and the temporary VM. To avoid this conflict, change the IP address of the temporary instant access VM after the VM is created.
  2. To ensure that the VM Ganymede is running in instant access mode, run the Get-DpHvIaVm cmdlet to query the IBM Spectrum Protect server for instant access VMs.
    $cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred

Get-DpHvIaVm -VmName Ganymede -Session $session

Remove-DpHvSession -Session $session
  3. Run a verification tool on the instant access VM named Ganymede_verify to verify that the backup image can be restored.

    To verify the integrity of the disks and data, use a utility such as chkdsk, or a utility or application of your choice, to verify the virtual disks and data. If the temporary VM passes the integrity checks, you can remove the temporary resources that were created to support the instant access restore operation.

  4. Remove the instant access VM named Ganymede_verify by running the following cmdlet:
    $cred = Get-Credential -Message "Enter credentials" -UserName user_name
$session = New-DpHvSession -ComputerName computer_name -Credential $cred

$vmName = "Ganymede"
$newVmName = "Ganymede_verify"
$restoreType = "VmCleanup"
$TargetPath = "D:\SSD1\RecoveryAgent\mount"

Restore-DpHvVm -Session $session -VmName $vmName -NewVmName $newVmName `
  -TargetPath $targetPath -restoreType $restoreType

Remove-DpHvSession -Session $session
Related reference:
PowerShell cmdlets for Data Protection for Microsoft Hyper-V