sandbox

Documentation

Overview

Package sandbox creates and manipulates sandboxes.

Index

• type Args
• type Sandbox
  • func New(conf *config.Config, args *Args) (*Sandbox, error)
  • func (s *Sandbox) BlockProfile(f *os.File, duration time.Duration) error
  • func (s *Sandbox) CPUProfile(f *os.File, duration time.Duration) error
  • func (s *Sandbox) Cat(cid string, files []string, out *os.File) error
  • func (s *Sandbox) ChangeLogging(args control.LoggingArgs) error
  • func (s *Sandbox) Checkpoint(cid string, f *os.File) error
  • func (s *Sandbox) CreateSubcontainer(conf *config.Config, cid string, tty *os.File) error
  • func (s *Sandbox) DestroyContainer(cid string) error
  • func (s *Sandbox) Event(cid string) (*boot.EventOut, error)
  • func (s *Sandbox) Execute(conf *config.Config, args *control.ExecArgs) (int32, error)
  • func (s *Sandbox) HeapProfile(f *os.File, delay time.Duration) error
  • func (s *Sandbox) IsRootContainer(cid string) bool
  • func (s *Sandbox) IsRunning() bool
  • func (s *Sandbox) MutexProfile(f *os.File, duration time.Duration) error
  • func (s *Sandbox) NewCGroup() (cgroup.Cgroup, error)
  • func (s *Sandbox) Pause(cid string) error
  • func (s *Sandbox) Processes(cid string) ([]*control.Process, error)
  • func (s *Sandbox) Reduce(cid string, wait bool) error
  • func (s *Sandbox) Restore(cid string, spec *specs.Spec, conf *config.Config, filename string) error
  • func (s *Sandbox) Resume(cid string) error
  • func (s *Sandbox) SignalContainer(cid string, sig unix.Signal, all bool) error
  • func (s *Sandbox) SignalProcess(cid string, pid int32, sig unix.Signal, fgProcess bool) error
  • func (s *Sandbox) Stacks() (string, error)
  • func (s *Sandbox) StartRoot(spec *specs.Spec, conf *config.Config) error
  • func (s *Sandbox) StartSubcontainer(spec *specs.Spec, conf *config.Config, cid string, ...) error
  • func (s *Sandbox) Stream(cid string, filters []string, out *os.File) error
  • func (s *Sandbox) Trace(f *os.File, duration time.Duration) error
  • func (s *Sandbox) Usage(cid string, Full bool) (control.MemoryUsage, error)
  • func (s *Sandbox) UsageFD(cid string) (*control.MemoryUsageRecord, error)
  • func (s *Sandbox) Wait(cid string) (unix.WaitStatus, error)
  • func (s *Sandbox) WaitPID(cid string, pid int32) (unix.WaitStatus, error)

Types

type Args

type Args struct {
	// ID is the sandbox unique identifier.
	ID string

	// Spec is the OCI spec that describes the container.
	Spec *specs.Spec

	// BundleDir is the directory containing the container bundle.
	BundleDir string

	// ConsoleSocket is the path to a unix domain socket that will receive
	// the console FD. It may be empty.
	ConsoleSocket string

	// UserLog is the filename to send user-visible logs to. It may be empty.
	UserLog string

	// IOFiles is the list of files that connect to a 9P endpoint for the mounts
	// points using Gofers. They must be in the same order as mounts appear in
	// the spec.
	IOFiles []*os.File

	// MountsFile is a file container mount information from the spec. It's
	// equivalent to the mounts from the spec, except that all paths have been
	// resolved to their final absolute location.
	MountsFile *os.File

	// Gcgroup is the cgroup that the sandbox is part of.
	Cgroup cgroup.Cgroup

	// Attached indicates that the sandbox lifecycle is attached with the caller.
	// If the caller exits, the sandbox should exit too.
	Attached bool
}

Args is used to configure a new sandbox.

type Sandbox

type Sandbox struct {
	// ID is the id of the sandbox (immutable). By convention, this is the same
	// ID as the first container run in the sandbox.
	ID string `json:"id"`

	// Pid is the pid of the running sandbox (immutable). May be 0 if the sandbox
	// is not running.
	Pid int `json:"pid"`

	// UID is the user ID in the parent namespace that the sandbox is running as.
	UID int `json:"uid"`
	// GID is the group ID in the parent namespace that the sandbox is running as.
	GID int `json:"gid"`

	// CgroupJSON contains the cgroup configuration that the sandbox is part of
	// and allow serialization of the configuration into json
	CgroupJSON cgroup.CgroupJSON `json:"cgroup"`

	// OriginalOOMScoreAdj stores the value of oom_score_adj when the sandbox
	// started, before it may be modified.
	OriginalOOMScoreAdj int `json:"originalOomScoreAdj"`
	// contains filtered or unexported fields
}

Sandbox wraps a sandbox process.

It is used to start/stop sandbox process (and associated processes like gofers), as well as for running and manipulating containers inside a running sandbox.

Note: Sandbox must be immutable because a copy of it is saved for each container and changes would not be synchronized to all of them.

func New

func New(conf *config.Config, args *Args) (*Sandbox, error)

New creates the sandbox process. The caller must call Destroy() on the sandbox.

func (*Sandbox) BlockProfile

func (s *Sandbox) BlockProfile(f *os.File, duration time.Duration) error

BlockProfile writes a block profile to the given file.

func (*Sandbox) CPUProfile

func (s *Sandbox) CPUProfile(f *os.File, duration time.Duration) error

CPUProfile collects a CPU profile.

func (*Sandbox) Cat

func (s *Sandbox) Cat(cid string, files []string, out *os.File) error

Cat sends the cat call for a container in the sandbox.

func (*Sandbox) ChangeLogging

func (s *Sandbox) ChangeLogging(args control.LoggingArgs) error

ChangeLogging changes logging options.

func (*Sandbox) Checkpoint

func (s *Sandbox) Checkpoint(cid string, f *os.File) error

Checkpoint sends the checkpoint call for a container in the sandbox. The statefile will be written to f.

func (*Sandbox) CreateSubcontainer

func (s *Sandbox) CreateSubcontainer(conf *config.Config, cid string, tty *os.File) error

CreateSubcontainer creates a container inside the sandbox.

func (*Sandbox) DestroyContainer

func (s *Sandbox) DestroyContainer(cid string) error

DestroyContainer destroys the given container. If it is the root container, then the entire sandbox is destroyed.

func (*Sandbox) Event

func (s *Sandbox) Event(cid string) (*boot.EventOut, error)

Event retrieves stats about the sandbox such as memory and CPU utilization.

func (*Sandbox) Execute

func (s *Sandbox) Execute(conf *config.Config, args *control.ExecArgs) (int32, error)

Execute runs the specified command in the container. It returns the PID of the newly created process.

func (*Sandbox) HeapProfile

func (s *Sandbox) HeapProfile(f *os.File, delay time.Duration) error

HeapProfile writes a heap profile to the given file.

func (*Sandbox) IsRootContainer

func (s *Sandbox) IsRootContainer(cid string) bool

IsRootContainer returns true if the specified container ID belongs to the root container.

func (*Sandbox) IsRunning

func (s *Sandbox) IsRunning() bool

IsRunning returns true if the sandbox or gofer process is running.

func (*Sandbox) MutexProfile

func (s *Sandbox) MutexProfile(f *os.File, duration time.Duration) error

MutexProfile writes a mutex profile to the given file.

func (*Sandbox) NewCGroup

func (s *Sandbox) NewCGroup() (cgroup.Cgroup, error)

NewCGroup returns the sandbox's Cgroup, or an error if it does not have one.

func (*Sandbox) Pause

func (s *Sandbox) Pause(cid string) error

Pause sends the pause call for a container in the sandbox.

func (*Sandbox) Processes

func (s *Sandbox) Processes(cid string) ([]*control.Process, error)

Processes retrieves the list of processes and associated metadata for a given container in this sandbox.

func (*Sandbox) Reduce

func (s *Sandbox) Reduce(cid string, wait bool) error

Reduce sends the reduce call for a container in the sandbox.

func (*Sandbox) Restore

func (s *Sandbox) Restore(cid string, spec *specs.Spec, conf *config.Config, filename string) error

Restore sends the restore call for a container in the sandbox.

func (*Sandbox) Resume

func (s *Sandbox) Resume(cid string) error

Resume sends the resume call for a container in the sandbox.

func (*Sandbox) SignalContainer

func (s *Sandbox) SignalContainer(cid string, sig unix.Signal, all bool) error

SignalContainer sends the signal to a container in the sandbox. If all is true and signal is SIGKILL, then waits for all processes to exit before returning.

func (*Sandbox) SignalProcess

func (s *Sandbox) SignalProcess(cid string, pid int32, sig unix.Signal, fgProcess bool) error

SignalProcess sends the signal to a particular process in the container. If fgProcess is true, then the signal is sent to the foreground process group in the same session that PID belongs to. This is only valid if the process is attached to a host TTY.

func (*Sandbox) Stacks

func (s *Sandbox) Stacks() (string, error)

Stacks collects and returns all stacks for the sandbox.

func (*Sandbox) StartRoot

func (s *Sandbox) StartRoot(spec *specs.Spec, conf *config.Config) error

StartRoot starts running the root container process inside the sandbox.

func (*Sandbox) StartSubcontainer

func (s *Sandbox) StartSubcontainer(spec *specs.Spec, conf *config.Config, cid string, stdios, goferFiles []*os.File) error

StartSubcontainer starts running a sub-container inside the sandbox.

func (*Sandbox) Stream

func (s *Sandbox) Stream(cid string, filters []string, out *os.File) error

Stream sends the AttachDebugEmitter call for a container in the sandbox, and dumps filtered events to out.

func (*Sandbox) Trace

func (s *Sandbox) Trace(f *os.File, duration time.Duration) error

Trace collects an execution trace.

func (*Sandbox) Usage

func (s *Sandbox) Usage(cid string, Full bool) (control.MemoryUsage, error)

Usage sends the collect call for a container in the sandbox.

func (*Sandbox) UsageFD

func (s *Sandbox) UsageFD(cid string) (*control.MemoryUsageRecord, error)

UsageFD sends the usagefd call for a container in the sandbox.

func (*Sandbox) Wait

func (s *Sandbox) Wait(cid string) (unix.WaitStatus, error)

Wait waits for the containerized process to exit, and returns its WaitStatus.

func (*Sandbox) WaitPID

func (s *Sandbox) WaitPID(cid string, pid int32) (unix.WaitStatus, error)

WaitPID waits for process 'pid' in the container's sandbox and returns its WaitStatus.