booter

README

Booter package

The booter package provides a Booter interface that allows to define custom ways of booting a machine. Booter only requires a method to get its name, and a method to boot the machine. This interface is suitable to be used by Systemboot's uinit.

Each custom booter will define their own name (e.g. "netboot") and the custom logic to boot. For example, a network booter may try to get a network configuration via DHCPv6, download a boot program, and run it.

The custom booter also needs to provide a way to be initialized. This is usually done by defining a function called "New" (e.g. "NewNetBooter"). This function takes as input a sequence of bytes, representing the booter configuration, and will return a Booter object, or an error.

The exact format of the boot configuration is determined by the custom booter, but there is a general structure that every booter configuration has to provide. This is discussed in the Booter configuration section below

Booter configuration

A Booter configuration is a JSON file with a simple structure. The requirements are:

• the top level object is a map
• the map contains at least a "type" field, with a string value that holds the booter's name
• the JSON should not be nested. This is recommended for simplicity but is not strictly required

For example, the NetBooter configuration can be like the following:

{
    "type": "netboot",
    "method": "<method>",
    "mac": "<mac address",
    "override_url": "<url>"
}

where:

• "type" is required, and its value is always "netboot" (otherwise it's not recognized as a NetBooter)
• "method" is required, and can be either "dhcpv6", "dhcpv4" or "slaac"
• "mac" is required, and it is the MAC address of the interface that will try to boot from the network. It has the "aa:bb:cc:dd:ee:ff" format
• "override_url" is optional, unles "method" is "slaac", and it is the URL from which the booter will try to download the network boot program

Creating a new Booter

To create a new Booter, the following things are necessary:

• define a structure for the new booter, that implements the Booter interface described above. I.e. implement the TypeName and Boot methods
• define a NewMyBooterName (e.g. "NewLocalBoot") that takes a sequence of bytes as input, and return a Booter or an error if it's an invalid or unknown configuration. The input byte sequence must contain a valid JSON configuration for that booter in order to return successfully
• the new booter has to be registered as a supported booter. Just add the NewMyBooterName function (however this function is called) to the supportedBooterParsers in bootentry.go. This array is used by GetBootEntries to test a boot configuration against all the available booters

Documentation

Index

• Variables
• type BootEntry
  • func GetBootEntries() []BootEntry
• type Booter
  • func GetBooterFor(entry BootEntry) Booter
  • func NewLocalBooter(config []byte) (Booter, error)
  • func NewNetBooter(config []byte) (Booter, error)
• type LocalBooter
  • func (lb *LocalBooter) Boot() error
  • func (lb *LocalBooter) TypeName() string
• type NetBooter
  • func (nb *NetBooter) Boot() error
  • func (nb *NetBooter) TypeName() string
• type NullBooter
  • func (nb *NullBooter) Boot() error
  • func (nb *NullBooter) TypeName() string

Variables

var (
	Get    = vpd.Get
	Set    = vpd.Set
	GetAll = vpd.GetAll
)

Get, Set and GetAll are defined here as variables so they can be overridden for testing, or for using a key-value store other than VPD.

Types

type BootEntry

type BootEntry struct {
	Name   string
	Config []byte
	Booter Booter
}

BootEntry represents a boot entry, with its name, configuration, and Booter instance. It can map to existing key-value stores like VPD or EFI vars.

func GetBootEntries

func GetBootEntries() []BootEntry

GetBootEntries returns a list of BootEntry objects stored in the VPD partition of the flash chip

type Booter

type Booter interface {
	Boot() error
	TypeName() string
}

Booter is an interface that defines custom boot types. Implementations can be like network boot, local boot, etc.

func GetBooterFor

func GetBooterFor(entry BootEntry) Booter

GetBooterFor looks for a supported Booter implementation and returns it, if found. If not found, a NullBooter is returned.

func NewLocalBooter

func NewLocalBooter(config []byte) (Booter, error)

NewLocalBooter parses a boot entry config and returns a Booter instance, or an error if any

func NewNetBooter

func NewNetBooter(config []byte) (Booter, error)

NewNetBooter parses a boot entry config and returns a Booter instance, or an error if any

type LocalBooter

type LocalBooter struct {
	Type       string `json:"type"`
	Method     string `json:"method"`
	DeviceGUID string `json:"device_guid"`
	Kernel     string `json:"kernel,omitempty"`
	KernelArgs string `json:"kernel_args,omitempty"`
	Initramfs  string `json:"ramfs,omitempty"`
}

LocalBooter implements the Booter interface for booting from local storage.

func (*LocalBooter) Boot

func (lb *LocalBooter) Boot() error

Boot will run the boot procedure. In the case of LocalBooter, it will call the `localboot` command

func (*LocalBooter) TypeName

func (lb *LocalBooter) TypeName() string

TypeName returns the name of the booter type

type NetBooter

type NetBooter struct {
	Type           string  `json:"type"`
	Method         string  `json:"method"`
	MAC            string  `json:"mac"`
	OverrideURL    *string `json:"override_url,omitempty"`
	Retries        *int    `json:"retries,omitempty"`
	DebugOnFailure bool    `json:"debug_on_failure,omitempty"`
}

NetBooter implements the Booter interface for booting over DHCPv6. See NewNetBooterDHCPv6 for details on the fields.

func (*NetBooter) Boot

func (nb *NetBooter) Boot() error

Boot will run the boot procedure. In the case of NetBooter, it will call the `netboot` command

func (*NetBooter) TypeName

func (nb *NetBooter) TypeName() string

TypeName returns the name of the booter type

type NullBooter

type NullBooter struct {
}

NullBooter is a dummy booter that does nothing. It is used when no other booter has been found

func (*NullBooter) Boot

func (nb *NullBooter) Boot() error

Boot will run the boot procedure. In the case of this NullBooter it will do nothing

func (*NullBooter) TypeName

func (nb *NullBooter) TypeName() string

TypeName returns the name of the booter type