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
- Variables
- func AddHostonlyDHCP(ifname string, d DHCP) error
- func AddInternalDHCP(netname string, d DHCP) error
- func ConvertRawToImage(filename, dest, format string) error
- func DHCPs() (map[string]*DHCP, error)
- func DelExtra(name, key string) error
- func GetMediumUUID(disk string) (string, error)
- func HostonlyNets() (map[string]*HostonlyNet, error)
- func MakeDiskImage(dest string, size uint, r io.Reader) error
- func NATNets() (map[string]NATNet, error)
- func ParseIPv4Mask(s string) net.IPMask
- func RegisterDisk(mName, sName, disk string, port int) error
- func SetExtra(name, key, val string) error
- func SetNATPF(vmId string, n int, name string, rule PFRule) error
- func UnregisterDisk(mName, disk string) error
- func ZeroFill(w io.Writer, n int64) error
- type DHCP
- type DriveMType
- type DriveType
- type Flag
- type HostonlyNet
- type Machine
- func (m *Machine) AddNATPF(n int, name string, rule PFRule) error
- func (m *Machine) AddSharedFolder(name string, sFolder SharedFolder) error
- func (m *Machine) AddStorageCtl(name string, ctl StorageController) error
- func (m *Machine) AttachStorage(ctlName string, medium StorageMedium) error
- func (m *Machine) AttachStorageWithOutput(ctlName string, medium StorageMedium) (string, string, error)
- func (m *Machine) CreateSerialPort(hostFile, portNum, ioBase, irq string, sType PortMode, server bool) error
- func (m *Machine) DelNATPF(n int, name string) error
- func (m *Machine) DelNIC(n int) error
- func (m *Machine) DelStorageCtl(name string) error
- func (m *Machine) Delete() error
- func (m *Machine) Modify(extra []string) error
- func (m *Machine) ModifyNIC(n int, nicType NICNetwork, device string) error
- func (m *Machine) NicConf(n int, nic NIC) []string
- func (m *Machine) Pause() error
- func (m *Machine) Poweroff() error
- func (m *Machine) Refresh() error
- func (m *Machine) RemoveSharedFolder(name, shareFolderName string) error
- func (m *Machine) Reset() error
- func (m *Machine) Restart() error
- func (m *Machine) Save() error
- func (m *Machine) SerialPortConf(hostFile, portNum, ioBase, irq string, sType PortMode, server bool) []string
- func (m *Machine) SetNIC(n int, nic NIC) error
- func (m *Machine) Start() error
- func (m *Machine) Stop() error
- func (m *Machine) StopSerialPort(portNum string) error
- type MachineState
- type NATNet
- type NIC
- type NICHardware
- type NICNetwork
- type PFProto
- type PFRule
- type PortMode
- type SerialPort
- type SharedFolder
- type StorageController
- type StorageControllerChipset
- type StorageMedium
- type SystemBus
Constants ¶
const ( Poweroff = MachineState("poweroff") Running = MachineState("running") Paused = MachineState("paused") Saved = MachineState("saved") Aborted = MachineState("aborted") )
const ( NICNetAbsent = NICNetwork("none") NICNetDisconnected = NICNetwork("null") NICNetNAT = NICNetwork("nat") NICNetBridged = NICNetwork("bridged") NICNetInternal = NICNetwork("intnet") NICNetHostonly = NICNetwork("hostonly") NICNetGeneric = NICNetwork("generic") )
const ( AMDPCNetPCIII = NICHardware("Am79C970A") AMDPCNetFASTIII = NICHardware("Am79C973") IntelPro1000MTDesktop = NICHardware("82540EM") IntelPro1000TServer = NICHardware("82543GC") IntelPro1000MTServer = NICHardware("82545EM") VirtIO = NICHardware("virtio") )
const ( PFTCP = PFProto("tcp") PFUDP = PFProto("udp") )
const ( HOST_MODE_DISCONNECTED = 1 << iota HOST_MODE_PIPE HOST_MODE_DEVICE HOST_MODE_RAW_FILE )
const ( SysBusIDE = SystemBus("ide") SysBusSATA = SystemBus("sata") SysBusSCSI = SystemBus("scsi") SysBusSAS = SystemBus("sas") SysBusFloppy = SystemBus("floppy") )
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") )
const ( DriveDVD = DriveType("dvddrive") DriveHDD = DriveType("hdd") DriveFDD = DriveType("fdd") )
const ( DriveMNormal = DriveMType("normal") DriveMWritethrough = DriveMType("writethrough") DriveMImmutable = DriveMType("immutable") DriveMReadonly = DriveMType("readonly") DriveMMultiattach = DriveMType("multiattach") )
Variables ¶
var ( ErrMachineExist = errors.New("machine already exists") ErrMachineNotExist = errors.New("machine does not exist") ErrVBMNotFound = errors.New("VBoxManage not found") )
var (
ErrHostonlyInterfaceCreation = errors.New("failed to create hostonly interface")
)
var (
VBM string // Path to VBoxManage utility.
)
Functions ¶
func AddHostonlyDHCP ¶
AddHostonlyDHCP adds a DHCP server to a host-only network.
func AddInternalDHCP ¶
AddInternalDHCP adds a DHCP server to an internal network.
func ConvertRawToImage ¶
Convert the raw format device to vmdk format
func GetMediumUUID ¶
func HostonlyNets ¶
func HostonlyNets() (map[string]*HostonlyNet, error)
HostonlyNets gets all host-only networks in a map keyed by HostonlyNet.NetworkName.
func MakeDiskImage ¶
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 ParseIPv4Mask ¶
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 UnregisterDisk ¶
Types ¶
type DriveMType ¶
type DriveMType string
type Flag ¶
type Flag int
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 ¶
CreateMachine creates a new machine. If basefolder is empty, use default.
func GetMachine ¶
GetMachine finds a machine by its name or UUID.
func ListMachines ¶
ListMachines lists all registered machines.
func (*Machine) AddNATPF ¶
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 (*Machine) DelNATPF ¶
DelNATPF deletes the NAT port forwarding rule with the given name from the n-th NIC.
func (*Machine) DelStorageCtl ¶
DelStorageCtl deletes the storage controller with the given name.
func (*Machine) ModifyNIC ¶
func (m *Machine) ModifyNIC(n int, nicType NICNetwork, device string) error
SetNIC set the n-th NIC.
func (*Machine) Poweroff ¶
Poweroff forcefully stops the machine. State is lost and might corrupt the disk image.
func (*Machine) RemoveSharedFolder ¶
DelSharedFolder deletes a shared folder with the given machine
func (*Machine) Reset ¶
Reset forcefully restarts the machine. State is lost and might corrupt the disk image.
func (*Machine) SerialPortConf ¶
func (*Machine) StopSerialPort ¶
type MachineState ¶
type MachineState string
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 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.
type SerialPort ¶
type SharedFolder ¶
type SharedFolder struct {}
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.