Documentation
¶
Overview ¶
Package sandbox provides the core sandbox VM management functionality.
Index ¶
- Variables
- func DefaultGuestAgentPath() string
- func DefaultGuestFusedPath() string
- func DefaultGuestInitPath() string
- func DefaultInitramfsPath() string
- func DefaultKernelPath() string
- func DefaultKernelPathWithVersion(version string) (string, error)
- func ExecInteractiveViaRelay(ctx context.Context, socketPath, command, workingDir, user string, ...) (int, error)
- func ExecPipeViaRelay(ctx context.Context, socketPath, command, workingDir, user string, ...) (int, error)
- func ExecViaRelay(ctx context.Context, socketPath, command, workingDir, user string) (*api.ExecResult, error)
- func KernelArch() string
- func KernelVersion() string
- func PortForwardViaRelay(ctx context.Context, relaySocketPath string, remotePort int, ...) error
- type AllowListUpdateResult
- type ExecRelay
- type FirewallRules
- type Options
- type PortForwardManager
- type Sandbox
- func (s *Sandbox) AddAllowedHosts(ctx context.Context, hosts []string) ([]string, error)
- func (s *Sandbox) AllowedHosts(ctx context.Context) ([]string, error)
- func (s *Sandbox) CAPool() *sandboxnet.CAPool
- func (s *Sandbox) Close(ctx context.Context) error
- func (s *Sandbox) Config() *api.Config
- func (s *Sandbox) Events() <-chan api.Event
- func (s *Sandbox) Exec(ctx context.Context, command string, opts *api.ExecOptions) (*api.ExecResult, error)
- func (s *Sandbox) ExecInteractive(ctx context.Context, command string, opts *api.ExecOptions, rows, cols uint16, ...) (int, error)
- func (s *Sandbox) ID() string
- func (s *Sandbox) ListFiles(ctx context.Context, path string) ([]api.FileInfo, error)
- func (s *Sandbox) Machine() vm.Machine
- func (s *Sandbox) Policy() *policy.Engine
- func (s *Sandbox) PrepareExecEnv() *api.ExecOptions
- func (s *Sandbox) ReadFile(ctx context.Context, path string) ([]byte, error)
- func (s *Sandbox) ReadFileTo(ctx context.Context, path string, w io.Writer) (int64, error)
- func (s *Sandbox) RemoveAllowedHosts(ctx context.Context, hosts []string) ([]string, error)
- func (s *Sandbox) Start(ctx context.Context) error
- func (s *Sandbox) StartPortForwards(ctx context.Context, addresses []string, forwards []api.PortForward) (*PortForwardManager, error)
- func (s *Sandbox) Stop(ctx context.Context) error
- func (s *Sandbox) Workspace() string
- func (s *Sandbox) WriteFile(ctx context.Context, path string, content []byte, mode uint32) error
Constants ¶
This section is empty.
Variables ¶
var ( // Exec relay errors ErrRelayConnect = errors.New("connect to exec relay") ErrRelaySend = errors.New("send exec request") ErrRelayRead = errors.New("read exec result") ErrRelayUnexpected = errors.New("unexpected message type") ErrRelayDecode = errors.New("decode exec result") ErrRelayListen = errors.New("listen on relay socket") ErrRelayProxy = errors.New("relay port-forward proxy") // Rootfs errors ErrGuestAgent = errors.New("guest-agent not found") ErrGuestFused = errors.New("guest-fused not found") ErrGuestInit = errors.New("guest-init not found") ErrResizeRootfs = errors.New("resize rootfs") ErrCreateRootfs = errors.New("create rootfs image") ErrCreateTemp = errors.New("create temp file") ErrWriteTemp = errors.New("write temp file") ErrDebugfs = errors.New("debugfs") ErrStatRootfs = errors.New("stat rootfs") ErrTruncate = errors.New("truncate rootfs") ErrResize2fs = errors.New("resize2fs") // Sandbox lifecycle errors (shared between darwin and linux) ErrRegisterState = errors.New("register VM state") ErrAllocateSubnet = errors.New("allocate subnet") ErrCreateCAPool = errors.New("create CA pool") ErrCopyRootfs = errors.New("copy rootfs") ErrPrepareRootfs = errors.New("prepare rootfs") ErrPrepareBootstrapRoot = errors.New("prepare bootstrap rootfs") ErrInjectCACert = errors.New("inject CA cert into rootfs") ErrInvalidDiskCfg = errors.New("invalid extra disk config") ErrCreateVM = errors.New("create VM") ErrCreateProxy = errors.New("create transparent proxy") ErrFirewallSetup = errors.New("setup firewall rules") ErrNetworkStack = errors.New("create network stack") ErrVFSListener = errors.New("setup VFS listener") ErrVFSServer = errors.New("start VFS server") ErrMachineClose = errors.New("machine close") ErrPrepareOverlayMount = errors.New("prepare overlay mount snapshot") ErrCopyOverlaySource = errors.New("copy overlay mount source") ErrRemoveOverlaySnapshot = errors.New("remove overlay mount snapshot") ErrOverlayLayerLimit = errors.New("overlay layer limit exceeded") ErrOverlayDiskLimit = errors.New("overlay disk device limit exceeded") ErrFirewallCleanup = errors.New("firewall cleanup") ErrNATCleanup = errors.New("NAT cleanup") ErrNetworkFile = errors.New("get network file") ErrReleaseSubnet = errors.New("release subnet") ErrUnregisterState = errors.New("unregister VM state") ErrRemoveRootfs = errors.New("remove rootfs copy") ErrProxyClose = errors.New("proxy close") ErrLifecycleInit = errors.New("initialize lifecycle record") ErrLifecycleUpdate = errors.New("update lifecycle record") ErrPortForwardDial = errors.New("dial guest port-forward service") ErrPortForwardInit = errors.New("initialize guest port-forward") ErrPortForwardBind = errors.New("bind local port-forward listener") ErrPortForwardCopy = errors.New("proxy port-forward stream") ErrNoVsockDialer = errors.New("vm backend does not support vsock dial") ErrVFSDisabled = errors.New("vfs is disabled") ErrAllowListHosts = errors.New("invalid allow-list hosts") ErrInteractiveUnsupported = errors.New("interactive exec unsupported") )
Sentinel errors for the sandbox package.
Functions ¶
func DefaultGuestAgentPath ¶
func DefaultGuestAgentPath() string
DefaultGuestAgentPath returns the default path to guest-agent binary.
func DefaultGuestFusedPath ¶
func DefaultGuestFusedPath() string
DefaultGuestFusedPath returns the default path to guest-fused binary.
func DefaultGuestInitPath ¶ added in v0.1.20
func DefaultGuestInitPath() string
DefaultGuestInitPath returns the default path to guest-init binary.
func DefaultInitramfsPath ¶
func DefaultInitramfsPath() string
DefaultInitramfsPath returns the default path to the initramfs image (optional, mainly for macOS).
func DefaultKernelPath ¶
func DefaultKernelPath() string
DefaultKernelPath returns the path to the kernel image, downloading if needed. It checks in order: MATCHLOCK_KERNEL env, legacy paths, then downloads from OCI.
func DefaultKernelPathWithVersion ¶
DefaultKernelPathWithVersion returns the path to a specific kernel version.
func ExecInteractiveViaRelay ¶
func ExecInteractiveViaRelay(ctx context.Context, socketPath, command, workingDir, user string, rows, cols uint16, stdin io.Reader, stdout io.Writer) (int, error)
ExecInteractiveViaRelay connects to an exec relay socket and runs an interactive command.
func ExecPipeViaRelay ¶ added in v0.1.12
func ExecPipeViaRelay(ctx context.Context, socketPath, command, workingDir, user string, stdin io.Reader, stdout, stderr io.Writer) (int, error)
ExecPipeViaRelay connects to an exec relay socket and runs a command with bidirectional stdin/stdout/stderr piping (no PTY).
func ExecViaRelay ¶
func ExecViaRelay(ctx context.Context, socketPath, command, workingDir, user string) (*api.ExecResult, error)
ExecViaRelay connects to an exec relay socket and runs a command. The context controls the lifetime — if cancelled, the connection is closed.
Types ¶
type AllowListUpdateResult ¶ added in v0.1.24
func AllowListAddViaRelay ¶ added in v0.1.24
func AllowListDeleteViaRelay ¶ added in v0.1.24
type ExecRelay ¶
type ExecRelay struct {
// contains filtered or unexported fields
}
ExecRelay serves exec requests from external processes via a Unix socket. This allows `matchlock exec` to run commands in a VM owned by another process.
func NewExecRelay ¶
type FirewallRules ¶
FirewallRules is an interface for managing firewall rules.
type Options ¶
type Options struct {
// KernelPath overrides the default kernel path
KernelPath string
// RootfsPaths are immutable lower image paths in base->top order (required).
RootfsPaths []string
// RootfsFSTypes optionally declares filesystem type per lower image.
RootfsFSTypes []string
}
Options configures sandbox creation.
type PortForwardManager ¶ added in v0.1.20
type PortForwardManager struct {
// contains filtered or unexported fields
}
PortForwardManager manages host listeners that proxy traffic into a sandbox.
func (*PortForwardManager) Bindings ¶ added in v0.1.20
func (m *PortForwardManager) Bindings() []api.PortForwardBinding
Bindings returns the active listener bindings.
func (*PortForwardManager) Close ¶ added in v0.1.20
func (m *PortForwardManager) Close() error
Close stops all listeners and waits for active proxy loops to exit.
type Sandbox ¶
type Sandbox struct {
// contains filtered or unexported fields
}
Sandbox represents a running sandbox VM with all associated resources.
func (*Sandbox) AddAllowedHosts ¶ added in v0.1.24
func (*Sandbox) AllowedHosts ¶ added in v0.1.24
func (*Sandbox) CAPool ¶ added in v0.1.1
func (s *Sandbox) CAPool() *sandboxnet.CAPool
func (*Sandbox) Exec ¶
func (s *Sandbox) Exec(ctx context.Context, command string, opts *api.ExecOptions) (*api.ExecResult, error)
func (*Sandbox) ExecInteractive ¶ added in v0.1.26
func (*Sandbox) PrepareExecEnv ¶ added in v0.1.1
func (s *Sandbox) PrepareExecEnv() *api.ExecOptions
func (*Sandbox) ReadFileTo ¶ added in v0.1.4
func (*Sandbox) RemoveAllowedHosts ¶ added in v0.1.24
func (*Sandbox) StartPortForwards ¶ added in v0.1.20
func (s *Sandbox) StartPortForwards(ctx context.Context, addresses []string, forwards []api.PortForward) (*PortForwardManager, error)
StartPortForwards starts local listeners and proxies connections to the guest.