proxy

Documentation

Overview

Package proxy implements a library for handling proxyDHCP requests.

Index

• Variables
• type ErrArchNotFound
  • func (e ErrArchNotFound) Error() string
• type ErrIgnorePacket
  • func (e ErrIgnorePacket) Error() string
• type ErrInvalidMsgType
  • func (e ErrInvalidMsgType) Error() string
• type ErrInvalidOption60
  • func (e ErrInvalidOption60) Error() string
• type Handler
  • func NewHandler(ctx context.Context, opts ...Option) *Handler
  • func (h *Handler) Redirection(conn net.PacketConn, peer net.Addr, m *dhcpv4.DHCPv4)
  • func (h *Handler) Server(addr netaddr.IPPort) (*server4.Server, error)
• type Option
  • func WithHTTPAddr(ha netaddr.IPPort) Option
  • func WithIPXEAddr(u *url.URL) Option
  • func WithIPXEScript(s string) Option
  • func WithLogger(l logr.Logger) Option
  • func WithTFTPAddr(ta netaddr.IPPort) Option
  • func WithUserClass(s string) Option
• type UserClass

Variables

var (
	// ErrOpt97LeadingByteError is used when the option 60 is not a valid PXE request.
	ErrOpt97LeadingByteError = fmt.Errorf("malformed client GUID (option 97), leading byte must be zero")
	// ErrOpt97WrongSize is used when the option 60 is not a valid PXE request.
	ErrOpt97WrongSize = fmt.Errorf("malformed client GUID (option 97), wrong size")
	// ErrOpt60Missing is used when the option 60 is missing from a PXE request.
	ErrOpt60Missing = fmt.Errorf("not a valid PXE request, missing option 60")
	// ErrOpt93Missing is used when the option 93 is missing from a PXE request.
	ErrOpt93Missing = fmt.Errorf("not a valid PXE request, missing option 93")
	// ErrOpt94Missing is used when the option 94 is missing from a PXE request.
	ErrOpt94Missing = fmt.Errorf("not a valid PXE request, missing option 94")
	// ErrUnknownArch is used when the PXE client request is from an unknown architecture.
	ErrUnknownArch = fmt.Errorf("could not determine client architecture from option 93")
	// ErrInvalidHandler is used when validation of the Handler struct fails.
	ErrInvalidHandler = fmt.Errorf("handler validation failed")
)

var ArchToBootFile = map[iana.Arch]string{
	iana.INTEL_X86PC:       "undionly.kpxe",
	iana.NEC_PC98:          "undionly.kpxe",
	iana.EFI_ITANIUM:       "undionly.kpxe",
	iana.DEC_ALPHA:         "undionly.kpxe",
	iana.ARC_X86:           "undionly.kpxe",
	iana.INTEL_LEAN_CLIENT: "undionly.kpxe",
	iana.EFI_IA32:          "ipxe.efi",
	iana.EFI_X86_64:        "ipxe.efi",
	iana.EFI_XSCALE:        "ipxe.efi",
	iana.EFI_BC:            "ipxe.efi",
	iana.EFI_ARM32:         "snp.efi",
	iana.EFI_ARM64:         "snp.efi",
	iana.EFI_X86_HTTP:      "ipxe.efi",
	iana.EFI_X86_64_HTTP:   "ipxe.efi",
	iana.EFI_ARM32_HTTP:    "snp.efi",
	iana.EFI_ARM64_HTTP:    "snp.efi",
}

ArchToBootFile maps supported hardware PXE architectures types to iPXE binary files.

Types

type ErrArchNotFound

type ErrArchNotFound struct {
	Arch   iana.Arch
	Detail string
}

ErrArchNotFound is for when an PXE client request is an architecture that does not have a matching bootfile. See var ArchToBootFile for the look ups.

func (ErrArchNotFound) Error

func (e ErrArchNotFound) Error() string

Error returns the string representation of ErrArchNotFound.

type ErrIgnorePacket

type ErrIgnorePacket struct {
	PacketType dhcpv4.MessageType
	Details    string
}

ErrIgnorePacket is for when a DHCP packet should be ignored.

func (ErrIgnorePacket) Error

func (e ErrIgnorePacket) Error() string

Error returns the string representation of ErrIgnorePacket.

type ErrInvalidMsgType

type ErrInvalidMsgType struct {
	Invalid dhcpv4.MessageType
}

ErrInvalidMsgType is used when the message type is not a valid DHCP message type [DISCOVER, REQUEST].

func (ErrInvalidMsgType) Error

func (e ErrInvalidMsgType) Error() string

Error returns the string representation of ErrInvalidMsgType.

type ErrInvalidOption60

type ErrInvalidOption60 struct {
	Opt60 string
}

ErrInvalidOption60 is used when the option 60 is not a valid PXE request [PXEClient, HTTPClient].

func (ErrInvalidOption60) Error

func (e ErrInvalidOption60) Error() string

Error returns the string representation of ErrInvalidOption60.

type Handler

type Handler struct {
	Ctx context.Context `validate:"required"`
	Log logr.Logger     `validate:"required"`
	// TFTPAddr is the address to use for PXE clients requesting a tftp boot.
	TFTPAddr netaddr.IPPort `validate:"required"`
	// HTTPAddr is the address to use for PXE clients requesting a http boot.
	HTTPAddr netaddr.IPPort `validate:"required"`
	// IPXEAddr is the address to use for PXE clients requesting to boot from an iPXE script.
	IPXEAddr *url.URL `validate:"required"`
	// IPXEScript is the iPXE script to use for PXE clients requesting to boot from an iPXE script.
	IPXEScript string `validate:"required"`
	// UserClass is the custom user class (dhcp opt 77) to check if we are in a known iPXE binary.
	// When found, this allow us to stop serving iPXE binaries for PXE client requests and serve an iPXE script.
	UserClass string `validate:""`
}

Handler holds the data necessary to respond correctly to PXE enabled DHCP requests. It also holds context and a logger.

func NewHandler

func NewHandler(ctx context.Context, opts ...Option) *Handler

NewHandler creates a new Handler struct. A few defaults are set here, but can be overridden by passing in options.

func (*Handler) Redirection

func (h *Handler) Redirection(conn net.PacketConn, peer net.Addr, m *dhcpv4.DHCPv4)

Redirection name comes from section 2.5 of http://www.pix.net/software/pxeboot/archive/pxespec.pdf

func (*Handler) Server

func (h *Handler) Server(addr netaddr.IPPort) (*server4.Server, error)

Server returns a proxy DHCP server for the Handler.

type Option

type Option func(*Handler)

Option for setting Handler values.

func WithHTTPAddr

func WithHTTPAddr(ha netaddr.IPPort) Option

WithHTTPAddr sets the HTTP address for the Handler struct.

func WithIPXEAddr

func WithIPXEAddr(u *url.URL) Option

WithIPXEAddr sets the IPXE address for the Handler struct.

func WithIPXEScript

func WithIPXEScript(s string) Option

WithIPXEScript sets the IPXE script for the Handler struct.

func WithLogger

func WithLogger(l logr.Logger) Option

WithLogger sets the logger for the Handler struct.

func WithTFTPAddr

func WithTFTPAddr(ta netaddr.IPPort) Option

WithTFTPAddr sets the TFTP address for the Handler struct.

func WithUserClass

func WithUserClass(s string) Option

WithUserClass sets the user class for the Handler struct.

type UserClass

type UserClass string

UserClass is DHCP option 77 (https://www.rfc-editor.org/rfc/rfc3004.html).

const (
	// If the client has had iPXE burned into its ROM (or is a VM
	// that uses iPXE as the PXE "ROM"), special handling is
	// needed because in this mode the client is using iPXE native
	// drivers and chainloading to a UNDI stack won't work.
	IPXE UserClass = "iPXE"
	// If the client identifies as "Tinkerbell", we've already
	// chainloaded this client to the full-featured copy of iPXE
	// we supply. We have to distinguish this case so we don't
	// loop on the chainload step.
	Tinkerbell UserClass = "Tinkerbell"
)

known user-class types. must correspond to DHCP option 77 - User-Class https://www.rfc-editor.org/rfc/rfc3004.html