Documentation
¶
Overview ¶
Package control contains types that expose control server methods, and can be used to configure and interact with a running sandbox process.
Index ¶
- Variables
- func ConfigureSaveRestoreExec(k *kernel.Kernel, argv []string, timeout time.Duration, containerID string) error
- func ContainerUsage(kr *kernel.Kernel) map[string]uint64
- func ConvertToStateSaveOpts(o *controlapi.SaveOpts) (*state.SaveOpts, error)
- func ExecAsync(proc *Proc, args *ExecArgs) (*kernel.ThreadGroup, kernel.ThreadID, *host.TTYFileDescription, error)
- func PostRestore(k *kernel.Kernel, timeline *timing.Timeline) error
- func PostResume(k *kernel.Kernel, timeline *timing.Timeline) error
- func Processes(k *kernel.Kernel, containerID string, out *[]*controlapi.Process) error
- func SaveRestoreExec(k *kernel.Kernel, mode SaveRestoreExecMode) error
- type CatOpts
- type Cgroups
- type Container
- type ContainerArgs
- type ContainerNamespaces
- type Events
- type EventsOpts
- type ExecArgs
- type Fs
- type GetRegisteredMetricsOpts
- type Lifecycle
- func (l *Lifecycle) GetExitStatus(args *ContainerArgs, status *uint32) error
- func (l *Lifecycle) IsContainerRunning(args *ContainerArgs, isRunning *bool) error
- func (l *Lifecycle) Pause(*ContainerArgs, *struct{}) error
- func (l *Lifecycle) PauseExternalNetworking(*ContainerArgs, *struct{}) error
- func (l *Lifecycle) Reap(args *ContainerArgs, _ *struct{}) error
- func (l *Lifecycle) Resume(*ContainerArgs, *struct{}) error
- func (l *Lifecycle) ResumeExternalNetworking(*ContainerArgs, *struct{}) error
- func (l *Lifecycle) Shutdown(_, _ *struct{}) error
- func (l *Lifecycle) SignalContainer(args *SignalContainerArgs, _ *struct{}) error
- func (l *Lifecycle) StartContainer(args *StartContainerArgs, _ *uint32) error
- type Logging
- type Metrics
- type MountOpts
- type Proc
- type Profile
- func (p *Profile) Block(o *controlapi.BlockProfileOpts, _ *struct{}) error
- func (p *Profile) CPU(o *controlapi.CPUProfileOpts, _ *struct{}) error
- func (p *Profile) Goroutine(o *controlapi.GoroutineProfileOpts, _ *struct{}) error
- func (p *Profile) Heap(o *controlapi.HeapProfileOpts, _ *struct{}) error
- func (p *Profile) Mutex(o *controlapi.MutexProfileOpts, _ *struct{}) error
- func (p *Profile) Stop()
- func (p *Profile) Trace(o *controlapi.TraceProfileOpts, _ *struct{}) error
- type PsArgs
- type ReadOpts
- type SaveRestoreExecMode
- type SignalContainerArgs
- type SignalProcessArgs
- type StartContainerArgs
- type State
- type UmountOpts
- type Usage
- func (u *Usage) Collect(opts *controlapi.MemoryUsageOpts, out *controlapi.MemoryUsage) error
- func (*Usage) GetFileIoStats(_ *struct{}, out *string) error
- func (u *Usage) Reduce(opts *UsageReduceOpts, out *UsageReduceOutput) error
- func (u *Usage) UsageFD(opts *controlapi.MemoryUsageFileOpts, out *controlapi.MemoryUsageFile) error
- type UsageReduceOpts
- type UsageReduceOutput
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidFiles = errors.New("exactly one file must be provided")
ErrInvalidFiles is returned when the urpc call to Save does not include an appropriate file payload (e.g. there is no output file!).
Functions ¶
func ConfigureSaveRestoreExec ¶
func ConfigureSaveRestoreExec(k *kernel.Kernel, argv []string, timeout time.Duration, containerID string) error
ConfigureSaveRestoreExec sets the configuration for the save/restore binary. If containerID is empty, the global init process will be used for the save/restore binary's leader task.
A previously stored configuration is replaced: a sandbox may be checkpointed repeatedly, and the configuration also survives in the kernel state across a restore. The leader task is always resolved anew, since a task stored by an earlier call may have exited.
func ContainerUsage ¶
ContainerUsage retrieves per-container CPU usage.
func ConvertToStateSaveOpts ¶
func ConvertToStateSaveOpts(o *controlapi.SaveOpts) (*state.SaveOpts, error)
ConvertToStateSaveOpts converts a control.SaveOpts to a state.SaveOpts. state.SaveOpts.Close() must be called when the state.SaveOpts is no longer needed.
func ExecAsync ¶
func ExecAsync(proc *Proc, args *ExecArgs) (*kernel.ThreadGroup, kernel.ThreadID, *host.TTYFileDescription, error)
ExecAsync runs a new task, but doesn't wait for it to finish. It is defined as a function rather than a method to avoid exposing execAsync as an RPC.
func PostRestore ¶
PostRestore is called after restoring the kernel.
Precondition: The kernel should be running.
func PostResume ¶
PostResume is called after resuming the kernel.
Precondition: The kernel should be running.
func Processes ¶
Processes retrieves information about processes running in the sandbox with the given container id. All processes are returned if 'containerID' is empty.
func SaveRestoreExec ¶
func SaveRestoreExec(k *kernel.Kernel, mode SaveRestoreExecMode) error
SaveRestoreExec creates a new process that executes the save/restore binary specified by k.SaveRestoreExecConfig and waits for it to finish.
Precondition: The kernel should be running; k.SetSaveRestoreExecConfig should be setup with an argv, otherwise this function is a no-op.
Types ¶
type CatOpts ¶
type CatOpts struct {
// Files are the filesystem paths for the files to cat.
Files []string `json:"files"`
// FilePayload contains the destination for output.
urpc.FilePayload
}
CatOpts contains options for the Cat RPC call.
type Cgroups ¶
Cgroups contains the state for cgroupfs related control commands.
func (*Cgroups) ReadControlFiles ¶
func (c *Cgroups) ReadControlFiles(args *controlapi.CgroupsReadArgs, out *controlapi.CgroupsResults) error
ReadControlFiles is an RPC stub for batch-reading cgroupfs control files.
func (*Cgroups) WriteControlFiles ¶
func (c *Cgroups) WriteControlFiles(args *controlapi.CgroupsWriteArgs, out *controlapi.CgroupsResults) error
WriteControlFiles is an RPC stub for batch-writing cgroupfs control files.
type Container ¶
type Container struct {
// contains filtered or unexported fields
}
Container contains the set of parameters to represent a container.
type ContainerArgs ¶
type ContainerArgs struct {
ContainerID string `json:"container_id"`
}
ContainerArgs is the set of arguments for container related APIs after starting the container.
type ContainerNamespaces ¶
type ContainerNamespaces struct {
MountNamespace *vfs.MountNamespace
PIDNamespace *kernel.PIDNamespace
CgroupNamespace *kernel.CgroupNamespace
}
ContainerNamespaces holds container namespaces that are constructed before StartContainer.
type Events ¶
type Events struct {
// contains filtered or unexported fields
}
Events is the control server state for eventchannel-related commands.
func (*Events) AttachDebugEmitter ¶
func (e *Events) AttachDebugEmitter(o *EventsOpts, _ *struct{}) error
AttachDebugEmitter receives a connected unix domain socket FD from the client and establishes it as a new emitter for the sentry eventchannel. Any existing emitters are replaced on a subsequent attach.
type EventsOpts ¶
type EventsOpts struct {
urpc.FilePayload
}
EventsOpts are the arguments for eventchannel-related commands.
type ExecArgs ¶
type ExecArgs struct {
controlapi.ExecArgs
// MountNamespace is the mount namespace to execute the new process in.
// A reference on MountNamespace must be held for the lifetime of the
// ExecArgs. If MountNamespace is nil, it will default to the init
// process's MountNamespace.
MountNamespace *vfs.MountNamespace
// If FDTable is not nil, it is the process FD table. If Exec/ExecAsync
// succeeds, it takes a reference on FDTable.
FDTable *kernel.FDTable
// PIDNamespace is the pid namespace for the process being executed.
PIDNamespace *kernel.PIDNamespace
// InitialCgroupV2 is the cgroup2 node the process being executed starts
// in. If nil, it starts in the root cgroup.
InitialCgroupV2 kernel.Cgroup2
// CgroupNamespace is the cgroup namespace for the process being executed.
// If nil, the root cgroup namespace is used. A reference on
// CgroupNamespace must be held for the lifetime of the ExecArgs.
CgroupNamespace *kernel.CgroupNamespace
// Limits is the limit set for the process being executed.
Limits *limits.LimitSet
// SeccompFilter is an optional seccomp filter to install on the new
// process.
SeccompFilter *kernel.SyscallFilter
}
ExecArgs is the set of arguments to exec.
type Fs ¶
Fs includes fs-related functions.
func (*Fs) Mount ¶
Mount is a RPC stub which mounts a filesystem into a container's mount namespace.
func (*Fs) Read ¶
Read is a RPC stub which prints out and returns the content of the file up to the specified size.
func (*Fs) TarRootfsUpperLayer ¶
func (f *Fs) TarRootfsUpperLayer(o *controlapi.TarRootfsUpperLayerOpts, _ *struct{}) error
TarRootfsUpperLayer is a RPC stub which serializes the rootfs upper layer to a tar file. When the rootfs is not an overlayfs, it returns an error.
func (*Fs) Umount ¶
func (f *Fs) Umount(o *UmountOpts, _ *struct{}) error
Umount is a RPC stub which unmounts a filesystem from a container's mount namespace.
type GetRegisteredMetricsOpts ¶
type GetRegisteredMetricsOpts struct{}
GetRegisteredMetricsOpts contains metric registration query options.
type Lifecycle ¶
type Lifecycle struct {
// Kernel is the kernel where the tasks belong to.
Kernel *kernel.Kernel
// ShutdownCh is the channel used to signal the sentry to shutdown
// the sentry/sandbox.
//
// +checklocks:mu
ShutdownCh chan struct{}
// ContainerNamespacesMap maps container IDs to namespaces.
//
// +checklocks:mu
ContainerNamespacesMap map[string]ContainerNamespaces
// contains filtered or unexported fields
}
Lifecycle provides functions related to starting and stopping tasks.
func (*Lifecycle) GetExitStatus ¶
func (l *Lifecycle) GetExitStatus(args *ContainerArgs, status *uint32) error
GetExitStatus returns the container exit status if it has stopped.
+checklocksexclude:l.mu
func (*Lifecycle) IsContainerRunning ¶
func (l *Lifecycle) IsContainerRunning(args *ContainerArgs, isRunning *bool) error
IsContainerRunning returns true if the container is running.
+checklocksexclude:l.mu
func (*Lifecycle) Pause ¶
func (l *Lifecycle) Pause(*ContainerArgs, *struct{}) error
Pause pauses the container.
func (*Lifecycle) PauseExternalNetworking ¶
func (l *Lifecycle) PauseExternalNetworking(*ContainerArgs, *struct{}) error
PauseExternalNetworking pauses external networking for the container.
func (*Lifecycle) Reap ¶
func (l *Lifecycle) Reap(args *ContainerArgs, _ *struct{}) error
Reap notifies the sandbox that the caller is interested in the exit status via an exit event. The caller is responsible for handling any corresponding exit events, especially if they're interested in waiting for the exit.
+checklocksexclude:l.mu
func (*Lifecycle) Resume ¶
func (l *Lifecycle) Resume(*ContainerArgs, *struct{}) error
Resume resumes the container.
func (*Lifecycle) ResumeExternalNetworking ¶
func (l *Lifecycle) ResumeExternalNetworking(*ContainerArgs, *struct{}) error
ResumeExternalNetworking resumes external networking for the container.
func (*Lifecycle) Shutdown ¶
Shutdown sends signal to destroy the sentry/sandbox.
+checklocksexclude:l.mu
func (*Lifecycle) SignalContainer ¶
func (l *Lifecycle) SignalContainer(args *SignalContainerArgs, _ *struct{}) error
SignalContainer signals the container in multi-container mode. It returns error if the container hasn't started or has exited.
+checklocksexclude:l.mu
func (*Lifecycle) StartContainer ¶
func (l *Lifecycle) StartContainer(args *StartContainerArgs, _ *uint32) error
StartContainer will start a new container in the sandbox.
+checklocksexclude:l.mu
type Logging ¶
type Logging struct{}
Logging provides functions related to logging.
func (*Logging) Change ¶
func (l *Logging) Change(args *controlapi.LoggingArgs, code *int) error
Change will change the log level and strace arguments. Although this functions signature requires an error it never actually returns an error. It's required by the URPC interface. Additionally, it may look odd that this is the only method attached to an empty struct but this is also part of how URPC dispatches.
type Metrics ¶
type Metrics struct{}
Metrics includes metrics-related RPC stubs.
func (*Metrics) Export ¶
func (u *Metrics) Export(opts *controlapi.MetricsExportOpts, out *controlapi.MetricsExportData) error
Export export metrics data into MetricsExportData.
func (*Metrics) GetRegisteredMetrics ¶
func (u *Metrics) GetRegisteredMetrics(_ *GetRegisteredMetricsOpts, out *controlapi.MetricsRegistrationResponse) error
GetRegisteredMetrics sets `out` to the metric registration information. Meant to be called over the control channel, with `out` as return value. This should be called during Sentry boot before any container starts. Metric registration data is used by the processes querying sandbox metrics to ensure the integrity of metrics exported from the untrusted sandbox.
type MountOpts ¶
type MountOpts struct {
// ContainerID identifies which container's mount namespace to mount into.
ContainerID string `json:"container_id"`
// Source is the mount source (e.g. device name or host path).
Source string `json:"source"`
// Target is the absolute path inside the container where the filesystem
// will be mounted.
Target string `json:"target"`
// FSType is the filesystem type name (e.g., "gofer", "tmpfs").
FSType string `json:"fs_type"`
// Flags are the Linux mount flags (e.g. MS_RDONLY, MS_NOEXEC).
Flags uint64 `json:"flags"`
// Data contains filesystem-specific mount options (e.g. "cache=remote,aname=/").
Data string `json:"data"`
// FilePayload contains file descriptors sent over SCM_RIGHTS (e.g. socket FD to Gofer).
urpc.FilePayload
}
MountOpts contains options for the Mount RPC call.
type Proc ¶
Proc includes task-related functions.
func (*Proc) SignalProcess ¶
func (proc *Proc) SignalProcess(args *SignalProcessArgs, _ *struct{}) error
SignalProcess sends a signal to the process with the given PID.
type Profile ¶
type Profile struct {
// contains filtered or unexported fields
}
Profile includes profile-related RPC stubs. It provides a way to control the built-in runtime profiling facilities.
The profile object must be instantied via NewProfile.
func NewProfile ¶
NewProfile returns a new Profile object.
func (*Profile) Block ¶
func (p *Profile) Block(o *controlapi.BlockProfileOpts, _ *struct{}) error
Block dumps a blocking profile.
func (*Profile) CPU ¶
func (p *Profile) CPU(o *controlapi.CPUProfileOpts, _ *struct{}) error
CPU is an RPC stub which collects a CPU profile.
func (*Profile) Goroutine ¶
func (p *Profile) Goroutine(o *controlapi.GoroutineProfileOpts, _ *struct{}) error
Goroutine dumps out the stack trace for all running goroutines.
func (*Profile) Heap ¶
func (p *Profile) Heap(o *controlapi.HeapProfileOpts, _ *struct{}) error
Heap generates a heap profile.
func (*Profile) Mutex ¶
func (p *Profile) Mutex(o *controlapi.MutexProfileOpts, _ *struct{}) error
Mutex dumps a mutex profile.
func (*Profile) Trace ¶
func (p *Profile) Trace(o *controlapi.TraceProfileOpts, _ *struct{}) error
Trace is an RPC stub which starts collection of an execution trace.
type PsArgs ¶
type PsArgs struct {
// JSON will force calls to Ps to return the result as a JSON payload.
JSON bool
}
PsArgs is the set of arguments to ps.
type SaveRestoreExecMode ¶
type SaveRestoreExecMode string
SaveRestoreExecMode is the mode for the save/restore binary.
const ( // SaveRestoreExecSave is the save mode for the save/restore exec. SaveRestoreExecSave SaveRestoreExecMode = "save" // SaveRestoreExecRestore is the restore mode for the save/restore exec. SaveRestoreExecRestore SaveRestoreExecMode = "restore" // SaveRestoreExecResume is the resume mode for the save/restore binary. SaveRestoreExecResume SaveRestoreExecMode = "resume" )
type SignalContainerArgs ¶
type SignalContainerArgs struct {
ContainerID string `json:"container_id"`
Signo int32 `json:"signo"`
SignalAll bool `json:"signalAll"`
}
SignalContainerArgs is the set of arguments for signalling a container.
type SignalProcessArgs ¶
type SignalProcessArgs struct {
// Signal number to send.
Signo int `json:"signo"`
// Process ID (in the root PID namespace) to signal.
PID int `json:"pid"`
}
SignalProcessArgs is the arguments to SignalProcess.
type StartContainerArgs ¶
type StartContainerArgs struct {
// Filename is the filename to load.
//
// If this is provided as "", then the file will be guessed via Argv[0].
Filename string `json:"filename"`
// Argv is a list of arguments.
Argv []string `json:"argv"`
// Envv is a list of environment variables.
Envv []string `json:"envv"`
// Secret_envv is a list of secret environment variables.
//
// NOTE: This field must never be logged!
SecretEnvv []string `json:"secret_envv"`
// WorkingDirectory defines the working directory for the new process.
WorkingDirectory string `json:"wd"`
// KUID is the UID to run with in the root user namespace. Defaults to
// root if not set explicitly.
KUID auth.KUID `json:"KUID"`
// KGID is the GID to run with in the root user namespace. Defaults to
// the root group if not set explicitly.
KGID auth.KGID `json:"KGID"`
// User is the user string used to retrieve UID/GID.
User string `json:"user"`
// ContainerID is the container for the process being executed.
ContainerID string `json:"container_id"`
// InitialCgroups is the set of cgroup controllers container needs to be initialised to.
InitialCgroups map[kernel.CgroupControllerType]string `json:"initial_cgroups"`
// Limits is the limit set for the process being executed.
Limits map[string]limits.Limit `json:"limits"`
// If HOME environment variable is not provided, and this flag is set,
// then the HOME environment variable will be set inside the container
// based on the user's home directory in /etc/passwd.
ResolveHome bool `json:"resolve_home"`
// If set, attempt to resolve the binary_path via the following procedure:
// 1) If binary_path is absolute, it is used directly.
// 2) If binary_path contains a slash, then it is resolved relative to the
// working_directory (or the root it working_directory is not set).
// 3) Otherwise, search the PATH environment variable for the first directory
// that contains an executable file with name in binary_path.
ResolveBinaryPath bool `json:"resolve_binary_path"`
// DonatedFDs is the list of sentry-intrenal file descriptors that will
// donated. They correspond to the donated files in FilePayload.
DonatedFDs []int `json:"donated_fds"`
// FilePayload determines the files to give to the new process.
urpc.FilePayload
}
StartContainerArgs is the set of arguments to start a container.
func (StartContainerArgs) String ¶
func (sca StartContainerArgs) String() string
String formats the StartContainerArgs without the SecretEnvv field.
type State ¶
State includes state-related functions.
func (*State) Save ¶
func (s *State) Save(o *controlapi.SaveOpts, _ *struct{}) (err error)
Save saves the running system.
func (*State) SaveWithOpts ¶
func (s *State) SaveWithOpts(saveOpts *state.SaveOpts, execOpts *controlapi.SaveRestoreExecOpts) error
SaveWithOpts saves the running system with the given options. If saveOpts.Resume is true, the caller must call PostResume afterwards.
type UmountOpts ¶
type UmountOpts struct {
// ContainerID identifies which container's mount namespace to unmount from.
ContainerID string `json:"container_id"`
// Target is the absolute path inside the container to unmount.
Target string `json:"target"`
// Flags are Linux umount2 flags (e.g. MNT_DETACH).
Flags uint32 `json:"flags"`
}
UmountOpts contains options for the Umount RPC call.
type Usage ¶
Usage includes usage-related RPC stubs.
func (*Usage) Collect ¶
func (u *Usage) Collect(opts *controlapi.MemoryUsageOpts, out *controlapi.MemoryUsage) error
Collect returns memory used by the sandboxed application.
func (*Usage) GetFileIoStats ¶
GetFileIoStats writes the read times in nanoseconds to out.
func (*Usage) Reduce ¶
func (u *Usage) Reduce(opts *UsageReduceOpts, out *UsageReduceOutput) error
Reduce requests that the sentry attempt to reduce its memory usage.
func (*Usage) UsageFD ¶
func (u *Usage) UsageFD(opts *controlapi.MemoryUsageFileOpts, out *controlapi.MemoryUsageFile) error
UsageFD returns the file that tracks the memory usage of the application.
type UsageReduceOpts ¶
type UsageReduceOpts struct {
// If Wait is `true`, Reduce blocks until all activity initiated by
// Usage.Reduce() has completed.
// If Wait is `false`, Go garbage collection is still performed and may
// still block for some time, unless `DoNotGC` is `true`.
Wait bool `json:"wait"`
// If DoNotGC is true, Reduce does not explicitly run Go garbage collection.
// Garbage collection may block for an indeterminate amount of time.
// Note that the runtime Go may still perform routine garbage collection at
// any time during program execution, so a routine GC is still possible even
// when this option set to `true`.
DoNotGC bool `json:"do_not_gc"`
}
UsageReduceOpts contains options to Usage.Reduce().
type UsageReduceOutput ¶
type UsageReduceOutput struct{}
UsageReduceOutput contains output from Usage.Reduce().
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package controlapi is the API `runsc` uses to communicate with the Sentry process.
|
Package controlapi is the API `runsc` uses to communicate with the Sentry process. |