virtualbox

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2017 License: Apache-2.0 Imports: 15 Imported by: 7

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 (
	HOST_MODE_DISCONNECTED = 1 << iota
	HOST_MODE_PIPE
	HOST_MODE_DEVICE
	HOST_MODE_RAW_FILE
)
View Source 
const (
	SysBusIDE    = SystemBus("ide")
	SysBusSATA   = SystemBus("sata")
	SysBusSCSI   = SystemBus("scsi")
	SysBusSAS    = SystemBus("sas")
	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")
)
View Source 
const (
	DriveMNormal       = DriveMType("normal")
	DriveMWritethrough = DriveMType("writethrough")
	DriveMImmutable    = DriveMType("immutable")
	DriveMShareable    = DriveMType("shareable")
	DriveMReadonly     = DriveMType("readonly")
	DriveMMultiattach  = DriveMType("multiattach")
)

Variables

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")
)
View Source 
var (
	VBM string // Path to VBoxManage utility.
)

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 ConvertRawToImage 

func ConvertRawToImage(filename, dest, format string) error

Convert the raw format device to vmdk format

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 GetMediumUUID 

func GetMediumUUID(disk string) (string, error)

func HostonlyNets 

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

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

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 RegisterDisk 

func RegisterDisk(mName, sName, disk string, port int) error

func SetExtra 

func SetExtra(name, key, val string) error

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

func SetNATPF 

func SetNATPF(vmId string, n int, name string, rule PFRule) error

func UnregisterDisk 

func UnregisterDisk(mName, disk string) error

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 DriveMType 

type DriveMType string

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}
}

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 ListMachines 

func ListMachines() ([]*Machine, error)

ListMachines lists all registered machines.

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) AddSharedFolder 

func (m *Machine) AddSharedFolder(name string, sFolder SharedFolder) error

AddSharedFolder adds a shared folder with the given machine

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) AttachStorageWithOutput 

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

AttachStorage attaches a storage medium to the named storage controller.

func (*Machine) CreateSerialPort 

func (m *Machine) CreateSerialPort(hostFile, portNum, ioBase, irq string, sType PortMode, server bool) error

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) DelNIC 

func (m *Machine) DelNIC(n int) error

DelNIC disable 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(extra []string) error

Modify changes the settings of the machine.

func (*Machine) ModifyNIC 

func (m *Machine) ModifyNIC(n int, nicType NICNetwork, device string) error

SetNIC set the n-th NIC.

func (*Machine) NicConf 

func (m *Machine) NicConf(n int, nic NIC) []string

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) RemoveSharedFolder 

func (m *Machine) RemoveSharedFolder(name, shareFolderName string) error

DelSharedFolder deletes a shared folder with the given machine

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) SerialPortConf 

func (m *Machine) SerialPortConf(hostFile, portNum, ioBase, irq string, sType PortMode, server bool) []string

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.

func (*Machine) StopSerialPort 

func (m *Machine) StopSerialPort(portNum string) error

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
	BridgedAdapter  string
	NatNet          string
	NatSetting      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 PortMode 

type PortMode int

type SerialPort 

type SerialPort struct {
	HostFile   string
	PortNum    string
	IoBase     string
	Irq        string
	SType      PortMode
	ServerMode bool
}

type SharedFolder 

type SharedFolder struct {
	Name      string
	Path      string
	Automount bool
	Transient bool
	Readonly  bool
}

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
	MType     DriveMType
	SSD       bool
}

StorageMedium represents the storage medium attached to a storage controller.

type SystemBus 

type SystemBus string

SystemBus represents the system bus of a storage controller.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.