Automating Deployment of Hyper-V based Microsoft Labs

by Dmitry Kirsanov 6. October 2012 14:22

Microsoft Certified Trainer logoThis article is about free software I made to automate the deployment of exported Hyper-V machines. More precisely – Hyper-V machines of labs for Microsoft Official Curriculums (MOC), used by students at Microsoft official training classes. It should be interesting for MCTs (i.e. Microsoft Certified Trainers) out there, whose job is to deploy labs in form of Hyper-V virtual machines, as well as for system administrators having the same duty of periodic installation of Hyper-V virtual machines. The installation procedure of a pack of Hyper-V machines could be extremely time consuming. Or should I say - used to be.

I will speak about it as about the solution for a lab deployment problem, but if you are working with other virtual machines, just think about the similarities with your scenario.

There are basically three ways to set up labs in the class:

  1. Classic. Each workstation in the class is the server, meaning it has Hyper-V server installed everywhere, which also means it has to be Microsoft Windows Server 2008 or higher.
  2. Centralized. You have a single server or server farm, where all Hyper-V machines are running. This allows you to have old and / or low-end hardware for students. You don’t pay too much for OS licenses, can use cheap hardware like computers based on Atom processor, so workstations consume less electricity. Could even use Windows PE, to get rid from licensing problem and hard drive. However, you should pray for your server to not fail, or you’ll have no labs.
  3. Cloud. Usually not an option for the training center, mainly because of its budget requirements. All Hyper-V machines are running in the private cloud, and users are connecting to such machines using web browser. In that case thin client machines could run the cheapest option and won’t require upgrades. An example of such are MSDN labs and TechNet labs.

We are going to talk about automating the first method only, since Centralized would only require to install labs once, and Cloud wouldn’t require you to do anything at all, unless you are also the administrator of the cloud.

How we usually set up the MOC Labs, the classic way

When you want to set up the lab in your class, you need to follow few steps. I’ll list them here to illustrate the areas that require automation.

Step 0. Ensure your hardware supports virtualization and it’s not blocked by BIOS, then install Windows Server 2008 or higher, download lab installation files from Microsoft. These steps don’t have to be automated, as you only do it once per machine. Other steps, however, need to be repeated each time you want to install labs, and some of them are extremely time consuming:

  1. Run every self-extractable file downloaded from Microsoft. They will be installed on c:\program files\microsoft learning\course  id.
  2. Open each sub-directory of the target course directory, and check for vmconfig.xml file. It contains links to VHD files which might or might not be on referenced locations. You have to check that each one of them exist. Usually it also has links to so called base image – a large virtual disk which is common for many courses which usually resides in separate directory. If the file doesn’t exist – you have to copy it from where you store such files.
  3. There is one batch file per each machine, which creates the symbolic links for required VHD files. You have to run all such batch files as administrator, and ensure they succeed – they have a pause command as the last one, so you’ll have to close window each time you run such batch file.
  4. You need to log into your Hyper-V manager and import each machine, one by one. That would be a short process, but you have to go through the wizard over and over again.
  5. You could end right here, but then on the first run system would ask you to restart. Not a big deal, but may cause frustration and unnecessary delay in lab execution. To avoid that, you need to run each imported machine and wait until windows operating system of the virtual machine ends booting. Then, you have to shut it down, no logging in is necessary. If you will not do that, student will be asked to restart virtual machine on the first run. For you that would mean waiting for some students. Sometimes such restart may take 5 minutes or more.
  6. In the end, you create the snapshot, so you could reset the virtual machine later, to avoid reimporting of the machine for the next student. Usually we rename such snapshot to “Starting Image”, so we can distinguish it from other snapshots.

If you are importing a set of 19 machines which consume about 60Gb in total, to set up the class of 20 machines would take a whole day. Not the most productive day of your life. For some people, the repetitive entering of commands and performing manual operations, creates a false feeling of doing something useful. But it’s not about us.


As Steve Krug said – “don’t make me think!”. Being human means doing human errors, and most errors we make is when we are following the cryptic manual and skip important step somewhere in the middle.

I only want to press one button and see everything being done for me. That’s my “business requirement” for the whole solution.

The first version of solution would require me to perform one action at each target workstation. Second version should do everything in one operation invoked from the administrator’s machine. This means that I would see all machines in real time, with all the progress and current state of deployment.

But first I needed to make sure I can deploy one set of machines by performing one operation. Say – double-click a shortcut and that’s it.


Since I would limit my actions to one double-click, and it would have to deploy all files and do all the operations from the list above, it would have to be an executable, which also contains all the files and settings. WinRAR self-extracting archive was a perfect candidate.

When you are executing the large self-extracting (SFX) archive over the network, the operation (theoretically, anyway) should perform faster, because your machine would receive compressed data over the network, and decompress them on your machine. So, if the network is the bottleneck, but the CPU of your workstation is fast enough (otherwise why would you install Hyper-V on it?), it could lead to a faster deployment process. In fact, though, the difference is not that significant.

However, Microsoft supplies it’s virtual machines as set of multiple WinRAR SFX, each of which requires accepting the EULA twice and each time it switches to secure desktop (that’s when the whole window is disabled, and you need to answer the security elevation prompt), because it requires administrative privileges. Boring and time consuming, so I have to decompress all files first, from original media (that is – files downloaded from Microsoft Official Curriculum Library, MOCL).

Introducing Hyper-Weed

Yet another crazily named solution, but that’s what you pay for free software. The Hyper-Weed (pronounced – Hyper-V) consists of two parts: the MSK (abbreviation for MOC Setup Kit) and WeedBuilder. The MSK is a small framework which has to be installed once on each Hyper-V host where you want to support automated Hyper-V machine installation. WeedBuilder is the tool to create self-extracting one-step installation packages.

MOC Setup Package (MSK)

MSK (see download link below) is an executable file, which installs few files into c:\utils directory. It also checks that your machine has .NET Framework 4.0 Client Profile, and installs it if needed (you’ll be asked to confirm that action). Also it will check for existence of 7-zip – free archive manager with exceptional compression ratio. Both packages will be downloaded and installed from official sources ( and and only if you don’t have them installed yet.

Framework, installed by MSK, consists of Hyper-V PowerShell modules, checkvmconfig utility (see below) and the hyperweed utility. Both utilities are command-line, meaning you can use them also in Windows Server Core – edition of Windows Server without the graphical user interface.

The checkvmconfig utility checks the configuration file of exported Hyper-V machine and verifies, that all mentioned virtual hard disk files (vhd) locations are valid. If files not found, the checkvmconfig will look for them at local hard drive and once found – create a symbolic link at the path found in configuration file.
If the file is not found, utility will look for it on file shares that you specify in checkvmconfig.config file. This is very handy when your machine requires base files, which may only be found somewhere on your file server. In that case, utility will copy them to local machine at location specified in exported virtual machine config file. Important to note, that virtual hard drives stored on file server may be compressed using 7-zip, so instead of base.vhd you may have file base.7z, and utility will find and decompress it automatically, when needed, so it will save you gigabytes of space on your file server.

Hyperweed utility is reading the script, generated by WeedBuilder. A very simple script that you can create manually. It supports just about six commands and automates the installation and maintenance of Hyper-V machines. Hyperweed translates that script into PowerShell and runs it. The reason why the WeedBuilder generates intermediate text file instead of .ps1 file is the fact that different Hyper-V objects may be required for different versions of Windows, so different versions of MSK will be needed to successfully install the same virtual machine, depending from environment.

Hyperweed script is a normal text file with any file extension (by default – “.vmsd”). The script file is provided as the only command line argument for hyperweed.exe.

Hyperweed script commands

There are just 6 commands at the moment, they are very simple:

ShutdownAll – gracefully shuts down all running virtual machines on Hyper-V server.

Shutdown [Machine Name] – shuts down the specified virtual machine. However, instead of the name you can use mask. Like 6292* will shut down all machines whose names begin with 6292. ShutdownAll is equal to “Shutdown *”.

Check [Machine Name] – will start specified virtual machine, wait until the heartbeat (that is – when it fully loads the guest operating system) and gracefully shuts down the virtual machine.

Import [Path to virtual machine directory] – will import virtual machine(s) from specified directory.

Sleep [seconds] – will pause script execution for specified amount of seconds. If the parameter is omitted (i.e. you just type “Sleep”), the time is 60 seconds.

Snapshot [Virtual Machine name] [Snapshot name] – will create snapshot for specified virtual machine, which could be the mask of the virtual machine name, and optionally give it a name. If you want to use long snapshot name, you can put it into quote marks (“). If you don’t specify the snapshot name, it will be set to “Starting Image”.

As you can see, very simple.

HyperWeed Builder utility

HyperWeed BuilderHyperweed Builder is not part of MSK, as you will only need it on your workstation, when transforming Microsoft’s official labs (or any of your custom labs) into hyperweed setup file.

It allows you to prepare the script for the hyperweed utility, as well as the batch file that will execute automatically after the decompression of all required files. You’ll need to specify the directory with all original Hyper-V machines, place to save the WinRAR SFX files, name of the SFX file and the unique mask for all names of your machines.

After you press the “Start” button, you’ll see two files opened for editing:


First will be the VMSD file. Or “Virtual Machine Setup Definition”. As you can see in this screen shot, pretty simple commands and layout.


Second will be the Windows batch file that will be executed after all files will be decompressed. You can edit both files, if needed, and save/close. They will be automatically included in automated setup file.

So, that’s what I do first, when I need to prepare the Perfect Virtual Machine:

Step 1. Decompress original virtual machines

After you finished downloading the original files, run each EXE file you’ve got and agree to the EULA. Make sure you read it thoroughly each time. By default, it will be decompressed to c:\program files\microsoft learning.

The difference with the step 1 from the before mentioned classic way of set up, is that you only do it once on your workstation. You can do it on ordinary Windows workstation without Hyper-V, as all you need to do is to decompress files.

Step 2. Run the HyperWeed Builder

In this step you’ll need to run the HyperWeed Builder utility just as described previously. You’ll need to check whether the generated VMSD and BAT files are what you need, or you can make changes before proceeding. To ensure that all changes are saved, close both Notepads before proceeding.

Ensure that directory names and virtual machine names are correct in both BAT and VMSD. There may be situation when it’s not so – all utilities are in BETA stage. When everything looks ok, close Notepads and proceed with HyperWeed Builder. When it will say “Done!” and WinRAR will start creating your SFX archive, you can close the utility.

Step 3. Test!

After your multi-volume SFX is completed, make sure you test it on another computer, where Hyper-V is installed, but these virtual machines are not. To test virtual machine, install the MSK package first, and then run the first volume of the WinRAR SFX archive of your lab, produced by HyperWeed Builder.

By the way, ensure that all configuration files (.config) of two utilities from MSK package are pointing to the right locations. Such applications are hyperweed.exe and checkvmconfig.exe, and they are installed into c:\utils by default. So the configuration file names are hyperweed.exe.config and checkvmconfig.exe.config. They are simple XML files, so you can edit them using any XML editor, even Notepad.

Demonstration of Automatic Virtual Lab installation

Update: Important note: as many of you noticed, but I forgot to mention previously, in all workstations where you’ve set up the MSK package, in order for automatic setup to run, you’ll need to set up the permissive PowerShell policy. Here is an article about PowerShell security, i.e. how to do it. You can either do it by running a command, or by setting it up through Active Directory group policy (GPO). Both methods are described in the article.


MOC Setup Kit (MSK) package: (1.12 mb)


WeedBuilder utility (requires WinRAR to create SFX packages): (9.36 kb)

blog comments powered by Disqus