Documentation
¶
Overview ¶
Package guest is the typed client for the ossein guest agent — the PID-1 init inside the microVM (guest/vminitd + guest/internal/guestagent) — over its Connect-on-vsock control channel. The wire contract is proto/SandboxContext.proto, vendored verbatim from apple/containerization at the ref in proto/PIN, and both ends import ONE generated tree (internal/sandbox), so the wire types cannot drift between them.
Index ¶
- Variables
- type Agent
- func (a *Agent) AddrAdd(ctx context.Context, iface, cidr string) error
- func (a *Agent) Close() error
- func (a *Agent) CloseProcessStdin(ctx context.Context, processID string) error
- func (a *Agent) ConfigureDNS(ctx context.Context, location string, nameservers []string) error
- func (a *Agent) ConfigureHosts(ctx context.Context, location string, entries []HostsEntry) error
- func (a *Agent) CopyInArchive(ctx context.Context, path, device string) error
- func (a *Agent) CreateProcess(ctx context.Context, processID string, specJSON []byte, stdio StdioPorts) error
- func (a *Agent) Getenv(ctx context.Context, key string) (string, error)
- func (a *Agent) KillProcess(ctx context.Context, processID string, signal int32) error
- func (a *Agent) LinkUp(ctx context.Context, iface string) error
- func (a *Agent) Mkdir(ctx context.Context, path string, all bool, perms uint32) error
- func (a *Agent) Mount(ctx context.Context, typ, source, destination string, options []string) error
- func (a *Agent) ProxyVsockOutOf(ctx context.Context, id string, vsockPort uint32, guestPath string) error
- func (a *Agent) ResizeProcess(ctx context.Context, processID string, rows, cols uint32) error
- func (a *Agent) RouteAddDefault(ctx context.Context, iface, gateway string) error
- func (a *Agent) SetupEmulator(ctx context.Context, name, binaryPath, offset, magic, mask, flags string) error
- func (a *Agent) StartProcess(ctx context.Context, processID string) (int32, error)
- func (a *Agent) StopVsockProxy(ctx context.Context, id string) error
- func (a *Agent) Sync(ctx context.Context) error
- func (a *Agent) Umount(ctx context.Context, path string) error
- func (a *Agent) WaitProcess(ctx context.Context, processID string) (int32, error)
- func (a *Agent) WriteFile(ctx context.Context, path string, data []byte, mode uint32) error
- type HostsEntry
- type StdioPorts
Constants ¶
This section is empty.
Variables ¶
var ErrAgent = errors.New("vminitd agent failure")
ErrAgent indicates a vminitd (guest agent) operation failed — every RPC wrapper folds its failure into this sentinel, so a caller can check errors.Is(err, guest.ErrAgent) for "the guest agent misbehaved".
Functions ¶
This section is empty.
Types ¶
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
Agent is a connected guest-agent client. It speaks two services over one http.Client for the vendored SandboxContext contract.
func Dial ¶
Dial connects to the guest agent through connect (a factory producing fresh vsock conns, since net/http opens a new connection per concurrent call and may redial), then verifies liveness AND protocol compatibility in one round-trip: the guest echoes protocol.Revision back through protocol.RevEnvVar, and anything else is refused. The default embedded initfs is build-time paired with this binary, so a mismatch only happens — by design — when --initfs/OSSEIN_INITFS substitutes a foreign guest.
func (*Agent) Close ¶
Close shuts the control channel down. There is no single connection to close any more: the transport owns a pool of vsock conns, so closing means dropping all of them. Nothing here can fail, but the error return is kept — callers defer it, and the signature is the package's contract.
func (*Agent) CloseProcessStdin ¶
CloseProcessStdin closes the guest-side stdin of the process.
func (*Agent) ConfigureDNS ¶
ConfigureDNS writes a resolv.conf at location (an absolute guest path).
func (*Agent) ConfigureHosts ¶
ConfigureHosts writes an /etc/hosts at location (an absolute guest path).
func (*Agent) CopyInArchive ¶
CopyInArchive has vminitd extract a tar+lz4 archive — the rootfs blob the host attached as a read-only virtio-blk disk at VM creation — from device into path, as guest root: full Linux metadata fidelity with zero extra guest binaries and no host-side data path.
func (*Agent) CreateProcess ¶
func (a *Agent) CreateProcess(ctx context.Context, processID string, specJSON []byte, stdio StdioPorts) error
CreateProcess registers the container init process under id. Ossein runs exactly one process per throwaway VM, and the guest's convention for the init process is procID == containerID — so the wrappers take a single id and set both wire fields. specJSON is the full OCI runtime spec.
func (*Agent) KillProcess ¶
KillProcess signals the process. The response's `result` field is vestigial Apple-proto surface — the guest reports failure via the RPC error code and always leaves it zero — so only the error is meaningful.
func (*Agent) ProxyVsockOutOf ¶
func (a *Agent) ProxyVsockOutOf(ctx context.Context, id string, vsockPort uint32, guestPath string) error
ProxyVsockOutOf asks vminitd to listen on vsockPort inside the guest and forward each accepted connection to the unix socket at guestPath — the host end then reaches that guest socket via vm.Connect(vsockPort).
Semantics per vminitd's VsockProxy: OUT_OF = vminitd listens on VSOCK and dials the guest unix path (pull traffic out of the guest); INTO = vminitd creates/listens on the guest unix path and dials the HOST over vsock (push host services into the guest). guestPath is resolved in the guest ROOT namespace — container sockets must be rootfs-prefixed.
func (*Agent) ResizeProcess ¶
ResizeProcess resizes the process's TTY.
func (*Agent) RouteAddDefault ¶
RouteAddDefault installs the guest's default route via gateway.
func (*Agent) SetupEmulator ¶
func (a *Agent) SetupEmulator(ctx context.Context, name, binaryPath, offset, magic, mask, flags string) error
SetupEmulator registers a binfmt_misc handler — the Rosetta hook. Values mirror the documented rosetta binfmt registration line.
func (*Agent) StartProcess ¶
StartProcess starts a created process and returns its guest pid.
func (*Agent) StopVsockProxy ¶
StopVsockProxy tears down a proxy previously registered under id, closing the guest-side listener.
func (*Agent) WaitProcess ¶
WaitProcess blocks until the process exits and returns its exit code.
type HostsEntry ¶
HostsEntry is one /etc/hosts line.
type StdioPorts ¶
StdioPorts are host-side vsock listener ports the guest connects back to for each stream; nil means the stream is not wired.
Source Files