Documentation ¶
Overview ¶
Package libcontainer provides a native Go implementation for creating containers with namespaces, cgroups, capabilities, and filesystem access controls. It allows you to manage the lifecycle of the container performing additional operations after the container is created.
Index ¶
- Constants
- func Cgroupfs(l *LinuxFactory) error
- func CriuPath(criupath string) func(*LinuxFactory) error
- func InitArgs(args ...string) func(*LinuxFactory) error
- func IntelRdtFs(l *LinuxFactory) error
- func NewgidmapPath(newgidmapPath string) func(*LinuxFactory) error
- func NewuidmapPath(newuidmapPath string) func(*LinuxFactory) error
- func RootlessCgroupfs(l *LinuxFactory) error
- func SystemdCgroups(l *LinuxFactory) error
- func TmpfsRoot(l *LinuxFactory) error
- type BaseContainer
- type BaseState
- type Boolmsg
- type Bytemsg
- type Container
- type CriuOpts
- type CriuPageServerInfo
- type Error
- type ErrorCode
- type Factory
- type IO
- type Int32msg
- type LinuxFactory
- type NetworkInterface
- type PressureLevel
- type Process
- type State
- type Stats
- type Status
- type VethPairName
Constants ¶
const ( CRIU_CG_MODE_SOFT cgMode = 3 + iota // restore cgroup properties if only dir created by criu CRIU_CG_MODE_FULL // always restore all cgroups and their properties CRIU_CG_MODE_STRICT // restore all, requiring them to not present in the system CRIU_CG_MODE_DEFAULT // the same as CRIU_CG_MODE_SOFT )
const ( InitMsg uint16 = 62000 CloneFlagsAttr uint16 = 27281 NsPathsAttr uint16 = 27282 UidmapAttr uint16 = 27283 GidmapAttr uint16 = 27284 SetgroupAttr uint16 = 27285 OomScoreAdjAttr uint16 = 27286 RootlessEUIDAttr uint16 = 27287 UidmapPathAttr uint16 = 27288 GidmapPathAttr uint16 = 27289 )
list of known message types we want to send to bootstrap program The number is randomly chosen to not conflict with known netlink types
Variables ¶
This section is empty.
Functions ¶
func Cgroupfs ¶
func Cgroupfs(l *LinuxFactory) error
Cgroupfs is an options func to configure a LinuxFactory to return containers that use the native cgroups filesystem implementation to create and manage cgroups.
func CriuPath ¶
func CriuPath(criupath string) func(*LinuxFactory) error
CriuPath returns an option func to configure a LinuxFactory with the provided criupath
func InitArgs ¶
func InitArgs(args ...string) func(*LinuxFactory) error
InitArgs returns an options func to configure a LinuxFactory with the provided init binary path and arguments.
func IntelRdtFs ¶
func IntelRdtFs(l *LinuxFactory) error
IntelRdtfs is an options func to configure a LinuxFactory to return containers that use the Intel RDT "resource control" filesystem to create and manage Intel RDT resources (e.g., L3 cache, memory bandwidth).
func NewgidmapPath ¶
func NewgidmapPath(newgidmapPath string) func(*LinuxFactory) error
NewgidmapPath returns an option func to configure a LinuxFactory with the provided ..
func NewuidmapPath ¶
func NewuidmapPath(newuidmapPath string) func(*LinuxFactory) error
NewuidmapPath returns an option func to configure a LinuxFactory with the provided ..
func RootlessCgroupfs ¶
func RootlessCgroupfs(l *LinuxFactory) error
RootlessCgroupfs is an options func to configure a LinuxFactory to return containers that use the native cgroups filesystem implementation to create and manage cgroups. The difference between RootlessCgroupfs and Cgroupfs is that RootlessCgroupfs can transparently handle permission errors that occur during rootless container (including euid=0 in userns) setup (while still allowing cgroup usage if they've been set up properly).
func SystemdCgroups ¶
func SystemdCgroups(l *LinuxFactory) error
SystemdCgroups is an options func to configure a LinuxFactory to return containers that use systemd to create and manage cgroups.
func TmpfsRoot ¶
func TmpfsRoot(l *LinuxFactory) error
TmpfsRoot is an option func to mount LinuxFactory.Root to tmpfs.
Types ¶
type BaseContainer ¶ added in v0.0.5
type BaseContainer interface { // Returns the ID of the container ID() string // Returns the current status of the container. // // errors: // ContainerNotExists - Container no longer exists, // Systemerror - System error. Status() (Status, error) // State returns the current container's state information. // // errors: // SystemError - System error. State() (*State, error) // OCIState returns the current container's state information. // // errors: // SystemError - System error. OCIState() (*specs.State, error) // Returns the current config of the container. Config() configs.Config // Returns the PIDs inside this container. The PIDs are in the namespace of the calling process. // // errors: // ContainerNotExists - Container no longer exists, // Systemerror - System error. // // Some of the returned PIDs may no longer refer to processes in the Container, unless // the Container state is PAUSED in which case every PID in the slice is valid. Processes() ([]int, error) // Returns statistics for the container. // // errors: // ContainerNotExists - Container no longer exists, // Systemerror - System error. Stats() (*Stats, error) // Set resources of container as configured // // We can use this to change resources when containers are running. // // errors: // SystemError - System error. Set(config configs.Config) error // Start a process inside the container. Returns error if process fails to // start. You can track process lifecycle with passed Process structure. // // errors: // ContainerNotExists - Container no longer exists, // ConfigInvalid - config is invalid, // ContainerPaused - Container is paused, // SystemError - System error. Start(process *Process) (err error) // Run immediately starts the process inside the container. Returns error if process // fails to start. It does not block waiting for the exec fifo after start returns but // opens the fifo after start returns. // // errors: // ContainerNotExists - Container no longer exists, // ConfigInvalid - config is invalid, // ContainerPaused - Container is paused, // SystemError - System error. Run(process *Process) (err error) // Destroys the container, if its in a valid state, after killing any // remaining running processes. // // Any event registrations are removed before the container is destroyed. // No error is returned if the container is already destroyed. // // Running containers must first be stopped using Signal(..). // Paused containers must first be resumed using Resume(..). // // errors: // ContainerNotStopped - Container is still running, // ContainerPaused - Container is paused, // SystemError - System error. Destroy() error // Signal sends the provided signal code to the container's initial process. // // If all is specified the signal is sent to all processes in the container // including the initial process. // // errors: // SystemError - System error. Signal(s os.Signal, all bool) error // Exec signals the container to exec the users process at the end of the init. // // errors: // SystemError - System error. Exec() error }
BaseContainer is a libcontainer container object.
Each container is thread-safe within the same process. Since a container can be destroyed by a separate process, any function may return that the container was not found. BaseContainer includes methods that are platform agnostic.
type BaseState ¶ added in v0.0.5
type BaseState struct { // ID is the container ID. ID string `json:"id"` // InitProcessPid is the init process id in the parent namespace. InitProcessPid int `json:"init_process_pid"` // InitProcessStartTime is the init process start time in clock cycles since boot time. InitProcessStartTime uint64 `json:"init_process_start"` // Created is the unix timestamp for the creation time of the container in UTC Created time.Time `json:"created"` // Config is the container's configuration. Config configs.Config `json:"config"` }
BaseState represents the platform agnostic pieces relating to a running container's state
type Bytemsg ¶ added in v0.0.6
Bytemsg has the following representation | nlattr len | nlattr type | | value | pad |
type Container ¶
type Container interface { BaseContainer // Checkpoint checkpoints the running container's state to disk using the criu(8) utility. // // errors: // Systemerror - System error. Checkpoint(criuOpts *CriuOpts) error // Restore restores the checkpointed container to a running state using the criu(8) utility. // // errors: // Systemerror - System error. Restore(process *Process, criuOpts *CriuOpts) error // If the Container state is RUNNING or CREATED, sets the Container state to PAUSING and pauses // the execution of any user processes. Asynchronously, when the container finished being paused the // state is changed to PAUSED. // If the Container state is PAUSED, do nothing. // // errors: // ContainerNotExists - Container no longer exists, // ContainerNotRunning - Container not running or created, // Systemerror - System error. Pause() error // If the Container state is PAUSED, resumes the execution of any user processes in the // Container before setting the Container state to RUNNING. // If the Container state is RUNNING, do nothing. // // errors: // ContainerNotExists - Container no longer exists, // ContainerNotPaused - Container is not paused, // Systemerror - System error. Resume() error // NotifyOOM returns a read-only channel signaling when the container receives an OOM notification. // // errors: // Systemerror - System error. NotifyOOM() (<-chan struct{}, error) // NotifyMemoryPressure returns a read-only channel signaling when the container reaches a given pressure level // // errors: // Systemerror - System error. NotifyMemoryPressure(level PressureLevel) (<-chan struct{}, error) }
Container is a libcontainer container object.
Each container is thread-safe within the same process. Since a container can be destroyed by a separate process, any function may return that the container was not found.
type CriuOpts ¶
type CriuOpts struct { ImagesDirectory string // directory for storing image files WorkDirectory string // directory to cd and write logs/pidfiles/stats to ParentImage string // directory for storing parent image files in pre-dump and dump LeaveRunning bool // leave container in running state after checkpoint TcpEstablished bool // checkpoint/restore established TCP connections ExternalUnixConnections bool // allow external unix connections ShellJob bool // allow to dump and restore shell jobs FileLocks bool // handle file locks, for safety PreDump bool // call criu predump to perform iterative checkpoint PageServer CriuPageServerInfo // allow to dump to criu page server VethPairs []VethPairName // pass the veth to criu when restore ManageCgroupsMode cgMode // dump or restore cgroup mode EmptyNs uint32 // don't c/r properties for namespace from this mask AutoDedup bool // auto deduplication for incremental dumps LazyPages bool // restore memory pages lazily using userfaultfd StatusFd string // fd for feedback when lazy server is ready }
type CriuPageServerInfo ¶
type Error ¶
type Error interface { error // Returns an error if it failed to write the detail of the Error to w. // The detail of the Error may include the error message and a // representation of the stack trace. Detail(w io.Writer) error // Returns the error code for this error. Code() ErrorCode }
Error is the API error type.
type ErrorCode ¶
type ErrorCode int
ErrorCode is the API error code type.
type Factory ¶
type Factory interface { // Creates a new container with the given id and starts the initial process inside it. // id must be a string containing only letters, digits and underscores and must contain // between 1 and 1024 characters, inclusive. // // The id must not already be in use by an existing container. Containers created using // a factory with the same path (and filesystem) must have distinct ids. // // Returns the new container with a running process. // // errors: // IdInUse - id is already in use by a container // InvalidIdFormat - id has incorrect format // ConfigInvalid - config is invalid // Systemerror - System error // // On error, any partially created container parts are cleaned up (the operation is atomic). Create(id string, config *configs.Config) (Container, error) // Load takes an ID for an existing container and returns the container information // from the state. This presents a read only view of the container. // // errors: // Path does not exist // System error Load(id string) (Container, error) // StartInitialization is an internal API to libcontainer used during the reexec of the // container. // // Errors: // Pipe connection error // System error StartInitialization() error // Type returns info string about factory type (e.g. lxc, libcontainer...) Type() string }
type IO ¶ added in v0.0.7
type IO struct { Stdin io.WriteCloser Stdout io.ReadCloser Stderr io.ReadCloser }
IO holds the process's STDIO
type LinuxFactory ¶
type LinuxFactory struct { // Root directory for the factory to store state. Root string // InitPath is the path for calling the init responsibilities for spawning // a container. InitPath string // InitArgs are arguments for calling the init responsibilities for spawning // a container. InitArgs []string // CriuPath is the path to the criu binary used for checkpoint and restore of // containers. CriuPath string // New{u,g}uidmapPath is the path to the binaries used for mapping with // rootless containers. NewuidmapPath string NewgidmapPath string // Validator provides validation to container configurations. Validator validate.Validator // NewCgroupsManager returns an initialized cgroups manager for a single container. NewCgroupsManager func(config *configs.Cgroup, paths map[string]string) cgroups.Manager // NewIntelRdtManager returns an initialized Intel RDT manager for a single container. NewIntelRdtManager func(config *configs.Config, id string, path string) intelrdt.Manager }
LinuxFactory implements the default factory interface for linux based systems.
func (*LinuxFactory) StartInitialization ¶
func (l *LinuxFactory) StartInitialization() (err error)
StartInitialization loads a container by opening the pipe fd from the parent to read the configuration and state This is a low level implementation detail of the reexec and should not be consumed externally
func (*LinuxFactory) Type ¶
func (l *LinuxFactory) Type() string
type NetworkInterface ¶
type PressureLevel ¶ added in v0.0.7
type PressureLevel uint
const ( LowPressure PressureLevel = iota MediumPressure CriticalPressure )
type Process ¶
type Process struct { // The command to be run followed by any arguments. Args []string // Env specifies the environment variables for the process. Env []string // User will set the uid and gid of the executing process running inside the container // local to the container's user and group configuration. User string // AdditionalGroups specifies the gids that should be added to supplementary groups // in addition to those that the user belongs to. AdditionalGroups []string // Cwd will change the processes current working directory inside the container's rootfs. Cwd string // Stdin is a pointer to a reader which provides the standard input stream. Stdin io.Reader // Stdout is a pointer to a writer which receives the standard output stream. Stdout io.Writer // Stderr is a pointer to a writer which receives the standard error stream. Stderr io.Writer // ExtraFiles specifies additional open files to be inherited by the container ExtraFiles []*os.File // Initial sizings for the console ConsoleWidth uint16 ConsoleHeight uint16 // Capabilities specify the capabilities to keep when executing the process inside the container // All capabilities not specified will be dropped from the processes capability mask Capabilities *configs.Capabilities // AppArmorProfile specifies the profile to apply to the process and is // changed at the time the process is execed AppArmorProfile string // Label specifies the label to apply to the process. It is commonly used by selinux Label string // NoNewPrivileges controls whether processes can gain additional privileges. NoNewPrivileges *bool // Rlimits specifies the resource limits, such as max open files, to set in the container // If Rlimits are not set, the container will inherit rlimits from the parent process Rlimits []configs.Rlimit // ConsoleSocket provides the masterfd console. ConsoleSocket *os.File // Init specifies whether the process is the first process in the container. Init bool // contains filtered or unexported fields }
Process specifies the configuration and IO for a process inside a container.
func (*Process) InitializeIO ¶ added in v0.0.7
InitializeIO creates pipes for use with the process's stdio and returns the opposite side for each. Do not use this if you want to have a pseudoterminal set up for you by libcontainer (TODO: fix that too). TODO: This is mostly unnecessary, and should be handled by clients.
type State ¶
type State struct { BaseState // Specified if the container was started under the rootless mode. // Set to true if BaseState.Config.RootlessEUID && BaseState.Config.RootlessCgroups Rootless bool `json:"rootless"` // Path to all the cgroups setup for a container. Key is cgroup subsystem name // with the value as the path. CgroupPaths map[string]string `json:"cgroup_paths"` // NamespacePaths are filepaths to the container's namespaces. Key is the namespace type // with the value as the path. NamespacePaths map[configs.NamespaceType]string `json:"namespace_paths"` // Container's standard descriptors (std{in,out,err}), needed for checkpoint and restore ExternalDescriptors []string `json:"external_descriptors,omitempty"` // Intel RDT "resource control" filesystem path IntelRdtPath string `json:"intel_rdt_path"` }
State represents a running container's state
type Stats ¶
type Stats struct { Interfaces []*NetworkInterface CgroupStats *cgroups.Stats IntelRdtStats *intelrdt.Stats }
type Status ¶
type Status int
Status is the status of a container.
const ( // Created is the status that denotes the container exists but has not been run yet. Created Status = iota // Running is the status that denotes the container exists and is running. Running // Pausing is the status that denotes the container exists, it is in the process of being paused. Pausing // Paused is the status that denotes the container exists, but all its processes are paused. Paused // Stopped is the status that denotes the container does not have a created or running process. Stopped )
type VethPairName ¶ added in v0.0.4
Source Files ¶
- capabilities_linux.go
- console_linux.go
- container.go
- container_linux.go
- criu_opts_linux.go
- error.go
- factory.go
- factory_linux.go
- generic_error.go
- init_linux.go
- message_linux.go
- network_linux.go
- notify_linux.go
- process.go
- process_linux.go
- restored_process.go
- rootfs_linux.go
- setns_init_linux.go
- standard_init_linux.go
- state_linux.go
- stats.go
- stats_linux.go
- sync.go
Directories ¶
Path | Synopsis |
---|---|
Package criurpc is a generated protocol buffer package.
|
Package criurpc is a generated protocol buffer package. |
integration is used for integration testing of libcontainer
|
integration is used for integration testing of libcontainer |
Package specconv implements conversion of specifications to libcontainer configurations
|
Package specconv implements conversion of specifications to libcontainer configurations |