Flexible Hyper-V Backup Utility
Hyper-V Backup Utility can also be downloaded from:
A demonstration video is available on my YouTube channel.
Please consider supporting my work:
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 PowerShell 5.0.
- This utility has been tested on Windows 10, Windows Server 2019, Windows Server 2016 and Windows Server 2012 R2 (Datacenter and Core Installations) with PowerShell 5.0.
When you should 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.
$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.
The table below shows all the command line options available with descriptions 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.||\\nas\Backups 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|
|-SzThreads||Instructs 7-Zip to use multiple threads. By default only 1 thread will be used.||mmt4|
|-SzComp||Instructs 7-Zip to use different levels of compression. By default the fastest compression will be used.||mx1 – mx9|
|-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 email@example.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|
|-User||The user account to authenticate to the SMTP firstname.lastname@example.org|
|-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|
Hyper-V-Backup.ps1 -BackupTo \\nas\vms -List C:\scripts\vms.txt -Wd E:\temp -NoPerms -Keep 30 -Compress -Sz -SzThreads mmt8 -SzComp mx5 -L C:\scripts\logs -Subject 'Server: Hyper-V Backup' -SendTo email@example.com -From firstname.lastname@example.org -Smtp smtp.outlook.com -User user -Pwd C:\foo\pwd.txt -UseSsl
This will shutdown, one at a time, all the VMs listed in the file located in C:\scripts\vms.txt and back up their files to \nas\vms, using E:\temp as a working directory. A zip file for each VM folder will be created using 7-Zip. 7-Zip will use 8 threads and medium compression. 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.
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.
- 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.
- Added custom subject line for e-mail.
- Added more feedback when the script is used interactively.
- Added the ability to specify the VMs to be backed up using a txt file.
- Improved logging slightly to be clearer about which VM’s previous backups are being deleted.
- 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.
- 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”.
- 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.
- The script has been tested performing backups of Virtual Machines running on a Hyper-V cluster.
- Minor update to documentation.
- Changed SMTP authentication to require an encrypted password file.
- Added instructions on how to generate an encrypted password file.
- Added necessary information to add the script to the PowerShell Gallery.
- Improved the log output to be easier to read.
- Improved commenting on the code for documentation purposes.
- Added authentication and SSL options for e-mail notification.
- 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.