vz

package module
v3.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 22, 2023 License: MIT Imports: 16 Imported by: 11

README

vz - Go binding with Apple Virtualization.framework

Build Go Reference

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 (VM) on Apple silicon and Intel-based Mac computers. Use this framework to boot and run macOS or Linux-based operating systems in custom environments that you define. The framework supports the Virtual I/O Device (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 macOS Big Sur (11.0.0).
  • Latest version of vz supports last two Go major releases and might work with older versions.

Installation

Initialize your project by creating a folder and then running go mod init github.com/your/repo (learn more) inside the folder. Then install vz with the go get command:

$ go get github.com/Code-Hex/vz/v3

Deprecated older versions (v1, v2).

Feature Overview

  • ✅ Virtualize Linux on a Mac (x86_64, arm64)
    • GUI Support
    • Boot Extensible Firmware Interface (EFI) ROM
    • Clipboard sharing through the SPICE agent
  • ✅ Virtualize macOS on Apple Silicon Macs (arm64)
    • Fetches the latest restore image supported by this host from the network
    • Start in recovery mode
  • ✅ Running Intel Binaries in Linux VMs with Rosetta (arm64)
  • ✅ Shared Directories
  • ✅ Virtio Sockets
  • ✅ Less dependent (only under golang.org/x/*)

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.

Known compile-time warnings

If you compile using an older Xcode SDK, you will get the following warnings.

This example warns that macOS 12.3 API and macOS 13 API are not available in the binary build. This means these APIs are not available even if you are running this binary on a modern OS (macOS 12.3 or macOS 13).

$ go build .
# github.com/Code-Hex/vz/v3
In file included from _cgo_export.c:4:
In file included from socket.go:6:
In file included from ./virtualization_11.h:9:
./virtualization_helper.h:25:9: warning: macOS 12.3 API has been disabled [-W#pragma-messages]
./virtualization_helper.h:32:9: warning: macOS 13 API has been disabled [-W#pragma-messages]

If you want to build a binary that can use the API on all operating systems, make sure the Xcode SDK is up-to-date.

You can check the version of the Xcode SDK available for each macOS on this site.

https://xcodereleases.com/

Version compatibility check

The package provides a mechanism for checking the availability of the respective API through error handling:

bootLoader, err := vz.NewEFIBootLoader()
if errors.Is(err, vz.ErrUnsupportedOSVersion) || errors.Is(err, vz.ErrBuildTargetOSVersion) {
  return fallbackBootLoader()
}
if err != nil {
  return nil, err
}
return bootLoader, nil

There are two items to check.

  1. API is compatible with the version of macOS
  2. The binary was built with the API enabled

Knowledge for the Apple Virtualization.framework

There is a lot of knowledge required to use this Apple Virtualization.framework, but the information is too scattered and very difficult to understand. In most cases, this can be found in the official documentation. However, the Linux kernel knowledge required to use the feature provided by this framework is not documented. Therefore, I have compiled the knowledge I have gathered so far into this wiki.

https://github.com/Code-Hex/vz/wiki

Anyone is free to edit this wiki. It would help someone if you could add information not listed here. Let's make a good wiki together!

Testing

If you want to contribute some code, you will need to add tests.

PUI PUI Linux is used to test this library. This Linux is designed to provide only the minimum functionality required for the Apple Virtualization.framework (Virtio), so the kernel file size is very small.

The test code uses the Makefile in the project root.

$ # Download PUI PUI Linux, Only required the first time.
$ make download_kernel
$ make test

Which projects use this library?

  • vfkit is a macOS command-line hypervisor for Apple and Intel CPUs that supports most of Apple's Virtualization Framework features.
  • Lima launches Linux virtual machines with automatic file sharing and port forwarding (similar to WSL2).
  • linuxkit is a toolkit for building custom minimal, immutable Linux distributions.

LICENSE

MIT License

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnsupportedOSVersion is returned when calling a method which is only
	// available in newer macOS versions.
	ErrUnsupportedOSVersion = errors.New("unsupported macOS version")

	// ErrBuildTargetOSVersion indicates that the API is available but the
	// running program has disabled it.
	ErrBuildTargetOSVersion = errors.New("unsupported build target macOS version")
)

Functions

func CreateDiskImage 

func CreateDiskImage(pathname string, size int64) error

CreateDiskImage is creating disk image with specified filename and filesize. For example, if you want to create disk with 64GiB, you can set "64 * 1024 * 1024 * 1024" to size.

Note that if you have specified a pathname which already exists, this function returns os.ErrExist error. So you can handle it with os.IsExist function.

func MacOSGuestAutomountTag 

func MacOSGuestAutomountTag() (string, error)

MacOSGuestAutomountTag returns the macOS automount tag.

A device configured with this tag will be automatically mounted in a macOS guest. This is only supported on macOS 13 and newer, error will be returned on older versions.

func SpiceAgentPortAttachmentName 

func SpiceAgentPortAttachmentName() (string, error)

SpiceAgentPortAttachmentName returns the Spice agent port name.

func VirtualMachineConfigurationMaximumAllowedCPUCount 

func VirtualMachineConfigurationMaximumAllowedCPUCount() uint

VirtualMachineConfigurationMaximumAllowedCPUCount returns maximum number of CPUs for a virtual machine.

func VirtualMachineConfigurationMaximumAllowedMemorySize 

func VirtualMachineConfigurationMaximumAllowedMemorySize() uint64

VirtualMachineConfigurationMaximumAllowedMemorySize returns maximum amount of memory allowed for a virtual machine.

func VirtualMachineConfigurationMinimumAllowedCPUCount 

func VirtualMachineConfigurationMinimumAllowedCPUCount() uint

VirtualMachineConfigurationMinimumAllowedCPUCount returns minimum number of CPUs for a virtual machine.

func VirtualMachineConfigurationMinimumAllowedMemorySize 

func VirtualMachineConfigurationMinimumAllowedMemorySize() uint64

VirtualMachineConfigurationMinimumAllowedMemorySize returns minimum amount of memory required by virtual machines.

Types

type AudioDeviceConfiguration 

type AudioDeviceConfiguration interface {
	objc.NSObject
	// contains filtered or unexported methods
}

AudioDeviceConfiguration interface for an audio device configuration.

type BootLoader 

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

BootLoader is the interface of boot loader definitions.

type BridgedNetwork 

type BridgedNetwork interface {
	objc.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, error)

NewBridgedNetworkDeviceAttachment creates a new BridgedNetworkDeviceAttachment with networkInterface.

This is only supported on macOS 11 and newer, error will be returned on older versions.

type ConsoleDeviceConfiguration 

type ConsoleDeviceConfiguration interface {
	objc.NSObject
	// contains filtered or unexported methods
}

ConsoleDeviceConfiguration interface for an console device configuration.

type ConsolePortConfiguration 

type ConsolePortConfiguration interface {
	objc.NSObject
	// contains filtered or unexported methods
}

type DirectoryShare 

type DirectoryShare interface {
	objc.NSObject
	// contains filtered or unexported methods
}

DirectoryShare is the base interface for a directory share.

type DirectorySharingDeviceConfiguration 

type DirectorySharingDeviceConfiguration interface {
	objc.NSObject
	// contains filtered or unexported methods
}

DirectorySharingDeviceConfiguration for a directory sharing device configuration.

type DiskBlockDeviceStorageDeviceAttachment added in v3.1.0 

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

DiskBlockDeviceStorageDeviceAttachment is a storage device attachment that uses a disk to store data.

The disk block device implements a storage attachment by using an actual disk rather than a disk image on a file system.

Warning: Handle the disk passed to this attachment with caution. If the disk has a file system formatted on it, the guest can destroy data in a way that isn’t recoverable.

By default, only the root user can access the disk file handle. Running virtual machines as root isn’t recommended. The best practice is to open the file in a separate process that has root privileges, then pass the open file descriptor using XPC or a Unix socket to a non-root process running Virtualization.

func NewDiskBlockDeviceStorageDeviceAttachment added in v3.1.0 

func NewDiskBlockDeviceStorageDeviceAttachment(file *os.File, readOnly bool, syncMode DiskSynchronizationMode) (*DiskBlockDeviceStorageDeviceAttachment, error)

NewDiskBlockDeviceStorageDeviceAttachment creates a new block storage device attachment from a file handle and with the specified access mode, synchronization mode, and error object that you provide.

- file is the *os.File to a block device to attach to this VM. - readOnly is a boolean value that indicates whether this disk attachment is read-only; otherwise, if the file handle allows writes, the device can write data into it. this parameter affects how the Virtualization framework exposes the disk to the guest operating system by the storage controller. If you intend to use the disk in read-only mode, it’s also a best practice to open the file handle as read-only. - syncMode is one of the available DiskSynchronizationMode options.

Note that the disk attachment retains the file handle, and the handle must be open when the virtual machine starts.

This is only supported on macOS 14 and newer, error will be returned on older versions.

type DiskImageCachingMode added in v3.0.3 

type DiskImageCachingMode int

DiskImageCachingMode describes the disk image caching mode.

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

const (
	DiskImageCachingModeAutomatic DiskImageCachingMode = iota
	DiskImageCachingModeUncached
	DiskImageCachingModeCached
)

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.

This is only supported on macOS 11 and newer, error will be returned on older versions.

func NewDiskImageStorageDeviceAttachmentWithCacheAndSync added in v3.0.3 

func NewDiskImageStorageDeviceAttachmentWithCacheAndSync(diskPath string, readOnly bool, cachingMode DiskImageCachingMode, syncMode DiskImageSynchronizationMode) (*DiskImageStorageDeviceAttachment, error)

NewDiskImageStorageDeviceAttachmentWithCacheAndSync 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. - cachingMode is one of the available DiskImageCachingMode options. - syncMode is to define how the disk image synchronizes with the underlying storage when the guest operating system flushes data, described by one of the available DiskImageSynchronizationMode modes.

This is only supported on macOS 12 and newer, error will be returned on older versions.

type DiskImageSynchronizationMode added in v3.0.3 

type DiskImageSynchronizationMode int

DiskImageSynchronizationMode describes the disk image synchronization mode.

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

const (
	DiskImageSynchronizationModeFull DiskImageSynchronizationMode = 1 + iota
	DiskImageSynchronizationModeFsync
	DiskImageSynchronizationModeNone
)

type DiskSynchronizationMode added in v3.1.0 

type DiskSynchronizationMode int

DiskSynchronizationMode describes the synchronization modes available to the guest OS.

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

const (
	// Perform all synchronization operations as requested by the guest OS.
	//
	// Using this mode, flush and barrier commands from the guest result in
	// the system sending their counterpart synchronization commands to the
	// underlying disk implementation.
	DiskSynchronizationModeFull DiskSynchronizationMode = iota

	// DiskSynchronizationModeNone don’t synchronize the data with the permanent storage.
	//
	// This option doesn’t guarantee data integrity if any error condition occurs such as
	// disk full on the host, panic, power loss, and so on.
	//
	// This mode is useful when a VM is only run once to perform a task to completion or
	// failure. In case of failure, the state of blocks on disk and their order isn’t defined.
	//
	// Using this mode may result in improved performance since no synchronization with the underlying
	// storage is necessary.
	DiskSynchronizationModeNone
)

type EFIBootLoader 

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

EFIBootLoader Boot loader configuration for booting guest operating systems expecting an EFI ROM. see: https://developer.apple.com/documentation/virtualization/vzefibootloader?language=objc

func NewEFIBootLoader 

func NewEFIBootLoader(opts ...NewEFIBootLoaderOption) (*EFIBootLoader, error)

NewEFIBootLoader creates a new EFI boot loader.

This is only supported on macOS 13 and newer, error will be returned on older versions.

func (*EFIBootLoader) VariableStore 

func (e *EFIBootLoader) VariableStore() *EFIVariableStore

VariableStore returns EFI variable store.

type EFIVariableStore 

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

EFIVariableStore is EFI variable store. The EFI variable store contains NVRAM variables exposed by the EFI ROM.

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

func NewEFIVariableStore 

func NewEFIVariableStore(path string, opts ...NewEFIVariableStoreOption) (*EFIVariableStore, error)

NewEFIVariableStore Initialize the variable store. If no options are specified, it initializes from the paths that exist.

This is only supported on macOS 13 and newer, error will be returned on older versions.

func (*EFIVariableStore) Path 

func (e *EFIVariableStore) Path() string

Path returns the path of the variable store on the local file system.

type ErrorCode 

type ErrorCode int

Error type returned by the Virtualization framework. The NSError domain is VZErrorDomain, the code is one of the ErrorCode constants. 

const (
	// ErrorInternal is an internal error such as the virtual machine unexpectedly stopping.
	ErrorInternal ErrorCode = 1 + iota

	// ErrorInvalidVirtualMachineConfiguration represents invalid machine configuration.
	ErrorInvalidVirtualMachineConfiguration

	// ErrorInvalidVirtualMachineState represents API used with a machine in the wrong state
	// (e.g. interacting with a machine before it is running).
	ErrorInvalidVirtualMachineState

	// ErrorInvalidVirtualMachineStateTransition is invalid change of state
	// (e.g. pausing a virtual machine that is not started).
	ErrorInvalidVirtualMachineStateTransition

	// ErrorInvalidDiskImage represents unrecognized disk image format or invalid disk image.
	ErrorInvalidDiskImage

	// ErrorVirtualMachineLimitExceeded represents the running virtual machine limit was exceeded.
	// Available from macOS 12.0 and above.
	ErrorVirtualMachineLimitExceeded

	// ErrorNetworkError represents network error occurred.
	// Available from macOS 13.0 and above.
	ErrorNetworkError

	// ErrorOutOfDiskSpace represents machine ran out of disk space.
	// Available from macOS 13.0 and above.
	ErrorOutOfDiskSpace

	// ErrorOperationCancelled represents the operation was cancelled.
	// Available from macOS 13.0 and above.
	ErrorOperationCancelled

	// ErrorNotSupported represents the operation is not supported.
	// Available from macOS 13.0 and above.
	ErrorNotSupported
)
const (
	// ErrorRestoreImageCatalogLoadFailed represents the restore image catalog failed to load.
	// Available from macOS 13.0 and above.
	ErrorRestoreImageCatalogLoadFailed ErrorCode = 10001 + iota

	// ErrorInvalidRestoreImageCatalog represents the restore image catalog is invalid.
	// Available from macOS 13.0 and above.
	ErrorInvalidRestoreImageCatalog

	// ErrorNoSupportedRestoreImagesInCatalog represents the restore image catalog has no supported restore images.
	// Available from macOS 13.0 and above.
	ErrorNoSupportedRestoreImagesInCatalog

	// ErrorRestoreImageLoadFailed represents the restore image failed to load.
	// Available from macOS 13.0 and above.
	ErrorRestoreImageLoadFailed

	// ErrorInvalidRestoreImage represents the restore image is invalid.
	// Available from macOS 13.0 and above.
	ErrorInvalidRestoreImage

	// ErrorInstallationRequiresUpdate represents a software update is required to complete the installation.
	// Available from macOS 13.0 and above.
	ErrorInstallationRequiresUpdate

	// ErrorInstallationFailed is an error occurred during installation.
	// Available from macOS 13.0 and above.
	ErrorInstallationFailed
)

macOS installation errors.

func (ErrorCode) String 

func (i ErrorCode) String() string

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, error)

NewFileHandleNetworkDeviceAttachment initialize the attachment with a file handle.

file parameter is holding a connected datagram socket.

This is only supported on macOS 11 and newer, error will be returned on older versions.

func (*FileHandleNetworkDeviceAttachment) MaximumTransmissionUnit 

func (f *FileHandleNetworkDeviceAttachment) MaximumTransmissionUnit() int

MaximumTransmissionUnit returns the maximum transmission unit (MTU) associated with this attachment. The default MTU is 1500.

func (*FileHandleNetworkDeviceAttachment) SetMaximumTransmissionUnit 

func (f *FileHandleNetworkDeviceAttachment) SetMaximumTransmissionUnit(mtu int) error

SetMaximumTransmissionUnit sets the maximum transmission unit (MTU) associated with this attachment.

The maximum MTU allowed is 65535, and the minimum MTU allowed is 1500. An invalid MTU value will result in an invalid virtual machine configuration.

The client side of the associated datagram socket must be properly configured with the appropriate values for SO_SNDBUF, and SO_RCVBUF. Set these using the setsockopt(_:_:_:_:_:) system call. The system expects the value of SO_RCVBUF to be at least double the value of SO_SNDBUF, and for optimal performance, the recommended value of SO_RCVBUF is four times the value of SO_SNDBUF.

This is only supported on macOS 13 and newer, error will be returned on older versions.

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, error)

NewFileHandleSerialPortAttachment initialize 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.

This is only supported on macOS 11 and newer, error will be returned on older versions.

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.

This is only supported on macOS 11 and newer, error will be returned on older versions.

type GenericMachineIdentifier 

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

GenericMachineIdentifier is a struct that represents a unique identifier for a virtual machine.

func NewGenericMachineIdentifier 

func NewGenericMachineIdentifier() (*GenericMachineIdentifier, error)

NewGenericMachineIdentifier initialize a new machine identifier is used by guests to uniquely identify the virtual hardware.

Two virtual machines running concurrently should not use the same identifier.

If the virtual machine is serialized to disk, the identifier can be preserved in a binary representation through DataRepresentation method. The identifier can then be recreated with NewGenericMachineIdentifierWithData function from the binary representation.

This is only supported on macOS 13 and newer, error will be returned on older versions.

func NewGenericMachineIdentifierWithData 

func NewGenericMachineIdentifierWithData(b []byte) (*GenericMachineIdentifier, error)

NewGenericMachineIdentifierWithData initialize a new machine identifier described by the specified data representation.

This is only supported on macOS 13 and newer, error will be returned on older versions.

func NewGenericMachineIdentifierWithDataPath 

func NewGenericMachineIdentifierWithDataPath(pathname string) (*GenericMachineIdentifier, error)

NewGenericMachineIdentifierWithDataPath initialize a new machine identifier described by the specified pathname.

This is only supported on macOS 13 and newer, error will be returned on older versions.

func (*GenericMachineIdentifier) DataRepresentation 

func (g *GenericMachineIdentifier) DataRepresentation() []byte

DataRepresentation opaque data representation of the machine identifier. This can be used to recreate the same machine identifier with NewGenericMachineIdentifierWithData function.

type GenericPlatformConfiguration 

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

GenericPlatformConfiguration is the platform configuration for a generic Intel or ARM virtual machine.

func NewGenericPlatformConfiguration 

func NewGenericPlatformConfiguration(opts ...GenericPlatformConfigurationOption) (*GenericPlatformConfiguration, error)

NewGenericPlatformConfiguration creates a new generic platform configuration.

This is only supported on macOS 12 and newer, error will be returned on older versions.

func (*GenericPlatformConfiguration) MachineIdentifier 

func (m *GenericPlatformConfiguration) MachineIdentifier() *GenericMachineIdentifier

MachineIdentifier returns the machine identifier.

type GenericPlatformConfigurationOption 

type GenericPlatformConfigurationOption func(*GenericPlatformConfiguration) error

GenericPlatformConfigurationOption is an optional function to create its configuration.

func WithGenericMachineIdentifier 

func WithGenericMachineIdentifier(m *GenericMachineIdentifier) GenericPlatformConfigurationOption

WithGenericMachineIdentifier is an option to create a new GenericPlatformConfiguration.

This is only supported on macOS 13 and newer, error will be returned on older versions.

type GraphicsDeviceConfiguration 

type GraphicsDeviceConfiguration interface {
	objc.NSObject
	// contains filtered or unexported methods
}

GraphicsDeviceConfiguration is an interface for a graphics device configuration.

type KeyboardConfiguration 

type KeyboardConfiguration interface {
	objc.NSObject
	// contains filtered or unexported methods
}

KeyboardConfiguration interface for a keyboard configuration.

type LinuxBootLoader 

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

LinuxBootLoader Boot loader configuration for a Linux kernel. see: https://developer.apple.com/documentation/virtualization/vzlinuxbootloader?language=objc

func NewLinuxBootLoader 

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

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

This is only supported on macOS 11 and newer, error will be returned on older versions.

func (*LinuxBootLoader) String 

func (b *LinuxBootLoader) String() string

type LinuxBootLoaderOption 

type LinuxBootLoaderOption func(b *LinuxBootLoader) error

LinuxBootLoaderOption is an option for 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 

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 

func NewMACAddress(macAddr net.HardwareAddr) (*MACAddress, error)

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

This is only supported on macOS 11 and newer, error will be returned on older versions.

func NewRandomLocallyAdministeredMACAddress 

func NewRandomLocallyAdministeredMACAddress() (*MACAddress, error)

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

This is only supported on macOS 11 and newer, error will be returned on older versions.

func (*MACAddress) HardwareAddr 

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

func (*MACAddress) String 

func (m *MACAddress) String() string

type MemoryBalloonDeviceConfiguration 

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

MemoryBalloonDeviceConfiguration for a memory balloon device configuration.

type MultipleDirectoryShare 

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

MultipleDirectoryShare defines the directory share for multiple directories.

func NewMultipleDirectoryShare 

func NewMultipleDirectoryShare(shares map[string]*SharedDirectory) (*MultipleDirectoryShare, error)

NewMultipleDirectoryShare creates a new multiple directories share.

This is only supported on macOS 12 and newer, error will be returned on older versions.

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, error)

NewNATNetworkDeviceAttachment creates a new NATNetworkDeviceAttachment.

This is only supported on macOS 11 and newer, error will be returned on older versions.

type NSError 

type NSError struct {
	Domain               string
	Code                 int
	LocalizedDescription string
	UserInfo             string
}

NSError indicates NSError.

func (*NSError) Error 

func (n *NSError) Error() string

type NVMExpressControllerDeviceConfiguration added in v3.1.0 

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

NVMExpressControllerDeviceConfiguration is a configuration of an NVM Express Controller storage device.

This device configuration creates a storage device that conforms to the NVM Express specification revision 1.1b.

func NewNVMExpressControllerDeviceConfiguration added in v3.1.0 

func NewNVMExpressControllerDeviceConfiguration(attachment StorageDeviceAttachment) (*NVMExpressControllerDeviceConfiguration, error)

NewNVMExpressControllerDeviceConfiguration creates a new NVMExpressControllerDeviceConfiguration with a device attachment.

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

This is only supported on macOS 14 and newer, error will be returned on older versions.

type NetworkDeviceAttachment 

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

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

type NewEFIBootLoaderOption 

type NewEFIBootLoaderOption func(b *EFIBootLoader)

NewEFIBootLoaderOption is an option type to initialize a new EFIBootLoader.

func WithEFIVariableStore 

func WithEFIVariableStore(variableStore *EFIVariableStore) NewEFIBootLoaderOption

WithEFIVariableStore sets the optional EFI variable store.

type NewEFIVariableStoreOption 

type NewEFIVariableStoreOption func(*EFIVariableStore) error

NewEFIVariableStoreOption is an option type to initialize a new EFIVariableStore.

func WithCreatingEFIVariableStore 

func WithCreatingEFIVariableStore() NewEFIVariableStoreOption

WithCreatingEFIVariableStore is an option to initialized VZEFIVariableStore to a path on a file system. If the variable store already exists in path, it is overwritten.

type NewVirtioConsolePortConfigurationOption 

type NewVirtioConsolePortConfigurationOption func(*VirtioConsolePortConfiguration)

NewVirtioConsolePortConfigurationOption is an option type to initialize a new VirtioConsolePortConfiguration

func WithVirtioConsolePortConfigurationAttachment 

func WithVirtioConsolePortConfigurationAttachment(attachment SerialPortAttachment) NewVirtioConsolePortConfigurationOption

WithVirtioConsolePortConfigurationAttachment sets the console port attachment. The default is nil.

func WithVirtioConsolePortConfigurationIsConsole 

func WithVirtioConsolePortConfigurationIsConsole(isConsole bool) NewVirtioConsolePortConfigurationOption

WithVirtioConsolePortConfigurationIsConsole sets the console port may be marked for use as the system console. The default is false.

func WithVirtioConsolePortConfigurationName 

func WithVirtioConsolePortConfigurationName(name string) NewVirtioConsolePortConfigurationOption

WithVirtioConsolePortConfigurationName sets the console port's name. The default behavior is to not use a name unless set.

type PlatformConfiguration 

type PlatformConfiguration interface {
	objc.NSObject
	// contains filtered or unexported methods
}

PlatformConfiguration is an interface for a platform configuration.

type PointingDeviceConfiguration 

type PointingDeviceConfiguration interface {
	objc.NSObject
	// contains filtered or unexported methods
}

PointingDeviceConfiguration is an interface for a pointing device configuration.

type SerialPortAttachment 

type SerialPortAttachment interface {
	objc.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 SharedDirectory 

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

SharedDirectory is a shared directory.

func NewSharedDirectory 

func NewSharedDirectory(dirPath string, readOnly bool) (*SharedDirectory, error)

NewSharedDirectory creates a new shared directory.

This is only supported on macOS 12 and newer, error will be returned on older versions.

type SingleDirectoryShare 

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

SingleDirectoryShare defines the directory share for a single directory.

func NewSingleDirectoryShare 

func NewSingleDirectoryShare(share *SharedDirectory) (*SingleDirectoryShare, error)

NewSingleDirectoryShare creates a new single directory share.

This is only supported on macOS 12 and newer, error will be returned on older versions.

type SocketDeviceConfiguration 

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

SocketDeviceConfiguration for a socket device configuration.

type SpiceAgentPortAttachment 

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

SpiceAgentPortAttachment is an attachment point that enables the Spice clipboard sharing capability.

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

func NewSpiceAgentPortAttachment 

func NewSpiceAgentPortAttachment() (*SpiceAgentPortAttachment, error)

NewSpiceAgentPortAttachment creates a new Spice agent port attachment.

This is only supported on macOS 13 and newer, error will be returned on older versions.

func (*SpiceAgentPortAttachment) SetSharesClipboard 

func (s *SpiceAgentPortAttachment) SetSharesClipboard(enable bool)

SetSharesClipboard sets enable the Spice agent clipboard sharing capability.

func (*SpiceAgentPortAttachment) SharesClipboard 

func (s *SpiceAgentPortAttachment) SharesClipboard() bool

SharesClipboard returns enable the Spice agent clipboard sharing capability.

type StorageDeviceAttachment 

type StorageDeviceAttachment interface {
	objc.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 {
	objc.NSObject
	// contains filtered or unexported methods
}

StorageDeviceConfiguration for a storage device configuration.

type USBKeyboardConfiguration 

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

USBKeyboardConfiguration is a device that defines the configuration for a USB keyboard.

func NewUSBKeyboardConfiguration 

func NewUSBKeyboardConfiguration() (*USBKeyboardConfiguration, error)

NewUSBKeyboardConfiguration creates a new USB keyboard configuration.

This is only supported on macOS 12 and newer, error will be returned on older versions.

type USBMassStorageDeviceConfiguration 

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

USBMassStorageDeviceConfiguration is a configuration of a USB Mass Storage storage device.

This device configuration creates a storage device that conforms to the USB Mass Storage specification.

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

func NewUSBMassStorageDeviceConfiguration 

func NewUSBMassStorageDeviceConfiguration(attachment StorageDeviceAttachment) (*USBMassStorageDeviceConfiguration, error)

NewUSBMassStorageDeviceConfiguration initialize a USBMassStorageDeviceConfiguration with a device attachment.

This is only supported on macOS 13 and newer, error will be returned on older versions.

type USBScreenCoordinatePointingDeviceConfiguration 

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

USBScreenCoordinatePointingDeviceConfiguration is a struct that defines the configuration for a USB pointing device that reports absolute coordinates.

func NewUSBScreenCoordinatePointingDeviceConfiguration 

func NewUSBScreenCoordinatePointingDeviceConfiguration() (*USBScreenCoordinatePointingDeviceConfiguration, error)

NewUSBScreenCoordinatePointingDeviceConfiguration creates a new USBScreenCoordinatePointingDeviceConfiguration.

This is only supported on macOS 12 and newer, error will be returned on older versions.

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, error)

NewVirtioBlockDeviceConfiguration initialize a VZVirtioBlockDeviceConfiguration with a device attachment.

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

This is only supported on macOS 11 and newer, error will be returned on older versions.

func (*VirtioBlockDeviceConfiguration) BlockDeviceIdentifier 

func (v *VirtioBlockDeviceConfiguration) BlockDeviceIdentifier() (string, error)

BlockDeviceIdentifier returns the device identifier is a string identifying the Virtio block device. Empty string by default.

The identifier can be retrieved in the guest via a VIRTIO_BLK_T_GET_ID request.

This is only supported on macOS 12.3 and newer, error will be returned on older versions.

see: https://developer.apple.com/documentation/virtualization/vzvirtioblockdeviceconfiguration/3917717-blockdeviceidentifier

func (*VirtioBlockDeviceConfiguration) SetBlockDeviceIdentifier 

func (v *VirtioBlockDeviceConfiguration) SetBlockDeviceIdentifier(identifier string) error

SetBlockDeviceIdentifier sets the device identifier is a string identifying the Virtio block device.

The device identifier must be at most 20 bytes in length and ASCII-encodable.

This is only supported on macOS 12.3 and newer, error will be returned on older versions.

see: https://developer.apple.com/documentation/virtualization/vzvirtioblockdeviceconfiguration/3917717-blockdeviceidentifier

type VirtioConsoleDeviceConfiguration 

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

VirtioConsoleDeviceConfiguration is Virtio Console Device.

func NewVirtioConsoleDeviceConfiguration 

func NewVirtioConsoleDeviceConfiguration() (*VirtioConsoleDeviceConfiguration, error)

NewVirtioConsoleDeviceConfiguration creates a new VirtioConsoleDeviceConfiguration.

func (*VirtioConsoleDeviceConfiguration) MaximumPortCount 

func (v *VirtioConsoleDeviceConfiguration) MaximumPortCount() uint32

MaximumPortCount returns the maximum number of ports allocated by this device. The default is the number of ports attached to this device.

func (*VirtioConsoleDeviceConfiguration) SetVirtioConsolePortConfiguration 

func (v *VirtioConsoleDeviceConfiguration) SetVirtioConsolePortConfiguration(idx int, portConfig *VirtioConsolePortConfiguration)

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, error)

NewVirtioConsoleDeviceSerialPortConfiguration creates a new NewVirtioConsoleDeviceSerialPortConfiguration.

This is only supported on macOS 11 and newer, error will be returned on older versions.

type VirtioConsolePortConfiguration 

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

VirtioConsolePortConfiguration is Virtio Console Port

A console port is a two-way communication channel between a host VZSerialPortAttachment and a virtual machine console port. One or more console ports are attached to a Virtio console device.

func NewVirtioConsolePortConfiguration 

func NewVirtioConsolePortConfiguration(opts ...NewVirtioConsolePortConfigurationOption) (*VirtioConsolePortConfiguration, error)

NewVirtioConsolePortConfiguration creates a new VirtioConsolePortConfiguration.

This is only supported on macOS 13 and newer, error will be returned on older versions.

func (*VirtioConsolePortConfiguration) Attachment 

func (v *VirtioConsolePortConfiguration) Attachment() SerialPortAttachment

Attachment returns the console port attachment.

func (*VirtioConsolePortConfiguration) IsConsole 

func (v *VirtioConsolePortConfiguration) IsConsole() bool

IsConsole returns the console port may be marked for use as the system console.

func (*VirtioConsolePortConfiguration) Name 

func (v *VirtioConsolePortConfiguration) Name() string

Name returns the console port's name.

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, error)

NewVirtioEntropyDeviceConfiguration creates a new Virtio Entropy Device confiuration.

This is only supported on macOS 11 and newer, error will be returned on older versions.

type VirtioFileSystemDeviceConfiguration 

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

VirtioFileSystemDeviceConfiguration is a configuration of a Virtio file system device.

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

func NewVirtioFileSystemDeviceConfiguration 

func NewVirtioFileSystemDeviceConfiguration(tag string) (*VirtioFileSystemDeviceConfiguration, error)

NewVirtioFileSystemDeviceConfiguration create a new VirtioFileSystemDeviceConfiguration.

This is only supported on macOS 12 and newer, error will be returned on older versions.

func (*VirtioFileSystemDeviceConfiguration) SetDirectoryShare 

func (c *VirtioFileSystemDeviceConfiguration) SetDirectoryShare(share DirectoryShare)

SetDirectoryShare sets the directory share associated with this configuration.

type VirtioGraphicsDeviceConfiguration 

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

VirtioGraphicsDeviceConfiguration is configuration that represents the configuration of a Virtio graphics device for a Linux VM.

This device configuration creates a graphics device using paravirtualization. The emulated device follows the Virtio GPU Device specification.

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

func NewVirtioGraphicsDeviceConfiguration 

func NewVirtioGraphicsDeviceConfiguration() (*VirtioGraphicsDeviceConfiguration, error)

NewVirtioGraphicsDeviceConfiguration creates a new Virtio graphics device.

This is only supported on macOS 13 and newer, error will be returned on older versions.

func (*VirtioGraphicsDeviceConfiguration) SetScanouts 

func (v *VirtioGraphicsDeviceConfiguration) SetScanouts(scanoutConfigs ...*VirtioGraphicsScanoutConfiguration)

SetScanouts sets the displays associated with this graphics device.

Maximum of one scanout is supported.

type VirtioGraphicsScanoutConfiguration 

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

VirtioGraphicsScanoutConfiguration is the configuration for a Virtio graphics device that configures the dimensions of the graphics device for a Linux VM. see: https://developer.apple.com/documentation/virtualization/vzvirtiographicsscanoutconfiguration?language=objc

func NewVirtioGraphicsScanoutConfiguration 

func NewVirtioGraphicsScanoutConfiguration(widthInPixels int64, heightInPixels int64) (*VirtioGraphicsScanoutConfiguration, error)

NewVirtioGraphicsScanoutConfiguration creates a Virtio graphics device with the specified dimensions.

This is only supported on macOS 13 and newer, error will be returned on older versions.

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, error)

NewVirtioNetworkDeviceConfiguration creates a new VirtioNetworkDeviceConfiguration with NetworkDeviceAttachment.

This is only supported on macOS 11 and newer, error will be returned on older versions.

func (*VirtioNetworkDeviceConfiguration) SetMACAddress 

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

type VirtioSocketConnection 

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 is generated from duplicated a file descriptor which is returned from virtualization.framework. macOS cannot connect directly to the Guest operating system using vsock. The　vsock connection must always be made via virtualization.framework. The diagram looks like this.

┌─────────┐ ┌────────────────────────────┐ ┌────────────┐ │ macOS │<─── unix socket ───>│ virtualization.framework │<─── vsock ───>│ Guest OS │ └─────────┘ └────────────────────────────┘ └────────────┘

You will notice that this is not vsock in using this library. However, all data this connection goes through to the vsock connection to which the Guest OS is connected.

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 

func (v *VirtioSocketConnection) Close() error

Close will be called when caused something error in socket.

func (*VirtioSocketConnection) DestinationPort 

func (v *VirtioSocketConnection) DestinationPort() uint32

DestinationPort returns the destination port number of the connection.

func (*VirtioSocketConnection) LocalAddr 

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

LocalAddr returns the local network address.

func (*VirtioSocketConnection) Read 

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

Read reads data from connection of the vsock protocol.

func (*VirtioSocketConnection) RemoteAddr 

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

RemoteAddr returns the remote network address.

func (*VirtioSocketConnection) SetDeadline 

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 

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 

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 

func (v *VirtioSocketConnection) SourcePort() uint32

SourcePort returns the source port number of the connection.

func (*VirtioSocketConnection) Write 

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

Write writes data to the connection of the vsock protocol.

type VirtioSocketDevice 

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

func (v *VirtioSocketDevice) Connect(port uint32) (*VirtioSocketConnection, error)

Connect 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 specified 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) Listen 

func (v *VirtioSocketDevice) Listen(port uint32) (*VirtioSocketListener, error)

Listen creates a new VirtioSocketListener which is a struct that listens for port-based connection requests from the guest operating system.

Be sure to close the listener by calling `VirtioSocketListener.Close` after used this one.

This is only supported on macOS 11 and newer, error will be returned on older versions.

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, error)

NewVirtioSocketDeviceConfiguration creates a new VirtioSocketDeviceConfiguration.

This is only supported on macOS 11 and newer, error will be returned on older versions.

type VirtioSocketListener 

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 (*VirtioSocketListener) Accept 

func (v *VirtioSocketListener) Accept() (net.Conn, error)

Accept implements the Accept method in the Listener interface; it waits for the next call and returns a net.Conn.

func (*VirtioSocketListener) AcceptVirtioSocketConnection 

func (v *VirtioSocketListener) AcceptVirtioSocketConnection() (*VirtioSocketConnection, error)

AcceptVirtioSocketConnection accepts the next incoming call and returns the new connection.

func (*VirtioSocketListener) Addr 

func (v *VirtioSocketListener) Addr() net.Addr

Addr returns the listener's network address, a *VirtioSocketListenerAddr.

func (*VirtioSocketListener) Close 

func (v *VirtioSocketListener) Close() error

Close stops listening on the virtio socket.

type VirtioSocketListenerAddr 

type VirtioSocketListenerAddr struct {
	CID  uint32
	Port uint32
}

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

func (*VirtioSocketListenerAddr) Network 

func (a *VirtioSocketListenerAddr) Network() string

Network returns "vsock".

func (*VirtioSocketListenerAddr) String 

func (a *VirtioSocketListenerAddr) String() string

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

type VirtioSoundDeviceConfiguration 

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

VirtioSoundDeviceConfiguration is a struct that defines a Virtio sound device configuration.

Use a VirtioSoundDeviceConfiguration to configure an audio device for your VM. After creating this struct, assign appropriate values via the SetStreams method which defines the behaviors of the underlying audio streams for this audio device.

After creating and configuring a VirtioSoundDeviceConfiguration struct, assign it to the SetAudioDevicesVirtualMachineConfiguration method of your VM’s configuration.

func NewVirtioSoundDeviceConfiguration 

func NewVirtioSoundDeviceConfiguration() (*VirtioSoundDeviceConfiguration, error)

NewVirtioSoundDeviceConfiguration creates a new sound device configuration.

This is only supported on macOS 12 and newer, error will be returned on older versions.

func (*VirtioSoundDeviceConfiguration) SetStreams 

func (v *VirtioSoundDeviceConfiguration) SetStreams(streams ...VirtioSoundDeviceStreamConfiguration)

SetStreams sets the list of audio streams exposed by this device.

type VirtioSoundDeviceHostInputStreamConfiguration 

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

VirtioSoundDeviceHostInputStreamConfiguration is a PCM stream of input audio data, such as from a microphone via host.

func NewVirtioSoundDeviceHostInputStreamConfiguration 

func NewVirtioSoundDeviceHostInputStreamConfiguration() (*VirtioSoundDeviceHostInputStreamConfiguration, error)

NewVirtioSoundDeviceHostInputStreamConfiguration creates a new PCM stream configuration of input audio data from host.

This is only supported on macOS 12 and newer, error will be returned on older versions.

type VirtioSoundDeviceHostOutputStreamConfiguration 

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

VirtioSoundDeviceHostOutputStreamConfiguration is a struct that defines a Virtio host sound device output stream configuration.

A PCM stream of output audio data, such as to a speaker from host.

func NewVirtioSoundDeviceHostOutputStreamConfiguration 

func NewVirtioSoundDeviceHostOutputStreamConfiguration() (*VirtioSoundDeviceHostOutputStreamConfiguration, error)

NewVirtioSoundDeviceHostOutputStreamConfiguration creates a new sounds device output stream configuration.

This is only supported on macOS 12 and newer, error will be returned on older versions.

type VirtioSoundDeviceStreamConfiguration 

type VirtioSoundDeviceStreamConfiguration interface {
	objc.NSObject
	// contains filtered or unexported methods
}

VirtioSoundDeviceStreamConfiguration interface for Virtio Sound Device Stream Configuration.

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, error)

NewVirtioTraditionalMemoryBalloonDeviceConfiguration creates a new VirtioTraditionalMemoryBalloonDeviceConfiguration.

This is only supported on macOS 11 and newer, error will be returned on older versions.

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, error)

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.

This is only supported on macOS 11 and newer, error will be returned on older versions.

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

func (v *VirtualMachine) CanStop() bool

CanStop returns whether the machine is in a state that can be stopped.

This is only supported on macOS 12 and newer, false will always be returned on older versions.

func (*VirtualMachine) Pause 

func (v *VirtualMachine) Pause() error

Pause a virtual machine that is in Running state.

If you want to listen status change events, use the "StateChangedNotify" method.

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. Returns true if the request was made successfully.

func (*VirtualMachine) Resume 

func (v *VirtualMachine) Resume() error

Resume a virtual machine that is in the Paused state.

If you want to listen status change events, use the "StateChangedNotify" method.

func (*VirtualMachine) SocketDevices 

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(opts ...VirtualMachineStartOption) error

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

If you want to listen status change events, use the "StateChangedNotify" method.

If options are specified, also checks whether these options are available in use your macOS version available.

func (*VirtualMachine) StartGraphicApplication 

func (v *VirtualMachine) StartGraphicApplication(width, height float64) error

StartGraphicApplication starts an application to display graphics of the VM.

You must to call runtime.LockOSThread before calling this method.

This is only supported on macOS 12 and newer, error will be returned on older versions.

func (*VirtualMachine) State 

func (v *VirtualMachine) State() VirtualMachineState

State represents execution state of the virtual machine.

func (*VirtualMachine) StateChangedNotify 

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

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

func (*VirtualMachine) Stop 

func (v *VirtualMachine) Stop() error

Stop stops a VM that’s in either a running or paused state.

The completion handler returns an error object when the VM fails to stop, or nil if the stop was successful.

If you want to listen status change events, use the "StateChangedNotify" method.

Warning: This is a destructive operation. It stops the VM without giving the guest a chance to stop cleanly.

This is only supported on macOS 12 and newer, error will be returned on older versions.

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, error)

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.

This is only supported on macOS 11 and newer, error will be returned on older versions.

func (*VirtualMachineConfiguration) NetworkDevices 

func (v *VirtualMachineConfiguration) NetworkDevices() []*VirtioNetworkDeviceConfiguration

NetworkDevices return the list of network device configuration set in this virtual machine configuration. Return an empty array if no network device configuration is set.

func (*VirtualMachineConfiguration) SetAudioDevicesVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetAudioDevicesVirtualMachineConfiguration(cs []AudioDeviceConfiguration)

SetAudioDevicesVirtualMachineConfiguration sets list of audio devices. Empty by default.

This is only supported on macOS 12 and newer. Older versions do nothing.

func (*VirtualMachineConfiguration) SetConsoleDevicesVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetConsoleDevicesVirtualMachineConfiguration(cs []ConsoleDeviceConfiguration)

SetConsoleDevicesVirtualMachineConfiguration sets list of console devices. Empty by default.

This is only supported on macOS 13 and newer. Older versions do nothing.

func (*VirtualMachineConfiguration) SetDirectorySharingDevicesVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetDirectorySharingDevicesVirtualMachineConfiguration(cs []DirectorySharingDeviceConfiguration)

SetDirectorySharingDevicesVirtualMachineConfiguration sets list of directory sharing devices. Empty by default.

This is only supported on macOS 12 and newer. Older versions do nothing.

func (*VirtualMachineConfiguration) SetEntropyDevicesVirtualMachineConfiguration 

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

SetEntropyDevicesVirtualMachineConfiguration sets list of entropy devices. Empty by default.

func (*VirtualMachineConfiguration) SetGraphicsDevicesVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetGraphicsDevicesVirtualMachineConfiguration(cs []GraphicsDeviceConfiguration)

SetGraphicsDevicesVirtualMachineConfiguration sets list of graphics devices. Empty by default.

This is only supported on macOS 12 and newer. Older versions do nothing.

func (*VirtualMachineConfiguration) SetKeyboardsVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetKeyboardsVirtualMachineConfiguration(cs []KeyboardConfiguration)

SetKeyboardsVirtualMachineConfiguration sets list of keyboards. Empty by default.

This is only supported on macOS 12 and newer. Older versions do nothing.

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

func (v *VirtualMachineConfiguration) SetPlatformVirtualMachineConfiguration(c PlatformConfiguration)

SetPlatformVirtualMachineConfiguration sets the hardware platform to use. Defaults to GenericPlatformConfiguration.

This is only supported on macOS 12 and newer. Older versions do nothing.

func (*VirtualMachineConfiguration) SetPointingDevicesVirtualMachineConfiguration 

func (v *VirtualMachineConfiguration) SetPointingDevicesVirtualMachineConfiguration(cs []PointingDeviceConfiguration)

SetPointingDevicesVirtualMachineConfiguration sets list of pointing devices. Empty by default.

This is only supported on macOS 12 and newer. Older versions do nothing.

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

func (v *VirtualMachineConfiguration) SocketDevices() []SocketDeviceConfiguration

SocketDevices return the list of socket device configuration configured in this virtual machine configuration. Return an empty array if no socket device configuration is set.

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 VirtualMachineStartOption 

type VirtualMachineStartOption func(*virtualMachineStartOptions) error

VirtualMachineStartOption is an option for virtual machine start.

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

	// VirtualMachineStateStopping The virtual machine is being stopped.
	// This is the intermediate state between VirtualMachineStateRunning and VirtualMachineStateStop.
	//
	// Available on macOS 12.0 and above.
	VirtualMachineStateStopping

	// VirtualMachineStateSaving The virtual machine is being saved.
	// This is the intermediate state between VirtualMachineStatePaused and VirtualMachineStatePaused
	//
	// Available on macOS 14.0 and above.
	VirtualMachineStateSaving

	// VirtualMachineStateRestoring	The virtual machine is being restored.
	// This is the intermediate state between VirtualMachineStateStopped and either VirtualMachineStatePaused on success or VirtualMachineStateStopped on failure.
	//
	// Available on macOS 14.0 and above.
	VirtualMachineStateRestoring
)

func (VirtualMachineState) String 

func (i VirtualMachineState) String() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
addtags
codesign
internal
objc
progress
testhelper

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.