virtualbox

package
v1.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 24, 2014 License: Apache-2.0 Imports: 15 Imported by: 0

README

go-virtualbox

This is a wrapper package for Golang to interact with VirtualBox. The API is experimental at the moment and you should expect frequent changes.

API doc at http://godoc.org/github.com/riobard/go-virtualbox

Documentation

Overview

Package virtualbox implements wrappers to interact with VirtualBox.

VirtualBox Machine State Transition

A VirtualBox machine can be in one of the following states:

poweroff: The VM is powered off and no previous running state saved.
running: The VM is running.
paused: The VM is paused, but its state is not saved to disk. If you quit VirtualBox, the state will be lost.
saved: The VM is powered off, and the previous state is saved on disk.
aborted: The VM process crashed. This should happen very rarely.

VBoxManage supports the following transitions between states:

startvm <VM>: poweroff|saved --> running
controlvm <VM> pause: running --> paused
controlvm <VM> resume: paused --> running
controlvm <VM> savestate: running -> saved
controlvm <VM> acpipowerbutton: running --> poweroff
controlvm <VM> poweroff: running --> poweroff (unsafe)
controlvm <VM> reset: running --> poweroff --> running (unsafe)

Poweroff and reset are unsafe because they will lose state and might corrupt the disk image.

To make things simpler, the following transitions are used instead:

start: poweroff|saved|paused|aborted --> running
stop: [paused|saved -->] running --> poweroff
save: [paused -->] running --> saved
restart: [paused|saved -->] running --> poweroff --> running
poweroff: [paused|saved -->] running --> poweroff (unsafe)
reset: [paused|saved -->] running --> poweroff --> running (unsafe)

The takeaway is we try our best to transit the virtual machine into the state you want it to be, and you only need to watch out for the potentially unsafe poweroff and reset.

Index

Constants

View Source
const (
	Poweroff = MachineState("poweroff")
	Running  = MachineState("running")
	Paused   = MachineState("paused")
	Saved    = MachineState("saved")
	Aborted  = MachineState("aborted")
)
View Source
const (
	NICNetAbsent       = NICNetwork("none")
	NICNetDisconnected = NICNetwork("null")
	NICNetNAT          = NICNetwork("nat")
	NICNetBridged      = NICNetwork("bridged")
	NICNetInternal     = NICNetwork("intnet")
	NICNetHostonly     = NICNetwork("hostonly")
	NICNetGeneric      = NICNetwork("generic")
)
View Source
const (
	AMDPCNetPCIII         = NICHardware("Am79C970A")
	AMDPCNetFASTIII       = NICHardware("Am79C973")
	IntelPro1000MTDesktop = NICHardware("82540EM")
	IntelPro1000TServer   = NICHardware("82543GC")
	IntelPro1000MTServer  = NICHardware("82545EM")
	VirtIO                = NICHardware("virtio")
)
View Source
const (
	PFTCP = PFProto("tcp")
	PFUDP = PFProto("udp")
)
View Source
const (
	SysBusIDE    = SystemBus("ide")
	SysBusSATA   = SystemBus("sata")
	SysBusSCSI   = SystemBus("scsi")
	SysBusFloppy = SystemBus("floppy")
)
View Source
const (
	CtrlLSILogic    = StorageControllerChipset("LSILogic")
	CtrlLSILogicSAS = StorageControllerChipset("LSILogicSAS")
	CtrlBusLogic    = StorageControllerChipset("BusLogic")
	CtrlIntelAHCI   = StorageControllerChipset("IntelAHCI")
	CtrlPIIX3       = StorageControllerChipset("PIIX3")
	CtrlPIIX4       = StorageControllerChipset("PIIX4")
	CtrlICH6        = StorageControllerChipset("ICH6")
	CtrlI82078      = StorageControllerChipset("I82078")
)
View Source
const (
	DriveDVD = DriveType("dvddrive")
	DriveHDD = DriveType("hdd")
	DriveFDD = DriveType("fdd")
)

Variables

View Source
var (
	VBM     string // Path to VBoxManage utility.
	Verbose bool   // Verbose mode.
)
View Source
var (
	ErrMachineExist    = errors.New("machine already exists")
	ErrMachineNotExist = errors.New("machine does not exist")
	ErrVBMNotFound     = errors.New("VBoxManage not found")
)
View Source
var (
	ErrHostonlyInterfaceCreation = errors.New("failed to create hostonly interface")
)

Functions

func AddHostonlyDHCP

func AddHostonlyDHCP(ifname string, d DHCP) error

AddHostonlyDHCP adds a DHCP server to a host-only network.

func AddInternalDHCP

func AddInternalDHCP(netname string, d DHCP) error

AddInternalDHCP adds a DHCP server to an internal network.

func DHCPs

func DHCPs() (map[string]*DHCP, error)

DHCPs gets all DHCP server settings in a map keyed by DHCP.NetworkName.

func DelExtra

func DelExtra(name, key string) error

DelExtraData deletes extra data. Name could be "global"|<uuid>|<vmname>

func HostonlyNets

func HostonlyNets() (map[string]*HostonlyNet, error)

HostonlyNets gets all host-only networks in a map keyed by HostonlyNet.NetworkName.

func ListMachines

func ListMachines() ([]string, error)

ListMachines lists all registered machines.

func MakeDiskImage

func MakeDiskImage(dest string, size uint, r io.Reader) error

MakeDiskImage makes a disk image at dest with the given size in MB. If r is not nil, it will be read as a raw disk image to convert from.

func NATNets

func NATNets() (map[string]NATNet, error)

NATNets gets all NAT networks in a map keyed by NATNet.Name.

func ParseIPv4Mask

func ParseIPv4Mask(s string) net.IPMask

ParseIPv4Mask parses IPv4 netmask written in IP form (e.g. 255.255.255.0). This function should really belong to the net package.

func SetExtra

func SetExtra(name, key, val string) error

SetExtra sets extra data. Name could be "global"|<uuid>|<vmname>

func ZeroFill

func ZeroFill(w io.Writer, n int64) error

ZeroFill writes n zero bytes into w.

Types

type DHCP

type DHCP struct {
	NetworkName string
	IPv4        net.IPNet
	LowerIP     net.IP
	UpperIP     net.IP
	Enabled     bool
}

DHCP server info.

type DriveType

type DriveType string

DriveType represents the hardware type of a drive.

type Flag

type Flag int
const (
	F_acpi Flag = 1 << iota
	F_ioapic
	F_rtcuseutc
	F_cpuhotplug
	F_pae
	F_longmode
	F_synthcpu
	F_hpet
	F_hwvirtex
	F_triplefaultreset
	F_nestedpaging
	F_largepages
	F_vtxvpid
	F_vtxux
	F_accelerate3d
)

Flag names in lowercases to be consistent with VBoxManage options.

func (Flag) Get

func (f Flag) Get(o Flag) string

Test if flag is set. Return "on" or "off".

type HostonlyNet

type HostonlyNet struct {
	Name        string
	GUID        string
	DHCP        bool
	IPv4        net.IPNet
	IPv6        net.IPNet
	HwAddr      net.HardwareAddr
	Medium      string
	Status      string
	NetworkName string // referenced in DHCP.NetworkName
}

Host-only network.

func CreateHostonlyNet

func CreateHostonlyNet() (*HostonlyNet, error)

CreateHostonlyNet creates a new host-only network.

func (*HostonlyNet) Config

func (n *HostonlyNet) Config() error

Config changes the configuration of the host-only network.

type Machine

type Machine struct {
	Name       string
	UUID       string
	State      MachineState
	CPUs       uint
	Memory     uint // main memory (in MB)
	VRAM       uint // video memory (in MB)
	CfgFile    string
	BaseFolder string
	OSType     string
	Flag       Flag
	BootOrder  []string // max 4 slots, each in {none|floppy|dvd|disk|net}
	DockerPort uint
	SSHPort    uint
	SerialFile string
}

Machine information.

func CreateMachine

func CreateMachine(name, basefolder string) (*Machine, error)

CreateMachine creates a new machine. If basefolder is empty, use default.

func GetMachine

func GetMachine(id string) (*Machine, error)

GetMachine finds a machine by its name or UUID.

func (*Machine) AddNATPF

func (m *Machine) AddNATPF(n int, name string, rule PFRule) error

AddNATPF adds a NAT port forarding rule to the n-th NIC with the given name.

func (*Machine) AddStorageCtl

func (m *Machine) AddStorageCtl(name string, ctl StorageController) error

AddStorageCtl adds a storage controller with the given name.

func (*Machine) AttachStorage

func (m *Machine) AttachStorage(ctlName string, medium StorageMedium) error

AttachStorage attaches a storage medium to the named storage controller.

func (*Machine) DelNATPF

func (m *Machine) DelNATPF(n int, name string) error

DelNATPF deletes the NAT port forwarding rule with the given name from the n-th NIC.

func (*Machine) DelStorageCtl

func (m *Machine) DelStorageCtl(name string) error

DelStorageCtl deletes the storage controller with the given name.

func (*Machine) Delete

func (m *Machine) Delete() error

Delete deletes the machine and associated disk images.

func (*Machine) Modify

func (m *Machine) Modify() error

Modify changes the settings of the machine.

func (*Machine) Pause

func (m *Machine) Pause() error

Pause pauses the execution of the machine.

func (*Machine) Poweroff

func (m *Machine) Poweroff() error

Poweroff forcefully stops the machine. State is lost and might corrupt the disk image.

func (*Machine) Refresh

func (m *Machine) Refresh() error

Refresh reloads the machine information.

func (*Machine) Reset

func (m *Machine) Reset() error

Reset forcefully restarts the machine. State is lost and might corrupt the disk image.

func (*Machine) Restart

func (m *Machine) Restart() error

Restart gracefully restarts the machine.

func (*Machine) Save

func (m *Machine) Save() error

Suspend suspends the machine and saves its state to disk.

func (*Machine) SetNIC

func (m *Machine) SetNIC(n int, nic NIC) error

SetNIC set the n-th NIC.

func (*Machine) Start

func (m *Machine) Start() error

Start starts the machine.

func (*Machine) Stop

func (m *Machine) Stop() error

Stop gracefully stops the machine.

type MachineState

type MachineState string

type NATNet

type NATNet struct {
	Name    string
	IPv4    net.IPNet
	IPv6    net.IPNet
	DHCP    bool
	Enabled bool
}

A NATNet defines a NAT network.

type NIC

type NIC struct {
	Network         NICNetwork
	Hardware        NICHardware
	HostonlyAdapter string
}

NIC represents a virtualized network interface card.

type NICHardware

type NICHardware string

NICHardware represents the type of NIC hardware.

type NICNetwork

type NICNetwork string

NICNetwork represents the type of NIC networks.

type PFProto

type PFProto string

PFProto represents the protocol of a port forwarding rule.

type PFRule

type PFRule struct {
	Proto     PFProto
	HostIP    net.IP // can be nil to match any host interface
	HostPort  uint16
	GuestIP   net.IP // can be nil if guest IP is leased from built-in DHCP
	GuestPort uint16
}

PFRule represents a port forwarding rule.

func (PFRule) Format

func (r PFRule) Format() string

Format returns the string needed as a command-line argument to VBoxManage.

func (PFRule) String

func (r PFRule) String() string

String returns a human-friendly representation of the port forwarding rule.

type StorageController

type StorageController struct {
	SysBus      SystemBus
	Ports       uint // SATA port count 1--30
	Chipset     StorageControllerChipset
	HostIOCache bool
	Bootable    bool
}

StorageController represents a virtualized storage controller.

type StorageControllerChipset

type StorageControllerChipset string

StorageControllerChipset represents the hardware of a storage controller.

type StorageMedium

type StorageMedium struct {
	Port      uint
	Device    uint
	DriveType DriveType
	Medium    string // none|emptydrive|<uuid>|<filename|host:<drive>|iscsi
}

StorageMedium represents the storage medium attached to a storage controller.

type SystemBus

type SystemBus string

SystemBus represents the system bus of a storage controller.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL