VirtualBox PowerShell Module

Discussion about using the VirtualBox API, Tutorials, Samples.
Andrew Brehm
Posts: 42
Joined: 28. Mar 2012, 17:19

VirtualBox PowerShell Module

Post by Andrew Brehm »

For what it's worth, I have started writing a PowerShell module for VirtualBox which translates VBoxManage commands into cmdlets and also features a VirtualBoxVM object. It's currently rather primitive but I plan to continue working on it for my own purposes. But if anyone is interested I can upload it somewhere and keep it current.

Currently I have these cmdlets
PS C:\Program Files\WindowsPowerShell\Modules\VirtualBox> Get-Command -Module VirtualBox

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        Get-VirtualBoxVM                                   0.0        VirtualBox
Function        Invoke-VirtualBoxVMPowerShellScript                0.0        VirtualBox
Function        Invoke-VirtualBoxVMProcess                         0.0        VirtualBox
Function        New-VirtualBoxVMObject                             0.0        VirtualBox
Function        Open-VirtualBoxVMConsole                           0.0        VirtualBox
Function        Start-VirtualBoxVM                                 0.0        VirtualBox
Function        Stop-VirtualBoxVM                                  0.0        VirtualBox
and an object type VirtualBoxVM which currently has the fields Name, Uuid, State, Running (bool, not shown by default) and Info (everything returned by VBoxManage showvminfo as a string, not shown by default).
  • Invoke-*Process runs a program on the VM using a credential if given or asking for the password of the current user if none given.
  • Invoke-*PowerShellScript runs a PowerShell script block (for example Install-WindowsUpdate -Confirm:0 -AutoReboot, I like updating VMs semi-manually).
  • Open-*Console starts a VM and opens the GUI. Start-*VM starts the VM in the background. Each cmdlet takes one Name, Uuid or VirtualBoxVM except Get-*VM which can use wildcards to find VMs.
  • New-*Object does not create a VM but creates a VirtualBoxVM object based on the output of VBoxManage showvminfo. It is used internally by Get-VirtualBoxVM.
It's well possible that all of this has already been done but I find this module useful for my own purposes.
Last edited by socratis on 10. Dec 2019, 20:13, edited 1 time in total.
Reason: Fixed formatting.
socratis
Site Moderator
Posts: 27330
Joined: 22. Oct 2010, 11:03
Primary OS: Mac OS X other
VBox Version: PUEL
Guest OSses: Win(*>98), Linux*, OSX>10.5
Location: Greece

Re: VirtualBox PowerShell Module

Post by socratis »

Andrew Brehm wrote:I have started writing a PowerShell module for VirtualBox which translates VBoxManage commands into cmdlets
I did not know what a "cmdlet" is, had to look it up, and I ended in Microsoft's Cmdlet Overview. Since this is more of a programming-related topic, I think I should move it in the "The VirtualBox API" section of the forums for the moment, even though you're not technically using the API to create your cmdlets. Or are you?

Tell me what you think...
Do NOT send me Personal Messages (PMs) for troubleshooting, they are simply deleted.
Do NOT reply with the "QUOTE" button, please use the "POST REPLY", at the bottom of the form.
If you obfuscate any information requested, I will obfuscate my response. These are virtual UUIDs, not real ones.
Andrew Brehm
Posts: 42
Joined: 28. Mar 2012, 17:19

Re: VirtualBox PowerShell Module

Post by Andrew Brehm »

The module is actually written in PowerShell as well so it won't use the API soon. On the other hand, using VBoxManager programmatically is an "API call" in the widest sense, so perhaps. Finally, the module can in the future use the API instead of VBoxManage or both, so API will be appropriate in the long run.
socratis
Site Moderator
Posts: 27330
Joined: 22. Oct 2010, 11:03
Primary OS: Mac OS X other
VBox Version: PUEL
Guest OSses: Win(*>98), Linux*, OSX>10.5
Location: Greece

Re: VirtualBox PowerShell Module

Post by socratis »

OK moving to the "API" section then. Otherwise it will get lost in the noise... ;)
Do NOT send me Personal Messages (PMs) for troubleshooting, they are simply deleted.
Do NOT reply with the "QUOTE" button, please use the "POST REPLY", at the bottom of the form.
If you obfuscate any information requested, I will obfuscate my response. These are virtual UUIDs, not real ones.
Andrew Brehm
Posts: 42
Joined: 28. Mar 2012, 17:19

Re: VirtualBox PowerShell Module

Post by Andrew Brehm »

Just a quick update so people don't think I gave up on this.

I will upload a first release shortly after the holidays.

I have two new cmdlets Submit-VirtualBoxVMProcess and Submit-VirtualBoxVMPowerShellScript. I use the latter to run Get-WindowsUpdate and Install-WindowsUpdate on a series of VMs.
SmithersTheOracle
Posts: 60
Joined: 28. Dec 2019, 08:58
Primary OS: MS Windows 7
VBox Version: PUEL
Guest OSses: Windows, Linux

Re: VirtualBox PowerShell Module

Post by SmithersTheOracle »

I was actually about to start a module when I saw this. Can you post what you've got on Github or something? I've never been one to reinvent the wheel and I'd like to keep my cmdlets standard with yours.

I can start rewriting the cmdlets using API calls, if you'd like. My main goal for this was going to be "Start-VboxVM -Type Headless" and "Control-VboxVM -AddEncPassword" since vboxmanage doesn't play too well with the password. But, I think it'd be a powerful tool for Vbox since PS is finally cross-platform and I'd like to see a complete module.

Maybe if we can get some traction, others will hop onboard too. :D
Andrew Brehm
Posts: 42
Joined: 28. Mar 2012, 17:19

Re: VirtualBox PowerShell Module

Post by Andrew Brehm »

I'll be back home tomorrow evening and over New Year's I will upload what I have.

It actually didn't occur to me to use the API instead of VBoxManage.exe since I only started my work because I found the vboxmanage commands tiresome. My module is implemented in PowerShell, as I found an implementation in C# too complicated for the simple tasks I needed.
SmithersTheOracle
Posts: 60
Joined: 28. Dec 2019, 08:58
Primary OS: MS Windows 7
VBox Version: PUEL
Guest OSses: Windows, Linux

Re: VirtualBox PowerShell Module

Post by SmithersTheOracle »

If vboxmanage took the password on input I wouldn't be trying to waste my time on the SDK... believe me. From what I can tell, there's no documentation specific to PS or .Net and there seems to be differences in what PS sees in the COM and the Web Service from what's documented in the SDKref. Addencpassword even only seems to exist in vboxmanage as a direct call to the console, not really its own function. Still not going to give up though. It's just going to take me longer than I was hoping.

My main issue is with the web service. I've been trying to find out where I can get the managed object template from to hand off as the first variable of, seemingly, each method. It's a lot to dig through. If anyone else has any input, I welcome suggestions and corrections.

Also, it's really slow importing the WSDL file - 30 seconds or so. Does anyone know a way to store everything natively after importing it through New-WebServiceProxy so I can skip that? Maybe I can just export everything as an XML or something?

Additionally, I noticed an earlier module that uses the COM. It's on Github at /jdhitsolutions/PSVirtualBox. <-- Not sure if I can post links here so I'll just leave the suffix like that. Seems like it was a great start. I figured I'd use it as an outline for how all of my functions will be structured. I just need to fix everything so it's not case sensitive and I want to implement the author's Todo list at the top of the file. Also, if you're reading this Jeff, I noticed the issues you were having fairly quickly. Did you ever have any ideas on how to work out the data type issues? Maybe I'm seeing issues that you didn't? Any issues with me semi-plagiarizing your work? I promise to leave your name wherever it belongs.
SmithersTheOracle
Posts: 60
Joined: 28. Dec 2019, 08:58
Primary OS: MS Windows 7
VBox Version: PUEL
Guest OSses: Windows, Linux

Re: VirtualBox PowerShell Module

Post by SmithersTheOracle »

Quick update. A thought occurred to me that I might be able to echo the password to the vboxmanage command like so:

Code: Select all

& cmd /c echo $password> Vboxmanage controlvm "2016 Core" addencpassword "2016 Core" -
but it doesn't do anything.

I tried pipe-lining it instead, but got:

Code: Select all

& cmd /c echo $password| Vboxmanage controlvm "2016 Core" addencpassword "2016 Core" -
Enter password:VBoxManage.exe: error: Failed to retrieve echo setting (VERR_INVALID_HANDLE)
back from it.

Same results from command prompt as well. Even this would be an acceptable stop-gap in the mean time. Too bad that didn't work either.
SmithersTheOracle
Posts: 60
Joined: 28. Dec 2019, 08:58
Primary OS: MS Windows 7
VBox Version: PUEL
Guest OSses: Windows, Linux

Re: VirtualBox PowerShell Module

Post by SmithersTheOracle »

Well I got a working draft. Here's what I did so far so everyone can follow along with the progress. You might want to read it in it's entirety first to see what you'll be doing. This is going to be a long post again. (Sorry :roll: ) Mods: If you want this moved to a new thread, let me know. I know I've kind of thread-jacked Andrew at this point.

*--IF YOU AREN'T SURE WHAT ANY OF THIS IS, PLEASE STOP AND ASK QUESTIONS FIRST. I DON'T WANT ANYONE SCREWING UP THEIR COMPUTER DOING ANYTHING YOU SEE HERE!--*

Edit: Removed the body of this post since there's now a working copy on GitHub.
Last edited by SmithersTheOracle on 9. Jan 2020, 07:50, edited 1 time in total.
Andrew Brehm
Posts: 42
Joined: 28. Mar 2012, 17:19

Re: VirtualBox PowerShell Module

Post by Andrew Brehm »

I have uploaded an initial commit of my primitive PowerShell-based PowerShell module for VirtualBox.

I use it myself mainly to run Install-WindowsUpdate on a series of VirtualBox VMs. It works well for that purpose. I will add documentation at some point.

https://github.com/ajbrehm/NNVirtualBoxPowerShellModule

If anyone wants to participate, I'll add as committers. What license should I use?
SmithersTheOracle
Posts: 60
Joined: 28. Dec 2019, 08:58
Primary OS: MS Windows 7
VBox Version: PUEL
Guest OSses: Windows, Linux

Re: VirtualBox PowerShell Module

Post by SmithersTheOracle »

Wow. I'm pretty jealous of how nice it looks. Mine's only a few of days old now, but I'm going to release it in all its ugly glory. Just need to finish converting the last function that I've got so far (Suspend-VirtualBoxVM) and I'll post it. I won't finish updating the help before posting, so some of it will be copy-pasted from other commands to fill in the void. I'm sure some additional bug testing will need to be done as well. At least it'll have a real structure to speak of, compared to the quick script I wrote above. Function before form - I'll clean it up when it works with a few less bugs.

As for the license, since mine's based on Jeff's, it will also include the MIT license. I e-mailed Jeff and let him know I was deriving my work from his and he didn't have a problem with it. However, since it's covered under the MIT license, this will not be a commercial project. Anyone who wants to help should understand that.

Things I've got so far:

Code: Select all

# define aliases
New-Alias -Name gvbox -Value Get-VirtualBox
New-Alias -Name stavboxs -Value Start-VirtualBoxSession
New-Alias -Name stovboxs -Value Stop-VirtualBoxSession
New-Alias -Name stavboxws -Value Start-VirtualBoxWebSrv
New-Alias -Name stovboxws -Value Stop-VirtualBoxWebSrv
New-Alias -Name resvboxws -Value Restart-VirtualBoxWebSrv
New-Alias -Name refvboxws -Value Update-VirtualBoxWebSrv
New-Alias -Name gvboxp -Value Get-VirtualBoxProcess
New-Alias -Name gvboxvm -Value Get-VirtualBoxVM
New-Alias -Name suvboxvm -Value Suspend-VirtualBoxVM
New-Alias -Name stavboxvm -Value Start-VirtualBoxVM
New-Alias -Name stovboxvm -Value Stop-VirtualBoxVM
# export module members
Export-ModuleMember -Alias * -Function * -Variable @('vbox','vboxwebsrvtask')
Andrew Brehm
Posts: 42
Joined: 28. Mar 2012, 17:19

Re: VirtualBox PowerShell Module

Post by Andrew Brehm »

Should we start coordinating?

What is yours written in? PowerShell? I didn't take a look yet.
SmithersTheOracle
Posts: 60
Joined: 28. Dec 2019, 08:58
Primary OS: MS Windows 7
VBox Version: PUEL
Guest OSses: Windows, Linux

Re: VirtualBox PowerShell Module

Post by SmithersTheOracle »

Absolutely. I've been writing it in Powershell using the Windows ISE, but I'm going to switch over to VS Code to link it to the repo. I created a new Github account with this same name to handle this project. I'll PM you what I've got right now before so you can take a look before I officially upload it. Let me know what you think.
SmithersTheOracle
Posts: 60
Joined: 28. Dec 2019, 08:58
Primary OS: MS Windows 7
VBox Version: PUEL
Guest OSses: Windows, Linux

Re: VirtualBox PowerShell Module

Post by SmithersTheOracle »

Just a quick update: I've cleaned up a lot of the code and converted just about everything I can to actual classes. Looking into adding some methods to parse and handle the errors/exceptions VirtualBox gives back. Still having an issue with the Suspend-VirtualBoxVM command throwing back a non-mutable error, but I've fixed the session lock/unlock issue. I've also added a Get-VirtualBoxDisks command that pulls a lot of useful information. Added a switch to all of the relevant commands to speed things up, by skipping some rather redundant checks. I've gone through each command and re-written the help text from scratch, so I've probably missed something. Altogether, things are a lot more stable now. I'll be releasing a public version soon.

Andrew: I've been trying to replicate IGuestSession::createProcess the same way as VBox's source code with no luck so far. Strange thing is I can see the conhost process create in the guest OS, linger for a few seconds, then it just goes away. Complete call I've got right now is this:

Code: Select all

$global:vbox.IMachine_lockMachine($imachine.Id,$imachine.ISession,1)
$iconsole = $global:vbox.ISession_getConsole($imachine.ISession)
$iconsoleguest = $global:vbox.IConsole_getGuest($iconsole)
$iguestsession = $global:vbox.IGuest_createSession($iconsoleguest,$Credential.GetNetworkCredential().UserName,$Credential.GetNetworkCredential().Password,$Credential.GetNetworkCredential().Domain,"PsShutdown")
$iguestsessionstatus = $global:vbox.IGuestSession_waitFor($iguestsession, 1, 10000)
$global:vbox.IGuestSession_processCreate($iguestsession, 'cmd.exe', @('/c','powershell -ExecutionPolicy Bypass -Command `"Stop-Computer -Force -Confirm:$false`"'), @(), 3, 10000)
$global:vbox.IManagedObjectRef_release($iconsole)
$global:vbox.ISession_unlockMachine($imachine.ISession)
The aggravating part is that there are no errors. I'll keep trying though.
Post Reply