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 ¶
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 ¶
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 ¶
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) Replace ¶
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.