github.com/mheon/docker@v0.11.2-0.20150922122814-44f47903a831/daemon/execdriver/driver.go (about)

     1  package execdriver
     2  
     3  import (
     4  	"errors"
     5  	"io"
     6  	"os/exec"
     7  	"time"
     8  
     9  	// TODO Windows: Factor out ulimit
    10  	"github.com/docker/docker/pkg/ulimit"
    11  	"github.com/opencontainers/runc/libcontainer"
    12  	"github.com/opencontainers/runc/libcontainer/configs"
    13  )
    14  
    15  // Context is a generic key value pair that allows
    16  // arbatrary data to be sent
    17  type Context map[string]string
    18  
    19  // Define error messages
    20  var (
    21  	ErrNotRunning              = errors.New("Container is not running")
    22  	ErrWaitTimeoutReached      = errors.New("Wait timeout reached")
    23  	ErrDriverAlreadyRegistered = errors.New("A driver already registered this docker init function")
    24  	ErrDriverNotFound          = errors.New("The requested docker init has not been found")
    25  )
    26  
    27  // DriverCallback defines a callback function which is used in "Run" and "Exec".
    28  // This allows work to be done in the parent process when the child is passing
    29  // through PreStart, Start and PostStop events.
    30  // Callbacks are provided a processConfig pointer and the pid of the child
    31  type DriverCallback func(processConfig *ProcessConfig, pid int) error
    32  
    33  // Hooks is a struct containing function pointers to callbacks
    34  // used by any execdriver implementation exploiting hooks capabilities
    35  type Hooks struct {
    36  	// PreStart is called before container's CMD/ENTRYPOINT is executed
    37  	PreStart []DriverCallback
    38  	// Start is called after the container's process is full started
    39  	Start DriverCallback
    40  	// PostStop is called after the container process exits
    41  	PostStop []DriverCallback
    42  }
    43  
    44  // Info is driver specific information based on
    45  // processes registered with the driver
    46  type Info interface {
    47  	IsRunning() bool
    48  }
    49  
    50  // Terminal represents a pseudo TTY, it is for when
    51  // using a container interactively.
    52  type Terminal interface {
    53  	io.Closer
    54  	Resize(height, width int) error
    55  }
    56  
    57  // ExitStatus provides exit reasons for a container.
    58  type ExitStatus struct {
    59  	// The exit code with which the container exited.
    60  	ExitCode int
    61  
    62  	// Whether the container encountered an OOM.
    63  	OOMKilled bool
    64  }
    65  
    66  // Driver is an interface for drivers to implement
    67  // including all basic functions a driver should have
    68  type Driver interface {
    69  	// Run executes the process, blocks until the process exits and returns
    70  	// the exit code. It's the last stage on Docker side for running a container.
    71  	Run(c *Command, pipes *Pipes, hooks Hooks) (ExitStatus, error)
    72  
    73  	// Exec executes the process in an existing container, blocks until the
    74  	// process exits and returns the exit code.
    75  	Exec(c *Command, processConfig *ProcessConfig, pipes *Pipes, hooks Hooks) (int, error)
    76  
    77  	// Kill sends signals to process in container.
    78  	Kill(c *Command, sig int) error
    79  
    80  	// Pause pauses a container.
    81  	Pause(c *Command) error
    82  
    83  	// Unpause unpauses a container.
    84  	Unpause(c *Command) error
    85  
    86  	// Name returns the name of the driver.
    87  	Name() string
    88  
    89  	// Info returns the configuration stored in the driver struct,
    90  	// "temporary" hack (until we move state from core to plugins).
    91  	Info(id string) Info
    92  
    93  	// GetPidsForContainer returns a list of pid for the processes running in a container.
    94  	GetPidsForContainer(id string) ([]int, error)
    95  
    96  	// Terminate kills a container by sending signal SIGKILL.
    97  	Terminate(c *Command) error
    98  
    99  	// Clean removes all traces of container exec.
   100  	Clean(id string) error
   101  
   102  	// Stats returns resource stats for a running container
   103  	Stats(id string) (*ResourceStats, error)
   104  
   105  	// SupportsHooks refers to the driver capability to exploit pre/post hook functionality
   106  	SupportsHooks() bool
   107  }
   108  
   109  // Ipc settings of the container
   110  // It is for IPC namespace setting. Usually different containers
   111  // have their own IPC namespace, however this specifies to use
   112  // an existing IPC namespace.
   113  // You can join the host's or a container's IPC namespace.
   114  type Ipc struct {
   115  	ContainerID string `json:"container_id"` // id of the container to join ipc.
   116  	HostIpc     bool   `json:"host_ipc"`
   117  }
   118  
   119  // Pid settings of the container
   120  // It is for PID namespace setting. Usually different containers
   121  // have their own PID namespace, however this specifies to use
   122  // an existing PID namespace.
   123  // Joining the host's PID namespace is currently the only supported
   124  // option.
   125  type Pid struct {
   126  	HostPid bool `json:"host_pid"`
   127  }
   128  
   129  // UTS settings of the container
   130  // It is for UTS namespace setting. Usually different containers
   131  // have their own UTS namespace, however this specifies to use
   132  // an existing UTS namespace.
   133  // Joining the host's UTS namespace is currently the only supported
   134  // option.
   135  type UTS struct {
   136  	HostUTS bool `json:"host_uts"`
   137  }
   138  
   139  // Resources contains all resource configs for a driver.
   140  // Currently these are all for cgroup configs.
   141  // TODO Windows: Factor out ulimit.Rlimit
   142  type Resources struct {
   143  	Memory           int64            `json:"memory"`
   144  	MemorySwap       int64            `json:"memory_swap"`
   145  	KernelMemory     int64            `json:"kernel_memory"`
   146  	CPUShares        int64            `json:"cpu_shares"`
   147  	CpusetCpus       string           `json:"cpuset_cpus"`
   148  	CpusetMems       string           `json:"cpuset_mems"`
   149  	CPUPeriod        int64            `json:"cpu_period"`
   150  	CPUQuota         int64            `json:"cpu_quota"`
   151  	BlkioWeight      int64            `json:"blkio_weight"`
   152  	Rlimits          []*ulimit.Rlimit `json:"rlimits"`
   153  	OomKillDisable   bool             `json:"oom_kill_disable"`
   154  	MemorySwappiness int64            `json:"memory_swappiness"`
   155  }
   156  
   157  // ResourceStats contains information about resource usage by a container.
   158  type ResourceStats struct {
   159  	*libcontainer.Stats
   160  	Read        time.Time `json:"read"`
   161  	MemoryLimit int64     `json:"memory_limit"`
   162  	SystemUsage uint64    `json:"system_usage"`
   163  }
   164  
   165  // Mount contains information for a mount operation.
   166  type Mount struct {
   167  	Source      string `json:"source"`
   168  	Destination string `json:"destination"`
   169  	Writable    bool   `json:"writable"`
   170  	Private     bool   `json:"private"`
   171  	Slave       bool   `json:"slave"`
   172  }
   173  
   174  // ProcessConfig describes a process that will be run inside a container.
   175  type ProcessConfig struct {
   176  	exec.Cmd `json:"-"`
   177  
   178  	Privileged  bool     `json:"privileged"`
   179  	User        string   `json:"user"`
   180  	Tty         bool     `json:"tty"`
   181  	Entrypoint  string   `json:"entrypoint"`
   182  	Arguments   []string `json:"arguments"`
   183  	Terminal    Terminal `json:"-"` // standard or tty terminal
   184  	Console     string   `json:"-"` // dev/console path
   185  	ConsoleSize [2]int   `json:"-"` // h,w of initial console size
   186  }
   187  
   188  // Command wrapps an os/exec.Cmd to add more metadata
   189  //
   190  // TODO Windows: Factor out unused fields such as LxcConfig, AppArmorProfile,
   191  // and CgroupParent.
   192  type Command struct {
   193  	ID                 string            `json:"id"`
   194  	Rootfs             string            `json:"rootfs"` // root fs of the container
   195  	ReadonlyRootfs     bool              `json:"readonly_rootfs"`
   196  	InitPath           string            `json:"initpath"` // dockerinit
   197  	WorkingDir         string            `json:"working_dir"`
   198  	ConfigPath         string            `json:"config_path"` // this should be able to be removed when the lxc template is moved into the driver
   199  	Network            *Network          `json:"network"`
   200  	Ipc                *Ipc              `json:"ipc"`
   201  	Pid                *Pid              `json:"pid"`
   202  	UTS                *UTS              `json:"uts"`
   203  	Resources          *Resources        `json:"resources"`
   204  	Mounts             []Mount           `json:"mounts"`
   205  	AllowedDevices     []*configs.Device `json:"allowed_devices"`
   206  	AutoCreatedDevices []*configs.Device `json:"autocreated_devices"`
   207  	CapAdd             []string          `json:"cap_add"`
   208  	CapDrop            []string          `json:"cap_drop"`
   209  	GroupAdd           []string          `json:"group_add"`
   210  	ContainerPid       int               `json:"container_pid"`  // the pid for the process inside a container
   211  	ProcessConfig      ProcessConfig     `json:"process_config"` // Describes the init process of the container.
   212  	ProcessLabel       string            `json:"process_label"`
   213  	MountLabel         string            `json:"mount_label"`
   214  	LxcConfig          []string          `json:"lxc_config"`
   215  	AppArmorProfile    string            `json:"apparmor_profile"`
   216  	CgroupParent       string            `json:"cgroup_parent"` // The parent cgroup for this command.
   217  	FirstStart         bool              `json:"first_start"`
   218  	LayerPaths         []string          `json:"layer_paths"` // Windows needs to know the layer paths and folder for a command
   219  	LayerFolder        string            `json:"layer_folder"`
   220  }