The cl-virtualbox Reference Manual

This is the cl-virtualbox Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 04:36:04 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 cl-virtualbox

Control VirtualBox from Common Lisp

Author

Fernando Borretti

Home Page

https://github.com/eudoxia0/cl-virtualbox

License

MIT

Long Description

‘cl-virtualbox‘ is a library that allows you to control VirtualBox from Common Lisp, by calling the ‘vboxmanage‘ command.

# Usage

## Listing VMs

* ‘list-vms ()‘: Return a list of plists with the :name and :uuid of every virtual machine.

* ‘list-running-vms ()‘: Like ‘list-vms‘, but only return the VMs that are running.

Examples:

~~~lisp
virtualbox> (list-vms)
((:uuid "68fdde1a-a009-4c6f-af6e-250ef879e3e7" :name "crane_ubuntu_1410013141185_11153")
(:uuid "b0ebec92-85cb-408c-b32c-c969e6392d5f" :name "vm_ubuntu_1410966111913_95217")
(:uuid "9ad98045-5109-4233-8b82-4c9a49b4cab7" :name "trivial-ssh_default_1411575480546_50302")
(:uuid "5d287f3c-9b17-4a66-990a-80d4db3167ae" :name "windows")) virtualbox> (list-running-vms)
nil
~~~

## Finding VMs

* ‘find-by-name (name)‘: Find a virtual machine by name.

* ‘find-by-uuid (uuid)‘: Find a virtual machine by UUID.

Examples:

~~~lisp
virtualbox> (find-by-name "crane_ubuntu_1410013141185_11153")
(:uuid "68fdde1a-a009-4c6f-af6e-250ef879e3e7" :name "crane_ubuntu_1410013141185_11153")
virtualbox> (find-by-uuid "9ad98045-5109-4233-8b82-4c9a49b4cab7")
(:uuid "9ad98045-5109-4233-8b82-4c9a49b4cab7" :name "trivial-ssh_default_1411575480546_50302")
~~~

## Creating and Modifying VMs

* ‘create-vm (name)‘: Create a new virtual machine named ‘name‘.

* ‘set-vm-memory (name memory)‘: Set the VM’s memory (In megabytes)

* ‘set-vm-vram (name memory)‘: The the VM’s video memory (In megabytes).

* ‘set-vm-cpu-count (name count)‘: Set the number of virtual CPUs the VM has.

* ‘set-vm-acpi (name state)‘: Turn ACPI support on/off.

* ‘set-vm-ioapic (name state)‘: Turn IOAPIC support on/off.

* ‘set-vm-pae (name state)‘: Enable/disable PAE.

* ‘set-vm-longmode (name state)‘: Enable/disable longmode.

* ‘set-vm-hpet (name state)‘: Enable/disable the High-Precision Event Timer (HPET).

* ‘set-vm-3d-acceleration (name state)‘: Enable/disable 3D acceleration.

## Network Configuration

* ‘map-vm-ports (name host-port guest-port)‘: Map TCP traffic from ‘host-port‘ to ‘guest-ip:guest-port‘ in the guest.

## Controlling VM State

* ‘start-vm (name &key (type headless))‘: Start the virtual machine.

* ‘pause-vm (name)‘: Pause the virtual machine.

* ‘resume-vm (name)‘: Resume the virtual machine after pausing it.

* ‘cold-reboot-vm (name)‘: Reboot the virtual machine.

* ‘poweroff-vm (name)‘: Power off the virtual machine.

## Managing Hard Drives

* ‘create-hd (path &key size (format vdi))‘: Create a virtual hard drive on ‘path‘, with size ‘size‘ (In megabytes) and type ‘type‘ (:vdi by default).

## Managing DVDs

* ‘mount-dvd (name path)‘: Mount a DVD to the virtual machine.

* ‘unmount-dvd (name)‘: Remove the DVD from the virtual DVD drive.

# License

Copyright (c) 2014-2018 Fernando Borretti (eudoxiahp@gmail.com)

Licensed under the MIT License.

Version

0.1

Dependencies
  • cl-ppcre (system).
  • uiop (system).
  • alexandria (system).
  • usocket (system).
Source

cl-virtualbox.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 cl-virtualbox/src

Source

cl-virtualbox.asd.

Parent Component

cl-virtualbox (system).

Child Component

cl-virtualbox.lisp (file).


4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 cl-virtualbox/cl-virtualbox.asd

Source

cl-virtualbox.asd.

Parent Component

cl-virtualbox (system).

ASDF Systems

cl-virtualbox.

Packages

cl-virtualbox-asd.


4.1.2 cl-virtualbox/src/cl-virtualbox.lisp

Source

cl-virtualbox.asd.

Parent Component

src (module).

Packages

cl-virtualbox.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 cl-virtualbox

Source

cl-virtualbox.lisp.

Nickname

virtualbox

Use List

common-lisp.

Public Interface
Internals

5.2 cl-virtualbox-asd

Source

cl-virtualbox.asd.

Use List
  • asdf/interface.
  • common-lisp.

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Special variables

Special Variable: *vboxmanage-path*

The path to the VBoxManage command.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.


6.1.2 Ordinary functions

Function: attach-hd (name pathname &optional controller device port)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: cold-reboot-vm (name)

Reboot the virtual machine.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: configure-network (name network-name ip-address lower-ip upper-ip &optional network-mask)

The hard way to set an IP address.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: create-hd (path &key size format)

Create a virtual hard drive on ‘path‘, with size ‘size‘ (In megabytes) and type ‘type‘ (:vdi by default).

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: create-vm (name)

Create a new virtual machine named ‘name‘.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: execute (name image username password &key wait-stdout)

Execute ‘image‘ on the virtual machine ‘name‘, under the account ‘username‘ and ‘password‘. If ‘wait-stdout‘ is true, wait for the program to finish and print its output.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: find-by-name (name)

Find a virtual machine by name.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: find-by-uuid (uuid)

Find a virtual machine by UUID.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: import-vm (ovf-path &optional name)

Import a virtual machine from an OVF file.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: list-host-only-ifs ()

List host only interfaces.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: list-running-vms ()

Like ‘list-vms‘, but only return the VMs that are running.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: list-vms ()

Return a list of plists with the :name and :uuid of every virtual machine.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: map-vm-ports (name host-port guest-ip guest-port)

Map TCP traffic from ‘host-port‘ to ‘guest-ip:guest-port‘ in the guest.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: mount-dvd (name path)

Mount a DVD to the virtual machine.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: pause-vm (name)

Pause the virtual machine.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: poweroff-vm (name)

Power off the virtual machine.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: resume-vm (name)

Resume the virtual machine after pausing it.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: send-virtual-input (name input-list)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: set-vm-3d-acceleration (name state)

Enable/disable 3D acceleration.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: set-vm-acpi (name state)

Turn ACPI support on/off.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: set-vm-cpu-count (name count)

Set the number of virtual CPUs the VM has.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: set-vm-hpet (name state)

Enable/disable the High-Precision Event Timer (HPET).

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: set-vm-ioapic (name state)

Turn IOAPIC support on/off.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: set-vm-ip (name network-name ip-address)

The easy way to set an IP address.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: set-vm-longmode (name state)

Enable/disable longmode.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: set-vm-memory (name memory)

Set the VM’s memory (In megabytes)

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: set-vm-pae (name state)

Enable/disable PAE.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: set-vm-vram (name memory)

The the VM’s video memory (In megabytes).

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: start-vm (name &key type)

Start the virtual machine.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: unmount-dvd (name)

Remove the DVD from the virtual DVD drive.

Package

cl-virtualbox.

Source

cl-virtualbox.lisp.


6.2 Internals


6.2.1 Special variables

Special Variable: +character-scancode-map+
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Special Variable: +special-scancode-map+
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.


6.2.2 Ordinary functions

Function: bool->str (bool)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: cmd (command-format &rest args)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: keyword->scancodes (keyword)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: keyword->str (keyword)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: parse-key-value (string)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: parse-list-line (line)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: parse-report (string)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: parse-vm-list (string)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: run-cmd (command)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: send-scancodes (name scancodes)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: split-by-double-newlines (string)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: split-by-newlines (string)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.

Function: string->scancodes (string)
Package

cl-virtualbox.

Source

cl-virtualbox.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   B   C   E   F   I   K   L   M   P   R   S   U  
Index Entry  Section

A
attach-hd: Public ordinary functions

B
bool->str: Private ordinary functions

C
cmd: Private ordinary functions
cold-reboot-vm: Public ordinary functions
configure-network: Public ordinary functions
create-hd: Public ordinary functions
create-vm: Public ordinary functions

E
execute: Public ordinary functions

F
find-by-name: Public ordinary functions
find-by-uuid: Public ordinary functions
Function, attach-hd: Public ordinary functions
Function, bool->str: Private ordinary functions
Function, cmd: Private ordinary functions
Function, cold-reboot-vm: Public ordinary functions
Function, configure-network: Public ordinary functions
Function, create-hd: Public ordinary functions
Function, create-vm: Public ordinary functions
Function, execute: Public ordinary functions
Function, find-by-name: Public ordinary functions
Function, find-by-uuid: Public ordinary functions
Function, import-vm: Public ordinary functions
Function, keyword->scancodes: Private ordinary functions
Function, keyword->str: Private ordinary functions
Function, list-host-only-ifs: Public ordinary functions
Function, list-running-vms: Public ordinary functions
Function, list-vms: Public ordinary functions
Function, map-vm-ports: Public ordinary functions
Function, mount-dvd: Public ordinary functions
Function, parse-key-value: Private ordinary functions
Function, parse-list-line: Private ordinary functions
Function, parse-report: Private ordinary functions
Function, parse-vm-list: Private ordinary functions
Function, pause-vm: Public ordinary functions
Function, poweroff-vm: Public ordinary functions
Function, resume-vm: Public ordinary functions
Function, run-cmd: Private ordinary functions
Function, send-scancodes: Private ordinary functions
Function, send-virtual-input: Public ordinary functions
Function, set-vm-3d-acceleration: Public ordinary functions
Function, set-vm-acpi: Public ordinary functions
Function, set-vm-cpu-count: Public ordinary functions
Function, set-vm-hpet: Public ordinary functions
Function, set-vm-ioapic: Public ordinary functions
Function, set-vm-ip: Public ordinary functions
Function, set-vm-longmode: Public ordinary functions
Function, set-vm-memory: Public ordinary functions
Function, set-vm-pae: Public ordinary functions
Function, set-vm-vram: Public ordinary functions
Function, split-by-double-newlines: Private ordinary functions
Function, split-by-newlines: Private ordinary functions
Function, start-vm: Public ordinary functions
Function, string->scancodes: Private ordinary functions
Function, unmount-dvd: Public ordinary functions

I
import-vm: Public ordinary functions

K
keyword->scancodes: Private ordinary functions
keyword->str: Private ordinary functions

L
list-host-only-ifs: Public ordinary functions
list-running-vms: Public ordinary functions
list-vms: Public ordinary functions

M
map-vm-ports: Public ordinary functions
mount-dvd: Public ordinary functions

P
parse-key-value: Private ordinary functions
parse-list-line: Private ordinary functions
parse-report: Private ordinary functions
parse-vm-list: Private ordinary functions
pause-vm: Public ordinary functions
poweroff-vm: Public ordinary functions

R
resume-vm: Public ordinary functions
run-cmd: Private ordinary functions

S
send-scancodes: Private ordinary functions
send-virtual-input: Public ordinary functions
set-vm-3d-acceleration: Public ordinary functions
set-vm-acpi: Public ordinary functions
set-vm-cpu-count: Public ordinary functions
set-vm-hpet: Public ordinary functions
set-vm-ioapic: Public ordinary functions
set-vm-ip: Public ordinary functions
set-vm-longmode: Public ordinary functions
set-vm-memory: Public ordinary functions
set-vm-pae: Public ordinary functions
set-vm-vram: Public ordinary functions
split-by-double-newlines: Private ordinary functions
split-by-newlines: Private ordinary functions
start-vm: Public ordinary functions
string->scancodes: Private ordinary functions

U
unmount-dvd: Public ordinary functions