libmocktainer

README

libmocktainer

A stripped down version of libcontainer, with the bare minimum functionalities preserved for running Linux VMMs (QEMU, Firecracker) while remaining compliant with the OCI runtime flow.

Its main purpose is to back Unikraft's runu OCI runtime CLI.

Maintenance

To facilitate the maintenance of this library, please be mindful and keep it as close as possible to the upstream libcontainer code.

Copyright and license

The source code of libcontainer is distributed under the terms of the Apache 2.0 license, copyright 2014 Docker, inc.

Documentation

Index

• Constants
• Variables
• func Init()
• type BaseState
• type Bytemsg
  • func (msg *Bytemsg) Len() int
  • func (msg *Bytemsg) Serialize() []byte
• type Container
  • func Create(root, id string, config *configs.Config) (*Container, error)
  • func Load(root, id string) (*Container, error)
  • func (c *Container) Config() configs.Config
  • func (c *Container) Destroy() error
  • func (c *Container) Exec() error
  • func (c *Container) ID() string
  • func (c *Container) Signal(s os.Signal) error
  • func (c *Container) Start(process *Process) error
  • func (c *Container) State() (*State, error)
  • func (c *Container) Status() (Status, error)
• type Int32msg
  • func (msg *Int32msg) Len() int
  • func (msg *Int32msg) Serialize() []byte
• type Process
  • func (p Process) Pid() (int, error)
  • func (p Process) Signal(sig os.Signal) error
  • func (p Process) Wait() (*os.ProcessState, error)
• type State
• type Status
  • func (s Status) String() string

Constants

const (
	InitMsg        uint16 = 62000
	CloneFlagsAttr uint16 = 27281
	NsPathsAttr    uint16 = 27282
)

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

var (
	ErrExist      = errors.New("container with given ID already exists")
	ErrInvalidID  = errors.New("invalid container ID format")
	ErrNotExist   = errors.New("container does not exist")
	ErrRunning    = errors.New("container still running")
	ErrNotRunning = errors.New("container not running")
)

Functions

func Init

func Init()

Init is part of "runc init" implementation.

Types

type BaseState

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

type Bytemsg struct {
	Type  uint16
	Value []byte
}

Bytemsg has the following representation | nlattr len | nlattr type | | value | pad |

func (*Bytemsg) Len

func (msg *Bytemsg) Len() int

func (*Bytemsg) Serialize

func (msg *Bytemsg) Serialize() []byte

type Container

type Container struct {
	// contains filtered or unexported fields
}

Container is a libcontainer container object.

func Create

func Create(root, id string, config *configs.Config) (*Container, error)

Create creates a new container with the given id inside a given state directory (root), and returns a Container object.

The root is a state directory which many containers can share. It can be used later to get the list of containers, or to get information about a particular container (see Load).

The id must not be empty and consist of only the following characters: ASCII letters, digits, underscore, plus, minus, period. The id must be unique and non-existent for the given root path.

func Load

func Load(root, id string) (*Container, error)

Load takes a path to the state directory (root) and an id of an existing container, and returns a Container object reconstructed from the saved state. This presents a read only view of the container.

func (*Container) Config

func (c *Container) Config() configs.Config

Config returns the container's configuration

func (*Container) Destroy

func (c *Container) Destroy() error

Destroy destroys the container, if its in a valid state.

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.

func (*Container) Exec

func (c *Container) Exec() error

Exec signals the container to exec the users process at the end of the init.

func (*Container) ID

func (c *Container) ID() string

ID returns the container's unique ID

func (*Container) Signal

func (c *Container) Signal(s os.Signal) error

Signal sends a specified signal to container's init.

When s is SIGKILL and the container does not have its own PID namespace, all the container's processes are killed. In this scenario, the libcontainer user may be required to implement a proper child reaper.

func (*Container) Start

func (c *Container) Start(process *Process) error

Start starts a process inside the container. Returns error if process fails to start. You can track process lifecycle with passed Process structure.

func (*Container) State

func (c *Container) State() (*State, error)

State returns the current container's state information.

func (*Container) Status

func (c *Container) Status() (Status, error)

Status returns the current status of the container.

type Int32msg

type Int32msg struct {
	Type  uint16
	Value uint32
}

func (*Int32msg) Len

func (msg *Int32msg) Len() int

func (*Int32msg) Serialize

func (msg *Int32msg) Serialize() []byte

Serialize serializes the message. Int32msg has the following representation | nlattr len | nlattr type | | uint32 value |

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

	// 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

	// 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

	// LogLevel is a string containing a numeric representation of the current
	// log level (i.e. "4", but never "info"). It is passed on to runc init as
	// _LIBCONTAINER_LOGLEVEL environment variable.
	LogLevel string
	// contains filtered or unexported fields
}

Process specifies the configuration and IO for a process inside a container.

func (Process) Pid

func (p Process) Pid() (int, error)

Pid returns the process ID

func (Process) Signal

func (p Process) Signal(sig os.Signal) error

Signal sends a signal to the Process.

func (Process) Wait

func (p Process) Wait() (*os.ProcessState, error)

Wait waits for the process to exit. Wait releases any resources associated with the Process

type State

type State struct {
	BaseState

	// 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"`
}

State represents a running container's state

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
	// Stopped is the status that denotes the container does not have a created or running process.
	Stopped
)

func (Status) String

func (s Status) String() string