vmexec

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package vmexec is what the workspace drivers share (design/workstreams/agent/LLD/ workspace-kata.md#the-driver-internalagentworkspacekata): running commands in a workspace through the driver's exec command, and over it Put's and Get's tar streams, Exec with its pid-file cancel, and the network read. A driver supplies only its exec prefix (tart exec [-i] <name>, or sudo -n kata-helper exec [-i] <name>) and its lifecycle verbs.

Callers check workspace names (workspace.ValidName) before calling; this package checks the VM paths and file names, and treats everything the VM sends back as untrusted.

Index

Constants

View Source
const ExecScript = `echo $$ > "$0" && exec "$@"`

ExecScript, with $0 the pid file and "$@" the command, records its pid and becomes the command, so a cancel can signal it: the exec commands don't forward signals.

View Source
const MaxGet = 64 << 20

MaxGet is the drivers' default bound on Get's compressed stream; host.Extract bounds what it unpacks to.

View Source
const PutScript = `set -eu; rm -rf "$0"; mkdir -p "$0"; tar -xf - -C "$0" --no-same-owner; chown -R root:root "$0"; chmod -R a+rX,a-w "$0"`

PutScript, run as root with $0 the destination, replaces it with the tar stream on stdin, root's and read-only: a+rX,a-w makes files 0444 and directories and executables 0555.

View Source
const SignalScript = `test -s "$0" && exec sudo -n kill -s "$1" "$(cat "$0")"`

SignalScript, with $0 the pid file and $1 the signal, signals the process it names.

Variables

This section is empty.

Functions

func CleanupCtx

func CleanupCtx(ctx context.Context) (context.Context, context.CancelFunc)

CleanupCtx is a context for cleanup that runs after ctx is done too.

func ExitError

func ExitError(name, label string, err error) error

ExitError maps the exec command's exit to *workspace.ExitError when it's a non-zero status, and to an exec failure under label otherwise.

func Output

func Output(ctx context.Context, r Runner, bin string, args ...string) (string, error)

Output runs bin with args and returns its stdout; a failure carries stderr's first line.

Types

type Cmd

type Cmd struct {
	Name string
	Args []string
	// Env is added to the environment (a later entry wins).
	Env    []string
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

Cmd is one invocation of a driver's command (tart, or sudo and the kata helper).

type Config

type Config struct {
	Runner Runner
	// Prefix is the command that runs argv in workspace name, its binary first; stdin is set
	// when argv reads standard input (tart exec -i).
	Prefix func(name string, stdin bool) []string
	// Label names the exec command in errors: "tart exec".
	Label string
	// Grace is how long Exec waits after the remote SIGTERM before SIGKILL.
	Grace time.Duration
}

Config is a driver's exec command and its cancel grace.

type ExecRunner

type ExecRunner struct {
	// SudoGrace is how long a cancelled sudo call (the kata helper's verbs) gets after SIGTERM
	// before SIGKILL. Default: sudocancel.HelperGrace.
	SudoGrace time.Duration
}

ExecRunner runs real programs.

func (ExecRunner) Run

func (r ExecRunner) Run(ctx context.Context, c Cmd) error

Run implements Runner. When ctx ends, a sudo call gets SIGTERM, which sudo relays to the kata helper, and SIGKILL only after SudoGrace; anything else (tart) gets SIGKILL (sudocancel.Apply).

func (ExecRunner) Start

func (ExecRunner) Start(c Cmd) (host.Process, error)

Start implements Runner, with host.StartCmd: Stop sends the group SIGTERM, then SIGKILL.

type Remote

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

Remote runs commands in a driver's workspaces. It's safe for concurrent use.

func New

func New(c Config) *Remote

New returns a Remote; c's fields are all required.

func (*Remote) Exec

func (r *Remote) Exec(ctx context.Context, name string, argv []string, stdin io.Reader, stdout, stderr io.Writer, status func(error) error) error

Exec implements workspace.Driver's Exec: <prefix [-i]> sh -c ExecScript <pid file> argv…. When ctx is done it signals the remote process through another exec (TERM, then KILL after Grace) and stops the local exec command once it hasn't exited. status maps the exec command's exit (nil for success) to Exec's error; nil means ExitError under Label.

func (*Remote) Get

func (r *Remote) Get(ctx context.Context, name, srcDir, dstDir string, maxBytes int64, files ...string) (err error)

Get implements workspace.Driver's Get: <prefix> sudo tar -czf - -C <srcDir> . (or the named files, with GNU tar's --ignore-failed-read so a missing one is only a warning) into a temp file next to dstDir (at most maxBytes), then host.Extract into dstDir. A failure removes dstDir.

func (*Remote) Network

func (r *Remote) Network(ctx context.Context, name string) (workspace.Network, error)

Network reads the VM's default route (via: the host's address on the VM's network) and the address the VM sends from to it (src: its own).

func (*Remote) Output

func (r *Remote) Output(ctx context.Context, name string, argv ...string) (string, error)

Output runs argv in name and returns its stdout, as the package's Output.

func (*Remote) Put

func (r *Remote) Put(ctx context.Context, name, srcDir, dstDir string) error

Put implements workspace.Driver's Put: a tar stream of srcDir (directories and regular files only) into <prefix -i> sudo sh -c PutScript.

type Runner

type Runner interface {
	// Run runs c to completion; ctx being done kills it (a sudo call gets SIGTERM first).
	Run(ctx context.Context, c Cmd) error
	// Start starts c in its own process group, not tied to a context: its owner stops it.
	Start(c Cmd) (host.Process, error)
}

Runner runs a driver's commands. Tests use a fake; nothing in them runs the real ones.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL