control

package
v0.0.0-...-ba09d25 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 29, 2021 License: Apache-2.0, MIT Imports: 39 Imported by: 0

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

View Source 
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

View Source 
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 

func ContainerUsage(kr *kernel.Kernel) map[string]uint64

ContainerUsage retrieves per-container CPU usage.

func ExecAsync 

func ExecAsync(proc *Proc, args *ExecArgs) (*kernel.ThreadGroup, kernel.ThreadID, *host.TTYFileOperations, *hostvfs2.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 

func PrintPIDsJSON(pl []*Process) (string, error)

PrintPIDsJSON prints a JSON object containing only the PIDs in pl. This behavior is the same as runc's.

func ProcessListToJSON 

func ProcessListToJSON(pl []*Process) (string, error)

ProcessListToJSON will return the JSON representation of ps.

func ProcessListToTable 

func ProcessListToTable(pl []*Process) string

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

func Processes 

func Processes(k *kernel.Kernel, containerID string, out *[]*Process) error

Processes retrieves information about processes running in the sandbox with the given container id. All processes are returned if 'containerID' is empty.

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 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 *fs.MountNamespace

	// MountNamespaceVFS2 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.
	MountNamespaceVFS2 *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.
	urpc.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.

func (ExecArgs) String 

func (args ExecArgs) String() string

String prints the arguments as a string.

type Fs 

type Fs struct {
	Kernel *kernel.Kernel
}

Fs includes fs-related functions.

func (*Fs) Cat 

func (f *Fs) Cat(o *CatOpts, _ *struct{}) error

Cat is a RPC stub which prints out and returns the content of the files.

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 *kernel.Kernel
}

Lifecycle provides functions related to starting and stopping tasks.

func (*Lifecycle) Pause 

func (l *Lifecycle) Pause(_, _ *struct{}) error

Pause pauses all tasks, blocking until they are stopped.

func (*Lifecycle) Resume 

func (l *Lifecycle) Resume(_, _ *struct{}) error

Resume resumes all tasks.

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 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 

type Proc struct {
	Kernel *kernel.Kernel
}

Proc includes task-related functions.

At the moment, this is limited to exec support.

func (*Proc) Exec 

func (proc *Proc) Exec(args *ExecArgs, waitStatus *uint32) error

Exec runs a new task.

func (*Proc) Ps 

func (proc *Proc) Ps(args *PsArgs, out *string) error

Ps provides a process listing for the running kernel.

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 

func NewProfile(k *kernel.Kernel) *Profile

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) Stop 

func (p *Profile) Stop()

Stop implements urpc.Stopper.Stop.

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 State 

type State struct {
	Kernel   *kernel.Kernel
	Watchdog *watchdog.Watchdog
}

State includes state-related functions.

func (*State) Save 

func (s *State) Save(o *SaveOpts, _ *struct{}) error

Save saves the running system.

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 

type Usage struct {
	Kernel *kernel.Kernel
}

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 

func (*Usage) GetFileIoStats(_ *struct{}, out *string) error

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.
	Wait bool `json:"wait"`
}

UsageReduceOpts contains options to Usage.Reduce().

type UsageReduceOutput 

type UsageReduceOutput struct{}

UsageReduceOutput contains output from Usage.Reduce().

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.