package uvm

import "github.com/Microsoft/hcsshim/internal/uvm"

Index

Constants 

const (
	// MaxVPMEMCount is the maximum number of VPMem devices that may be added to an LCOW
	// utility VM
	MaxVPMEMCount = 128

	// DefaultVPMEMCount is the default number of VPMem devices that may be added to an LCOW
	// utility VM if the create request doesn't specify how many.
	DefaultVPMEMCount = 64

	// DefaultVPMemSizeBytes is the default size of a VPMem device if the create request
	// doesn't specify.
	DefaultVPMemSizeBytes = 4 * 1024 * 1024 * 1024 // 4GB
)
const (
	// InitrdFile is the default file name for an initrd.img used to boot LCOW.
	InitrdFile = "initrd.img"
	// VhdFile is the default file name for a rootfs.vhd used to boot LCOW.
	VhdFile = "rootfs.vhd"
	// KernelFile is the default file name for a kernel used to boot LCOW.
	KernelFile = "kernel"
	// UncompressedKernelFile is the default file name for an uncompressed
	// kernel used to boot LCOW with KernelDirect.
	UncompressedKernelFile = "vmlinux"
)

Variables 

var (
	// ErrNetNSAlreadyAttached is an error indicating the guest UVM already has
	// an endpoint by this id.
	ErrNetNSAlreadyAttached = errors.New("network namespace already added")
	// ErrNetNSNotFound is an error indicating the guest UVM does not have a
	// network namespace by this id.
	ErrNetNSNotFound = errors.New("network namespace not found")
)
var (
	ErrNoAvailableLocation      = fmt.Errorf("no available location")
	ErrNotAttached              = fmt.Errorf("not attached")
	ErrAlreadyAttached          = fmt.Errorf("already attached")
	ErrNoSCSIControllers        = fmt.Errorf("no SCSI controllers configured for this utility VM")
	ErrTooManyAttachments       = fmt.Errorf("too many SCSI attachments")
	ErrSCSILayerWCOWUnsupported = fmt.Errorf("SCSI attached layers are not supported for WCOW")
)
var (
	// ErrMaxVPMEMLayerSize is the error returned when the size of `hostPath` is
	// greater than the max vPMEM layer size set at create time.
	ErrMaxVPMEMLayerSize = fmt.Errorf("layer size is to large for VPMEM max size")
)

Functions

func GetContainerPipeMapping 

func GetContainerPipeMapping(uvm *UtilityVM, mount specs.Mount) (src string, dst string)

GetContainerPipeMapping returns the source and destination to use for a given pipe mount in a container.

func IsPipe 

func IsPipe(hostPath string) bool

IsPipe returns true if the given path references a named pipe.

Types

type NetworkEndpoints 

type NetworkEndpoints struct {
	EndpointIDs []string
	// ID of the namespace the endpoints belong to
	Namespace string
}

NetworkEndpoints is a struct containing all of the endpoint IDs of a network namespace.

func (*NetworkEndpoints) Release 

func (endpoints *NetworkEndpoints) Release(ctx context.Context) error

Release releases the resources for all of the network endpoints in a namespace.

type Options 

type Options struct {
	ID                      string // Identifier for the uvm. Defaults to generated GUID.
	Owner                   string // Specifies the owner. Defaults to executable name.
	AdditionHCSDocumentJSON string // Optional additional JSON to merge into the HCS document prior

	// MemorySizeInMB sets the UVM memory. If `0` will default to platform
	// default.
	MemorySizeInMB int32

	LowMMIOGapInMB   uint64
	HighMMIOBaseInMB uint64
	HighMMIOGapInMB  uint64

	// Memory for UVM. Defaults to true. For physical backed memory, set to
	// false.
	AllowOvercommit bool

	// Memory for UVM. Defaults to false. For virtual memory with deferred
	// commit, set to true.
	EnableDeferredCommit bool

	// ProcessorCount sets the number of vCPU's. If `0` will default to platform
	// default.
	ProcessorCount int32

	// ProcessorLimit sets the maximum percentage of each vCPU's the UVM can
	// consume. If `0` will default to platform default.
	ProcessorLimit int32

	// ProcessorWeight sets the relative weight of these vCPU's vs another UVM's
	// when scheduling. If `0` will default to platform default.
	ProcessorWeight int32

	// StorageQoSIopsMaximum sets the maximum number of Iops. If `0` will
	// default to the platform default.
	StorageQoSIopsMaximum int32

	// StorageQoSIopsMaximum sets the maximum number of bytes per second. If `0`
	// will default to the platform default.
	StorageQoSBandwidthMaximum int32

	// ExternalGuestConnection sets whether the guest RPC connection is performed
	// internally by the OS platform or externally by this package.
	ExternalGuestConnection bool
}

Options are the set of options passed to Create() to create a utility vm.

type OptionsLCOW 

type OptionsLCOW struct {
	*Options

	BootFilesPath         string              // Folder in which kernel and root file system reside. Defaults to \Program Files\Linux Containers
	KernelFile            string              // Filename under `BootFilesPath` for the kernel. Defaults to `kernel`
	KernelDirect          bool                // Skip UEFI and boot directly to `kernel`
	RootFSFile            string              // Filename under `BootFilesPath` for the UVMs root file system. Defaults to `InitrdFile`
	KernelBootOptions     string              // Additional boot options for the kernel
	EnableGraphicsConsole bool                // If true, enable a graphics console for the utility VM
	ConsolePipe           string              // The named pipe path to use for the serial console.  eg \\.\pipe\vmpipe
	SCSIControllerCount   uint32              // The number of SCSI controllers. Defaults to 1. Currently we only support 0 or 1.
	UseGuestConnection    bool                // Whether the HCS should connect to the UVM's GCS. Defaults to true
	ExecCommandLine       string              // The command line to exec from init. Defaults to GCS
	ForwardStdout         bool                // Whether stdout will be forwarded from the executed program. Defaults to false
	ForwardStderr         bool                // Whether stderr will be forwarded from the executed program. Defaults to true
	OutputHandler         OutputHandler       `json:"-"` // Controls how output received over HVSocket from the UVM is handled. Defaults to parsing output as logrus messages
	VPMemDeviceCount      uint32              // Number of VPMem devices. Defaults to `DefaultVPMEMCount`. Limit at 128. If booting UVM from VHD, device 0 is taken.
	VPMemSizeBytes        uint64              // Size of the VPMem devices. Defaults to `DefaultVPMemSizeBytes`.
	PreferredRootFSType   PreferredRootFSType // If `KernelFile` is `InitrdFile` use `PreferredRootFSTypeInitRd`. If `KernelFile` is `VhdFile` use `PreferredRootFSTypeVHD`
	EnableColdDiscardHint bool                // Whether the HCS should use cold discard hints. Defaults to false
	VPCIEnabled           bool                // Whether the kernel should enable pci
}

OptionsLCOW are the set of options passed to CreateLCOW() to create a utility vm.

func NewDefaultOptionsLCOW 

func NewDefaultOptionsLCOW(id, owner string) *OptionsLCOW

NewDefaultOptionsLCOW creates the default options for a bootable version of LCOW.

`id` the ID of the compute system. If not passed will generate a new GUID.

`owner` the owner of the compute system. If not passed will use the executable files name.

type OptionsWCOW 

type OptionsWCOW struct {
	*Options

	LayerFolders []string // Set of folders for base layers and scratch. Ordered from top most read-only through base read-only layer, followed by scratch
}

OptionsWCOW are the set of options passed to CreateWCOW() to create a utility vm.

func NewDefaultOptionsWCOW 

func NewDefaultOptionsWCOW(id, owner string) *OptionsWCOW

NewDefaultOptionsWCOW creates the default options for a bootable version of WCOW. The caller `MUST` set the `LayerFolders` path on the returned value.

`id` the ID of the compute system. If not passed will generate a new GUID.

`owner` the owner of the compute system. If not passed will use the executable files name.

type OutputHandler 

type OutputHandler func(io.Reader)

OutputHandler is used to process the output from the program run in the UVM.

type PipeMount 

type PipeMount struct {
	HostPath string
	// contains filtered or unexported fields
}

PipeMount contains the host path for pipe mount

func (*PipeMount) Release 

func (pipe *PipeMount) Release(ctx context.Context) error

Release frees the resources of the corresponding pipe Mount

type Plan9Share 

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

Plan9Share is a struct containing host paths for the UVM

func (*Plan9Share) Release 

func (p9 *Plan9Share) Release(ctx context.Context) error

Release frees the resources of the corresponding Plan9 share

type PreferredRootFSType 

type PreferredRootFSType int
const (
	PreferredRootFSTypeInitRd PreferredRootFSType = iota
	PreferredRootFSTypeVHD
)

type SCSIMount 

type SCSIMount struct {

	// path is the host path to the vhd that is mounted.
	HostPath string
	// path for the uvm
	UVMPath string
	// scsi controller
	Controller int
	// scsi logical unit number
	LUN int32
	// contains filtered or unexported fields
}

SCSIMount struct representing a SCSI mount point and the UVM it belongs to.

func (*SCSIMount) Release 

func (sm *SCSIMount) Release(ctx context.Context) error

Release frees the resources of the corresponding Scsi Mount

type UtilityVM 

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

UtilityVM is the object used by clients representing a utility VM

func CreateLCOW 

func CreateLCOW(ctx context.Context, opts *OptionsLCOW) (_ *UtilityVM, err error)

CreateLCOW creates an HCS compute system representing a utility VM.

func CreateWCOW 

func CreateWCOW(ctx context.Context, opts *OptionsWCOW) (_ *UtilityVM, err error)

CreateWCOW creates an HCS compute system representing a utility VM.

WCOW Notes:

func (*UtilityVM) AddEndpointsToNS 

func (uvm *UtilityVM) AddEndpointsToNS(ctx context.Context, id string, endpoints []*hns.HNSEndpoint) error

AddEndpointsToNS adds all unique `endpoints` to the network namespace matching `id`. On failure does not roll back any previously successfully added endpoints.

If no network namespace matches `id` returns `ErrNetNSNotFound`.

func (*UtilityVM) AddNetNS 

func (uvm *UtilityVM) AddNetNS(ctx context.Context, id string) error

AddNetNS adds network namespace inside the guest.

If a namespace with `id` already exists returns `ErrNetNSAlreadyAttached`.

func (*UtilityVM) AddPipe 

func (uvm *UtilityVM) AddPipe(ctx context.Context, hostPath string) (*PipeMount, error)

AddPipe shares a named pipe into the UVM.

func (*UtilityVM) AddPlan9 

func (uvm *UtilityVM) AddPlan9(ctx context.Context, hostPath string, uvmPath string, readOnly bool, restrict bool, allowedNames []string) (*Plan9Share, error)

AddPlan9 adds a Plan9 share to a utility VM.

func (*UtilityVM) AddSCSI 

func (uvm *UtilityVM) AddSCSI(ctx context.Context, hostPath string, uvmPath string, readOnly bool, vmAccess VMAccessType) (*SCSIMount, error)

AddSCSI adds a SCSI disk to a utility VM at the next available location. This function should be called for a adding a scratch layer, a read-only layer as an alternative to VPMEM, or for other VHD mounts.

`hostPath` is required and must point to a vhd/vhdx path.

`uvmPath` is optional. If not provided, no guest request will be made

`readOnly` set to `true` if the vhd/vhdx should be attached read only.

`vmAccess` indicates what access to grant the vm for the hostpath

func (*UtilityVM) AddSCSIPhysicalDisk 

func (uvm *UtilityVM) AddSCSIPhysicalDisk(ctx context.Context, hostPath, uvmPath string, readOnly bool) (*SCSIMount, error)

AddSCSIPhysicalDisk attaches a physical disk from the host directly to the Utility VM at the next available location.

`hostPath` is required and `likely` start's with `\\.\PHYSICALDRIVE`.

`uvmPath` is optional if a guest mount is not requested.

`readOnly` set to `true` if the physical disk should be attached read only.

func (*UtilityVM) AddVPMEM 

func (uvm *UtilityVM) AddVPMEM(ctx context.Context, hostPath string) (_ string, err error)

AddVPMEM adds a VPMEM disk to a utility VM at the next available location and returns the UVM path where the layer was mounted.

func (*UtilityVM) AddVSMB 

func (uvm *UtilityVM) AddVSMB(ctx context.Context, hostPath string, guestRequest interface{}, options *hcsschema.VirtualSmbShareOptions) (*VSMBShare, error)

AddVSMB adds a VSMB share to a Windows utility VM. Each VSMB share is ref-counted and only added if it isn't already. This is used for read-only layers, mapped directories to a container, and for mapped pipes.

func (*UtilityVM) AssignDevice 

func (uvm *UtilityVM) AssignDevice(ctx context.Context, device hcsschema.VirtualPciDevice) (*VPCIDevice, error)

AssignDevice assigns a new vpci device to the uvm

func (*UtilityVM) Capabilities 

func (uvm *UtilityVM) Capabilities() (uint32, schema1.GuestDefinedCapabilities)

Capabilities returns the protocol version and the guest defined capabilities. This should only be used for testing.

func (*UtilityVM) Close 

func (uvm *UtilityVM) Close() (err error)

Close terminates and releases resources associated with the utility VM.

func (*UtilityVM) CombineLayersLCOW 

func (uvm *UtilityVM) CombineLayersLCOW(ctx context.Context, layerPaths []string, scratchPath, rootfsPath string) error

CombineLayersLCOW combines `layerPaths` and optionally `scratchPath` into an overlay filesystem at `rootfsPath`. If `scratchPath` is empty the overlay will be read only.

NOTE: `layerPaths`, `scrathPath`, and `rootfsPath` are paths from within the UVM.

func (*UtilityVM) CombineLayersWCOW 

func (uvm *UtilityVM) CombineLayersWCOW(ctx context.Context, layerPaths []hcsschema.Layer, containerRootPath string) error

CombineLayersWCOW combines `layerPaths` with `containerRootPath` into the container file system.

Note: `layerPaths` and `containerRootPath` are paths from within the UVM.

func (*UtilityVM) ContainerCounter 

func (uvm *UtilityVM) ContainerCounter() uint64

ContainerCounter is used for where we layout things for a container in a utility VM. For WCOW it'll be C:\c\N\. For LCOW it'll be /run/gcs/c/N/.

func (*UtilityVM) CreateContainer 

func (uvm *UtilityVM) CreateContainer(ctx context.Context, id string, settings interface{}) (cow.Container, error)

CreateContainer creates a container in the utility VM.

func (*UtilityVM) CreateProcess 

func (uvm *UtilityVM) CreateProcess(ctx context.Context, settings interface{}) (cow.Process, error)

CreateProcess creates a process in the utility VM.

func (*UtilityVM) DeleteContainerState 

func (uvm *UtilityVM) DeleteContainerState(ctx context.Context, cid string) error

func (*UtilityVM) DeleteContainerStateSupported 

func (uvm *UtilityVM) DeleteContainerStateSupported() bool

func (*UtilityVM) DumpStacks 

func (uvm *UtilityVM) DumpStacks(ctx context.Context) (string, error)

func (*UtilityVM) ExitError 

func (uvm *UtilityVM) ExitError() error

ExitError returns an error if the utility VM has terminated unexpectedly.

func (*UtilityVM) GetScsiUvmPath 

func (uvm *UtilityVM) GetScsiUvmPath(ctx context.Context, hostPath string) (string, error)

GetScsiUvmPath returns the guest mounted path of a SCSI drive.

If `hostPath` is not mounted returns `ErrNotAttached`.

func (*UtilityVM) GetVSMBUvmPath 

func (uvm *UtilityVM) GetVSMBUvmPath(ctx context.Context, hostPath string) (string, error)

GetVSMBUvmPath returns the guest path of a VSMB mount.

func (*UtilityVM) ID 

func (uvm *UtilityVM) ID() string

ID returns the ID of the VM's compute system.

func (*UtilityVM) IsOCI 

func (uvm *UtilityVM) IsOCI() bool

IsOCI returns false, indicating the parameters to CreateProcess should not include an OCI spec.

func (*UtilityVM) OS 

func (uvm *UtilityVM) OS() string

OS returns the operating system of the utility VM.

func (*UtilityVM) ProcessorCount 

func (uvm *UtilityVM) ProcessorCount() int32

ProcessorCount returns the number of processors actually assigned to the UVM.

func (*UtilityVM) RemoveCombinedLayers 

func (uvm *UtilityVM) RemoveCombinedLayers(ctx context.Context, rootfsPath string) error

RemoveCombinedLayers removes the previously combined layers at `rootfsPath`.

NOTE: `rootfsPath` is the path from within the UVM.

func (*UtilityVM) RemoveDevice 

func (uvm *UtilityVM) RemoveDevice(ctx context.Context, id string) error

RemoveDevice removes a vpci device from the uvm

func (*UtilityVM) RemoveEndpointsFromNS 

func (uvm *UtilityVM) RemoveEndpointsFromNS(ctx context.Context, id string, endpoints []*hns.HNSEndpoint) error

RemoveEndpointsFromNS removes all matching `endpoints` in the network namespace matching `id`. If no endpoint matching `endpoint.Id` is found in the network namespace this command silently succeeds.

If no network namespace matches `id` returns `ErrNetNSNotFound`.

func (*UtilityVM) RemoveNetNS 

func (uvm *UtilityVM) RemoveNetNS(ctx context.Context, id string) error

RemoveNetNS removes the namespace from the uvm and all remaining endpoints in the namespace.

If a namespace matching `id` is not found this command silently succeeds.

func (*UtilityVM) RemovePipe 

func (uvm *UtilityVM) RemovePipe(ctx context.Context, hostPath string) error

RemovePipe removes a shared named pipe from the UVM.

func (*UtilityVM) RemovePlan9 

func (uvm *UtilityVM) RemovePlan9(ctx context.Context, share *Plan9Share) error

RemovePlan9 removes a Plan9 share from a utility VM. Each Plan9 share is ref-counted and only actually removed when the ref-count drops to zero.

func (*UtilityVM) RemoveSCSI 

func (uvm *UtilityVM) RemoveSCSI(ctx context.Context, hostPath string) error

RemoveSCSI removes a SCSI disk from a utility VM.

func (*UtilityVM) RemoveVPMEM 

func (uvm *UtilityVM) RemoveVPMEM(ctx context.Context, hostPath string) (err error)

RemoveVPMEM removes a VPMEM disk from a Utility VM. If the `hostPath` is not attached returns `ErrNotAttached`.

func (*UtilityVM) RemoveVSMB 

func (uvm *UtilityVM) RemoveVSMB(ctx context.Context, hostPath string) error

RemoveVSMB removes a VSMB share from a utility VM. Each VSMB share is ref-counted and only actually removed when the ref-count drops to zero.

func (*UtilityVM) SignalProcessSupported 

func (uvm *UtilityVM) SignalProcessSupported() bool

SignalProcessSupported returns `true` if the guest supports the capability to signal a process.

This support was added RS5+ guests.

func (*UtilityVM) Start 

func (uvm *UtilityVM) Start(ctx context.Context) (err error)

Start synchronously starts the utility VM.

func (*UtilityVM) Stats 

func (uvm *UtilityVM) Stats(ctx context.Context) (*stats.VirtualMachineStatistics, error)

Stats returns various UVM statistics.

func (*UtilityVM) Terminate 

func (uvm *UtilityVM) Terminate(ctx context.Context) error

Terminate requests that the utility VM be terminated.

func (*UtilityVM) UVMMountCounter 

func (uvm *UtilityVM) UVMMountCounter() uint64

mountCounter is used for maintaining the number of mounts to the UVM. This helps in generating unique mount paths for every mount.

func (*UtilityVM) Wait 

func (uvm *UtilityVM) Wait() error

Wait waits synchronously for a utility VM to terminate.

type VMAccessType 

type VMAccessType int

VMAccessType is used to determine the various types of access we can grant for a given file. 

const (
	// `VMAccessTypeNoop` indicates no additional access should be given. Note
	// this should be used for layers and gpu vhd where we have given VM group
	// access outside of the shim (containerd for layers, package installation
	// for gpu vhd).
	VMAccessTypeNoop VMAccessType = iota
	// `VMAccessTypeGroup` indicates we should give access to a file for the VM group sid
	VMAccessTypeGroup
	// `VMAccessTypeIndividual` indicates we should give additional access to a file for
	// the running VM only
	VMAccessTypeIndividual
)

type VPCIDevice 

type VPCIDevice struct {
	ID string
	// contains filtered or unexported fields
}

VPCIDevice represents a vpci device. Holds its guid and a handle to the uvm it belongs to.

func (*VPCIDevice) Release 

func (vpci *VPCIDevice) Release(ctx context.Context) error

Release frees the resources of the corresponding vpci device

type VSMBShare 

type VSMBShare struct {
	HostPath string
	// contains filtered or unexported fields
}

VSMBShare contains the host path for a Vsmb Mount

func (*VSMBShare) Release 

func (vsmb *VSMBShare) Release(ctx context.Context) error

Release frees the resources of the corresponding vsmb Mount

Source Files

capabilities.go combine_layers.go constants.go counter.go create.go create_lcow.go create_wcow.go delete_container.go dumpstacks.go modify.go network.go pipes.go plan9.go resourcepaths.go scsi.go start.go stats.go types.go virtual_device.go vpmem.go vsmb.go wait.go

Version
v0.8.9
Published
Apr 28, 2020
Platform
js/wasm
Imports
47 packages
Last checked
1 minute ago –

Tools for package owners.