<commit_before>﻿@{
    Layout = "~/_ContentLayout.cshtml";
}

@section headerBody {
    <h1>Installing packages on a Virtual Machine</h1>
    <p class="lead">Boxstarter can install packages on Hyper-V Virtual Machines with support for setting and restoring checkpoints. No VM configuration needed. 
}

<h3>Limitations and Prerequisites</h3>
<p>Boxstarter's Hyper-V support is limited to:</p>
<ul>
    <li>Powershell Version 3 Hyper-V Hosts and above. This is automatically installed on Windows 8, 8.1 and Server 2012 and 2012 R2. Windows Server 2008 R2 can be upgraded to Version 3 (or 4) by installing version 3 or 4 of the <a href="http://www.microsoft.com/en-us/download/details.aspx?id=34595">Windows Management Framework</a>.</li>
    <li>Microsoft's Hyper-V virtualization technology comes with Windows Server and also the Windows client operating systems 8 and 8.1 professional and enterprise. It cannot be installed on Home editions of Windows 8 or on any version of Windows 7.</li>
    <li>If Boxstarter determines that configuration is necessary for PowerShell remoting, the VHD file of the VM must be accesible and writable to the user issuing the <code>Enable-BoxstarterVM</code> command.</li>
    <li>Boxstarter's HyperV commands must be run on the Hyper-V host machine.</li>
    <li>HyperV Guests are subject to the same limitations as any other Boxstarter installation environment: Powershel v2 .net 4 and OSs Windows 7/Server 2008 R2 and higher.</li>
</ul>

<h3>Automatic configuration of Hyper-V guest instances</h3>
<p>Boxstarter will configure remoting on the Hyper-V guest if it finds that it is not enabled already. The amount of configuration depends on the environment. If web services management (WSMAN) or WMI ports are already enabled and a built in admin or domain credential is being used, Boxstarter should not need to perform any special configuration above that done by <code>Install-BoxstarterPackage</code>. Boxstrter can enable Powershell Remoing from a WMI method call. If WSMAN or WMI are not open (by default they are not enabled on client versions of windows) or if the credential being used is a local user other than the builtin administrator, Boxstarter will shut down the VM, mount its VHD, and make a couple small changes to the Windows registry to either enable WMI, enable the LocalAccountTokenFilterPolicy or both.</p>
<pre>
$cred=Get-Credential domain\username
Enable-BoxstarterVM -VMName myVM -Credential $cred
</pre>
<p>This will perform any of the configuration mentioned above if necessary and return a <code>BoxstarterConnectionConfig</code> object holding the DNS name of the guest machine and the Credential pased to the command.</p> 
<p>This object can be piped to Boxstarter's Install-BoxstarterPackage command.</p>
<pre>
$cred=Get-Credential domain\username
"myVM1","myVM2" |
  Enable-BoxstarterVM -Credential $cred | 
    Install-BoxstarterPackage -PackageName myPackage
</pre>
<p>This installs myPackage on myVM1 and myVM2 after ensuring that both are propperly configured for a remote install.</p>

<h3>Checkpoints</h3>
<p>The <code>Enable-BoxstarterVM</code> command can take a CheckpointName parameter. If this checkpoint exists, Boxstarter will restore the VM to this checkpoint before performing any action. If the checkpoint does not exist, Boxstarter will create a new Checkpoint after any configurations have been made.</p>
<p>This is particularly useful when you want to restore a machine to a known state before perfoming an installation.</p>
<pre>
$cred=Get-Credential domain\username
Enable-BoxstarterVM -VMName myVM1 -Credential $cred -CheckPointName BareOS | 
    Install-BoxstarterPackage -PackageName myPackage
</pre>
<p>This resets the VM to its BareOS state before Installing the myPackage package.</p>
<h3>What about creating New VMs with Boxstarter?</h3>
<p>I considered adding a New-BoxstarterVM command but the fact is that Microsoft's own Hyper-V PowerShell module does a fine job of making this easy. This is typically a task that is not done nearly as feequently as tearing down and reseting an existing VM so it did not seem like a feature much worth the effort. To demonstrate how you would setup a New Hyper-V VM. You could use a script like this:</p>
<pre>
New-VMSwitch -NetAdapterInterfaceDescription "Intel(R) Centrino(R) Advanced-N 6205" -Name MySwitch
New-VM -Name "myVM" -MemoryStartupBytes 1GB -SwitchName MySwitch -VHDPath "C:\Users\Matt\Downloads\Windows Server 2008 R2 Enterprise Evaluation (Full Edition).vhd"
Start-VM "myVM"
</pre>
<p>Thats pretty simple. This creates a virtual switch that binds to our network adapter. Your adapter might be named differently. Run <code>Get-NetAdapter</code> to get a list of your adapters. Then create the VM and attach it to a VHD and the switch you just created. Now you have a VM with windows server 2008 R2 connected to the internet. There are a ton of other useful commands. Run <code>get-command -Module Hyper-V</code> to see them all. They are all well documented. For example, to view the documentation on the <code>Add-VMDvdDrive</code> command, run:</p>
<pre>
Get-Help Add-VMDvdDrive -Full
</pre>
If for some reason you cannot find the Hyper-V module on your machine (its supported with windows PowerShell 4), you may need to enable the feature:
<pre>
Install-windowsfeature -name hyper-v -IncludeManagementTools
</pre>
<h3>Download a free evaluation edition Windows VHD</h3>
<p>You dont need a purchased copy of Windows or a fancy shmancy MSDN subscription to test out Boxstarter Installs on a VM. Microsoft provides evaluation copies of many of its OS versions on VHD that can be used for a limited numer of days (usually 90). You can legally reinstall a new copy when the evaluation expires. While this is unfit for a production environment, its a great way to test your boxstarter or chocolatey installs.</p>
<p>Here are links to free Windows evaluation VHDs:</p>
<ul>
    <li><a href="http://technet.microsoft.com/en-US/evalcenter/hh699156.aspx?ocid=wc-tn-wctc">Windows 8.1</a></li>
    <li><a href="http://www.microsoft.com/en-us/download/details.aspx?id=16572">Windows 2008 R2</a></li>
    <li><a href="http://technet.microsoft.com/en-us/evalcenter/dn205286.aspx">Windows 2012 R2</a></li>
</ul>

<h3>Working with remote Hyper-V hosts or other virtualization technologies</h3>
<p>Boxstarter will very soon provide support for Azure and AWS VMs. However, if you are working with any virtualization technologies that support the VHD file format, you can use the <code>Enable-BoxstarterVHD</code> command to enable WMI, LocalAccountTokenFilterPolicy and retrieve the computer name of the VM running the VHD. The VHD must be accesible and writable to the user issuing the command and it must contain the system volume (the drive with the Windows folder) of the VM.</p>
<pre>
Enable-BoxstarterVHD -VHDPath "C:\Virtual hard disks\win81diff_F2AE6535-2532-455F-8E5A-0211595221F8.avhdx"
</pre>
<p>This will mount The VHD provided in the VHDPath, enable the WMI Firewall ports and enable LocalAccountTokenFilterPolicy in the Windows registry stored in the VHD.</p>
<p>NOTE: Although The parameter is explicitly referred to as <code>VHDPath</code>, any valid VHD file extension is accepted. The above example uses a differencing disk but is valid since that is the primary hard drive of a guest VM.</p>
<h3>Troubleshooting Boxstarter VM Installs</h3>
<h4>General Connectivity</h4>
<p>Boxstarter makes a best effort attempt to test and configure your VM for remote installation. However, every environment is different and may include slightly tweaked configurations that Boxstarter cannot anticipate. Especially if you are inside a domain environment, there may be various group policies in place that edit various settings and permission levels that will cause a Boxstarter install to fail. Almost all of these scenarios can be corrected for and over time, Boxstarter should improve at compensating for these nuances.</p>

<p>The first thing to do if Boxstarter is unable to reach the vm is to run:</p>
<pre>Enable-PSRemoting -Force</pre>
<p>on the vm. This will most often put the machine in a state where it can accept remote sessions from Boxstarter.</p>
<h4>Have you lost your domain trust relationship?</h4>
<p>In a domain environment, it is possible that over time a VM may lose its trust relationship with the Domain Controller especially if you revert to a snapshot that has an expired machine password. When this happens things stop to authenticate correctly and often remote communicaion sessions are denied. It is not always obvious that this is the problem. Usually you can tell by examining the Network Adapter on the VM and it states that it is Unauthenticated. The most reliable fix for this is to Unjoin the domain and then rejoin.</p><commit_msg>Copy edit of the new Hyper-V Documentation<commit_after>﻿@{
    Layout = "~/_ContentLayout.cshtml";
}

@section headerBody {
    <h1>Installing packages on a Virtual Machine</h1>
    <p class="lead">Boxstarter can install packages on Hyper-V Virtual Machines with support for setting and restoring checkpoints. No VM configuration needed. 
}

<h3>Limitations and Prerequisites</h3>
<p>Boxstarter's Hyper-V support is limited to:</p>
<ul>
    <li>PowerShell Version 3 Hyper-V Hosts and above. This is automatically installed on Windows 8, 8.1 and Server 2012 and 2012 R2. Windows Server 2008 R2 can be upgraded to Version 3 (or 4) by installing version 3 or 4 of the <a href="http://www.microsoft.com/en-us/download/details.aspx?id=34595">Windows Management Framework</a>.</li>
    <li>Microsoft's Hyper-V virtualization technology comes with Windows Server and also the Windows client operating systems 8 and 8.1 professional and enterprise. It cannot be installed on Home editions of Windows 8 or on any version of Windows 7.</li>
    <li>If Boxstarter determines that configuration is necessary for PowerShell Remoting, the VHD file of the VM must be accessible and writable to the user issuing the <code>Enable-BoxstarterVM</code> command.</li>
    <li>Boxstarter's Hyper-V commands must be run on the Hyper-V host machine.</li>
    <li>Hyper-V Guests are subject to the same limitations as any other Boxstarter installation environment: PowerShell v2, .net 4, and OS's Windows 7/Server 2008 R2 and higher.</li>
</ul>

<h3>Automatic configuration of Hyper-V guest instances</h3>
<p>Boxstarter will configure PowerShell Remoting on the Hyper-V guest if it finds that it is not enabled already. The amount of configuration depends on the environment. If web services management (WSMAN) or WMI ports are already enabled and a built-in administrator or domain credential is being used, Boxstarter should not need to perform any special configuration above that done by <code>Install-BoxstarterPackage</code>. Boxstarter can enable PowerShell Remoting from a WMI method call. If WSMAN or WMI are not open (by default they are not enabled on client versions of windows) or if the credential being used is a local user other than the built-in administrator, Boxstarter will shut down the VM, mount its VHD, and make a couple small changes to the Windows registry to either enable WMI, enable the LocalAccountTokenFilterPolicy, or both.</p>
<pre>
$cred=Get-Credential domain\username
Enable-BoxstarterVM -VMName myVM -Credential $cred
</pre>
<p>This will perform any of the configuration mentioned above if necessary and return a <code>BoxstarterConnectionConfig</code> object holding the DNS name of the guest machine and the Credential passed to the command.</p> 
<p>This object can be piped to Boxstarter's Install-BoxstarterPackage command.</p>
<pre>
$cred=Get-Credential domain\username
"myVM1","myVM2" |
  Enable-BoxstarterVM -Credential $cred | 
    Install-BoxstarterPackage -PackageName myPackage
</pre>
<p>This installs myPackage on myVM1 and myVM2 after ensuring that both are properly configured for a remote install.</p>

<h3>Checkpoints</h3>
<p>The <code>Enable-BoxstarterVM</code> command can take a CheckpointName parameter. If this checkpoint exists, Boxstarter will restore the VM to this checkpoint before performing any action. If the checkpoint does not exist, Boxstarter will create a new Checkpoint after any configurations have been made.</p>
<p>This is particularly useful when you want to restore a machine to a known state before performing an installation.</p>
<pre>
$cred=Get-Credential domain\username
Enable-BoxstarterVM -VMName myVM1 -Credential $cred -CheckPointName BareOS | 
    Install-BoxstarterPackage -PackageName myPackage
</pre>
<p>This resets the VM to its BareOS state before Installing the myPackage package.</p>
<h3>What about creating New VMs with Boxstarter?</h3>
<p>I considered adding a New-BoxstarterVM command but the fact is that Microsoft's own Hyper-V PowerShell module does a fine job of making this easy. This is typically a task that is not done nearly as frequently as tearing down and reseting an existing VM so it did not seem like a feature much worth the effort. To demonstrate how you would setup a New Hyper-V VM. You could use a script like this:</p>
<pre>
New-VMSwitch -NetAdapterInterfaceDescription "Intel(R) Centrino(R) Advanced-N 6205" -Name MySwitch
New-VM -Name "myVM" -MemoryStartupBytes 1GB -SwitchName MySwitch -VHDPath "C:\Users\Matt\Downloads\Windows Server 2008 R2 Enterprise Evaluation (Full Edition).vhd"
Start-VM "myVM"
</pre>
<p>That's pretty simple. This creates a virtual switch that binds to our network adapter. Your adapter might be named differently. Run <code>Get-NetAdapter</code> to get a list of your adapters. Then create the VM and attach it to a VHD and the switch you just created. Now you have a VM with Windows Server 2008 R2 connected to the Internet. There are a ton of other useful commands. Run <code>Get-Command -Module Hyper-V</code> to see them all. They are all well documented. For example, to view the documentation on the <code>Add-VMDvdDrive</code> command, run:</p>
<pre>
Get-Help Add-VMDvdDrive -Full
</pre>
<p>If for some reason you cannot find the Hyper-V module on your machine (it's supported with Windows PowerShell 4), you may need to enable the feature:</p>
<pre>
Install-WindowsFeature -name hyper-v -IncludeManagementTools
</pre>
<h3>Download a free evaluation edition Windows VHD</h3>
<p>You don't need a purchased copy of Windows or a fancy shmancy MSDN subscription to test out Boxstarter Installs on a VM. Microsoft provides evaluation copies of many of its OS versions on VHD that can be used for a limited number of days (usually 90). You can legally reinstall a new copy when the evaluation expires. While this is unfit for a production environment, its a great way to test your Boxstarter or Chocolatey installs.</p>
<p>Here are links to free Windows evaluation VHDs:</p>
<ul>
    <li><a href="http://technet.microsoft.com/en-US/evalcenter/hh699156.aspx?ocid=wc-tn-wctc">Windows 8.1</a></li>
    <li><a href="http://www.microsoft.com/en-us/download/details.aspx?id=16572">Windows 2008 R2</a></li>
    <li><a href="http://technet.microsoft.com/en-us/evalcenter/dn205286.aspx">Windows 2012 R2</a></li>
</ul>

<h3>Working with remote Hyper-V hosts or other virtualization technologies</h3>
<p>Boxstarter will very soon provide support for Azure and AWS VMs. However, if you are working with any virtualization technologies that support the VHD file format, you can use the <code>Enable-BoxstarterVHD</code> command to enable WMI, LocalAccountTokenFilterPolicy and retrieve the computer name of the VM running the VHD. The VHD must be accessible and writable to the user issuing the command and it must contain the system volume (the drive with the Windows folder) of the VM.</p>
<pre>
Enable-BoxstarterVHD -VHDPath "C:\Virtual hard disks\win81diff_F2AE6535-2532-455F-8E5A-0211595221F8.avhdx"
</pre>
<p>This will mount the VHD provided in the VHDPath, enable the WMI Firewall ports and enable LocalAccountTokenFilterPolicy in the Windows registry stored in the VHD.</p>
<p>NOTE: Although The parameter is explicitly referred to as <code>VHDPath</code>, any valid VHD file extension is accepted. The above example uses a differencing disk, but is valid since that is the primary hard drive of a guest VM.</p>
<h3>Troubleshooting Boxstarter VM Installs</h3>
<h4>General Connectivity</h4>
<p>Boxstarter makes a best effort attempt to test and configure your VM for remote installation. However, every environment is different and may include slightly tweaked configurations that Boxstarter cannot anticipate. Especially if you are inside a domain environment, there may be various group policies in place that edit various settings and permission levels that will cause a Boxstarter install to fail. Almost all of these scenarios can be corrected for and over time, Boxstarter should improve at compensating for these nuances.</p>

<p>The first thing to do if Boxstarter is unable to reach the VM is to run:</p>
<pre>Enable-PSRemoting -Force</pre>
<p>on the VM. This will most often put the machine in a state where it can accept remote sessions from Boxstarter.</p>
<h4>Have you lost your domain trust relationship?</h4>
<p>In a domain environment, it is possible that over time a VM may lose its trust relationship with the Domain Controller especially if you revert to a snapshot that has an expired machine password. When this happens things stop authenticating correctly and often remote communication sessions are denied. It is not always obvious that this is the problem. Usually you can tell by examining the Network Adapter on the VM and it states that it is Unauthenticated. The most reliable fix for this is to unjoin the domain and then rejoin.</p>
{'fraction_non_alphanumeric': 0.06900062213675696, 'fraction_numerical': 0.015723092585261014, 'mean_word_length': 4.793577981651376, 'pattern_counts': {'":': 0, '<': 247, '<?xml version=': 0, '>': 247, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4591530', 'n_tokens_mistral': 5016, 'n_tokens_neox': 4649, 'n_words': 2440}