ibft

Documentation

Overview

Package ibft defines the iSCSI Boot Firmware Table.

An iBFT is placed in memory by a bootloader to tell an OS which iSCSI target it was booted from and what additional iSCSI targets it shall connect to.

An iBFT is typically placed in one of two places:

(1) an ACPI table named "iBFT", or

(2) in the 512K-1M physical memory range identified by its first 4 bytes.

However, this package doesn't concern itself with the placement, just the marshaling of the table's bytes.

Index

• type BDF
• type IBFT
  • func (i *IBFT) Marshal() []byte
  • func (i *IBFT) String() string
• type Initiator
• type NIC
• type Origin
• type Target

Types

type BDF

type BDF struct {
	Bus      uint8
	Device   uint8
	Function uint8
}

BDF is a Bus/Device/Function Identifier of a PCI device.

type IBFT

type IBFT struct {
	SingleLoginMode bool

	// Initiator offset: 0x50
	Initiator Initiator

	// NIC offset: 0xa0
	NIC0 NIC

	// Target offset: 0x110
	Target0 Target
}

IBFT defines the entire iSCSI boot firmware table.

func (*IBFT) Marshal

func (i *IBFT) Marshal() []byte

Marshal returns a binary representation of the iBFT.

Pointers within an iBFT is relative, so this can be placed anywhere necessary.

func (*IBFT) String

func (i *IBFT) String() string

String is a short summary of the iBFT contents.

type Initiator

type Initiator struct {
	// Name is the name of the initiator.
	//
	// Some servers apparently use initiator names for permissions.
	Name string

	Valid bool

	// Boot indicates that this initiator was used to boot.
	Boot bool

	// I have no clue what this stuff is.
	SNSServer             net.IP
	SLPServer             net.IP
	PrimaryRadiusServer   net.IP
	SecondaryRadiusServer net.IP
}

Initiator defines an iSCSI initiator.

type NIC

type NIC struct {
	// Valid NIC.
	Valid bool

	// Boot indicates this NIC was used to boot from.
	Boot bool

	// Global indicates a globally reachable IP (as opposed to a link-local IP).
	Global bool

	// IPNet is the IP and subnet mask for this network interface.
	IPNet *net.IPNet

	// Origin is the source of the IP address prefix.
	//
	// It's hard to say what loaded operating systems do with this field.
	//
	// The Windows docs for NL_PREFIX_ORIGIN consider it the origin of only
	// the IP address prefix. iPXE only ever sets the Manual and DHCP
	// constants, even in all IPv6 cases where it came from RAs.
	Origin Origin

	// Gateway is the network gateway. The gateway must be within the IPNet.
	Gateway net.IP

	// PrimaryDNS is the primary DNS server.
	PrimaryDNS net.IP

	// SecondaryDNS is a secondary DNS server.
	SecondaryDNS net.IP

	// DHCPServer is the address for the DHCP server, if one was used.
	DHCPServer net.IP

	// VLAN is the VLAN for this network interface.
	VLAN uint16

	// MACAddress is the MAC of the network interface.
	MACAddress net.HardwareAddr

	// PCIBDF is the Bus/Device/Function identifier of the PCI NIC device.
	PCIBDF BDF

	// HostName is the host name of the machine.
	HostName string
}

NIC defines NIC network configuration such as IP, gateway, DNS.

type Origin

type Origin uint8

Origin is the source of network configuration; for example, DHCP or static configuration.

The spec links to a Microsoft.com 404 page. We got this info from iPXE code, but most likely it refers to the NL_PREFIX_ORIGIN enumeration in nldef.h, which can currently be found here https://docs.microsoft.com/en-us/windows/win32/api/nldef/ne-nldef-nl_prefix_origin

const (
	// OriginOther means the IP prefix was provided by a source other than
	// those in this enumeration.
	OriginOther Origin = 0

	// OriginManual means the IP address prefix was manually specified.
	OriginManual Origin = 1

	// OriginWellKnown means the IP address prefix is from a well-known
	// source.
	OriginWellKnown Origin = 2

	// OriginDHCP means the IP addrss prefix was provided by DHCP settings.
	OriginDHCP Origin = 3

	// OriginRA means the IP address prefix was obtained through a router
	// advertisement (RA).
	OriginRA Origin = 4

	// OriginUnchanged menas the IP address prefix should be unchanged.
	// This value is used when setting the properties for a unicast IP
	// interface when the value for the IP prefix origin should be left
	// unchanged.
	OriginUnchanged Origin = 0xf
)

These values and descriptions were taken from the NL_PREFIX_ORIGIN enumeration documentation for Windows.

They can also be found in iPXE source at src/include/ipxe/ibft.h.

type Target

type Target struct {
	Valid bool
	Boot  bool

	CHAP  bool
	RCHAP bool

	// Target is the server to connect to.
	Target *net.TCPAddr

	// BootLUN is the LUN to connect to.
	BootLUN uint64

	CHAPType uint8

	// NICAssociation is the Index of the NIC.
	NICAssociation uint8

	// TargetName is the name of the iSCSI target.
	//
	// The target name must be a valid iSCSI Qualifier Name or EUI.
	TargetName string

	CHAPName          string
	CHAPSecret        string
	ReverseCHAPName   string
	ReverseCHAPSecret string
}

Target carries info about an iSCSI target server.