sysinit

package
v0.15.4 Latest Latest
Warning

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

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

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

View Source 
const (
	MS_NOSUID = unix.MS_NOSUID
	MS_NODEV  = unix.MS_NODEV
	MS_NOEXEC = unix.MS_NOEXEC
)

Mount flags.

View Source 
const (
	O_CLOEXEC = unix.O_CLOEXEC
	O_WRONLY  = unix.O_WRONLY
	O_NOCTTY  = unix.O_NOCTTY
	O_NDELAY  = unix.O_NDELAY
)

Open flags.

View Source 
const (
	ENODEV = unix.ENODEV
)

Errors.

Variables

View Source 
var (
	// ErrNotPidOne is returned if the process is expected to be run as PID 1
	// but is not.
	ErrNotPidOne = errors.New("process does not have ID 1")
	// ErrPanic is returned if a [Func] panicked.
	ErrPanic = errors.New("function panicked")
)

Functions 

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 LoadModule added in v0.11.0 

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 added in v0.11.0 

func LoadModules(pattern string) error

LoadModules loads all files found for the given glob pattern as kernel modules.

See filepath.Glob for the pattern format.

func Mount added in v0.11.0 

func Mount(path string, opts MountOptions) error

Mount mounts the system file system of 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 the given set of system file systems.

The mounts are executed in lexicographic order of the paths. If only optional mount points failed, it returns an OptionalMountError with all errors.

func Poweroff 

func Poweroff() error

Poweroff shuts down the system.

It does not return, unless in case of error. It should be called deferred at the start of the main init function.

func Run 

func Run(funcs ...Func)

Run is the entry point for an actual init system.

It runs the given functions and ensures proper shutdown of the system. It never returns. It must be run as PID 1, otherwise it panics immediately.

For proper communication with the virtrun host component /dev, /sys and /proc are mounted.

The given [Func]s are run in the order given. They must not terminate the program (e.g. by os.Exit). Panics are recovered from before the [ExitHandler] runs.

The given [ExitHandler] is run after the functions ran. It might be nil if they succeeded. It can be used for any post processing, like printing the exit code.

A typical example that prints the exit code to stdout would be: 

Run(
	ExitCodeID.PrintExitCode,
	[WithMountPoints]([SystemMountPoints]()),
	[WithSymlinks]([DevSymlinks]()),
	[WithInterfaceUp]("lo"),
	[WithModules]("/lib/modules/*"),
	[WithEnv]([EnvVars]{"PATH": "/data"}),
	func() error {
		// Optional additional custom setup functions.
	},
	func() error {
		// Your actual main code.
	},
)

Pay attention to the proper order: symlinks should be created after the dependent mounts.

func SetEnv added in v0.15.0 

func SetEnv(envVars EnvVars) error

SetEnv sets the given EnvVars in the environment.

func SetInterfaceUp added in v0.13.0 

func SetInterfaceUp(name string) error

SetInterfaceUp brings the interface with the given name up.

func SetupHostPipes added in v0.15.4 

func SetupHostPipes(state *State) error

SetupHostPipes configures all present serial/virtual consoles and creates /dev/virtun* symlinks.

If virto consoles are present (/dev/hvc*) then only those are used. Otherwise serial consoles (/dev/ttyS*) are used.

The ID of the created host pipes matches the ID/port of the console it writes to, e.g. /dev/virtrun1 writes to /dev/hvc1.

func Sysctl added in v0.15.0 

func Sysctl(key, value string) error

Sysctl allows to set kernel knobs via sysctl(2).

Types

type CleanupFunc added in v0.15.0 

type CleanupFunc func() error

CleanupFunc defines a function that runs on cleanup after all Func ran.

type EnvVars added in v0.12.0 

type EnvVars map[string]string

EnvVars is a map of environment variable values by name.

type FSType 

type FSType string

FSType is a file system type. 

const (
	FSTypeBpf      FSType = "bpf"
	FSTypeCgroup2  FSType = "cgroup2"
	FSTypeConfig   FSType = "configfs"
	FSTypeDebug    FSType = "debugfs"
	FSTypeDevPts   FSType = "devpts"
	FSTypeDevTmp   FSType = "devtmpfs"
	FSTypeFuseCtl  FSType = "fusectl"
	FSTypeHugeTlb  FSType = "hugetlbfs"
	FSTypeMqueue   FSType = "mqueue"
	FSTypeProc     FSType = "proc"
	FSTypePstore   FSType = "pstore"
	FSTypeSecurity FSType = "securityfs"
	FSTypeSys      FSType = "sysfs"
	FSTypeTracing  FSType = "tracefs"
)

Special file system types.

type Func added in v0.15.0 

type Func func(*State) error

Func is a function run by Run.

func WithEnv added in v0.15.0 

func WithEnv(envVars EnvVars) Func

WithEnv returns a setup Func that wraps SetEnv and can be used with Run.

func WithHostPipes added in v0.15.0 

func WithHostPipes() Func

WithHostPipes returns a setup Func that sets up consoles for communication with the host.

func WithInterfaceUp added in v0.15.0 

func WithInterfaceUp(name string) Func

WithInterfaceUp returns a Func that wraps SetInterfaceUp and can be used with Run.

func WithModules added in v0.15.0 

func WithModules(pattern string) Func

WithModules returns a setup Func that wraps LoadModules and can be used with Run.

func WithMountPoints added in v0.15.0 

func WithMountPoints(mountPoints MountPoints) Func

WithMountPoints returns a setup Func that wraps MountAll and can be used with Run.

It logs optional mounts that failed.

func WithStdoutHostPipe added in v0.15.0 

func WithStdoutHostPipe() Func

WithStdoutHostPipe returns a setup Func that sets up a separate stream for stdout. It replaces the original os.Stdout. 

func WithSymlinks(symlinks Symlinks) Func

WithSymlinks returns a setup Func that wraps CreateSymlinks and can be used with Run.

type MountFlags added in v0.14.0 

type MountFlags int

MountFlags is a set of flags passed to the unix.Mount syscall.

type MountOptions added in v0.13.0 

type MountOptions struct {
	// FSType is the files system type. It must be set to an available [FSType].
	FSType FSType

	// Source is the source device to mount. Can be empty for all the special
	// file system types [FSType]s. If empty it is set to the string of the
	// type.
	Source string

	// Flags are optional mount flags as defined by mount(2).
	Flags MountFlags

	// Data are optional additional parameters that depend of the [FSType] used.
	Data string
}

MountOptions contains parameters for a mount point.

type MountPoints 

type MountPoints map[string]MountOptions

MountPoints is a collection of MountPoints.

func SystemMountPoints added in v0.15.0 

func SystemMountPoints() MountPoints

SystemMountPoints returns a map of non-essential special pseudo and virtual file systems.

type OptionalMountError added in v0.15.0 

type OptionalMountError []error

OptionalMountError is a collection of errors that occurred for mount points that may fail.

func (OptionalMountError) Error added in v0.15.0 

func (e OptionalMountError) Error() string

func (OptionalMountError) Is added in v0.15.0 

func (OptionalMountError) Is(other error) bool

Is returns true if the given other error is an OptionalMountError.

func (OptionalMountError) Unwrap added in v0.15.0 

func (e OptionalMountError) Unwrap() []error

type State added in v0.15.0 

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

State keeps state of the current system.

func (*State) Cleanup added in v0.15.0 

func (s *State) Cleanup(fn CleanupFunc)

Cleanup register a cleanup.

Cleanup function run in the reverse order they are added. Errors are logged to the default logger.

func (*State) SetExitCode added in v0.15.0 

func (s *State) SetExitCode(exitCode int)

SetExitCode sets the exit code to be written on successful run.

If none is set or any errors occurred no exit code is written. 

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. 

func DevSymlinks() Symlinks

DevSymlinks returns a map with well-known symlinks for /dev.

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.