1 // Package libcontainer provides a native Go implementation for creating containers 2 // with namespaces, cgroups, capabilities, and filesystem access controls. 3 // It allows you to manage the lifecycle of the container performing additional operations 4 // after the container is created. 5 package libcontainer 6 7 import ( 8 "os" 9 "time" 10 11 "github.com/opencontainers/runc/libcontainer/configs" 12 "github.com/opencontainers/runtime-spec/specs-go" 13 ) 14 15 // Status is the status of a container. 16 type Status int 17 18 const ( 19 // Created is the status that denotes the container exists but has not been run yet. 20 Created Status = iota 21 // Running is the status that denotes the container exists and is running. 22 Running 23 // Pausing is the status that denotes the container exists, it is in the process of being paused. 24 Pausing 25 // Paused is the status that denotes the container exists, but all its processes are paused. 26 Paused 27 // Stopped is the status that denotes the container does not have a created or running process. 28 Stopped 29 ) 30 31 func (s Status) String() string { 32 switch s { 33 case Created: 34 return "created" 35 case Running: 36 return "running" 37 case Pausing: 38 return "pausing" 39 case Paused: 40 return "paused" 41 case Stopped: 42 return "stopped" 43 default: 44 return "unknown" 45 } 46 } 47 48 // BaseState represents the platform agnostic pieces relating to a 49 // running container's state 50 type BaseState struct { 51 // ID is the container ID. 52 ID string `json:"id"` 53 54 // InitProcessPid is the init process id in the parent namespace. 55 InitProcessPid int `json:"init_process_pid"` 56 57 // InitProcessStartTime is the init process start time in clock cycles since boot time. 58 InitProcessStartTime uint64 `json:"init_process_start"` 59 60 // Created is the unix timestamp for the creation time of the container in UTC 61 Created time.Time `json:"created"` 62 63 // Config is the container's configuration. 64 Config configs.Config `json:"config"` 65 } 66 67 // BaseContainer is a libcontainer container object. 68 // 69 // Each container is thread-safe within the same process. Since a container can 70 // be destroyed by a separate process, any function may return that the container 71 // was not found. BaseContainer includes methods that are platform agnostic. 72 type BaseContainer interface { 73 // Returns the ID of the container 74 ID() string 75 76 // Returns the current status of the container. 77 Status() (Status, error) 78 79 // State returns the current container's state information. 80 State() (*State, error) 81 82 // OCIState returns the current container's state information. 83 OCIState() (*specs.State, error) 84 85 // Returns the current config of the container. 86 Config() configs.Config 87 88 // Returns the PIDs inside this container. The PIDs are in the namespace of the calling process. 89 // 90 // Some of the returned PIDs may no longer refer to processes in the Container, unless 91 // the Container state is PAUSED in which case every PID in the slice is valid. 92 Processes() ([]int, error) 93 94 // Returns statistics for the container. 95 Stats() (*Stats, error) 96 97 // Set resources of container as configured 98 // 99 // We can use this to change resources when containers are running. 100 // 101 Set(config configs.Config) error 102 103 // Start a process inside the container. Returns error if process fails to 104 // start. You can track process lifecycle with passed Process structure. 105 Start(process *Process) (err error) 106 107 // Run immediately starts the process inside the container. Returns error if process 108 // fails to start. It does not block waiting for the exec fifo after start returns but 109 // opens the fifo after start returns. 110 Run(process *Process) (err error) 111 112 // Destroys the container, if its in a valid state, after killing any 113 // remaining running processes. 114 // 115 // Any event registrations are removed before the container is destroyed. 116 // No error is returned if the container is already destroyed. 117 // 118 // Running containers must first be stopped using Signal(..). 119 // Paused containers must first be resumed using Resume(..). 120 Destroy() error 121 122 // Signal sends the provided signal code to the container's initial process. 123 // 124 // If all is specified the signal is sent to all processes in the container 125 // including the initial process. 126 Signal(s os.Signal, all bool) error 127 128 // Exec signals the container to exec the users process at the end of the init. 129 Exec() error 130 } 131