sandboxenv

package
v0.6.13 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package sandboxenv holds the environment a sandbox was created with, for a guest whose agent cannot inherit it.

A container created cold starts toolboxd with the sandbox's env already in its own process environment, so every exec, session and terminal inherits it through os.Environ(). A Firecracker guest boots from a rootfs or a template snapshot that never saw the create request, so the host pushes the env over vsock once the agent is up (the set_env op) and toolboxd keeps it here. A containerd warm-pool container was started from the pool's spec, which never saw the create request either: the host sends the env in the adopt frame on the ready socket, and toolboxd keeps it here before it takes the identity and starts the held-back image command.

The env is how users pass secrets, so this package keeps it in memory only: nothing here writes it to a file or logs it, and errors never quote a key or a value. toolboxd is PID 1 in a Firecracker guest (toolboxd-init execs it), so there is no in-guest restart that could come back without it: if toolboxd exits the guest kernel panics and the VM is gone. In a container toolboxd is PID 1 too, and a restart is a new task that boots parked again and is adopted again, with the env re-sent from the sealed row.

Index

Constants

This section is empty.

Variables

View Source
var ErrInvalid = errors.New("sandbox env has an empty key, a key containing '=', or a NUL byte")

ErrInvalid is returned for an env the guest cannot apply: an empty key, or a key or value the kernel's environ format cannot carry. The message names neither the key nor the value, since either could be a secret pasted into the wrong field.

Functions

func Validate

func Validate(env map[string]string) error

Validate reports whether env can be laid over a process environment. Keys may not be empty or contain '=' (the environ separator); neither keys nor values may contain NUL (the environ terminator).

Types

type Store

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

Store is the sandbox env of one guest. The zero value is an empty store, ready to use. Safe for concurrent use: Replace swaps the whole map under the lock, so a reader sees either the old env or the new one, never half.

func (*Store) Environ

func (s *Store) Environ(base []string) []string

Environ lays the sandbox env over base (a process environment, normally os.Environ()) and returns a new slice; base is not modified.

The precedence is the container one: the image's env, then the sandbox env, then whatever a request adds on top (callers append per-request env after this, and os/exec keeps the last value of a repeated key). A key the sandbox env sets is dropped from base rather than repeated, so a child's /proc/<pid>/environ shows each key once. A sandbox env that sets PATH also sets the PATH login shells put back (loginshell.Env), as a container started with that PATH records it.

func (*Store) Len

func (s *Store) Len() int

Len is the number of keys in the sandbox env.

func (*Store) Replace

func (s *Store) Replace(env map[string]string) (bool, error)

Replace sets the sandbox env to exactly env, dropping any key the previous env had and env does not. Replace, not merge, is what makes a re-delivered push converge: sending the same env twice leaves the store as one push did, and a retried push after a lost ack cannot append duplicates. It reports whether the env changed.

Jump to

Keyboard shortcuts

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