systrap

README

The systrap platform

This platform is similar with the ptrace platform but differs on how system calls, page-faults and other exceptions are handled.

Linux allows setting seccomp filters with SECCOMP_RET_TRAP, such that when a thread tries to call a system call caught by the seccomp filter, this thread will receive the SIGSYS signal.

gVisor's systrap platform uses this kernel feature to have all thread events that have to be handled in the sentry trigger signals.

The systrap platform implements a stub signal handler (as part of the sysmsg module), and communication protocol between this stub signal handler and the Sentry.

The initialization of a new stub thread involves:

• Installing seccomp filters to trap all user system calls.
• Setting up an alternate signal stack which is shared with the Sentry.
• Setting up the sysmsg signal handler for SIGSYS, SIGSEGV, SIGBUS, SIGFPE, SIGTRAP, and SIGILL.

User code is executed in the context of a stub thread. When it calls a system call or triggers a page-fault, the stub signal handler code executes. It notifies the Sentry of this new signal. The Sentry handles this, and calls back the system thread so that it can resume running.

When the kernel prepares to execute the signal handler, it generates a signal frame which contains the process state (registers, FPU state, etc). Then, when the kernel resumes the process, the process state is restored from this frame. The signal frame is saved on the signal handler stack. This memory region is shared with the Sentry process. This allows gVisor to read and modify the thread state from the Sentry.

Documentation

Overview

Package systrap provides a seccomp-based implementation of the platform interface.

In a nutshell, it works as follows:

The creation of a new address space creates a new child processes.

The creation of a new stub thread creates a new system thread with a specified address space. To initialize this thread, the following action will be done:

• install a signal stack which is shared with the Sentry.
• install a signal handler for SYS, BUS, FPE, CHLD, TRAP, SEGV signals. This signal handler is a key part of the systrap platform. Any stub event which has to be handled in a privilege mode (by the Sentry) triggers one of previous signals. The signal handler is running on the separate stack which is shared with the Sentry. There is the sysmsg structure to synchronize the Sentry and a stub thread.
• install seccomp filters to trap user system calls.
• send a fake SIGSEGV to stop the thread in the signal handler.

A platformContext is just a collection of temporary variables. Calling Switch on a platformContext does the following:

Set up proper registers and an FPU state on a stub signal frame.
Wake up a stub thread by changing sysmsg->stage and calling FUTEX_WAKE.
Wait for new stub event by polling sysmsg->stage.

Lock order:

subprocessPool.mu
	subprocess.mu
		platformContext.mu

+checkalignedignore

Index

• Constants
• Variables
• type Systrap
  • func New() (*Systrap, error)
  • func (*Systrap) CooperativelySchedulesAddressSpace() bool
  • func (*Systrap) MapUnit() uint64
  • func (*Systrap) MaxUserAddress() hostarch.Addr
  • func (*Systrap) MinUserAddress() hostarch.Addr
  • func (p *Systrap) NewAddressSpace(any) (platform.AddressSpace, <-chan struct{}, error)
  • func (*Systrap) NewContext(ctx pkgcontext.Context) platform.Context
  • func (p *Systrap) SeccompInfo() platform.SeccompInfo
  • func (*Systrap) SupportsAddressSpaceIO() bool

Constants

const (
	ERESTARTSYS    = unix.Errno(512)
	ERESTARTNOINTR = unix.Errno(513)
	ERESTARTNOHAND = unix.Errno(514)
)

Linux kernel errnos which "should never be seen by user programs", but will be revealed to ptrace syscall exit tracing.

These constants are only used in subprocess.go.

Variables

var SystrapProfiling = metric.FakeMetricBuilder{}

SystrapProfiling is a builder that produces conditionally compiled metrics. Metrics made from this are compiled and active at runtime when the "systrap_profiling" go-tag is specified at compilation.

Types

type Systrap

type Systrap struct {
	platform.NoCPUPreemptionDetection
	platform.UseHostGlobalMemoryBarrier
	platform.DoesNotOwnPageTables
	// contains filtered or unexported fields
}

Systrap represents a collection of seccomp subprocesses.

func New

func New() (*Systrap, error)

New returns a new seccomp-based implementation of the platform interface.

func (*Systrap) CooperativelySchedulesAddressSpace

func (*Systrap) CooperativelySchedulesAddressSpace() bool

CooperativelySchedulesAddressSpace implements platform.Platform.CooperativelySchedulesAddressSpace.

func (*Systrap) MapUnit

func (*Systrap) MapUnit() uint64

MapUnit implements platform.Platform.MapUnit.

func (*Systrap) MaxUserAddress

func (*Systrap) MaxUserAddress() hostarch.Addr

MaxUserAddress returns the first address that may not be used by user applications.

func (*Systrap) MinUserAddress

func (*Systrap) MinUserAddress() hostarch.Addr

MinUserAddress implements platform.MinUserAddress.

func (*Systrap) NewAddressSpace

func (p *Systrap) NewAddressSpace(any) (platform.AddressSpace, <-chan struct{}, error)

NewAddressSpace returns a new subprocess.

func (*Systrap) NewContext

func (*Systrap) NewContext(ctx pkgcontext.Context) platform.Context

NewContext returns an interruptible platformContext.

func (*Systrap) SeccompInfo

func (p *Systrap) SeccompInfo() platform.SeccompInfo

SeccompInfo returns seccomp filter info for the systrap platform.

func (*Systrap) SupportsAddressSpaceIO

func (*Systrap) SupportsAddressSpaceIO() bool

SupportsAddressSpaceIO implements platform.Platform.SupportsAddressSpaceIO.