kernel

package
v0.0.0-...-8516598 Latest Latest
Warning

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

Go to latest
Published: Dec 16, 2024 License: Apache-2.0, MIT Imports: 91 Imported by: 119

README

This package contains:

  • A (partial) emulation of the "core Linux kernel", which governs task execution and scheduling, system call dispatch, and signal handling. See below for details.

  • The top-level interface for the sentry's Linux kernel emulation in general, used by the main function of all versions of the sentry. This interface revolves around the Env type (defined in kernel.go).

Background

In Linux, each schedulable context is referred to interchangeably as a "task" or "thread". Tasks can be divided into userspace and kernel tasks. In the sentry, scheduling is managed by the Go runtime, so each schedulable context is a goroutine; only "userspace" (application) contexts are referred to as tasks, and represented by Task objects. (From this point forward, "task" refers to the sentry's notion of a task unless otherwise specified.)

At a high level, Linux application threads can be thought of as repeating a "run loop":

  • Some amount of application code is executed in userspace.

  • A trap (explicit syscall invocation, hardware interrupt or exception, etc.) causes control flow to switch to the kernel.

  • Some amount of kernel code is executed in kernelspace, e.g. to handle the cause of the trap.

  • The kernel "returns from the trap" into application code.

Analogously, each task in the sentry is associated with a task goroutine that executes that task's run loop (Task.run in task_run.go). However, the sentry's task run loop differs in structure in order to support saving execution state to, and resuming execution from, checkpoints.

While in kernelspace, a Linux thread can be descheduled (cease execution) in a variety of ways:

  • It can yield or be preempted, becoming temporarily descheduled but still runnable. At present, the sentry delegates scheduling of runnable threads to the Go runtime.

  • It can exit, becoming permanently descheduled. The sentry's equivalent is returning from Task.run, terminating the task goroutine.

  • It can enter interruptible sleep, a state in which it can be woken by a caller-defined wakeup or the receipt of a signal. In the sentry, interruptible sleep (which is ambiguously referred to as blocking) is implemented by making all events that can end blocking (including signal notifications) communicated via Go channels and using select to multiplex wakeup sources; see task_block.go.

  • It can enter uninterruptible sleep, a state in which it can only be woken by a caller-defined wakeup. Killable sleep is a closely related variant in which the task can also be woken by SIGKILL. (These definitions also include Linux's "group-stopped" (TASK_STOPPED) and "ptrace-stopped" (TASK_TRACED) states.)

To maximize compatibility with Linux, sentry checkpointing appears as a spurious signal-delivery interrupt on all tasks; interrupted system calls return EINTR or are automatically restarted as usual. However, these semantics require that uninterruptible and killable sleeps do not appear to be interrupted. In other words, the state of the task, including its progress through the interrupted operation, must be preserved by checkpointing. For many such sleeps, the wakeup condition is application-controlled, making it infeasible to wait for the sleep to end before checkpointing. Instead, we must support checkpointing progress through sleeping operations.

Implementation

We break the task's control flow graph into states, delimited by:

  1. Points where uninterruptible and killable sleeps may occur. For example, there exists a state boundary between signal dequeueing and signal delivery because there may be an intervening ptrace signal-delivery-stop.

  2. Points where sleep-induced branches may "rejoin" normal execution. For example, the syscall exit state exists because it can be reached immediately following a synchronous syscall, or after a task that is sleeping in execve() or vfork() resumes execution.

  3. Points containing large branches. This is strictly for organizational purposes. For example, the state that processes interrupt-signaled conditions is kept separate from the main "app" state to reduce the size of the latter.

  4. SyscallReinvoke, which does not correspond to anything in Linux, and exists solely to serve the autosave feature.

States before which a stop may occur are represented as implementations of the taskRunState interface named run(state), allowing them to be saved and restored. States that cannot be immediately preceded by a stop are simply Task methods named do(state).

Conditions that can require task goroutines to cease execution for unknown lengths of time are called stops. Stops are divided into internal stops, which are stops whose start and end conditions are implemented within the sentry, and external stops, which are stops whose start and end conditions are not known to the sentry. Hence all uninterruptible and killable sleeps are internal stops, and the existence of a pending checkpoint operation is an external stop. Internal stops are reified into instances of the TaskStop type, while external stops are merely counted. The task run loop alternates between checking for stops and advancing the task's state. This allows checkpointing to hold tasks in a stopped state while waiting for all tasks in the system to stop.

Documentation

Overview

Package kernel provides an emulation of the Linux kernel.

See README.md for a detailed overview.

Lock order (outermost locks must be taken first):

Kernel.extMu
  TTY.mu
  timekeeperTcpipTimer.mu
  ThreadGroup.timerMu
    Locks acquired by ktime.Timer methods
      TaskSet.mu
        SignalHandlers.mu
          Task.mu
      runningTasksMu

Locking SignalHandlers.mu in multiple SignalHandlers requires locking TaskSet.mu exclusively first. Locking Task.mu in multiple Tasks at the same time requires locking all of their signal mutexes first.

Index

Constants

View Source
const (
	CgroupControllerCPU     = CgroupControllerType("cpu")
	CgroupControllerCPUAcct = CgroupControllerType("cpuacct")
	CgroupControllerCPUSet  = CgroupControllerType("cpuset")
	CgroupControllerDevices = CgroupControllerType("devices")
	CgroupControllerJob     = CgroupControllerType("job")
	CgroupControllerMemory  = CgroupControllerType("memory")
	CgroupControllerPIDs    = CgroupControllerType("pids")
)

Available cgroup controllers.

View Source
const (
	// CtxCanTrace is a Context.Value key for a function with the same
	// signature and semantics as kernel.Task.CanTrace.
	CtxCanTrace contextID = iota

	// CtxKernel is a Context.Value key for a Kernel.
	CtxKernel

	// CtxPIDNamespace is a Context.Value key for a PIDNamespace.
	CtxPIDNamespace

	// CtxTask is a Context.Value key for a Task.
	CtxTask

	// CtxUTSNamespace is a Context.Value key for a UTSNamespace.
	CtxUTSNamespace
)
View Source
const (
	// SupportUndocumented indicates the syscall is not documented yet.
	SupportUndocumented = iota

	// SupportUnimplemented indicates the syscall is unimplemented.
	SupportUnimplemented

	// SupportPartial indicates the syscall is partially supported.
	SupportPartial

	// SupportFull indicates the syscall is fully supported.
	SupportFull
)
View Source
const (

	// StraceEnableLog enables syscall log tracing.
	StraceEnableLog

	// StraceEnableEvent enables syscall event tracing.
	StraceEnableEvent

	// ExternalBeforeEnable enables the external hook before syscall execution.
	ExternalBeforeEnable

	// ExternalAfterEnable enables the external hook after syscall execution.
	ExternalAfterEnable

	// SecCheckEnter represents a schematized/enter syscall seccheck event.
	SecCheckEnter

	// SecCheckExit represents a schematized/exit syscall seccheck event.
	SecCheckExit

	// SecCheckRawEnter represents raw/enter syscall seccheck event.
	SecCheckRawEnter

	// SecCheckRawExit represents raw/exit syscall seccheck event.
	SecCheckRawExit
)

Possible flags for SyscallFlagsTable.enable.

View Source
const (
	// EventExit represents an exit notification generated for a child thread
	// group leader or a tracee under the conditions specified in the comment
	// above runExitNotify.
	EventExit waiter.EventMask = 1 << iota

	// EventChildGroupStop occurs when a child thread group completes a group
	// stop (i.e. all tasks in the child thread group have entered a stopped
	// state as a result of a group stop).
	EventChildGroupStop

	// EventTraceeStop occurs when a task that is ptraced by a task in the
	// notified thread group enters a ptrace stop (see ptrace(2)).
	EventTraceeStop

	// EventGroupContinue occurs when a child thread group, or a thread group
	// whose leader is ptraced by a task in the notified thread group, that had
	// initiated or completed a group stop leaves the group stop, due to the
	// child thread group or any task in the child thread group being sent
	// SIGCONT.
	EventGroupContinue
)

Task events that can be waited for.

View Source
const InvalidCgroupHierarchyID uint32 = 0

InvalidCgroupHierarchyID indicates an uninitialized hierarchy ID.

View Source
const InvalidCgroupID uint32 = 0

InvalidCgroupID indicates an uninitialized cgroup ID.

MaxFdLimit defines the upper limit on the integer value of file descriptors.

View Source
const SignalPanic = linux.SIGUSR2

SignalPanic is used to panic the running threads. It is a signal which cannot be used by the application: it must be caught and ignored by the runtime (in order to catch possible races).

View Source
const StraceEnableBits = StraceEnableLog | StraceEnableEvent

StraceEnableBits combines both strace log and event flags.

SupportedCloneFlags is the bitwise OR of all the supported flags for clone. TODO(b/290826530): Implement CLONE_INTO_CGROUP when cgroups v2 is implemented.

View Source
const TasksLimit = (1 << 16)

TasksLimit is the maximum number of threads for untrusted application. Linux doesn't really limit this directly, rather it is limited by total memory size, stacks allocated and a global maximum. There's no real reason for us to limit it either, (esp. since threads are backed by go routines), and we would expect to hit resource limits long before hitting this number. However, for correctness, we still check that the user doesn't exceed this number.

Note that because of the way futexes are implemented, there *are* in fact serious restrictions on valid thread IDs. They are limited to 2^30 - 1 (kernel/fork.c:MAX_THREADS).

Variables

View Source
var CgroupCtrls = []CgroupControllerType{"cpu", "cpuacct", "cpuset", "devices", "job", "memory", "pids"}

CgroupCtrls is the list of cgroup controllers.

View Source
var (
	// CtrlDoExit is returned by the implementations of the exit and exit_group
	// syscalls to enter the task exit path directly, skipping syscall exit
	// tracing.
	CtrlDoExit = &SyscallControl{next: (*runExit)(nil), ignoreReturn: true}
)
View Source
var ErrNoWaitableEvent = errors.New("non-blocking Wait found eligible threads but no waitable events")

ErrNoWaitableEvent is returned by non-blocking Task.Waits (e.g. waitpid(WNOHANG)) that find no waitable events, but determine that waitable events may exist in the future. (In contrast, if a non-blocking or blocking Wait determines that there are no tasks that can produce a waitable event, Task.Wait returns ECHILD.)

View Source
var IOUringEnabled = false

IOUringEnabled is set to true when IO_URING is enabled. Added as a global to allow easy access everywhere.

View Source
var MAX_RW_COUNT = int(hostarch.Addr(math.MaxInt32).RoundDown())

MAX_RW_COUNT is the maximum size in bytes of a single read or write. Reads and writes that exceed this size may be silently truncated. (Linux: include/linux/fs.h:MAX_RW_COUNT)

StopSignals is the set of signals whose default action is SignalActionStop.

UnblockableSignals contains the set of signals which cannot be blocked.

Functions

func ContextCanTrace

func ContextCanTrace(ctx context.Context, t *Task, attach bool) bool

ContextCanTrace returns true if ctx is permitted to trace t, in the same sense as kernel.Task.CanTrace.

func ExtractErrno

func ExtractErrno(err error, sysno int) int

ExtractErrno extracts an integer error number from the error. The syscall number is purely for context in the error case. Use -1 if syscall number is unknown.

func IncrementUnimplementedSyscallCounter

func IncrementUnimplementedSyscallCounter(sysno uintptr)

IncrementUnimplementedSyscallCounter increments the "unimplemented syscall" metric for the given syscall number. A syscall table must have been initialized prior to calling this function.

FIXME(gvisor.dev/issue/10556): checkescape can't distinguish between this file and files named syscalls.go in other directories, resulting in false positives, so this function cannot be +checkescape:all.

func LoadSeccheckData

func LoadSeccheckData(t *Task, mask seccheck.FieldMask, info *pb.ContextData)

LoadSeccheckData sets info from the task based on mask.

func LoadSeccheckDataLocked

func LoadSeccheckDataLocked(t *Task, mask seccheck.FieldMask, info *pb.ContextData, cwd string)

LoadSeccheckDataLocked sets info from the task based on mask.

Preconditions: The TaskSet mutex must be locked.

func RegisterSyscallTable

func RegisterSyscallTable(s *SyscallTable)

RegisterSyscallTable registers a new syscall table for use by a Kernel.

func SignalInfoNoInfo

func SignalInfoNoInfo(sig linux.Signal, sender, receiver *Task) *linux.SignalInfo

SignalInfoNoInfo returns a SignalInfo equivalent to Linux's SEND_SIG_NOINFO.

func SignalInfoPriv

func SignalInfoPriv(sig linux.Signal) *linux.SignalInfo

SignalInfoPriv returns a SignalInfo equivalent to Linux's SEND_SIG_PRIV.

Types

type AIOCallback

type AIOCallback func(context.Context)

AIOCallback is an function that does asynchronous I/O on behalf of a task.

type Auxmap

type Auxmap map[string]any

Auxmap contains miscellaneous data for the task.

type Cgroup

type Cgroup struct {
	*kernfs.Dentry
	CgroupImpl
}

Cgroup represents a named pointer to a cgroup in cgroupfs. When a task enters a cgroup, it holds a reference on the underlying dentry pointing to the cgroup.

+stateify savable

func (*Cgroup) Path

func (c *Cgroup) Path() string

Path returns the absolute path of c, relative to its hierarchy root.

func (*Cgroup) Walk

func (c *Cgroup) Walk(ctx context.Context, vfsObj *vfs.VirtualFilesystem, p fspath.Path) (Cgroup, error)

Walk returns the cgroup at p, starting from c.

type CgroupController

type CgroupController interface {
	// Returns the type of this cgroup controller (ex "memory", "cpu"). Returned
	// value is valid for the lifetime of the controller.
	Type() CgroupControllerType

	// Hierarchy returns the ID of the hierarchy this cgroup controller is
	// attached to. Returned value is valid for the lifetime of the controller.
	HierarchyID() uint32

	// EffectiveRootCgroup returns the effective root cgroup for this
	// controller. This is either the actual root of the underlying cgroupfs
	// filesystem, or the override root configured at sandbox startup. Returned
	// value is valid for the lifetime of the controller.
	EffectiveRootCgroup() Cgroup

	// NumCgroups returns the number of cgroups managed by this controller.
	// Returned value is a snapshot in time.
	NumCgroups() uint64

	// Enabled returns whether this controller is enabled. Returned value is a
	// snapshot in time.
	Enabled() bool
}

CgroupController is the common interface to cgroup controllers available to the entire sentry. The controllers themselves are defined by cgroupfs.

Callers of this interface are often unable access synchronization needed to ensure returned values remain valid. Some of values returned from this interface are thus snapshots in time, and may become stale. This is ok for many callers like procfs.

type CgroupControllerType

type CgroupControllerType string

CgroupControllerType is the name of a cgroup controller.

func ParseCgroupController

func ParseCgroupController(val string) (CgroupControllerType, error)

ParseCgroupController parses a string as a CgroupControllerType.

type CgroupImpl

type CgroupImpl interface {
	// Controllers lists the controller associated with this cgroup.
	Controllers() []CgroupController

	// HierarchyID returns the id of the hierarchy that contains this cgroup.
	HierarchyID() uint32

	// Name returns the name for this cgroup, if any. If no name was provided
	// when the hierarchy was created, returns "".
	Name() string

	// Enter moves t into this cgroup.
	Enter(t *Task)

	// Leave moves t out of this cgroup.
	Leave(t *Task)

	// PrepareMigrate initiates a migration of t from src to this cgroup. See
	// cgroupfs.controller.PrepareMigrate.
	PrepareMigrate(t *Task, src *Cgroup) error

	// CommitMigrate completes an in-flight migration. See
	// cgroupfs.controller.CommitMigrate.
	CommitMigrate(t *Task, src *Cgroup)

	// AbortMigrate cancels an in-flight migration. See
	// cgroupfs.controller.AbortMigrate.
	AbortMigrate(t *Task, src *Cgroup)

	// Charge charges a controller in this cgroup for a particular resource. key
	// must match a valid resource for the specified controller type.
	//
	// The implementer should silently succeed if no matching controllers are
	// found.
	//
	// The underlying implementation will panic if passed an incompatible
	// resource type for a given controller.
	//
	// See cgroupfs.controller.Charge.
	Charge(t *Task, d *kernfs.Dentry, ctl CgroupControllerType, res CgroupResourceType, value int64) error

	// ReadControlFromBackground allows a background context to read a cgroup's
	// control values.
	ReadControl(ctx context.Context, name string) (string, error)

	// WriteControl allows a background context to write a cgroup's control
	// values.
	WriteControl(ctx context.Context, name string, val string) error

	// ID returns the id of this cgroup.
	ID() uint32
}

CgroupImpl is the common interface to cgroups.

type CgroupMigrationContext

type CgroupMigrationContext struct {
	// contains filtered or unexported fields
}

CgroupMigrationContext represents an in-flight cgroup migration for a single task.

func (*CgroupMigrationContext) Abort

func (ctx *CgroupMigrationContext) Abort()

Abort cancels a migration.

func (*CgroupMigrationContext) Commit

func (ctx *CgroupMigrationContext) Commit()

Commit completes a migration.

type CgroupMount

type CgroupMount struct {
	Fs    *vfs.Filesystem
	Root  *vfs.Dentry
	Mount *vfs.Mount
}

CgroupMount contains the cgroup mount. These mounts are created for the root container by default and are stored in the kernel.

+stateify savable

type CgroupRegistry

type CgroupRegistry struct {
	// contains filtered or unexported fields
}

CgroupRegistry tracks the active set of cgroup controllers on the system.

+stateify savable

func (*CgroupRegistry) AddCgroup

func (r *CgroupRegistry) AddCgroup(cg CgroupImpl)

AddCgroup adds the ID and cgroup in the map.

func (*CgroupRegistry) FindCgroup

func (r *CgroupRegistry) FindCgroup(ctx context.Context, ctype CgroupControllerType, path string) (Cgroup, error)

FindCgroup locates a cgroup with the given parameters.

A cgroup is considered a match even if it contains other controllers on the same hierarchy.

func (*CgroupRegistry) FindHierarchy

func (r *CgroupRegistry) FindHierarchy(name string, ctypes []CgroupControllerType) (*vfs.Filesystem, error)

FindHierarchy returns a cgroup filesystem containing exactly the set of controllers named in ctypes, and optionally the name specified in name if it isn't empty. If no such FS is found, FindHierarchy return nil. FindHierarchy takes a reference on the returned FS, which is transferred to the caller.

func (*CgroupRegistry) GenerateProcCgroups

func (r *CgroupRegistry) GenerateProcCgroups(buf *bytes.Buffer)

GenerateProcCgroups writes the contents of /proc/cgroups to buf.

func (*CgroupRegistry) GetCgroup

func (r *CgroupRegistry) GetCgroup(cid uint32) (CgroupImpl, error)

GetCgroup returns the cgroup associated with the cgroup ID.

func (*CgroupRegistry) NextCgroupID

func (r *CgroupRegistry) NextCgroupID() (uint32, error)

NextCgroupID returns a newly allocated, unique cgroup ID.

func (*CgroupRegistry) Register

func (r *CgroupRegistry) Register(name string, cs []CgroupController, fs cgroupFS) error

Register registers the provided set of controllers with the registry as a new hierarchy. If any controller is already registered, the function returns an error without modifying the registry. Register sets the hierarchy ID for the filesystem on success.

func (*CgroupRegistry) Unregister

func (r *CgroupRegistry) Unregister(hid uint32)

Unregister removes a previously registered hierarchy from the registry. If no such hierarchy is registered, Unregister is a no-op.

type CgroupResourceType

type CgroupResourceType int

CgroupResourceType represents a resource type tracked by a particular controller.

const (
	// CgroupResourcePID represents a charge for pids.current.
	CgroupResourcePID CgroupResourceType = iota
)

Resources for the cpuacct controller.

type CreateProcessArgs

type CreateProcessArgs struct {
	// Filename is the filename to load as the init binary.
	//
	// If this is provided as "", File will be checked, then the file will be
	// guessed via Argv[0].
	Filename string

	// File is a passed host FD pointing to a file to load as the init binary.
	//
	// This is checked if and only if Filename is "".
	File *vfs.FileDescription

	// Argv is a list of arguments.
	Argv []string

	// Envv is a list of environment variables.
	Envv []string

	// WorkingDirectory is the initial working directory.
	//
	// This defaults to the root if empty.
	WorkingDirectory string

	// Credentials is the initial credentials.
	Credentials *auth.Credentials

	// FDTable is the initial set of file descriptors. If CreateProcess succeeds,
	// it takes a reference on FDTable.
	FDTable *FDTable

	// Umask is the initial umask.
	Umask uint

	// Limits are the initial resource limits.
	Limits *limits.LimitSet

	// MaxSymlinkTraversals is the maximum number of symlinks to follow
	// during resolution.
	MaxSymlinkTraversals uint

	// UTSNamespace is the initial UTS namespace.
	UTSNamespace *UTSNamespace

	// IPCNamespace is the initial IPC namespace.
	IPCNamespace *IPCNamespace

	// PIDNamespace is the initial PID Namespace.
	PIDNamespace *PIDNamespace

	// MountNamespace optionally contains the mount namespace for this
	// process. If nil, the init process's mount namespace is used.
	//
	// Anyone setting MountNamespace must donate a reference (i.e.
	// increment it).
	MountNamespace *vfs.MountNamespace

	// ContainerID is the container that the process belongs to.
	ContainerID string

	// InitialCgroups are the cgroups the container is initialized to.
	InitialCgroups map[Cgroup]struct{}

	// Origin indicates how the task was first created.
	Origin TaskOrigin

	// TTY is the optional controlling TTY to associate with this process.
	TTY *TTY
}

CreateProcessArgs holds arguments to kernel.CreateProcess.

func (*CreateProcessArgs) NewContext

func (args *CreateProcessArgs) NewContext(k *Kernel) context.Context

NewContext returns a context.Context that represents the task that will be created by args.NewContext(k).

type FDFlags

type FDFlags struct {
	// CloseOnExec indicates the descriptor should be closed on exec.
	CloseOnExec bool
}

FDFlags define flags for an individual descriptor.

+stateify savable

func (FDFlags) ToLinuxFDFlags

func (f FDFlags) ToLinuxFDFlags() (mask uint)

ToLinuxFDFlags converts a kernel.FDFlags object to a Linux descriptor flags representation.

func (FDFlags) ToLinuxFileFlags

func (f FDFlags) ToLinuxFileFlags() (mask uint)

ToLinuxFileFlags converts a kernel.FDFlags object to a Linux file flags representation.

type FDTable

type FDTable struct {
	FDTableRefs
	// contains filtered or unexported fields
}

FDTable is used to manage File references and flags.

+stateify savable

func (*FDTable) CurrentMaxFDs

func (f *FDTable) CurrentMaxFDs() int

CurrentMaxFDs returns the number of file descriptors that may be stored in f without reallocation.

func (*FDTable) DecRef

func (f *FDTable) DecRef(ctx context.Context)

DecRef implements RefCounter.DecRef.

If f reaches zero references, all of its file descriptors are removed.

func (*FDTable) Exists

func (f *FDTable) Exists(fd int32) bool

Exists returns whether fd is defined in the table. It is inherently racy.

func (*FDTable) ForEach

func (f *FDTable) ForEach(ctx context.Context, fn func(fd int32, file *vfs.FileDescription, flags FDFlags) bool)

ForEach iterates over all non-nil files upto maxFd in sorted order.

It is the caller's responsibility to acquire an appropriate lock.

func (*FDTable) Fork

func (f *FDTable) Fork(ctx context.Context, maxFd int32) *FDTable

Fork returns an independent FDTable, cloning all FDs up to maxFds (non-inclusive).

func (*FDTable) Get

func (f *FDTable) Get(fd int32) (*vfs.FileDescription, FDFlags)

Get returns a reference to the file and the flags for the FD or nil if no file is defined for the given fd.

N.B. Callers are required to use DecRef when they are done.

func (*FDTable) GetFDs

func (f *FDTable) GetFDs(ctx context.Context) []int32

GetFDs returns a sorted list of valid fds.

Precondition: The caller must be running on the task goroutine, or Task.mu must be locked.

func (*FDTable) GetLastFd

func (f *FDTable) GetLastFd() int32

GetLastFd returns the last set FD in the FDTable bitmap.

func (*FDTable) NewFD

func (f *FDTable) NewFD(ctx context.Context, minFD int32, file *vfs.FileDescription, flags FDFlags) (int32, error)

NewFD allocates a file descriptor greater than or equal to minFD for the given file description. If it succeeds, it takes a reference on file.

func (*FDTable) NewFDAt

func (f *FDTable) NewFDAt(ctx context.Context, fd int32, file *vfs.FileDescription, flags FDFlags) (*vfs.FileDescription, error)

NewFDAt sets the file reference for the given FD. If there is an existing file description for that FD, it is returned.

N.B. Callers are required to use DecRef on the returned file when they are done.

Precondition: file != nil.

func (*FDTable) NewFDs

func (f *FDTable) NewFDs(ctx context.Context, minFD int32, files []*vfs.FileDescription, flags FDFlags) (fds []int32, err error)

NewFDs allocates new FDs guaranteed to be the lowest number available greater than or equal to the minFD parameter. All files will share the set flags. Success is guaranteed to be all or none.

func (*FDTable) Remove

func (f *FDTable) Remove(ctx context.Context, fd int32) *vfs.FileDescription

Remove removes an FD from f. It returns the removed file description.

N.B. Callers are required to use DecRef on the returned file when they are done.

func (*FDTable) RemoveIf

func (f *FDTable) RemoveIf(ctx context.Context, cond func(*vfs.FileDescription, FDFlags) bool)

RemoveIf removes all FDs where cond is true.

func (*FDTable) RemoveNextInRange

func (f *FDTable) RemoveNextInRange(ctx context.Context, startFd int32, endFd int32) (int32, *vfs.FileDescription)

RemoveNextInRange removes the next FD that falls within the given range, and returns the FD number and FileDescription of the removed FD.

N.B. Callers are required to use DecRef on the returned file when they are done.

func (*FDTable) SetFlags

func (f *FDTable) SetFlags(ctx context.Context, fd int32, flags FDFlags) error

SetFlags sets the flags for the given file descriptor.

True is returned iff flags were changed.

func (*FDTable) SetFlagsForRange

func (f *FDTable) SetFlagsForRange(ctx context.Context, startFd int32, endFd int32, flags FDFlags) error

SetFlagsForRange sets the flags for the given range of file descriptors (inclusive: [startFd, endFd]).

func (*FDTable) String

func (f *FDTable) String() string

String is a stringer for FDTable.

type FSContext

type FSContext struct {
	FSContextRefs
	// contains filtered or unexported fields
}

FSContext contains filesystem context.

This includes umask and working directory.

+stateify savable

func NewFSContext

func NewFSContext(root, cwd vfs.VirtualDentry, umask uint) *FSContext

NewFSContext returns a new filesystem context.

func (*FSContext) DecRef

func (f *FSContext) DecRef(ctx context.Context)

DecRef implements RefCounter.DecRef.

When f reaches zero references, DecRef will be called on both root and cwd Dirents.

Note that there may still be calls to WorkingDirectory() or RootDirectory() (that return nil). This is because valid references may still be held via proc files or other mechanisms.

func (*FSContext) Fork

func (f *FSContext) Fork() *FSContext

Fork forks this FSContext.

This is not a valid call after f is destroyed.

func (*FSContext) RootDirectory

func (f *FSContext) RootDirectory() vfs.VirtualDentry

RootDirectory returns the current filesystem root.

This will return an empty vfs.VirtualDentry if called after f is destroyed, otherwise it will return a Dirent with a reference taken.

func (*FSContext) SetRootDirectory

func (f *FSContext) SetRootDirectory(ctx context.Context, vd vfs.VirtualDentry)

SetRootDirectory sets the root directory. It takes a reference on vd.

This is not a valid call after f is destroyed.

func (*FSContext) SetWorkingDirectory

func (f *FSContext) SetWorkingDirectory(ctx context.Context, d vfs.VirtualDentry)

SetWorkingDirectory sets the current working directory. This will take an extra reference on the VirtualDentry.

This is not a valid call after f is destroyed.

func (*FSContext) SwapUmask

func (f *FSContext) SwapUmask(mask uint) uint

SwapUmask atomically sets the current umask and returns the old umask.

func (*FSContext) Umask

func (f *FSContext) Umask() uint

Umask returns the current umask.

func (*FSContext) WorkingDirectory

func (f *FSContext) WorkingDirectory() vfs.VirtualDentry

WorkingDirectory returns the current working directory.

This will return an empty vfs.VirtualDentry if called after f is destroyed, otherwise it will return a Dirent with a reference taken.

type IPCNamespace

type IPCNamespace struct {
	// contains filtered or unexported fields
}

IPCNamespace represents an IPC namespace.

+stateify savable

func IPCNamespaceFromContext

func IPCNamespaceFromContext(ctx context.Context) *IPCNamespace

IPCNamespaceFromContext returns the IPC namespace in which ctx is executing, or nil if there is no such IPC namespace. It takes a reference on the namespace.

func NewIPCNamespace

func NewIPCNamespace(userNS *auth.UserNamespace) *IPCNamespace

NewIPCNamespace creates a new IPC namespace.

func (*IPCNamespace) DecRef

func (i *IPCNamespace) DecRef(ctx context.Context)

DecRef decrements the namespace's refcount.

func (*IPCNamespace) Destroy

func (i *IPCNamespace) Destroy(ctx context.Context)

Destroy implements nsfs.Namespace.Destroy.

func (*IPCNamespace) GetInode

func (i *IPCNamespace) GetInode() *nsfs.Inode

GetInode returns the nsfs inode associated with the IPC namespace.

func (*IPCNamespace) IncRef

func (i *IPCNamespace) IncRef()

IncRef increments the Namespace's refcount.

func (*IPCNamespace) InitPosixQueues

func (i *IPCNamespace) InitPosixQueues(ctx context.Context, vfsObj *vfs.VirtualFilesystem, creds *auth.Credentials) error

InitPosixQueues creates a new POSIX queue registry, and returns an error if the registry was previously initialized.

func (*IPCNamespace) MsgqueueRegistry

func (i *IPCNamespace) MsgqueueRegistry() *msgqueue.Registry

MsgqueueRegistry returns the message queue registry for this namespace.

func (*IPCNamespace) PosixQueues

func (i *IPCNamespace) PosixQueues() *mq.Registry

PosixQueues returns the posix message queue registry for this namespace.

Precondition: i.InitPosixQueues must have been called.

func (*IPCNamespace) SemaphoreRegistry

func (i *IPCNamespace) SemaphoreRegistry() *semaphore.Registry

SemaphoreRegistry returns the semaphore set registry for this namespace.

func (*IPCNamespace) SetInode

func (i *IPCNamespace) SetInode(inode *nsfs.Inode)

SetInode sets the nsfs `inode` to the IPC namespace.

func (*IPCNamespace) ShmRegistry

func (i *IPCNamespace) ShmRegistry() *shm.Registry

ShmRegistry returns the shm segment registry for this namespace.

func (*IPCNamespace) Type

func (i *IPCNamespace) Type() string

Type implements nsfs.Namespace.Type.

func (*IPCNamespace) UserNamespace

func (i *IPCNamespace) UserNamespace() *auth.UserNamespace

UserNamespace returns the user namespace associated with the namespace.

type InitKernelArgs

type InitKernelArgs struct {
	// FeatureSet is the emulated CPU feature set.
	FeatureSet cpuid.FeatureSet

	// Timekeeper manages time for all tasks in the system.
	Timekeeper *Timekeeper

	// RootUserNamespace is the root user namespace.
	RootUserNamespace *auth.UserNamespace

	// RootNetworkNamespace is the root network namespace. If nil, no networking
	// will be available.
	RootNetworkNamespace *inet.Namespace

	// ApplicationCores is the number of logical CPUs visible to sandboxed
	// applications. The set of logical CPU IDs is [0, ApplicationCores); thus
	// ApplicationCores is analogous to Linux's nr_cpu_ids, the index of the
	// most significant bit in cpu_possible_mask + 1.
	ApplicationCores uint

	// If UseHostCores is true, Task.CPU() returns the task goroutine's CPU
	// instead of a virtualized CPU number, and Task.CopyToCPUMask() is a
	// no-op. If ApplicationCores is less than hostcpu.MaxPossibleCPU(), it
	// will be overridden.
	UseHostCores bool

	// ExtraAuxv contains additional auxiliary vector entries that are added to
	// each process by the ELF loader.
	ExtraAuxv []arch.AuxEntry

	// Vdso holds the VDSO and its parameter page.
	Vdso *loader.VDSO

	// VdsoParams is the VDSO parameter page manager.
	VdsoParams *VDSOParamPage

	// RootUTSNamespace is the root UTS namespace.
	RootUTSNamespace *UTSNamespace

	// RootIPCNamespace is the root IPC namespace.
	RootIPCNamespace *IPCNamespace

	// PIDNamespace is the root PID namespace.
	PIDNamespace *PIDNamespace

	// MaxFDLimit specifies the maximum file descriptor number that can be
	// used by processes.  If it is zero, the limit will be set to
	// unlimited.
	MaxFDLimit int32

	// UnixSocketOpts contains configuration options for unix sockets.
	UnixSocketOpts transport.UnixSocketOpts
}

InitKernelArgs holds arguments to Init.

type IntervalTimer

type IntervalTimer struct {
	// contains filtered or unexported fields
}

IntervalTimer represents a POSIX interval timer as described by timer_create(2).

+stateify savable

func (*IntervalTimer) DestroyTimer

func (it *IntervalTimer) DestroyTimer()

DestroyTimer releases it's resources.

func (*IntervalTimer) NotifyTimer

func (it *IntervalTimer) NotifyTimer(exp uint64)

NotifyTimer implements ktime.TimerListener.NotifyTimer.

func (*IntervalTimer) PauseTimer

func (it *IntervalTimer) PauseTimer()

PauseTimer pauses the associated Timer.

func (*IntervalTimer) ResumeTimer

func (it *IntervalTimer) ResumeTimer()

ResumeTimer resumes the associated Timer.

type Kcov

type Kcov struct {
	// contains filtered or unexported fields
}

Kcov provides kernel coverage data to userspace through a memory-mapped region, as kcov does in Linux.

To give the illusion that the data is always up to date, we update the shared memory every time before we return to userspace.

func (*Kcov) Clear

func (kcov *Kcov) Clear(ctx context.Context)

Clear resets the mode and clears the owning task and memory mapping for kcov. It is called when the fd corresponding to kcov is closed. Note that the mode needs to be set so that the next call to kcov.TaskWork() will exit early.

func (*Kcov) ConfigureMMap

func (kcov *Kcov) ConfigureMMap(ctx context.Context, opts *memmap.MMapOpts) error

ConfigureMMap is called by the vfs.FileDescription for this kcov instance to implement vfs.FileDescription.ConfigureMMap.

func (*Kcov) DisableTrace

func (kcov *Kcov) DisableTrace(ctx context.Context) error

DisableTrace performs the KCOV_DISABLE_TRACE ioctl.

func (*Kcov) EnableTrace

func (kcov *Kcov) EnableTrace(ctx context.Context, traceKind uint8) error

EnableTrace performs the KCOV_ENABLE_TRACE ioctl.

func (*Kcov) InitTrace

func (kcov *Kcov) InitTrace(size uint64) error

InitTrace performs the KCOV_INIT_TRACE ioctl.

func (*Kcov) OnTaskExit

func (kcov *Kcov) OnTaskExit()

OnTaskExit is called when the owning task exits. It is similar to kcov.Clear(), except the memory mapping is not cleared, so that the same mapping can be used in the future if kcov is enabled again by another task.

func (*Kcov) TaskWork

func (kcov *Kcov) TaskWork(t *Task)

TaskWork implements TaskWorker.TaskWork.

type Kernel

type Kernel struct {

	// Platform is the platform that is used to execute tasks in the created
	// Kernel.
	platform.Platform `state:"nosave"`

	// SpecialOpts contains special kernel options.
	SpecialOpts

	// If set to true, report address space activation waits as if the task is in
	// external wait so that the watchdog doesn't report the task stuck.
	SleepForAddressSpaceActivation bool

	// YAMAPtraceScope is the current level of YAMA ptrace restrictions.
	YAMAPtraceScope atomicbitops.Int32

	// MaxFDLimit specifies the maximum file descriptor number that can be
	// used by processes.
	MaxFDLimit atomicbitops.Int32

	// UnixSocketOpts stores configuration options for management of unix sockets.
	UnixSocketOpts transport.UnixSocketOpts
	// contains filtered or unexported fields
}

Kernel represents an emulated Linux kernel. It must be initialized by calling Init() or LoadFrom().

+stateify savable

func KernelFromContext

func KernelFromContext(ctx context.Context) *Kernel

KernelFromContext returns the Kernel in which ctx is executing, or nil if there is no such Kernel.

func (*Kernel) AddCgroupMount

func (k *Kernel) AddCgroupMount(ctl string, mnt *CgroupMount)

AddCgroupMount adds the cgroup mounts to the cgroupMountsMap. These cgroup mounts are created during the creation of root container process and the reference ownership is transferred to the kernel.

func (*Kernel) AddDevGofer

func (k *Kernel) AddDevGofer(contName string, goferFD int) error

AddDevGofer initializes the dev gofer connection and starts tracking it. It takes ownership of goferFD.

func (*Kernel) AddStateToCheckpoint

func (k *Kernel) AddStateToCheckpoint(key, v any)

AddStateToCheckpoint adds a key-value pair to be additionally checkpointed.

func (*Kernel) ApplicationCores

func (k *Kernel) ApplicationCores() uint

ApplicationCores returns the number of CPUs visible to sandboxed applications.

func (*Kernel) CPUClockNow

func (k *Kernel) CPUClockNow() ktime.Time

CPUClockNow returns the current value of the kernel CPU clock, which coarsely approximates wall time but is suspended when no tasks are running.

func (*Kernel) CgroupRegistry

func (k *Kernel) CgroupRegistry() *CgroupRegistry

CgroupRegistry returns the cgroup registry.

func (*Kernel) CheckpointCount

func (k *Kernel) CheckpointCount() uint32

CheckpointCount returns the current checkpoint count. Note that the result may be stale by the time the caller uses it.

func (*Kernel) ContainerName

func (k *Kernel) ContainerName(cid string) string

ContainerName returns the container name for a given container ID.

func (*Kernel) CreateProcess

func (k *Kernel) CreateProcess(args CreateProcessArgs) (*ThreadGroup, ThreadID, error)

CreateProcess creates a new task in a new thread group with the given options. The new task has no parent and is in the root PID namespace.

If k.Start() has already been called, then the created process must be started by calling kernel.StartProcess(tg).

If k.Start() has not yet been called, then the created task will begin running when k.Start() is called.

CreateProcess has no analogue in Linux; it is used to create the initial application task, as well as processes started by the control server.

func (*Kernel) Deadline

func (*Kernel) Deadline() (time.Time, bool)

Deadline implements context.Context.Deadline.

func (*Kernel) DeleteSocket

func (k *Kernel) DeleteSocket(sock *vfs.FileDescription)

DeleteSocket removes a socket from the system-wide socket table.

func (*Kernel) Done

func (*Kernel) Done() <-chan struct{}

Done implements context.Context.Done.

func (*Kernel) EmitUnimplementedEvent

func (k *Kernel) EmitUnimplementedEvent(ctx context.Context, sysno uintptr)

EmitUnimplementedEvent emits an UnimplementedSyscall event via the event channel.

func (*Kernel) Err

func (*Kernel) Err() error

Err implements context.Context.Err.

func (*Kernel) FeatureSet

func (k *Kernel) FeatureSet() cpuid.FeatureSet

FeatureSet returns the FeatureSet.

func (*Kernel) GenerateInotifyCookie

func (k *Kernel) GenerateInotifyCookie() uint32

GenerateInotifyCookie generates a unique inotify event cookie.

Returned values may overlap with previously returned values if the value space is exhausted. 0 is not a valid cookie value, all other values representable in a uint32 are allowed.

func (*Kernel) GetCgroupMount

func (k *Kernel) GetCgroupMount(ctl string) *CgroupMount

GetCgroupMount returns the cgroup mount for the given cgroup controller.

func (*Kernel) GetDevGoferClient

func (k *Kernel) GetDevGoferClient(contName string) *devutil.GoferClient

GetDevGoferClient implements devutil.GoferClientProviderFromContext.GetDevGoferClient.

func (*Kernel) GetNamespaceInode

func (k *Kernel) GetNamespaceInode(ctx context.Context, ns vfs.Namespace) refs.TryRefCounter

GetNamespaceInode returns a new nsfs inode which serves as a reference counter for the namespace.

func (*Kernel) GetUserCounters

func (k *Kernel) GetUserCounters(uid auth.KUID) *UserCounters

GetUserCounters returns the user counters for the given KUID.

func (*Kernel) GlobalInit

func (k *Kernel) GlobalInit() *ThreadGroup

GlobalInit returns the thread group with ID 1 in the root PID namespace, or nil if no such thread group exists. GlobalInit may return a thread group containing no tasks if the thread group has already exited.

func (*Kernel) HostMount

func (k *Kernel) HostMount() *vfs.Mount

HostMount returns the hostfs mount.

func (*Kernel) IncCheckpointCount

func (k *Kernel) IncCheckpointCount()

IncCheckpointCount increments the checkpoint counter.

func (*Kernel) Init

func (k *Kernel) Init(args InitKernelArgs) error

Init initialize the Kernel with no tasks.

Callers must manually set Kernel.Platform and call Kernel.SetMemoryFile before calling Init.

func (*Kernel) IsPaused

func (k *Kernel) IsPaused() bool

IsPaused returns true if the kernel is currently paused.

func (*Kernel) Kill

func (k *Kernel) Kill(ws linux.WaitStatus)

Kill requests that all tasks in k immediately exit as if group exiting with status ws. Kill does not wait for tasks to exit.

func (*Kernel) ListSockets

func (k *Kernel) ListSockets() []*SocketRecord

ListSockets returns a snapshot of all sockets.

Callers of ListSockets() should use SocketRecord.Sock.TryIncRef() to get a reference on a socket in the table.

func (*Kernel) LoadFrom

func (k *Kernel) LoadFrom(ctx context.Context, r, pagesMetadata io.Reader, pagesFile *fd.FD, background bool, timeReady chan struct{}, net inet.Stack, clocks sentrytime.Clocks, vfsOpts *vfs.CompleteRestoreOptions, saveRestoreNet bool) error

LoadFrom returns a new Kernel loaded from args.

LoadFrom takes ownership of pagesFile.

func (*Kernel) LoadTaskImage

func (k *Kernel) LoadTaskImage(ctx context.Context, args loader.LoadArgs) (*TaskImage, *syserr.Error)

LoadTaskImage loads a specified file into a new TaskImage.

args.MemoryManager does not need to be set by the caller.

func (*Kernel) MemoryFile

func (k *Kernel) MemoryFile() *pgalloc.MemoryFile

MemoryFile returns the MemoryFile that provides application memory.

func (*Kernel) MonotonicClock

func (k *Kernel) MonotonicClock() ktime.SampledClock

MonotonicClock returns the application CLOCK_MONOTONIC clock.

func (*Kernel) NetlinkPorts

func (k *Kernel) NetlinkPorts() *port.Manager

NetlinkPorts returns the netlink port manager.

func (*Kernel) NewFDTable

func (k *Kernel) NewFDTable() *FDTable

NewFDTable allocates a new FDTable that may be used by tasks in k.

func (*Kernel) NewKcov

func (k *Kernel) NewKcov() *Kcov

NewKcov creates and returns a Kcov instance.

func (*Kernel) NewThreadGroup

func (k *Kernel) NewThreadGroup(pidns *PIDNamespace, sh *SignalHandlers, terminationSignal linux.Signal, limits *limits.LimitSet) *ThreadGroup

NewThreadGroup returns a new, empty thread group in PID namespace pidns. The thread group leader will send its parent terminationSignal when it exits. The new thread group isn't visible to the system until a task has been created inside of it by a successful call to TaskSet.NewTask.

func (*Kernel) OnCheckpointAttempt

func (k *Kernel) OnCheckpointAttempt(err error)

OnCheckpointAttempt is called when a checkpoint attempt is completed. err is any checkpoint errors that may have occurred.

func (*Kernel) Pause

func (k *Kernel) Pause()

Pause requests that all tasks in k temporarily stop executing, and blocks until all tasks and asynchronous I/O operations in k have stopped. Multiple calls to Pause nest and require an equal number of calls to Unpause to resume execution.

func (*Kernel) PipeMount

func (k *Kernel) PipeMount() *vfs.Mount

PipeMount returns the pipefs mount.

func (*Kernel) PopCheckpointState

func (k *Kernel) PopCheckpointState(key any) any

PopCheckpointState pops a key-value pair from the additional checkpoint state. If the key doesn't exist, nil is returned.

func (*Kernel) PopulateNewCgroupHierarchy

func (k *Kernel) PopulateNewCgroupHierarchy(root Cgroup)

PopulateNewCgroupHierarchy moves all tasks into a newly created cgroup hierarchy.

Precondition: root must be a new cgroup with no tasks. This implies the controllers for root are also new and currently manage no task, which in turn implies the new cgroup can be populated without migrating tasks between cgroups.

func (*Kernel) RealtimeClock

func (k *Kernel) RealtimeClock() ktime.SampledClock

RealtimeClock returns the application CLOCK_REALTIME clock.

func (*Kernel) RebuildTraceContexts

func (k *Kernel) RebuildTraceContexts()

RebuildTraceContexts rebuilds the trace context for all tasks.

Unfortunately, if these are built while tracing is not enabled, then we will not have meaningful trace data. Rebuilding here ensures that we can do so after tracing has been enabled.

func (*Kernel) ReceiveTaskStates

func (k *Kernel) ReceiveTaskStates()

ReceiveTaskStates receives full states for all tasks.

func (*Kernel) RecordSocket

func (k *Kernel) RecordSocket(sock *vfs.FileDescription)

RecordSocket adds a socket to the system-wide socket table for tracking.

Precondition: Caller must hold a reference to sock.

Note that the socket table will not hold a reference on the vfs.FileDescription.

func (*Kernel) RegisterContainerName

func (k *Kernel) RegisterContainerName(cid, containerName string)

RegisterContainerName registers a container name for a given container ID.

func (*Kernel) Release

func (k *Kernel) Release()

Release releases resources owned by k.

Precondition: This should only be called after the kernel is fully initialized, e.g. after k.Start() has been called.

func (*Kernel) ReleaseCgroupHierarchy

func (k *Kernel) ReleaseCgroupHierarchy(hid uint32)

ReleaseCgroupHierarchy moves all tasks out of all cgroups belonging to the hierarchy with the provided id. This is intended for use during hierarchy teardown, as otherwise the tasks would be orphaned w.r.t to some controllers.

func (*Kernel) RemoveDevGofer

func (k *Kernel) RemoveDevGofer(contName string)

RemoveDevGofer closes the dev gofer connection, if one exists, and stops tracking it.

func (*Kernel) ReplaceFSContextRoots

func (k *Kernel) ReplaceFSContextRoots(ctx context.Context, oldRoot vfs.VirtualDentry, newRoot vfs.VirtualDentry)

ReplaceFSContextRoots updates root and cwd to `newRoot` in the FSContext across all tasks whose old root or cwd were `oldRoot`.

func (*Kernel) ResetCheckpointStatus

func (k *Kernel) ResetCheckpointStatus()

ResetCheckpointStatus resets the last checkpoint status, indicating a new checkpoint is in progress. Caller must call OnCheckpointAttempt when the checkpoint attempt is completed.

func (*Kernel) RestoreContainerMapping

func (k *Kernel) RestoreContainerMapping(containerIDs map[string]string)

RestoreContainerMapping remaps old container IDs to new ones after a restore. containerIDs maps "name -> new container ID". Note that container names remain constant between restore sessions.

func (*Kernel) RootIPCNamespace

func (k *Kernel) RootIPCNamespace() *IPCNamespace

RootIPCNamespace takes a reference and returns the root IPCNamespace.

func (*Kernel) RootNetworkNamespace

func (k *Kernel) RootNetworkNamespace() *inet.Namespace

RootNetworkNamespace returns the root network namespace, always non-nil.

func (*Kernel) RootPIDNamespace

func (k *Kernel) RootPIDNamespace() *PIDNamespace

RootPIDNamespace returns the root PIDNamespace.

func (*Kernel) RootUTSNamespace

func (k *Kernel) RootUTSNamespace() *UTSNamespace

RootUTSNamespace returns the root UTSNamespace.

func (*Kernel) RootUserNamespace

func (k *Kernel) RootUserNamespace() *auth.UserNamespace

RootUserNamespace returns the root UserNamespace.

func (*Kernel) SaveStatus

func (k *Kernel) SaveStatus() (saved, autosaved bool, err error)

SaveStatus returns the sandbox save status. If it was saved successfully, autosaved indicates whether save was triggered by autosave. If it was not saved successfully, err indicates the sandbox error that caused the kernel to exit during save.

func (*Kernel) SaveTo

func (k *Kernel) SaveTo(ctx context.Context, w, pagesMetadata io.Writer, pagesFile *fd.FD, mfOpts pgalloc.SaveOpts) error

SaveTo saves the state of k to w.

Preconditions: The kernel must be paused throughout the call to SaveTo.

func (*Kernel) Saver

func (k *Kernel) Saver() Saver

Saver returns the kernel's Saver. Thread-compatible.

func (*Kernel) SendContainerSignal

func (k *Kernel) SendContainerSignal(cid string, info *linux.SignalInfo) error

SendContainerSignal sends the given signal to all processes inside the namespace that match the given container ID.

func (*Kernel) SendExternalSignal

func (k *Kernel) SendExternalSignal(info *linux.SignalInfo, context string)

SendExternalSignal injects a signal into the kernel.

context is used only for debugging to describe how the signal was received.

Preconditions: Kernel must have an init process.

func (*Kernel) SendExternalSignalProcessGroup

func (k *Kernel) SendExternalSignalProcessGroup(pg *ProcessGroup, info *linux.SignalInfo) error

SendExternalSignalProcessGroup sends a signal to all ThreadGroups in the given process group.

This function doesn't skip signals like SendExternalSignal does.

func (*Kernel) SendExternalSignalThreadGroup

func (k *Kernel) SendExternalSignalThreadGroup(tg *ThreadGroup, info *linux.SignalInfo) error

SendExternalSignalThreadGroup injects a signal into an specific ThreadGroup.

This function doesn't skip signals like SendExternalSignal does.

func (*Kernel) SetHostMount

func (k *Kernel) SetHostMount(mnt *vfs.Mount)

SetHostMount sets the hostfs mount.

func (*Kernel) SetMemoryFile

func (k *Kernel) SetMemoryFile(mf *pgalloc.MemoryFile)

SetMemoryFile sets Kernel.mf. SetMemoryFile must be called before Init or LoadFrom.

func (*Kernel) SetSaveError

func (k *Kernel) SetSaveError(err error)

SetSaveError sets the sandbox error that caused the kernel to exit during save, if one is not already set.

func (*Kernel) SetSaveSuccess

func (k *Kernel) SetSaveSuccess(autosave bool)

SetSaveSuccess sets the flag indicating that save completed successfully, if no status was already set.

func (*Kernel) SetSaver

func (k *Kernel) SetSaver(s Saver)

SetSaver sets the kernel's Saver. Thread-compatible.

func (*Kernel) ShmMount

func (k *Kernel) ShmMount() *vfs.Mount

ShmMount returns the tmpfs mount.

func (*Kernel) SocketMount

func (k *Kernel) SocketMount() *vfs.Mount

SocketMount returns the sockfs mount.

func (*Kernel) Start

func (k *Kernel) Start() error

Start starts execution of all tasks in k.

Preconditions: Start may be called exactly once.

func (*Kernel) StartProcess

func (k *Kernel) StartProcess(tg *ThreadGroup)

StartProcess starts running a process that was created with CreateProcess.

func (*Kernel) SupervisorContext

func (k *Kernel) SupervisorContext() context.Context

SupervisorContext returns a Context with maximum privileges in k. It should only be used by goroutines outside the control of the emulated kernel defined by e.

Callers are responsible for ensuring that the returned Context is not used concurrently with changes to the Kernel.

func (*Kernel) Syslog

func (k *Kernel) Syslog() *syslog

Syslog returns the syslog.

func (*Kernel) TaskSet

func (k *Kernel) TaskSet() *TaskSet

TaskSet returns the TaskSet.

func (*Kernel) TestOnlySetGlobalInit

func (k *Kernel) TestOnlySetGlobalInit(tg *ThreadGroup)

TestOnlySetGlobalInit sets the thread group with ID 1 in the root PID namespace.

func (*Kernel) Timekeeper

func (k *Kernel) Timekeeper() *Timekeeper

Timekeeper returns the Timekeeper.

func (*Kernel) UniqueID

func (k *Kernel) UniqueID() uint64

UniqueID returns a unique identifier.

func (*Kernel) Unpause

func (k *Kernel) Unpause()

Unpause ends the effect of a previous call to Pause. If Unpause is called without a matching preceding call to Pause, Unpause may panic.

func (*Kernel) VFS

func (k *Kernel) VFS() *vfs.VirtualFilesystem

VFS returns the virtual filesystem for the kernel.

func (*Kernel) WaitCheckpoint

func (k *Kernel) WaitCheckpoint(n uint32) error

WaitCheckpoint waits for the Kernel to have been successfully checkpointed n-1 times, then waits for either the n-th successful checkpoint (in which case it returns nil) or any number of failed checkpoints (in which case it returns an error returned by any such failure).

func (*Kernel) WaitExited

func (k *Kernel) WaitExited()

WaitExited blocks until all tasks in k have exited. No tasks can be created after WaitExited returns.

type MissingFn

type MissingFn func(t *Task, sysno uintptr, args arch.SyscallArguments) (uintptr, error)

MissingFn is a syscall to be called when an implementation is missing.

type OldRSeqCriticalRegion

type OldRSeqCriticalRegion struct {
	// When a task in this thread group has its CPU preempted (as defined by
	// platform.ErrContextCPUPreempted) or has a signal delivered to an
	// application handler while its instruction pointer is in CriticalSection,
	// set the instruction pointer to Restart and application register r10 (on
	// amd64) to the former instruction pointer.
	CriticalSection hostarch.AddrRange
	Restart         hostarch.Addr
}

OldRSeqCriticalRegion describes an old rseq critical region.

+stateify savable

type PIDNamespace

type PIDNamespace struct {
	// contains filtered or unexported fields
}

A PIDNamespace represents a PID namespace, a bimap between thread IDs and tasks. See the pid_namespaces(7) man page for further details.

N.B. A task is said to be visible in a PID namespace if the PID namespace contains a thread ID that maps to that task.

+stateify savable

func NewRootPIDNamespace

func NewRootPIDNamespace(userns *auth.UserNamespace) *PIDNamespace

NewRootPIDNamespace creates the root PID namespace. 'owner' is not available yet when root namespace is created and must be set by caller.

func PIDNamespaceFromContext

func PIDNamespaceFromContext(ctx context.Context) *PIDNamespace

PIDNamespaceFromContext returns the PID namespace in which ctx is executing, or nil if there is no such PID namespace.

func (*PIDNamespace) ID

func (ns *PIDNamespace) ID() uint64

ID returns a non-zero ID that is unique across PID namespaces.

func (*PIDNamespace) IDOfProcessGroup

func (ns *PIDNamespace) IDOfProcessGroup(pg *ProcessGroup) ProcessGroupID

IDOfProcessGroup returns the process group assigned to pg in PID namespace ns.

The same constraints apply as IDOfSession.

func (*PIDNamespace) IDOfSession

func (ns *PIDNamespace) IDOfSession(s *Session) SessionID

IDOfSession returns the Session assigned to s in PID namespace ns.

If this group isn't visible in this namespace, zero will be returned. It is the callers responsibility to check that before using this function.

func (*PIDNamespace) IDOfTask

func (ns *PIDNamespace) IDOfTask(t *Task) ThreadID

IDOfTask returns the TID assigned to the given task in PID namespace ns. If the task is not visible in that namespace, IDOfTask returns 0. (This return value is significant in some cases, e.g. getppid() is documented as returning 0 if the caller's parent is in an ancestor namespace and consequently not visible to the caller.) If the task is nil, IDOfTask returns 0.

func (*PIDNamespace) IDOfThreadGroup

func (ns *PIDNamespace) IDOfThreadGroup(tg *ThreadGroup) ThreadID

IDOfThreadGroup returns the TID assigned to tg's leader in PID namespace ns. If the task is not visible in that namespace, IDOfThreadGroup returns 0.

func (*PIDNamespace) NewChild

func (ns *PIDNamespace) NewChild(userns *auth.UserNamespace) *PIDNamespace

NewChild returns a new, empty PID namespace that is a child of ns. Authority over the new PID namespace is controlled by userns.

func (*PIDNamespace) NumTasks

func (ns *PIDNamespace) NumTasks() int

NumTasks returns the number of tasks in ns.

func (*PIDNamespace) NumTasksPerContainer

func (ns *PIDNamespace) NumTasksPerContainer(cid string) int

NumTasksPerContainer returns the number of tasks in ns that belongs to given container.

func (*PIDNamespace) ProcessGroupWithID

func (ns *PIDNamespace) ProcessGroupWithID(id ProcessGroupID) *ProcessGroup

ProcessGroupWithID returns the ProcessGroup with the given ID in the PID namespace ns, or nil if that given ID is not defined in this namespace.

A reference is not taken on the process group.

func (*PIDNamespace) Root

func (ns *PIDNamespace) Root() *PIDNamespace

Root returns the root PID namespace of ns.

func (*PIDNamespace) SessionWithID

func (ns *PIDNamespace) SessionWithID(id SessionID) *Session

SessionWithID returns the Session with the given ID in the PID namespace ns, or nil if that given ID is not defined in this namespace.

A reference is not taken on the session.

func (*PIDNamespace) TaskWithID

func (ns *PIDNamespace) TaskWithID(tid ThreadID) *Task

TaskWithID returns the task with thread ID tid in PID namespace ns. If no task has that TID, TaskWithID returns nil.

func (*PIDNamespace) Tasks

func (ns *PIDNamespace) Tasks() []*Task

Tasks returns a snapshot of the tasks in ns.

func (*PIDNamespace) TasksAppend

func (ns *PIDNamespace) TasksAppend(ts []*Task) []*Task

TasksAppend appends a snapshot of the tasks in ns to ts.

func (*PIDNamespace) ThreadGroupWithID

func (ns *PIDNamespace) ThreadGroupWithID(tid ThreadID) *ThreadGroup

ThreadGroupWithID returns the thread group led by the task with thread ID tid in PID namespace ns. If no task has that TID, or if the task with that TID is not a thread group leader, ThreadGroupWithID returns nil.

func (*PIDNamespace) ThreadGroups

func (ns *PIDNamespace) ThreadGroups() []*ThreadGroup

ThreadGroups returns a snapshot of the thread groups in ns.

func (*PIDNamespace) ThreadGroupsAppend

func (ns *PIDNamespace) ThreadGroupsAppend(tgs []*ThreadGroup) []*ThreadGroup

ThreadGroupsAppend appends a snapshot of the thread groups in ns to tgs.

func (*PIDNamespace) UserNamespace

func (ns *PIDNamespace) UserNamespace() *auth.UserNamespace

UserNamespace returns the user namespace associated with PID namespace ns.

type ProcessGroup

type ProcessGroup struct {
	// contains filtered or unexported fields
}

ProcessGroup contains an originator threadgroup and a parent Session.

+stateify savable

func (*ProcessGroup) IsOrphan

func (pg *ProcessGroup) IsOrphan() bool

IsOrphan returns true if this process group is an orphan.

func (*ProcessGroup) Originator

func (pg *ProcessGroup) Originator() *ThreadGroup

Originator returns the originator of the process group.

func (*ProcessGroup) SendSignal

func (pg *ProcessGroup) SendSignal(info *linux.SignalInfo) error

SendSignal sends a signal to all processes inside the process group. It is analogous to kernel/signal.c:kill_pgrp.

func (*ProcessGroup) Session

func (pg *ProcessGroup) Session() *Session

Session returns the process group's session without taking a reference.

type ProcessGroupID

type ProcessGroupID ThreadID

ProcessGroupID is the public identifier.

type Saver

type Saver interface {
	SaveAsync() error
	SpecEnviron(containerName string) []string
}

Saver is an interface for saving the kernel.

type Session

type Session struct {
	SessionRefs
	// contains filtered or unexported fields
}

Session contains a leader threadgroup and a list of ProcessGroups.

+stateify savable

func (*Session) DecRef

func (s *Session) DecRef()

DecRef drops a reference.

Precondition: callers must hold TaskSet.mu for writing.

type SessionID

type SessionID ThreadID

SessionID is the public identifier.

type SignalAction

type SignalAction int

SignalAction is an internal signal action.

const (
	SignalActionTerm SignalAction = iota
	SignalActionCore
	SignalActionStop
	SignalActionIgnore
	SignalActionHandler
)

Available signal actions. Note that although we refer the complete set internally, the application is only capable of using the Default and Ignore actions from the system call interface.

type SignalHandlers

type SignalHandlers struct {
	// contains filtered or unexported fields
}

SignalHandlers holds information about signal actions.

+stateify savable

func NewSignalHandlers

func NewSignalHandlers() *SignalHandlers

NewSignalHandlers returns a new SignalHandlers specifying all default actions.

func (*SignalHandlers) Fork

func (sh *SignalHandlers) Fork() *SignalHandlers

Fork returns a copy of sh for a new thread group.

func (*SignalHandlers) IsIgnored

func (sh *SignalHandlers) IsIgnored(sig linux.Signal) bool

IsIgnored returns true if the signal is ignored.

type SocketRecord

type SocketRecord struct {
	Sock *vfs.FileDescription
	ID   uint64 // Socket table entry number.
	// contains filtered or unexported fields
}

SocketRecord represents a socket recorded in Kernel.sockets.

+stateify savable

type SpecialOpts

type SpecialOpts struct{}

SpecialOpts contains non-standard options for the kernel.

+stateify savable

type Stracer

type Stracer interface {
	// SyscallEnter is called on syscall entry.
	//
	// The returned private data is passed to SyscallExit.
	SyscallEnter(t *Task, sysno uintptr, args arch.SyscallArguments, flags uint32) any

	// SyscallExit is called on syscall exit.
	SyscallExit(context any, t *Task, sysno, rval uintptr, err error)
}

Stracer traces syscall execution.

type Syscall

type Syscall struct {
	// Name is the syscall name.
	Name string
	// Fn is the implementation of the syscall.
	Fn SyscallFn
	// SupportLevel is the level of support implemented in gVisor.
	SupportLevel SyscallSupportLevel
	// Note describes the compatibility of the syscall.
	Note string
	// URLs is set of URLs to any relevant bugs or issues.
	URLs []string
	// PointCallback is an optional callback that converts syscall arguments
	// to a proto that can be used with seccheck.Sink.
	// Callback functions must follow this naming convention:
	//   PointSyscallNameInCamelCase, e.g. PointReadat, PointRtSigaction.
	PointCallback SyscallToProto
}

Syscall includes the syscall implementation and compatibility information.

type SyscallControl

type SyscallControl struct {
	// contains filtered or unexported fields
}

SyscallControl is returned by syscalls to control the behavior of Task.doSyscallInvoke.

type SyscallFlagsTable

type SyscallFlagsTable struct {
	// contains filtered or unexported fields
}

SyscallFlagsTable manages a set of enable/disable bit fields on a per-syscall basis.

func (*SyscallFlagsTable) Enable

func (e *SyscallFlagsTable) Enable(bit uint32, s map[uintptr]bool, missingEnable bool)

Enable sets enable bit `bit` for all syscalls based on s.

Syscalls missing from `s` are disabled.

Syscalls missing from the initial table passed to Init cannot be added as individual syscalls. If present in s they will be ignored.

Callers to Word may see either the old or new value while this function is executing.

func (*SyscallFlagsTable) EnableAll

func (e *SyscallFlagsTable) EnableAll(bit uint32)

EnableAll sets enable bit bit for all syscalls, present and missing.

func (*SyscallFlagsTable) UpdateSecCheck

func (e *SyscallFlagsTable) UpdateSecCheck(state *seccheck.State)

UpdateSecCheck implements seccheck.SyscallFlagListener.

It is called when per-syscall seccheck event enablement changes.

func (*SyscallFlagsTable) Word

func (e *SyscallFlagsTable) Word(sysno uintptr) uint32

Word returns the enable bitfield for sysno.

type SyscallFn

type SyscallFn func(t *Task, sysno uintptr, args arch.SyscallArguments) (uintptr, *SyscallControl, error)

SyscallFn is a syscall implementation.

type SyscallInfo

type SyscallInfo struct {
	Exit  bool
	Sysno uintptr
	Args  arch.SyscallArguments
	Rval  uintptr
	Errno int
}

SyscallInfo provides generic information about the syscall.

type SyscallRestartBlock

type SyscallRestartBlock interface {
	Restart(t *Task) (uintptr, error)
}

SyscallRestartBlock represents the restart block for a syscall restartable with a custom function. It encapsulates the state required to restart a syscall across a S/R.

type SyscallSupportLevel

type SyscallSupportLevel int

SyscallSupportLevel is a syscall support levels.

func (SyscallSupportLevel) String

func (l SyscallSupportLevel) String() string

String returns a human readable representation of the support level.

type SyscallTable

type SyscallTable struct {
	// OS is the operating system that this syscall table implements.
	OS abi.OS

	// Arch is the architecture that this syscall table targets.
	Arch arch.Arch

	// The OS version that this syscall table implements.
	Version Version

	// AuditNumber is a numeric constant that represents the syscall table. If
	// non-zero, auditNumber must be one of the AUDIT_ARCH_* values defined by
	// linux/audit.h.
	AuditNumber uint32

	// Table is the collection of functions.
	Table map[uintptr]Syscall

	// Emulate is a collection of instruction addresses to emulate. The
	// keys are addresses, and the values are system call numbers.
	Emulate map[hostarch.Addr]uintptr

	// The function to call in case of a missing system call.
	Missing MissingFn

	// Stracer traces this syscall table.
	Stracer Stracer

	// External is used to handle an external callback.
	External func(*Kernel)

	// ExternalFilterBefore is called before External is called before the syscall is executed.
	// External is not called if it returns false.
	ExternalFilterBefore func(*Task, uintptr, arch.SyscallArguments) bool

	// ExternalFilterAfter is called before External is called after the syscall is executed.
	// External is not called if it returns false.
	ExternalFilterAfter func(*Task, uintptr, arch.SyscallArguments) bool

	// FeatureEnable stores the strace and one-shot enable bits.
	FeatureEnable SyscallFlagsTable
	// contains filtered or unexported fields
}

SyscallTable is a lookup table of system calls.

Note that a SyscallTable is not savable directly. Instead, they are saved as an OS/Arch pair and lookup happens again on restore.

func LookupSyscallTable

func LookupSyscallTable(os abi.OS, a arch.Arch) (*SyscallTable, bool)

LookupSyscallTable returns the SyscallCall table for the OS/Arch combination.

func SyscallTables

func SyscallTables() []*SyscallTable

SyscallTables returns a read-only slice of registered SyscallTables.

func (*SyscallTable) Init

func (s *SyscallTable) Init()

Init initializes the system call table.

This should normally be called only during registration.

func (*SyscallTable) Lookup

func (s *SyscallTable) Lookup(sysno uintptr) SyscallFn

Lookup returns the syscall implementation, if one exists.

func (*SyscallTable) LookupEmulate

func (s *SyscallTable) LookupEmulate(addr hostarch.Addr) (uintptr, bool)

LookupEmulate looks up an emulation syscall number.

func (*SyscallTable) LookupName

func (s *SyscallTable) LookupName(sysno uintptr) string

LookupName looks up a syscall name.

func (*SyscallTable) LookupNo

func (s *SyscallTable) LookupNo(name string) (uintptr, error)

LookupNo looks up a syscall number by name.

func (*SyscallTable) LookupSyscallToProto

func (s *SyscallTable) LookupSyscallToProto(sysno uintptr) SyscallToProto

LookupSyscallToProto looks up the SyscallToProto callback for the given syscall. It may return nil if none is registered.

func (*SyscallTable) MaxSysno

func (s *SyscallTable) MaxSysno() (max uintptr)

MaxSysno returns the largest system call number.

type SyscallToProto

SyscallToProto is a callback function that converts generic syscall data to schematized protobuf for the corresponding syscall.

type TTY

type TTY struct {
	// TTYOperations holds operations on the tty. It is immutable.
	TTYOperations
	// contains filtered or unexported fields
}

TTY defines the relationship between a thread group and its controlling terminal.

+stateify savable

func NewTTY

func NewTTY(index uint32, ttyOps TTYOperations) *TTY

NewTTY constructs a new TTY.

func (*TTY) Index

func (tty *TTY) Index() uint32

Index returns the tty's index.

func (*TTY) SignalForegroundProcessGroup

func (tty *TTY) SignalForegroundProcessGroup(info *linux.SignalInfo)

SignalForegroundProcessGroup sends the signal to the foreground process group of the TTY.

func (*TTY) ThreadGroup

func (tty *TTY) ThreadGroup() *ThreadGroup

ThreadGroup returns the ThreadGroup this TTY is associated with.

type TTYOperations

type TTYOperations interface {
	// Open opens the tty.
	Open(ctx context.Context, mnt *vfs.Mount, vfsd *vfs.Dentry, opts vfs.OpenOptions) (*vfs.FileDescription, error)
}

TTYOperations handle tty operations. It is analogous to (a small subset) of Linux's struct tty_operations and exists to avoid a circular dependency.

type Task

type Task struct {

	// Origin is the origin of the task.
	Origin TaskOrigin
	// contains filtered or unexported fields
}

Task represents a thread of execution in the untrusted app. It includes registers and any thread-specific state that you would normally expect.

Each task is associated with a goroutine, called the task goroutine, that executes code (application code, system calls, etc.) on behalf of that task. See Task.run (task_run.go).

All fields that are "owned by the task goroutine" can only be mutated by the task goroutine while it is running. The task goroutine does not require synchronization to read these fields, although it still requires synchronization as described for those fields to mutate them.

All fields that are "exclusive to the task goroutine" can only be accessed by the task goroutine while it is running. The task goroutine does not require synchronization to read or write these fields.

+stateify savable

func TaskFromContext

func TaskFromContext(ctx context.Context) *Task

TaskFromContext returns the Task associated with ctx, or nil if there is no such Task.

func (*Task) Activate

func (t *Task) Activate()

Activate ensures that the task has an active address space.

func (*Task) AppendSyscallFilter

func (t *Task) AppendSyscallFilter(p bpf.Program, syncAll bool) error

AppendSyscallFilter adds BPF program p as a system call filter.

Preconditions: The caller must be running on the task goroutine.

func (*Task) Arch

func (t *Task) Arch() *arch.Context64

Arch returns t's arch.Context64.

Preconditions: The caller must be running on the task goroutine, or t.mu must be locked.

func (*Task) AsyncContext

func (t *Task) AsyncContext() context.Context

AsyncContext returns a context.Context representing t. The returned context.Context is intended for use by goroutines other than t's task goroutine; for example, signal delivery to t will not interrupt goroutines that are blocking using the returned context.Context.

func (*Task) BeginExternalStop

func (t *Task) BeginExternalStop()

BeginExternalStop indicates the start of an external stop that applies to t. BeginExternalStop does not wait for t's task goroutine to stop.

func (*Task) Block

func (t *Task) Block(C <-chan struct{}) error

Block implements context.Context.Block

func (*Task) BlockOn

func (t *Task) BlockOn(w waiter.Waitable, mask waiter.EventMask) bool

BlockOn implements context.Context.BlockOn.

func (*Task) BlockWithDeadline

func (t *Task) BlockWithDeadline(C <-chan struct{}, haveDeadline bool, deadline ktime.Time) error

BlockWithDeadline blocks t until it is woken by an event, the application monotonic clock indicates a time of deadline (only if haveDeadline is true), or t is interrupted. It returns nil if an event is received from C, ETIMEDOUT if the deadline expired, and linuxerr.ErrInterrupted if t is interrupted.

Preconditions: The caller must be running on the task goroutine.

func (*Task) BlockWithDeadlineFrom

func (t *Task) BlockWithDeadlineFrom(C <-chan struct{}, clock ktime.Clock, haveDeadline bool, deadline ktime.Time) error

BlockWithDeadlineFrom is similar to BlockWithDeadline, except it uses the passed clock (instead of application monotonic clock).

Most clients should use BlockWithDeadline or BlockWithTimeout instead.

Preconditions: The caller must be running on the task goroutine.

func (*Task) BlockWithTimeout

func (t *Task) BlockWithTimeout(C chan struct{}, haveTimeout bool, timeout time.Duration) (time.Duration, error)

BlockWithTimeout blocks t until an event is received from C, the application monotonic clock indicates that timeout has elapsed (only if haveTimeout is true), or t is interrupted. It returns:

  • The remaining timeout, which is guaranteed to be 0 if the timeout expired, and is unspecified if haveTimeout is false.

  • An error which is nil if an event is received from C, ETIMEDOUT if the timeout expired, and linuxerr.ErrInterrupted if t is interrupted.

Preconditions: The caller must be running on the task goroutine.

func (*Task) BlockWithTimeoutOn

func (t *Task) BlockWithTimeoutOn(w waiter.Waitable, mask waiter.EventMask, timeout time.Duration) (time.Duration, bool)

BlockWithTimeoutOn implements context.Context.BlockWithTimeoutOn.

func (*Task) CPU

func (t *Task) CPU() int32

CPU returns the cpu id for a given task.

func (*Task) CPUClock

func (t *Task) CPUClock() ktime.Clock

CPUClock returns a clock measuring the CPU time the task has spent executing application and "kernel" code.

func (*Task) CPUMask

func (t *Task) CPUMask() sched.CPUSet

CPUMask returns a copy of t's allowed CPU mask.

func (*Task) CPUStats

func (t *Task) CPUStats() usage.CPUStats

CPUStats returns the CPU usage statistics of t.

func (*Task) CanTrace

func (t *Task) CanTrace(target *Task, attach bool) bool

CanTrace checks that t is permitted to access target's state, as defined by ptrace(2), subsection "Ptrace access mode checking". If attach is true, it checks for access mode PTRACE_MODE_ATTACH; otherwise, it checks for access mode PTRACE_MODE_READ.

In Linux, ptrace access restrictions may be configured by LSMs. While we do not support LSMs, we do add additional restrictions based on the commoncap and YAMA LSMs.

TODO(gvisor.dev/issue/212): The result of CanTrace is immediately stale (e.g., a racing setuid(2) may change traceability). This may pose a risk when a task changes from traceable to not traceable. This is only problematic across execve, where privileges may increase.

We currently do not implement privileged executables (set-user/group-ID bits and file capabilities), so that case is not reachable.

func (*Task) CgroupPrepareMigrate

func (t *Task) CgroupPrepareMigrate(dst Cgroup) (*CgroupMigrationContext, error)

CgroupPrepareMigrate starts a cgroup migration for this task to dst. The migration must be completed through the returned context.

func (*Task) ChargeFor

func (t *Task) ChargeFor(other *Task, ctl CgroupControllerType, res CgroupResourceType, value int64) (bool, Cgroup, error)

ChargeFor charges t's cgroup on behalf of some other task. Returns the cgroup that's charged if any. Returned cgroup has an extra ref that's transferred to the caller.

func (*Task) Children

func (t *Task) Children() map[*Task]struct{}

Children returns children of this task.

func (*Task) ClearRSeq

func (t *Task) ClearRSeq(addr hostarch.Addr, length, signature uint32) error

ClearRSeq unregisters addr as this thread's rseq structure.

Preconditions: The caller must be running on the task goroutine.

func (*Task) ClearYAMAException

func (t *Task) ClearYAMAException()

ClearYAMAException removes any YAMA exception with t as the tracee.

func (*Task) Clone

func (t *Task) Clone(args *linux.CloneArgs) (ThreadID, *SyscallControl, error)

Clone implements the clone(2) syscall and returns the thread ID of the new task in t's PID namespace. Clone may return both a non-zero thread ID and a non-nil error.

Preconditions: The caller must be running Task.doSyscallInvoke on the task goroutine.

func (*Task) CompareAndSwapUint32

func (t *Task) CompareAndSwapUint32(addr hostarch.Addr, old, new uint32) (uint32, error)

CompareAndSwapUint32 implements futex.Target.CompareAndSwapUint32.

func (*Task) ContainerID

func (t *Task) ContainerID() string

ContainerID returns t's container ID.

func (*Task) CopyContext

func (t *Task) CopyContext(ctx context.Context, opts usermem.IOOpts) *taskCopyContext

CopyContext returns a marshal.CopyContext that copies to/from t's address space using opts.

func (*Task) CopyInBytes

func (t *Task) CopyInBytes(addr hostarch.Addr, dst []byte) (int, error)

CopyInBytes is a fast version of CopyIn if the caller can serialize the data without reflection and pass in a byte slice.

This Task's AddressSpace must be active.

func (*Task) CopyInIovecs

func (t *Task) CopyInIovecs(addr hostarch.Addr, numIovecs int) (hostarch.AddrRangeSeq, error)

CopyInIovecs copies in IoVecs for Task.

Preconditions: Same as usermem.IO.CopyIn, plus: * The caller must be running on the task goroutine. * t's AddressSpace must be active.

func (*Task) CopyInIovecsAsSlice

func (t *Task) CopyInIovecsAsSlice(addr hostarch.Addr, numIovecs int) ([]hostarch.AddrRange, error)

CopyInIovecsAsSlice copies in IoVecs and returns them in a slice.

Preconditions: Same as usermem.IO.CopyIn, plus:

  • The caller must be running on the task goroutine or hold t.mu.
  • t's AddressSpace must be active.

func (*Task) CopyInString

func (t *Task) CopyInString(addr hostarch.Addr, maxlen int) (string, error)

CopyInString copies a NUL-terminated string of length at most maxlen in from the task's memory. The copy will fail with syscall.EFAULT if it traverses user memory that is unmapped or not readable by the user.

This Task's AddressSpace must be active.

func (*Task) CopyInVector

func (t *Task) CopyInVector(addr hostarch.Addr, maxElemSize, maxTotalSize int) ([]string, error)

CopyInVector copies a NULL-terminated vector of strings from the task's memory. The copy will fail with syscall.EFAULT if it traverses user memory that is unmapped or not readable by the user.

maxElemSize is the maximum size of each individual element.

maxTotalSize is the maximum total length of all elements plus the total number of elements. For example, the following strings correspond to the following set of sizes:

{ "a", "b", "c" } => 6 (3 for lengths, 3 for elements)
{ "abc" }         => 4 (3 for length, 1 for elements)

This Task's AddressSpace must be active.

func (*Task) CopyOutBytes

func (t *Task) CopyOutBytes(addr hostarch.Addr, src []byte) (int, error)

CopyOutBytes is a fast version of CopyOut if the caller can serialize the data without reflection and pass in a byte slice.

This Task's AddressSpace must be active.

func (*Task) CopyOutIovecs

func (t *Task) CopyOutIovecs(addr hostarch.Addr, src hostarch.AddrRangeSeq) error

CopyOutIovecs converts src to an array of struct iovecs and copies it to the memory mapped at addr for Task.

Preconditions: Same as usermem.IO.CopyOut, plus:

  • The caller must be running on the task goroutine.
  • t's AddressSpace must be active.

func (*Task) CopyScratchBuffer

func (t *Task) CopyScratchBuffer(size int) []byte

CopyScratchBuffer returns a scratch buffer to be used in CopyIn/CopyOut functions. It must only be used within those functions and can only be used by the task goroutine; it exists to improve performance and thus intentionally lacks any synchronization.

Callers should pass a constant value as an argument if possible, which will allow the compiler to inline and optimize out the if statement below.

func (*Task) Credentials

func (t *Task) Credentials() *auth.Credentials

Credentials returns t's credentials.

This value must be considered immutable.

func (*Task) Deactivate

func (t *Task) Deactivate()

Deactivate relinquishes the task's active address space.

func (*Task) Deadline

func (*Task) Deadline() (time.Time, bool)

Deadline implements context.Context.Deadline.

func (*Task) DebugDumpState

func (t *Task) DebugDumpState()

DebugDumpState logs task state at log level debug.

Preconditions: The caller must be running on the task goroutine.

func (*Task) Debugf

func (t *Task) Debugf(fmt string, v ...any)

Debugf creates a debug string that includes the task ID.

func (*Task) Done

func (*Task) Done() <-chan struct{}

Done implements context.Context.Done.

func (*Task) DropBoundingCapability

func (t *Task) DropBoundingCapability(cp linux.Capability) error

DropBoundingCapability attempts to drop capability cp from t's capability bounding set.

func (*Task) EndExternalStop

func (t *Task) EndExternalStop()

EndExternalStop indicates the end of an external stop started by a previous call to Task.BeginExternalStop. EndExternalStop does not wait for t's task goroutine to resume.

func (*Task) EnterCgroup

func (t *Task) EnterCgroup(c Cgroup) error

EnterCgroup moves t into c.

func (*Task) EnterInitialCgroups

func (t *Task) EnterInitialCgroups(parent *Task, initCgroups map[Cgroup]struct{})

EnterInitialCgroups moves t into an initial set of cgroups. If initCgroups is not nil, the new task will be placed in the specified cgroups. Otherwise, if parent is not nil, the new task will be placed in the parent's cgroups. If neither is specified, the new task will be in the root cgroups.

This is analogous to Linux's kernel/cgroup/cgroup.c:cgroup_css_set_fork().

Precondition: t isn't in any cgroups yet, t.cgroups is empty.

func (*Task) Err

func (*Task) Err() error

Err implements context.Context.Err.

func (*Task) Execve

func (t *Task) Execve(newImage *TaskImage, argv, env []string, executable *vfs.FileDescription, pathname string) (*SyscallControl, error)

Execve implements the execve(2) syscall by killing all other tasks in its thread group and switching to newImage. Execve always takes ownership of newImage.

If executable is not nil, it is the first executable file that was loaded in the process of obtaining newImage, and pathname is a path to it.

Preconditions: The caller must be running Task.doSyscallInvoke on the task goroutine.

func (*Task) ExitState

func (t *Task) ExitState() TaskExitState

ExitState returns t's current progress through the exit path.

func (*Task) ExitStatus

func (t *Task) ExitStatus() linux.WaitStatus

ExitStatus returns t's exit status, which is only guaranteed to be meaningful if t.ExitState() != TaskExitNone.

func (*Task) FDTable

func (t *Task) FDTable() *FDTable

FDTable returns t's FDTable. FDMTable does not take an additional reference on the returned FDMap.

Precondition: The caller must be running on the task goroutine, or t.mu must be locked.

func (*Task) FSContext

func (t *Task) FSContext() *FSContext

FSContext returns t's FSContext. FSContext does not take an additional reference on the returned FSContext.

Precondition: The caller must be running on the task goroutine, or t.mu must be locked.

func (*Task) Futex

func (t *Task) Futex() *futex.Manager

Futex returns t's futex manager.

Preconditions: The caller must be running on the task goroutine, or t.mu must be locked.

func (*Task) FutexWaiter

func (t *Task) FutexWaiter() *futex.Waiter

FutexWaiter returns the Task's futex.Waiter.

func (*Task) GenerateProcTaskCgroup

func (t *Task) GenerateProcTaskCgroup(buf *bytes.Buffer)

GenerateProcTaskCgroup writes the contents of /proc/<pid>/cgroup for t to buf.

func (*Task) GetCgroupEntries

func (t *Task) GetCgroupEntries() []TaskCgroupEntry

GetCgroupEntries generates the contents of /proc/<pid>/cgroup as a TaskCgroupEntry array.

func (*Task) GetFile

func (t *Task) GetFile(fd int32) *vfs.FileDescription

GetFile is a convenience wrapper for t.FDTable().Get.

Precondition: same as FDTable.Get.

func (*Task) GetIPCNamespace

func (t *Task) GetIPCNamespace() *IPCNamespace

GetIPCNamespace takes a reference on the task IPC namespace and returns it. It will return nil if the task isn't alive.

func (*Task) GetMountNamespace

func (t *Task) GetMountNamespace() *vfs.MountNamespace

GetMountNamespace returns t's MountNamespace. A reference is taken on the returned mount namespace.

func (*Task) GetNetworkNamespace

func (t *Task) GetNetworkNamespace() *inet.Namespace

GetNetworkNamespace takes a reference on the task network namespace and returns it. It can return nil if the task isn't alive.

func (*Task) GetRobustList

func (t *Task) GetRobustList() hostarch.Addr

GetRobustList sets the robust futex list for the task.

func (*Task) GetSharedKey

func (t *Task) GetSharedKey(addr hostarch.Addr) (futex.Key, error)

GetSharedKey implements futex.Target.GetSharedKey.

func (*Task) GetUTSNamespace

func (t *Task) GetUTSNamespace() *UTSNamespace

GetUTSNamespace takes a reference on the task UTS namespace and returns it. It will return nil if the task isn't alive.

func (*Task) Getitimer

func (t *Task) Getitimer(id int32) (linux.ItimerVal, error)

Getitimer implements getitimer(2).

Preconditions: The caller must be running on the task goroutine.

func (*Task) GoroutineID

func (t *Task) GoroutineID() int64

GoroutineID returns the ID of t's task goroutine.

func (*Task) HasCapability

func (t *Task) HasCapability(cp linux.Capability) bool

HasCapability checks if the task has capability cp in its user namespace.

func (*Task) HasCapabilityIn

func (t *Task) HasCapabilityIn(cp linux.Capability, ns *auth.UserNamespace) bool

HasCapabilityIn checks if the task has capability cp in user namespace ns.

func (*Task) IOUsage

func (t *Task) IOUsage() *usage.IO

IOUsage returns the io usage of the thread.

func (*Task) IPCNamespace

func (t *Task) IPCNamespace() *IPCNamespace

IPCNamespace returns the task's IPC namespace.

func (*Task) Infof

func (t *Task) Infof(fmt string, v ...any)

Infof logs an formatted info message by calling log.Infof.

func (*Task) Interrupt

func (t *Task) Interrupt()

Interrupt implements context.Blocker.Interrupt.

func (*Task) Interrupted

func (t *Task) Interrupted() bool

Interrupted implements context.Context.Interrupted.

func (*Task) IntervalTimerCreate

func (t *Task) IntervalTimerCreate(c ktime.Clock, sigev *linux.Sigevent) (linux.TimerID, error)

IntervalTimerCreate implements timer_create(2).

func (*Task) IntervalTimerDelete

func (t *Task) IntervalTimerDelete(id linux.TimerID) error

IntervalTimerDelete implements timer_delete(2).

func (*Task) IntervalTimerGetoverrun

func (t *Task) IntervalTimerGetoverrun(id linux.TimerID) (int32, error)

IntervalTimerGetoverrun implements timer_getoverrun(2).

Preconditions: The caller must be running on the task goroutine.

func (*Task) IntervalTimerGettime

func (t *Task) IntervalTimerGettime(id linux.TimerID) (linux.Itimerspec, error)

IntervalTimerGettime implements timer_gettime(2).

func (*Task) IntervalTimerSettime

func (t *Task) IntervalTimerSettime(id linux.TimerID, its linux.Itimerspec, abs bool) (linux.Itimerspec, error)

IntervalTimerSettime implements timer_settime(2).

func (*Task) IovecsIOSequence

func (t *Task) IovecsIOSequence(addr hostarch.Addr, iovcnt int, opts usermem.IOOpts) (usermem.IOSequence, error)

IovecsIOSequence returns a usermem.IOSequence representing the array of iovcnt struct iovecs at addr in t's address space. opts applies to the returned IOSequence, not the reading of the struct iovec array.

IovecsIOSequence is analogous to Linux's lib/iov_iter.c:import_iovec().

Preconditions: Same as Task.CopyInIovecs.

func (*Task) IsChrooted

func (t *Task) IsChrooted() bool

IsChrooted returns true if the root directory of t's FSContext is not the root directory of t's MountNamespace.

Preconditions: The caller must be running on the task goroutine, or t.mu must be locked.

func (*Task) IsLogging

func (t *Task) IsLogging(level log.Level) bool

IsLogging returns true iff this level is being logged.

func (*Task) IsNetworkNamespaced

func (t *Task) IsNetworkNamespaced() bool

IsNetworkNamespaced returns true if t is in a non-root network namespace.

func (*Task) JoinSessionKeyring

func (t *Task) JoinSessionKeyring(keyDesc *string) (*auth.Key, error)

JoinSessionKeyring causes the task to join a keyring with the given key description (not ID). If `keyDesc` is nil, then the task joins a newly-instantiated session keyring instead.

func (*Task) KGID

func (t *Task) KGID() uint32

KGID returns t's kgid.

func (*Task) KUID

func (t *Task) KUID() uint32

KUID returns t's kuid.

func (*Task) Kernel

func (t *Task) Kernel() *Kernel

Kernel returns the Kernel containing t.

func (*Task) LeaveCgroups

func (t *Task) LeaveCgroups()

LeaveCgroups removes t out from all its cgroups.

func (*Task) Limits

func (t *Task) Limits() *limits.LimitSet

Limits implements context.Context.Limits.

func (*Task) LoadUint32

func (t *Task) LoadUint32(addr hostarch.Addr) (uint32, error)

LoadUint32 implements futex.Target.LoadUint32.

func (*Task) LookupKey

func (t *Task) LookupKey(keyID auth.KeySerial) (*auth.Key, error)

LookupKey looks up a key by ID using this task's credentials.

func (*Task) MaxRSS

func (t *Task) MaxRSS(which int32) uint64

MaxRSS returns the maximum resident set size of the task in bytes. which should be one of RUSAGE_SELF, RUSAGE_CHILDREN, RUSAGE_THREAD, or RUSAGE_BOTH. See getrusage(2) for documentation on the behavior of these flags.

func (*Task) MemoryManager

func (t *Task) MemoryManager() *mm.MemoryManager

MemoryManager returns t's MemoryManager. MemoryManager does not take an additional reference on the returned MM.

Preconditions: The caller must be running on the task goroutine, or t.mu must be locked.

func (*Task) MigrateCgroup

func (t *Task) MigrateCgroup(dst Cgroup) error

MigrateCgroup migrates this task to the dst cgroup.

func (*Task) MountNamespace

func (t *Task) MountNamespace() *vfs.MountNamespace

MountNamespace returns t's MountNamespace.

func (*Task) Name

func (t *Task) Name() string

Name returns t's name.

func (*Task) NetworkContext

func (t *Task) NetworkContext() inet.Stack

NetworkContext returns the network stack used by the task. NetworkContext may return nil if no network stack is available.

TODO(gvisor.dev/issue/1833): Migrate callers of this method to NetworkNamespace().

func (*Task) NetworkNamespace

func (t *Task) NetworkNamespace() *inet.Namespace

NetworkNamespace returns the network namespace observed by the task.

func (*Task) NetworkNamespaceByFD

func (t *Task) NetworkNamespaceByFD(fd int32) (*inet.Namespace, error)

NetworkNamespaceByFD returns the network namespace associated with the specified descriptor.

func (*Task) NewFDAt

func (t *Task) NewFDAt(fd int32, file *vfs.FileDescription, flags FDFlags) (*vfs.FileDescription, error)

NewFDAt is a convenience wrapper for t.FDTable().NewFDAt.

This automatically passes the task as the context.

Precondition: same as FDTable.

func (*Task) NewFDFrom

func (t *Task) NewFDFrom(minFD int32, file *vfs.FileDescription, flags FDFlags) (int32, error)

NewFDFrom is a convenience wrapper for t.FDTable().NewFD.

This automatically passes the task as the context.

Precondition: same as FDTable.Get.

func (*Task) NewFDs

func (t *Task) NewFDs(fd int32, files []*vfs.FileDescription, flags FDFlags) ([]int32, error)

NewFDs is a convenience wrapper for t.FDTable().NewFDs.

This automatically passes the task as the context.

Precondition: same as FDTable.

func (*Task) Niceness

func (t *Task) Niceness() int

Niceness returns t's niceness.

func (*Task) NotifyRlimitCPUUpdated

func (t *Task) NotifyRlimitCPUUpdated()

NotifyRlimitCPUUpdated is called by setrlimit.

Preconditions: The caller must be running on the task goroutine.

func (*Task) NumaPolicy

func (t *Task) NumaPolicy() (policy linux.NumaPolicy, nodeMask uint64)

NumaPolicy returns t's current numa policy.

func (*Task) OOMScoreAdj

func (t *Task) OOMScoreAdj() int32

OOMScoreAdj gets the task's thread group's OOM score adjustment.

func (*Task) OldRSeqCPUAddr

func (t *Task) OldRSeqCPUAddr() hostarch.Addr

OldRSeqCPUAddr returns the address that old rseq will keep updated with t's CPU number.

Preconditions: The caller must be running on the task goroutine.

func (*Task) OldRSeqCriticalRegion

func (t *Task) OldRSeqCriticalRegion() OldRSeqCriticalRegion

OldRSeqCriticalRegion returns a copy of t's thread group's current old restartable sequence.

func (*Task) OwnCopyContext

func (t *Task) OwnCopyContext(opts usermem.IOOpts) *ownTaskCopyContext

OwnCopyContext returns a marshal.CopyContext that copies to/from t's address space using opts. The returned CopyContext may only be used by t's task goroutine.

Since t already implements marshal.CopyContext, this is only needed to override the usermem.IOOpts used for the copy.

func (*Task) PIDNamespace

func (t *Task) PIDNamespace() *PIDNamespace

PIDNamespace returns the PID namespace containing t.

func (*Task) Parent

func (t *Task) Parent() *Task

Parent returns t's parent.

func (*Task) ParentDeathSignal

func (t *Task) ParentDeathSignal() linux.Signal

ParentDeathSignal returns t's parent death signal.

func (*Task) ParentLocked

func (t *Task) ParentLocked() *Task

ParentLocked returns t's parent. Caller must ensure t's TaskSet mu is locked for at least reading.

+checklocks:t.tg.pidns.owner.mu

func (*Task) PendingSignals

func (t *Task) PendingSignals() linux.SignalSet

PendingSignals returns the set of pending signals.

func (*Task) PrepareExit

func (t *Task) PrepareExit(ws linux.WaitStatus)

PrepareExit indicates an exit with the given status.

Preconditions: The caller must be running on the task goroutine.

func (*Task) PrepareGroupExit

func (t *Task) PrepareGroupExit(ws linux.WaitStatus)

PrepareGroupExit indicates a group exit with status es to t's thread group.

PrepareGroupExit is analogous to Linux's do_group_exit(), except that it does not tail-call do_exit(), except that it *does* set Task.exitStatus. (Linux does not do so until within do_exit(), since it reuses exit_code for ptrace.)

Preconditions: The caller must be running on the task goroutine.

func (*Task) Priority

func (t *Task) Priority() int

Priority returns t's priority.

func (*Task) Ptrace

func (t *Task) Ptrace(req int64, pid ThreadID, addr, data hostarch.Addr) error

Ptrace implements the ptrace system call.

func (*Task) QueueAIO

func (t *Task) QueueAIO(cb AIOCallback)

QueueAIO queues an AIOCallback which will be run asynchronously.

func (*Task) RSeqAvailable

func (t *Task) RSeqAvailable() bool

RSeqAvailable returns true if t supports (old and new) restartable sequences.

func (*Task) RegisterOnDestroyAction

func (t *Task) RegisterOnDestroyAction(act TaskDestroyAction) bool

RegisterOnDestroyAction registers an action to be executed when the task is destroyed.

It returns true if the action was successfully registered. If the task is already terminated, it returns false.

func (*Task) RegisterWork

func (t *Task) RegisterWork(work TaskWorker)

RegisterWork can be used to register additional task work that will be performed prior to returning to user space. See TaskWorker.TaskWork for semantics regarding registration.

func (*Task) ResetKcov

func (t *Task) ResetKcov()

ResetKcov clears the kcov instance associated with t.

func (*Task) ResetMemCgIDFromCgroup

func (t *Task) ResetMemCgIDFromCgroup(cg Cgroup)

ResetMemCgIDFromCgroup sets the memory cgroup id to zero, if the task has a memory cgroup.

func (*Task) RestoreContainerID

func (t *Task) RestoreContainerID(cid string)

RestoreContainerID sets t's container ID in case the restored container ID is different from when it was saved.

func (*Task) SeccompMode

func (t *Task) SeccompMode() int

SeccompMode returns a SECCOMP_MODE_* constant indicating the task's current seccomp syscall filtering mode, appropriate for both prctl(PR_GET_SECCOMP) and /proc/[pid]/status.

func (*Task) SendGroupSignal

func (t *Task) SendGroupSignal(info *linux.SignalInfo) error

SendGroupSignal sends the given signal to t's thread group.

func (*Task) SendSignal

func (t *Task) SendSignal(info *linux.SignalInfo) error

SendSignal sends the given signal to t.

The following errors may be returned:

linuxerr.ESRCH - The task has exited.
linuxerr.EINVAL - The signal is not valid.
linuxerr.EAGAIN - THe signal is realtime, and cannot be queued.

func (*Task) SessionKeyring

func (t *Task) SessionKeyring() (*auth.Key, error)

SessionKeyring returns this Task's session keyring. Session keyrings are inherited from the parent when a task is started. If the session keyring is unset, it is implicitly initialized. As such, this function should never return ENOKEY.

func (*Task) SetCPUMask

func (t *Task) SetCPUMask(mask sched.CPUSet) error

SetCPUMask sets t's allowed CPU mask based on mask. It takes ownership of mask.

Preconditions: mask.Size() == sched.CPUSetSize(t.Kernel().ApplicationCores()).

func (*Task) SetCapabilitySets

func (t *Task) SetCapabilitySets(permitted, inheritable, effective auth.CapabilitySet) error

SetCapabilitySets attempts to change t's permitted, inheritable, and effective capability sets.

func (*Task) SetClearTID

func (t *Task) SetClearTID(addr hostarch.Addr)

SetClearTID sets t's cleartid.

Preconditions: The caller must be running on the task goroutine.

func (*Task) SetExtraGIDs

func (t *Task) SetExtraGIDs(gids []auth.GID) error

SetExtraGIDs attempts to change t's supplemental groups. All IDs are interpreted as being in t's user namespace.

func (*Task) SetGID

func (t *Task) SetGID(gid auth.GID) error

SetGID implements the semantics of setgid(2).

func (*Task) SetKcov

func (t *Task) SetKcov(k *Kcov)

SetKcov sets the kcov instance associated with t.

func (*Task) SetKeepCaps

func (t *Task) SetKeepCaps(k bool)

SetKeepCaps will set the keep capabilities flag PR_SET_KEEPCAPS.

func (*Task) SetMemCgID

func (t *Task) SetMemCgID(memCgID uint32)

SetMemCgID sets the given memory cgroup id to the task.

func (*Task) SetMemCgIDFromCgroup

func (t *Task) SetMemCgIDFromCgroup(cg Cgroup)

SetMemCgIDFromCgroup sets the id of the given memory cgroup to the task.

func (*Task) SetName

func (t *Task) SetName(name string)

SetName changes t's name.

func (*Task) SetNiceness

func (t *Task) SetNiceness(n int)

SetNiceness sets t's niceness to n.

func (*Task) SetNumaPolicy

func (t *Task) SetNumaPolicy(policy linux.NumaPolicy, nodeMask uint64)

SetNumaPolicy sets t's numa policy.

func (*Task) SetOOMScoreAdj

func (t *Task) SetOOMScoreAdj(adj int32) error

SetOOMScoreAdj sets the task's thread group's OOM score adjustment. The value should be between -1000 and 1000 inclusive.

func (*Task) SetOldRSeqCPUAddr

func (t *Task) SetOldRSeqCPUAddr(addr hostarch.Addr) error

SetOldRSeqCPUAddr replaces the address that old rseq will keep updated with t's CPU number.

Preconditions:

  • t.RSeqAvailable() == true.
  • The caller must be running on the task goroutine.
  • t's AddressSpace must be active.

func (*Task) SetOldRSeqCriticalRegion

func (t *Task) SetOldRSeqCriticalRegion(r OldRSeqCriticalRegion) error

SetOldRSeqCriticalRegion replaces t's thread group's old restartable sequence.

Preconditions: t.RSeqAvailable() == true.

func (*Task) SetParentDeathSignal

func (t *Task) SetParentDeathSignal(sig linux.Signal)

SetParentDeathSignal sets t's parent death signal.

func (*Task) SetPermsOnKey

func (t *Task) SetPermsOnKey(key *auth.Key, perms auth.KeyPermissions) error

SetPermsOnKey sets the permission bits on the given key using the task's credentials.

func (*Task) SetREGID

func (t *Task) SetREGID(r, e auth.GID) error

SetREGID implements the semantics of setregid(2).

func (*Task) SetRESGID

func (t *Task) SetRESGID(r, e, s auth.GID) error

SetRESGID implements the semantics of the setresgid(2) syscall.

func (*Task) SetRESUID

func (t *Task) SetRESUID(r, e, s auth.UID) error

SetRESUID implements the semantics of the setresuid(2) syscall.

func (*Task) SetREUID

func (t *Task) SetREUID(r, e auth.UID) error

SetREUID implements the semantics of setreuid(2).

func (*Task) SetRSeq

func (t *Task) SetRSeq(addr hostarch.Addr, length, signature uint32) error

SetRSeq registers addr as this thread's rseq structure.

Preconditions: The caller must be running on the task goroutine.

func (*Task) SetRobustList

func (t *Task) SetRobustList(addr hostarch.Addr)

SetRobustList sets the robust futex list for the task.

func (*Task) SetSavedSignalMask

func (t *Task) SetSavedSignalMask(mask linux.SignalSet)

SetSavedSignalMask sets the saved signal mask (see Task.savedSignalMask's comment).

Preconditions: The caller must be running on the task goroutine.

func (*Task) SetSignalMask

func (t *Task) SetSignalMask(mask linux.SignalSet)

SetSignalMask sets t's signal mask.

Preconditions:

  • The caller must be running on the task goroutine.
  • t.exitState < TaskExitZombie.

func (*Task) SetSignalStack

func (t *Task) SetSignalStack(alt linux.SignalStack) bool

SetSignalStack sets the task-private signal stack.

This value may not be changed if the task is currently executing on the signal stack, i.e. if t.onSignalStack returns true. In this case, this function will return false. Otherwise, true is returned.

func (*Task) SetSyscallRestartBlock

func (t *Task) SetSyscallRestartBlock(r SyscallRestartBlock)

SetSyscallRestartBlock sets the restart block for use in restart_syscall(2). After registering a restart block, a syscall should return ERESTART_RESTARTBLOCK to request a restart using the block.

Precondition: The caller must be running on the task goroutine.

func (*Task) SetUID

func (t *Task) SetUID(uid auth.UID) error

SetUID implements the semantics of setuid(2).

func (*Task) SetUserNamespace

func (t *Task) SetUserNamespace(ns *auth.UserNamespace) error

SetUserNamespace attempts to move c into ns.

func (*Task) SetYAMAException

func (t *Task) SetYAMAException(tracer *Task)

SetYAMAException creates a YAMA exception allowing all descendants of tracer to trace t. If tracer is nil, then any task is allowed to trace t.

If there was an existing exception, it is overwritten with the new one.

func (*Task) Setitimer

func (t *Task) Setitimer(id int32, newitv linux.ItimerVal) (linux.ItimerVal, error)

Setitimer implements setitimer(2).

Preconditions: The caller must be running on the task goroutine.

func (*Task) Setns

func (t *Task) Setns(fd *vfs.FileDescription, flags int32) error

Setns reassociates thread with the specified namespace.

func (*Task) SigaltStack

func (t *Task) SigaltStack(setaddr hostarch.Addr, oldaddr hostarch.Addr) (*SyscallControl, error)

SigaltStack implements the sigaltstack syscall.

func (*Task) SignalMask

func (t *Task) SignalMask() linux.SignalSet

SignalMask returns a copy of t's signal mask.

func (*Task) SignalRegister

func (t *Task) SignalRegister(e *waiter.Entry)

SignalRegister registers a waiter for pending signals.

func (*Task) SignalReturn

func (t *Task) SignalReturn(rt bool) (*SyscallControl, error)

SignalReturn implements sigreturn(2) (if rt is false) or rt_sigreturn(2) (if rt is true).

func (*Task) SignalStack

func (t *Task) SignalStack() linux.SignalStack

SignalStack returns the task-private signal stack.

By precondition, a full state has to be pulled.

func (*Task) SignalUnregister

func (t *Task) SignalUnregister(e *waiter.Entry)

SignalUnregister unregisters a waiter for pending signals.

func (*Task) Sigtimedwait

func (t *Task) Sigtimedwait(set linux.SignalSet, timeout time.Duration) (*linux.SignalInfo, error)

Sigtimedwait implements the semantics of sigtimedwait(2).

Preconditions:

  • The caller must be running on the task goroutine.
  • t.exitState < TaskExitZombie.

func (*Task) SingleIOSequence

func (t *Task) SingleIOSequence(addr hostarch.Addr, length int, opts usermem.IOOpts) (usermem.IOSequence, error)

SingleIOSequence returns a usermem.IOSequence representing [addr, addr+length) in t's address space. If this contains addresses outside the application address range, it returns EFAULT. If length exceeds MAX_RW_COUNT, the range is silently truncated.

SingleIOSequence is analogous to Linux's lib/iov_iter.c:import_single_range(). (Note that the non-vectorized read and write syscalls in Linux do not use import_single_range(). However they check access_ok() in fs/read_write.c:vfs_read/vfs_write, and overflowing address ranges are truncated to MAX_RW_COUNT by fs/read_write.c:rw_verify_area().)

func (*Task) Stack

func (t *Task) Stack() *arch.Stack

Stack returns the userspace stack.

Preconditions: The caller must be running on the task goroutine, or t.mu must be locked.

func (*Task) Start

func (t *Task) Start(tid ThreadID)

Start starts the task goroutine. Start must be called exactly once for each task returned by NewTask.

'tid' must be the task's TID in the root PID namespace and it's used for debugging purposes only (set as parameter to Task.run to make it visible in stack dumps).

func (*Task) StartTime

func (t *Task) StartTime() ktime.Time

StartTime returns t's start time.

func (*Task) StateStatus

func (t *Task) StateStatus() string

StateStatus returns a string representation of the task's current state, appropriate for /proc/[pid]/status.

func (*Task) SwapUint32

func (t *Task) SwapUint32(addr hostarch.Addr, new uint32) (uint32, error)

SwapUint32 implements futex.Target.SwapUint32.

func (*Task) SyscallRestartBlock

func (t *Task) SyscallRestartBlock() SyscallRestartBlock

SyscallRestartBlock returns the currently registered restart block for use in restart_syscall(2). This function is *not* idempotent and may be called once per syscall. This function must not be called if a restart block has not been registered for the current syscall.

Precondition: The caller must be running on the task goroutine.

func (*Task) SyscallTable

func (t *Task) SyscallTable() *SyscallTable

SyscallTable returns t's syscall table.

Preconditions: The caller must be running on the task goroutine, or t.mu must be locked.

func (*Task) TGIDInRoot

func (t *Task) TGIDInRoot() ThreadID

TGIDInRoot returns t's TGID in the root PID namespace.

func (*Task) TaskGoroutineState

func (t *Task) TaskGoroutineState() TaskGoroutineState

TaskGoroutineState returns the current state of the task goroutine.

func (*Task) TaskGoroutineStateTime

func (t *Task) TaskGoroutineStateTime() (state TaskGoroutineState, time ktime.Time)

TaskGoroutineStateTime returns the current state of the task goroutine, and the value of Kernel.CPUClockNow() when that state was last updated or refreshed.

func (*Task) TaskImage

func (t *Task) TaskImage() *TaskImage

TaskImage returns t's TaskImage.

Precondition: The caller must be running on the task goroutine, or t.mu must be locked.

func (*Task) TaskSet

func (t *Task) TaskSet() *TaskSet

TaskSet returns the TaskSet containing t.

func (*Task) ThreadGroup

func (t *Task) ThreadGroup() *ThreadGroup

ThreadGroup returns the thread group containing t.

func (*Task) ThreadID

func (t *Task) ThreadID() ThreadID

ThreadID returns t's thread ID in its own PID namespace. If the task is dead, ThreadID returns 0.

func (*Task) Timekeeper

func (t *Task) Timekeeper() *Timekeeper

Timekeeper returns the system Timekeeper.

func (*Task) Tracer

func (t *Task) Tracer() *Task

Tracer returns t's ptrace Tracer.

func (*Task) UTSNamespace

func (t *Task) UTSNamespace() *UTSNamespace

UTSNamespace returns the task's UTS namespace.

func (*Task) UninterruptibleSleepFinish

func (t *Task) UninterruptibleSleepFinish(activate bool)

UninterruptibleSleepFinish implements context.Context.UninterruptibleSleepFinish.

func (*Task) UninterruptibleSleepStart

func (t *Task) UninterruptibleSleepStart(deactivate bool)

UninterruptibleSleepStart implements context.Context.UninterruptibleSleepStart.

func (*Task) UnregisterOnDestroyAction

func (t *Task) UnregisterOnDestroyAction(key TaskDestroyAction)

UnregisterOnDestroyAction unregisters an action previously registered with RegisterOnDestroyAction.

func (*Task) Unshare

func (t *Task) Unshare(flags int32) error

Unshare changes the set of resources t shares with other tasks, as specified by flags.

Preconditions: The caller must be running on the task goroutine.

func (*Task) UnshareFdTable

func (t *Task) UnshareFdTable(maxFd int32)

UnshareFdTable unshares the FdTable that task t shares with other tasks, upto the maxFd.

Preconditions: The caller must be running on the task goroutine.

func (*Task) UserCPUClock

func (t *Task) UserCPUClock() ktime.Clock

UserCPUClock returns a clock measuring the CPU time the task has spent executing application code.

func (*Task) UserNamespace

func (t *Task) UserNamespace() *auth.UserNamespace

UserNamespace returns the user namespace associated with the task.

func (*Task) Value

func (t *Task) Value(key any) any

Value implements context.Context.Value.

Preconditions: The caller must be running on the task goroutine.

func (*Task) Wait

func (t *Task) Wait(opts *WaitOptions) (*WaitResult, error)

Wait waits for an event from a thread group that is a child of t's thread group, or a task in such a thread group, or a task that is ptraced by t, subject to the options specified in opts.

func (*Task) Warningf

func (t *Task) Warningf(fmt string, v ...any)

Warningf logs a warning string by calling log.Warningf.

func (*Task) WithMuLocked

func (t *Task) WithMuLocked(f func(*Task))

WithMuLocked executes f with t.mu locked.

func (*Task) Yield

func (t *Task) Yield()

Yield yields the processor for the calling task.

type TaskCgroupEntry

type TaskCgroupEntry struct {
	HierarchyID uint32 `json:"hierarchy_id"`
	Controllers string `json:"controllers,omitempty"`
	Path        string `json:"path,omitempty"`
}

TaskCgroupEntry represents a line in /proc/<pid>/cgroup, and is used to format a cgroup for display.

type TaskConfig

type TaskConfig struct {
	// Kernel is the owning Kernel.
	Kernel *Kernel

	// Parent is the new task's parent. Parent may be nil.
	Parent *Task

	// If InheritParent is not nil, use InheritParent's parent as the new
	// task's parent.
	InheritParent *Task

	// ThreadGroup is the ThreadGroup the new task belongs to.
	ThreadGroup *ThreadGroup

	// SignalMask is the new task's initial signal mask.
	SignalMask linux.SignalSet

	// TaskImage is the TaskImage of the new task. Ownership of the
	// TaskImage is transferred to TaskSet.NewTask, whether or not it
	// succeeds.
	TaskImage *TaskImage

	// FSContext is the FSContext of the new task. A reference must be held on
	// FSContext, which is transferred to TaskSet.NewTask whether or not it
	// succeeds.
	FSContext *FSContext

	// FDTable is the FDTableof the new task. A reference must be held on
	// FDMap, which is transferred to TaskSet.NewTask whether or not it
	// succeeds.
	FDTable *FDTable

	// Credentials is the Credentials of the new task.
	Credentials *auth.Credentials

	// Niceness is the niceness of the new task.
	Niceness int

	// NetworkNamespace is the network namespace to be used for the new task.
	NetworkNamespace *inet.Namespace

	// AllowedCPUMask contains the cpus that this task can run on.
	AllowedCPUMask sched.CPUSet

	// UTSNamespace is the UTSNamespace of the new task.
	UTSNamespace *UTSNamespace

	// IPCNamespace is the IPCNamespace of the new task.
	IPCNamespace *IPCNamespace

	// MountNamespace is the MountNamespace of the new task.
	MountNamespace *vfs.MountNamespace

	// RSeqAddr is a pointer to the userspace linux.RSeq structure.
	RSeqAddr hostarch.Addr

	// RSeqSignature is the signature that the rseq abort IP must be signed
	// with.
	RSeqSignature uint32

	// ContainerID is the container the new task belongs to.
	ContainerID string

	// InitialCgroups are the cgroups the container is initialised to.
	InitialCgroups map[Cgroup]struct{}

	// UserCounters is user resource counters.
	UserCounters *UserCounters

	// SessionKeyring is the session keyring associated with the parent task.
	// It may be nil.
	SessionKeyring *auth.Key

	Origin TaskOrigin
}

TaskConfig defines the configuration of a new Task (see below).

type TaskDestroyAction

type TaskDestroyAction interface {
	TaskDestroyAction(ctx context.Context)
}

TaskDestroyAction defines an action to be executed when a task is destroyed.

type TaskExitState

type TaskExitState uint32

TaskExitState represents a step in the task exit path.

"Exiting" and "exited" are often ambiguous; prefer to name specific states.

const (
	// TaskExitNone indicates that the task has not begun exiting.
	TaskExitNone TaskExitState = iota

	// TaskExitInitiated indicates that the task goroutine has entered the exit
	// path, and the task is no longer eligible to participate in group stops
	// or group signal handling. TaskExitInitiated is analogous to Linux's
	// PF_EXITING.
	TaskExitInitiated

	// TaskExitZombie indicates that the task has released its resources, and
	// the task no longer prevents a sibling thread from completing execve.
	TaskExitZombie

	// TaskExitDead indicates that the task's thread IDs have been released,
	// and the task no longer prevents its thread group leader from being
	// reaped. ("Reaping" refers to the transitioning of a task from
	// TaskExitZombie to TaskExitDead.)
	TaskExitDead
)

func (TaskExitState) String

func (t TaskExitState) String() string

String implements fmt.Stringer.

type TaskGoroutineState

type TaskGoroutineState uint32

TaskGoroutineState is a coarse representation of the current execution status of a kernel.Task goroutine.

const (
	// TaskGoroutineNonexistent indicates that the task goroutine has either
	// not yet been created by Task.Start() or has returned from Task.run().
	// This must be the zero value for TaskGoroutineState.
	TaskGoroutineNonexistent TaskGoroutineState = iota

	// TaskGoroutineRunningSys indicates that the task goroutine is executing
	// sentry code.
	TaskGoroutineRunningSys

	// TaskGoroutineRunningApp indicates that the task goroutine is executing
	// application code.
	TaskGoroutineRunningApp

	// TaskGoroutineBlockedInterruptible indicates that the task goroutine is
	// blocked in Task.block(), and hence may be woken by Task.interrupt()
	// (e.g. due to signal delivery).
	TaskGoroutineBlockedInterruptible

	// TaskGoroutineBlockedUninterruptible indicates that the task goroutine is
	// stopped outside of Task.block() and Task.doStop(), and hence cannot be
	// woken by Task.interrupt().
	TaskGoroutineBlockedUninterruptible

	// TaskGoroutineStopped indicates that the task goroutine is blocked in
	// Task.doStop(). TaskGoroutineStopped is similar to
	// TaskGoroutineBlockedUninterruptible, but is a separate state to make it
	// possible to determine when Task.stop is meaningful.
	TaskGoroutineStopped
)

type TaskImage

type TaskImage struct {
	// Name is the thread name set by the prctl(PR_SET_NAME) system call.
	Name string

	// Arch is the architecture-specific context (registers, etc.)
	Arch *arch.Context64

	// MemoryManager is the task's address space.
	MemoryManager *mm.MemoryManager
	// contains filtered or unexported fields
}

TaskImage is the subset of a task's data that is provided by the loader.

+stateify savable

func (*TaskImage) FileCaps

func (image *TaskImage) FileCaps() string

FileCaps return the task image's security.capability extended attribute.

func (*TaskImage) Fork

func (image *TaskImage) Fork(ctx context.Context, k *Kernel, shareAddressSpace bool) (*TaskImage, error)

Fork returns a duplicate of image. The copied TaskImage always has an independent arch.Context64. If shareAddressSpace is true, the copied TaskImage shares an address space with the original; otherwise, the copied TaskImage has an independent address space that is initially a duplicate of the original's.

type TaskOrigin

type TaskOrigin int

TaskOrigin indicates how the task was initially created.

const (
	// OriginUnknown indicates that task creation source is not known (or not important).
	OriginUnknown TaskOrigin = iota

	// OriginExec indicates that task was created due to an exec request inside a container.
	OriginExec
)

type TaskSet

type TaskSet struct {

	// Root is the root PID namespace, in which all tasks in the TaskSet are
	// visible. The Root pointer is immutable.
	Root *PIDNamespace
	// contains filtered or unexported fields
}

A TaskSet comprises all tasks in a system.

+stateify savable

func (*TaskSet) BeginExternalStop

func (ts *TaskSet) BeginExternalStop()

BeginExternalStop indicates the start of an external stop that applies to all current and future tasks in ts. BeginExternalStop does not wait for task goroutines to stop.

func (*TaskSet) EndExternalStop

func (ts *TaskSet) EndExternalStop()

EndExternalStop indicates the end of an external stop started by a previous call to TaskSet.BeginExternalStop. EndExternalStop does not wait for task goroutines to resume.

func (*TaskSet) ForEachThreadGroup

func (ts *TaskSet) ForEachThreadGroup(f func(tg *ThreadGroup))

ForEachThreadGroup applies f to each thread group in ts.

func (*TaskSet) IsExiting

func (ts *TaskSet) IsExiting() bool

IsExiting returns true if all tasks in ts are exiting or have exited.

func (*TaskSet) Kill

func (ts *TaskSet) Kill(ws linux.WaitStatus)

Kill requests that all tasks in ts exit as if group exiting with status ws. Kill does not wait for tasks to exit.

Kill has no analogue in Linux; it's provided for save/restore only.

func (*TaskSet) NewTask

func (ts *TaskSet) NewTask(ctx context.Context, cfg *TaskConfig) (*Task, error)

NewTask creates a new task defined by cfg.

NewTask does not start the returned task; the caller must call Task.Start.

If successful, NewTask transfers references held by cfg to the new task. Otherwise, NewTask releases them.

func (*TaskSet) PullFullState

func (ts *TaskSet) PullFullState()

PullFullState receives full states for all tasks.

type TaskStop

type TaskStop interface {
	// Killable returns true if Task.Kill should end the stop prematurely.
	// Killable is analogous to Linux's TASK_WAKEKILL.
	Killable() bool
}

A TaskStop is a condition visible to the task control flow graph that prevents a task goroutine from running or exiting, i.e. an internal stop.

NOTE(b/30793614): Most TaskStops don't contain any data; they're distinguished by their type. The obvious way to implement such a TaskStop is:

type groupStop struct{}
func (groupStop) Killable() bool { return true }
...
t.beginInternalStop(groupStop{})

However, this doesn't work because the state package can't serialize values, only pointers. Furthermore, the correctness of save/restore depends on the ability to pass a TaskStop to endInternalStop that will compare equal to the TaskStop that was passed to beginInternalStop, even if a save/restore cycle occurred between the two. As a result, the current idiom is to always use a typecast nil for data-free TaskStops:

type groupStop struct{}
func (*groupStop) Killable() bool { return true }
...
t.beginInternalStop((*groupStop)(nil))

This is pretty gross, but the alternatives seem grosser.

type TaskWorker

type TaskWorker interface {
	// TaskWork will be executed prior to returning to user space. Note that
	// TaskWork may call RegisterWork again, but this will not be executed until
	// the next return to user space, unlike in Linux. This effectively allows
	// registration of indefinite user return hooks, but not by default.
	TaskWork(t *Task)
}

TaskWorker is a deferred task.

This must be savable.

type ThreadGroup

type ThreadGroup struct {
	// contains filtered or unexported fields
}

A ThreadGroup is a logical grouping of tasks that has widespread significance to other kernel features (e.g. signal handling). ("Thread groups" are usually called "processes" in userspace documentation.)

ThreadGroup is a superset of Linux's struct signal_struct.

+stateify savable

func (*ThreadGroup) CPUClock

func (tg *ThreadGroup) CPUClock() ktime.Clock

CPUClock returns a ktime.Clock that measures the time that a thread group has spent executing, including sentry time.

func (*ThreadGroup) CPUStats

func (tg *ThreadGroup) CPUStats() usage.CPUStats

CPUStats returns the combined CPU usage statistics of all past and present threads in tg.

func (*ThreadGroup) Count

func (tg *ThreadGroup) Count() int

Count returns the number of non-exited threads in the group.

func (*ThreadGroup) CreateProcessGroup

func (tg *ThreadGroup) CreateProcessGroup() error

CreateProcessGroup creates a new process group.

An EPERM error will be returned if the ThreadGroup belongs to a different Session, is a Session leader or the group already exists.

func (*ThreadGroup) CreateSession

func (tg *ThreadGroup) CreateSession() (SessionID, error)

CreateSession creates a new Session, with the ThreadGroup as the leader.

EPERM may be returned if either the given ThreadGroup is already a Session leader, or a ProcessGroup already exists for the ThreadGroup's ID.

func (*ThreadGroup) ExitStatus

func (tg *ThreadGroup) ExitStatus() linux.WaitStatus

ExitStatus returns the exit status that would be returned by a consuming wait*() on tg.

func (*ThreadGroup) ForegroundProcessGroup

func (tg *ThreadGroup) ForegroundProcessGroup(tty *TTY) (*ProcessGroup, error)

ForegroundProcessGroup returns the foreground process group of the thread group.

func (*ThreadGroup) ForegroundProcessGroupID

func (tg *ThreadGroup) ForegroundProcessGroupID(tty *TTY) (ProcessGroupID, error)

ForegroundProcessGroupID returns the foreground process group ID of the thread group.

func (*ThreadGroup) ID

func (tg *ThreadGroup) ID() ThreadID

ID returns tg's leader's thread ID in its own PID namespace. If tg's leader is dead, ID returns 0.

func (*ThreadGroup) IOUsage

func (tg *ThreadGroup) IOUsage() *usage.IO

IOUsage returns the total io usage of all dead and live threads in the group.

func (*ThreadGroup) IsChildSubreaper

func (tg *ThreadGroup) IsChildSubreaper() bool

IsChildSubreaper returns whether this ThreadGroup is a child subreaper.

func (*ThreadGroup) IsInitIn

func (tg *ThreadGroup) IsInitIn(pidns *PIDNamespace) bool

IsInitIn returns whether this ThreadGroup has TID 1 int the given PIDNamespace.

func (*ThreadGroup) JoinProcessGroup

func (tg *ThreadGroup) JoinProcessGroup(pidns *PIDNamespace, pgid ProcessGroupID, checkExec bool) error

JoinProcessGroup joins an existing process group.

This function will return EACCES if an exec has been performed since fork by the given ThreadGroup, and EPERM if the Sessions are not the same or the group does not exist.

If checkExec is set, then the join is not permitted after the process has executed exec at least once.

func (*ThreadGroup) JoinedChildCPUStats

func (tg *ThreadGroup) JoinedChildCPUStats() usage.CPUStats

JoinedChildCPUStats implements the semantics of RUSAGE_CHILDREN: "Return resource usage statistics for all children of [tg] that have terminated and been waited for. These statistics will include the resources used by grandchildren, and further removed descendants, if all of the intervening descendants waited on their terminated children."

func (*ThreadGroup) Leader

func (tg *ThreadGroup) Leader() *Task

Leader returns tg's leader.

func (*ThreadGroup) Limits

func (tg *ThreadGroup) Limits() *limits.LimitSet

Limits returns tg's limits.

func (*ThreadGroup) MemberIDs

func (tg *ThreadGroup) MemberIDs(pidns *PIDNamespace) []ThreadID

MemberIDs returns a snapshot of the ThreadIDs (in PID namespace pidns) for all tasks in tg.

func (*ThreadGroup) MigrateCgroup

func (tg *ThreadGroup) MigrateCgroup(dst Cgroup) error

MigrateCgroup migrates all tasks in tg to the dst cgroup. Either all tasks are migrated, or none are. Atomicity of migrations wrt cgroup membership (i.e. a task can't switch cgroups mid-migration due to another migration) is guaranteed because migrations are serialized by TaskSet.mu.

func (*ThreadGroup) PIDNamespace

func (tg *ThreadGroup) PIDNamespace() *PIDNamespace

PIDNamespace returns the PID namespace containing tg.

func (*ThreadGroup) ProcessGroup

func (tg *ThreadGroup) ProcessGroup() *ProcessGroup

ProcessGroup returns the ThreadGroup's ProcessGroup.

A reference is not taken on the process group.

func (*ThreadGroup) Release

func (tg *ThreadGroup) Release(ctx context.Context)

Release releases the thread group's resources.

func (*ThreadGroup) ReleaseControllingTTY

func (tg *ThreadGroup) ReleaseControllingTTY(tty *TTY) error

ReleaseControllingTTY gives up tty as the controlling tty of tg.

func (*ThreadGroup) SendSignal

func (tg *ThreadGroup) SendSignal(info *linux.SignalInfo) error

SendSignal sends the given signal to tg, using tg's leader to determine if the signal is blocked.

func (*ThreadGroup) Session

func (tg *ThreadGroup) Session() *Session

Session returns the ThreadGroup's Session.

A reference is not taken on the session.

func (*ThreadGroup) SetChildSubreaper

func (tg *ThreadGroup) SetChildSubreaper(isSubreaper bool)

SetChildSubreaper marks this ThreadGroup sets the isChildSubreaper field on this ThreadGroup, and marks all child ThreadGroups as having a subreaper. Recursion stops if we find another subreaper process, which is either a ThreadGroup with isChildSubreaper bit set, or a ThreadGroup with PID=1 inside a PID namespace.

func (*ThreadGroup) SetControllingTTY

func (tg *ThreadGroup) SetControllingTTY(ctx context.Context, tty *TTY, steal bool, isReadable bool) error

SetControllingTTY sets tty as the controlling terminal of tg.

func (*ThreadGroup) SetForegroundProcessGroupID

func (tg *ThreadGroup) SetForegroundProcessGroupID(tty *TTY, pgid ProcessGroupID) error

SetForegroundProcessGroupID sets the foreground process group of tty to pgid.

func (*ThreadGroup) SetSigAction

func (tg *ThreadGroup) SetSigAction(sig linux.Signal, actptr *linux.SigAction) (linux.SigAction, error)

SetSigAction atomically sets the thread group's signal action for signal sig to *actptr (if actptr is not nil) and returns the old signal action.

func (*ThreadGroup) SignalHandlers

func (tg *ThreadGroup) SignalHandlers() *SignalHandlers

SignalHandlers returns the signal handlers used by tg. The returned value may be racy; see the field comment for ThreadGroup.signalHandlers.

func (*ThreadGroup) TTY

func (tg *ThreadGroup) TTY() *TTY

TTY returns the thread group's controlling terminal. If nil, there is no controlling terminal.

func (*ThreadGroup) TaskSet

func (tg *ThreadGroup) TaskSet() *TaskSet

TaskSet returns the TaskSet containing tg.

func (*ThreadGroup) TerminationSignal

func (tg *ThreadGroup) TerminationSignal() linux.Signal

TerminationSignal returns the thread group's termination signal, which is the signal that will be sent to its leader's parent when all threads have exited.

func (*ThreadGroup) UserCPUClock

func (tg *ThreadGroup) UserCPUClock() ktime.Clock

UserCPUClock returns a ktime.Clock that measures the time that a thread group has spent executing.

func (*ThreadGroup) WaitExited

func (tg *ThreadGroup) WaitExited()

WaitExited blocks until all task goroutines in tg have exited.

WaitExited does not correspond to anything in Linux; it's provided so that external callers of Kernel.CreateProcess can wait for the created thread group to terminate.

type ThreadID

type ThreadID int32

ThreadID is a generic thread identifier.

+marshal

func (ThreadID) String

func (tid ThreadID) String() string

String returns a decimal representation of the ThreadID.

type Timekeeper

type Timekeeper struct {
	// contains filtered or unexported fields
}

Timekeeper manages all of the kernel clocks.

+stateify savable

func NewTimekeeper

func NewTimekeeper() *Timekeeper

NewTimekeeper returns a Timekeeper that is automatically kept up-to-date. NewTimekeeper does not take ownership of paramPage.

SetClocks must be called on the returned Timekeeper before it is usable.

func (*Timekeeper) AfterFunc

func (t *Timekeeper) AfterFunc(d time.Duration, f func()) tcpip.Timer

AfterFunc implements tcpip.Clock.

func (*Timekeeper) BootTime

func (t *Timekeeper) BootTime() ktime.Time

BootTime returns the system boot real time.

func (*Timekeeper) Destroy

func (t *Timekeeper) Destroy()

Destroy destroys the Timekeeper, freeing all associated resources.

func (*Timekeeper) GetTime

func (t *Timekeeper) GetTime(c sentrytime.ClockID) (int64, error)

GetTime returns the current time in nanoseconds.

func (*Timekeeper) Now

func (t *Timekeeper) Now() time.Time

Now implements tcpip.Clock.

func (*Timekeeper) NowMonotonic

func (t *Timekeeper) NowMonotonic() tcpip.MonotonicTime

NowMonotonic implements tcpip.Clock.

func (*Timekeeper) PauseUpdates

func (t *Timekeeper) PauseUpdates()

PauseUpdates stops clock parameter updates. This should only be used when Tasks are not running and thus cannot access the clock.

func (*Timekeeper) ResumeUpdates

func (t *Timekeeper) ResumeUpdates(params *VDSOParamPage)

ResumeUpdates restarts clock parameter updates stopped by PauseUpdates.

func (*Timekeeper) SetClocks

func (t *Timekeeper) SetClocks(c sentrytime.Clocks, params *VDSOParamPage)

SetClocks the backing clock source.

SetClocks must be called before the Timekeeper is used, and it may not be called more than once, as changing the clock source without extra correction could cause time discontinuities.

It must also be called after Load.

type UTSNamespace

type UTSNamespace struct {
	// contains filtered or unexported fields
}

UTSNamespace represents a UTS namespace, a holder of two system identifiers: the hostname and domain name.

+stateify savable

func NewUTSNamespace

func NewUTSNamespace(hostName, domainName string, userns *auth.UserNamespace) *UTSNamespace

NewUTSNamespace creates a new UTS namespace.

func UTSNamespaceFromContext

func UTSNamespaceFromContext(ctx context.Context) *UTSNamespace

UTSNamespaceFromContext returns the UTS namespace in which ctx is executing, or nil if there is no such UTS namespace.

func (*UTSNamespace) Clone

func (u *UTSNamespace) Clone(userns *auth.UserNamespace) *UTSNamespace

Clone makes a copy of this UTS namespace, associating the given user namespace.

func (*UTSNamespace) DecRef

func (u *UTSNamespace) DecRef(ctx context.Context)

DecRef decrements the namespace's refcount.

func (*UTSNamespace) Destroy

func (u *UTSNamespace) Destroy(ctx context.Context)

Destroy implements nsfs.Namespace.Destroy.

func (*UTSNamespace) DomainName

func (u *UTSNamespace) DomainName() string

DomainName returns the domain name of this UTS namespace.

func (*UTSNamespace) GetInode

func (u *UTSNamespace) GetInode() *nsfs.Inode

GetInode returns the nsfs inode associated with the UTS namespace.

func (*UTSNamespace) HostName

func (u *UTSNamespace) HostName() string

HostName returns the host name of this UTS namespace.

func (*UTSNamespace) IncRef

func (u *UTSNamespace) IncRef()

IncRef increments the Namespace's refcount.

func (*UTSNamespace) SetDomainName

func (u *UTSNamespace) SetDomainName(domain string)

SetDomainName sets the domain name of this UTS namespace.

func (*UTSNamespace) SetHostName

func (u *UTSNamespace) SetHostName(host string)

SetHostName sets the host name of this UTS namespace.

func (*UTSNamespace) SetInode

func (u *UTSNamespace) SetInode(inode *nsfs.Inode)

SetInode sets the nsfs `inode` to the UTS namespace.

func (*UTSNamespace) Type

func (u *UTSNamespace) Type() string

Type implements nsfs.Namespace.Type.

func (*UTSNamespace) UserNamespace

func (u *UTSNamespace) UserNamespace() *auth.UserNamespace

UserNamespace returns the user namespace associated with this UTS namespace.

type UserCounters

type UserCounters struct {
	// contains filtered or unexported fields
}

UserCounters is a set of user counters.

+stateify savable

type VDSOParamPage

type VDSOParamPage struct {
	// contains filtered or unexported fields
}

VDSOParamPage manages a VDSO parameter page.

Its memory layout looks like:

type page struct {
	// seq is a sequence counter that protects the fields below.
	seq uint64
	vdsoParams
}

Everything in the struct is 8 bytes for easy alignment.

It must be kept in sync with params in vdso/vdso_time.cc.

+stateify savable

func NewVDSOParamPage

func NewVDSOParamPage(mf *pgalloc.MemoryFile, fr memmap.FileRange) *VDSOParamPage

NewVDSOParamPage returns a VDSOParamPage.

Preconditions:

  • fr is a single page allocated from mf. VDSOParamPage does not take ownership of fr; it must remain allocated for the lifetime of the VDSOParamPage.
  • VDSOParamPage must be the only writer to fr.
  • mf.MapInternal(fr) must return a single safemem.Block.

func (*VDSOParamPage) Write

func (v *VDSOParamPage) Write(f func() vdsoParams) error

Write updates the VDSO parameters.

Write starts a write block, calls f to get the new parameters, writes out the new parameters, then ends the write block.

type Version

type Version struct {
	// Operating system name (e.g. "Linux").
	Sysname string

	// Operating system release (e.g. "4.4-amd64").
	Release string

	// Operating system version. On Linux this takes the shape
	// "#VERSION CONFIG_FLAGS TIMESTAMP"
	// where:
	//	- VERSION is a sequence counter incremented on every successful build
	//	- CONFIG_FLAGS is a space-separated list of major enabled kernel features
	//    (e.g. "SMP" and "PREEMPT")
	//	- TIMESTAMP is the build timestamp as returned by `date`
	Version string
}

Version defines the application-visible system version.

type WaitOptions

type WaitOptions struct {
	// If SpecificTID is non-zero, only events from the task with thread ID
	// SpecificTID are eligible to be waited for. SpecificTID is resolved in
	// the PID namespace of the waiter (the method receiver of Task.Wait). If
	// no such task exists, or that task would not otherwise be eligible to be
	// waited for by the waiting task, then there are no waitable tasks and
	// Wait will return ECHILD.
	SpecificTID ThreadID

	// If SpecificPGID is non-zero, only events from ThreadGroups with a
	// matching ProcessGroupID are eligible to be waited for. (Same
	// constraints as SpecificTID apply.)
	SpecificPGID ProcessGroupID

	// If NonCloneTasks is true, events from non-clone tasks are eligible to be
	// waited for.
	NonCloneTasks bool

	// If CloneTasks is true, events from clone tasks are eligible to be waited
	// for.
	CloneTasks bool

	// If SiblingChildren is true, events from children tasks of any task
	// in the thread group of the waiter are eligible to be waited for.
	SiblingChildren bool

	// Events is a bitwise combination of the events defined above that specify
	// what events are of interest to the call to Wait.
	Events waiter.EventMask

	// If ConsumeEvent is true, the Wait should consume the event such that it
	// cannot be returned by a future Wait. Note that if a task exit is
	// consumed in this way, in most cases the task will be reaped.
	ConsumeEvent bool

	// If BlockInterruptErr is not nil, Wait will block until either an event
	// is available or there are no tasks that could produce a waitable event;
	// if that blocking is interrupted, Wait returns BlockInterruptErr. If
	// BlockInterruptErr is nil, Wait will not block.
	BlockInterruptErr error
}

WaitOptions controls the behavior of Task.Wait.

type WaitResult

type WaitResult struct {
	// Task is the task that reported the event.
	Task *Task

	// TID is the thread ID of Task in the PID namespace of the task that
	// called Wait (that is, the method receiver of the call to Task.Wait). TID
	// is provided because consuming exit waits cause the thread ID to be
	// deallocated.
	TID ThreadID

	// UID is the real UID of Task in the user namespace of the task that
	// called Wait.
	UID auth.UID

	// Event is exactly one of the events defined above.
	Event waiter.EventMask

	// Status is the wait status associated with the event.
	Status linux.WaitStatus
}

WaitResult contains information about a waited-for event.

Directories

Path Synopsis
Package auth implements an access control model that is a subset of Linux's.
Package auth implements an access control model that is a subset of Linux's.
Package contexttest provides a test context.Context which includes a dummy kernel pointing to a valid platform.
Package contexttest provides a test context.Context which includes a dummy kernel pointing to a valid platform.
Package fasync provides FIOASYNC related functionality.
Package fasync provides FIOASYNC related functionality.
Package futex provides an implementation of the futex interface as found in the Linux kernel.
Package futex provides an implementation of the futex interface as found in the Linux kernel.
Package ipc defines functionality and utilities common to sysvipc mechanisms.
Package ipc defines functionality and utilities common to sysvipc mechanisms.
Package memevent implements the memory usage events controller, which periodically emits events via the eventchannel.
Package memevent implements the memory usage events controller, which periodically emits events via the eventchannel.
Package mq provides an implementation for POSIX message queues.
Package mq provides an implementation for POSIX message queues.
Package msgqueue implements System V message queues.
Package msgqueue implements System V message queues.
Package pipe provides a pipe implementation.
Package pipe provides a pipe implementation.
Package sched implements scheduler related features.
Package sched implements scheduler related features.
Package semaphore implements System V semaphores.
Package semaphore implements System V semaphores.
Package shm implements sysv shared memory segments.
Package shm implements sysv shared memory segments.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL