On this page:
start-vbox-vm
stop-vbox-vm
take-vbox-snapshot
restore-vbox-snapshot
delete-vbox-snapshot
exists-vbox-snapshot?
get-vbox-snapshot-uuid
import-vbox-vm

3 Managing VirtualBox Machines🔗ℹ

The remote-shell/vbox library provides support for working with VirtualBox instances. The library is a fairly thin wrapper on the VBoxManage command, which is located via find-executable-path.

procedure

(start-vbox-vm name    
  [#:max-vms max-vms    
  #:log-status log-status    
  #:pause-seconds pause-seconds    
  #:dry-run? dry-run?])  void?
  name : string?
  max-vms : real? = 1
  log-status : (string? #:rest any/c . -> . any) = printf
  pause-seconds : real? = 3
  dry-run? : any/c = #f
Starts a VirtualBox virtual machine name that is in a saved, powered off, or running state (where a running machine continues to run).

The start will fail if max-vms virtual machines are already currently running. This limit is a precaution against starting too many virtual-machine instances, which can overwhelm the host operating system.

The log-status argument is used to report actions and status information.

After the machine is started, start-vbox-vm pauses for the amount of time specified by pause-seconds, which gives the virtual machine time to find its bearings.

If dry-run is #t, then the machine is not actually started, but status information is written using log-status to report the action that would have been taken.

procedure

(stop-vbox-vm name    
  [#:save-state? save-state?    
  #:log-status log-status    
  #:dry-run? dry-run?])  void?
  name : string?
  save-state? : any/c = #t
  log-status : (string? #:rest any/c . -> . any) = printf
  dry-run? : any/c = #f
Stops a VirtualBox virtual machine name that is in a running state. If save-state? is true, then the machine is put into saved state, otherwise the current machine state is discarded and the machine is powered off.

The log-status argument is used to report actions and status information.

If dry-run is #t, then the machine is not actually started, but status information is written using log-status to report the action that would have been taken.

procedure

(take-vbox-snapshot name snapshot-name)  void?

  name : string?
  snapshot-name : string?
Takes a snapshot of a virtual machine (which may be running), creating the snapshot named snapshot-name.

procedure

(restore-vbox-snapshot name snapshot-name)  void?

  name : string?
  snapshot-name : string?
Changes the current state of a virtual machine to be the one recorded as snapshot-name. The virtual machine must not be running.

procedure

(delete-vbox-snapshot name snapshot-name)  void?

  name : string?
  snapshot-name : string?
Deletes snapshot-name for the virtual machine name.

procedure

(exists-vbox-snapshot? name snapshot-name)  boolean?

  name : string?
  snapshot-name : string?
Reports whether snapshot-name exists for the virtual machine name.

procedure

(get-vbox-snapshot-uuid name snapshot-name)  (or/c #f string?)

  name : string?
  snapshot-name : string?
Returns the UUID of snapshot-name for the virtual machine name.

Added in version 1.1 of package remote-shell-lib.

procedure

(import-vbox-vm path    
  [#:name name    
  #:cpus cpus    
  #:memory memory])  void?
  path : path-string?
  name : (or/c false/c non-empty-string?) = #f
  cpus : (or/c false/c exact-positive-integer?) = #f
  memory : (or/c false/c exact-positive-integer?) = #f
Imports a VirtualBox VM from the OVF file at path.

When provided, name specifies what the VM’s alias (as seen in the GUI and in the output of commands like VBoxManage list vms) ought to be.

The cpus argument can be used to override the number of processors the VM has access to.

The memory argument can be used to override the amount of RAM (in MB) the VM has access to.

Added in version 1.4 of package remote-shell-lib.