hcsshim

package module
v0.6.13 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2018 License: MIT Imports: 21 Imported by: 537

README

hcsshim

This package supports launching Windows Server containers from Go. It is primarily used in the Docker Engine project, but it can be freely used by other projects as well.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at secure@microsoft.com. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

Copyright (c) 2018 Microsoft Corp. All rights reserved.

Documentation

Index

Constants

View Source 
const (
	Add     RequestType  = "Add"
	Remove  RequestType  = "Remove"
	Network ResourceType = "Network"
)

RequestType const

View Source 
const (
	// Specific user-visible exit codes
	WaitErrExecFailed = 32767

	ERROR_GEN_FAILURE          = syscall.Errno(31)
	ERROR_SHUTDOWN_IN_PROGRESS = syscall.Errno(1115)
	WSAEINVAL                  = syscall.Errno(10022)

	// Timeout on wait calls
	TimeoutInfinite = 0xFFFFFFFF
)
View Source 
const (
	Allow ActionType = "Allow"
	Block ActionType = "Block"

	In  DirectionType = "In"
	Out DirectionType = "Out"

	Host   RuleType = "Host"
	Switch RuleType = "Switch"
)

Variables

View Source 
var (
	// ErrComputeSystemDoesNotExist is an error encountered when the container being operated on no longer exists
	ErrComputeSystemDoesNotExist = syscall.Errno(0xc037010e)

	// ErrElementNotFound is an error encountered when the object being referenced does not exist
	ErrElementNotFound = syscall.Errno(0x490)

	// ErrElementNotFound is an error encountered when the object being referenced does not exist
	ErrNotSupported = syscall.Errno(0x32)

	// ErrInvalidData is an error encountered when the request being sent to hcs is invalid/unsupported
	// decimal -2147024883 / hex 0x8007000d
	ErrInvalidData = syscall.Errno(0xd)

	// ErrHandleClose is an error encountered when the handle generating the notification being waited on has been closed
	ErrHandleClose = errors.New("hcsshim: the handle generating this notification has been closed")

	// ErrAlreadyClosed is an error encountered when using a handle that has been closed by the Close method
	ErrAlreadyClosed = errors.New("hcsshim: the handle has already been closed")

	// ErrInvalidNotificationType is an error encountered when an invalid notification type is used
	ErrInvalidNotificationType = errors.New("hcsshim: invalid notification type")

	// ErrInvalidProcessState is an error encountered when the process is not in a valid state for the requested operation
	ErrInvalidProcessState = errors.New("the process is in an invalid state for the attempted operation")

	// ErrTimeout is an error encountered when waiting on a notification times out
	ErrTimeout = errors.New("hcsshim: timeout waiting for notification")

	// ErrUnexpectedContainerExit is the error encountered when a container exits while waiting for
	// a different expected notification
	ErrUnexpectedContainerExit = errors.New("unexpected container exit")

	// ErrUnexpectedProcessAbort is the error encountered when communication with the compute service
	// is lost while waiting for a notification
	ErrUnexpectedProcessAbort = errors.New("lost communication with compute service")

	// ErrUnexpectedValue is an error encountered when hcs returns an invalid value
	ErrUnexpectedValue = errors.New("unexpected value returned from hcs")

	// ErrVmcomputeAlreadyStopped is an error encountered when a shutdown or terminate request is made on a stopped container
	ErrVmcomputeAlreadyStopped = syscall.Errno(0xc0370110)

	// ErrVmcomputeOperationPending is an error encountered when the operation is being completed asynchronously
	ErrVmcomputeOperationPending = syscall.Errno(0xC0370103)

	// ErrVmcomputeOperationInvalidState is an error encountered when the compute system is not in a valid state for the requested operation
	ErrVmcomputeOperationInvalidState = syscall.Errno(0xc0370105)

	// ErrProcNotFound is an error encountered when the the process cannot be found
	ErrProcNotFound = syscall.Errno(0x7f)

	// ErrVmcomputeOperationAccessIsDenied is an error which can be encountered when enumerating compute systems in RS1/RS2
	// builds when the underlying silo might be in the process of terminating. HCS was fixed in RS3.
	ErrVmcomputeOperationAccessIsDenied = syscall.Errno(0x5)

	// ErrVmcomputeInvalidJSON is an error encountered when the compute system does not support/understand the messages sent by management
	ErrVmcomputeInvalidJSON = syscall.Errno(0xc037010d)

	// ErrVmcomputeUnknownMessage is an error encountered guest compute system doesn't support the message
	ErrVmcomputeUnknownMessage = syscall.Errno(0xc037010b)

	// ErrNotSupported is an error encountered when hcs doesn't support the request
	ErrPlatformNotSupported = errors.New("unsupported platform request")
)

Functions

func ActivateLayer 

func ActivateLayer(info DriverInfo, id string) error

ActivateLayer will find the layer with the given id and mount it's filesystem. For a read/write layer, the mounted filesystem will appear as a volume on the host, while a read-only layer is generally expected to be a no-op. An activated layer must later be deactivated via DeactivateLayer.

func CreateLayer 

func CreateLayer(info DriverInfo, id, parent string) error

CreateLayer creates a new, empty, read-only layer on the filesystem based on the parent layer provided.

func CreateSandboxLayer 

func CreateSandboxLayer(info DriverInfo, layerId, parentId string, parentLayerPaths []string) error

CreateSandboxLayer creates and populates new read-write layer for use by a container. This requires both the id of the direct parent layer, as well as the full list of paths to all parent layers up to the base (and including the direct parent whose id was provided).

func DeactivateLayer 

func DeactivateLayer(info DriverInfo, id string) error

DeactivateLayer will dismount a layer that was mounted via ActivateLayer.

func DestroyLayer 

func DestroyLayer(info DriverInfo, id string) error

DestroyLayer will remove the on-disk files representing the layer with the given id, including that layer's containing folder, if any.

func ExpandSandboxSize added in v0.3.2 

func ExpandSandboxSize(info DriverInfo, layerId string, size uint64) error

ExpandSandboxSize expands the size of a layer to at least size bytes.

func ExportLayer 

func ExportLayer(info DriverInfo, layerId string, exportFolderPath string, parentLayerPaths []string) error

ExportLayer will create a folder at exportFolderPath and fill that folder with the transport format version of the layer identified by layerId. This transport format includes any metadata required for later importing the layer (using ImportLayer), and requires the full list of parent layer paths in order to perform the export.

func GetLayerMountPath 

func GetLayerMountPath(info DriverInfo, id string) (string, error)

GetLayerMountPath will look for a mounted layer with the given id and return the path at which that layer can be accessed. This path may be a volume path if the layer is a mounted read-write layer, otherwise it is expected to be the folder path at which the layer is stored.

func GetSharedBaseImages 

func GetSharedBaseImages() (imageData string, err error)

GetSharedBaseImages will enumerate the images stored in the common central image store and return descriptive info about those images for the purpose of registering them with the graphdriver, graph, and tagstore.

func HotAttachEndpoint added in v0.5.15 

func HotAttachEndpoint(containerID string, endpointID string) error

HotAttachEndpoint makes a HCS Call to attach the endpoint to the container

func HotDetachEndpoint added in v0.5.15 

func HotDetachEndpoint(containerID string, endpointID string) error

HotDetachEndpoint makes a HCS Call to detach the endpoint from the container

func ImportLayer 

func ImportLayer(info DriverInfo, layerID string, importFolderPath string, parentLayerPaths []string) error

ImportLayer will take the contents of the folder at importFolderPath and import that into a layer with the id layerId. Note that in order to correctly populate the layer and interperet the transport format, all parent layers must already be present on the system at the paths provided in parentLayerPaths.

func IsAlreadyClosed added in v0.5.3 

func IsAlreadyClosed(err error) bool

IsAlreadyClosed checks if an error is caused by the Container or Process having been already closed by a call to the Close() method.

func IsAlreadyStopped added in v0.4.0 

func IsAlreadyStopped(err error) bool

IsAlreadyStopped returns a boolean indicating whether the error is caused by a Container or Process being already stopped. Note: Currently, ErrElementNotFound can mean that a Process has either already exited, or does not exist. Both IsAlreadyStopped and IsNotExist will currently return true when the error is ErrElementNotFound or ErrProcNotFound.

func IsNotExist added in v0.4.0 

func IsNotExist(err error) bool

IsNotExist checks if an error is caused by the Container or Process not existing. Note: Currently, ErrElementNotFound can mean that a Process has either already exited, or does not exist. Both IsAlreadyStopped and IsNotExist will currently return true when the error is ErrElementNotFound or ErrProcNotFound.

func IsNotSupported added in v0.5.15 

func IsNotSupported(err error) bool

IsNotSupported returns a boolean indicating whether the error is caused by unsupported platform requests Note: Currently Unsupported platform requests can be mean either ErrVmcomputeInvalidJSON, ErrInvalidData, ErrNotSupported or ErrVmcomputeUnknownMessage is thrown from the Platform

func IsPending added in v0.4.0 

func IsPending(err error) bool

IsPending returns a boolean indicating whether the error is that the requested operation is being completed in the background.

func IsTP4 

func IsTP4() bool

IsTP4 returns whether the currently running Windows build is at least TP4.

func IsTimeout added in v0.4.0 

func IsTimeout(err error) bool

IsTimeout returns a boolean indicating whether the error is caused by a timeout waiting for the operation to complete.

func LayerExists 

func LayerExists(info DriverInfo, id string) (bool, error)

LayerExists will return true if a layer with the given id exists and is known to the system.

func PrepareLayer 

func PrepareLayer(info DriverInfo, layerId string, parentLayerPaths []string) error

PrepareLayer finds a mounted read-write layer matching layerId and enables the the filesystem filter for use on that layer. This requires the paths to all parent layers, and is necessary in order to view or interact with the layer as an actual filesystem (reading and writing files, creating directories, etc). Disabling the filter must be done via UnprepareLayer.

func ProcessBaseLayer 

func ProcessBaseLayer(path string) error

ProcessBaseLayer post-processes a base layer that has had its files extracted. The files should have been extracted to <path>\Files.

func ProcessUtilityVMImage 

func ProcessUtilityVMImage(path string) error

ProcessUtilityVMImage post-processes a utility VM image that has had its files extracted. The files should have been extracted to <path>\Files.

func SetCurrentThreadCompartmentId added in v0.4.3 

func SetCurrentThreadCompartmentId(compartmentId uint32) (hr error)

func UnprepareLayer 

func UnprepareLayer(info DriverInfo, layerId string) error

UnprepareLayer disables the filesystem filter for the read-write layer with the given id.

Types

type ACLPolicy added in v0.5.27 

type ACLPolicy struct {
	Type            PolicyType `json:"Type"`
	Protocol        uint16
	InternalPort    uint16
	Action          ActionType
	Direction       DirectionType
	LocalAddresses  string
	RemoteAddresses string
	LocalPort       uint16
	RemotePort      uint16
	RuleType        RuleType `json:"RuleType,omitempty"`
	Priority        uint16
	ServiceName     string
}

type ActionType added in v0.5.27 

type ActionType string

type AssignedDevice added in v0.6.12 

type AssignedDevice struct {
	//  InterfaceClassGUID of the device to assign to container.
	InterfaceClassGUID string `json:"InterfaceClassGuid,omitempty"`
}

AssignedDevice represents a device that has been directly assigned to a container

NOTE: Support added in RS5

type ComputeSystemQuery added in v0.5.3 

type ComputeSystemQuery struct {
	IDs    []string `json:"Ids,omitempty"`
	Types  []string `json:",omitempty"`
	Names  []string `json:",omitempty"`
	Owners []string `json:",omitempty"`
}

type Container added in v0.3.0 

type Container interface {
	// Start synchronously starts the container.
	Start() error

	// Shutdown requests a container shutdown, but it may not actually be shutdown until Wait() succeeds.
	Shutdown() error

	// Terminate requests a container terminate, but it may not actually be terminated until Wait() succeeds.
	Terminate() error

	// Waits synchronously waits for the container to shutdown or terminate.
	Wait() error

	// WaitTimeout synchronously waits for the container to terminate or the duration to elapse. It
	// returns false if timeout occurs.
	WaitTimeout(time.Duration) error

	// Pause pauses the execution of a container.
	Pause() error

	// Resume resumes the execution of a container.
	Resume() error

	// HasPendingUpdates returns true if the container has updates pending to install.
	HasPendingUpdates() (bool, error)

	// Statistics returns statistics for a container.
	Statistics() (Statistics, error)

	// ProcessList returns details for the processes in a container.
	ProcessList() ([]ProcessListItem, error)

	// MappedVirtualDisks returns virtual disks mapped to a utility VM, indexed by controller
	MappedVirtualDisks() (map[int]MappedVirtualDiskController, error)

	// CreateProcess launches a new process within the container.
	CreateProcess(c *ProcessConfig) (Process, error)

	// OpenProcess gets an interface to an existing process within the container.
	OpenProcess(pid int) (Process, error)

	// Close cleans up any state associated with the container but does not terminate or wait for it.
	Close() error

	// Modify the System
	Modify(config *ResourceModificationRequestResponse) error
}

Container represents a created (but not necessarily running) container.

func CreateContainer added in v0.3.0 

func CreateContainer(id string, c *ContainerConfig) (Container, error)

CreateContainer creates a new container with the given configuration but does not start it.

func CreateContainerWithJSON added in v0.5.13 

func CreateContainerWithJSON(id string, c *ContainerConfig, additionalJSON string) (Container, error)

CreateContainerWithJSON creates a new container with the given configuration but does not start it. It is identical to CreateContainer except that optional additional JSON can be merged before passing to HCS.

func OpenContainer added in v0.3.0 

func OpenContainer(id string) (Container, error)

OpenContainer opens an existing container by ID.

type ContainerConfig added in v0.3.0 

type ContainerConfig struct {
	SystemType                  string              // HCS requires this to be hard-coded to "Container"
	Name                        string              // Name of the container. We use the docker ID.
	Owner                       string              `json:",omitempty"` // The management platform that created this container
	VolumePath                  string              `json:",omitempty"` // Windows volume path for scratch space. Used by Windows Server Containers only. Format \\?\\Volume{GUID}
	IgnoreFlushesDuringBoot     bool                `json:",omitempty"` // Optimization hint for container startup in Windows
	LayerFolderPath             string              `json:",omitempty"` // Where the layer folders are located. Used by Windows Server Containers only. Format  %root%\windowsfilter\containerID
	Layers                      []Layer             // List of storage layers. Required for Windows Server and Hyper-V Containers. Format ID=GUID;Path=%root%\windowsfilter\layerID
	Credentials                 string              `json:",omitempty"` // Credentials information
	ProcessorCount              uint32              `json:",omitempty"` // Number of processors to assign to the container.
	ProcessorWeight             uint64              `json:",omitempty"` // CPU shares (relative weight to other containers with cpu shares). Range is from 1 to 10000. A value of 0 results in default shares.
	ProcessorMaximum            int64               `json:",omitempty"` // Specifies the portion of processor cycles that this container can use as a percentage times 100. Range is from 1 to 10000. A value of 0 results in no limit.
	StorageIOPSMaximum          uint64              `json:",omitempty"` // Maximum Storage IOPS
	StorageBandwidthMaximum     uint64              `json:",omitempty"` // Maximum Storage Bandwidth in bytes per second
	StorageSandboxSize          uint64              `json:",omitempty"` // Size in bytes that the container system drive should be expanded to if smaller
	MemoryMaximumInMB           int64               `json:",omitempty"` // Maximum memory available to the container in Megabytes
	HostName                    string              `json:",omitempty"` // Hostname
	MappedDirectories           []MappedDir         `json:",omitempty"` // List of mapped directories (volumes/mounts)
	MappedPipes                 []MappedPipe        `json:",omitempty"` // List of mapped Windows named pipes
	HvPartition                 bool                // True if it a Hyper-V Container
	NetworkSharedContainerName  string              `json:",omitempty"` // Name (ID) of the container that we will share the network stack with.
	EndpointList                []string            `json:",omitempty"` // List of networking endpoints to be attached to container
	HvRuntime                   *HvRuntime          `json:",omitempty"` // Hyper-V container settings. Used by Hyper-V containers only. Format ImagePath=%root%\BaseLayerID\UtilityVM
	Servicing                   bool                `json:",omitempty"` // True if this container is for servicing
	AllowUnqualifiedDNSQuery    bool                `json:",omitempty"` // True to allow unqualified DNS name resolution
	DNSSearchList               string              `json:",omitempty"` // Comma seperated list of DNS suffixes to use for name resolution
	ContainerType               string              `json:",omitempty"` // "Linux" for Linux containers on Windows. Omitted otherwise.
	TerminateOnLastHandleClosed bool                `json:",omitempty"` // Should HCS terminate the container once all handles have been closed
	MappedVirtualDisks          []MappedVirtualDisk `json:",omitempty"` // Array of virtual disks to mount at start
	AssignedDevices             []AssignedDevice    `json:",omitempty"` // Array of devices to assign. NOTE: Support added in RS5
	RegistryChanges             *RegistryChanges    `json:",omitempty"` // Registry changes to be applied to the container
}

ContainerConfig is used as both the input of CreateContainer and to convert the parameters to JSON for passing onto the HCS

type ContainerError added in v0.3.0 

type ContainerError struct {
	Container *container
	Operation string
	ExtraInfo string
	Err       error
}

ContainerError is an error encountered in HCS during an operation on a Container object

func (*ContainerError) Error added in v0.3.0 

func (e *ContainerError) Error() string

type ContainerProperties added in v0.5.3 

type ContainerProperties struct {
	ID                           string `json:"Id"`
	Name                         string
	SystemType                   string
	Owner                        string
	SiloGUID                     string                              `json:"SiloGuid,omitempty"`
	RuntimeID                    string                              `json:"RuntimeId,omitempty"`
	IsRuntimeTemplate            bool                                `json:",omitempty"`
	RuntimeImagePath             string                              `json:",omitempty"`
	Stopped                      bool                                `json:",omitempty"`
	ExitType                     string                              `json:",omitempty"`
	AreUpdatesPending            bool                                `json:",omitempty"`
	ObRoot                       string                              `json:",omitempty"`
	Statistics                   Statistics                          `json:",omitempty"`
	ProcessList                  []ProcessListItem                   `json:",omitempty"`
	MappedVirtualDiskControllers map[int]MappedVirtualDiskController `json:",omitempty"`
}

ContainerProperties holds the properties for a container and the processes running in that container

func GetContainers added in v0.5.3 

func GetContainers(q ComputeSystemQuery) ([]ContainerProperties, error)

GetContainers gets a list of the containers on the system that match the query

type DirectionType added in v0.5.27 

type DirectionType string

type DriverInfo 

type DriverInfo struct {
	Flavour int
	HomeDir string
}
To pass into syscall, we need a struct matching the following:

enum GraphDriverType 

{
    DiffDriver,
    FilterDriver
};

struct DriverInfo {
    GraphDriverType Flavour;
    LPCWSTR HomeDir;
};

type ELBPolicy added in v0.5.27 

type ELBPolicy struct {
	LBPolicy
	SourceVIP string   `json:"SourceVIP,omitempty"`
	VIPs      []string `json:"VIPs,omitempty"`
	ILB       bool     `json:"ILB,omitempty"`
}

ELBPolicy is a structure defining schema for ELB LoadBalancing based Policy

type EndpointAttachDetachRequest added in v0.6.2 

type EndpointAttachDetachRequest struct {
	ContainerID    string     `json:"ContainerId,omitempty"`
	SystemType     SystemType `json:"SystemType"`
	CompartmentID  uint16     `json:"CompartmentId,omitempty"`
	VirtualNICName string     `json:"VirtualNicName,omitempty"`
}

EndpointAttachDetachRequest is the structure used to send request to the container to modify the system Supported resource types are Network and Request Types are Add/Remove

type EndpointNotFoundError added in v0.6.7 

type EndpointNotFoundError struct {
	EndpointName string
}

func (EndpointNotFoundError) Error added in v0.6.7 

func (e EndpointNotFoundError) Error() string

type EndpointResquestResponse added in v0.6.2 

type EndpointResquestResponse struct {
	Success bool
	Error   string
}

EndpointResquestResponse is object to get the endpoint request response

type FilterLayerReader 

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

FilterLayerReader provides an interface for extracting the contents of an on-disk layer.

func (*FilterLayerReader) Close 

func (r *FilterLayerReader) Close() (err error)

Close frees resources associated with the layer reader. It will return an error if there was an error while reading the layer or of the layer was not completely read.

func (*FilterLayerReader) Next 

func (r *FilterLayerReader) Next() (string, int64, *winio.FileBasicInfo, error)

Next reads the next available file from a layer, ensuring that parent directories are always read before child files and directories.

Next returns the file's relative path, size, and basic file metadata. Read() should be used to extract a Win32 backup stream with the remainder of the metadata and the data.

func (*FilterLayerReader) Read 

func (r *FilterLayerReader) Read(b []byte) (int, error)

Read reads from the current file's Win32 backup stream.

type FilterLayerWriter 

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

FilterLayerWriter provides an interface to write the contents of a layer to the file system.

func (*FilterLayerWriter) Add 

func (w *FilterLayerWriter) Add(name string, fileInfo *winio.FileBasicInfo) error

Add adds a file or directory to the layer. The file's parent directory must have already been added.

name contains the file's relative path. fileInfo contains file times and file attributes; the rest of the file metadata and the file data must be written as a Win32 backup stream to the Write() method. winio.BackupStreamWriter can be used to facilitate this. 

func (w *FilterLayerWriter) AddLink(name string, target string) error

AddLink adds a hard link to the layer. The target of the link must have already been added.

func (*FilterLayerWriter) Close 

func (w *FilterLayerWriter) Close() (err error)

Close completes the layer write operation. The error must be checked to ensure that the operation was successful.

func (*FilterLayerWriter) Remove 

func (w *FilterLayerWriter) Remove(name string) error

Remove removes a file from the layer. The file must have been present in the parent layer.

name contains the file's relative path.

func (*FilterLayerWriter) Write 

func (w *FilterLayerWriter) Write(b []byte) (int, error)

Write writes more backup stream data to the current file.

type GUID 

type GUID [16]byte

func NameToGuid 

func NameToGuid(name string) (id GUID, err error)

NameToGuid converts the given string into a GUID using the algorithm in the Host Compute Service, ensuring GUIDs generated with the same string are common across all clients.

func NewGUID 

func NewGUID(source string) *GUID

func (*GUID) ToString 

func (g *GUID) ToString() string

type HNSEndpoint 

type HNSEndpoint struct {
	Id                 string            `json:"ID,omitempty"`
	Name               string            `json:",omitempty"`
	VirtualNetwork     string            `json:",omitempty"`
	VirtualNetworkName string            `json:",omitempty"`
	Policies           []json.RawMessage `json:",omitempty"`
	MacAddress         string            `json:",omitempty"`
	IPAddress          net.IP            `json:",omitempty"`
	DNSSuffix          string            `json:",omitempty"`
	DNSServerList      string            `json:",omitempty"`
	GatewayAddress     string            `json:",omitempty"`
	EnableInternalDNS  bool              `json:",omitempty"`
	DisableICC         bool              `json:",omitempty"`
	PrefixLength       uint8             `json:",omitempty"`
	IsRemoteEndpoint   bool              `json:",omitempty"`
}

HNSEndpoint represents a network endpoint in HNS

func GetHNSEndpointByID added in v0.5.15 

func GetHNSEndpointByID(endpointID string) (*HNSEndpoint, error)

GetHNSEndpointByID get the Endpoint by ID

func GetHNSEndpointByName added in v0.5.15 

func GetHNSEndpointByName(endpointName string) (*HNSEndpoint, error)

GetHNSEndpointByName gets the endpoint filtered by Name

func HNSEndpointRequest 

func HNSEndpointRequest(method, path, request string) (*HNSEndpoint, error)

HNSEndpointRequest makes a HNS call to modify/query a network endpoint

func HNSListEndpointRequest added in v0.5.15 

func HNSListEndpointRequest() ([]HNSEndpoint, error)

HNSListEndpointRequest makes a HNS call to query the list of available endpoints

func (*HNSEndpoint) ApplyACLPolicy added in v0.5.27 

func (endpoint *HNSEndpoint) ApplyACLPolicy(policies ...*ACLPolicy) error

ApplyACLPolicy applies a set of ACL Policies on the Endpoint

func (*HNSEndpoint) ContainerAttach added in v0.6.2 

func (endpoint *HNSEndpoint) ContainerAttach(containerID string, compartmentID uint16) error

ContainerAttach attaches an endpoint to container

func (*HNSEndpoint) ContainerDetach added in v0.6.2 

func (endpoint *HNSEndpoint) ContainerDetach(containerID string) error

ContainerDetach detaches an endpoint from container

func (*HNSEndpoint) ContainerHotAttach added in v0.6.2 

func (endpoint *HNSEndpoint) ContainerHotAttach(containerID string) error

ContainerHotAttach attaches an endpoint to a running container

func (*HNSEndpoint) ContainerHotDetach added in v0.6.2 

func (endpoint *HNSEndpoint) ContainerHotDetach(containerID string) error

ContainerHotDetach detaches an endpoint from a running container

func (*HNSEndpoint) Create added in v0.5.15 

func (endpoint *HNSEndpoint) Create() (*HNSEndpoint, error)

Create Endpoint by sending EndpointRequest to HNS. TODO: Create a separate HNS interface to place all these methods

func (*HNSEndpoint) Delete added in v0.5.15 

func (endpoint *HNSEndpoint) Delete() (*HNSEndpoint, error)

Delete Endpoint by sending EndpointRequest to HNS

func (*HNSEndpoint) HostAttach added in v0.6.2 

func (endpoint *HNSEndpoint) HostAttach(compartmentID uint16) error

HostAttach attaches a nic on the host

func (*HNSEndpoint) HostDetach added in v0.6.2 

func (endpoint *HNSEndpoint) HostDetach() error

HostDetach detaches a nic on the host

func (*HNSEndpoint) Update added in v0.5.27 

func (endpoint *HNSEndpoint) Update() (*HNSEndpoint, error)

Update Endpoint

func (*HNSEndpoint) VirtualMachineNICAttach added in v0.6.2 

func (endpoint *HNSEndpoint) VirtualMachineNICAttach(virtualMachineNICName string) error

VirtualMachineNICAttach attaches a endpoint to a virtual machine

func (*HNSEndpoint) VirtualMachineNICDetach added in v0.6.2 

func (endpoint *HNSEndpoint) VirtualMachineNICDetach() error

VirtualMachineNICDetach detaches a endpoint from a virtual machine

type HNSNetwork 

type HNSNetwork struct {
	Id                   string            `json:"ID,omitempty"`
	Name                 string            `json:",omitempty"`
	Type                 string            `json:",omitempty"`
	NetworkAdapterName   string            `json:",omitempty"`
	SourceMac            string            `json:",omitempty"`
	Policies             []json.RawMessage `json:",omitempty"`
	MacPools             []MacPool         `json:",omitempty"`
	Subnets              []Subnet          `json:",omitempty"`
	DNSSuffix            string            `json:",omitempty"`
	DNSServerList        string            `json:",omitempty"`
	DNSServerCompartment uint32            `json:",omitempty"`
	ManagementIP         string            `json:",omitempty"`
	AutomaticDNS         bool              `json:",omitempty"`
}

HNSNetwork represents a network in HNS

func GetHNSNetworkByID added in v0.5.15 

func GetHNSNetworkByID(networkID string) (*HNSNetwork, error)

GetHNSNetworkByID

func GetHNSNetworkByName added in v0.5.15 

func GetHNSNetworkByName(networkName string) (*HNSNetwork, error)

GetHNSNetworkName filtered by Name

func HNSListNetworkRequest 

func HNSListNetworkRequest(method, path, request string) ([]HNSNetwork, error)

HNSListNetworkRequest makes a HNS call to query the list of available networks

func HNSNetworkRequest 

func HNSNetworkRequest(method, path, request string) (*HNSNetwork, error)

HNSNetworkRequest makes a call into HNS to update/query a single network

func (*HNSNetwork) Create added in v0.5.27 

func (network *HNSNetwork) Create() (*HNSNetwork, error)

Create Network by sending NetworkRequest to HNS.

func (*HNSNetwork) CreateEndpoint added in v0.5.27 

func (network *HNSNetwork) CreateEndpoint(endpoint *HNSEndpoint) (*HNSEndpoint, error)

func (*HNSNetwork) CreateRemoteEndpoint added in v0.5.27 

func (network *HNSNetwork) CreateRemoteEndpoint(endpoint *HNSEndpoint) (*HNSEndpoint, error)

func (*HNSNetwork) Delete added in v0.5.27 

func (network *HNSNetwork) Delete() (*HNSNetwork, error)

Delete Network by sending NetworkRequest to HNS

func (*HNSNetwork) NewEndpoint added in v0.5.27 

func (network *HNSNetwork) NewEndpoint(ipAddress net.IP, macAddress net.HardwareAddr) *HNSEndpoint

Creates an endpoint on the Network.

type HcsError 

type HcsError struct {
	Err error
	// contains filtered or unexported fields
}

func (*HcsError) Error 

func (e *HcsError) Error() string

type HvRuntime added in v0.3.0 

type HvRuntime struct {
	ImagePath           string `json:",omitempty"`
	SkipTemplate        bool   `json:",omitempty"`
	LinuxInitrdFile     string `json:",omitempty"` // File under ImagePath on host containing an initrd image for starting a Linux utility VM
	LinuxKernelFile     string `json:",omitempty"` // File under ImagePath on host containing a kernel for starting a Linux utility VM
	LinuxBootParameters string `json:",omitempty"` // Additional boot parameters for starting a Linux Utility VM in initrd mode
	BootSource          string `json:",omitempty"` // "Vhd" for Linux Utility VM booting from VHD
	WritableBootSource  bool   `json:",omitempty"` // Linux Utility VM booting from VHD
}

type IsolationPolicy added in v0.5.27 

type IsolationPolicy struct {
	Type               PolicyType `json:"Type"`
	VLAN               uint
	VSID               uint
	InDefaultIsolation bool
}

type LBPolicy added in v0.5.27 

type LBPolicy struct {
	Policy
	Protocol     uint16 `json:"Protocol,omitempty"`
	InternalPort uint16
	ExternalPort uint16
}

LBPolicy is a structure defining schema for LoadBalancing based Policy

type Layer added in v0.3.0 

type Layer struct {
	ID   string
	Path string
}

type LayerReader 

type LayerReader interface {
	Next() (string, int64, *winio.FileBasicInfo, error)
	Read(b []byte) (int, error)
	Close() error
}

func NewLayerReader 

func NewLayerReader(info DriverInfo, layerID string, parentLayerPaths []string) (LayerReader, error)

NewLayerReader returns a new layer reader for reading the contents of an on-disk layer. The caller must have taken the SeBackupPrivilege privilege to call this and any methods on the resulting LayerReader.

type LayerWriter 

type LayerWriter interface {
	// Add adds a file to the layer with given metadata.
	Add(name string, fileInfo *winio.FileBasicInfo) error
	// AddLink adds a hard link to the layer. The target must already have been added.
	AddLink(name string, target string) error
	// Remove removes a file that was present in a parent layer from the layer.
	Remove(name string) error
	// Write writes data to the current file. The data must be in the format of a Win32
	// backup stream.
	Write(b []byte) (int, error)
	// Close finishes the layer writing process and releases any resources.
	Close() error
}

LayerWriter is an interface that supports writing a new container image layer.

func NewLayerWriter 

func NewLayerWriter(info DriverInfo, layerID string, parentLayerPaths []string) (LayerWriter, error)

NewLayerWriter returns a new layer writer for creating a layer on disk. The caller must have taken the SeBackupPrivilege and SeRestorePrivilege privileges to call this and any methods on the resulting LayerWriter.

type MacPool 

type MacPool struct {
	StartMacAddress string `json:",omitempty"`
	EndMacAddress   string `json:",omitempty"`
}

MacPool is assoicated with a network and represents a list of macaddresses available to the network

type MappedDir added in v0.3.0 

type MappedDir struct {
	HostPath          string
	ContainerPath     string
	ReadOnly          bool
	BandwidthMaximum  uint64
	IOPSMaximum       uint64
	CreateInUtilityVM bool
	// LinuxMetadata - Support added in 1803/RS4+.
	LinuxMetadata bool `json:",omitempty"`
}

type MappedPipe added in v0.5.26 

type MappedPipe struct {
	HostPath          string
	ContainerPipeName string
}

type MappedVirtualDisk added in v0.5.21 

type MappedVirtualDisk struct {
	HostPath          string `json:",omitempty"` // Path to VHD on the host
	ContainerPath     string // Platform-specific mount point path in the container
	CreateInUtilityVM bool   `json:",omitempty"`
	ReadOnly          bool   `json:",omitempty"`
	Cache             string `json:",omitempty"` // "" (Unspecified); "Disabled"; "Enabled"; "Private"; "PrivateAllowSharing"
	AttachOnly        bool   `json:",omitempty:`
}

type MappedVirtualDiskController added in v0.5.28 

type MappedVirtualDiskController struct {
	MappedVirtualDisks map[int]MappedVirtualDisk `json:",omitempty"`
}

MappedVirtualDiskController is the structure of an item returned by a MappedVirtualDiskList call on a container

type MemoryStats added in v0.4.0 

type MemoryStats struct {
	UsageCommitBytes            uint64 `json:"MemoryUsageCommitBytes,omitempty"`
	UsageCommitPeakBytes        uint64 `json:"MemoryUsageCommitPeakBytes,omitempty"`
	UsagePrivateWorkingSetBytes uint64 `json:"MemoryUsagePrivateWorkingSetBytes,omitempty"`
}

MemoryStats holds the memory statistics for a container

type NatPolicy 

type NatPolicy struct {
	Type         PolicyType `json:"Type"`
	Protocol     string
	InternalPort uint16
	ExternalPort uint16
}

type NetworkNotFoundError added in v0.6.7 

type NetworkNotFoundError struct {
	NetworkName string
}

func (NetworkNotFoundError) Error added in v0.6.7 

func (e NetworkNotFoundError) Error() string

type NetworkStats added in v0.4.0 

type NetworkStats struct {
	BytesReceived          uint64 `json:",omitempty"`
	BytesSent              uint64 `json:",omitempty"`
	PacketsReceived        uint64 `json:",omitempty"`
	PacketsSent            uint64 `json:",omitempty"`
	DroppedPacketsIncoming uint64 `json:",omitempty"`
	DroppedPacketsOutgoing uint64 `json:",omitempty"`
	EndpointId             string `json:",omitempty"`
	InstanceId             string `json:",omitempty"`
}

NetworkStats holds the network statistics for a container

type OutboundNatPolicy added in v0.5.27 

type OutboundNatPolicy struct {
	Policy
	VIP        string   `json:"VIP,omitempty"`
	Exceptions []string `json:"ExceptionList,omitempty"`
}

type PaPolicy added in v0.5.2 

type PaPolicy struct {
	Type PolicyType `json:"Type"`
	PA   string     `json:"PA"`
}

type Policy added in v0.5.27 

type Policy struct {
	Type PolicyType `json:"Type"`
}

type PolicyList added in v0.5.27 

type PolicyList struct {
	ID                 string            `json:"ID,omitempty"`
	EndpointReferences []string          `json:"References,omitempty"`
	Policies           []json.RawMessage `json:"Policies,omitempty"`
}

PolicyList is a structure defining schema for Policy list request

func AddLoadBalancer added in v0.5.27 

func AddLoadBalancer(endpoints []HNSEndpoint, isILB bool, sourceVIP, vip string, protocol uint16, internalPort uint16, externalPort uint16) (*PolicyList, error)

AddLoadBalancer policy list for the specified endpoints

func AddRoute added in v0.5.27 

func AddRoute(endpoints []HNSEndpoint, destinationPrefix string, nextHop string, encapEnabled bool) (*PolicyList, error)

AddRoute adds route policy list for the specified endpoints

func GetPolicyListByID added in v0.6.2 

func GetPolicyListByID(policyListID string) (*PolicyList, error)

GetPolicyListByID get the policy list by ID

func HNSListPolicyListRequest added in v0.5.27 

func HNSListPolicyListRequest() ([]PolicyList, error)

HNSListPolicyListRequest gets all the policy list

func HNSPolicyListRequest added in v0.5.27 

func HNSPolicyListRequest(method, path, request string) (*PolicyList, error)

HNSPolicyListRequest makes a call into HNS to update/query a single network

func PolicyListRequest added in v0.5.27 

func PolicyListRequest(method, path, request string) (*PolicyList, error)

PolicyListRequest makes a HNS call to modify/query a network policy list

func (*PolicyList) AddEndpoint added in v0.5.27 

func (policylist *PolicyList) AddEndpoint(endpoint *HNSEndpoint) (*PolicyList, error)

AddEndpoint add an endpoint to a Policy List

func (*PolicyList) Create added in v0.5.27 

func (policylist *PolicyList) Create() (*PolicyList, error)

Create PolicyList by sending PolicyListRequest to HNS.

func (*PolicyList) Delete added in v0.5.27 

func (policylist *PolicyList) Delete() (*PolicyList, error)

Delete deletes PolicyList

func (*PolicyList) RemoveEndpoint added in v0.5.27 

func (policylist *PolicyList) RemoveEndpoint(endpoint *HNSEndpoint) (*PolicyList, error)

RemoveEndpoint removes an endpoint from the Policy List

type PolicyType added in v0.5.27 

type PolicyType string

Type of Request Support in ModifySystem 

const (
	Nat                  PolicyType = "NAT"
	ACL                  PolicyType = "ACL"
	PA                   PolicyType = "PA"
	VLAN                 PolicyType = "VLAN"
	VSID                 PolicyType = "VSID"
	VNet                 PolicyType = "VNET"
	L2Driver             PolicyType = "L2Driver"
	Isolation            PolicyType = "Isolation"
	QOS                  PolicyType = "QOS"
	OutboundNat          PolicyType = "OutBoundNAT"
	ExternalLoadBalancer PolicyType = "ELB"
	Route                PolicyType = "ROUTE"
)

RequestType const

type Process added in v0.3.0 

type Process interface {
	// Pid returns the process ID of the process within the container.
	Pid() int

	// Kill signals the process to terminate but does not wait for it to finish terminating.
	Kill() error

	// Wait waits for the process to exit.
	Wait() error

	// WaitTimeout waits for the process to exit or the duration to elapse. It returns
	// false if timeout occurs.
	WaitTimeout(time.Duration) error

	// ExitCode returns the exit code of the process. The process must have
	// already terminated.
	ExitCode() (int, error)

	// ResizeConsole resizes the console of the process.
	ResizeConsole(width, height uint16) error

	// Stdio returns the stdin, stdout, and stderr pipes, respectively. Closing
	// these pipes does not close the underlying pipes; it should be possible to
	// call this multiple times to get multiple interfaces.
	Stdio() (io.WriteCloser, io.ReadCloser, io.ReadCloser, error)

	// CloseStdin closes the write side of the stdin pipe so that the process is
	// notified on the read side that there is no more data in stdin.
	CloseStdin() error

	// Close cleans up any state associated with the process but does not kill
	// or wait on it.
	Close() error
}

Process represents a running or exited process.

type ProcessConfig added in v0.3.0 

type ProcessConfig struct {
	ApplicationName   string            `json:",omitempty"`
	CommandLine       string            `json:",omitempty"`
	CommandArgs       []string          `json:",omitempty"` // Used by Linux Containers on Windows
	User              string            `json:",omitempty"`
	WorkingDirectory  string            `json:",omitempty"`
	Environment       map[string]string `json:",omitempty"`
	EmulateConsole    bool              `json:",omitempty"`
	CreateStdInPipe   bool              `json:",omitempty"`
	CreateStdOutPipe  bool              `json:",omitempty"`
	CreateStdErrPipe  bool              `json:",omitempty"`
	ConsoleSize       [2]uint           `json:",omitempty"`
	CreateInUtilityVm bool              `json:",omitempty"` // Used by Linux Containers on Windows
	OCISpecification  *json.RawMessage  `json:",omitempty"` // Used by Linux Containers on Windows
}

ProcessConfig is used as both the input of Container.CreateProcess and to convert the parameters to JSON for passing onto the HCS

type ProcessError added in v0.3.0 

type ProcessError struct {
	Process   *process
	Operation string
	ExtraInfo string
	Err       error
}

ProcessError is an error encountered in HCS during an operation on a Process object

func (*ProcessError) Error added in v0.3.0 

func (e *ProcessError) Error() string

type ProcessListItem added in v0.4.2 

type ProcessListItem struct {
	CreateTimestamp              time.Time `json:",omitempty"`
	ImageName                    string    `json:",omitempty"`
	KernelTime100ns              uint64    `json:",omitempty"`
	MemoryCommitBytes            uint64    `json:",omitempty"`
	MemoryWorkingSetPrivateBytes uint64    `json:",omitempty"`
	MemoryWorkingSetSharedBytes  uint64    `json:",omitempty"`
	ProcessId                    uint32    `json:",omitempty"`
	UserTime100ns                uint64    `json:",omitempty"`
}

ProcessList is the structure of an item returned by a ProcessList call on a container

type ProcessorStats added in v0.4.0 

type ProcessorStats struct {
	TotalRuntime100ns  uint64 `json:",omitempty"`
	RuntimeUser100ns   uint64 `json:",omitempty"`
	RuntimeKernel100ns uint64 `json:",omitempty"`
}

ProcessorStats holds the processor statistics for a container

type QosPolicy 

type QosPolicy struct {
	Type                            PolicyType `json:"Type"`
	MaximumOutgoingBandwidthInBytes uint64
}

type RegistryChanges added in v0.6.13 

type RegistryChanges struct {
	AddValues  []RegistryValue `json:",omitempty"`
	DeleteKeys []RegistryValue `json:",omitempty"`
}

type RegistryKey added in v0.6.13 

type RegistryKey struct {
	Hive     string
	Name     string
	Volatile bool `json:",omitempty"`
}

RegistryKey is used to specify registry key name

type RegistryValue added in v0.6.13 

type RegistryValue struct {
	Key         RegistryKey
	Name        string
	Type        string
	StringValue string  `json:",omitempty"`
	BinaryValue []byte  `json:",omitempty"`
	DWordValue  *uint32 `json:",omitempty"`
	QWordValue  *uint64 `json:",omitempty"`
	CustomType  *uint32 `json:",omitempty"`
}

RegistryKey is used to specify registry key name

type RequestType added in v0.5.15 

type RequestType string

Type of Request Support in ModifySystem

type ResourceModificationRequestResponse added in v0.5.15 

type ResourceModificationRequestResponse struct {
	Resource ResourceType `json:"ResourceType"`
	Data     interface{}  `json:"Settings"`
	Request  RequestType  `json:"RequestType,omitempty"`
}

ResourceModificationRequestResponse is the structure used to send request to the container to modify the system Supported resource types are Network and Request Types are Add/Remove

type ResourceType added in v0.5.15 

type ResourceType string

Type of Resource Support in ModifySystem

type RoutePolicy added in v0.5.27 

type RoutePolicy struct {
	Policy
	DestinationPrefix string `json:"DestinationPrefix,omitempty"`
	NextHop           string `json:"NextHop,omitempty"`
	EncapEnabled      bool   `json:"NeedEncap,omitempty"`
}

RoutePolicy is a structure defining schema for Route based Policy

type RuleType added in v0.5.27 

type RuleType string

type Statistics added in v0.4.0 

type Statistics struct {
	Timestamp          time.Time      `json:",omitempty"`
	ContainerStartTime time.Time      `json:",omitempty"`
	Uptime100ns        uint64         `json:",omitempty"`
	Memory             MemoryStats    `json:",omitempty"`
	Processor          ProcessorStats `json:",omitempty"`
	Storage            StorageStats   `json:",omitempty"`
	Network            []NetworkStats `json:",omitempty"`
}

Statistics is the structure returned by a statistics call on a container

type StorageStats added in v0.4.0 

type StorageStats struct {
	ReadCountNormalized  uint64 `json:",omitempty"`
	ReadSizeBytes        uint64 `json:",omitempty"`
	WriteCountNormalized uint64 `json:",omitempty"`
	WriteSizeBytes       uint64 `json:",omitempty"`
}

StorageStats holds the storage statistics for a container

type Subnet 

type Subnet struct {
	AddressPrefix  string            `json:",omitempty"`
	GatewayAddress string            `json:",omitempty"`
	Policies       []json.RawMessage `json:",omitempty"`
}

Subnet is assoicated with a network and represents a list of subnets available to the network

type SystemType added in v0.6.2 

type SystemType string

SystemType represents the type of the system on which actions are done 

const (
	ContainerType      SystemType = "Container"
	VirtualMachineType SystemType = "VirtualMachine"
	HostType           SystemType = "Host"
)

SystemType const

type VlanPolicy added in v0.3.2 

type VlanPolicy struct {
	Type PolicyType `json:"Type"`
	VLAN uint
}

type VsidPolicy added in v0.3.2 

type VsidPolicy struct {
	Type PolicyType `json:"Type"`
	VSID uint
}

type WC_LAYER_DESCRIPTOR 

type WC_LAYER_DESCRIPTOR struct {
	LayerId GUID
	Flags   uint32
	Pathp   *uint16
}
To pass into syscall, we need a struct matching the following:

typedef struct _WC_LAYER_DESCRIPTOR { 

//
// The ID of the layer
//

GUID LayerId;

//
// Additional flags
//

union {
    struct {
        ULONG Reserved : 31;
        ULONG Dirty : 1;    // Created from sandbox as a result of snapshot
    };
    ULONG Value;
} Flags;

//
// Path to the layer root directory, null-terminated
//

PCWSTR Path;

} WC_LAYER_DESCRIPTOR, *PWC_LAYER_DESCRIPTOR;

Source Files

View all Source files

Directories

Path Synopsis
test module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.