vz

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2022 License: MIT Imports: 11 Imported by: 2

README

vz - Go binding with Apple Virtualization.framework

Build

vz provides the power of the Apple Virtualization.framework in Go. Put here is block quote of overreview which is written what is Virtualization.framework from the document.

The Virtualization framework provides high-level APIs for creating and managing virtual machines on Apple silicon and Intel-based Mac computers. Use this framework to boot and run a Linux-based operating system in a custom environment that you define. The framework supports the Virtio specification, which defines standard interfaces for many device types, including network, socket, serial port, storage, entropy, and memory-balloon devices.

USAGE

Please see the example directory.

REQUIREMENTS

Higher or equal to Go 1.17.

macOS Monterey (v12.x.x)

For the latest macOS version is developed on the master branch and released as v2.x.x.

You can install by go get github.com/Code-Hex/vz/v2

macOS Big Sur (v11.x.x)

Some methods of this framework are available and some are not, depending on the version of macOS. Therefore, Go language side also needs to control which methods are available depending on the macOS version.

From now on, those available in Big Sur (11.0.0) will be developed on the v1 branch and released as v1.x.x.

You can install by go get github.com/Code-Hex/vz

IMPORTANT

For binaries used in this package, you need to create an entitlements file like the one below and apply the following command.

vz.entitlements 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>com.apple.security.virtualization</key>
	<true/>
</dict>
</plist>

$ codesign --entitlements vz.entitlements -s - <YOUR BINARY PATH>

A process must have the com.apple.security.virtualization entitlement to use the Virtualization APIs.

If you want to use VZBridgedNetworkDeviceAttachment, you need to add also com.apple.vm.networking entitlement.

LICENSE

MIT License

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Addr added in v1.0.0 

type Addr struct {
	CID  uint32
	Port uint32
}

Addr represents a network end point address for the vsock protocol.

func (*Addr) Network added in v1.0.0 

func (a *Addr) Network() string

Network returns "vsock".

func (*Addr) String added in v1.0.0 

func (a *Addr) String() string

String returns string of "<cid>:<port>"

type BootLoader 

type BootLoader interface {
	NSObject
	// contains filtered or unexported methods
}

BootLoader is the interface of boot loader definitions. see: LinuxBootLoader

type BridgedNetwork 

type BridgedNetwork interface {
	NSObject

	// NetworkInterfaces returns the list of network interfaces available for bridging.
	NetworkInterfaces() []BridgedNetwork

	// Identifier returns the unique identifier for this interface.
	// The identifier is the BSD name associated with the interface (e.g. "en0").
	Identifier() string

	// LocalizedDisplayName returns a display name if available (e.g. "Ethernet").
	LocalizedDisplayName() string
}

BridgedNetwork defines a network interface that bridges a physical interface with a virtual machine.

A bridged interface is shared between the virtual machine and the host system. Both host and virtual machine send and receive packets on the same physical interface but have distinct network layers.

The BridgedNetwork can be used with a BridgedNetworkDeviceAttachment to set up a network device NetworkDeviceConfiguration. TODO(codehex): implement... see: https://developer.apple.com/documentation/virtualization/vzbridgednetworkinterface?language=objc

type BridgedNetworkDeviceAttachment 

type BridgedNetworkDeviceAttachment struct {
	// contains filtered or unexported fields
}

BridgedNetworkDeviceAttachment represents a physical interface on the host computer.

Use this struct when configuring a network interface for your virtual machine. A bridged network device sends and receives packets on the same physical interface as the host computer, but does so using a different network layer.

To use this attachment, your app must have the com.apple.vm.networking entitlement. If it doesn’t, the use of this attachment point results in an invalid VZVirtualMachineConfiguration object in objective-c.

see: https://developer.apple.com/documentation/virtualization/vzbridgednetworkdeviceattachment?language=objc

func NewBridgedNetworkDeviceAttachment 

func NewBridgedNetworkDeviceAttachment(networkInterface BridgedNetwork) *BridgedNetworkDeviceAttachment

NewBridgedNetworkDeviceAttachment creates a new BridgedNetworkDeviceAttachment with networkInterface.

func (*BridgedNetworkDeviceAttachment) Ptr 

func (o *BridgedNetworkDeviceAttachment) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*BridgedNetworkDeviceAttachment) Release 

func (p *BridgedNetworkDeviceAttachment) Release()

Release releases allocated resources in objective-c world.

type DiskImageStorageDeviceAttachment 

type DiskImageStorageDeviceAttachment struct {
	// contains filtered or unexported fields
}

DiskImageStorageDeviceAttachment is a storage device attachment using a disk image to implement the storage.

This storage device attachment uses a disk image on the host file system as the drive of the storage device. Only raw data disk images are supported. see: https://developer.apple.com/documentation/virtualization/vzdiskimagestoragedeviceattachment?language=objc

func NewDiskImageStorageDeviceAttachment 

func NewDiskImageStorageDeviceAttachment(diskPath string, readOnly bool) (*DiskImageStorageDeviceAttachment, error)

NewDiskImageStorageDeviceAttachment initialize the attachment from a local file path. Returns error is not nil, assigned with the error if the initialization failed.

- diskPath is local file URL to the disk image in RAW format. - readOnly if YES, the device attachment is read-only, otherwise the device can write data to the disk image.

func (*DiskImageStorageDeviceAttachment) Ptr 

func (o *DiskImageStorageDeviceAttachment) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*DiskImageStorageDeviceAttachment) Release 

func (p *DiskImageStorageDeviceAttachment) Release()

Release releases allocated resources in objective-c world.

type FileHandleNetworkDeviceAttachment 

type FileHandleNetworkDeviceAttachment struct {
	// contains filtered or unexported fields
}

FileHandleNetworkDeviceAttachment sending raw network packets over a file handle.

The file handle attachment transmits the raw packets/frames between the virtual network interface and a file handle. The data transmitted through this attachment is at the level of the data link layer. see: https://developer.apple.com/documentation/virtualization/vzfilehandlenetworkdeviceattachment?language=objc

func NewFileHandleNetworkDeviceAttachment 

func NewFileHandleNetworkDeviceAttachment(file *os.File) *FileHandleNetworkDeviceAttachment

NewFileHandleNetworkDeviceAttachment initialize the attachment with a file handle.

file parameter is holding a connected datagram socket.

func (*FileHandleNetworkDeviceAttachment) Ptr 

func (o *FileHandleNetworkDeviceAttachment) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*FileHandleNetworkDeviceAttachment) Release 

func (p *FileHandleNetworkDeviceAttachment) Release()

Release releases allocated resources in objective-c world.

type FileHandleSerialPortAttachment 

type FileHandleSerialPortAttachment struct {
	// contains filtered or unexported fields
}

FileHandleSerialPortAttachment defines a serial port attachment from a file handle.

Data written to fileHandleForReading goes to the guest. Data sent from the guest appears on fileHandleForWriting. see: https://developer.apple.com/documentation/virtualization/vzfilehandleserialportattachment?language=objc

func NewFileHandleSerialPortAttachment 

func NewFileHandleSerialPortAttachment(read, write *os.File) *FileHandleSerialPortAttachment

NewFileHandleSerialPortAttachment intialize the FileHandleSerialPortAttachment from file handles.

read parameter is an *os.File for reading from the file. write parameter is an *os.File for writing to the file.

func (*FileHandleSerialPortAttachment) Ptr 

func (o *FileHandleSerialPortAttachment) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*FileHandleSerialPortAttachment) Release 

func (p *FileHandleSerialPortAttachment) Release()

Release releases allocated resources in objective-c world.

type FileSerialPortAttachment 

type FileSerialPortAttachment struct {
	// contains filtered or unexported fields
}

FileSerialPortAttachment defines a serial port attachment from a file.

Any data sent by the guest on the serial interface is written to the file. No data is sent to the guest over serial with this attachment. see: https://developer.apple.com/documentation/virtualization/vzfileserialportattachment?language=objc

func NewFileSerialPortAttachment 

func NewFileSerialPortAttachment(path string, shouldAppend bool) (*FileSerialPortAttachment, error)

NewFileSerialPortAttachment initialize the FileSerialPortAttachment from a path of a file. If error is not nil, used to report errors if intialization fails.

  • path of the file for the attachment on the local file system.
  • shouldAppend True if the file should be opened in append mode, false otherwise. When a file is opened in append mode, writing to that file will append to the end of it.

func (*FileSerialPortAttachment) Ptr 

func (o *FileSerialPortAttachment) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*FileSerialPortAttachment) Release 

func (p *FileSerialPortAttachment) Release()

Release releases allocated resources in objective-c world.

type LinuxBootLoader 

type LinuxBootLoader struct {
	// contains filtered or unexported fields
}

LinuxBootLoader Boot loader configuration for a Linux kernel.

func NewLinuxBootLoader 

func NewLinuxBootLoader(vmlinuz string, opts ...LinuxBootLoaderOption) *LinuxBootLoader

NewLinuxBootLoader creates a LinuxBootLoader with the Linux kernel passed as Path.

func (*LinuxBootLoader) Ptr 

func (o *LinuxBootLoader) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*LinuxBootLoader) Release 

func (p *LinuxBootLoader) Release()

Release releases allocated resources in objective-c world.

func (*LinuxBootLoader) String 

func (b *LinuxBootLoader) String() string

type LinuxBootLoaderOption 

type LinuxBootLoaderOption func(b *LinuxBootLoader)

func WithCommandLine 

func WithCommandLine(cmdLine string) LinuxBootLoaderOption

WithCommandLine sets the command-line parameters. see: https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html

func WithInitrd 

func WithInitrd(initrdPath string) LinuxBootLoaderOption

WithInitrd sets the optional initial RAM disk.

type MACAddress added in v0.0.4 

type MACAddress struct {
	// contains filtered or unexported fields
}

MACAddress represents a media access control address (MAC address), the 48-bit ethernet address. see: https://developer.apple.com/documentation/virtualization/vzmacaddress?language=objc

func NewMACAddress added in v0.0.4 

func NewMACAddress(macAddr net.HardwareAddr) *MACAddress

NewMACAddress creates a new MACAddress with net.HardwareAddr (MAC address).

func NewRandomLocallyAdministeredMACAddress added in v0.0.4 

func NewRandomLocallyAdministeredMACAddress() *MACAddress

NewRandomLocallyAdministeredMACAddress creates a valid, random, unicast, locally administered address.

func (*MACAddress) HardwareAddr added in v0.0.4 

func (m *MACAddress) HardwareAddr() net.HardwareAddr

func (*MACAddress) Ptr added in v0.0.4 

func (o *MACAddress) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*MACAddress) Release added in v0.0.4 

func (p *MACAddress) Release()

Release releases allocated resources in objective-c world.

func (*MACAddress) String added in v0.0.4 

func (m *MACAddress) String() string

type MemoryBalloonDeviceConfiguration 

type MemoryBalloonDeviceConfiguration interface {
	NSObject
	// contains filtered or unexported methods
}

MemoryBalloonDeviceConfiguration for a memory balloon device configuration.

type NATNetworkDeviceAttachment 

type NATNetworkDeviceAttachment struct {
	// contains filtered or unexported fields
}

Network device attachment using network address translation (NAT) with outside networks.

Using the NAT attachment type, the host serves as router and performs network address translation for accesses to outside networks. see: https://developer.apple.com/documentation/virtualization/vznatnetworkdeviceattachment?language=objc

func NewNATNetworkDeviceAttachment 

func NewNATNetworkDeviceAttachment() *NATNetworkDeviceAttachment

NewNATNetworkDeviceAttachment creates a new NATNetworkDeviceAttachment.

func (*NATNetworkDeviceAttachment) Ptr 

func (o *NATNetworkDeviceAttachment) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*NATNetworkDeviceAttachment) Release 

func (p *NATNetworkDeviceAttachment) Release()

Release releases allocated resources in objective-c world.

type NSArray added in v1.0.0 

type NSArray struct {
	// contains filtered or unexported fields
}

NSArray indicates NSArray

func (*NSArray) Ptr added in v1.0.0 

func (o *NSArray) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*NSArray) Release added in v1.0.0 

func (p *NSArray) Release()

Release releases allocated resources in objective-c world.

func (*NSArray) ToPointerSlice added in v1.0.0 

func (n *NSArray) ToPointerSlice() []unsafe.Pointer

ToPointerSlice method returns slice of the obj-c object as unsafe.Pointer.

type NSError 

type NSError struct {
	Domain               string
	Code                 int
	LocalizedDescription string
	UserInfo             string
	// contains filtered or unexported fields
}

NSError indicates NSError.

func (*NSError) Error 

func (n *NSError) Error() string

func (*NSError) Ptr 

func (o *NSError) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*NSError) Release 

func (p *NSError) Release()

Release releases allocated resources in objective-c world.

type NSObject 

type NSObject interface {
	Ptr() unsafe.Pointer
}

NSObject indicates NSObject

type NetworkDeviceAttachment 

type NetworkDeviceAttachment interface {
	NSObject
	// contains filtered or unexported methods
}

NetworkDeviceAttachment for a network device attachment. see: https://developer.apple.com/documentation/virtualization/vznetworkdeviceattachment?language=objc

type SerialPortAttachment 

type SerialPortAttachment interface {
	NSObject
	// contains filtered or unexported methods
}

SerialPortAttachment interface for a serial port attachment.

A serial port attachment defines how the virtual machine's serial port interfaces with the host system.

type SocketDeviceConfiguration 

type SocketDeviceConfiguration interface {
	NSObject
	// contains filtered or unexported methods
}

SocketDeviceConfiguration for a socket device configuration.

type StorageDeviceAttachment 

type StorageDeviceAttachment interface {
	NSObject
	// contains filtered or unexported methods
}

StorageDeviceAttachment for a storage device attachment.

A storage device attachment defines how a virtual machine storage device interfaces with the host system. see: https://developer.apple.com/documentation/virtualization/vzstoragedeviceattachment?language=objc

type StorageDeviceConfiguration 

type StorageDeviceConfiguration interface {
	NSObject
	// contains filtered or unexported methods
}

StorageDeviceConfiguration for a storage device configuration.

type VirtioBlockDeviceConfiguration 

type VirtioBlockDeviceConfiguration struct {
	// contains filtered or unexported fields
}

VirtioBlockDeviceConfiguration is a configuration of a paravirtualized storage device of type Virtio Block Device.

This device configuration creates a storage device using paravirtualization. The emulated device follows the Virtio Block Device specification.

The host implementation of the device is done through an attachment subclassing VZStorageDeviceAttachment like VZDiskImageStorageDeviceAttachment. see: https://developer.apple.com/documentation/virtualization/vzvirtioblockdeviceconfiguration?language=objc

func NewVirtioBlockDeviceConfiguration 

func NewVirtioBlockDeviceConfiguration(attachment StorageDeviceAttachment) *VirtioBlockDeviceConfiguration

NewVirtioBlockDeviceConfiguration initialize a VZVirtioBlockDeviceConfiguration with a device attachment.

- attachment The storage device attachment. This defines how the virtualized device operates on the host side.

func (*VirtioBlockDeviceConfiguration) Ptr 

func (o *VirtioBlockDeviceConfiguration) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*VirtioBlockDeviceConfiguration) Release 

func (p *VirtioBlockDeviceConfiguration) Release()

Release releases allocated resources in objective-c world.

type VirtioConsoleDeviceSerialPortConfiguration 

type VirtioConsoleDeviceSerialPortConfiguration struct {
	// contains filtered or unexported fields
}

VirtioConsoleDeviceSerialPortConfiguration represents Virtio Console Serial Port Device.

The device creates a console which enables communication between the host and the guest through the Virtio interface. The device sets up a single port on the Virtio console device. see: https://developer.apple.com/documentation/virtualization/vzvirtioconsoledeviceserialportconfiguration?language=objc

func NewVirtioConsoleDeviceSerialPortConfiguration 

func NewVirtioConsoleDeviceSerialPortConfiguration(attachment SerialPortAttachment) *VirtioConsoleDeviceSerialPortConfiguration

NewVirtioConsoleDeviceSerialPortConfiguration creates a new NewVirtioConsoleDeviceSerialPortConfiguration.

func (*VirtioConsoleDeviceSerialPortConfiguration) Ptr 

func (o *VirtioConsoleDeviceSerialPortConfiguration) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*VirtioConsoleDeviceSerialPortConfiguration) Release 

func (p *VirtioConsoleDeviceSerialPortConfiguration) Release()

Release releases allocated resources in objective-c world.

type VirtioEntropyDeviceConfiguration 

type VirtioEntropyDeviceConfiguration struct {
	// contains filtered or unexported fields
}

VirtioEntropyDeviceConfiguration is used to expose a source of entropy for the guest operating system’s random-number generator. When you create this object and add it to your virtual machine’s configuration, the virtual machine configures a Virtio-compliant entropy device. The guest operating system uses this device as a seed to generate random numbers.

see: https://developer.apple.com/documentation/virtualization/vzvirtioentropydeviceconfiguration?language=objc

func NewVirtioEntropyDeviceConfiguration 

func NewVirtioEntropyDeviceConfiguration() *VirtioEntropyDeviceConfiguration

NewVirtioEntropyDeviceConfiguration creates a new Virtio Entropy Device confiuration.

func (*VirtioEntropyDeviceConfiguration) Ptr 

func (o *VirtioEntropyDeviceConfiguration) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*VirtioEntropyDeviceConfiguration) Release 

func (p *VirtioEntropyDeviceConfiguration) Release()

Release releases allocated resources in objective-c world.

type VirtioNetworkDeviceConfiguration 

type VirtioNetworkDeviceConfiguration struct {
	// contains filtered or unexported fields
}

VirtioNetworkDeviceConfiguration is configuration of a paravirtualized network device of type Virtio Network Device.

The communication channel used on the host is defined through the attachment. It is set with the VZNetworkDeviceConfiguration.attachment property in objective-c.

The configuration is only valid with valid MACAddress and attachment.

see: https://developer.apple.com/documentation/virtualization/vzvirtionetworkdeviceconfiguration?language=objc

func NewVirtioNetworkDeviceConfiguration 

func NewVirtioNetworkDeviceConfiguration(attachment NetworkDeviceAttachment) *VirtioNetworkDeviceConfiguration

NewVirtioNetworkDeviceConfiguration creates a new VirtioNetworkDeviceConfiguration with NetworkDeviceAttachment.

func (*VirtioNetworkDeviceConfiguration) Ptr 

func (o *VirtioNetworkDeviceConfiguration) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*VirtioNetworkDeviceConfiguration) Release 

func (p *VirtioNetworkDeviceConfiguration) Release()

Release releases allocated resources in objective-c world.

func (*VirtioNetworkDeviceConfiguration) SetMACAddress added in v1.0.0 

func (v *VirtioNetworkDeviceConfiguration) SetMACAddress(macAddress *MACAddress)

type VirtioSocketConnection added in v1.0.0 

type VirtioSocketConnection struct {
	// contains filtered or unexported fields
}

VirtioSocketConnection is a port-based connection between the guest operating system and the host computer.

You don’t create connection objects directly. When the guest operating system initiates a connection, the virtual machine creates the connection object and passes it to the appropriate VirtioSocketListener struct, which forwards the object to its delegate.

This is implemented net.Conn interface.

This struct does not have any pointers for objects of the Objective-C. Because the various values of the VZVirtioSocketConnection object handled by Objective-C are no longer needed after the conversion to the Go struct.

see: https://developer.apple.com/documentation/virtualization/vzvirtiosocketconnection?language=objc

func (*VirtioSocketConnection) Close added in v1.0.0 

func (v *VirtioSocketConnection) Close() error

Close will be called when caused something error in socket.

func (*VirtioSocketConnection) DestinationPort added in v1.0.0 

func (v *VirtioSocketConnection) DestinationPort() uint32

DestinationPort returns the destination port number of the connection.

func (*VirtioSocketConnection) FileDescriptor added in v1.0.0 

func (v *VirtioSocketConnection) FileDescriptor() uintptr

FileDescriptor returns the file descriptor associated with the socket.

Data is sent by writing to the file descriptor. Data is received by reading from the file descriptor. A file descriptor of -1 indicates a closed connection.

func (*VirtioSocketConnection) ID added in v1.0.0 

func (v *VirtioSocketConnection) ID() string

ID returns connection ID. this ID is used as filename of the vsock protocol connection.

func (*VirtioSocketConnection) LocalAddr added in v1.0.0 

func (v *VirtioSocketConnection) LocalAddr() net.Addr

LocalAddr returns the local network address.

func (*VirtioSocketConnection) Read added in v1.0.0 

func (v *VirtioSocketConnection) Read(b []byte) (n int, err error)

Read reads data from connection of the vsock protocol.

func (*VirtioSocketConnection) RemoteAddr added in v1.0.0 

func (v *VirtioSocketConnection) RemoteAddr() net.Addr

RemoteAddr returns the remote network address.

func (*VirtioSocketConnection) SetDeadline added in v1.0.0 

func (v *VirtioSocketConnection) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the connection. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.

func (*VirtioSocketConnection) SetReadDeadline added in v1.0.0 

func (v *VirtioSocketConnection) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for future Read calls and any currently-blocked Read call. A zero value for t means Read will not time out.

func (*VirtioSocketConnection) SetWriteDeadline added in v1.0.0 

func (v *VirtioSocketConnection) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for future Write calls and any currently-blocked Write call. Even if write times out, it may return n > 0, indicating that some of the data was successfully written. A zero value for t means Write will not time out.

func (*VirtioSocketConnection) SourcePort added in v1.0.0 

func (v *VirtioSocketConnection) SourcePort() uint32

SourcePort returns the source port number of the connection.

func (*VirtioSocketConnection) Write added in v1.0.0 

func (v *VirtioSocketConnection) Write(b []byte) (n int, err error)

Write writes data to the connection of the vsock protocol.

type VirtioSocketDevice added in v1.0.0 

type VirtioSocketDevice struct {
	// contains filtered or unexported fields
}

VirtioSocketDevice a device that manages port-based connections between the guest system and the host computer.

Don’t create a VirtioSocketDevice struct directly. Instead, when you request a socket device in your configuration, the virtual machine creates it and you can get it via SocketDevices method. see: https://developer.apple.com/documentation/virtualization/vzvirtiosocketdevice?language=objc

func (*VirtioSocketDevice) ConnectToPort added in v1.0.0 

func (v *VirtioSocketDevice) ConnectToPort(port uint32, fn func(conn *VirtioSocketConnection, err error))

ConnectToPort Initiates a connection to the specified port of the guest operating system.

This method initiates the connection asynchronously, and executes the completion handler when the results are available. If the guest operating system doesn’t listen for connections to the specifed port, this method does nothing.

For a successful connection, this method sets the sourcePort property of the resulting VZVirtioSocketConnection object to a random port number. see: https://developer.apple.com/documentation/virtualization/vzvirtiosocketdevice/3656677-connecttoport?language=objc

func (*VirtioSocketDevice) Ptr added in v1.0.0 

func (o *VirtioSocketDevice) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*VirtioSocketDevice) Release added in v1.0.0 

func (p *VirtioSocketDevice) Release()

Release releases allocated resources in objective-c world.

func (*VirtioSocketDevice) RemoveSocketListenerForPort added in v1.0.0 

func (v *VirtioSocketDevice) RemoveSocketListenerForPort(listener *VirtioSocketListener, port uint32)

RemoveSocketListenerForPort removes the listener object from the specfied port.

see: https://developer.apple.com/documentation/virtualization/vzvirtiosocketdevice/3656678-removesocketlistenerforport?language=objc

func (*VirtioSocketDevice) SetSocketListenerForPort added in v1.0.0 

func (v *VirtioSocketDevice) SetSocketListenerForPort(listener *VirtioSocketListener, port uint32)

SetSocketListenerForPort configures an object to monitor the specified port for new connections.

see: https://developer.apple.com/documentation/virtualization/vzvirtiosocketdevice/3656679-setsocketlistener?language=objc

type VirtioSocketDeviceConfiguration 

type VirtioSocketDeviceConfiguration struct {
	// contains filtered or unexported fields
}

VirtioSocketDeviceConfiguration is a configuration of the Virtio socket device.

This configuration creates a Virtio socket device for the guest which communicates with the host through the Virtio interface. Only one Virtio socket device can be used per virtual machine. see: https://developer.apple.com/documentation/virtualization/vzvirtiosocketdeviceconfiguration?language=objc

func NewVirtioSocketDeviceConfiguration 

func NewVirtioSocketDeviceConfiguration() *VirtioSocketDeviceConfiguration

NewVirtioSocketDeviceConfiguration creates a new VirtioSocketDeviceConfiguration.

func (*VirtioSocketDeviceConfiguration) Ptr 

func (o *VirtioSocketDeviceConfiguration) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*VirtioSocketDeviceConfiguration) Release 

func (p *VirtioSocketDeviceConfiguration) Release()

Release releases allocated resources in objective-c world.

type VirtioSocketListener added in v1.0.0 

type VirtioSocketListener struct {
	// contains filtered or unexported fields
}

VirtioSocketListener a struct that listens for port-based connection requests from the guest operating system.

see: https://developer.apple.com/documentation/virtualization/vzvirtiosocketlistener?language=objc

func NewVirtioSocketListener added in v1.0.0 

func NewVirtioSocketListener(handler func(conn *VirtioSocketConnection, err error)) *VirtioSocketListener

NewVirtioSocketListener creates a new VirtioSocketListener with connection handler.

The handler is executed asynchronously. Be sure to close the connection used in the handler by calling `conn.Close`. This is to prevent connection leaks.

func (*VirtioSocketListener) Ptr added in v1.0.0 

func (o *VirtioSocketListener) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*VirtioSocketListener) Release added in v1.0.0 

func (p *VirtioSocketListener) Release()

Release releases allocated resources in objective-c world.

type VirtioTraditionalMemoryBalloonDeviceConfiguration 

type VirtioTraditionalMemoryBalloonDeviceConfiguration struct {
	// contains filtered or unexported fields
}

VirtioTraditionalMemoryBalloonDeviceConfiguration is a configuration of the Virtio traditional memory balloon device.

see: https://developer.apple.com/documentation/virtualization/vzvirtiotraditionalmemoryballoondeviceconfiguration?language=objc

func NewVirtioTraditionalMemoryBalloonDeviceConfiguration 

func NewVirtioTraditionalMemoryBalloonDeviceConfiguration() *VirtioTraditionalMemoryBalloonDeviceConfiguration

NewVirtioTraditionalMemoryBalloonDeviceConfiguration creates a new VirtioTraditionalMemoryBalloonDeviceConfiguration.

func (*VirtioTraditionalMemoryBalloonDeviceConfiguration) Ptr 

func (o *VirtioTraditionalMemoryBalloonDeviceConfiguration) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*VirtioTraditionalMemoryBalloonDeviceConfiguration) Release 

func (p *VirtioTraditionalMemoryBalloonDeviceConfiguration) Release()

Release releases allocated resources in objective-c world.

type VirtualMachine 

type VirtualMachine struct {
	// contains filtered or unexported fields
}

VirtualMachine represents the entire state of a single virtual machine.

A Virtual Machine is the emulation of a complete hardware machine of the same architecture as the real hardware machine. When executing the Virtual Machine, the Virtualization framework uses certain hardware resources and emulates others to provide isolation and great performance.

The definition of a virtual machine starts with its configuration. This is done by setting up a VirtualMachineConfiguration struct. Once configured, the virtual machine can be started with (*VirtualMachine).Start() method.

Creating a virtual machine using the Virtualization framework requires the app to have the "com.apple.security.virtualization" entitlement. see: https://developer.apple.com/documentation/virtualization/vzvirtualmachine?language=objc

func NewVirtualMachine 

func NewVirtualMachine(config *VirtualMachineConfiguration) *VirtualMachine

NewVirtualMachine creates a new VirtualMachine with VirtualMachineConfiguration.

The configuration must be valid. Validation can be performed at runtime with (*VirtualMachineConfiguration).Validate() method. The configuration is copied by the initializer.

A new dispatch queue will create when called this function. Every operation on the virtual machine must be done on that queue. The callbacks and delegate methods are invoked on that queue.

func (*VirtualMachine) CanPause 

func (v *VirtualMachine) CanPause() bool

CanPause returns true if the machine is in a state that can be paused.

func (*VirtualMachine) CanRequestStop 

func (v *VirtualMachine) CanRequestStop() bool

CanRequestStop returns whether the machine is in a state where the guest can be asked to stop.

func (*VirtualMachine) CanResume 

func (v *VirtualMachine) CanResume() bool

CanResume returns true if the machine is in a state that can be resumed.

func (*VirtualMachine) CanStart 

func (v *VirtualMachine) CanStart() bool

CanStart returns true if the machine is in a state that can be started.

func (*VirtualMachine) Pause 

func (v *VirtualMachine) Pause(fn func(error))

Pause a virtual machine that is in Running state.

- fn parameter called after the virtual machine has been successfully paused or on error. The error parameter passed to the block is null if the start was successful.

func (*VirtualMachine) Ptr 

func (o *VirtualMachine) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*VirtualMachine) Release 

func (p *VirtualMachine) Release()

Release releases allocated resources in objective-c world.

func (*VirtualMachine) RequestStop 

func (v *VirtualMachine) RequestStop() (bool, error)

RequestStop requests that the guest turns itself off.

If returned error is not nil, assigned with the error if the request failed. Returens true if the request was made successfully.

func (*VirtualMachine) Resume 

func (v *VirtualMachine) Resume(fn func(error))

Resume a virtual machine that is in the Paused state.

- fn parameter called after the virtual machine has been successfully resumed or on error. The error parameter passed to the block is null if the resumption was successful.

func (*VirtualMachine) SocketDevices added in v1.0.0 

func (v *VirtualMachine) SocketDevices() []*VirtioSocketDevice

SocketDevices return the list of socket devices configured on this virtual machine. Return an empty array if no socket device is configured.

Since only NewVirtioSocketDeviceConfiguration is available in vz package, it will always return VirtioSocketDevice. see: https://developer.apple.com/documentation/virtualization/vzvirtualmachine/3656702-socketdevices?language=objc

func (*VirtualMachine) Start 

func (v *VirtualMachine) Start(fn func(error))

Start a virtual machine that is in either Stopped or Error state.

- fn parameter called after the virtual machine has been successfully started or on error. The error parameter passed to the block is null if the start was successful.

func (*VirtualMachine) State 

func (v *VirtualMachine) State() VirtualMachineState

State represents execution state of the virtual machine.

func (*VirtualMachine) StateChangedNotify added in v0.0.2 

func (v *VirtualMachine) StateChangedNotify() <-chan VirtualMachineState

StateChangedNotify gets notification is changed execution state of the virtual machine.

type VirtualMachineConfiguration 

type VirtualMachineConfiguration struct {
	// contains filtered or unexported fields
}

VirtualMachineConfiguration defines the configuration of a VirtualMachine.

The following properties must be configured before creating a virtual machine:

  • bootLoader

The configuration of devices is often done in two parts: - Device configuration - Device attachment

The device configuration defines the characteristics of the emulated hardware device. For example, for a network device, the device configuration defines the type of network adapter present in the virtual machine and its MAC address.

The device attachment defines the host machine's resources that are exposed by the virtual device. For example, for a network device, the device attachment can be virtual network interface with a NAT to the real network.

Creating a virtual machine using the Virtualization framework requires the app to have the "com.apple.security.virtualization" entitlement. A VirtualMachineConfiguration is considered invalid if the application does not have the entitlement.

see: https://developer.apple.com/documentation/virtualization/vzvirtualmachineconfiguration?language=objc

func NewVirtualMachineConfiguration 

func NewVirtualMachineConfiguration(bootLoader BootLoader, cpu uint, memorySize uint64) *VirtualMachineConfiguration

NewVirtualMachineConfiguration creates a new configuration.

  • bootLoader parameter is used when the virtual machine starts.
  • cpu parameter is The number of CPUs must be a value between VZVirtualMachineConfiguration.minimumAllowedCPUCount and VZVirtualMachineConfiguration.maximumAllowedCPUCount.
  • memorySize parameter represents memory size in bytes. The memory size must be a multiple of a 1 megabyte (1024 * 1024 bytes) between VZVirtualMachineConfiguration.minimumAllowedMemorySize and VZVirtualMachineConfiguration.maximumAllowedMemorySize.

func (*VirtualMachineConfiguration) Ptr 

func (o *VirtualMachineConfiguration) Ptr() unsafe.Pointer

Ptr returns raw pointer.

func (*VirtualMachineConfiguration) Release 

func (p *VirtualMachineConfiguration) Release()

Release releases allocated resources in objective-c world.

func (*VirtualMachineConfiguration) SetEntropyDevicesVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetEntropyDevicesVirtualMachineConfiguration(cs []*VirtioEntropyDeviceConfiguration)

SetEntropyDevicesVirtualMachineConfiguration sets list of entropy devices. Empty by default.

func (*VirtualMachineConfiguration) SetMemoryBalloonDevicesVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetMemoryBalloonDevicesVirtualMachineConfiguration(cs []MemoryBalloonDeviceConfiguration)

SetMemoryBalloonDevicesVirtualMachineConfiguration sets list of memory balloon devices. Empty by default.

func (*VirtualMachineConfiguration) SetNetworkDevicesVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetNetworkDevicesVirtualMachineConfiguration(cs []*VirtioNetworkDeviceConfiguration)

SetNetworkDevicesVirtualMachineConfiguration sets list of network adapters. Empty by default.

func (*VirtualMachineConfiguration) SetSerialPortsVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetSerialPortsVirtualMachineConfiguration(cs []*VirtioConsoleDeviceSerialPortConfiguration)

SetSerialPortsVirtualMachineConfiguration sets list of serial ports. Empty by default.

func (*VirtualMachineConfiguration) SetSocketDevicesVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetSocketDevicesVirtualMachineConfiguration(cs []SocketDeviceConfiguration)

SetSocketDevicesVirtualMachineConfiguration sets list of socket devices. Empty by default.

func (*VirtualMachineConfiguration) SetStorageDevicesVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetStorageDevicesVirtualMachineConfiguration(cs []StorageDeviceConfiguration)

SetStorageDevicesVirtualMachineConfiguration sets list of disk devices. Empty by default.

func (*VirtualMachineConfiguration) Validate 

func (v *VirtualMachineConfiguration) Validate() (bool, error)

Validate the configuration.

Return true if the configuration is valid. If error is not nil, assigned with the validation error if the validation failed.

type VirtualMachineState 

type VirtualMachineState int

VirtualMachineState represents execution state of the virtual machine. 

const (
	// VirtualMachineStateStopped Initial state before the virtual machine is started.
	VirtualMachineStateStopped VirtualMachineState = iota

	// VirtualMachineStateRunning Running virtual machine.
	VirtualMachineStateRunning

	// VirtualMachineStatePaused A started virtual machine is paused.
	// This state can only be transitioned from VirtualMachineStatePausing.
	VirtualMachineStatePaused

	// VirtualMachineStateError The virtual machine has encountered an internal error.
	VirtualMachineStateError

	// VirtualMachineStateStarting The virtual machine is configuring the hardware and starting.
	VirtualMachineStateStarting

	// VirtualMachineStatePausing The virtual machine is being paused.
	// This is the intermediate state between VirtualMachineStateRunning and VirtualMachineStatePaused.
	VirtualMachineStatePausing

	// VirtualMachineStateResuming The virtual machine is being resumed.
	// This is the intermediate state between VirtualMachineStatePaused and VirtualMachineStateRunning.
	VirtualMachineStateResuming
)

Source Files

View all Source files

Directories

Path Synopsis
example module

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.