This page looks best with JavaScript enabled

Hyper-V Backup Utility

Flexible Hyper-V Backup Utility

Hyper-V Backup Utility can be downloaded from:

A demonstration video is available on my YouTube channel.

Please consider supporting my work:

  • Sign up using Patreon.
  • Support with a one-time payment using PayPal.

If you’d like to contact me, please leave a comment, send me a tweet or DM, or you can join my Discord server.

-Mike

Features and Requirements

  • It’s designed to be run on a Hyper-V host.
  • The Hyper-V host must have the Hyper-V management PowerShell modules installed.
  • A leading feature is that the utility can be used to backup VMs to a device which the Hyper-V host does not have permission to run a regular export.
  • The utility can be used to backup VMs from Hyper-V hosts in a cluster configuration.
  • The utility requires at least Windows PowerShell 5.0.
  • This utility has been tested on Windows 10, Windows Server 2019 and Windows Server 2016 (Datacenter and Core Installations) with Windows PowerShell 5.0.

7-Zip support

I’ve implemented support for 7-Zip into the script. You should be able to use any option that 7-zip supports, although currently the only options I’ve tested fully are ‘-t’ archive type, ‘-p’ password and ‘-v’ split files.

When to use the -NoPerms switch

The -NoPerms switch is intended as a workaround when used in an environment where the Hyper-V host cannot be given the required permissions to run a regular export to a remote device such as a NAS device.

Hyper-V’s export operation requires that the computer account in Active Directory have access to the location where the exports are being stored. I recommend creating an Active Directory group for the Hyper-V hosts and then giving the group the required ‘Full Control’ file and share permissions. When a NAS, such as a QNAP device is intended to be used as an export location, Hyper-V will not be able to complete the operation as the computer account will not have access to the share on the NAS. To copy all the files necessary for a complete backup, the VM must be in an offline state for the operation to be completed, so the VM will be shut down for the duration of the copy process when the -NoPerms switch is used.

Using This Script with A Hyper-V Cluster

I’ve tested the script backing up VMs running on a Hyper-V cluster and it works just as with standalone Hyper-V hosts. I recommend setting up a staggered Scheduled Task to run the script on each of the Hyper-V hosts in the cluster. The script will detect if there are any Virtual Machines with the status of ‘Running’ and perform a backup, as configured. The script can also be configured to accept a list of VMs via a TXT file, if this option is used the script will only look for the listed VMs and not any with the ‘Running’ status.

Generating A Password File

The password used for SMTP server authentication must be in an encrypted text file. To generate the password file, run the following command in PowerShell on the computer and logged in with the user that will be running the utility. When you run the command, you will be prompted for a username and password. Enter the username and password you want to use to authenticate to your SMTP server. Please note: This is only required if you need to authenticate to the SMTP server when send the log via e-mail.

1
2
$creds = Get-Credential
$creds.Password | ConvertFrom-SecureString | Set-Content c:\scripts\ps-script-pwd.txt

After running the commands, you will have a text file containing the encrypted password. When configuring the -Pwd switch enter the path and file name of this file.

Configuration

Here’s a list of all the command line switches and example configurations.

Command Line Switch Description Example
-BackupTo The path the virtual machines should be backed up to. Each VM will have its own folder inside this location. Do not add a trailing backslash. \\server\vm-backup OR E:\Backups
-List Enter the path to a txt file with a list of Hyper-V VM names to backup. If this option is not configured, all running VMs will be backed up. C:\scripts\vms.txt
-Wd The path to the working directory to use for the backup before copying it to the final backup directory. Use a directory on local fast media to improve performance. C:\temp
-NoPerms Configures the utility to shut down the running VM(s) to do the file-copy based backup instead of using the Hyper-V export function. If no list is specified and multiple VMs are running, the process will run through the VMs alphabetically. N/A
-Keep Instructs the utility to keep a specified number of days worth of backups. VM backups older than the number of days specified will be deleted. Every effort has been taken to only remove backup files or folders generated by this utility. 30
-Compress This option will create a zip file of each Hyper-V VM backup. Available disk space should be considered when using this option. N/A
-Sz Configure the utility to use 7-Zip to compress the VM backups. 7-Zip must be installed in the default location ($env:ProgramFiles) if it is not found, Windows compression will be used as a fallback. N/A
-SzOptions Use this option to configure options for 7-Zip. The switches must be comma separated and surrounded by single or double quotes. ‘-t7z,-v2G,-ppassword’
-ShortDate Configure the script to use only the Year, Month and Day in backup filenames. N/A
-NoBanner Use this option to hide the ASCII art title in the console. N/A
-L The path to output the log file to. The file name will be Hyper-V-Backup_YYYY-MM-dd_HH-mm-ss.log. Do not add a trailing \ backslash. C:\scripts\logs
-Subject The subject line for the e-mail log. Encapsulate with single or double quotes. If no subject is specified, the default of “Hyper-V Backup Utility Log” will be used. ‘Server: Notification’
-SendTo The e-mail address the log should be sent to. me@contoso.com
-From The e-mail address the log should be sent from. HyperV@contoso.com
-Smtp The DNS name or IP address of the SMTP server. smtp.live.com OR smtp.office365.com
-Port The Port that should be used for the SMTP server. If none is specified then the default of 25 will be used. 587
-User The user account to authenticate to the SMTP server. example@contoso.com
-Pwd The txt file containing the encrypted password for SMTP authentication. C:\scripts\ps-script-pwd.txt
-UseSsl Configures the utility to connect to the SMTP server using SSL. N/A

Example

1
Hyper-V-Backup.ps1 -BackupTo \\server\vm-backup -List C:\scripts\vms.txt -Wd C:\temp -Keep 30 -Compress -Sz -SzOptions '-t7z,-ppassword' -L C:\scripts\logs -Subject 'Server: Hyper-V Backup' -SendTo me@contoso.com -From hyperv@contoso.com -Smtp smtp.outlook.com -User me@contoso.com -Pwd C:\scripts\ps-script-pwd.txt -UseSsl

This example would perform a live export of all the VMs listed in the file located in C:\scripts\vms.txt and back up their files to \server\vm-backup, using C:\temp as a working directory. A .7z file for each VM folder will be created using 7-zip. Any backups older than 30 days will also be deleted. The log file will be output to C:\scripts\logs and sent via e-mail with a custom subject line.

Change Log

2021-08-10: Version 21.08.10

  • Added an option to specify the Port for SMTP communication.

2021-07-02: Version 21.07.02

  • Fixed many bugs introduced with implementing more 7-zip options. 7-zip options I’ve tested fully are ‘-t’ archive type, ‘-p’ password and ‘-v’ split files.
  • Implemented and automated a formal testing process.

2021-06-14: Version 21.06.14

  • Replaced -Sz* specific options with -SzOptions which will support any option that 7-zip supports.

2021-06-02: Version 21.06.02

  • Fixed an error where file types which are not .zip were not being moved from the working directory to the final backup location.

2021-05-30: Version 21.05.30

  • Added additional 7-Zip options. -SzSplit to split archives into configuration volumes.
  • Changed existing switches for 7-Zip options. Users must now add an additional hyphen ‘-’ for 7-Zip options. This has been done to better support features that 7-Zip supports.
  • Changed how old files are removed. Users should take extra care if they are storing non back-up files in the backup location. This has been done so that 7-Zip’s split function can be supported.

2020-07-13: Version 20.07.13

  • Added -ShortDate option. This will create backups with only the Year, Month, Day as the file name.
  • Added pass through for 7-Zip options - CPU threads to use and compression level.
  • Added proper error handling so errors are properly reported in the console, log and email.
  • Bug fixes to create folders when paths are configured without the folders existing.

2020-02-28: Version 20.02.28 ‘Artifact’

  • Fixed e-mail report extra line breaks in Outlook 365, Version 2001.
  • Config report matches design of Image Factory Utility.
  • Improved and simplified code.

2020-02-18: Version 2020.02.14 ‘Valentine’

Current known issues:

  • E-mail report has extra line breaks in Outlook 365, Version 2001.

New features:

  • Refactored code.
  • Fully backwards compatible.
  • Added option to use a working directory to stage backups before moving them to final backup location.
  • Added option to use 7-Zip for backup compression.
  • Added ASCII banner art when run in the console.
  • Added option to disable the ASCII banner art.

2019-09-04 v4.5

  • Added custom subject line for e-mail.

2019-05-26 v4.4

  • Added more feedback when the script is used interactively.

2018-06-21 v4.3

  • Added the ability to specify the VMs to be backed up using a txt file.

2018-03-04 v4.2

  • Improved logging slightly to be clearer about which VM’s previous backups are being deleted.

2018-03-03 v4.1

  • Added option to compress the VM backups to a zip file. This option will remove the original VM backup.
  • Added option to keep a configurable number of days’ worth of backups, so you can keep a history/archive of previous backups. Every effort has been taken to only remove backup files or folders generated by this utility.
  • Changed the script so that when backup is complete, the VM backup folders/zip files will be have the time and date append to them.

2018-01-15 v4.0

  • The backup script no longer creates a folder named after the Host server. The VM backups are placed in the root of the specified backup location.
  • Fixed a small issue with logging where the script completes the backup process, then states incorrectly “there are no VMs to backup”.

2018-01-12 v3.9

  • Fixed a small bug that occurred when there were no VMs to backup, the script incorrectly logged an error in exporting the VMs. It now states that that are no VMs to backup.

2018-01-12 v3.8

  • The script has been tested performing backups of Virtual Machines running on a Hyper-V cluster.
  • Minor update to documentation.

2017-10-16 v3.7

  • Changed SMTP authentication to require an encrypted password file.
  • Added instructions on how to generate an encrypted password file.

2017-10-07 v3.6

  • Added necessary information to add the script to the PowerShell Gallery.

2017-09-18 v3.5

  • Improved the log output to be easier to read.

2017-07-22 v3.4

  • Improved commenting on the code for documentation purposes.
  • Added authentication and SSL options for e-mail notification.

2017-05-20 v3.3

  • Added configuration via command line switches.
  • Added option to perform regular online export if destination allows it.

2017-04-24 Minor Update

  • Cleaned up the formatting and commented sections of the script.

2017-04-21 Minor Update

  • Added the ability to email the log file when the script completes.
Share on
Support the author with