2015-02-12 09:12:03 +08:00
// 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.
2014-02-19 08:56:11 +08:00
package libcontainer
2014-12-17 17:12:23 +08:00
import (
2015-02-01 12:51:12 +08:00
"os"
2014-12-17 17:12:23 +08:00
"github.com/docker/libcontainer/configs"
)
2015-02-12 08:45:23 +08:00
// The status of a container.
type Status int
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 does not exist.
Destroyed
)
2015-02-12 06:45:07 +08:00
// State represents a running container's state
type State struct {
2015-02-12 08:45:23 +08:00
// ID is the container ID.
ID string ` json:"id" `
2015-02-12 06:45:07 +08:00
// InitProcessPid is the init process id in the parent namespace.
2015-02-12 08:45:23 +08:00
InitProcessPid int ` json:"init_process_pid" `
2015-02-12 06:45:07 +08:00
// InitProcessStartTime is the init process start time.
2015-02-12 08:45:23 +08:00
InitProcessStartTime string ` json:"init_process_start" `
2015-02-12 06:45:07 +08:00
// Path to all the cgroups setup for a container. Key is cgroup subsystem name
// with the value as the path.
2015-02-12 08:45:23 +08:00
CgroupPaths map [ string ] string ` json:"cgroup_paths" `
2015-02-12 06:45:07 +08:00
// NamespacePaths are filepaths to the container's namespaces. Key is the namespace name
// with the value as the path.
2015-02-12 08:45:23 +08:00
NamespacePaths map [ string ] string ` json:"namespace_paths" `
// Config is the container's configuration.
Config configs . Config ` json:"config" `
2015-02-12 06:45:07 +08:00
}
2014-10-28 08:51:14 +08:00
// 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 Container interface {
2014-08-26 23:18:13 +08:00
// Returns the ID of the container
ID ( ) string
2014-07-09 01:17:05 +08:00
2015-02-04 02:50:18 +08:00
// Returns the current status of the container.
2014-07-09 01:17:05 +08:00
//
2014-10-23 07:27:06 +08:00
// errors:
2015-02-12 06:45:07 +08:00
// ContainerDestroyed - Container no longer exists,
2014-10-23 07:27:06 +08:00
// Systemerror - System error.
2015-02-12 08:45:23 +08:00
Status ( ) ( Status , error )
2014-07-09 01:17:05 +08:00
2015-02-12 06:45:07 +08:00
// State returns the current container's state information.
//
// errors:
// Systemerror - System erroor.
State ( ) ( * State , error )
2014-07-09 01:17:05 +08:00
// Returns the current config of the container.
2015-02-01 13:21:06 +08:00
Config ( ) configs . Config
2014-07-09 01:17:05 +08:00
2014-10-23 01:35:29 +08:00
// Returns the PIDs inside this container. The PIDs are in the namespace of the calling process.
2014-07-17 09:02:29 +08:00
//
2014-10-23 07:27:06 +08:00
// errors:
2014-09-04 07:03:41 +08:00
// ContainerDestroyed - Container no longer exists,
2014-10-23 07:27:06 +08:00
// Systemerror - System error.
2014-07-09 01:17:05 +08:00
//
2014-10-23 01:35:29 +08:00
// 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.
2014-10-23 07:27:06 +08:00
Processes ( ) ( [ ] int , error )
2014-10-23 01:35:29 +08:00
// Returns statistics for the container.
2014-07-09 01:17:05 +08:00
//
2014-10-23 07:27:06 +08:00
// errors:
2014-10-23 01:35:29 +08:00
// ContainerDestroyed - Container no longer exists,
2014-10-23 07:27:06 +08:00
// Systemerror - System error.
2015-02-01 11:56:27 +08:00
Stats ( ) ( * Stats , error )
2014-10-23 01:35:29 +08:00
// Start a process inside the container. Returns the PID of the new process (in the caller process's namespace) and a channel that will return the exit status of the process whenever it dies.
2014-07-09 01:17:05 +08:00
//
2014-10-23 07:27:06 +08:00
// errors:
2014-09-04 07:03:41 +08:00
// ContainerDestroyed - Container no longer exists,
2014-10-23 01:35:29 +08:00
// ConfigInvalid - config is invalid,
// ContainerPaused - Container is paused,
2014-10-23 07:27:06 +08:00
// Systemerror - System error.
2015-02-01 12:51:12 +08:00
Start ( process * Process ) ( pid int , err error )
2014-07-09 01:17:05 +08:00
2014-10-23 01:35:29 +08:00
// 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.
2014-07-09 01:17:05 +08:00
//
2014-10-23 07:27:06 +08:00
// errors:
// Systemerror - System error.
Destroy ( ) error
2014-07-09 01:17:05 +08:00
// 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.
//
2014-10-23 07:27:06 +08:00
// errors:
2014-09-04 07:03:41 +08:00
// ContainerDestroyed - Container no longer exists,
2014-10-23 07:27:06 +08:00
// Systemerror - System error.
Pause ( ) error
2014-07-09 01:17:05 +08:00
// 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.
//
2014-10-23 07:27:06 +08:00
// errors:
2014-09-04 07:03:41 +08:00
// ContainerDestroyed - Container no longer exists,
2014-10-23 07:27:06 +08:00
// Systemerror - System error.
Resume ( ) error
2014-10-23 03:06:35 +08:00
2015-02-01 12:51:12 +08:00
// Signal sends the specified signal to the init process of the container.
2014-10-23 03:06:35 +08:00
//
2014-10-23 07:27:06 +08:00
// errors:
2014-10-23 03:06:35 +08:00
// ContainerDestroyed - Container no longer exists,
// ContainerPaused - Container is paused,
2014-10-23 07:27:06 +08:00
// Systemerror - System error.
2015-02-01 12:51:12 +08:00
Signal ( signal os . Signal ) error
2014-10-23 03:06:35 +08:00
2015-02-12 07:09:54 +08:00
// NotifyOOM returns a read-only channel signaling when the container receives an OOM notification.
2015-02-01 11:56:27 +08:00
//
// errors:
// Systemerror - System error.
2015-02-12 07:09:54 +08:00
NotifyOOM ( ) ( <- chan struct { } , error )
2014-05-17 15:06:29 +08:00
}