Hyper-V Backup Utility

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:

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

If you’d like to get in touch with me please leave a comment, send me a tweet or DM, or send me a message via my contact form.

-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 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.

 

Configuration

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 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
-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

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 me@contoso.com -From hyperv@contoso.com
-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.

Change Log

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.

 

111 thoughts on “Hyper-V Backup Utility

Add yours

  1. Hello,

    I start the script via the task scheduler and want to save the exports to an external USB hard drive. And get this error message.
    2020-09-19 05:51:24 [INFO] Log started
    ************ Running with the following config *************.
    This virtual host: ……. JTHOST00.
    VMs to backup: ………..
    ……………………. jtapp
    ……………………. jtdom
    Backup directory: …….. F:\backup-jtvm\VMS.
    Working directory: ……. D:\workdir.
    Backups to keep: ……… No Config
    Logs directory: ………. D:\scripts\logs.
    E-mail log to: ……….. No Config
    E-mail log from: ……… No Config
    E-mail subject: ………. Default
    SMTP server: …………. No Config
    SMTP user: …………… No Config
    SMTP pwd file: ……….. No Config
    -UseSSL switch: ………. False.
    -NoPerms switch: ……… True.
    -ShortDate switch: ……. True.
    -Compress switch: …….. True.
    -Sz switch: ………….. True.
    7-zip threads: ……….. mmt1.
    7-zip compression: ……. mx1.

    2020-09-19 05:51:25 [INFO] Process started.
    2020-09-19 05:51:25 [INFO] Stopping VM: jtapp
    Stop-VM: error when terminating.
    In D:\Scripts\Hyper-V-Backup.ps1: 901 characters: 13
    + Stop-VM $ Vm
    + ~~~~~~~~~~~
    + CategoryInfo: NotSpecified: (:) [Stop-VM], VirtualizationExeption
    + FullyQualifiedErrorId: Unspecified, Microsoft.HyperV.PowerShell.Commands.StopVM

    Actually the VMs should be shut down. The export job starts and the VMs remain online.
    After performing the task, the working directory is empty and the directories are on the external hard drive, but there is no compressed file.
    I start the script from a batch file:
    PowerShell -ep bypass D:\Scripts\Hyper-V-Backup.ps1 -BackupTo F:\backup-jtvm\VMS -Wd D:\workdir -NoPerms -Keep 30 -Compress -Sz -SzThreads mmt8
    -SzComp mx5 -L D:\scripts\logs
    Why are the machines not shut down? Is something missing here?
    The HyperV module for remote administration is installed.
    greeting
    Andreas

    Like

Leave a Reply to Anonymous Cancel reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Create a website or blog at WordPress.com

Up ↑

%d bloggers like this: