runc/libcontainer
Michael Crosby 3d8a20bb77 Do not use stream encoders
Marshall the raw objects for the sync pipes so that no new line chars
are left behind in the pipe causing errors.

Signed-off-by: Michael Crosby <crosbymichael@gmail.com>
2016-01-26 14:52:00 -08:00
..
apparmor Adding error conditions when apparmor disabled 2015-11-22 13:14:18 +05:30
cgroups cgroups: fs: fix cgroup.Parent path sanitisation 2016-01-21 16:53:06 -08:00
configs Embed Resources for backward compatibility 2016-01-19 15:27:26 -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 Revert "cgroups: add pids controller support" 2015-12-19 07:48:48 -08:00
label Docker needs to know whether the user requested a relabel 2015-10-28 15:44:38 -04:00
nsenter setns: replace env with netlink for bootstrap data 2015-12-03 18:03:48 +00:00
seccomp Handle seccomp proc parsing errors 2016-01-19 15:27:54 -08:00
selinux Update import paths for new repository 2015-06-21 19:29:59 -07:00
stacktrace avoid infinite loop with GCCGO 2015-07-10 19:15:26 +00:00
system Fix build tags 2015-07-01 13:22:09 -07:00
user Allow numeric groups for containers without /etc/group 2015-10-04 19:02:35 -04:00
utils Do not use stream encoders 2016-01-26 14:52:00 -08:00
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 libcontainer/SPEC.md: fix /dev/stdio symlinks 2015-10-21 11:10:24 +02: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 Windows: Refactor Container interface 2015-11-02 15:12:16 -08:00
container_linux.go Do not use stream encoders 2016-01-26 14:52:00 -08:00
container_linux_test.go Update import paths for new repository 2015-06-21 19:29:59 -07: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 Do not use stream encoders 2016-01-26 14:52:00 -08:00
factory_linux_test.go Do not use stream encoders 2016-01-26 14:52:00 -08:00
generic_error.go Revert "cgroups: add pids controller support" 2015-12-19 07:48:48 -08:00
generic_error_test.go Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00
init_linux.go Revert "cgroups: add pids controller support" 2015-12-19 07:48:48 -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 Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00
notify_linux_test.go Move libcontainer into subdirectory 2015-06-21 19:29:15 -07:00
process.go Move linux only Process.InitializeIO behind the linux build flag. 2015-12-15 15:12:29 -05:00
process_linux.go Do not use stream encoders 2016-01-26 14:52:00 -08:00
restored_process.go Add signal API to Container interface 2015-08-03 17:07:29 -07:00
rootfs_linux.go Merge pull request #357 from ashahab-altiscale/350-container-in-container 2015-11-16 14:54:02 -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 Revert "cgroups: add pids controller support" 2015-12-19 07:48:48 -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.