virtualbox

A library to interact with VirtualBox.

node-virtualbox

A JavaScript library to interact with VirtualBox virtual machines.

Installation

Obtain the package

$ npm install virtualbox [--save] [-g]

and then use it

var virtualbox = require('virtualbox');

The general formula for commands is:

virtualbox. API command ( "registered vm name", callback );

Available API commands are listed at the end of this document.

Controlling Power and State

node-virtualbox provides convenience methods to command the guest machine's power state in the customary ways.

Virtual machines will start headless by default, but you can pass a boolean parameter to start them with a GUI:

virtualbox.start("machine_name", true, function (error) {
  if (error) throw error;
  console.log("Virtual Machine has started WITH A GUI!");
});
 

So as not to break pre-0.1.0 implementations, the old method still works (which also defaults to headless):

virtualbox.start("machine_name", function (error) {
  if (error) throw error;
  console.log("Virtual Machine has started HEADLESS!");
});

:warning: Note: For historical reasons, .stop is an alias to .savestate.

virtualbox.stop("machine_name", function (error) {
  if (error) throw error;
  console.log("Virtual Machine has been saved");
});
 

To halt a machine completely, you can use poweroff or acpipowerbutton:

virtualbox.poweroff("machine_name", function (error) {
  if (error) throw error;
  console.log("Virtual Machine has been powered off!");
});
virtualbox.acpipowerbutton("machine_name", function (error) {
  if (error) throw error;
  console.log("Virtual Machine's ACPI power button was pressed.");
});

Noting the caveat above that .stop is actually an alias to .savestate...

virtualbox.pause("machine_name", function (error) {
  if (error) throw error;
  console.log("Virtual Machine is now paused!");
});
virtualbox.savestate("machine_name", function (error) {
  if (error) throw error;
  console.log("Virtual Machine is now paused!");
});

And, in the same family, acpisleepbutton:

virtualbox.savestate("machine_name", function (error) {
  if (error) throw error;
  console.log("Virtual Machine's ACPI sleep button signal was sent.");
});

Note that you should probably resume a machine which is in one of the above three states.

virtualbox.resume("machine_name", function (error) {
  if (error) throw error;
  console.log("Virtual Machine is now paused!");
});

And, of course, a reset button method:

virtualbox.reset("machine_name", function (error) {
  if (error) throw error;
  console.log("Virtual Machine's reset button was pressed!");
});

Controlling the guest OS

This method takes an options object with the name of the virtual machine, the path to the binary to be executed and any parameters to pass:

var options = {
  vm: "machine_name",
  cmd: "C:\\Program Files\\Internet Explorer\\iexplore.exe",
  params: "https://google.com"
}
 
virtualbox.exec(options, function (error) {
    if (error) throw error;
    console.log('Started Internet Explorer...');
});

Pass username and password information in an options object:

var options = {
  vm: "machine_name",
  user:"Administrator",
  password: "123456",
  cmd: "C:\\Program Files\\Internet Explorer\\iexplore.exe",
  params: "https://google.com"
};

Tasks can be killed in the guest as well. In Windows guests this calls taskkill.exe /im and on Linux, BSD and OS X (Darwin) guests, it calls sudo killall:

virtualbox.kill({
    vm: "machine_name",
    cmd: "iexplore.exe"
}, function (error) {
    if (error) throw error;
    console.log('Terminated Internet Explorer.');
});

Meta information about machine

List all registered machines, returns an array:

virtualbox.list(function (machineserror) {
  if (error) throw error;
  // Act on machines 
});

Obtaining a guest property by key name:

var options = {
  vm: "machine_name",
  key: "/VirtualBox/GuestInfo/Net/0/V4/IP"
}
 
virtualbox.guestproperty(function (machineserror) {
  if (error) throw error;
  // Act on machines 
});

Puttig it all together

var virtualbox = require('virtualbox');
 
virtualbox.start("machine_name", function (error) {
 
    if (error) throw error;
 
    console.log('VM "w7" has been successfully started');
 
    virtualbox.exec({
        vm: "machine_name",
        cmd: "C:\\Program Files\\Internet Explorer\\iexplore.exe",
        params: "http://google.com"
    }, function (error) {
 
        if (error) throw error;
        console.log('Running Internet Explorer...');
 
    });
 
});

Available Methods

virtualbox

  • .pause({vm:"machine_name"}, callback)
  • .reset({vm:"machine_name"}, callback)
  • .resume({vm:"machine_name"}, callback)
  • .start({vm:"machine_name"}, callback) and .start({vm:"machine_name"}, true, callback)
  • .stop({vm:"machine_name"}, callback)
  • .savestate({vm:"machine_name"}, callback)
  • .poweroff({vm:"machine_name"}, callback)
  • .acpisleepbutton({vm:"machine_name"}, callback)
  • .acpipowerbutton({vm:"machine_name"}, callback)
  • .guestproperty({vm:"machine_name", property: "propname"}, callback)
  • .exec(){vm: "machine_name", cmd: "C:\\Program Files\\Internet Explorer\\iexplore.exe", params: "http://google.com"}, callback)
  • .exec(){vm: "machine_name", user:"Administrator", password: "123456", cmd: "C:\\Program Files\\Internet Explorer\\iexplore.exe", params: "http://google.com"}, callback)
  • .kill({vm:"machine_name"}, callback)
  • .list(callback)

Troubleshooting

  • Make sure that Guest account is enabled on the VM.
  • Make sure your linux guest can sudo with NOPASSWD (at least for now).
  • VMs start headlessly by default: if you're having trouble with executing a command, start the VM with GUI and observe the screen after executing same command.
  • To avoid having "Concurrent guest process limit is reached" error message, execute your commands as an administrator.
  • Don't forget that this whole thing is asynchronous, and depends on the return of vboxmanage not the actual running state/runlevel of services within the guest. See https://github.com/azer/node-virtualbox/issues/9

More Examples