libkrun provides guest initialization through the init/ subsystem. In a standard container/microVM workload, the guest init runs as PID 1, mounts runtime filesystems, configures networking and environment variables, and launches the target process.
Note:
krun-init(paired withlibkrunfw) is designed for lightweight container workloads (e.g.crun'skrunruntime). It is not used when booting full VM images with EFI firmware (such as Podman machine on macOS viakrunkit) or when booting an external kernel with its own rootfs/initramfs.
init/init-binary: Guest PID 1 binary compiled statically for the target guest OS/arch.init/init-blob: Host-side configuration builder (Config), OCI spec ingestion. This embeds init binary.init/aws-nitro: Standalone enclave init implementation for AWS Nitro Enclaves (AWS_NITRO=1).
init-binary is the binary executed by the guest kernel at boot. It is statically compiled for the guest target (e.g. x86_64-unknown-linux-musl, aarch64-unknown-linux-musl, or x86_64-unknown-freebsd).
At startup, init-binary:
- Ensures standard I/O descriptors (stdin, stdout, stderr) are open.
- Mounts essential pseudofilesystems (
/proc,/sys,/dev,/dev/pts,/dev/shm,/sys/fs/cgroup). - If root disk remount is requested (
KRUN_BLOCK_ROOT_DEVICEor TEE block storage), mounts the block device and pivots root. - Reads the configuration file (
/.krun_config.json) exposed by the virtio-fs overlay. - Sets up guest networking (DHCP or TSI dummy interface).
- Applies environment variables, hostname, resource limits (
rlimit), and changes working directory. - Rewires stdio to configured virtio-console ports (
krun-stdin,krun-stdout,krun-stderr). - Spawns and supervises the workload (capturing its exit code to notify the VMM via virtiofs ioctl and shutting down the VM), or directly execs as PID 1 if
KRUN_INIT_PID1=1.
init-blob is the host-side manager and configuration builder:
- Host Payload Ownership: The host
init-blobcrate owns the embedded guest binary data and the serialized configuration buffer (Config). - Filesystem Overlay Injection (
Config::apply): Whenconfig.apply(&mut overlay, &mut payload)is invoked, it writes the embedded init binary (at/init.krun) and the configuration file (/.krun_config.json) as in-memory files intoFsOverlay(the virtio-fs overlay), and appendsinit=/init.krunto the kernel command line inPayload. - Lifetime Requirement: Because
applypasses borrowed memory pointers intoFsOverlaythat are read when the guest boots and executes/init.krun, the RustConfig(or CKrunInitConfighandle) must remain allocated for the entire lifetime of the VM. - OCI Spec Ingestion: Provides
Builder::from_oci_json()to convert standard containerconfig.jsonspecifications into guest initialization structures. - FFI Bridge: Exports the
libkrun_initC ABI using ffier (ffier::library_definition!("krun_init", ...)).
The optional Unix control channel lets a container runtime start another process in
the guest or signal the main workload. Set Builder::control_socket(path) on
the init configuration, then call Config::apply_with_vsock(overlay, payload, vsock) with the VM's VsockDevice. The call maps the configured host Unix
socket to the guest init's vsock port. Config::apply returns an error when a
control socket was configured without a vsock device. Keep the Config alive
for the VM's lifetime, as with other overlay files. The channel is unavailable
when KRUN_INIT_PID1=1, because that mode replaces init with the workload.
Windows builds do not expose the control channel API.
On the host, Controller::open(path, timeout_ms) waits for guest init to answer
on that socket. Controller::exec_pipes starts a process with duplicated stdio
descriptors; pass None for stdin to give the process immediate EOF.
Controller::exec_tty starts it with a pseudo-terminal. Call Process::wait
to relay stdio and receive the exit code. A signal self-pipe passed to wait
forwards signals and terminal size changes. Controller::signal_entrypoint
signals the main workload, including the SIGTERM used by a container stop
request. Each operation uses a separate connection.
Place the host socket in a private directory and restrict access to that directory. Any local process that can connect to the socket can request an exec in the guest; the default identity is guest root unless the request sets another UID and GID. The guest accepts the host vsock CID for this channel, and the VMM's TSI guard prevents guest-initiated connections to the mapped host listening socket. See Security Model.
The current relay writes guest output synchronously to the caller's stdout or stderr descriptor. If that consumer stops draining output, the relay also stops reading the control socket. Signal forwarding, including Ctrl-C, resumes when the consumer drains output. If the consumer closes the descriptor, the relay ends and the guest process receives SIGHUP.
When terminal input reaches EOF, queued terminal input is discarded and the guest process receives SIGHUP. Pipe input is drained before EOF.
When krun-init-blob is consumed as a standalone shared library (libkrun_init.so) or built with feature = "ffi":
- It interacts with
libkrunwithout compile-time linkage by using foreign handle types (FsOverlay,Payload) fromlibkrun-via-libc. - In
Config::apply,init-blobdynamically resolves requiredlibkrunfunctions (such askrun_fs_overlay_add_fileandkrun_payload_append_cmdline) from the process's global symbol table by default usinglibkrun_via_libc::ffi::require(). - When built with
feature = "krun"(the default, e.g. in-tree static Rust builds),init-bloblinks directly againstkrun::FsOverlayandkrun::Payloadtypes without dynamic symbol lookups.
The krun and ffi backends are mutually exclusive; shared-library builds use --no-default-features to disable krun.
Provides a Rust client for libkrun_init.so, generated at build time from bindings/init-blob-via-cdylib/ffier-krun_init.json using ffier-gen-rust-client. With ffier-strong, the library must be available at link time and runtime; ffier-dynlookup resolves its symbols at runtime.
Important:
init/aws-nitrois an entirely separate, standalone init implementation. It is unrelated to theinit-binary/init-blobarchitecture described above.