A library to interact with VirtualBox.
npm install virtualbox!NPM version
A JavaScript library to interact with VirtualBox virtual machines.
- Installation
- Controlling Power and State - Starting a cold machine: Two ways - Stopping a machine - Pausing, Saving and Resuming a machine
- Import a Machine
- Export a Machine
- Snapshot Manage
- Cloning a VM
- Storage - Manage the IDE controller - Attach a disk image file
- Controlling the guest OS - A note about security :warning: - Running programs in the guest - Executing commands as Administrators on Windows guests - Killing programs in the guest - Sending keystrokes to a virtual machine
- Meta information about machine
- Putting it all together
- Available Methods
- Troubleshooting
- More Examples
- License (MIT)
- Contributing
- Testing
Obtain the package
``bash`
$ npm install virtualbox [--save] [-g]
and then use it
`javascript`
var virtualbox = require('virtualbox');
The general formula for commands is:
> virtualbox. API command ( "registered vm name", [parameters], callback );
Available API commands are listed at the end of this document.
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:
`javascript`
virtualbox.start('machine_name', true, function start_callback(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):
`javascript`
virtualbox.start('machine_name', function start_callback(error) {
if (error) throw error;
console.log('Virtual Machine has started HEADLESS!');
});
Note: For historical reasons, .stop is an alias to .savestate.
`javascript`
virtualbox.stop('machine_name', function stop_callback(error) {
if (error) throw error;
console.log('Virtual Machine has been saved');
});
To halt a machine completely, you can use poweroff or acpipowerbutton:
`javascript`
virtualbox.poweroff('machine_name', function poweroff_callback(error) {
if (error) throw error;
console.log('Virtual Machine has been powered off!');
});
`javascript`
virtualbox.acpipowerbutton('machine_name', function acpipower_callback(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...
`javascript`
virtualbox.pause('machine_name', function pause_callback(error) {
if (error) throw error;
console.log('Virtual Machine is now paused!');
});
`javascript`
virtualbox.savestate('machine_name', function save_callback(error) {
if (error) throw error;
console.log('Virtual Machine is now paused!');
});
And, in the same family, acpisleepbutton:
`javascript`
virtualbox.acpisleepbutton('machine_name', function acpisleep_callback(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.
`javascript`
virtualbox.resume('machine_name', function resume_callback(error) {
if (error) throw error;
console.log('Virtual Machine is now paused!');
});
And, of course, a reset button method:
`javascript`
virtualbox.reset('machine_name', function reset_callback(error) {
if (error) throw error;
console.log("Virtual Machine's reset button was pressed!");
});
You can import an OVA or OVF file with the vmImport method:
`javascript`
virtualbox.vmImport('ova_file_path', options, function import_callback(error) {
if (error) throw error;
console.log('Virtual Machine was imported!');
});
The options object may contain optional parameters:
* vmname: the name of the new VM.cpus
* : the number of CPUs.memory
* : the amount of memory in megabytes.
You can export with vmExport method:
`javascript`
virtualbox.vmExport('machine_name', 'output', function export_callback(error) {
if (error) throw error;
console.log('Virtual Machine was exported!');
});
You can show snapshot list with snapshotList method:
`javascript`
virtualbox.snapshotList('machine_name', function (
error,
snapshotList,
currentSnapshotUUID
) {
if (error) throw error;
if (snapshotList) {
console.log(
JSON.stringify(snapshotList),
JSON.stringify(currentSnapshotUUID)
);
}
});
And, you can take a snapshot:
`javascript`
virtualbox.snapshotTake('machine_name', 'snapshot_name', function (
error,
uuid
) {
if (error) throw error;
console.log('Snapshot has been taken!');
console.log('UUID: ', uuid);
});
Or, delete a snapshot:
`javascript`
virtualbox.snapshotDelete('machine_name', 'snapshot_name', function (error) {
if (error) throw error;
console.log('Snapshot has been deleted!');
});
Or, restore a snapshot:
`javascript`
virtualbox.snapshotRestore('machine_name', 'snapshot_name', function (error) {
if (error) throw error;
console.log('Snapshot has been restored!');
});
Make a full clone (duplicate virtual hard drive) of a machine:
`javascript`
virtualbox.clone('source_machine_name', 'new_machine_name', function (error) {
if (error) throw error;
console.log('Done fully cloning the virtual machine!');
});
Make a linked clone (interdependent-differentially stored virtual hard drive) of a machine:
`javascript`
virtualbox.snapshotTake('machine_name', 'snapshot_name', function (
error,
uuid
) {
if (error) throw error;
console.log('Snapshot has been taken!');
console.log('UUID: ', uuid);
virtualbox.clone(
'machine_name',
'new_machine_name',
'snapshot_name',
function (error) {
if (error) throw error;
console.log('Done making a linked clone of the virtual machine!');
}
);
});
In case the VM doesn't have an IDE controller you can use the storagectl command to add one:
`javascript`
virtualbox.storage.addCtl(
{
vm: 'machine_name',
perhiperal_name: 'IDE', //optional
type: 'ide', //optional
},
function () {
console.log('Controller has been added!');
}
);
Mount an ISO file to the added controller:
`javascript`
virtualbox.storage.attach(
{
vm: 'machine_name',
perhiperal_name: 'IDE', //optional
port: '0', //optional
device: '0', //optional
type: 'dvddrive', //optional
medium: 'X:Foldercontaining\the.iso',
},
function () {
console.log('Image has been mounted!');
}
);
The _medium_ parameter of the options object can be set to the none value to unmount.
node-virtualbox is not opinionated: we believe that _you know best_ what _you_ need to do with _your_ virtual machine. Maybe that includes issuing sudo rm -rf / for some reason.
To that end, the virtualbox APIs provided by this module _take absolutely no steps_ to prevent you shooting yourself in the foot.
:warning: Therefore, if you accept user input and pass it to the virtual machine, you should take your own steps to filter input before it gets passed to virtualbox.
For more details and discussion, see issue #29.
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:
`javascript
var options = {
vm: 'machine_name',
cmd: 'C:\\Program Files\\Internet Explorer\\iexplore.exe',
params: 'https://google.com',
};
virtualbox.exec(options, function exec_callback(error, stdout) {
if (error) throw error;
console.log('Started Internet Explorer...');
});
`
Pass username and password information in an options object:
`javascript`
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:
`javascript`
virtualbox.kill(
{
vm: 'machine_name',
cmd: 'iexplore.exe',
},
function kill_callback(error) {
if (error) throw error;
console.log('Terminated Internet Explorer.');
}
);
Keyboard scan code sequences can be piped directly to a virtual machine's console:
`javascript
var SCAN_CODES = virtualbox.SCAN_CODES;
var sequence = [
{ key: 'SHIFT', type: 'make', code: SCAN_CODES['SHIFT'] },
{ key: 'A', type: 'make', code: SCAN_CODES['A'] },
{ key: 'SHIFT', type: 'break', code: SCAN_CODES.getBreakCode('SHIFT') },
{ key: 'A', type: 'break', code: SCAN_CODES.getBreakCode('A') },
];
virtualbox.keyboardputscancode(
'machine_name',
sequence,
function keyscan_callback(err) {
if (error) throw error;
console.log('Sent SHIFT A');
}
);
`
List all registered machines, returns an array:
`javascript`
virtualbox.list(function list_callback(machines, error) {
if (error) throw error;
// Act on machines
});
Obtaining a guest property by key name:
`javascript
var options = {
vm: 'machine_name',
key: '/VirtualBox/GuestInfo/Net/0/V4/IP',
};
virtualbox.guestproperty.get(options, function guestproperty_callback(machines, error) {
if (error) throw error;
// Act on machines
});
`
Obtaining an extra property by key name:
`javascript
var options = {
vm: 'machine_name',
key: 'GUI/Fullscreen',
};
virtualbox.extradata.get(options, function extradataget_callback(error, value) {
if (error) throw error;
console.log(
'Virtual Machine "%s" extra "%s" value is "%s"',
options.vm,
options.key,
value
);
});
`
Writing an extra property by key name:
`javascript
var options = {
vm: 'machine_name',
key: 'GUI/Fullscreen',
value: 'true',
};
virtualbox.extradata.set(options, function extradataset_callback(error) {
if (error) throw error;
console.log(
'Set Virtual Machine "%s" extra "%s" value to "%s"',
options.vm,
options.key,
options.value
);
});
`
_Note: some properties are only available/effective if the Guest OS has the (https://www.virtualbox.org/manual/ch04.html)[Guest Additions] installed and running._
`javascript
var virtualbox = require('virtualbox');
virtualbox.start('machine_name', function start_callback(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...');
}
);
});
`
virtualbox
- .pause({vm:"machine_name"}, callback)
-
-
- and .start({vm:"machine_name"}, true, callback)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Make sure that Guest account is enabled on the VM.
- Make sure your linux guest can sudo with NOPASSWD (at least for now).vboxmanage
- 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 _not_ the actual running state/runlevel of services within the guest. See
Please do!
- File an issue
- Fork and send a pull request.
Please abide by the Contributor Code of Conduct.
We currently do not have a complete unit testing suite. However, example scripts and a Vagrantfile are provided. Test your changes by writing a new script and/or running through all the test scripts to make sure they behave as expected. To do this install vagrant and run vagrant up in this repository's root directory. Then run the example scripts by using node: node test/integration/