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
- func CleanupCtx(ctx context.Context) (context.Context, context.CancelFunc)
- func ExitError(name, label string, err error) error
- func Output(ctx context.Context, r Runner, bin string, args ...string) (string, error)
- type Cmd
- type Config
- type ExecRunner
- type Remote
- func (r *Remote) Exec(ctx context.Context, name string, argv []string, stdin io.Reader, ...) error
- func (r *Remote) Get(ctx context.Context, name, srcDir, dstDir string, maxBytes int64, ...) (err error)
- func (r *Remote) Network(ctx context.Context, name string) (workspace.Network, error)
- func (r *Remote) Output(ctx context.Context, name string, argv ...string) (string, error)
- func (r *Remote) Put(ctx context.Context, name, srcDir, dstDir string) error
- type Runner
Constants ¶
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.
const MaxGet = 64 << 20
MaxGet is the drivers' default bound on Get's compressed stream; host.Extract bounds what it unpacks to.
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.
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 ¶
CleanupCtx is a context for cleanup that runs after ctx is done too.
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.
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 (*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 ¶
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).
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.