sysinit

Documentation

Overview

Package sysinit provides functions for building a simple init binary that sets up system virtual file system mount points, sets up correct shutdown and communicates the binaries exit codes on stdout for consumption by the QEMU wrapper virtrun.

Index

• Constants
• Variables
• func ConfigureLoopbackInterface() error
• func CreateSymlinks(symlinks Symlinks) error
• func IsPidOne() bool
• func IsPidOneChild() bool
• func ListRegularFiles(dir string) ([]string, error)
• func LoadModule(path string, params string) error
• func LoadModules(dir string) error
• func Mount(mount MountPoint) error
• func MountAll(mountPoints MountPoints) error
• func Poweroff()
• func PrintError(dst io.Writer, err error)
• func PrintExitCode(dst io.Writer, exitCode int)
• func Run(cfg Config, fn func() (int, error)) error
• func RunTests(m *testing.M, cfg Config)
• type Config
  • func DefaultConfig() Config
• type FSType
• type MountPoint
• type MountPoints
• type Symlinks

Constants

const ExitCodeFmt = "SYSINIT_EXIT_CODE: %d"

ExitCodeFmt is the format string for communicating the test results

The same format string must be configured for the [qemu.Command] so it is matched correctly.

Variables

var ErrNotPidOne = errors.New("process does not have ID 1")

ErrNotPidOne may be returned if the process is expected to be run as PID 1 but is not.

Functions

func ConfigureLoopbackInterface

func ConfigureLoopbackInterface() error

ConfigureLoopbackInterface brings the loopback interface up. Kernel should configure address already automatically.

func CreateSymlinks

func CreateSymlinks(symlinks Symlinks) error

CreateSymlinks creates common symbolic links in the file system.

This must be run after all file systems have been mounted.

func IsPidOne

func IsPidOne() bool

IsPidOne returns true if the running process has PID 1.

func IsPidOneChild

func IsPidOneChild() bool

IsPidOneChild returns true if the running process is a child of the process with PID 1.

func ListRegularFiles

func ListRegularFiles(dir string) ([]string, error)

ListRegularFiles lists all regular files in the given directory and all sub directories.

func LoadModule

func LoadModule(path string, params string) error

LoadModule loads the kernel module located at the given path with the given parameters.

The file may be compressed. The caller is responsible to ensure the module belongs to the running kernel and all dependencies are satisfied.

func LoadModules

func LoadModules(dir string) error

LoadModules loads all files found in the given directory as kernel modules.

func Mount

func Mount(mount MountPoint) error

Mount mounts the special file system with type FsType at the given path.

If path does not exist, it is created. An error is returned if this or the mount syscall fails.

func MountAll

func MountAll(mountPoints MountPoints) error

MountAll mounts all known essential special file systems at the usual paths.

All special file systems required for usual operations, like accessing kernel variables, modifying kernel knobs or accessing devices are mounted.

func Poweroff

func Poweroff()

Poweroff shuts down the system.

Call when done, or deferred right at the beginning of your `TestMain` function.

func PrintError

func PrintError(dst io.Writer, err error)

PrintError prints an error to the writer (like os.Stderr).

func PrintExitCode

func PrintExitCode(dst io.Writer, exitCode int)

PrintExitCode prints the magic string communicating the exit code of the init to the writer (like os.Stdout).

func Run

func Run(cfg Config, fn func() (int, error)) error

Run is the entry point for an actual init system. It prepares the system to be used. Preparing steps are: - Guarding itself to be actually PID 1. - Setup system poweroff on its exit. - Mount all known virtual system file systems.

Once this is done, the given function is run. The function must not call os.Exit itself since the program would not be able to ensure a correct system termination.

After that, an exit code is sent to stdout for consumption by the host process. The exit code returned by the function is used, unless it returned with an error. If the error is an exec.ExitError, it is parsed and its exit code is used. Otherwise the exit code is 127 in case it was never set or 126 in case there was an error.

func RunTests

func RunTests(m *testing.M, cfg Config)

RunTests sets up the system, runs the tests and shuts down the system.

Call it from your `TestMain` function. It wraps testing.M.Run and returns only in case of failure. It is an error if the process does not run with PID 1, since the intention of this library is to run test binaries in an isolated system.

Types

type Config

type Config struct {
	MountPoints       MountPoints
	Symlinks          Symlinks
	ConfigureLoopback bool
	ModulesDir        string
}

Config defines basic system configuration.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig creates a new default config.

type FSType

type FSType string

FSType is a file system type.

const (
	FSTypeDevTmp  FSType = "devtmpfs"
	FSTypeProc    FSType = "proc"
	FSTypeSys     FSType = "sysfs"
	FSTypeTmp     FSType = "tmpfs"
	FSTypeBpf     FSType = "bpf"
	FSTypeTracing FSType = "tracefs"
)

Special essential file system types.

type MountPoint

type MountPoint struct {
	Path   string
	FSType FSType
}

MountPoint is a single mount point for a virtual system FS.

type MountPoints

type MountPoints []MountPoint

MountPoints is a collection of MountPoints.

type Symlinks

type Symlinks map[string]string

Symlinks is a collection of symbolic links. Keys are symbolic links to create with the value being the target to link to.