netboot: go.universe.tf/netboot/pixiecore Index | Files | Directories

package pixiecore

import "go.universe.tf/netboot/pixiecore"

Index

Package Files

boot_configuration.go booters.go dhcp.go dhcpv6.go http.go logging.go pixicorev6.go pixiecore.go pxe.go tftp.go urlsign.go

type APIBootConfiguration Uses

type APIBootConfiguration struct {
    Client        *http.Client
    URLPrefix     string
    RecursiveDNS  []net.IP
    Preference    []byte
    UsePreference bool
}

APIBootConfiguration provides an interface to retrieve Boot File URL from an external server based on client ID and architecture type

func MakeAPIBootConfiguration Uses

func MakeAPIBootConfiguration(url string, timeout time.Duration, preference uint8, usePreference bool,
    dnsServerAddresses []net.IP) *APIBootConfiguration

MakeAPIBootConfiguration creates a new APIBootConfiguration initialized with provided values

func (*APIBootConfiguration) GetBootURL Uses

func (bc *APIBootConfiguration) GetBootURL(id []byte, clientArchType uint16) ([]byte, error)

GetBootURL returns Boot File URL, see RFC 5970

func (*APIBootConfiguration) GetPreference Uses

func (bc *APIBootConfiguration) GetPreference() []byte

GetPreference returns server's Preference, see RFC 3315

func (*APIBootConfiguration) GetRecursiveDNS Uses

func (bc *APIBootConfiguration) GetRecursiveDNS() []net.IP

GetRecursiveDNS returns list of addresses of recursive DNS servers, see RFC 3646

type Architecture Uses

type Architecture int

Architecture describes a kind of CPU architecture.

const (
    // ArchIA32 is a 32-bit x86 machine. It _may_ also support X64
    // execution, but Pixiecore has no way of knowing.
    ArchIA32 Architecture = iota
    // ArchX64 is a 64-bit x86 machine (aka amd64 aka X64).
    ArchX64
)

Architecture types that Pixiecore knows how to boot.

These architectures are self-reported by the booting machine. The machine may support additional execution modes. For example, legacy PC BIOS reports itself as an ArchIA32, but may also support ArchX64 execution.

func (Architecture) String Uses

func (a Architecture) String() string

type Booter Uses

type Booter interface {
    // The given MAC address wants to know what it should
    // boot. What should Pixiecore make it boot?
    //
    // Returning an error or a nil BootSpec will make Pixiecore ignore
    // the client machine's request.
    BootSpec(m Machine) (*Spec, error)
    // Get the bytes corresponding to an ID given in Spec.
    //
    // Additionally returns the total number of bytes in the
    // ReadCloser, or -1 if the size is unknown. Be warned, returning
    // -1 will make the boot process orders of magnitude slower due to
    // poor ipxe behavior.
    ReadBootFile(id ID) (io.ReadCloser, int64, error)
    // Write the given Reader to an ID given in Spec.
    WriteBootFile(id ID, body io.Reader) error
}

A Booter provides boot instructions and files for machines.

Due to the stateless nature of various boot protocols, BootSpec() will be called multiple times in the course of a single boot attempt.

func APIBooter Uses

func APIBooter(url string, timeout time.Duration) (Booter, error)

APIBooter gets a BootSpec from a remote server over HTTP.

The API is described in README.api.md

func StaticBooter Uses

func StaticBooter(spec *Spec) (Booter, error)

StaticBooter boots all machines with the same Spec.

IDs in spec should be either local file paths, or HTTP/HTTPS URLs.

type Firmware Uses

type Firmware int

Firmware describes a kind of firmware attempting to boot.

This should only be used for selecting the right bootloader within Pixiecore, kernel selection should key off the more generic Architecture.

const (
    FirmwareX86PC         Firmware = iota // "Classic" x86 BIOS with PXE/UNDI support
    FirmwareEFI32                         // 32-bit x86 processor running EFI
    FirmwareEFI64                         // 64-bit x86 processor running EFI
    FirmwareEFIBC                         // 64-bit x86 processor running EFI
    FirmwareX86Ipxe                       // "Classic" x86 BIOS running iPXE (no UNDI support)
    FirmwarePixiecoreIpxe                 // Pixiecore's iPXE, which has replaced the underlying firmware
)

The bootloaders that Pixiecore knows how to handle.

type ID Uses

type ID string

An ID is an identifier used by Booters to reference files.

type Machine Uses

type Machine struct {
    MAC  net.HardwareAddr
    Arch Architecture
}

A Machine describes a machine that is attempting to boot.

type Server Uses

type Server struct {
    Booter Booter

    // Address to listen on, or empty for all interfaces.
    Address string
    // HTTP port for boot services.
    HTTPPort int
    // HTTP port for human-readable information. Can be the same as
    // HTTPPort.
    HTTPStatusPort int

    // Ipxe lists the supported bootable Firmwares, and their
    // associated ipxe binary.
    Ipxe map[Firmware][]byte

    // Log receives logs on Pixiecore's operation. If nil, logging
    // is suppressed.
    Log func(subsystem, msg string)
    // Debug receives extensive logging on Pixiecore's internals. Very
    // useful for debugging, but very verbose.
    Debug func(subsystem, msg string)

    // These ports can technically be set for testing, but the
    // protocols burned in firmware on the client side hardcode these,
    // so if you change them in production, nothing will work.
    DHCPPort int
    TFTPPort int
    PXEPort  int

    // Listen for DHCP traffic without binding to the DHCP port. This
    // enables coexistence of Pixiecore with another DHCP server.
    //
    // Currently only supported on Linux.
    DHCPNoBind bool

    // Read UI assets from this path, rather than use the builtin UI
    // assets. Used for development of Pixiecore.
    UIAssetsDir string
    // contains filtered or unexported fields
}

A Server boots machines using a Booter.

func (*Server) Serve Uses

func (s *Server) Serve() error

Serve listens for machines attempting to boot, and uses Booter to help them.

func (*Server) Shutdown Uses

func (s *Server) Shutdown()

Shutdown causes Serve() to exit, cleaning up behind itself.

type ServerV6 Uses

type ServerV6 struct {
    Address string
    Port    string
    Duid    []byte

    BootConfig    dhcp6.BootConfiguration
    PacketBuilder *dhcp6.PacketBuilder
    AddressPool   dhcp6.AddressPool

    Log   func(subsystem, msg string)
    Debug func(subsystem, msg string)
    // contains filtered or unexported fields
}

ServerV6 boots machines using a Booter.

func NewServerV6 Uses

func NewServerV6() *ServerV6

NewServerV6 returns a new ServerV6.

func (*ServerV6) Serve Uses

func (s *ServerV6) Serve() error

Serve listens for machines attempting to boot, and responds to their DHCPv6 requests.

func (*ServerV6) Shutdown Uses

func (s *ServerV6) Shutdown()

Shutdown causes Serve() to exit, cleaning up behind itself.

type Spec Uses

type Spec struct {
    // The kernel to boot
    Kernel ID
    // Optional init ramdisks for linux kernels
    Initrd []ID
    // Optional kernel commandline. This string is evaluated as a
    // text/template template, in which "ID(x)" function is
    // available. Invoking ID(x) returns a URL that will call
    // Booter.ReadBootFile(x) when fetched.
    Cmdline string
    // Message to print on the client machine before booting.
    Message string

    // A raw iPXE script to run. Overrides all of the above.
    //
    // THIS IS NOT A STABLE INTERFACE. This will only work for
    // machines that get booted via iPXE. Currently, that is all of
    // them, but there is no guarantee that this will remain
    // true. When passing a custom iPXE script, it is your
    // responsibility to make the boot succeed, Pixiecore's
    // involvement ends when it serves your script.
    IpxeScript string
}

A Spec describes a kernel and associated configuration.

type StaticBootConfiguration Uses

type StaticBootConfiguration struct {
    HTTPBootURL   []byte
    IPxeBootURL   []byte
    RecursiveDNS  []net.IP
    Preference    []byte
    UsePreference bool
}

StaticBootConfiguration provides values for dhcp options that remain unchanged until restart

func MakeStaticBootConfiguration Uses

func MakeStaticBootConfiguration(httpBootURL, ipxeBootURL string, preference uint8, usePreference bool,
    dnsServerAddresses []net.IP) *StaticBootConfiguration

MakeStaticBootConfiguration creates a new StaticBootConfiguration with provided values

func (*StaticBootConfiguration) GetBootURL Uses

func (bc *StaticBootConfiguration) GetBootURL(id []byte, clientArchType uint16) ([]byte, error)

GetBootURL returns Boot File URL, see RFC 5970

func (*StaticBootConfiguration) GetPreference Uses

func (bc *StaticBootConfiguration) GetPreference() []byte

GetPreference returns server's Preference, see RFC 3315

func (*StaticBootConfiguration) GetRecursiveDNS Uses

func (bc *StaticBootConfiguration) GetRecursiveDNS() []net.IP

GetRecursiveDNS returns list of addresses of recursive DNS servers, see RFC 3646

Directories

PathSynopsis
api-exampleThis is an example API server that just statically serves a kernel, initrd and commandline.
cliPackage cli implements the commandline interface for Pixiecore.

Package pixiecore imports 24 packages (graph) and is imported by 2 packages. Updated 2019-02-09. Refresh now. Tools for package owners.