Crate vboxhelper

This crate is probably not what you hoped it was – in fact, it’s probably exactly what you feared. Rather than integrate against VirtualBox’s COM interfaces it will call the command line tools and parse their outputs.

Perhaps not surprisingly, this crate originally began as a bash script and slowly morphed into what it is today.

Examples

Terminate a virtual machine named myvm and revert it to a snapshot named mysnap.

use std::time::Duration;
use vboxhelper::*;

let vm = "myvm".parse::<VmId>().unwrap();
controlvm::kill(&vm).unwrap();

let ten_seconds = Duration::new(10, 0);
wait_for_croak(&vm, Some((ten_seconds, TimeoutAction::Error)));

// revert to a snapshot
let snap = "mysnap".parse::<snapshot::SnapshotId>().unwrap();
snapshot::restore(&vm, Some(snap)).unwrap();

VirtualBox Versions

This crate will generally attempt to track the latest version of VirtualBox.

Environment variables

In some cases vboxhelper will execute external commands with no intention of parsing their output. In these situations vboxhelper will by default consume the child processes’ output. This behavior can be changed by setting the VBOXHELPER_VERBOSE environment variable; setting its value to "1" will cause the library to output to be directed to stdout and stderr respectively.

If the variable VBOXHELPER_LOGS is set to a valid directory vboxhelper may use it to store log files.

Re-exports

pub use err::Error;

pub use vmid::VmId;

Modules

controlvm

Control the run state of a virtual machine.

err

guest

nics

snapshot

Manage virtual machine snapshots.

storage

vmid

Abstraction of a virtual machine identifier.

Structs

VmInfo

A structured representation of a virtual machine’s state and configuration.

Enums

Headless

Control whether running a VM headless should block until VM terminates or if it should return as soon as the VM has been started in the background.

RunContext

Control whether a virtual machine is run with a GUI or in Headless mode.

Shutdown

TimeoutAction

VmState

VirtualBox virtual machine states.

Functions

get_pid

Get the process id of the guest virtual machine.

get_running_vms_list

Get a list of all running virtual machines.

get_vm_info

Get structured information about a virtual machine.

get_vm_info_map

Get information about a virtual machine as a map.

get_vm_list

Get a list of virtual machines.

have_vm

is_vm_running

is_vm_state

Check whether a virtual machine is currently in a certain state.

try_get_pid

Wrapper method around get_pid() to retry getting the guest’s PID.

wait_for_croak

Wait for a virtual machine to self-terminate.

wait_for_state

Wait for a virtual machine to enter an expected state.