├── changelog.txt ├── .gitattributes ├── .gitignore ├── License.txt ├── PSVirtualBox.psd1 ├── About_PSVirtualbox.help.txt ├── README.md └── PSVirtualBox.psm1 /changelog.txt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/jdhitsolutions/PSVirtualBox/HEAD/changelog.txt -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Auto detect text files and perform LF normalization 2 | * text=auto 3 | 4 | # Custom for Visual Studio 5 | *.cs diff=csharp 6 | 7 | # Standard to msysgit 8 | *.doc diff=astextplain 9 | *.DOC diff=astextplain 10 | *.docx diff=astextplain 11 | *.DOCX diff=astextplain 12 | *.dot diff=astextplain 13 | *.DOT diff=astextplain 14 | *.pdf diff=astextplain 15 | *.PDF diff=astextplain 16 | *.rtf diff=astextplain 17 | *.RTF diff=astextplain 18 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Windows image file caches 2 | Thumbs.db 3 | ehthumbs.db 4 | 5 | # Folder config file 6 | Desktop.ini 7 | 8 | # Recycle Bin used on file shares 9 | $RECYCLE.BIN/ 10 | 11 | # Windows Installer files 12 | *.cab 13 | *.msi 14 | *.msm 15 | *.msp 16 | 17 | # Windows shortcuts 18 | *.lnk 19 | 20 | # ========================= 21 | # Operating System Files 22 | # ========================= 23 | 24 | # OSX 25 | # ========================= 26 | 27 | .DS_Store 28 | .AppleDouble 29 | .LSOverride 30 | 31 | # Thumbnails 32 | ._* 33 | 34 | # Files that might appear on external disk 35 | .Spotlight-V100 36 | .Trashes 37 | 38 | # Directories potentially created on remote AFP share 39 | .AppleDB 40 | .AppleDesktop 41 | Network Trash Folder 42 | Temporary Items 43 | .apdisk 44 | -------------------------------------------------------------------------------- /License.txt: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2015-2020 JDH Information Technology Solutions, Inc. 4 | 5 | 6 | Permission is hereby granted, free of charge, to any person obtaining a copy 7 | of this software and associated documentation files (the "Software"), to deal 8 | in the Software without restriction, including without limitation the rights 9 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 | copies of the Software, and to permit persons to whom the Software is 11 | furnished to do so, subject to the following conditions: 12 | 13 | 14 | The above copyright notice and this permission notice shall be included in 15 | all copies or substantial portions of the Software. 16 | 17 | 18 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 19 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 20 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 21 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 22 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 23 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 24 | THE SOFTWARE. 25 | 26 | 27 | 28 | -------------------------------------------------------------------------------- /PSVirtualBox.psd1: -------------------------------------------------------------------------------- 1 | # Module manifest for module 'PSVirtualBox' 2 | 3 | @{ 4 | 5 | # Script module or binary module file associated with this manifest 6 | ModuleToProcess = 'PSVirtualBox.psm1' 7 | 8 | # Version number of this module. 9 | ModuleVersion = '1.0.0.0' 10 | 11 | # ID used to uniquely identify this module 12 | GUID = '7fb0a080-331e-4633-8c27-d1fe95c3eacd' 13 | 14 | # Author of this module 15 | Author = 'Jeffery Hicks' 16 | 17 | # Company or vendor of this module 18 | CompanyName = 'JDH Information Technology Solutions' 19 | 20 | # Copyright statement for this module 21 | Copyright = '2011-2015 JDH Information Technology Solutions, Inc.' 22 | 23 | # Description of the functionality provided by this module 24 | Description = 'A PowerShell module for managing VirtualBox virtual machines' 25 | 26 | # Minimum version of the Windows PowerShell engine required by this module 27 | PowerShellVersion = '2.0' 28 | 29 | # Name of the Windows PowerShell host required by this module 30 | PowerShellHostName = '' 31 | 32 | # Minimum version of the Windows PowerShell host required by this module 33 | PowerShellHostVersion = '2.0' 34 | 35 | # Minimum version of the .NET Framework required by this module 36 | DotNetFrameworkVersion = '' 37 | 38 | # Minimum version of the common language runtime (CLR) required by this module 39 | CLRVersion = '' 40 | 41 | # Processor architecture (None, X86, Amd64, IA64) required by this module 42 | ProcessorArchitecture = 'None' 43 | 44 | # Modules that must be imported into the global environment prior to importing this module 45 | RequiredModules = @() 46 | 47 | # Assemblies that must be loaded prior to importing this module 48 | RequiredAssemblies = @() 49 | 50 | # Script files (.ps1) that are run in the caller's environment prior to importing this module 51 | ScriptsToProcess = @() 52 | 53 | # Type files (.ps1xml) to be loaded when importing this module 54 | TypesToProcess = @() 55 | 56 | # Format files (.ps1xml) to be loaded when importing this module 57 | FormatsToProcess = @() 58 | 59 | # Modules to import as nested modules of the module specified in ModuleToProcess 60 | NestedModules = @() 61 | 62 | # Functions to export from this module 63 | FunctionsToExport ="*" 64 | 65 | # Cmdlets to export from this module 66 | CmdletsToExport = "" 67 | 68 | # Variables to export from this module 69 | VariablesToExport = "vbox" 70 | 71 | # Aliases to export from this module 72 | AliasesToExport = "*" 73 | 74 | # List of all modules packaged with this module 75 | ModuleList = @() 76 | 77 | # List of all files packaged with this module 78 | FileList = @() 79 | 80 | # Private data to pass to the module specified in ModuleToProcess 81 | PrivateData = '' 82 | 83 | } 84 | 85 | 86 | 87 | -------------------------------------------------------------------------------- /About_PSVirtualbox.help.txt: -------------------------------------------------------------------------------- 1 | TOPIC 2 | about_PSVirtualBox 3 | 4 | SHORT DESCRIPTION 5 | These functions are wrappers to the underlying COM objets and APIs that you can use to manage 6 | a virtual machine infrastructure based on the VirtualBox application, which you can download 7 | for free from Oracle at http://www.virtualbox.org 8 | 9 | LONG DESCRIPTION 10 | The free virtualization application from Oracle, VirtualBox, offers an application SDK which 11 | at this point does not include native PowerShell support. This module is an attempt to utilize 12 | the VirtualBox COM object to perform common management tasks for virtual machines running 13 | in the VirtualBox environment. 14 | 15 | $VBOX GLOBAL VARIABLE 16 | When you import the module, a global variable is created for the main VirtualBox COM object. 17 | This variable, $vbox, is used by many of the support functions. It will be removed when you 18 | remove the module. If the variable does not exist when you call a function, that requires it, 19 | it will be recreated in the global scope. 20 | 21 | PS S:\> $vbox 22 | 23 | Version : 4.0.8 24 | Revision : 71778 25 | PackageType : WINDOWS_64BITS_GENERIC 26 | HomeFolder : C:\Users\Jeff/.VirtualBox 27 | SettingsFilePath : C:\Users\Jeff/.VirtualBox\VirtualBox.xml 28 | Host : System.__ComObject 29 | SystemProperties : System.__ComObject 30 | Machines : {Win2008 R2 Standard, Win7, CoreDC01, Exchange...} 31 | HardDisks : {Win2K8R2.vmdk, R2CoreAD.vmdk, ExchangeStore.vdi, 2008x86.vdi...} 32 | DVDImages : {VBoxGuestAdditions.iso, en_windows_xp_professional_with_service_pack_3_x86_cd_x14-80428.iso, 76 33 | 01.17514.101119-1850_Update_Sp_Wave1-GRMSP1.1_DVD.iso, VBoxGuestAdditions.iso...} 34 | FloppyImages : {} 35 | ProgressOperations : {2b94ee0d-c330-4a95-89e3-5eec2ca67937, e0290bb2-ab2e-4a2e-85fa-84c7d5c81691, f5d8e502-bfc2-40dc- 36 | a880-890c96677061, fe931e5a-66ca-4317-b6f7-5520026aa7f3} 37 | GuestOSTypes : {Other, Windows31, Windows95, Windows98...} 38 | SharedFolders : 39 | PerformanceCollector : System.__ComObject 40 | DHCPServers : {HostInterfaceNetworking-VirtualBox Host-Only Ethernet Adapter, HostInterfaceNetworking-VirtualB 41 | ox Host-Only Ethernet Adapter #2} 42 | EventSource : System.__ComObject 43 | ExtensionPackManager : System.__ComObject 44 | 45 | CASE SENSITIVE NAMES 46 | When passing virtual machine names, be aware that they are CaSe SenSiTive. 47 | 48 | CUSTOM OBJECTS AND NATIVE COM OBJECTS 49 | The Get-VBoxMachine is often used to get virtual machine objects and most other functions in 50 | the module will take pipelined input from this function. Get-VBoxMachine writes a custom 51 | object to the pipeline with commonly used properties. If you want to see the complete COM 52 | object, use the -IncludeRaw parameter. 53 | 54 | PS S:\> $vm=Get-VBoxMachine -Name "CoreDC01" -IncludeRaw 55 | PS S:\> $vm.raw 56 | 57 | Parent : System.__ComObject 58 | Accessible : 1 59 | AccessError : 60 | Name : CoreDC01 61 | Description : 62 | Id : ed29417c-869a-45bf-bbf3-79a407ade630 63 | OSTypeId : Windows2008_64 64 | HardwareVersion : 2 65 | HardwareUUID : ed29417c-869a-45bf-bbf3-79a407ade630 66 | CPUCount : 1 67 | CPUHotPlugEnabled : 0 68 | CPUExecutionCap : 100 69 | MemorySize : 512 70 | MemoryBalloonSize : 0 71 | PageFusionEnabled : 0 72 | VRAMSize : 16 73 | Accelerate3DEnabled : 0 74 | Accelerate2DVideoEnabled : 0 75 | MonitorCount : 1 76 | BIOSSettings : System.__ComObject 77 | FirmwareType : 1 78 | PointingHidType : 2 79 | KeyboardHidType : 2 80 | HpetEnabled : 0 81 | ChipsetType : 1 82 | SnapshotFolder : C:\Users\Jeff\.VirtualBox\Machines\CoreDC01\Snapshots 83 | VRDEServer : System.__ComObject 84 | MediumAttachments : {System.__ComObject, System.__ComObject, System.__ComObject} 85 | USBController : System.__ComObject 86 | AudioAdapter : System.__ComObject 87 | StorageControllers : {IDE Controller, Floppy Controller} 88 | SettingsFilePath : C:\Users\Jeff\.VirtualBox\Machines\CoreDC01\CoreDC01.xml 89 | SettingsModified : 90 | SessionState : 2 91 | SessionType : headless 92 | SessionPid : 1876 93 | State : 5 94 | LastStateChange : 1307967948068 95 | StateFilePath : 96 | LogFolder : C:\Users\Jeff\.VirtualBox\Machines\CoreDC01\Logs 97 | CurrentSnapshot : System.__ComObject 98 | SnapshotCount : 3 99 | CurrentStateModified : 1 100 | SharedFolders : {scripts} 101 | ClipboardMode : 3 102 | GuestPropertyNotificationPatterns : 103 | TeleporterEnabled : 0 104 | TeleporterPort : 0 105 | TeleporterAddress : 106 | TeleporterPassword : 107 | FaultToleranceState : 1 108 | FaultTolerancePort : 0 109 | FaultToleranceAddress : 110 | FaultTolerancePassword : 111 | FaultToleranceSyncInterval : 0 112 | RTCUseUTC : 0 113 | IoCacheEnabled : 1 114 | IoCacheSize : 5 115 | BandwidthControl : System.__ComObject 116 | PciDeviceAssignments : {} 117 | 118 | VERSION 119 | 0.9 120 | June 13, 2011 121 | 122 | SEE ALSO 123 | Get-VirtualBox 124 | Get-VBoxProcess 125 | Get-VBoxMachine 126 | Stop-VBoxMachine 127 | Start-VBoxMachine 128 | Suspend-VBoxMachine -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # PSVirtualBox 2 | 3 | ## Archived 4 | 5 | This module has been archived and should be considered deprecated. It has not been updated in a number of years and there is no guarantee that any of the code will work with newer versions of VirtualBox. You are welcome to use the code but be warned. 6 | 7 | ## Original Readme 8 | 9 | A PowerShell module to manage a Virtual Box environment. This module was developed for an older version of Virtual Box 10 | so I am sure it needs some updating. 11 | 12 | TOPIC 13 | about_PSVirtualBox 14 | 15 | SHORT DESCRIPTION 16 | These functions are wrappers to the underlying COM objets and APIs that you can use to manage 17 | a virtual machine infrastructure based on the VirtualBox application, which you can download 18 | for free from Oracle at http://www.virtualbox.org 19 | 20 | LONG DESCRIPTION 21 | The free virtualization application from Oracle, VirtualBox, offers an application SDK which 22 | at this point does not include native PowerShell support. This module is an attempt to utilize 23 | the VirtualBox COM object to perform common management tasks for virtual machines running 24 | in the VirtualBox environment. 25 | 26 | $VBOX GLOBAL VARIABLE 27 | When you import the module, a global variable is created for the main VirtualBox COM object. 28 | This variable, $vbox, is used by many of the support functions. It will be removed when you 29 | remove the module. If the variable does not exist when you call a function, that requires it, 30 | it will be recreated in the global scope. 31 | 32 | PS S:\> $vbox 33 | 34 | Version : 4.0.8 35 | Revision : 71778 36 | PackageType : WINDOWS_64BITS_GENERIC 37 | HomeFolder : C:\Users\Jeff/.VirtualBox 38 | SettingsFilePath : C:\Users\Jeff/.VirtualBox\VirtualBox.xml 39 | Host : System.__ComObject 40 | SystemProperties : System.__ComObject 41 | Machines : {Win2008 R2 Standard, Win7, CoreDC01, Exchange...} 42 | HardDisks : {Win2K8R2.vmdk, R2CoreAD.vmdk, ExchangeStore.vdi, 2008x86.vdi...} 43 | DVDImages : {VBoxGuestAdditions.iso, en_windows_xp_professional_with_service_pack_3_x86_cd_x14-80428.iso, 76 44 | 01.17514.101119-1850_Update_Sp_Wave1-GRMSP1.1_DVD.iso, VBoxGuestAdditions.iso...} 45 | FloppyImages : {} 46 | ProgressOperations : {2b94ee0d-c330-4a95-89e3-5eec2ca67937, e0290bb2-ab2e-4a2e-85fa-84c7d5c81691, f5d8e502-bfc2-40dc- 47 | a880-890c96677061, fe931e5a-66ca-4317-b6f7-5520026aa7f3} 48 | GuestOSTypes : {Other, Windows31, Windows95, Windows98...} 49 | SharedFolders : 50 | PerformanceCollector : System.__ComObject 51 | DHCPServers : {HostInterfaceNetworking-VirtualBox Host-Only Ethernet Adapter, HostInterfaceNetworking-VirtualB 52 | ox Host-Only Ethernet Adapter #2} 53 | EventSource : System.__ComObject 54 | ExtensionPackManager : System.__ComObject 55 | 56 | CASE SENSITIVE NAMES 57 | When passing virtual machine names, be aware that they are CaSe SenSiTive. 58 | 59 | CUSTOM OBJECTS AND NATIVE COM OBJECTS 60 | The Get-VBoxMachine is often used to get virtual machine objects and most other functions in 61 | the module will take pipelined input from this function. Get-VBoxMachine writes a custom 62 | object to the pipeline with commonly used properties. If you want to see the complete COM 63 | object, use the -IncludeRaw parameter. 64 | 65 | PS S:\> $vm=Get-VBoxMachine -Name "CoreDC01" -IncludeRaw 66 | PS S:\> $vm.raw 67 | 68 | Parent : System.__ComObject 69 | Accessible : 1 70 | AccessError : 71 | Name : CoreDC01 72 | Description : 73 | Id : ed29417c-869a-45bf-bbf3-79a407ade630 74 | OSTypeId : Windows2008_64 75 | HardwareVersion : 2 76 | HardwareUUID : ed29417c-869a-45bf-bbf3-79a407ade630 77 | CPUCount : 1 78 | CPUHotPlugEnabled : 0 79 | CPUExecutionCap : 100 80 | MemorySize : 512 81 | MemoryBalloonSize : 0 82 | PageFusionEnabled : 0 83 | VRAMSize : 16 84 | Accelerate3DEnabled : 0 85 | Accelerate2DVideoEnabled : 0 86 | MonitorCount : 1 87 | BIOSSettings : System.__ComObject 88 | FirmwareType : 1 89 | PointingHidType : 2 90 | KeyboardHidType : 2 91 | HpetEnabled : 0 92 | ChipsetType : 1 93 | SnapshotFolder : C:\Users\Jeff\.VirtualBox\Machines\CoreDC01\Snapshots 94 | VRDEServer : System.__ComObject 95 | MediumAttachments : {System.__ComObject, System.__ComObject, System.__ComObject} 96 | USBController : System.__ComObject 97 | AudioAdapter : System.__ComObject 98 | StorageControllers : {IDE Controller, Floppy Controller} 99 | SettingsFilePath : C:\Users\Jeff\.VirtualBox\Machines\CoreDC01\CoreDC01.xml 100 | SettingsModified : 101 | SessionState : 2 102 | SessionType : headless 103 | SessionPid : 1876 104 | State : 5 105 | LastStateChange : 1307967948068 106 | StateFilePath : 107 | LogFolder : C:\Users\Jeff\.VirtualBox\Machines\CoreDC01\Logs 108 | CurrentSnapshot : System.__ComObject 109 | SnapshotCount : 3 110 | CurrentStateModified : 1 111 | SharedFolders : {scripts} 112 | ClipboardMode : 3 113 | GuestPropertyNotificationPatterns : 114 | TeleporterEnabled : 0 115 | TeleporterPort : 0 116 | TeleporterAddress : 117 | TeleporterPassword : 118 | FaultToleranceState : 1 119 | FaultTolerancePort : 0 120 | FaultToleranceAddress : 121 | FaultTolerancePassword : 122 | FaultToleranceSyncInterval : 0 123 | RTCUseUTC : 0 124 | IoCacheEnabled : 1 125 | IoCacheSize : 5 126 | BandwidthControl : System.__ComObject 127 | PciDeviceAssignments : {} 128 | 129 | VERSION 130 | 0.9 131 | June 13, 2011 132 | 133 | SEE ALSO 134 | Get-VirtualBox 135 | Get-VBoxProcess 136 | Get-VBoxMachine 137 | Stop-VBoxMachine 138 | Start-VBoxMachine 139 | Suspend-VBoxMachine 140 | -------------------------------------------------------------------------------- /PSVirtualBox.psm1: -------------------------------------------------------------------------------- 1 | #Requires -version 2.0 2 | 3 | <# 4 | 5 | TODO: 6 | Integrate Progress bar 7 | Create new VM 8 | Create a new HDD 9 | 10 | #> 11 | 12 | <# 13 | **************************************************************** 14 | * DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED * 15 | * THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK. IF * 16 | * YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, * 17 | * DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING. * 18 | **************************************************************** 19 | #> 20 | 21 | Function Get-VirtualBox { 22 | 23 | <# 24 | .SYNOPSIS 25 | Get the VirtualBox service 26 | .DESCRIPTION 27 | Create a PowerShell object for the VirtualBox COM object. 28 | .EXAMPLE 29 | PS C:\> $vbox=Get-VirtualBox 30 | Create a variable $vbox to referece the VirtualBox service 31 | .NOTES 32 | NAME : Get-VirtualBox 33 | VERSION : 0.9 34 | LAST UPDATED: 6/10/2011 35 | AUTHOR : Jeffery Hicks 36 | .LINK 37 | Get-VBoxMachine 38 | Stop-VBoxMachine 39 | Start-VBoxMachine 40 | Suspend-VBoxMachine 41 | .INPUTS 42 | None 43 | .OUTPUTS 44 | COM Object 45 | #> 46 | 47 | [cmdletbinding()] 48 | Param() 49 | 50 | Write-Verbose "Starting $($myinvocation.mycommand)" 51 | #create vbox app 52 | Write-Verbose "Creating the VirtualBox COM object" 53 | $vbox = New-Object -ComObject "VirtualBox.VirtualBox" 54 | 55 | $vbox 56 | Write-Verbose "Ending $($myinvocation.mycommand)" 57 | 58 | } 59 | 60 | Function Get-VBoxMachine { 61 | 62 | <# 63 | .SYNOPSIS 64 | Get a VirtualBox virtual machine 65 | .DESCRIPTION 66 | Retrieve any or all vritual box machines by name, by state or all. The default usage, without any parameters is to display all running virtual machines. Use -IncludeRaw to add the native COM object for the virtual machine. 67 | .PARAMETER Name 68 | The name of a virtual machine. IMPORTANT: Names are case sensitive. 69 | .PARAMETER All 70 | Return all virtual machines regardless of state. Valid values are: 71 | "Stopped","Running","Saved","Teleported","Aborted","Paused","Stuck","Snapshotting", 72 | "Starting","Stopping","Restoring","TeleportingPausedVM","TeleportingIn","FaultTolerantSync", 73 | "DeletingSnapshotOnline","DeletingSnapshot", and "SettingUp" 74 | .PARAMETER State 75 | Return virtual machines based on their state. 76 | .PARAMETER IncludeRaw 77 | Include the raw or native COM object for the virtual machine. 78 | .EXAMPLE 79 | PS C:\> Get-VBoxMachine 80 | ID : 96c58d09-37be-46b1-9f4b-d37ea6da4005 81 | Name : Win2008 R2 Standard 82 | MemoryMB : 1500 83 | Description : Windows 2008 R2 Standard DC jdhlab.local 84 | State : Running 85 | OS : Windows2008_64 86 | 87 | ID : ed29417c-869a-45bf-bbf3-79a407ade630 88 | Name : CoreDC01 89 | MemoryMB : 512 90 | Description : 91 | State : Running 92 | OS : Windows2008_64 93 | 94 | ID : 2dd7f99a-d209-4b1c-ad79-2fa34e2c229a 95 | Name : Ubuntu 96 | MemoryMB : 1024 97 | Description : v11.04 Natty Narwhal 98 | State : Running 99 | OS : Ubuntu_64 100 | 101 | Return all running virtual machines 102 | .EXAMPLE 103 | PS C:\> Get-VBoxMachine -Name CoreDC01 104 | ID : ed29417c-869a-45bf-bbf3-79a407ade630 105 | Name : CoreDC01 106 | MemoryMB : 512 107 | Description : 108 | State : Running 109 | OS : Windows2008_64 110 | 111 | Retrieve a machine by name. Names are case sensitive 112 | .EXAMPLE 113 | PS C:\> Get-VBoxMachine -State Saved 114 | ID : 2dd7f99a-d209-4b1c-ad79-2fa34e2c229a 115 | Name : Ubuntu 116 | MemoryMB : 1024 117 | Description : v11.04 Natty Narwhal 118 | State : Saved 119 | OS : Ubuntu_64 120 | 121 | Get suspended virtual machines 122 | .NOTES 123 | NAME : Get-VBoxMachine 124 | VERSION : 0.9 125 | LAST UPDATED: 6/13/2011 126 | AUTHOR : Jeffery Hicks 127 | .LINK 128 | Stop-VBoxMachine 129 | Start-VBoxMachine 130 | Suspend-VBoxMachine 131 | .INPUTS 132 | Strings for virtual machine names 133 | .OUTPUTS 134 | Custom Object 135 | #> 136 | 137 | [cmdletbinding(DefaultParameterSetName="All")] 138 | Param( 139 | [Parameter(Position=0)] 140 | [string[]]$Name, 141 | [Parameter(ParameterSetName="All")] 142 | [switch]$All, 143 | [Parameter(ParameterSetName="All")] 144 | [ValidateSet("Stopped","Running","Saved","Teleported","Aborted", 145 | "Paused","Stuck","Snapshotting","Starting","Stopping", 146 | "Restoring","TeleportingPausedVM","TeleportingIn","FaultTolerantSync", 147 | "DeletingSnapshotOnline","DeletingSnapshot","SettingUp")] 148 | [string]$State = "Running", 149 | [switch]$IncludeRaw 150 | ) 151 | 152 | Write-Verbose "Starting $($myinvocation.mycommand)" 153 | 154 | #get global vbox variable or create it if it doesn't exist create it 155 | if (-Not $global:vbox) { 156 | $global:vbox = Get-VirtualBox 157 | } 158 | 159 | if ($Name) { 160 | #get virtual machines by name 161 | Write-Verbose "Getting virtual machines by name" 162 | #initialize an array to hold virtual machines 163 | $vmachines = @() 164 | foreach ($item in $Name) { 165 | Write-Verbose "Finding $item" 166 | $vMachines+= $vbox.FindMachine($item) 167 | } 168 | } #if $name 169 | elseif ($All) { 170 | #get all machines 171 | Write-Verbose "Getting all virtual machines" 172 | $vmachines = $vbox.Machines 173 | } 174 | Else { 175 | Write-Verbose "Getting virtual machines with a state of $State" 176 | 177 | #convert State to numeric value 178 | Switch ($state) { 179 | "Stopped" {$istate = 1} 180 | "Saved" {$istate = 2} 181 | "Teleported" {$istate = 3} 182 | "Aborted" {$istate = 4} 183 | "Running" {$istate = 5} 184 | "Paused" {$istate = 6} 185 | "Stuck" {$istate = 7} 186 | "Snapshotting" {$istate = 8} 187 | "Starting" {$istate = 9} 188 | "Stopping" {$istate = 10} 189 | "Restoring" {$istate = 11} 190 | "TeleportingPausedVM" {$istate = 12} 191 | "TeleportingIn" {$istate = 13} 192 | "FaultTolerantSync" {$istate = 14} 193 | "DeletingSnapshotOnline" {$istate = 15} 194 | "DeletingSnapshot" {$istate = 16} 195 | "SettingUp" {$istate = 17} 196 | 197 | } 198 | 199 | $vmachines=$vbox.Machines | where {$_.State -eq $iState} 200 | } 201 | 202 | Write-Verbose "Found $(($vmachines | measure-object).count) virtual machines" 203 | if ($vmachines) { 204 | #write a virtual machine object to the pipeline 205 | foreach ($vmachine in $vmachines) { 206 | 207 | #Decode state 208 | Switch ($vmachine.State) { 209 | 1 {$vstate = "Stopped"} 210 | 2 {$vstate = "Saved"} 211 | 3 {$vstate = "Teleported"} 212 | 4 {$vstate = "Aborted"} 213 | 5 {$vstate = "Running"} 214 | 6 {$vstate = "Paused"} 215 | 7 {$vstate = "Stuck"} 216 | 8 {$vstate = "Snapshotting"} 217 | 9 {$vstate = "Starting"} 218 | 10 {$vstate = "Stopping"} 219 | 11 {$vstate = "Restoring"} 220 | 12 {$vstate = "TeleportingPausedVM"} 221 | 13 {$vstate = "TeleportingIn"} 222 | 14 {$vstate = "FaultTolerantSync"} 223 | 15 {$vstate = "DeletingSnapshotOnline"} 224 | 16 {$vstate = "DeletingSnapshot"} 225 | 17 {$vstate = "SettingUp"} 226 | 227 | Default {$vstate = $vmachine.State} 228 | } 229 | 230 | $obj = New-Object -TypeName PSObject -Property @{ 231 | Name = $vmachine.name 232 | State = $vstate 233 | Description = $vmachine.description 234 | ID = $vmachine.ID 235 | OS = $vmachine.OSTypeID 236 | MemoryMB = $vmachine.MemorySize 237 | } 238 | if ($IncludeRaw) { 239 | #add raw COM object as a property 240 | $obj | Add-Member -MemberType Noteproperty -Name Raw -Value $vmachine -passthru 241 | } 242 | else { 243 | $obj 244 | } 245 | } #foreach 246 | } #if vmachines 247 | else { 248 | Write-Host "No matching virtual machines found. Machine names are CaSe SenSitIve." -ForegroundColor Magenta 249 | } 250 | Write-Verbose "Ending $($myinvocation.mycommand)" 251 | } #end function 252 | 253 | Function Suspend-VBoxMachine { 254 | 255 | <# 256 | .SYNOPSIS 257 | Suspend a virtual machine 258 | .DESCRIPTION 259 | This function will suspend or save the state of a running virtual machine. You must specify the virtual machine by its ID. 260 | .PARAMETER ID 261 | The ID or GUID of the running virtual machine. 262 | .PARAMETER WhatIf 263 | Show what the command would have processed 264 | .PARAMETER Confirm 265 | Confirm each suspension 266 | .EXAMPLE 267 | PS C:\> Get-VBoxMachine | Suspend-VBoxMachine 268 | Suspend all running virtual machines 269 | .NOTES 270 | NAME : Suspend-VBoxMachine 271 | VERSION : 0.9 272 | LAST UPDATED: 6/13/2011 273 | AUTHOR : Jeffery Hicks 274 | .LINK 275 | Get-VBoxMachine 276 | Stop-VBoxMachine 277 | Start-VBoxMachine 278 | .INPUTS 279 | Strings 280 | .OUTPUTS 281 | None 282 | #> 283 | 284 | [cmdletbinding(SupportsShouldProcess=$True)] 285 | Param( 286 | [Parameter(Position=0,Mandatory=$True,HelpMessage="Enter a virtual box machine ID", 287 | ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$True)] 288 | [ValidateNotNullorEmpty()] 289 | [GUID[]]$ID 290 | ) 291 | 292 | Begin { 293 | Write-Verbose "Ending $($myinvocation.mycommand)" 294 | #get global vbox variable or create it if it doesn't exist create it 295 | if (-Not $global:vbox) { 296 | $global:vbox = Get-VirtualBox 297 | } 298 | } #Begin 299 | 300 | Process { 301 | foreach ($item in $ID) { 302 | 303 | #get the virtual machine 304 | $vmachine = $vbox.FindMachine($item) 305 | 306 | if ($vmachine) { 307 | Write-Host "Suspending $($vmachine.name)" -ForegroundColor Cyan 308 | if ($pscmdlet.ShouldProcess($vmachine.name)) { 309 | #create Vbox session object 310 | Write-Verbose "Creating a session object" 311 | $vsession = New-Object -ComObject "VirtualBox.Session" 312 | #launch the VMProcess to lock in write mode 313 | Write-verbose "Locking the machine" 314 | $vmachine.LockMachine($vsession,1) 315 | #run the SaveState() method 316 | Write-Verbose "Saving State" 317 | $vsession.Machine.SaveState() 318 | } #should process 319 | } 320 | else { 321 | Write-Warning "Failed to find virtual machine with an id of $ID" 322 | } 323 | } #foreach $id 324 | } #process 325 | 326 | End { 327 | Write-Verbose "Ending $($myinvocation.mycommand)" 328 | } #End 329 | 330 | } #end function 331 | 332 | Function Start-VBoxMachine { 333 | 334 | <# 335 | .SYNOPSIS 336 | Start a virtual machine 337 | .DESCRIPTION 338 | Start one or more virtual box machines. The default is to start them in an interactive or GUI mode. But you can also run them headless which will start a new process window, but there will be no interactive console window. 339 | .PARAMETER Name 340 | The name of a virtual machine. IMPORTANT: Names are case sensitive. 341 | .PARAMETER Headless 342 | Run the virtual machine in a headless process. 343 | .EXAMPLE 344 | PS C:\> Start-VBoxMachine "Win7" 345 | Starts the virtual machine called Win7 in a GUI mode. 346 | .EXAMPLE 347 | PS C:\> Start-VBoxMachine CoreDC01 -headless 348 | Start virtual machine CoreDC01 headless. 349 | .NOTES 350 | NAME : Start-VBoxMachine 351 | VERSION : 0.9 352 | LAST UPDATED: 6/13/2011 353 | AUTHOR : SERENITY\Jeff 354 | .LINK 355 | Get-VBoxMachine 356 | Stop-VBoxMachine 357 | .INPUTS 358 | Strings 359 | .OUTPUTS 360 | None 361 | #> 362 | 363 | [cmdletbinding()] 364 | Param( 365 | [Parameter(Position=0,Mandatory=$True,HelpMessage="Enter a virtual machine name", 366 | ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$True)] 367 | [ValidateNotNullorEmpty()] 368 | [string[]]$Name, 369 | [switch]$Headless 370 | ) 371 | 372 | Begin { 373 | Write-Verbose "Starting $($myinvocation.mycommand)" 374 | #get global vbox variable or create it if it doesn't exist create it 375 | if (-Not $global:vbox) { 376 | $global:vbox = Get-VirtualBox 377 | } 378 | }#Begin 379 | 380 | Process { 381 | foreach ($item in $name) { 382 | 383 | #get the virtual machine 384 | $vmachine=$vbox.FindMachine($item) 385 | 386 | if ($vmachine) { 387 | #create Vbox session object 388 | Write-Verbose "Creating a session object" 389 | $vsession = New-Object -ComObject "VirtualBox.Session" 390 | if ($vmachine.State -lt 5) { 391 | if ($Headless) { 392 | Write-Verbose "Starting in headless mode" 393 | $vmachine.LaunchVMProcess($vsession,"headless","") 394 | } 395 | else { 396 | $vmachine.LaunchVMProcess($vsession,"gui","") 397 | } 398 | } 399 | else { 400 | Write-Host "I can only start machines that have been stopped." -ForegroundColor Magenta 401 | } 402 | 403 | } #if vmachine 404 | 405 | } #foreach 406 | } #process 407 | 408 | End { 409 | Write-Verbose "Ending $($myinvocation.mycommand)" 410 | } #End 411 | 412 | } #end function 413 | 414 | Function Stop-VBoxMachine { 415 | 416 | <# 417 | .SYNOPSIS 418 | Stop a virtual machine 419 | .DESCRIPTION 420 | Stop one or more virtual box machines by sending the ACPI shutdown signal. 421 | .PARAMETER Name 422 | The name of a virtual machine. IMPORTANT: Names are case sensitive. 423 | .PARAMETER Headless 424 | Run the virtual machine in a headless process. 425 | .EXAMPLE 426 | PS C:\> Stop-VBoxMachine "Win7" 427 | Stops the virtual machine called Win7 428 | .EXAMPLE 429 | PS C:\> Get-VBoxMachine | Stop-VBoxMachine 430 | Stop all running virtual machines 431 | .NOTES 432 | NAME : Stop-VBoxMachine 433 | VERSION : 0.9 434 | LAST UPDATED: 6/13/2011 435 | AUTHOR : SERENITY\Jeff 436 | .LINK 437 | Get-VBoxMachine 438 | Start-VBoxMachine 439 | Suspend-VBoxMachine 440 | .INPUTS 441 | Strings 442 | .OUTPUTS 443 | None 444 | #> 445 | 446 | 447 | [cmdletbinding(SupportsShouldProcess=$True)] 448 | Param( 449 | [Parameter(Position=0,Mandatory=$True,HelpMessage="Enter a virtual machine name", 450 | ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$True)] 451 | [ValidateNotNullorEmpty()] 452 | [string[]]$Name 453 | ) 454 | 455 | Begin { 456 | Write-Verbose "Starting $($myinvocation.mycommand)" 457 | #get global vbox variable or create it if it doesn't exist create it 458 | if (-Not $global:vbox) { 459 | $global:vbox = Get-VirtualBox 460 | } 461 | } #Begin 462 | 463 | Process { 464 | foreach ($item in $name) { 465 | 466 | #get the virtual machine 467 | $vmachine=$vbox.FindMachine($item) 468 | 469 | if ($vmachine) { 470 | if ($pscmdlet.ShouldProcess($vmachine.name)) { 471 | #create Vbox session object 472 | Write-Verbose "Creating a session object" 473 | $vsession = New-Object -ComObject "VirtualBox.Session" 474 | if ($vmachine.State -eq 5) { 475 | Write-verbose "Locking the machine" 476 | $vmachine.LockMachine($vsession,1) 477 | #send ACPI shutdown signal 478 | $vsession.console.PowerButton() 479 | } 480 | else { 481 | Write-Host "I can only stop machines that are running." -ForegroundColor Magenta 482 | } 483 | } #should process 484 | } #if vmachine 485 | 486 | } #foreach 487 | } #process 488 | 489 | End { 490 | Write-Verbose "Ending $($myinvocation.mycommand)" 491 | } #end 492 | 493 | } #end function 494 | 495 | Function Get-VBoxProcess { 496 | 497 | <# 498 | .SYNOPSIS 499 | Get all VirtualBox related processes 500 | .DESCRIPTION 501 | Find all running processes related to VirtualBox. 502 | .EXAMPLE 503 | PS C:\> Get-VBoxProcess 504 | Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName 505 | ------- ------ ----- ----- ----- ------ -- ----------- 506 | 401 56 36272 27956 139 36.63 1876 VBoxHeadless 507 | 754 129 103736 52940 244 76.85 12244 VBoxHeadless 508 | 3444 17 16076 11844 109 1,351.14 8176 VBoxSVC 509 | 193 15 19416 55140 137 1.28 12212 VirtualBox 510 | 511 | Get all running VirtualBox related processes 512 | .NOTES 513 | NAME : Get-VboxProcess 514 | VERSION : 0.9 515 | LAST UPDATED: 6/13/2011 516 | AUTHOR : Jeffery Hicks 517 | .LINK 518 | Get-VirtualBox 519 | .INPUTS 520 | None 521 | .OUTPUTS 522 | Process object 523 | #> 524 | 525 | [cmdletbinding()] 526 | Param() 527 | 528 | Write-Verbose "Starting $($myinvocation.mycommand)" 529 | Try { 530 | $processes = Get-Process -ErrorAction "Stop" | Where {$_.path -match "oracle\\virt"} 531 | Write-Verbose "Found $($processes | measure-object).Count processes)" 532 | $processes 533 | } 534 | Catch { 535 | Write-Host "Failed to find any VirtualBox related processes." -ForegroundColor Magenta 536 | } 537 | 538 | Finally { 539 | Write-Verbose "Ending $($myinvocation.mycommand)" 540 | } 541 | 542 | } #end function 543 | 544 | ######################################################################################### 545 | 546 | #Getting a reference to VirtualBox COM object 547 | $vbox=Get-VirtualBox 548 | $status="VirtualBox v{0} rev.{1} Machines: {2}" -f $vbox.version,$vbox.revision,$vbox.machines.count 549 | Write-Host $status -ForegroundColor Cyan 550 | 551 | #Defining some aliases 552 | New-Alias -Name gvbm -Value Get-VBoxMachine 553 | New-Alias -Name stovbm -Value Stop-VBoxMachine 554 | New-Alias -Name stavbm -Value Start-VBoxMachine 555 | New-Alias -Name suvbm -Value Suspend-VBoxMachine 556 | New-Alias -Name gvb -Value Get-VirtualBox 557 | New-Alias -Name gvbp -Value Get-VBoxProcess 558 | 559 | #Exporting some module members 560 | Export-ModuleMember -Alias * -Function * -Variable vbox 561 | --------------------------------------------------------------------------------