uinit

README

uinit

Uinit is a simple golang init process that is intended to be run from within u-root (but can run elsewhere too, say, as a light-weight container init).

Overview

Uinit is built to be scriptable with a simple YAML-format file. For an example script, see: cmds/uinit/uinit.script.

By default, uinit reads the script at the relative path ./uinit.script and writes tot he log file ./uinit.log. An alternative script can be specified on the commandline: ./uinit <path_to_script>

Uinit maintains a key/value store that allows for storing and recalling variables within the script. Variables can be accessed by placing strings of the format "{{.<key>}}" anywhere in the args section of a task. Technically, anything that can be processed by Go's text/template package can be placed here.

Uinit reads the script as a sequence of tasks. Each task calls a "module", and passes "args" to the module. Currently, we have the following modules:

• echo : Echo something to the log
• command : Execute a command. This can execute in foreground, background, or call Exec (which terminates uinit). Commands can be executed within a shell or directly.
• setvar : Sets a variable in the key/value store that can be later referenced.
• cmdline : Reads a file containing commandline arguments of the style: uinit.<key>=<val> adn sets <key> = <val> in the key/value store. If formated as uinit.key, then val="true" implicitly. This is intended primarily to read variables from /proc/cmdline which is the default file to parse, allowing for uinit configuration by kernel parameters. The prefix, which defaults to uinit can be set to anything.
• mount : Mount a filesystem.
• script : Run a subscript, either directly specified or in another script file.

More modules to come! (maybe?)

For more details on modules, see the example scripts, or look for README.md files in the modules/<module> directory.

Building/using

1. go get -u github.com/kraken-hpc/uinit/cmds/uinit This will build uinit and place it in $GOPATH/bin.
2. Write a script (see example *.script files)
3. Run it, and either name the script ./uinit.script, or pass it as a commandline argument.

Using as a package

As of v0.2.0, uinit can also be used as a Go package. This package will let your application run uinit scripts natively.

As an example, to load and run a script from a file:

s, err := uinit.NewScriptFromFile("myscript.script", logger)
if err != nil {
   log.Fatalf("failed to load script: %v", err)
}
if err = s.Run(); err != nil {
   log.Fatalf("failed to run script: %v", err)
}

For more details, see the package documentation at https://pkg.go.dev/github.com/kraken-hpc/uinit.

Building into u-root

You can build uinit directly into u-root by adding the following commandline options to your u-root build: -uinitcmd /bbin/uinit github.com/kraken-hpc/uinit/cmds/uinit Then make sure that you have a uinit.script in the root of your base cpio.

If you intend to boot something with systemdout of this, you'll want to:

1. have uroot.systemd on your kernel commandline
2. put a built uinit named inito in the root of your base cpio

Enjoy

Documentation

Index

• Variables
• func SplitCommandLine(s string) []string
• type KeyValue
• type Module
• type ModuleContext
• type Script
  • func NewScript(data []byte, logger *log.Logger) (s *Script, err error)
  • func NewScriptFromFile(file string, logger *log.Logger) (s *Script, err error)
  • func (s *Script) Run() (err error)
  • func (s *Script) Validate() (err error)
• type SimpleKV
  • func NewSimpleKV() (kv *SimpleKV)
  • func (kv *SimpleKV) Clear() (err error)
  • func (kv *SimpleKV) Get(name string) (val string, err error)
  • func (kv *SimpleKV) GetDefault(name, dval string) string
  • func (kv *SimpleKV) GetMap() map[string]string
  • func (kv *SimpleKV) Init()
  • func (kv *SimpleKV) Set(name, val string) (err error)
• type Task
  • func (t *Task) Run(ctx *ModuleContext) (err error)

Variables

var Modules = map[string]Module{}

Modules registry must be configured by the running application

Functions

func SplitCommandLine

func SplitCommandLine(s string) []string

SplitCommandLine strings on spaces except when a space is within a quoted, bracketed, or braced string. Supports nesting multiple brackets or braces.

Types

type KeyValue

type KeyValue interface {
	Init()
	Set(string, string) error
	Get(string) (string, error)
	GetDefault(string, string) string
	Clear() error
	GetMap() map[string]string
}

KeyValue describes our requirements for a key value store

type Module

type Module interface {
	Args() interface{}
	Run(ctx *ModuleContext, args interface{}) error
}

A Module is a named hook that can perform some task in our script A Script consists of a set of Tasks that use Modules to do work

type ModuleContext

type ModuleContext struct {
	Vars KeyValue
	Log  *log.Logger
}

ModuleContext gets passed to modules when they Run Vars provides a KeyValue store to be used by the script Log provides output logging capabilities for the script

type Script

type Script struct {
	Context *ModuleContext
	Tasks   []Task
}

A Script object represents a runnable uinit script A properly initialized scripted can be executed with Run()

func NewScript

func NewScript(data []byte, logger *log.Logger) (s *Script, err error)

NewScript will parse a YAML-formatted documented encoded in `data` If logger == nil, log.Default() will be used.

func NewScriptFromFile

func NewScriptFromFile(file string, logger *log.Logger) (s *Script, err error)

NewScriptFromFile will attempt to read and parse a YAML script in `file` and return a Script object. If logger == nil, log.Default() will be used.

func (*Script) Run

func (s *Script) Run() (err error)

Run will execute all of the tasks in the specified script. It will print progress messages to the script's Logger

func (*Script) Validate

func (s *Script) Validate() (err error)

Validate test whether a script is sane and ready to run

type SimpleKV

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

SimpleKV just provides an interface to a map

func NewSimpleKV

func NewSimpleKV() (kv *SimpleKV)

NewSimpleKV creates a new, initialized SimpleKV

func (*SimpleKV) Clear

func (kv *SimpleKV) Clear() (err error)

Clear clears the kv store

func (*SimpleKV) Get

func (kv *SimpleKV) Get(name string) (val string, err error)

Get tries to get a named value, returns an error if it doesn't exist

func (*SimpleKV) GetDefault

func (kv *SimpleKV) GetDefault(name, dval string) string

GetDefault tries to get a named value, sets to dval if it doesn't exist

func (*SimpleKV) GetMap

func (kv *SimpleKV) GetMap() map[string]string

GetMap returns a map that can be used for templating

func (*SimpleKV) Init

func (kv *SimpleKV) Init()

Init performs initializes internal data for the store

func (*SimpleKV) Set

func (kv *SimpleKV) Set(name, val string) (err error)

Set sets a named value in a map (will override)

type Task

type Task struct {
	Name   string
	Module string
	Args   yaml.Node
	Loop   []string
}

A Task is an individual Script item Each task should have at least a Name and Module Most tasks will have Args in a structure defined by the module A task can be executed in a loop if `Loop` is provided, in which case the Args will be templated with {{item}} = current loop value.

func (*Task) Run

func (t *Task) Run(ctx *ModuleContext) (err error)

Run an individual task