Documentation
¶
Overview ¶
Package overlayinit implements the logic of flintlock-overlay-init, the init of the initrd that flintlock boots an overlay root volume with.
The init assembles an overlayfs root from a read-only EROFS base device and a writable ext4 device, and then hands over to the init of the image. The interface between flintlockd and the init is the guest contract of docs/proposals/26-09-25-snapshot-restore/0204-overlay-boot-design.md, section 4. In short, for contract version 1:
- The kernel command line carries flintlock.root.contract=1, flintlock.root.base=<device> (the EROFS base) and flintlock.root.rw=<device> (the ext4 writable disk). An optional init= names the init of the image; the default is /sbin/init. The init reads the parameters from /proc/cmdline, because the kernel does not pass keys that contain a dot to the environment of init.
- The init mounts devtmpfs on /dev and proc on /proc, waits up to DeviceTimeout for both devices, mounts the base read-only, mounts the writable disk and creates upper/ and work/ on it, and mounts the overlay. Then it does the switch_root sequence: move /dev and /proc into the overlay, delete the contents of the initramfs, move the overlay to / and chroot. It uses switch_root and not pivot_root, because the initramfs rootfs cannot be unmounted on the 5.10 and 6.1 guest kernels. It checks that the init of the image is an executable file, writes one console line that names the contract version, both devices and their filesystem types, and execs the init of the image.
- On any error the init writes one line with the reason to the console and exits with a non-zero status. The kernel then panics. There is no rescue shell. The contract line is written last, just before the exec, so a failure leaves only the error line on the console. The one exception is an exec that fails after the check of the init, for example because the image lacks its dynamic loader. Then the console holds the contract line and the error line.
The console is standard output. The kernel opens /dev/console as the standard streams of /init before it runs, so the lines reach the serial console of the VMM and the init of the image inherits the same streams.
Every syscall sits behind the System interface, so that the sequence, the parameter parsing and the failure paths are unit tested without a boot.
Index ¶
Constants ¶
const ( // DeviceTimeout is the longest the init waits for the two block devices. DeviceTimeout = 10 * time.Second // DevicePollInterval is the pause between two checks for the block devices. DevicePollInterval = 100 * time.Millisecond // ConsolePrefix starts every line the init writes to the console. ConsolePrefix = "flintlock-overlay-init: " )
const ( // ContractVersion is the only guest contract version this init knows. ContractVersion = "1" // KeyContract is the kernel parameter that carries the contract version. KeyContract = "flintlock.root.contract" // KeyBase is the kernel parameter that names the read-only EROFS base device. KeyBase = "flintlock.root.base" // KeyRW is the kernel parameter that names the writable ext4 device. KeyRW = "flintlock.root.rw" // KeyInit is the kernel parameter that names the init of the image. KeyInit = "init" // DefaultInit is the init of the image when the command line has no init= parameter. DefaultInit = "/sbin/init" // BaseFSType is the filesystem type of the base device under contract version 1. BaseFSType = "erofs" // RWFSType is the filesystem type of the writable device under contract version 1. RWFSType = "ext4" )
Variables ¶
var ( // ErrMissingParam is returned when a required kernel parameter is absent. ErrMissingParam = errors.New("missing kernel parameter") // ErrInvalidParam is returned when a kernel parameter has a value the init cannot use. ErrInvalidParam = errors.New("invalid kernel parameter") // ErrUnknownContract is returned when the contract version is not one the init knows. ErrUnknownContract = errors.New("unknown contract version") // ErrDeviceTimeout is returned when a block device does not appear within DeviceTimeout. ErrDeviceTimeout = errors.New("timed out waiting for block device") // ErrNotBlockDevice is returned when a device path exists but is not a block device. ErrNotBlockDevice = errors.New("not a block device") // ErrInitNotExecutable is returned when the init of the image is missing or is not an executable file. ErrInitNotExecutable = errors.New("image init is not an executable file") )
Functions ¶
Types ¶
type Params ¶
type Params struct {
// Contract is the contract version.
Contract string
// Base is the path of the read-only EROFS base device.
Base string
// RW is the path of the writable ext4 device.
RW string
// Init is the path of the init of the image.
Init string
}
Params holds the validated kernel parameters of the guest contract.
func ParseCmdline ¶
ParseCmdline parses a kernel command line and validates the parameters of the guest contract. When a key appears more than once, the last value wins.
type System ¶
type System interface {
// ReadFile returns the contents of the file at path.
ReadFile(path string) ([]byte, error)
// Stat returns the information of the file at path, following symlinks.
Stat(path string) (os.FileInfo, error)
// MkdirAll creates the directory at path and its parents if they are absent.
MkdirAll(path string, perm os.FileMode) error
// Mount calls mount(2).
Mount(source, target, fstype string, flags uintptr, data string) error
// Chdir changes the working directory of the process.
Chdir(path string) error
// Chroot changes the root directory of the process.
Chroot(path string) error
// RemoveContents deletes everything under dir without crossing a mount
// point. It leaves dir itself in place.
RemoveContents(dir string) error
// Environ returns the environment of the process.
Environ() []string
// Exec replaces the process with the program at path. It only returns on error.
Exec(path string, argv, env []string) error
// Now returns the current time.
Now() time.Time
// Sleep pauses the process for d.
Sleep(d time.Duration)
}
System is the set of syscalls the init needs. The Linux implementation is NewSystem. The tests use a fake, so the sequence and the failure paths are tested without a boot.