I’m currently in the process of adding a Virtualization module to my Boxstarter project. This post is part of a three part series covering some of the technicalities involved. Although these posts will document how Boxstarter provisions a Windows VM, I think that there will be information covered to accommodate a wide range of scenarios whether you are interested in using Boxstarter or not.
The Boxstarter Scenario
Boxstarter is a set of Powershell modules (or you can simply invoke from a URL) that can deploy a single application or standup a complete environment from a script leveraging Chocolatey and Nuget packaging technologies. Its target scenario is to bring a Windows machine from bare OS to an environment that is fully patched and has everything you need to get stuff done. Yes, there are lots of cool solutions that can do this at enterprise scale but Boxstarter is designed to be light weight and very simple. It can perform this provisioning on a physical machine but what about VMs?
You can of course log on to a VM and use Boxstarter just as you would on any physical machine, but I want to eliminate the need to have to setup network settings and manually RDP or use a Hyper-V console to connect to the VM. Deploying a Boxstarter Install to a VM should be just as simple as any other environment.
How will Boxstarter provision a VM without the need to manually prepare it
Here is the basic flow:
- Inject a script into a VHD that will run under the local machine account with administrative privileges on boot. This script will add a firewall rule and edit the Local Account Token Filter Policy.
- Use PSEXEC to invoke another script from a user account that will enable powershell Remoting on the VM with credssp authentication so that your credentials in the remote session can be used to access other remote resources from the VM.
- Use powershell remoting to Invoke a Boxstarter package from the VM Host but that will run on the VM Guest.
- Wrap all of this up into a single, simple command. that can be extended to be VM Vendor agnostic but will work with Hyper-V and Windows Azure VMs out of the box.
Ideally, this could even be leveraged to create a Vagrant Provisioner.
This post will cover the zeroth point above. The use cases of plugging a startup script right into a VHD span well beyond Boxstarter and the means of doing it is not particularly difficult but it did take me a while to figure out how to get it done right to accommodate both simple workstation environments as well as Domain topologies.
Requirements on the Host and Guest
The Goal is that this should work on any “vanilla” bare OS guest install with access to the internet and no “special” networking configuration. No Firewall tweaking, no need to enable powershell remoting on the host or guest and no installation of software on the guest beyond the operating system. That said, the following are required:
- The VM guest must be able to access the internet unless your boxstarter package installs everything from a local source.
- The Host must be running at least Powershell v.3 and have the Hyper-V module available.
- The Guest must be running windows 7, 8, server 2008 R2 or server 2012.
- The VHD where the script is injected must contain the system volume of the VM (windows\system32).
The Script Script (the script that installs the script)
The script lives in the Boxstarter.VirtualMachine module and can be called like so:
$vhd=Get-VMHardDiskDrive -VMName "MyVMName"Add-VHDStartupScript $vhd.Path -FilesToCopy "c:\myFiles\file.ps1","..\MyOtherFiles" { $here = Split-Path -Parent $MyInvocation.MyCommand.Path . "$here\file.ps1"}
This will take the VHD used by the VM on the host named MyVMName, the file c:\myfiles\file.ps1 as well as all files in ..\MyOtherFiles will be copied to the VHD. Furthermore, the script block above will be stored in a file in the same directory as the copied files. A local Group Policy will be added to the Registry stored in the VHD that will call the above script when the VM next boots. To be clear, the script runs at boot time and not login time so that no separate login is necessary to kick things off. The script will run under the local machine account.
Validate and Mount the VHD
function Add-VHDStartupScript {[CmdletBinding()]param( [Parameter(Position=0,Mandatory=$true)] [ValidateScript({Test-Path $_})] [ValidatePattern("\.(a)?vhd(x)?$")] [string]$VHDPath, [Parameter(Position=1,Mandatory=$true)] [ScriptBlock]$Script, [Parameter(Position=2,Mandatory=$false)] [ValidateScript({ $_ | % {Test-Path $_} })] [string[]]$FilesToCopy = @())if((Get-ItemProperty $VHDPath -Name IsReadOnly).IsReadOnly){ throw New-Object -TypeName InvalidOperationException ` -ArgumentList "The VHD is Read-Only"} $volume=mount-vhd $VHDPath -Passthru | get-disk | Get-Partition | Get-Volumetry{ Get-PSDrive | Out-Null $winVolume = $volume | ? { Test-Path "$($_.DriveLetter):\windows\System32\config" } if($winVolume -eq $null){ throw New-Object -TypeName InvalidOperationException ` -ArgumentList "The VHD does not contain system volume" }
In the beginning of the script we validate the user input and Mount the VHD. Pretty straight forward stuff.
Copy files and create startup script file
$TargetScriptDirectory = "Boxstarter.Startup"mkdir "$($winVolume.DriveLetter):\$targetScriptDirectory" -Force | out-nullNew-Item "$($winVolume.DriveLetter):\$targetScriptDirectory\startup.bat" -Type File ` -Value "@echo off`r`npowershell -ExecutionPolicy Bypass -NoProfile -File `"%~dp0startup.ps1`""` -force | out-nullNew-Item "$($winVolume.DriveLetter):\$targetScriptDirectory\startup.ps1" -Type File ` -Value $script.ToString() -force | out-nullForEach($file in $FilesToCopy){ Copy-Item $file "$($winVolume.DriveLetter):\$targetScriptDirectory" -Force}
Here we copy the files provided in the FilesToCopy parameter and create a powershell file to hold the script in the script block and a batch file that will invoke the powershell file.
Load the registry hive in the VHD
reg load HKLM\VHDSYS "$($winVolume.DriveLetter):\windows\system32\config\software" | out-null
This takes the file in the VHD that contains HKLM\Software, which is where the computer startup group policies reside and Loads its keys into a new hive referencable from HKLM:\VHDSYS. Now we can query and modify the values in the registry as easily as we can any of our local registry information.
Add the Group Policy
Now that the VHD Registry is loaded, we need to add a Local Group Policy that will invoke our startup.bat file upon boot. This is a bit involved to account for various scenarios such as:
- What if you already have different startup scripts
- What if you have already have added a startup script and do not want to add a duplicate
- What if you have one or more domain group policies
To try and keep things at least somewhat tidy, we will place this logic in a separate function:
function Get-RegFile { $regFileTemplate = "$($boxstarter.BaseDir)\boxstarter.VirtualMachine\startupScript.reg" $startupRegFile = "$env:Temp\startupScript.reg" $policyKey = "HKLM:\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy" $scriptNum=0 $localGPONum=0 if(Test-Path "$policyKey\Scripts\Startup\0\0"){ $localGPO = Get-ChildItem "$policyKey\Scripts\Startup" | ? { (GCI -path $_.PSPath -Name DisplayName).DisplayName -eq "Local Group Policy" } if($localGPO -ne $null) { $localGPONum = $localGPO.PSChildName $localGPO=$null #free the key for GC so it can be unloaded } else{ Shift-OtherGPOs "$policyKey\Scripts\Startup" Shift-OtherGPOs "$policyKey\State\Machine\Scripts\Startup" } if(test-path "$policyKey\Scripts\Startup\$localGPONum"){ $scriptDirs = Get-ChildItem "$policyKey\Scripts\Startup\$localGPONum" $existingScriptDir = $scriptDirs | ? { (Get-ItemProperty -path $_.PSPath -Name Script).Script ` -like "*\Boxstarter.Startup\startup.bat" } if($existingScriptDir -eq $null){ [int]$scriptNum = $scriptDirs[-1].PSChildName $scriptNum += 1 } else { $scriptNum = $existingScriptDir.PSChildName $existingScriptDir = $null #free the key for GC so it can be unloaded } } $scriptDirs=$null } (Get-Content $regFileTemplate) | % { $_ -Replace "\\0\\0", "\$localGPONum\$scriptNum" } | Set-Content $startupRegFile -force return $startupRegFile}
function Shift-OtherGPOs($parentPath){ Get-ChildItem $parentPath | Sort-Object -Descending | % { [int]$num = $_.PSChildName $oldName = $_.Name.Replace("HKEY_LOCAL_MACHINE","HKLM:") [string]$newName = "$($num+1)" try {Rename-Item -Path $oldName -NewName $newName} catch [System.InvalidCastException] { #possible powershell bug when renaming reg keys that are numeric #the key is copied but the old key remains Remove-Item $oldName -Recurse -force } }}
A couple things to note here. The script Group Policies appear to be mirrored at both:
- HKLM:\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\State\Machine\Scripts\Startup
- HKLM:\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\Scripts\Startup
I honestly do not know why or what the significance is of the different locations. These are just the keys I saw that were affected when I manually played with creating startup scripts inside GPEDIT.MSC.
The Script keys maintain the following subkey structure:
\Scripts\Startup\{policy node}\{script node}
The policy and script nodes are each simple integers starting at 0 and increment for each additional policy scope or script. So a machine with a Local policy containing 1 script and a domain policy containing 2 scripts would look like:
\Scripts\Startup\0\0 – Local policy script
\Scripts\Startup\1\0 – First domain Policy script
\Scripts\Startup\1\1 – Second domain Policy script
From what I could tell in my experimentation, the Local Policy always occupied position 0.
Here are some surprising and unintuitive findings to be aware of:
- When you are done with the registry you will need to unload it just as we loaded it in order to free up the file. That is not surprising. What is surprising is that if you save any keys to a variable as you are navigating its values, you will need to dereference those variables. It was fun in VB6 and it is still fun today! To add icing to this cake, you also need to do the thing that you should really never do: call GC::Collect() before unloading. Yep, that’s right. Unless of coarse you like Access Exceptions.
- There seems to be a bug in the powershell registry provider when renaming keys that have a numeric value. Doing so raises a invalid cast exception. It also goes ahead and creates the renamed key but it does not delete the old name. This is why I delete it inside of the catch block.
The call to the above Get-RegFile function and the surrounding import code looks like:
reg load HKLM\VHDSYS "$($winVolume.DriveLetter):\windows\system32\config\software" | out-null$startupRegFile = Get-RegFilereg import $startupRegFile 2>&1 | out-nullRemove-Item $startupRegFile -force
We use the reg command to import the temp file with the altered template and then dispose of the temp file.
The registry import template
I found it easiest to create a .reg file containing all of the registry modifications instead of using the powershell registry provider to individually modify the tree. I simply needed to determine the correct policy and script nodes and then inject those into the template. Here is the template:
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\State\Machine\Scripts]
[HKEY_LOCAL_MACHINE\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\State\Machine\Scripts\Shutdown]
[HKEY_LOCAL_MACHINE\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\State\Machine\Scripts\Startup]
[HKEY_LOCAL_MACHINE\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\State\Machine\Scripts\Startup\0]"GPO-ID"="LocalGPO""SOM-ID"="Local""FileSysPath"="%SystemRoot%\\System32\\GroupPolicy\\Machine""DisplayName"="Local Group Policy""GPOName"="Local Group Policy""PSScriptOrder"=dword:00000001
[HKEY_LOCAL_MACHINE\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\State\Machine\Scripts\Startup\0\0]"Script"="%SystemDrive%\\Boxstarter.Startup\\startup.bat""Parameters"="""ExecTime"=hex(b):00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00
[HKEY_LOCAL_MACHINE\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\Scripts]
[HKEY_LOCAL_MACHINE\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\Scripts\Shutdown]
[HKEY_LOCAL_MACHINE\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\Scripts\Startup]
[HKEY_LOCAL_MACHINE\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\Scripts\Startup\0]"GPO-ID"="LocalGPO""SOM-ID"="Local""FileSysPath"="%SystemRoot%\\System32\\GroupPolicy\\Machine""DisplayName"="Local Group Policy""GPOName"="Local Group Policy""PSScriptOrder"=dword:00000001
[HKEY_LOCAL_MACHINE\VHDSYS\Microsoft\Windows\CurrentVersion\Group Policy\Scripts\Startup\0\0]"Script"="%SystemDrive%\\Boxstarter.Startup\\startup.bat""Parameters"="""IsPowershell"=dword:00000000"ExecTime"=hex(b):00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00
Cleaning up
Finally, we unload the registry hive and dismount the VHD:
}finally{ [GC]::Collect() reg unload HKLM\VHDSYS 2>&1 | out-null Dismount-VHD $VHDPath}
Again as noted before, we have the unattractive GC Collect. If anyone discovers a way to avoid this please comment but I was not able to find any other way around this. Failing to call Collect results in an Access Exception when unloading the registry. This is only the case if you have used the powershell registry provider to navigate the loaded hive. Also as noted before, if you have referenced any keys in a variable, you must deallocate those variables before the call to GC::Collect().
Reboot a VM attached to the VHD and see the script run
That’s it. Now you can reboot a VM attached to this VHD and its script will execute under the local machine account’s credentials with administrative privileges. Since the VHD format is supported by almost all of the major Virtualization vendors, you should be able to leverage this script on most virtualization platforms.
Next: Enable Powershell Remoting
The next post will explore how to use this script to enable powershell remoting on a VM guest. It is not enough to simply have the script enable remoting since remoting must be enabled by a user account. I’ll show you the approach I found that works to set that up.
Today I released Boxstarter v2.1.0 which includes support for piping multiple machines to the Install-BoxstarterPackage command and much improved options for receiving output on both the standard output pipeline as well as the host console. This release also adds a few bug fixes and some “Fit and Finish” details for remote installs.
