package libcontainer
import "github.com/opencontainers/runc/libcontainer"
Package 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.
Index ¶
- type BaseContainer
- type BaseState
- type Error
- type ErrorCode
- type Factory
- type IO
- type Process
- func (p Process) Pid() (int, error)
- func (p Process) Signal(sig os.Signal) error
- func (p Process) Wait() (*os.ProcessState, error)
- type Status
Types ¶
type BaseContainer ¶
type BaseContainer interface { // Returns the ID of the container ID() string // Returns the current status of the container. // // errors: // ContainerNotExists - Container no longer exists, // Systemerror - System error. Status() (Status, error) // State returns the current container's state information. // // errors: // SystemError - System error. State() (*State, error) // OCIState returns the current container's state information. // // errors: // SystemError - System error. OCIState() (*specs.State, error) // Returns the current config of the container. Config() configs.Config // Returns the PIDs inside this container. The PIDs are in the namespace of the calling process. // // errors: // ContainerNotExists - Container no longer exists, // Systemerror - System error. // // 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. Processes() ([]int, error) // Returns statistics for the container. // // errors: // ContainerNotExists - Container no longer exists, // Systemerror - System error. Stats() (*Stats, error) // Set resources of container as configured // // We can use this to change resources when containers are running. // // errors: // SystemError - System error. Set(config configs.Config) error // Start a process inside the container. Returns error if process fails to // start. You can track process lifecycle with passed Process structure. // // errors: // ContainerNotExists - Container no longer exists, // ConfigInvalid - config is invalid, // ContainerPaused - Container is paused, // SystemError - System error. Start(process *Process) (err error) // Run immediately starts the process inside the container. Returns error if process // fails to start. It does not block waiting for the exec fifo after start returns but // opens the fifo after start returns. // // errors: // ContainerNotExists - Container no longer exists, // ConfigInvalid - config is invalid, // ContainerPaused - Container is paused, // SystemError - System error. Run(process *Process) (err error) // Destroys the container, if its in a valid state, after killing any // remaining running processes. // // 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(..). // // errors: // ContainerNotStopped - Container is still running, // ContainerPaused - Container is paused, // SystemError - System error. Destroy() error // Signal sends the provided signal code to the container's initial process. // // If all is specified the signal is sent to all processes in the container // including the initial process. // // errors: // SystemError - System error. Signal(s os.Signal, all bool) error // Exec signals the container to exec the users process at the end of the init. // // errors: // SystemError - System error. Exec() error }
BaseContainer is 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. BaseContainer includes methods that are platform agnostic.
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 Error ¶
type Error interface { error // Returns an error if it failed to write the detail of the Error to w. // The detail of the Error may include the error message and a // representation of the stack trace. Detail(w io.Writer) error // Returns the error code for this error. Code() ErrorCode }
Error is the API error type.
type ErrorCode ¶
type ErrorCode int
ErrorCode is the API error code type.
const ( // Factory errors IdInUse ErrorCode = iota InvalidIdFormat // Container errors ContainerNotExists ContainerPaused ContainerNotStopped ContainerNotRunning ContainerNotPaused // Process errors NoProcessOps // Common errors ConfigInvalid ConsoleExists SystemError )
API error codes.
func (ErrorCode) String ¶
type Factory ¶
type Factory interface { // Creates a new container with the given id and starts the initial process inside it. // id must be a string containing only letters, digits and underscores and must contain // between 1 and 1024 characters, inclusive. // // The id must not already be in use by an existing container. Containers created using // a factory with the same path (and filesystem) must have distinct ids. // // Returns the new container with a running process. // // errors: // IdInUse - id is already in use by a container // InvalidIdFormat - id has incorrect format // ConfigInvalid - config is invalid // Systemerror - System error // // On error, any partially created container parts are cleaned up (the operation is atomic). Create(id string, config *configs.Config) (Container, error) // Load takes an ID for an existing container and returns the container information // from the state. This presents a read only view of the container. // // errors: // Path does not exist // System error Load(id string) (Container, error) // StartInitialization is an internal API to libcontainer used during the reexec of the // container. // // Errors: // Pipe connection error // System error StartInitialization() error // Type returns info string about factory type (e.g. lxc, libcontainer...) Type() string }
type IO ¶
type IO struct { Stdin io.WriteCloser Stdout io.ReadCloser Stderr io.ReadCloser }
IO holds the process's STDIO
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 // User will set the uid and gid of the executing process running inside the container // local to the container's user and group configuration. User string // AdditionalGroups specifies the gids that should be added to supplementary groups // in addition to those that the user belongs to. AdditionalGroups []string // Cwd will change the processes current working directory inside the container's rootfs. Cwd 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 // Initial sizings for the console ConsoleWidth uint16 ConsoleHeight uint16 // Capabilities specify the capabilities to keep when executing the process inside the container // All capabilities not specified will be dropped from the processes capability mask Capabilities *configs.Capabilities // 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 // NoNewPrivileges controls whether processes can gain additional privileges. NoNewPrivileges *bool // Rlimits specifies the resource limits, such as max open files, to set in the container // If Rlimits are not set, the container will inherit rlimits from the parent process Rlimits []configs.Rlimit // ConsoleSocket provides the masterfd console. ConsoleSocket *os.File // Init specifies whether the process is the first process in the container. Init bool LogLevel string // contains filtered or unexported fields }
Process specifies the configuration and IO for a process inside a container.
func (Process) Pid ¶
Pid returns the process ID
func (Process) Signal ¶
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 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 // Pausing is the status that denotes the container exists, it is in the process of being paused. Pausing // Paused is the status that denotes the container exists, but all its processes are paused. Paused // Stopped is the status that denotes the container does not have a created or running process. Stopped )
func (Status) String ¶
Source Files ¶
container.go error.go factory.go generic_error.go process.go sync.go
Directories ¶
Path | Synopsis |
---|---|
libcontainer/apparmor | |
libcontainer/capabilities | |
libcontainer/cgroups | |
libcontainer/cgroups/devices | |
libcontainer/cgroups/ebpf | |
libcontainer/cgroups/ebpf/devicefilter | Package devicefilter contains eBPF device filter program |
libcontainer/cgroups/fs | |
libcontainer/cgroups/fs2 | |
libcontainer/cgroups/systemd | |
libcontainer/configs | |
libcontainer/configs/validate | |
libcontainer/devices | |
libcontainer/integration | integration is used for integration testing of libcontainer |
libcontainer/intelrdt | |
libcontainer/logs | |
libcontainer/nsenter | |
libcontainer/nsenter/test | |
libcontainer/seccomp | |
libcontainer/seccomp/patchbpf | |
libcontainer/specconv | |
libcontainer/stacktrace | |
libcontainer/system | |
libcontainer/user | |
libcontainer/userns | |
libcontainer/utils |
- Version
- v1.0.0
- Published
- Jun 17, 2021
- Platform
- js/wasm
- Imports
- 12 packages
- Last checked
- 3 hours ago –
Tools for package owners.