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 ¶
- Constants
- Variables
- func ContainerUsage(kr *kernel.Kernel) map[string]uint64
- func ExecAsync(proc *Proc, args *ExecArgs) (*kernel.ThreadGroup, kernel.ThreadID, *host.TTYFileDescription, error)
- func PrintPIDsJSON(pl []*Process) (string, error)
- func ProcessListToJSON(pl []*Process) (string, error)
- func ProcessListToTable(pl []*Process) string
- func Processes(k *kernel.Kernel, containerID string, out *[]*Process) error
- type BlockProfileOpts
- type CPUProfileOpts
- type CatOpts
- type CgroupControlFile
- type Cgroups
- type CgroupsReadArg
- type CgroupsReadArgs
- type CgroupsResult
- type CgroupsResults
- type CgroupsWriteArg
- type CgroupsWriteArgs
- type Container
- type ContainerArgs
- type Events
- type EventsOpts
- type ExecArgs
- type FilePayload
- type Fs
- type GetRegisteredMetricsOpts
- type GoroutineProfileOpts
- type HeapProfileOpts
- type Lifecycle
- func (l *Lifecycle) GetExitStatus(args *ContainerArgs, status *uint32) error
- func (l *Lifecycle) IsContainerRunning(args *ContainerArgs, isRunning *bool) error
- func (l *Lifecycle) Pause(_, _ *struct{}) error
- func (l *Lifecycle) Reap(args *ContainerArgs, _ *struct{}) error
- func (l *Lifecycle) Resume(_, _ *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 LoggingArgs
- type MemoryUsage
- type MemoryUsageFile
- type MemoryUsageFileOpts
- type MemoryUsageOpts
- type MemoryUsageRecord
- type Metrics
- type MetricsExportData
- type MetricsExportOpts
- type MetricsRegistrationResponse
- type MutexProfileOpts
- type Proc
- type Process
- type Profile
- func (p *Profile) Block(o *BlockProfileOpts, _ *struct{}) error
- func (p *Profile) CPU(o *CPUProfileOpts, _ *struct{}) error
- func (p *Profile) Goroutine(o *GoroutineProfileOpts, _ *struct{}) error
- func (p *Profile) Heap(o *HeapProfileOpts, _ *struct{}) error
- func (p *Profile) Mutex(o *MutexProfileOpts, _ *struct{}) error
- func (p *Profile) Stop()
- func (p *Profile) Trace(o *TraceProfileOpts, _ *struct{}) error
- type PsArgs
- type SaveOpts
- type SignalContainerArgs
- type StartContainerArgs
- type State
- type TraceProfileOpts
- type Usage
- type UsageReduceOpts
- type UsageReduceOutput
Constants ¶
const ( // DefaultBlockProfileRate is the default profiling rate for block // profiles. // // The default here is 10%, which will record a stacktrace 10% of the // time when blocking occurs. Since these events should not be super // frequent, we expect this to achieve a reasonable balance between // collecting the data we need and imposing a high performance cost // (e.g. skewing even the CPU profile). DefaultBlockProfileRate = 10 // DefaultMutexProfileRate is the default profiling rate for mutex // profiles. Like the block rate above, we use a default rate of 10% // for the same reasons. DefaultMutexProfileRate = 10 )
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 ContainerUsage ¶
ContainerUsage retrieves per-container CPU usage.
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 PrintPIDsJSON ¶
PrintPIDsJSON prints a JSON object containing only the PIDs in pl. This behavior is the same as runc's.
func ProcessListToJSON ¶
ProcessListToJSON will return the JSON representation of ps.
func ProcessListToTable ¶
ProcessListToTable prints a table with the following format: UID PID PPID C TTY STIME TIME CMD 0 1 0 0 pty/4 14:04 505262ns tail
Types ¶
type BlockProfileOpts ¶
type BlockProfileOpts struct { // FilePayload is the destination for the profiling output. urpc.FilePayload // Duration is the duration of the profile. Duration time.Duration `json:"duration"` // Rate is the block profile rate. Rate int `json:"rate"` }
BlockProfileOpts contains options specifically for block profiles.
type CPUProfileOpts ¶
type CPUProfileOpts struct { // FilePayload is the destination for the profiling output. urpc.FilePayload // Duration is the duration of the profile. Duration time.Duration `json:"duration"` }
CPUProfileOpts contains options specifically for CPU profiles.
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 CgroupControlFile ¶
type CgroupControlFile struct { Controller string `json:"controller"` Path string `json:"path"` Name string `json:"name"` }
CgroupControlFile identifies a specific control file within a specific cgroup, for the hierarchy with a given controller.
type Cgroups ¶
Cgroups contains the state for cgroupfs related control commands.
func (*Cgroups) ReadControlFiles ¶
func (c *Cgroups) ReadControlFiles(args *CgroupsReadArgs, out *CgroupsResults) error
ReadControlFiles is an RPC stub for batch-reading cgroupfs control files.
func (*Cgroups) WriteControlFiles ¶
func (c *Cgroups) WriteControlFiles(args *CgroupsWriteArgs, out *CgroupsResults) error
WriteControlFiles is an RPC stub for batch-writing cgroupfs control files.
type CgroupsReadArg ¶
type CgroupsReadArg struct {
File CgroupControlFile `json:"file"`
}
CgroupsReadArg represents the arguments for a single read command.
type CgroupsReadArgs ¶
type CgroupsReadArgs struct {
Args []CgroupsReadArg `json:"args"`
}
CgroupsReadArgs represents the list of arguments for a batched read command.
type CgroupsResult ¶
CgroupsResult represents the result of a cgroup operation.
func (*CgroupsResult) AsError ¶
func (r *CgroupsResult) AsError() error
AsError interprets the result as an error.
func (*CgroupsResult) Unpack ¶
func (r *CgroupsResult) Unpack() (string, error)
Unpack splits CgroupsResult into a (value, error) tuple.
type CgroupsResults ¶
type CgroupsResults struct {
Results []CgroupsResult `json:"results"`
}
CgroupsResults represents the list of results for a batch command.
type CgroupsWriteArg ¶
type CgroupsWriteArg struct { File CgroupControlFile `json:"file"` Value string `json:"value"` }
CgroupsWriteArg represents the arguments for a single write command.
type CgroupsWriteArgs ¶
type CgroupsWriteArgs struct {
Args []CgroupsWriteArg `json:"args"`
}
CgroupsWriteArgs represents the lust of arguments for a batched write command.
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 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 { // 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"` // 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 // 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 // KGID is the GID to run with in the root user namespace. Defaults to // the root group if not set explicitly. KGID auth.KGID // ExtraKGIDs is the list of additional groups to which the user belongs. ExtraKGIDs []auth.KGID // Capabilities is the list of capabilities to give to the process. Capabilities *auth.TaskCapabilities // StdioIsPty indicates that FDs 0, 1, and 2 are connected to a host pty FD. StdioIsPty bool // FilePayload determines the files to give to the new process. FilePayload // ContainerID is the container for the process being executed. ContainerID string // PIDNamespace is the pid namespace for the process being executed. PIDNamespace *kernel.PIDNamespace // Limits is the limit set for the process being executed. Limits *limits.LimitSet }
ExecArgs is the set of arguments to exec.
type FilePayload ¶
type FilePayload struct { // FilePayload is the file payload that is transferred via RPC. urpc.FilePayload // GuestFDs are the file descriptors in the file descriptor map of the // executed application. They correspond 1:1 to the files in the // urpc.FilePayload. If a program is executed from a host file descriptor, // the file payload may contain one additional file. In that case, the file // used for program execution is the last file in the Files array. GuestFDs []int }
FilePayload aids to ensure that payload files and guest file descriptors are consistent when instantiated through the NewFilePayload helper method.
func NewFilePayload ¶
NewFilePayload returns a FilePayload that maps file descriptors to files inside the executed process and provides a file for execution.
type GetRegisteredMetricsOpts ¶
type GetRegisteredMetricsOpts struct{}
GetRegisteredMetricsOpts contains metric registration query options.
type GoroutineProfileOpts ¶
type GoroutineProfileOpts struct { // FilePayload is the destination for the profiling output. urpc.FilePayload }
GoroutineProfileOpts contains options specifically for goroutine profiles.
type HeapProfileOpts ¶
type HeapProfileOpts struct { // FilePayload is the destination for the profiling output. urpc.FilePayload // Delay is the sleep time, similar to Duration. This may // not affect the data collected however, as the heap will // continue only the memory associated with the last alloc. Delay time.Duration `json:"delay"` }
HeapProfileOpts contains options specifically for heap profiles.
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. ShutdownCh chan struct{} // MountNamespacesMap is a map of container id/names and the mount // namespaces. MountNamespacesMap map[string]*vfs.MountNamespace // 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.
func (*Lifecycle) IsContainerRunning ¶
func (l *Lifecycle) IsContainerRunning(args *ContainerArgs, isRunning *bool) error
IsContainerRunning returns true if the container is running.
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.
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.
func (*Lifecycle) StartContainer ¶
func (l *Lifecycle) StartContainer(args *StartContainerArgs, _ *uint32) error
StartContainer will start a new container in the sandbox.
type Logging ¶
type Logging struct{}
Logging provides functions related to logging.
func (*Logging) Change ¶
func (l *Logging) Change(args *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 LoggingArgs ¶
type LoggingArgs struct { // SetLevel is a flag used to indicate that we should update // the logging level. We should be able to change the strace // list without affecting the logging level and vice versa. SetLevel bool // Level is the log level that will be set if SetLevel is true. Level log.Level // SetLogPackets indicates that we should update the log packets flag. SetLogPackets bool // LogPackets is the actual value to set for LogPackets. // SetLogPackets must be enabled to indicate that we're changing // the value. LogPackets bool // SetStrace is a flag used to indicate that strace related // arguments were passed in. SetStrace bool // EnableStrace is a flag from the CLI that specifies whether to // enable strace at all. If this flag is false then a completely // pristine copy of the syscall table will be swapped in. This // approach is used to remain consistent with an empty strace // allowlist meaning trace all system calls. EnableStrace bool // Strace is the allowlist of syscalls to trace to log. If this // and StraceEventAllowlist are empty trace all system calls. StraceAllowlist []string // SetEventStrace is a flag used to indicate that event strace // related arguments were passed in. SetEventStrace bool // StraceEventAllowlist is the allowlist of syscalls to trace // to event log. StraceEventAllowlist []string }
LoggingArgs are the arguments to use for changing the logging level and strace list.
type MemoryUsage ¶
type MemoryUsage struct { Unknown uint64 `json:"Unknown"` System uint64 `json:"System"` Anonymous uint64 `json:"Anonymous"` PageCache uint64 `json:"PageCache"` Mapped uint64 `json:"Mapped"` Tmpfs uint64 `json:"Tmpfs"` Ramdiskfs uint64 `json:"Ramdiskfs"` Total uint64 `json:"Total"` }
MemoryUsage is a memory usage structure.
type MemoryUsageFile ¶
type MemoryUsageFile struct {
urpc.FilePayload
}
MemoryUsageFile contains the file handle to the usage file.
type MemoryUsageFileOpts ¶
type MemoryUsageFileOpts struct { // Version is used to ensure both sides agree on the format of the // shared memory buffer. Version uint64 `json:"Version"` }
MemoryUsageFileOpts contains usage file options.
type MemoryUsageOpts ¶
type MemoryUsageOpts struct { // Full indicates that a full accounting should be done. If Full is not // specified, then a partial accounting will be done, and Unknown will // contain a majority of memory. See Collect for more information. Full bool `json:"Full"` }
MemoryUsageOpts contains usage options.
type MemoryUsageRecord ¶
type MemoryUsageRecord struct {
// contains filtered or unexported fields
}
MemoryUsageRecord contains the mapping and platform memory file.
func NewMemoryUsageRecord ¶
func NewMemoryUsageRecord(usageFile, platformFile os.File) (*MemoryUsageRecord, error)
NewMemoryUsageRecord creates a new MemoryUsageRecord from usageFile and platformFile.
func (*MemoryUsageRecord) Fetch ¶
func (m *MemoryUsageRecord) Fetch() (mapped, unknown, total uint64, err error)
Fetch fetches the usage info from a MemoryUsageRecord.
type Metrics ¶
type Metrics struct{}
Metrics includes metrics-related RPC stubs.
func (*Metrics) Export ¶
func (u *Metrics) Export(opts *MetricsExportOpts, out *MetricsExportData) error
Export export metrics data into MetricsExportData.
func (*Metrics) GetRegisteredMetrics ¶
func (u *Metrics) GetRegisteredMetrics(_ *GetRegisteredMetricsOpts, out *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 MetricsExportData ¶
type MetricsExportData struct {
Snapshot *prometheus.Snapshot `json:"snapshot"`
}
MetricsExportData contains data for all metrics being exported.
type MetricsExportOpts ¶
type MetricsExportOpts struct { // If set, this is a regular expression that is used to filter the set of // exported metrics. OnlyMetrics string `json:"only_metrics"` }
MetricsExportOpts contains metric exporting options.
func (*MetricsExportOpts) Verify ¶
func (m *MetricsExportOpts) Verify(data *MetricsExportData) error
Verify verifies that the given exported data is compliant with the export options. This should be run client-side to double-check results.
type MetricsRegistrationResponse ¶
type MetricsRegistrationResponse struct {
RegisteredMetrics *pb.MetricRegistration
}
MetricsRegistrationResponse contains metric registration data.
type MutexProfileOpts ¶
type MutexProfileOpts struct { // FilePayload is the destination for the profiling output. urpc.FilePayload // Duration is the duration of the profile. Duration time.Duration `json:"duration"` // Fraction is the mutex profile fraction. Fraction int `json:"fraction"` }
MutexProfileOpts contains options specifically for mutex profiles.
type Proc ¶
Proc includes task-related functions.
At the moment, this is limited to exec support.
type Process ¶
type Process struct { UID auth.KUID `json:"uid"` PID kernel.ThreadID `json:"pid"` // Parent PID PPID kernel.ThreadID `json:"ppid"` Threads []kernel.ThreadID `json:"threads"` // Processor utilization C int32 `json:"c"` // TTY name of the process. Will be of the form "pts/N" if there is a // TTY, or "?" if there is not. TTY string `json:"tty"` // Start time STime string `json:"stime"` // CPU time Time string `json:"time"` // Executable shortname (e.g. "sh" for /bin/sh) Cmd string `json:"cmd"` }
Process contains information about a single process in a Sandbox.
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 *BlockProfileOpts, _ *struct{}) error
Block dumps a blocking profile.
func (*Profile) CPU ¶
func (p *Profile) CPU(o *CPUProfileOpts, _ *struct{}) error
CPU is an RPC stub which collects a CPU profile.
func (*Profile) Goroutine ¶
func (p *Profile) Goroutine(o *GoroutineProfileOpts, _ *struct{}) error
Goroutine dumps out the stack trace for all running goroutines.
func (*Profile) Heap ¶
func (p *Profile) Heap(o *HeapProfileOpts, _ *struct{}) error
Heap generates a heap profile.
func (*Profile) Mutex ¶
func (p *Profile) Mutex(o *MutexProfileOpts, _ *struct{}) error
Mutex dumps a mutex profile.
func (*Profile) Trace ¶
func (p *Profile) Trace(o *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 SaveOpts ¶
type SaveOpts struct { // Key is used for state integrity check. Key []byte `json:"key"` // Metadata is the set of metadata to prepend to the state file. Metadata map[string]string `json:"metadata"` // FilePayload contains the destination for the state. urpc.FilePayload }
SaveOpts contains options for the Save RPC call.
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 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"` // 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 TraceProfileOpts ¶
type TraceProfileOpts struct { // FilePayload is the destination for the profiling output. urpc.FilePayload // Duration is the duration of the profile. Duration time.Duration `json:"duration"` }
TraceProfileOpts contains options specifically for traces.
type Usage ¶
Usage includes usage-related RPC stubs.
func (*Usage) Collect ¶
func (u *Usage) Collect(opts *MemoryUsageOpts, out *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 *MemoryUsageFileOpts, out *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().