ipxedust

README

ipxedust

TFTP and HTTP library and cli for serving iPXE binaries.

Build

make build

Usage

CLI

./bin/ipxe-linux -h # ./bin/ipxe-darwin -h

USAGE
  Run TFTP and HTTP iPXE binary server

FLAGS
  -http-addr 0.0.0.0:8080  HTTP server address
  -http-timeout 5s         HTTP server timeout
  -log-level info          Log level
  -tftp-addr 0.0.0.0:69    TFTP server address
  -tftp-timeout 5s         TFTP server timeout

Design Philosophy

This repository is designed to be both a library and a command line tool. The custom iPXE binaries are built in the open. See the iPXE doc here for details. The coding design philosophy can be found here.

System Context Diagram

The following diagram details how ipxedust(ipxe binaries) fits into the greater Boots(PXE) stack. Architecture.

Documentation

Overview

Package ipxedust implements the iPXE tftp and http serving.

Index

• func Execute(ctx context.Context, args []string) error
• type Command
  • func (c *Command) RegisterFlags(f *flag.FlagSet)
  • func (c *Command) Run(ctx context.Context) error
  • func (c *Command) Validate() error
• type Server
  • func (c *Server) ListenAndServe(ctx context.Context) error
  • func (c *Server) Serve(ctx context.Context, tcpConn net.Listener, udpConn net.PacketConn) error
  • func (c *Server) Transformer(typ reflect.Type) func(dst, src reflect.Value) error
• type ServerSpec

Functions

func Execute

func Execute(ctx context.Context, args []string) error

Execute runs the ipxe command. Flags are registered, cli/env vars are parsed, the Command struct is validated, and the tftp and http services are run.

Types

type Command

type Command struct {
	// TFTPAddr is the TFTP server address:port.
	TFTPAddr string `validate:"required,hostname_port"`
	// TFTPTimeout is the timeout for serving individual TFTP requests.
	TFTPTimeout time.Duration `validate:"required,gte=1s"`
	// HTTPAddr is the HTTP server address:port.
	HTTPAddr string `validate:"required,hostname_port"`
	// HTTPTimeout is the timeout for serving individual HTTP requests.
	HTTPTimeout time.Duration `validate:"required,gte=1s"`
	// Log is the logging implementation.
	Log logr.Logger
	// LogLevel defines the logging level.
	LogLevel string
	// EnableTFTPSinglePort is a flag to enable single port mode for the TFTP server.
	// A standard TFTP server implementation receives requests on port 69 and
	// allocates a new high port (over 1024) dedicated to that request. In single
	// port mode, the same port is used for transmit and receive. If the server
	// is started on port 69, all communication will be done on port 69.
	// This option is required when running in a container that doesn't bind to the hosts
	// network because this type of dynamic port allocation is not generally supported.
	//
	// This option is specific to github.com/pin/tftp. The pin/tftp library says this option is
	// experimental and "Enabling this will negatively impact performance". Please take this into
	// consideration when using this option.
	EnableTFTPSinglePort bool
}

Command represents the ipxe command.

func (*Command) RegisterFlags

func (c *Command) RegisterFlags(f *flag.FlagSet)

RegisterFlags registers a flag set for the ipxe command.

func (*Command) Run

func (c *Command) Run(ctx context.Context) error

Run listens and serves the TFTP and HTTP services.

func (*Command) Validate

func (c *Command) Validate() error

Validate checks the Command struct for validation errors.

type Server

type Server struct {
	// TFTP holds the details specific for the TFTP server.
	TFTP ServerSpec
	// HTTP holds the details specific for the HTTP server.
	HTTP ServerSpec
	// Log is the logger to use.
	Log logr.Logger
	// EnableTFTPSinglePort is a flag to enable single port mode for the TFTP server.
	// A standard TFTP server implementation receives requests on port 69 and
	// allocates a new high port (over 1024) dedicated to that request. In single
	// port mode, the same port is used for transmit and receive. If the server
	// is started on port 69, all communication will be done on port 69.
	// This option is required when running in a container that doesn't bind to the hosts
	// network because this type of dynamic port allocation is not generally supported.
	//
	// This option is specific to github.com/pin/tftp. The pin/tftp library says this option is
	// experimental and "Enabling this will negatively impact performance". Please take this into
	// consideration when using this option.
	EnableTFTPSinglePort bool
}

Server holds the details for configuring the iPXE service.

func (*Server) ListenAndServe

func (c *Server) ListenAndServe(ctx context.Context) error

ListenAndServe will listen and serve iPXE binaries over TFTP and HTTP.

Default TFTP listen address is ":69".

Default HTTP listen address is ":8080".

Default request timeout for both is 5 seconds.

Override the defaults by setting the Config struct fields. See binary/binary.go for the iPXE files that are served.

func (*Server) Serve

func (c *Server) Serve(ctx context.Context, tcpConn net.Listener, udpConn net.PacketConn) error

Serve iPXE binaries over TFTP using udpConn and HTTP using tcpConn.

func (*Server) Transformer

func (c *Server) Transformer(typ reflect.Type) func(dst, src reflect.Value) error

Transformer for merging the netip.IPPort and logr.Logger structs.

type ServerSpec

type ServerSpec struct {
	// Addr is the address:port to listen on for requests.
	Addr netip.AddrPort
	// Timeout is the timeout for serving individual requests.
	Timeout time.Duration
	// Disabled allows a server to be disabled. Useful, for example, to disable TFTP.
	Disabled bool
	// The patch to apply to the iPXE binary.
	Patch []byte
}

ServerSpec holds details used to configure a server.