container

Documentation

Overview

Package container provides pre-forked container environment to run programs in isolated Linux namespaces.

Overview

It creates container within unshared container and communicate with host process using unix socket with oob for fd / pid and commands encoded by gob.

Protocol

Host to container communication protocol is single threaded and always initiated by the host:

## ping (alive check)

- send: ping - reply: pong

## conf (set configuration)

- send: conf - reply:

## open (open files in given mode inside container):

- send: []OpenCmd - reply: "success", file fds / "error"

## delete (unlink file / rmdir dir inside container):

- send: path - reply: "finished" / "error"

## reset (clean up container for later use (clear workdir / tmp)):

- send: - reply: "success"

## execve: (execute file inside container):

- send: argv, env, rLimits, fds - reply: - success: "success", pid - failed: "failed" - send (success): "init_finished" (as cmd) - reply: "finished" / send: "kill" (as cmd) - send: "kill" (as cmd) / reply: "finished" - reply:

Any socket related error will cause the container exit with all process inside container

Index

• Constants
• func Init() (err error)
• type Builder
  • func (b *Builder) Build() (Environment, error)
• type CredGenerator
• type Environment
• type ExecveParam
• type OpenCmd
• type SymbolicLink

Constants

const PathEnv = "PATH=/usr/local/bin:/usr/bin:/bin"

PathEnv defines path environment variable for the container init process

Functions

func Init

func Init() (err error)

Init is called for container init process it will check if pid == 1, otherwise it is noop Init will do infinite loop on socket commands, and exits when at socket close, use it in init function

Types

type Builder

type Builder struct {
	// Root is container root mount path, empty uses current work path
	Root string

	// TmpRoot defines the tmp dir pattern if not nil. Temp directory will be created as container root dir
	TmpRoot string

	// Mounts defines container mount points, empty uses default mounts
	Mounts []mount.Mount

	// SymbolicLinks defines symlinks to be created after mount file system
	SymbolicLinks []SymbolicLink

	// MaskPaths defines paths to be masked to avoid reading information from
	// outside of the container
	MaskPaths []string

	// WorkDir defines container default work directory (default: /w)
	WorkDir string

	// Stderr defines whether to dup container stderr to stderr for debug
	Stderr io.Writer

	// ExecFile defines executable that called Init, otherwise defer current
	// executable (/proc/self/exe)
	ExecFile string

	// CredGenerator defines a credential generator used to create new container
	CredGenerator CredGenerator

	// Clone flags defines unshare clone flag to create container
	CloneFlags uintptr

	// HostName set container hostname (default: go-sandbox)
	HostName string

	// DomainName set container domainname (default: go-sandbox)
	DomainName string

	// ContainerUID & ContainerGID set the container uid / gid mapping
	ContainerUID int
	ContainerGID int
}

Builder builds instance of container environment

func (*Builder) Build

func (b *Builder) Build() (Environment, error)

Build creates new environment with underlying container

type CredGenerator

type CredGenerator interface {
	Get() syscall.Credential
}

CredGenerator generates uid / gid credential used by container to isolate process and file system access

type Environment

type Environment interface {
	Ping() error
	Open([]OpenCmd) ([]*os.File, error)
	Delete(p string) error
	Reset() error
	Execve(context.Context, ExecveParam) runner.Result
	Destroy() error
}

Environment holds single progrem containerized environment

type ExecveParam

type ExecveParam struct {
	// Args holds command line arguments
	Args []string

	// Env specifies the environment of the process
	Env []string

	// Files specifies file descriptors for the child process
	Files []uintptr

	// ExecFile specifies file descriptor for executable file using fexecve
	ExecFile uintptr

	// RLimits specifies POSIX Resource limit through setrlimit
	RLimits []rlimit.RLimit

	// Seccomp specifies seccomp filter
	Seccomp seccomp.Filter

	// CTTY specifies whether to set controlling TTY
	CTTY bool

	// SyncFunc calls with pid just before execve (for attach the process to cgroups)
	SyncFunc func(pid int) error
}

ExecveParam is parameters to run process inside container

type OpenCmd

type OpenCmd struct {
	Path string
	Flag int
	Perm os.FileMode
}

OpenCmd correspond to a single open syscall

type SymbolicLink

type SymbolicLink struct {
	LinkPath string
	Target   string
}

SymbolicLink defines symlinks to be created after mount