rootfs

Documentation

Overview

Package rootfs converts a verified local OCI image layout into a safe, deterministic filesystem tree without invoking external tools.

Index

• Constants
• func InstallGuestTransportConfig(dir string, sessionKey []byte) error
• func InstallInit(dir, initBinary string, entrypoint []string) error
• func InstallProcessConfig(dir string, config ProcessConfig) error
• func WriteInitramfs(dir string, w io.Writer) error
• type GuestTransportConfig
• type Options
• type ProcessConfig
• type ProcessRlimit
• type Result
  • func Convert(opts Options) (result Result, err error)

Constants

const (
	GuestTransportConfigPath = "/etc/platform-factory/guest-transport.json"
	GuestSessionKeyPath      = "/etc/platform-factory/guest-session.key"
)

Functions

func InstallGuestTransportConfig

func InstallGuestTransportConfig(dir string, sessionKey []byte) error

InstallGuestTransportConfig provisions one per-boot authenticated COM2 endpoint. The key is deliberately written mode 0600 and is never included in the non-secret JSON metadata.

func InstallInit

func InstallInit(dir, initBinary string, entrypoint []string) error

InstallInit writes a project-owned PID 1 binary, and optionally a fixed entrypoint argv, into dir, a directory previously produced by Convert. It is deliberately separate from Convert: the init binary and entrypoint override are trusted, project-controlled inputs, never part of the untrusted OCI image content Convert extracts and verifies.

Unlike Convert, InstallInit is not atomic across its two writes: if the entrypoint argv fails validation, the init binary has already been written into dir. Callers that need all-or-nothing semantics must stage dir themselves (as the microvm-initramfs command does, by running Convert and InstallInit against a temporary directory before packing and installing the result).

func InstallProcessConfig

func InstallProcessConfig(dir string, config ProcessConfig) error

InstallProcessConfig writes the fuller OCI process contract used by the runtime facade. InstallInit's entrypoint.json remains supported for bundles that only need argv.

func WriteInitramfs

func WriteInitramfs(dir string, w io.Writer) error

WriteInitramfs packs dir, a directory tree already produced by Convert (plus, typically, InstallInit), into a deterministic gzip-compressed cpio "newc" archive suitable as a Linux kernel initramfs. It does not re-validate paths or link targets: it trusts dir to already be the output of Convert/InstallInit, exactly as digestTree does.

Inode numbers are synthesized sequentially in sorted-path order rather than read from the filesystem, and every entry's mtime is pinned to the Unix epoch, so byte-identical input directories always produce byte-identical archives regardless of host inode numbers or wall-clock time. Hardlink relationships from the source OCI layers are not preserved in the packed archive - each linked path is written as an independent regular file with its own full content - because only path and content (not inode identity) are observable to a kernel booting from this initramfs.

Types

type GuestTransportConfig

type GuestTransportConfig struct {
	Device         string `json:"device"`
	SessionKeyPath string `json:"session_key_path"`
}

type Options

type Options struct {
	Layout    string
	Output    string
	Platform  string
	Reference string
	// MaxBytes limits total uncompressed layer bytes, including tar
	// metadata and padding. MaxFiles limits archive entries (not merely
	// regular files), preventing directory/whiteout header bombs.
	MaxBytes     int64
	MaxFiles     int
	MaxFileBytes int64
}

type ProcessConfig

type ProcessConfig struct {
	Args    []string        `json:"args"`
	Env     []string        `json:"env,omitempty"`
	Cwd     string          `json:"cwd,omitempty"`
	UID     uint32          `json:"uid,omitempty"`
	GID     uint32          `json:"gid,omitempty"`
	Groups  []uint32        `json:"additional_gids,omitempty"`
	Umask   *uint32         `json:"umask,omitempty"`
	Rlimits []ProcessRlimit `json:"rlimits,omitempty"`
}

type ProcessRlimit

type ProcessRlimit struct {
	Type string `json:"type"`
	Hard uint64 `json:"hard"`
	Soft uint64 `json:"soft"`
}

type Result

type Result struct {
	ManifestDigest string `json:"manifest_digest"`
	RootFSDigest   string `json:"rootfs_digest"`
	Files          int    `json:"files"`
	Bytes          int64  `json:"bytes"`
}

func Convert

func Convert(opts Options) (result Result, err error)

Convert verifies the selected manifest, config, compressed layer digests and uncompressed diff IDs while streaming layers into a temporary directory. Output is installed atomically only after every check succeeds.