control

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 ExecAsync(proc *Proc, args *ExecArgs) (*kernel.ThreadGroup, kernel.ThreadID, *host.TTYFileOperations, 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 ExecArgs
  • func (args ExecArgs) String() string
• type Logging
  • func (l *Logging) Change(args *LoggingArgs, code *int) error
• type LoggingArgs
• type Proc
  • func (proc *Proc) Exec(args *ExecArgs, waitStatus *uint32) error
  • func (proc *Proc) Ps(args *PsArgs, out *string) error
• type Process
• type Profile
  • func (p *Profile) Goroutine(o *ProfileOpts, _ *struct{}) error
  • func (p *Profile) HeapProfile(o *ProfileOpts, _ *struct{}) error
  • func (p *Profile) StartCPUProfile(o *ProfileOpts, _ *struct{}) error
  • func (p *Profile) StartTrace(o *ProfileOpts, _ *struct{}) error
  • func (p *Profile) StopCPUProfile(_, _ *struct{}) error
  • func (p *Profile) StopTrace(_, _ *struct{}) error
• type ProfileOpts
• type PsArgs
• type SaveOpts
• type State
  • func (s *State) Save(o *SaveOpts, _ *struct{}) error

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 ExecAsync

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

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

ExecArgs is the set of arguments to exec.

func (ExecArgs) String

func (args ExecArgs) String() string

String prints the arguments as a string.

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 acctually return san 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
	// whitelist meaning trace all system calls.
	EnableStrace bool

	// Strace is the whitelist of syscalls to trace to log. If this
	// and StraceEventWhitelist are empty trace all system calls.
	StraceWhitelist []string

	// SetEventStrace is a flag used to indicate that event strace
	// related arguments were passed in.
	SetEventStrace bool

	// StraceEventWhitelist is the whitelist of syscalls to trace
	// to event log.
	StraceEventWhitelist []string
}

LoggingArgs are the arguments to use for changing the logging level and strace list.

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 {

	// Kernel is the kernel under profile.
	Kernel *kernel.Kernel
	// contains filtered or unexported fields
}

Profile includes profile-related RPC stubs. It provides a way to control the built-in pprof facility in sentry via sentryctl.

The following options to sentryctl are added:

• collect CPU profile on-demand. sentryctl -pid <pid> pprof-cpu-start sentryctl -pid <pid> pprof-cpu-stop

• dump out the stack trace of current go routines. sentryctl -pid <pid> pprof-goroutine

func (*Profile) Goroutine

func (p *Profile) Goroutine(o *ProfileOpts, _ *struct{}) error

Goroutine is an RPC stub which dumps out the stack trace for all running goroutines.

func (*Profile) HeapProfile

func (p *Profile) HeapProfile(o *ProfileOpts, _ *struct{}) error

HeapProfile generates a heap profile for the sentry.

func (*Profile) StartCPUProfile

func (p *Profile) StartCPUProfile(o *ProfileOpts, _ *struct{}) error

StartCPUProfile is an RPC stub which starts recording the CPU profile in a file.

func (*Profile) StartTrace

func (p *Profile) StartTrace(o *ProfileOpts, _ *struct{}) error

StartTrace is an RPC stub which starts collection of an execution trace.

func (*Profile) StopCPUProfile

func (p *Profile) StopCPUProfile(_, _ *struct{}) error

StopCPUProfile is an RPC stub which stops the CPU profiling and flush out the profile data. It takes no argument.

func (*Profile) StopTrace

func (p *Profile) StopTrace(_, _ *struct{}) error

StopTrace is an RPC stub which stops collection of an ongoing execution trace and flushes the trace data. It takes no argument.

type ProfileOpts

type ProfileOpts struct {
	// File is the filesystem path for the profile.
	File string `json:"path"`

	// FilePayload is the destination for the profiling output.
	urpc.FilePayload
}

ProfileOpts contains options for the StartCPUProfile/Goroutine RPC call.

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.