README ¶
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.
Container
A container is a self contained execution environment that shares the kernel of the host system and which is (optionally) isolated from other containers in the system.
Using libcontainer
To create a container you first have to initialize an instance of a factory that will handle the creation and initialization for a container.
Because containers are spawned in a two step process you will need to provide
arguments to a binary that will be executed as the init process for the container.
To use the current binary that is spawning the containers and acting as the parent
you can use os.Args[0]
and we have a command called init
setup.
root, err := libcontainer.New("/var/lib/container", libcontainer.InitArgs(os.Args[0], "init"))
if err != nil {
log.Fatal(err)
}
Once you have an instance of the factory created we can create a configuration struct describing how the container is to be created. A sample would look similar to this:
config := &configs.Config{
Rootfs: rootfs,
Capabilities: []string{
"CAP_CHOWN",
"CAP_DAC_OVERRIDE",
"CAP_FSETID",
"CAP_FOWNER",
"CAP_MKNOD",
"CAP_NET_RAW",
"CAP_SETGID",
"CAP_SETUID",
"CAP_SETFCAP",
"CAP_SETPCAP",
"CAP_NET_BIND_SERVICE",
"CAP_SYS_CHROOT",
"CAP_KILL",
"CAP_AUDIT_WRITE",
},
Namespaces: configs.Namespaces([]configs.Namespace{
{Type: configs.NEWNS},
{Type: configs.NEWUTS},
{Type: configs.NEWIPC},
{Type: configs.NEWPID},
{Type: configs.NEWNET},
}),
Cgroups: &configs.Cgroup{
Name: "test-container",
Parent: "system",
AllowAllDevices: false,
AllowedDevices: configs.DefaultAllowedDevices,
},
Devices: configs.DefaultAutoCreatedDevices,
Hostname: "testing",
Networks: []*configs.Network{
{
Type: "loopback",
Address: "127.0.0.1/0",
Gateway: "localhost",
},
},
Rlimits: []configs.Rlimit{
{
Type: syscall.RLIMIT_NOFILE,
Hard: uint64(1024),
Soft: uint64(1024),
},
},
}
Once you have the configuration populated you can create a container:
container, err := root.Create("container-id", config)
To spawn bash as the initial process inside the container and have the processes pid returned in order to wait, signal, or kill the process:
process := &libcontainer.Process{
Args: []string{"/bin/bash"},
Env: []string{"PATH=/bin"},
User: "daemon",
Stdin: os.Stdin,
Stdout: os.Stdout,
Stderr: os.Stderr,
}
err := container.Start(process)
if err != nil {
log.Fatal(err)
}
// wait for the process to finish.
status, err := process.Wait()
if err != nil {
log.Fatal(err)
}
// destroy the container.
container.Destroy()
Additional ways to interact with a running container are:
// return all the pids for all processes running inside the container.
processes, err := container.Processes()
// get detailed cpu, memory, io, and network statistics for the container and
// it's processes.
stats, err := container.Stats()
// pause all processes inside the container.
container.Pause()
// resume all paused processes.
container.Resume()
Checkpoint & Restore
libcontainer now integrates CRIU for checkpointing and restoring containers. This let's you save the state of a process running inside a container to disk, and then restore that state into a new process, on the same machine or on another machine.
criu
version 1.5.2 or higher is required to use checkpoint and restore.
If you don't already have criu
installed, you can build it from source, following the
online instructions. criu
is also installed in the docker image
generated when building libcontainer with docker.
Copyright and license
Code and documentation copyright 2014 Docker, inc. Code released under the Apache 2.0 license. Docs released under Creative commons.
Documentation ¶
Overview ¶
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 InitArgs(args ...string) func(*LinuxFactory) error
- func InitPath(path string, args ...string) func(*LinuxFactory) error
- func SystemdCgroups(l *LinuxFactory) error
- func TmpfsRoot(l *LinuxFactory) error
- type BaseContainer
- type BaseState
- type Console
- type Container
- type CriuOpts
- type CriuPageServerInfo
- type Error
- type ErrorCode
- type Factory
- type LinuxFactory
- type NetworkInterface
- type Process
- type State
- type Stats
- type Status
- type VethPairName
Constants ¶
const ( CRIU_CG_MODE_SOFT cg_mode = 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 )
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 InitArgs ¶
func InitArgs(args ...string) func(*LinuxFactory) error
InitArgs returns an options func to configure a LinuxFactory with the provided init arguments.
func InitPath ¶
func InitPath(path string, args ...string) func(*LinuxFactory) error
InitPath returns an options func to configure a LinuxFactory with the provided absolute path to the init binary and arguements.
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: // ContainerDestroyed - 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) // 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: // ContainerDestroyed - 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: // ContainerDestroyed - 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: // ContainerDestroyed - Container no longer exists, // ConfigInvalid - config is invalid, // ContainerPaused - Container is paused, // Systemerror - System error. Start(process *Process) (err error) // Destroys the container after killing all running processes. // // Any event registrations are removed before the container is destroyed. // No error is returned if the container is already destroyed. // // errors: // Systemerror - System error. Destroy() error // Signal sends the provided signal code to the container's initial process. // // errors: // Systemerror - System error. Signal(s os.Signal) error }
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. InitProcessStartTime string `json:"init_process_start"` // 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 Console ¶
type Console interface { io.ReadWriter io.Closer // Path returns the filesystem path to the slave side of the pty. Path() string // Fd returns the fd for the master of the pty. Fd() uintptr }
Console represents a pseudo TTY.
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) utiity. // // errors: // Systemerror - System error. Restore(process *Process, criuOpts *CriuOpts) error // If the Container state is RUNNING or PAUSING, 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: // ContainerDestroyed - Container no longer exists, // 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: // ContainerDestroyed - Container no longer exists, // 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) }
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 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 PageServer CriuPageServerInfo // allow to dump to criu page server VethPairs []VethPairName // pass the veth to criu when restore ManageCgroupsMode cg_mode // dump or restore cgroup mode }
type CriuPageServerInfo ¶
type Error ¶
type Error interface { error // Returns a verbose string including the error message // and a representation of the stack trace suitable for // printing. Detail(w io.Writer) error // Returns the error code for this error. Code() ErrorCode }
API Error type.
type ErrorCode ¶
type ErrorCode int
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 file system) 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 // Container is stopped // 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 LinuxFactory ¶
type LinuxFactory struct { // Root directory for the factory to store state. Root string // InitPath is the absolute path to the init binary. 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 // 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 }
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 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 // 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 // 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 []string // contains filtered or unexported fields }
Process specifies the configuration and IO for a process inside a container.
func (*Process) NewConsole ¶
NewConsole creates new console for process and returns it
type State ¶
type State struct { BaseState // 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"` }
State represents a running container's state
type Stats ¶
type Stats struct { Interfaces []*NetworkInterface CgroupStats *cgroups.Stats }
type Status ¶
type Status int
The status of a container.
const ( // The container exists and is running. Running Status = iota + 1 // The container exists, it is in the process of being paused. Pausing // The container exists, but all its processes are paused. Paused // The container exists, but its state is saved on disk Checkpointed // The container does not exist. Destroyed )
type VethPairName ¶ added in v0.0.4
Source Files ¶
- capabilities_linux.go
- console.go
- console_linux.go
- container.go
- container_linux.go
- container_userns_linux.go
- criu_opts_unix.go
- error.go
- factory.go
- factory_linux.go
- generic_error.go
- init_linux.go
- network_linux.go
- notify_linux.go
- process.go
- process_linux.go
- restored_process.go
- rootfs_linux.go
- setgroups_linux.go
- setns_init_linux.go
- standard_init_linux.go
- stats.go
- stats_linux.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 |