initx

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Feb 10, 2026 License: GPL-3.0 Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	VsockProgramPort = 9998
	VsockStdinPort   = 9999 // Separate port for streaming stdin

	// Capture flags for stdout/stderr capture and stdin delivery
	CaptureFlagNone    uint32 = 0x00
	CaptureFlagStdout  uint32 = 0x01
	CaptureFlagStderr  uint32 = 0x02
	CaptureFlagCombine uint32 = 0x04 // Combine stdout+stderr into single stream
	CaptureFlagStdin   uint32 = 0x08 // Stdin data is included in the message (buffered mode)

	// Stdin mode constants for streaming stdin protocol
	// These replace stdin_len field in the protocol when stdin_mode >= 0x02
	StdinModeNone      uint32 = 0x00 // No stdin (EOF immediately)
	StdinModeBuffered  uint32 = 0x01 // Buffered stdin (legacy - stdin_len and data follow code)
	StdinModeStreaming uint32 = 0x02 // Streaming stdin (separate vsock connection on port 9999)
)

VsockProgramServer handles program loading via vsock. Protocol:

  • Host → Guest: [len:4][time_sec:8][time_nsec:8][flags:4][code_len:4][reloc_count:4][relocs:4*count][code:code_len]
  • Guest → Host: [len:4][exit_code:4][stdout_len:4][stdout_data][stderr_len:4][stderr_data]

Note: time_sec and time_nsec come before flags to maintain 8-byte alignment for ARM64. When flags=0, guest response is just [len:4][exit_code:4] for backward compatibility.

Variables

View Source 
var ErrVMTerminated = errors.New("virtual machine terminated")

ErrVMTerminated is returned when a vsock operation fails because the virtual machine has terminated unexpectedly.

Functions

func AddDefaultRoute 

func AddDefaultRoute(ifName string, gateway uint32, errLabel ir.Label, errVar ir.Var) ir.Fragment

func AddKernelModulesToVFS added in v0.0.2 

func AddKernelModulesToVFS(fsBackend vfs.VirtioFsBackend, kernelLoader kernel.Kernel) error

AddKernelModulesToVFS adds kernel module files to the VFS backend for modprobe support. This function should be called after creating the VFS backend and loading the kernel, before creating the VirtualMachine.

func Build 

func Build(cfg BuilderConfig) (*ir.Program, error)

Build builds the init program using the RTG compiler. This is the main entry point for building init programs.

func BuildContainerInitProgram 

func BuildContainerInitProgram(cfg ContainerInitConfig) (*ir.Program, error)

BuildContainerInitProgram builds the container init program using RTG source code. The source code is embedded from container_init_source.go which is a valid Go file for IDE completion support. Most helpers are pure RTG, with complex ones injected at IR level.

func BuildFromRTG 

func BuildFromRTG(cfg BuilderConfig) (*ir.Program, error)

BuildFromRTG builds the init program from RTG source code. The source code is embedded from init_source.go which is a valid Go file for IDE completion support.

func Chroot 

func Chroot(path string, errLabel ir.Label, errVar ir.Var) ir.Fragment

func ClearRunResults 

func ClearRunResults(mailbox ir.Var) ir.Fragment

ClearRunResults zeros the run/start result slots so the host observes a clean state once the payload completes.

func ConfigureInterface 

func ConfigureInterface(ifName string, ip uint32, mask uint32, errLabel ir.Label, errVar ir.Var) ir.Fragment

func ConfigureLoopback 

func ConfigureLoopback(errLabel ir.Label, errVar ir.Var) ir.Fragment

ConfigureLoopback brings up the loopback interface (lo) with IP 127.0.0.1. This is needed for localhost networking (e.g., tests that use TCP on localhost).

func CreateFileFromStdin 

func CreateFileFromStdin(path string, length int64, mode uint32, errLabel ir.Label, errVar ir.Var) ir.Fragment

CreateFileFromStdin reads length bytes from stdin and writes them into path.

func Exec 

func Exec(path string, argv []string, envp []string, errLabel ir.Label, errVar ir.Var) ir.Fragment

Exec performs an execve syscall, replacing the current process with the specified program. This is used by ForkExecWait for the child process after fork.

func ExecOnly added in v0.0.2 

func ExecOnly(path string, argv []string, envp []string, errLabel ir.Label, errVar ir.Var) ir.Fragment

ExecOnly performs an execve syscall directly without forking. This is used for "exec mode" where the command replaces init as PID 1. Unlike ForkExecWait, there is no parent process waiting for the child.

func ForkExecWait 

func ForkExecWait(path string, argv []string, envp []string, forkErrLabel ir.Label, execErrLabel ir.Label, errVar ir.Var) ir.Fragment

func ForkExecWaitWithCwd added in v0.0.2 

func ForkExecWaitWithCwd(path string, argv []string, envp []string, cwd string, forkErrLabel ir.Label, execErrLabel ir.Label, errVar ir.Var) ir.Fragment

ForkExecWaitWithCwd is like ForkExecWait but changes to the specified working directory before executing the program. If cwd is empty, no chdir is performed.

func GetInterfaceIndex 

func GetInterfaceIndex(ifName string, errLabel ir.Label, errVar ir.Var) ir.Fragment

GetInterfaceIndex gets the interface index for a given interface name using SIOCGIFINDEX. Returns the ifindex in errVar on success, negative errno on failure.

func LogKmsg 

func LogKmsg(msg string) ir.Block

func Mkdir 

func Mkdir(path string, mode uint32, errLabel ir.Label, errVar ir.Var) ir.Fragment

func Mount 

func Mount(
	source, target, fstype string,
	flags uintptr,
	data string,
	errLabel ir.Label,
	errVar ir.Var,
) ir.Fragment

func MountBinfmtMisc added in v0.0.2 

func MountBinfmtMisc(errLabel ir.Label, errVar ir.Var) ir.Fragment

MountBinfmtMisc mounts the binfmt_misc filesystem at /proc/sys/fs/binfmt_misc.

func NeedsQEMUEmulation added in v0.0.2 

func NeedsQEMUEmulation(hostArch, imageArch hv.CpuArchitecture) bool

NeedsQEMUEmulation returns true if the image architecture differs from the host architecture and QEMU emulation is supported for that combination.

func RegisterBinfmt added in v0.0.2 

func RegisterBinfmt(registrationString string, errLabel ir.Label, errVar ir.Var) ir.Fragment

RegisterBinfmt writes a binfmt-misc registration string to /proc/sys/fs/binfmt_misc/register.

func ReportRunResult 

func ReportRunResult(stage any, detail any) ir.Fragment

ReportRunResult stores the provided detail/stage pair into the mailbox so the host can decode the error reason.

func RequestSnapshot 

func RequestSnapshot() ir.Fragment

RequestSnapshot asks the host to capture a snapshot by writing the dedicated doorbell value to the mailbox.

func SendProfilingEvent 

func SendProfilingEvent(basePtr ir.Var, name string) ir.Fragment

func SetClock 

func SetClock(sec int64, nsec int64, errLabel ir.Label, errVar ir.Var) ir.Fragment

func SetHostname 

func SetHostname(name string, errLabel ir.Label, errVar ir.Var) ir.Fragment

func SetHosts 

func SetHosts(hostname string, errLabel ir.Label, errVar ir.Var) ir.Fragment

SetHosts sets up /etc/hosts with localhost entries.

func SetHostsOptional 

func SetHostsOptional(hostname string) ir.Fragment

SetHostsOptional is like SetHosts but doesn't fail if the file can't be written.

func SetResolvConf 

func SetResolvConf(dnsServer string, errLabel ir.Label, errVar ir.Var) ir.Fragment

func SetupProfiling 

func SetupProfiling(basePtr ir.Var, errLabel ir.Label, errVar ir.Var) ir.Fragment

func SyncClockFromPTP 

func SyncClockFromPTP(ptpPath string, errLabel ir.Label, errVar ir.Var) ir.Fragment

func WriteBinaryFile added in v0.0.2 

func WriteBinaryFile(path string, data []byte, mode int64, errLabel ir.Label, errVar ir.Var) ir.Fragment

WriteBinaryFile writes binary data to a file in the guest filesystem. This is used to install QEMU static binaries.

Types

type BuilderConfig 

type BuilderConfig struct {
	Arch hv.CpuArchitecture

	PreloadModules []kernel.Module

	// TimesliceMMIOPhysAddr is the physical address of the timeslice MMIO region.
	// Guest code can write to this address to record timeslice markers.
	// If 0, uses the default value 0xf0001000.
	TimesliceMMIOPhysAddr uint64

	// VsockPort is the vsock port to use for program loading.
	// If 0, uses the default port (9998).
	VsockPort uint32
}

type ContainerInitConfig 

type ContainerInitConfig struct {
	Arch           hv.CpuArchitecture
	Cmd            []string
	Env            []string
	WorkDir        string
	EnableNetwork  bool
	Exec           bool
	SkipEntrypoint bool // If true, don't run Cmd - just initialize and wait for commands via vsock

	Hostname    string // default: tinyrange
	DNS         string // default: 10.42.0.1
	GuestIP     string // default: 10.42.0.2
	GuestMask   string // default: 255.255.255.0
	GuestIFName string // default: eth0

	// UID and GID for privilege dropping (nil = stay as root)
	UID *int
	GID *int

	// QEMUEmulation enables cross-architecture binary emulation.
	// If set, QEMU static binaries will be installed and binfmt-misc configured.
	QEMUEmulation *QEMUEmulationConfig

	// TimesliceMMIOPhysAddr is the physical address of the timeslice MMIO region.
	// If 0, uses default value 0xf0001000.
	TimesliceMMIOPhysAddr uint64
}

type ExitError 

type ExitError struct {
	Code int
}

ExitError represents a non-zero exit code returned from an initx payload.

func (*ExitError) Error 

func (e *ExitError) Error() string

Error implements the error interface.

type KernelLoader 

type KernelLoader interface {
	// GetKernel returns a reader for the kernel image, its size, and an error if any.
	GetKernel() (io.ReaderAt, int64, error)
}

type Module 

type Module struct {
	Name string
	Data []byte
}

type Option 

type Option interface {
	// contains filtered or unexported methods
}

func WithConsoleOutput 

func WithConsoleOutput(w io.Writer) Option

WithConsoleOutput redirects the VM console output (virtio-console) to w. If nil, the default (stderr) is used.

func WithDebugLogging 

func WithDebugLogging(enabled bool) Option

func WithDeviceTemplate 

func WithDeviceTemplate(dev hv.DeviceTemplate) Option

func WithDmesgLogging 

func WithDmesgLogging(enabled bool) Option

func WithFileFromBytes 

func WithFileFromBytes(guestPath string, data []byte, mode os.FileMode) Option

func WithGPUEnabled 

func WithGPUEnabled(enabled bool) Option

func WithQEMUEmulationEnabled added in v0.0.2 

func WithQEMUEmulationEnabled(enabled bool) Option

func WithSnapshot added in v0.0.2 

func WithSnapshot(snap hv.Snapshot) Option

WithSnapshot configures the VM to restore from the given snapshot after creation. This skips kernel loading since the snapshot contains the full VM state. The snapshot will be restored automatically after VM creation.

func WithStdin 

func WithStdin(r io.Reader) Option

func WithVsockProgramLoader added in v0.0.2 

func WithVsockProgramLoader(backend virtio.VsockBackend, port uint32) Option

WithVsockProgramLoader configures the VM to use vsock for program loading. The vsock backend must already have a vsock device added to the VM. This option should be used together with a vsock device template.

type ProgramResult added in v0.0.2 

type ProgramResult struct {
	ExitCode int32
	Stdout   []byte
	Stderr   []byte
}

ProgramResult contains the result of a program execution including captured output.

type QEMUEmulationConfig added in v0.0.2 

type QEMUEmulationConfig struct {
	// TargetArch is the architecture we're emulating (the container's architecture).
	TargetArch hv.CpuArchitecture

	// Binary is the QEMU static binary data.
	Binary []byte

	// BinaryPath is where to install the binary in the guest.
	BinaryPath string

	// BinfmtRegistration is the string to write to /proc/sys/fs/binfmt_misc/register.
	BinfmtRegistration string
}

QEMUEmulationConfig configures QEMU user emulation for cross-architecture support.

func PrepareQEMUEmulation added in v0.0.2 

func PrepareQEMUEmulation(hostArch, targetArch hv.CpuArchitecture, cacheDir string) (*QEMUEmulationConfig, error)

PrepareQEMUEmulation downloads the QEMU static binary and prepares the configuration for cross-architecture emulation.

hostArch is the architecture of the host (the VM kernel's architecture). targetArch is the architecture of the container binaries to emulate. cacheDir is the directory to cache downloaded packages.

type Session 

type Session struct {
	VM   *VirtualMachine
	Done <-chan error

	// Stop cancels the session and waits up to timeout for completion.
	Stop func(timeout time.Duration) error
	// Wait blocks until the session completes and returns the terminal error.
	Wait func() error
}

Session is a small orchestration handle for booting a VM and running a payload. It is intentionally UI-agnostic; callers own any window/terminal resources.

func StartSession 

func StartSession(parent context.Context, vm *VirtualMachine, prog *ir.Program, cfg SessionConfig) *Session

StartSession boots vm and then runs prog until completion or cancellation. It returns immediately with a handle; the boot+run work happens in a goroutine.

type SessionConfig 

type SessionConfig struct {
	// BootTimeout controls how long we wait for the initial boot program to run.
	// If zero, a default of 10 seconds is used.
	BootTimeout time.Duration

	// SkipBoot skips the boot phase. Use this when restoring from a snapshot.
	SkipBoot bool

	// OnBootComplete is called after boot completes successfully but before
	// the payload runs. Use this to capture a snapshot after boot.
	OnBootComplete func() error
}

type SnapshotCache 

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

SnapshotCache manages boot snapshots in a cache directory.

func NewSnapshotCache 

func NewSnapshotCache(cacheDir string, io SnapshotIO) *SnapshotCache

NewSnapshotCache creates a cache manager for the given directory.

func (*SnapshotCache) EnsureDir 

func (c *SnapshotCache) EnsureDir() error

EnsureDir creates the cache directory if it doesn't exist.

func (*SnapshotCache) GetSnapshotPath 

func (c *SnapshotCache) GetSnapshotPath(configHash hv.VMConfigHash) string

GetSnapshotPath returns the path to the snapshot file for a given config hash.

func (*SnapshotCache) HasValidSnapshot 

func (c *SnapshotCache) HasValidSnapshot(configHash hv.VMConfigHash, referenceTime time.Time) bool

HasValidSnapshot checks if a valid snapshot exists. Returns true if snapshot exists and is newer than referenceTime (typically kernel mod time).

func (*SnapshotCache) InvalidateAll 

func (c *SnapshotCache) InvalidateAll() error

InvalidateAll removes all cached snapshots.

func (*SnapshotCache) InvalidateCache 

func (c *SnapshotCache) InvalidateCache(configHash hv.VMConfigHash) error

InvalidateCache removes the cached snapshot for a config hash.

func (*SnapshotCache) LoadSnapshot 

func (c *SnapshotCache) LoadSnapshot(configHash hv.VMConfigHash) (hv.Snapshot, error)

LoadSnapshot loads a snapshot from the cache.

func (*SnapshotCache) SaveSnapshot 

func (c *SnapshotCache) SaveSnapshot(configHash hv.VMConfigHash, snap hv.Snapshot) error

SaveSnapshot saves a snapshot to the cache.

type SnapshotIO 

type SnapshotIO interface {
	SaveSnapshot(path string, snap hv.Snapshot) error
	LoadSnapshot(path string) (hv.Snapshot, error)
}

SnapshotIO provides platform-specific snapshot serialization. This interface allows the cache to work with different hypervisor backends.

func GetSnapshotIO 

func GetSnapshotIO() SnapshotIO

GetSnapshotIO returns the platform-specific snapshot IO implementation.

type VirtualMachine 

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

func NewVirtualMachine 

func NewVirtualMachine(
	h hv.Hypervisor,
	numCPUs int,
	memSizeMB uint64,
	kernelLoader kernel.Kernel,
	options ...Option,
) (*VirtualMachine, error)

func (*VirtualMachine) Architecture 

func (vm *VirtualMachine) Architecture() hv.CpuArchitecture

func (*VirtualMachine) Boot 

func (vm *VirtualMachine) Boot(ctx context.Context) error

Boot runs a minimal program to ensure the initx loop is running and devices are ready. This should be called before running the real payload program.

func (*VirtualMachine) CaptureSnapshot 

func (vm *VirtualMachine) CaptureSnapshot() (hv.Snapshot, error)

CaptureSnapshot captures a snapshot of the VM state.

func (*VirtualMachine) Close 

func (vm *VirtualMachine) Close() error

func (*VirtualMachine) DumpStackTrace 

func (vm *VirtualMachine) DumpStackTrace(vcpu hv.VirtualCPU) (int64, error)

func (*VirtualMachine) GPU 

func (vm *VirtualMachine) GPU() *virtio.GPU

GPU returns the virtio-gpu device if GPU is enabled, nil otherwise.

func (*VirtualMachine) HVVirtualMachine 

func (vm *VirtualMachine) HVVirtualMachine() hv.VirtualMachine

HVVirtualMachine returns the underlying hv.VirtualMachine for low-level operations.

func (*VirtualMachine) Keyboard 

func (vm *VirtualMachine) Keyboard() *virtio.Input

Keyboard returns the virtio-input keyboard device if GPU is enabled, nil otherwise.

func (*VirtualMachine) RestoreSnapshot 

func (vm *VirtualMachine) RestoreSnapshot(snap hv.Snapshot) error

RestoreSnapshot restores a VM from a snapshot.

func (*VirtualMachine) Run 

func (vm *VirtualMachine) Run(ctx context.Context, prog *ir.Program) error

func (*VirtualMachine) RunWithCapture added in v0.0.2 

func (vm *VirtualMachine) RunWithCapture(ctx context.Context, prog *ir.Program, flags uint32) (*ProgramResult, error)

RunWithCapture runs a program and captures stdout/stderr based on the flags. Returns a ProgramResult containing the exit code and captured output.

func (*VirtualMachine) RunWithCaptureAndStdin added in v0.0.2 

func (vm *VirtualMachine) RunWithCaptureAndStdin(ctx context.Context, prog *ir.Program, flags uint32, stdin []byte) (*ProgramResult, error)

RunWithCaptureAndStdin runs a program with optional stdin data and captures stdout/stderr. Returns a ProgramResult containing the exit code and captured output.

func (*VirtualMachine) RunWithStreamingStdin added in v0.0.2 

func (vm *VirtualMachine) RunWithStreamingStdin(ctx context.Context, prog *ir.Program, flags uint32, stdin io.Reader) (*ProgramResult, error)

RunWithStreamingStdin runs a program with streaming stdin from an io.Reader. This enables terminal-like stdin without blocking, and supports large stdin without memory overhead. Returns a ProgramResult containing the exit code and captured output.

func (*VirtualMachine) SetConsoleSize 

func (vm *VirtualMachine) SetConsoleSize(cols, rows int)

SetConsoleSize updates the virtio-console configuration so the guest can see the correct terminal size. This is best-effort (no-op if console is unavailable).

func (*VirtualMachine) Spawn 

func (vm *VirtualMachine) Spawn(ctx context.Context, path string, args ...string) error

Spawn executes path inside the guest using fork/exec, waiting for it to complete.

func (*VirtualMachine) StartStdinForwarding 

func (vm *VirtualMachine) StartStdinForwarding()

StartStdinForwarding activates stdin forwarding to the guest console. This should be called after the VM has booted and before the user command runs, to ensure stdin data is delivered to the user command rather than the init process.

func (*VirtualMachine) Tablet 

func (vm *VirtualMachine) Tablet() *virtio.Input

Tablet returns the virtio-input tablet device if GPU is enabled, nil otherwise.

func (*VirtualMachine) TimesliceMMIOPhysAddr added in v0.0.2 

func (vm *VirtualMachine) TimesliceMMIOPhysAddr() uint64

TimesliceMMIOPhysAddr returns the physical address of the timeslice MMIO region.

func (*VirtualMachine) VirtualCPUCall 

func (vm *VirtualMachine) VirtualCPUCall(id int, f func(vcpu hv.VirtualCPU) error) error

type VsockProgramServer added in v0.0.2 

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

VsockProgramServer is the host-side server for vsock-based program loading.

func NewVsockProgramServer added in v0.0.2 

func NewVsockProgramServer(backend virtio.VsockBackend, port uint32, arch hv.CpuArchitecture) (*VsockProgramServer, error)

NewVsockProgramServer creates a new vsock program server listening on the specified port.

func (*VsockProgramServer) Accept added in v0.0.2 

func (s *VsockProgramServer) Accept() error

Accept waits for a guest connection.

func (*VsockProgramServer) Close added in v0.0.2 

func (s *VsockProgramServer) Close() error

Close closes the server and any active connection.

func (*VsockProgramServer) RunWithStreamingStdin added in v0.0.2 

func (s *VsockProgramServer) RunWithStreamingStdin(ctx context.Context, prog *ir.Program, flags uint32, stdin io.Reader) (*ProgramResult, error)

RunWithStreamingStdin sends a program and streams stdin from an io.Reader. This is the main entry point for streaming stdin support. It sends the program with stdin_mode=StdinModeStreaming, then concurrently: - Accepts a stdin connection from the guest on port 9999 - Streams stdin data in chunks until EOF - Waits for the program result

func (*VsockProgramServer) SendProgram added in v0.0.2 

func (s *VsockProgramServer) SendProgram(prog *ir.Program) error

SendProgram sends a compiled program to the guest without capture flags. This is a convenience wrapper around SendProgramWithFlags with flags=0.

func (*VsockProgramServer) SendProgramWithFlags added in v0.0.2 

func (s *VsockProgramServer) SendProgramWithFlags(prog *ir.Program, flags uint32) error

SendProgramWithFlags sends a compiled program to the guest with capture flags. Protocol: [len:4][time_sec:8][time_nsec:8][flags:4][stdin_len:4][code_len:4][reloc_count:4][relocs:4*count][code:code_len][stdin_data] Note: time_sec and time_nsec come first to maintain 8-byte alignment for ARM64.

func (*VsockProgramServer) SendProgramWithFlagsAndStdin added in v0.0.2 

func (s *VsockProgramServer) SendProgramWithFlagsAndStdin(prog *ir.Program, flags uint32, stdin []byte) error

SendProgramWithFlagsAndStdin sends a compiled program to the guest with capture flags and optional stdin data. Protocol: [len:4][time_sec:8][time_nsec:8][flags:4][stdin_len:4][code_len:4][reloc_count:4][relocs:4*count][code:code_len][stdin_data] Note: time_sec and time_nsec come first to maintain 8-byte alignment for ARM64.

func (*VsockProgramServer) SendProgramWithStreamingStdin added in v0.0.2 

func (s *VsockProgramServer) SendProgramWithStreamingStdin(prog *ir.Program, flags uint32, stdinMode uint32) error

SendProgramWithStreamingStdin sends a compiled program to the guest with streaming stdin. Protocol: [len:4][time_sec:8][time_nsec:8][flags:4][stdin_mode:4][code_len:4][reloc_count:4][relocs:4*count][code:code_len] When stdin_mode=StdinModeStreaming, the guest connects back to port 9999 to receive stdin chunks. Note: This method does NOT hold the lock during the entire operation - it acquires/releases as needed.

func (*VsockProgramServer) SetVMTerminatedChannel added in v0.0.2 

func (s *VsockProgramServer) SetVMTerminatedChannel(ch <-chan struct{})

SetVMTerminatedChannel configures the channel that signals VM termination.

func (*VsockProgramServer) WaitResult added in v0.0.2 

func (s *VsockProgramServer) WaitResult(ctx context.Context) (int32, error)

WaitResult waits for and returns the exit code from the guest. This is a convenience wrapper for backward compatibility when capture is not needed.

func (*VsockProgramServer) WaitResultWithCapture added in v0.0.2 

func (s *VsockProgramServer) WaitResultWithCapture(ctx context.Context, flags uint32) (*ProgramResult, error)

WaitResultWithCapture waits for the result from the guest including captured output. Protocol response: [len:4][exit_code:4][stdout_len:4][stdout_data][stderr_len:4][stderr_data] When flags=0, response is just [len:4][exit_code:4].

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.