device

Documentation

Overview

Example (InfinibandValidMAC)

tests := []string{
	"00:00:00:00:fe:80:00:00:00:00:00:00:02:00:5e:10:00:00:00:01", // valid long form
	"a0:00:0f:c0:fe:80:00:00:00:00:00:00:4a:c8:f9:1b:aa:57:ef:19", // valid long form
	"02:00:5e:10:00:00:00:01",                                     // valid short form
	"4a:c8:f9:1b:aa:57:ef:19",                                     // valid short form
	"00-00-00-00-fe-80-00-00-00-00-00-00-02-00-5e-10-00-00-00-01", // invalid delimiter long form
	"0000.0000.fe80.0000.0000.0000.0200.5e10.0000.0001",           // invalid delimiter long form
	"02-00-5e-10-00-00-00-01",                                     // invalid delimiter short form
	"0200.5e10.0000.0001",                                         // invalid delimiter short form
	"00:00:5e:00:53:01",                                           // invalid ethernet MAC
	"invalid",
	"",
}

for _, v := range tests {
	err := infinibandValidMAC(v)
	fmt.Printf("%s, %t\n", v, err == nil)
}

Output:

00:00:00:00:fe:80:00:00:00:00:00:00:02:00:5e:10:00:00:00:01, true
a0:00:0f:c0:fe:80:00:00:00:00:00:00:4a:c8:f9:1b:aa:57:ef:19, true
02:00:5e:10:00:00:00:01, true
4a:c8:f9:1b:aa:57:ef:19, true
00-00-00-00-fe-80-00-00-00-00-00-00-02-00-5e-10-00-00-00-01, false
0000.0000.fe80.0000.0000.0000.0200.5e10.0000.0001, false
02-00-5e-10-00-00-00-01, false
0200.5e10.0000.0001, false
00:00:5e:00:53:01, false
invalid, false
, false

Index

• Constants
• Variables
• func BlockFsDetect(dev string) (string, error)
• func DiskGetRBDFormat(clusterName string, userName string, poolName string, volumeName string) string
• func DiskMount(srcPath string, dstPath string, recursive bool, propagation string, ...) error
• func DiskMountClear(mntPath string) error
• func DiskParseRBDFormat(rbd string) (string, string, []string, error)
• func DiskVMVirtfsProxyStart(execPath string, pidPath string, sharePath string, idmaps []idmap.Entry) (*os.File, revert.Hook, error)
• func DiskVMVirtfsProxyStop(pidPath string) error
• func DiskVMVirtiofsdStart(execPath string, inst instance.Instance, socketPath string, pidPath string, ...) (func(), net.Listener, error)
• func DiskVMVirtiofsdStop(socketPath string, pidPath string) error
• func IsBlockdev(path string) bool
• func NetworkGetDevMAC(devName string) (string, error)
• func NetworkSetDevMAC(devName string, mac string) error
• func NetworkSetDevMTU(devName string, mtu uint32) error
• func Register(inst instance.Instance, s *state.State, name string, conf deviceConfig.Device) error
• func USBRunHandlers(state *state.State, event *USBEvent)
• func UnixDeviceExists(devicesPath string, prefix string, path string) bool
• func UnixHotplugRunHandlers(state *state.State, event *UnixHotplugEvent)
• func Validate(instConfig instance.ConfigReader, state *state.State, name string, ...) error
• type Device
  • func New(inst instance.Instance, state *state.State, name string, ...) (Device, error)
• type NICState
• type Type
  • func LoadByType(state *state.State, projectName string, conf deviceConfig.Device) (Type, error)
• type USBEvent
  • func USBNewEvent(action string, vendor string, product string, serial string, major string, ...) (USBEvent, error)
• type UnixDevice
  • func UnixDeviceCreate(s *state.State, idmapSet *idmap.Set, devicesPath string, prefix string, ...) (*UnixDevice, error)
• type UnixEvent
• type UnixHotplugEvent
  • func UnixHotplugNewEvent(action string, vendor string, product string, major string, minor string, ...) (UnixHotplugEvent, error)
• type UnixSubscription
• type UnsupportedError
  • func (e UnsupportedError) Error() string
• type VolatileGetter
• type VolatileSetter

Examples

• Package (InfinibandValidMAC)

Constants

const DiskDirectIO = "directio"

DiskDirectIO is used to indicate disk should use direct I/O.

const DiskFileDescriptorMountPrefix = "fd"

DiskFileDescriptorMountPrefix indicates the mount dev path is using a file descriptor rather than a normal path. The Mount.DevPath field will be expected to be in the format: "fd:<fdNum>:<devPath>". It still includes the original dev path so that the instance driver can perform additional probing of the path to ascertain additional information if needed. However it will not be used to actually pass the path into the instance.

const DiskIOUring = "io_uring"

DiskIOUring is used to indicate disk should use io_uring if the system supports it.

const DiskLoopBacked = "loop"

DiskLoopBacked is used to indicate disk is backed onto a loop device.

const DiskVirtiofsdSockMountOpt = "virtiofsdSock"

DiskVirtiofsdSockMountOpt indicates the mount option prefix used to provide the virtiofsd socket path to the QEMU driver.

const GPUNvidiaDeviceKey = "nvidia.device"

GPUNvidiaDeviceKey is the key used for NVIDIA devices through libnvidia-container.

const IBDevPrefix = "infiniband.unix"

IBDevPrefix Infiniband devices prefix.

const RBDFormatPrefix = "rbd"

RBDFormatPrefix is the prefix used in disk paths to identify RBD.

const RBDFormatSeparator = " "

RBDFormatSeparator is the field separate used in disk paths for RBD devices.

Variables

var ErrCannotUpdate = fmt.Errorf("Device does not support updates")

ErrCannotUpdate is the error that occurs when a device cannot be updated.

var ErrMissingVirtiofsd = UnsupportedError{/* contains filtered or unexported fields */}

ErrMissingVirtiofsd is the error that occurs if virtiofsd is missing.

var ErrUnsupportedDevType = UnsupportedError{/* contains filtered or unexported fields */}

ErrUnsupportedDevType is the error that occurs when an unsupported device type is created.

Functions

func BlockFsDetect

func BlockFsDetect(dev string) (string, error)

BlockFsDetect detects the type of block device.

func DiskGetRBDFormat

func DiskGetRBDFormat(clusterName string, userName string, poolName string, volumeName string) string

DiskGetRBDFormat returns a rbd formatted string with the given values.

func DiskMount

func DiskMount(srcPath string, dstPath string, recursive bool, propagation string, mountOptions []string, fsName string) error

DiskMount mounts a disk device.

func DiskMountClear

func DiskMountClear(mntPath string) error

DiskMountClear unmounts and removes the mount path used for disk shares.

func DiskParseRBDFormat

func DiskParseRBDFormat(rbd string) (string, string, []string, error)

DiskParseRBDFormat parses an rbd formatted string, and returns the pool name, volume name, and list of options.

func DiskVMVirtfsProxyStart

func DiskVMVirtfsProxyStart(execPath string, pidPath string, sharePath string, idmaps []idmap.Entry) (*os.File, revert.Hook, error)

DiskVMVirtfsProxyStart starts a new virtfs-proxy-helper process. If the idmaps slice is supplied then the proxy process is run inside a user namespace using the supplied maps. Returns a file handle to the proxy process and a revert fail function that can be used to undo this function if a subsequent step fails,.

func DiskVMVirtfsProxyStop

func DiskVMVirtfsProxyStop(pidPath string) error

DiskVMVirtfsProxyStop stops the virtfs-proxy-helper process.

func DiskVMVirtiofsdStart

func DiskVMVirtiofsdStart(execPath string, inst instance.Instance, socketPath string, pidPath string, logPath string, sharePath string, idmaps []idmap.Entry, cacheOption string) (func(), net.Listener, error)

DiskVMVirtiofsdStart starts a new virtiofsd process. If the idmaps slice is supplied then the proxy process is run inside a user namespace using the supplied maps. Returns UnsupportedError error if the host system or instance does not support virtiosfd, returns normal error type if process cannot be started for other reasons. Returns revert function and listener file handle on success.

func DiskVMVirtiofsdStop

func DiskVMVirtiofsdStop(socketPath string, pidPath string) error

DiskVMVirtiofsdStop stops an existing virtiofsd process and cleans up.

func IsBlockdev

func IsBlockdev(path string) bool

IsBlockdev returns boolean indicating whether device is block type.

func NetworkGetDevMAC

func NetworkGetDevMAC(devName string) (string, error)

NetworkGetDevMAC retrieves the current MAC setting for a named network device.

func NetworkSetDevMAC

func NetworkSetDevMAC(devName string, mac string) error

NetworkSetDevMAC sets the MAC setting for a named network device if different from current.

func NetworkSetDevMTU

func NetworkSetDevMTU(devName string, mtu uint32) error

NetworkSetDevMTU sets the MTU setting for a named network device if different from current.

func Register

func Register(inst instance.Instance, s *state.State, name string, conf deviceConfig.Device) error

Register performs a lightweight load of the device, bypassing most validation to very quickly register the device on server startup.

func USBRunHandlers

func USBRunHandlers(state *state.State, event *USBEvent)

USBRunHandlers executes any handlers registered for USB events.

func UnixDeviceExists

func UnixDeviceExists(devicesPath string, prefix string, path string) bool

UnixDeviceExists checks if the unix device already exists in devices path.

func UnixHotplugRunHandlers

func UnixHotplugRunHandlers(state *state.State, event *UnixHotplugEvent)

UnixHotplugRunHandlers executes any handlers registered for Unix hotplug events.

func Validate

func Validate(instConfig instance.ConfigReader, state *state.State, name string, conf deviceConfig.Device) error

Validate checks a device's config is valid. This only requires an instance.ConfigReader rather than an full blown instance to allow profile devices to be validated too. Note: The supplied config may be modified during validation to enrich. If this is not desired, supply a copy.

Types

type Device

type Device interface {
	Type

	Config() deviceConfig.Device
	Name() string

	// Add performs any host-side setup when a device is added to an instance.
	// It is called irrespective of whether the instance is running or not.
	Add() error

	// PreStartCheck indicates if the device is available for starting.
	PreStartCheck() error

	// Start peforms any host-side configuration required to start the device for the instance.
	// This can be when a device is plugged into a running instance or the instance is starting.
	// Returns run-time configuration needed for configuring the instance with the new device.
	Start() (*deviceConfig.RunConfig, error)

	// Register provides the ability for a device to subcribe to daemon generated events.
	// It is called after a device is started (after Start()) or on daemon startup.
	Register() error

	// Update performs host-side modifications for a device based on the difference between the
	// current config and previous devices config supplied as an argument. This called if the
	// only config fields that have changed are supplied in the list returned from UpdatableFields().
	// The function also accepts a boolean indicating whether the instance is running or not.
	Update(oldDevices deviceConfig.Devices, running bool) error

	// Stop performs any host-side cleanup required when a device is removed from an instance,
	// either due to unplugging it from a running instance or instance is being shutdown.
	// Returns run-time configuration needed for detaching the device from the instance.
	Stop() (*deviceConfig.RunConfig, error)

	// Remove performs any host-side cleanup when a device is removed from an instance.
	Remove() error
}

Device represents a device that can be added to an instance.

func New

func New(inst instance.Instance, state *state.State, name string, conf deviceConfig.Device, volatileGet VolatileGetter, volatileSet VolatileSetter) (Device, error)

New instantiates a new device struct, validates the supplied config and sets it into the device. If the device type is valid, but the other config validation fails then an instantiated device is still returned with the validation error. If an unknown device is requested or the device is not compatible with the instance type then an ErrUnsupportedDevType error is returned. Note: The supplied config may be modified during validation to enrich. If this is not desired, supply a copy.

type NICState

type NICState interface {
	State() (*api.InstanceStateNetwork, error)
}

NICState provides the ability to access NIC state.

type Type

type Type interface {
	// CanHotPlug returns true if the device can be managed whilst instance is running.
	CanHotPlug() bool

	// CanMigrate returns true if the device should work properly on any cluster member.
	CanMigrate() bool

	// UpdatableFields returns a slice of config fields that can be updated. If only fields in this list have
	// changed then Update() is called rather triggering a device remove & add.
	UpdatableFields(oldDevice Type) []string
}

Type represents a device type.

func LoadByType

func LoadByType(state *state.State, projectName string, conf deviceConfig.Device) (Type, error)

LoadByType loads a device by type based on its project and config. It does not validate config beyond the type fields.

type USBEvent

type USBEvent struct {
	Action string

	Vendor  string
	Product string
	Serial  string

	Path        string
	Major       uint32
	Minor       uint32
	UeventParts []string
	UeventLen   int

	BusNum int
	DevNum int
}

USBEvent represents the properties of a USB device uevent.

func USBNewEvent

func USBNewEvent(action string, vendor string, product string, serial string, major string, minor string, busnum string, devnum string, devname string, ueventParts []string, ueventLen int) (USBEvent, error)

USBNewEvent instantiates a new USBEvent struct.

type UnixDevice

type UnixDevice struct {
	HostPath     string      // Absolute path to the device on the host.
	RelativePath string      // Relative path where the device will be mounted inside instance.
	Type         string      // Type of device; c (for char) or b for (block).
	Major        uint32      // Major number.
	Minor        uint32      // Minor number.
	Mode         os.FileMode // File mode.
	UID          int         // Owner UID.
	GID          int         // Owner GID.
}

UnixDevice contains information about a created UNIX device.

func UnixDeviceCreate

func UnixDeviceCreate(s *state.State, idmapSet *idmap.Set, devicesPath string, prefix string, m deviceConfig.Device, defaultMode bool) (*UnixDevice, error)

UnixDeviceCreate creates a UNIX device (either block or char). If the supplied device config map contains a major and minor number for the device, then a stat is avoided, otherwise this info retrieved from the origin device. Similarly, if a mode is supplied in the device config map or defaultMode is set as true, then the device is created with the supplied or default mode (0660) respectively, otherwise the origin device's mode is used. If the device config doesn't contain a type field then it defaults to created a unix-char device. The ownership of the created device defaults to root (0) but can be specified with the uid and gid fields in the device config map. It returns a UnixDevice containing information about the device created.

type UnixEvent

type UnixEvent struct {
	Action string // The type of event, either add or remove.
	Path   string // The absolute source path on the host.
}

UnixEvent represents the properties of a Unix device inotify event.

type UnixHotplugEvent

type UnixHotplugEvent struct {
	Action string

	Vendor  string
	Product string

	Path        string
	Major       uint32
	Minor       uint32
	Subsystem   string
	UeventParts []string
	UeventLen   int
}

UnixHotplugEvent represents the properties of a Unix hotplug device uevent.

func UnixHotplugNewEvent

func UnixHotplugNewEvent(action string, vendor string, product string, major string, minor string, subsystem string, devname string, ueventParts []string, ueventLen int) (UnixHotplugEvent, error)

UnixHotplugNewEvent instantiates a new UnixHotplugEvent struct.

type UnixSubscription

type UnixSubscription struct {
	Path    string                                           // The absolute source path on the host.
	Handler func(UnixEvent) (*deviceConfig.RunConfig, error) // The function to run when an event occurs.
}

UnixSubscription used to subcribe to specific events.

type UnsupportedError

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

UnsupportedError used for indicating the error is caused due to a lack of support.

func (UnsupportedError) Error

func (e UnsupportedError) Error() string

type VolatileGetter

type VolatileGetter func() map[string]string

VolatileGetter is a function that retrieves any key/value string that exists in the database config for this instance. It should only return keys that match the volatile device name prefix, and should remove the prefix before being returned.

type VolatileSetter

type VolatileSetter func(map[string]string) error

VolatileSetter is a function that accepts one or more key/value strings to save into the config for this instance. It should add the volatile device name prefix to each key when saving.