Virtual Machine Manager2008R2 Scripting GuideMicrosoft CorporationPublished: April 29, 2010FeedbackSend suggestions and comments about this document to . Please include the published date of the guide with your feedback.The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication. This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. 2010 Microsoft Corporation. All rights reserved.Microsoft, ActiveDirectory, Excel, Hyper-V, SQLServer, Windows, WindowsPowerShell, WindowsServer, and WindowsVista are trademarks of the Microsoft group of companies.All other trademarks are property of their respective owners.Revision HistoryRelease DateChangesSeptember 11, 2009Initial release of this documentation on the Microsoft Download CenterOctober 8, 2009Added new script CheckForPendingReboot.ps1November 19, 2009Added Working with Virtual Machine Manager Properties and MethodsDecember 10, 2009Added new script LoadBalanceVMsInCluster.ps1January 7, 2010Added Command PrecedenceFebruary 4, 2010Updated script LoadBalanceVMsInCluster.ps1April 29, 2010Added RemoveMissingVMs and SaveAndRestoreVMMMetadataContentsDisclaimer7Whats New in VMM 2008 R2 Scripting7Introduction to Scripting in Virtual Machine Manager12About Windows PowerShell for Virtual Machine Manager12Managing Objects in Virtual Machine Manager15Working with Virtual Machine Manager Properties and Methods19Using the VMM Cmdlets21Command Precedence21Using Cmdlet Help23Converting Cmdlet Help Examples into Scripts28Connecting to the Virtual Machine Manager Server29Running Scripts30Providing User Credentials in a Script33Creating and Modifying a Script from a VMM Wizard35Managing VMM Using Scripts40How to Back Up the VMM Database Using a Script40Sample Scripts to Manage VMM41BackupVMMDatabase.ps141CheckForPendingReboot.ps142GetLibraryAuditRecords.ps143SignScriptsInLibrary.ps145Managing Hosts Using Scripts46Sample Scripts to Manage Hosts46AddHostsInTrustedADdomain.ps147MaintenanceModeInCluster.ps147UpdateVMMAgents.ps149Managing Virtual Machines Using Scripts51How to Convert Virtual Machines Using a Script51How to Install Virtual Guest Services Using a Script53Sample Scripts to Manage Virtual Machines55CompatibilityCheck.ps155ConfigureVMNetworkAdapter.ps157ConvertESXVMUsingV2VfromHost.ps158ConvertESXVMUsingV2VfromLibrary.ps159CreateNewVMs.ps160CreateNewVMsFromTemplate.ps166CreateVMInLibraryMoveToHost.ps168GetVMNameAndIPAddress.ps170InstallVirtualGuestServices.ps171RapidProvisionVM.ps172RapidProvisionVMwithAnswerFile.ps174RecoverVMUsingRapidProvisioning.ps176SetProcessorCompatibility.ps178Managing a High Availability Environment Using Scripts80Sample Scripts to Manage a High Availability Environment80AddClusterCreateStopStartRemoveHAVM.ps181AddHostCluster.ps184EvacuateHosts.ps185LoadBalanceVMsInCluster.ps188RemoveMissingVMs93SaveAndRestoreVMMMetadata97Managing a VMware Environment Using Scripts102How to Add an ESX Server Host Using a Script102Sample Scripts to Manage a VMware Environment104AddESXHost.ps1105AddVirtualCenterServer.ps1107AddVirtualCenterServerChangeHostsToOK.ps1108Disclaimer 2009 Microsoft Corporation. All rights reserved. Sample scripts in this guide are not supported under any Microsoft standard support program or service. The sample scripts are provided AS IS without warranty of any kind. Microsoft disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages. Whats New in VMM 2008 R2 ScriptingThe Hyper-V role in Windows Server 2008 R2 includes significant feature improvements. System Center Virtual Machine Manager (VMM) 2008 R2 leverages these new enhancements by adding two new cmdlets and several parameters that extend the functionality of the existing VMM cmdlets. New and Updated Cmdlets and Parameters in VMM 2008 R2The following list summarizes the new and updated cmdlets and parameters in VMM 2008 R2.CmdletsDisable-VMHostThis cmdlet places a VMM host into maintenance mode. For more information, see Maintenance Mode for Hosts.Enable-VMHostThis new cmdlet removes a VMM host from maintenance mode and returns it to service. For more information, see Maintenance Mode for Hosts.ParametersAllowUnencryptedTransfersYou can use the AllowUnencryptedTransfers parameter to specify that network file transfers into or out of a library, or into, out of, or within a host group, do not require encryption. Allowing unencrypted file transfers can improve performance when neither the source computer nor the destination computer requires encryption. This parameter can be used with the Set-LibraryServer and Set-VMHostGroup cmdlets.BlockLMIfHostBusyYou can use the BlockLMIfHostBusy parameter of the Move-VM cmdlet to stop Hyper-V live migration from attempting to restart a live migration that could not previously start because the source host or the destination host was already performing a live migration.LimitCPUForMigrationThe LimitCPUForMigration parameter limits the processor features for a virtual machine so that the virtual machine can be migrated to a different physical computer that has a different version of the same processor as the source computer. Migrating virtual machines between physical computers with processors from different manufacturers is not supported. This parameter can be used with the following cmdlets: New-HardwareProfile, Set-HardwareProfile, New-VM, Set-VM, and Set-Template.MoveWithinClusterWhen you place a host that is a member of a host cluster into maintenance mode using the Disable-VMHost cmdlet, and you use the MoveWithinCluster parameter, all the virtual machines that are currently deployed on the host will be migrated to another host in the same host cluster.RemoveLibraryStoreSharePathYou can use the RemoveLibraryStoreSharePath parameter of the Set-VMMUserRole cmdlet to clear the path to the specified library share. This share is used by members of a self-service user role to store virtual machines or as a repository from which to deploy stored virtual machines or stored ISO images.RetainDeletedObjectsWhen you use the RetainDeletedObjects parameter with the Get-VMMServer cmdlet, the objects in the cache that are marked for deletion will be preserved. This parameter is included for users who might develop a user interface.RetainObjectCacheWhen you use the RetainObjectCache parameter with the Get-VMMServer cmdlet, the objects in the cache remain in memory and are not reclaimed by garbage collection. This parameter is included for users who might develop a user interface.UseClusterThe UseCluster parameter lets you force the transfer of a virtual machine using Windows Server 2008 Cluster Migration, even when Hyper-V live migration is available, when you move a virtual machine using the Move-VM cmdlet. For more information, see Live Migration.UseLocalVirtualHardDisksThe UseLocalVirtualHardDisks parameter specifies that the virtual hard disk file (.vhd) for a new virtual machine that is created by using the New-VM cmdlet is at a specified location on the destination host, and that no .vhd files will be copied from the library. For more information, see Rapid Provisioning of Virtual Machines.VMNetworkOptimizationEnabledThe VMNetworkOptimizationEnabled parameter enables virtual machine network optimization detection. This feature improves network performance for virtual machines with network adapters that support virtual machine queue (VMQ) or TCP Chimney Offload. VMQ enables creation of a unique network queue for each network adapter. TCP Chimney Offload enables network traffic processing to be offloaded from the networking stack. This parameter can be used with the New-VirtualNetworkAdapter, Set-VirtualNetworkAdapter, New-P2V, and New-V2V cmdlets.VMWarePortGroupYou can use the VMWarePortGroup parameter to specify a VMware port group.Live MigrationHyper-V live migration allows you to migrate a running virtual machine from one node of a Windows Server 2008 R2 failover cluster to another node in the same cluster without any perceived downtime for users. When you use the Move-VM cmdlet to move a running virtual machine that is on a clustered Windows Server 2008 R2 host, VMM will attempt to move the virtual machine using Hyper-V live migration. If Hyper-V live migration is not available, VMM will attempt to use Cluster Migration to move the virtual machine. To force VMM to use Windows Server 2008 Cluster Migration even if Hyper-V live migration is available, use the UseCluster parameter. For more information about Hyper-V live migration, see Whats New in Hyper-V in Windows Server 2008 R2 (/fwlink/?LinkId=147115). Virtual Machine Migration CompatibilityWhen you use the Get-VMHostRating cmdlet to get the host ratings for a single VMM host that is running Windows Server 2008 R2 or VMware, the cmdlet performs a direct validation of the running state of the virtual machine against the host to ensure migration compatibility of the virtual machine. Performing a direct validation might take several seconds to complete.Note If you use the Get-VMHostRating cmdlet to compare a virtual machine against an array of hosts, the cmdlet will not perform a direct validation of the hosts to produce host ratings. To ensure migration compatibility, you should perform a direct validation by running the Get-VMHostRating cmdlet on each potential target host individually.For a sample script about how to perform direct validation on a host, see CompatibilityCheck.ps1.Rapid Provisioning of Virtual MachinesTo quickly create virtual machines from a template, you can use the UseLocalVirtualHardDisks parameter of the New-VM cmdlet. This parameter specifies that New-VM use an existing virtual hard disk file stored locally on the destination host instead of copying a virtual hard disk file from the library by using Background Intelligent Transfer Service (BITS). Use the Move-VirtualHardDisk cmdlet to specify the local virtual hard disk file that the virtual machine should connect to in place of the virtual hard disk file that the template points to. You can also add another virtual hard disk to the virtual machine by using the New-VirtualDiskDrive cmdlet and specifying the virtual hard disk. For more information about how to use the UseLocalVirtualHardDisks parameter, type Get-Help New-VM -detailed at the command prompt. For a sample script about how to use rapid provisioning to create a new virtual machine, see RapidProvisionVM.ps1 or RapidProvisionVMwithAnswerFile.ps1. For a sample script about how to use rapid provisioning to recover a virtual machine, see RecoverVMUsingRapidProvisioning.ps1.Quick Storage MigrationFor a Windows Server 2008 R2 host or a VMware Storage VMotion-capable host, you can use the Move-VirtualHardDisk cmdlet together with the Move-VM cmdlet to migrate a running virtual machine and its files (Windows-based .vhd files or VMware-based .vmdk files) to a different storage location on the same host or on a different host, with minimal or no service outage. For more information about how to move a running virtual machine and its files, type Get-Help Move-VM examples at the command prompt.Maintenance Mode for HostsIn VMM 2008 R2, you can start maintenance mode for a Windows-based host anytime you need to perform maintenance tasks (such as applying updates or replacing a physical component) on the host. When you use the Disable-VMHost cmdlet to place a Windows Server 2008 R2 clustered host into maintenance mode, you can choose one of the following:If live migration is available, evacuate all highly available virtual machines to other hosts on the same cluster. Virtual machines that are not highly available are placed into a saved state.Place all virtual machines on the host into a saved state.When you place a stand-alone Windows-based host or a host within a Windows Server2008cluster into maintenance mode, VMM automatically places all the virtual machines into a saved state.While in maintenance mode, VMM automatically does the following:It blocks virtual machine creation operations on the host.It excludes the host from the host ratings during placement.It sets the value for the host state property to In Maintenance Mode.For more information about Disable-VMHost, type Get-Help Disable-VMHost detailed at the command prompt.After you have used the Enable-VMHost cmdlet to remove the host from maintenance mode and to place it back in service, VMM does the following: It allows virtual machine creation on the host.It includes the host in the host rating calculations during placement.It sets the value for the host state property back to the hosts current state. However, VMM does not automatically move highly available virtual machines back onto the host, and it does not restart any of the virtual machines that were placed in a saved state. For more information about Enable-VMHost, type Get-Help Enable-VMHost detailed at the command prompt. For a sample script about how to place clustered hosts into maintenance mode, see MaintenanceModeInCluster.ps1.See AlsoWhats New in Virtual Machine Manager 2008 R2Introduction to Scripting in Virtual Machine ManagerSystem Center Virtual Machine Manager (VMM)2008 is a server application that you can use to manage virtual machines on a variety of virtualization platforms. VMM server includes the Windows PowerShell - Virtual Machine Manager command shell. You can use this command shell to manage virtual machine hosts, library servers, virtual machines, and other VMM components interactively by using commands or by using task-based scripts.The VMM command shell includes all the standard Windows PowerShell cmdlets and a comprehensive set of cmdlets that are designed specifically for VMM. You can use standard Windows PowerShell cmdlets together with VMM cmdlets to create scripts. Windows PowerShell and the VMM command shell support programming constructions such as variable assignment, looping, conditional statements, and flow control.The sample scripts provided in each section illustrate how you can use Windows PowerShell for centralized management of your physical and virtual infrastructure when that infrastructure is managed by VMM. Experimenting with these scripts can help you understand how to create scripts that are useful in your own environment.This section includes the following topics:About Windows PowerShell for Virtual Machine ManagerManaging Objects in Virtual Machine ManagerUsing the VMM CmdletsUsing Cmdlet HelpConverting Cmdlet Help Examples into ScriptsConnecting to the Virtual Machine Manager ServerFor More InformationThe examples in this section focus on the VMM command shell. For more information about Windows PowerShell, see Windows PowerShell (/fwlink/?LinkId=86262). For more information about scripting with Windows PowerShell, see Scripting with Windows PowerShell (/fwlink/?LinkId=128815).About Windows PowerShell for Virtual Machine ManagerIn the Windows PowerShell - Virtual Machine Manager command shell, you can perform all System Center Virtual Machine Manager (VMM) administrative functions by using commands or by using task-based scripts. This topic explains the relationship between Windows PowerShell and VMM.How Virtual Machine Manager Uses Windows PowerShellWindows PowerShell and VMM provide cmdlets that you can use separately to perform simple adminis