runc/libcontainer
Mrunal Patel 6259f09e97 Merge pull request #426 from gitido/pressure_level
libcontainer: Add support for memcg pressure notifications
2016-01-14 16:23:07 -08:00
..
apparmor Adding error conditions when apparmor disabled 2015-11-22 13:14:18 +05:30
cgroups Only validate post-hyphen field length on cgroup mounts 2016-01-13 11:28:49 -08:00
configs Merge pull request #455 from hallyn/tty01 2016-01-14 14:35:46 -08:00
criurpc Add option to support criu manage cgroups mode for dump and restore 2015-10-11 04:42:54 +00:00
devices Windows: Tidy libcontainer\devices 2015-10-23 13:50:24 -07:00
hack Update import paths for new repository 2015-06-21 19:29:59 -07:00
integration libcontainer: set cgroup config late 2016-01-12 10:06:35 +11:00
label make localtest failure with selinux enabled 2015-11-24 23:24:30 +05:30
nsenter setns: replace env with netlink for bootstrap data 2015-12-03 18:03:48 +00:00
seccomp Add seccomp trace support 2015-11-12 17:03:53 -08:00
selinux Fixing TestSetFilecon in selinux test step 2015-11-28 13:51:46 +05:30
stacktrace avoid infinite loop with GCCGO 2015-07-10 19:15:26 +00:00
system Do not create devices when in user namespace 2016-01-08 12:54:08 -08:00
user Allow numeric groups for containers without /etc/group 2015-10-04 19:02:35 -04:00
utils Fixing typo in the comment for exit 2015-10-22 19:08:03 +05:30
xattr Fixing xattr test step issue 2015-11-29 09:24:42 +05:30
README.md Update README for the CAP prefix change 2015-09-15 14:44:12 -04:00
SPEC.md Fix typo word in SPEC.md 2015-12-30 00:30:58 +00:00
capabilities_linux.go Update github.com/syndtr/gocapability/capability to 2c00daeb6c3b45114c80ac44119e7b8801fdd852 2015-09-24 18:44:01 -04:00
compat_1.5_linux.go Don't set /proc/<PID>/setgroups to deny in Go1.5 2015-08-03 14:59:15 -04:00
console.go Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00
console_freebsd.go Export console New func 2015-12-09 11:59:10 -08:00
console_linux.go Export console New func 2015-12-09 11:59:10 -08:00
console_windows.go Export console New func 2015-12-09 11:59:10 -08:00
container.go Add state pattern for container state transition 2015-12-17 13:55:38 -08:00
container_linux.go Merge pull request #426 from gitido/pressure_level 2016-01-14 16:23:07 -08:00
container_linux_test.go Revert to non-recursive GetPids, add recursive GetAllPids 2016-01-08 19:42:25 +00:00
container_nouserns_linux.go Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00
container_userns_linux.go Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00
container_windows.go Windows: Refactor Container interface 2015-11-02 15:12:16 -08:00
criu_opts_unix.go Windows: Factor down criu_opts 2015-10-23 12:58:59 -07:00
criu_opts_windows.go Windows: Factor down criu_opts 2015-10-23 12:58:59 -07:00
error.go fix minor typo 2015-12-11 21:37:32 +08:00
error_test.go Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00
factory.go Update import paths for new repository 2015-06-21 19:29:59 -07:00
factory_linux.go libcontainer: set cgroup config late 2016-01-12 10:06:35 +11:00
factory_linux_test.go Windows: Refactor state struct 2015-10-26 14:45:20 -07:00
generic_error.go libcontainer: set cgroup config late 2016-01-12 10:06:35 +11:00
generic_error_test.go Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00
init_linux.go Merge pull request #446 from cyphar/18-add-pids-controller 2016-01-11 16:56:00 -08:00
message_linux.go Caclulate NLA_HDRLEN as gccgo workaround 2015-12-17 17:36:47 -06:00
network_linux.go libcontainer: network_linux.go: fix go vet 2015-11-30 12:31:18 +01:00
notify_linux.go libcontainer: Add support for memcg pressure notifications 2015-12-28 13:36:55 -05:00
notify_linux_test.go libcontainer: Add support for memcg pressure notifications 2015-12-28 13:36:55 -05:00
process.go Move linux only Process.InitializeIO behind the linux build flag. 2015-12-15 15:12:29 -05:00
process_linux.go libcontainer: set cgroup config late 2016-01-12 10:06:35 +11:00
restored_process.go Add signal API to Container interface 2015-08-03 17:07:29 -07:00
rootfs_linux.go Do not create devices when in user namespace 2016-01-08 12:54:08 -08:00
rootfs_linux_test.go Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00
setgroups_linux.go Don't set /proc/<PID>/setgroups to deny in Go1.5 2015-08-03 14:59:15 -04:00
setns_init_linux.go Adding oom_score_adj as a container config param. 2015-08-31 14:02:59 -07:00
standard_init_linux.go libcontainer: set cgroup config late 2016-01-12 10:06:35 +11:00
state_linux.go Add state pattern for container state transition 2015-12-17 13:55:38 -08:00
state_linux_test.go Add state pattern for container state transition 2015-12-17 13:55:38 -08:00
stats.go Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00
stats_freebsd.go Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00
stats_linux.go Update import paths for new repository 2015-06-21 19:29:59 -07:00
stats_windows.go Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00

README.md

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.

Code and documentation copyright 2014 Docker, inc. Code released under the Apache 2.0 license. Docs released under Creative commons.