8
"github.com/containers/common/pkg/resize"
9
"github.com/containers/podman/v5/libpod/define"
10
"github.com/opencontainers/runtime-spec/specs-go"
13
// OCIRuntime is an implementation of an OCI runtime.
14
// The OCI runtime implementation is expected to be a fairly thin wrapper around
15
// the actual runtime, and is not expected to include things like state
16
// management logic - e.g., we do not expect it to determine on its own that
17
// calling 'UnpauseContainer()' on a container that is not paused is an error.
18
// The code calling the OCIRuntime will manage this.
19
// TODO: May want to move the conmon cleanup code here - it depends on
20
// Conmon being in use.
21
type OCIRuntime interface { //nolint:interfacebloat22
// Name returns the name of the runtime.
24
// Path returns the path to the runtime executable.
27
// CreateContainer creates the container in the OCI runtime.
28
// The returned int64 contains the microseconds needed to restore
29
// the given container if it is a restore and if restoreOptions.PrintStats
30
// is true. In all other cases the returned int64 is 0.
31
CreateContainer(ctr *Container, restoreOptions *ContainerCheckpointOptions) (int64, error)
32
// UpdateContainerStatus updates the status of the given container.
33
UpdateContainerStatus(ctr *Container) error
34
// StartContainer starts the given container.
35
StartContainer(ctr *Container) error
36
// KillContainer sends the given signal to the given container.
37
// If all is set, all processes in the container will be signalled;
38
// otherwise, only init will be signalled.
39
KillContainer(ctr *Container, signal uint, all bool) error
40
// StopContainer stops the given container.
41
// The container's stop signal (or SIGTERM if unspecified) will be sent
43
// After the given timeout, SIGKILL will be sent.
44
// If the given timeout is 0, SIGKILL will be sent immediately, and the
45
// stop signal will be omitted.
46
// If all is set, we will attempt to use the --all flag will `kill` in
47
// the OCI runtime to kill all processes in the container, including
48
// exec sessions. This is only supported if the container has cgroups.
49
StopContainer(ctr *Container, timeout uint, all bool) error
50
// DeleteContainer deletes the given container from the OCI runtime.
51
DeleteContainer(ctr *Container) error
52
// PauseContainer pauses the given container.
53
PauseContainer(ctr *Container) error
54
// UnpauseContainer unpauses the given container.
55
UnpauseContainer(ctr *Container) error
57
// Attach to a container.
58
Attach(ctr *Container, params *AttachOptions) error
59
// HTTPAttach performs an attach intended to be transported over HTTP.
60
// For terminal attach, the container's output will be directly streamed
61
// to output; otherwise, STDOUT and STDERR will be multiplexed, with
62
// a header prepended as follows: 1-byte STREAM (0, 1, 2 for STDIN,
63
// STDOUT, STDERR), 3 null (0x00) bytes, 4-byte big endian length.
64
// If a cancel channel is provided, it can be used to asynchronously
65
// terminate the attach session. Detach keys, if given, will also cause
66
// the attach session to be terminated if provided via the STDIN
67
// channel. If they are not provided, the default detach keys will be
68
// used instead. Detach keys of "" will disable detaching via keyboard.
69
// The streams parameter will determine which streams to forward to the
71
HTTPAttach(ctr *Container, r *http.Request, w http.ResponseWriter, streams *HTTPAttachStreams, detachKeys *string, cancel <-chan bool, hijackDone chan<- bool, streamAttach, streamLogs bool) error
72
// AttachResize resizes the terminal in use by the given container.
73
AttachResize(ctr *Container, newSize resize.TerminalSize) error
75
// ExecContainer executes a command in a running container.
76
// Returns an int (PID of exec session), error channel (errors from
77
// attach), and error (errors that occurred attempting to start the exec
78
// session). This returns once the exec session is running - not once it
79
// has completed, as one might expect. The attach session will remain
80
// running, in a goroutine that will return via the chan error in the
82
// newSize resizes the tty to this size before the process is started, must be nil if the exec session has no tty
83
ExecContainer(ctr *Container, sessionID string, options *ExecOptions, streams *define.AttachStreams, newSize *resize.TerminalSize) (int, chan error, error)
84
// ExecContainerHTTP executes a command in a running container and
85
// attaches its standard streams to a provided hijacked HTTP session.
86
// Maintains the same invariants as ExecContainer (returns on session
87
// start, with a goroutine running in the background to handle attach).
88
// The HTTP attach itself maintains the same invariants as HTTPAttach.
89
// newSize resizes the tty to this size before the process is started, must be nil if the exec session has no tty
90
ExecContainerHTTP(ctr *Container, sessionID string, options *ExecOptions, r *http.Request, w http.ResponseWriter,
91
streams *HTTPAttachStreams, cancel <-chan bool, hijackDone chan<- bool, holdConnOpen <-chan bool, newSize *resize.TerminalSize) (int, chan error, error)
92
// ExecContainerDetached executes a command in a running container, but
93
// does not attach to it. Returns the PID of the exec session and an
94
// error (if starting the exec session failed)
95
ExecContainerDetached(ctr *Container, sessionID string, options *ExecOptions, stdin bool) (int, error)
96
// ExecAttachResize resizes the terminal of a running exec session. Only
97
// allowed with sessions that were created with a TTY.
98
ExecAttachResize(ctr *Container, sessionID string, newSize resize.TerminalSize) error
99
// ExecStopContainer stops a given exec session in a running container.
100
// SIGTERM with be sent initially, then SIGKILL after the given timeout.
101
// If timeout is 0, SIGKILL will be sent immediately, and SIGTERM will
103
ExecStopContainer(ctr *Container, sessionID string, timeout uint) error
104
// ExecUpdateStatus checks the status of a given exec session.
105
// Returns true if the session is still running, or false if it exited.
106
ExecUpdateStatus(ctr *Container, sessionID string) (bool, error)
108
// CheckpointContainer checkpoints the given container.
109
// Some OCI runtimes may not support this - if SupportsCheckpoint()
110
// returns false, this is not implemented, and will always return an
111
// error. If CheckpointOptions.PrintStats is true the first return parameter
112
// contains the number of microseconds the runtime needed to checkpoint
113
// the given container.
114
CheckpointContainer(ctr *Container, options ContainerCheckpointOptions) (int64, error)
116
// CheckConmonRunning verifies that the given container's Conmon
117
// instance is still running. Runtimes without Conmon, or systems where
118
// the PID of conmon is not available, should mock this as True.
119
// True indicates that Conmon for the instance is running, False
120
// indicates it is not.
121
CheckConmonRunning(ctr *Container) (bool, error)
123
// SupportsCheckpoint returns whether this OCI runtime
124
// implementation supports the CheckpointContainer() operation.
125
SupportsCheckpoint() bool
126
// SupportsJSONErrors is whether the runtime can return JSON-formatted
128
SupportsJSONErrors() bool
129
// SupportsNoCgroups is whether the runtime supports running containers
131
SupportsNoCgroups() bool
132
// SupportsKVM os whether the OCI runtime supports running containers
133
// without KVM separation
136
// AttachSocketPath is the path to the socket to attach to a given
138
// TODO: If we move Attach code in here, this should be made internal.
139
// We don't want to force all runtimes to share the same attach
141
AttachSocketPath(ctr *Container) (string, error)
142
// ExecAttachSocketPath is the path to the socket to attach to a given
143
// exec session in the given container.
144
// TODO: Probably should be made internal.
145
ExecAttachSocketPath(ctr *Container, sessionID string) (string, error)
146
// ExitFilePath is the path to a container's exit file.
147
// All runtime implementations must create an exit file when containers
148
// exit, containing the exit code of the container (as a string).
149
// This is the path to that file for a given container.
150
ExitFilePath(ctr *Container) (string, error)
152
// OOMFilePath is the path to a container's oom file if it was oom killed.
153
// An oom file is only created when the container is oom killed. The existence
154
// of this file means that the container was oom killed.
155
// This is the path to that file for a given container.
156
OOMFilePath(ctr *Container) (string, error)
158
// RuntimeInfo returns verbose information about the runtime.
159
RuntimeInfo() (*define.ConmonInfo, *define.OCIRuntimeInfo, error)
161
// UpdateContainer updates the given container's cgroup configuration.
162
UpdateContainer(ctr *Container, res *specs.LinuxResources) error
165
// AttachOptions are options used when attached to a container or an exec
167
type AttachOptions struct {168
// Streams are the streams to attach to.
169
Streams *define.AttachStreams
170
// DetachKeys containers the key combination that will detach from the
171
// attach session. Empty string is assumed as no detach keys - user
172
// detach is impossible. If unset, defaults from containers.conf will be
175
// InitialSize is the initial size of the terminal. Set before the
177
InitialSize *resize.TerminalSize
178
// AttachReady signals when the attach has successfully completed and
179
// streaming has begun.
180
AttachReady chan<- bool
181
// Start indicates that the container should be started if it is not
184
// Started signals when the container has been successfully started.
185
// Required if Start is true, unused otherwise.
189
// ExecOptions are options passed into ExecContainer. They control the command
190
// that will be executed and how the exec will proceed.
191
type ExecOptions struct {192
// Cmd is the command to execute.
194
// Env is a set of environment variables to add to the container.
195
Env map[string]string
196
// Terminal is whether to create a new TTY for the exec session.
198
// Cwd is the working directory for the executed command. If unset, the
199
// working directory of the container will be used.
201
// User is the user the command will be executed as. If unset, the user
202
// the container was run as will be used.
204
// Streams are the streams that will be attached to the container.
205
Streams *define.AttachStreams
206
// PreserveFDs is a number of additional file descriptors (in addition
207
// to 0, 1, 2) that will be passed to the executed process. The total FDs
208
// passed will be 3 + PreserveFDs.
210
// PreserveFD is a list of additional file descriptors (in addition
211
// to 0, 1, 2) that will be passed to the executed process.
213
// DetachKeys is a set of keys that, when pressed in sequence, will
214
// detach from the container.
215
// If not provided, the default keys will be used.
216
// If provided but set to "", detaching from the container will be
219
// ExitCommand is a command that will be run after the exec session
222
// ExitCommandDelay is a delay (in seconds) between the exec session
223
// exiting, and the exit command being invoked.
224
ExitCommandDelay uint
225
// Privileged indicates the execed process will be launched in Privileged mode
229
// HTTPAttachStreams informs the HTTPAttach endpoint which of the container's
230
// standard streams should be streamed to the client. If this is passed, at
231
// least one of the streams must be set to true.
232
type HTTPAttachStreams struct {