The iSCSI boot driver for FreeBSD

This driver provides an iSCSI boot feature for FreeBSD. It can be used with a bootable initiator offered by many server BIOSes, NIC firmwares or iPXE/gPXE. It connects to the iSCSI target specified in the iSCSI Boot Firmware Table (iBFT) automatically, making it simple to run a diskless machine.

Your boot firmware will create and populate the iBFT, connect to the specified iSCSI target and attempt to boot from the target volume (like any other supported disk). Any normal bootloader (such as FreeBSD's gptboot) can be used. The bootloader should load the kernel and modules (including isboot) and begin execution. During boot, the isboot driver configures the NIC and creates a new connection to the iSCSI target. The disk is then available to the operating system as normal, and can be used to mount the root volume.

Installation:

1. extract the archive:

   tar zxvf isboot-x.x.x.tar.gz

2. compile the module:

   cd isboot-x.x.x/src

   make

3. install the compiled module to the kernel directory:

   make install

4. edit /boot/loader.conf, and add the following line: isboot_load="YES"

Note: If you want use isboot with VIMAGE kernel, add CFLAGS+= -DVIMAGE to Makefile. The boot device may change after installation. It may be necessary to edit /etc/fstab in single-user mode.

The iBFT code supports two loader tunables: hw.ibft.acpi_table: Defaults to 1. If you have multiple iSCSI boot firmwares you may need to set this to a different value (such as 2). hw.ibft.verbose: Defaults to 0. Set it to 1 to enable verbose iBFT logs.

Similarly, there is a loader tunable for isboot debug output: net.isboot.debug: Defaults to 0. Set it to 1 for high-level messages, 2 for all informational messages and 3 for full trace output.

After boot you can see the boot device information via sysctl(8).

For example:

# sysctl net.isboot
net.isboot.device: da5
net.isboot.nic: cxl0
net.isboot.version: 0.2.15

# sysctl hw.ibft
hw.ibft.verbose: 1
hw.ibft.acpi_table: 1
hw.ibft.nic_gateway: 0.0.0.0
hw.ibft.nic_prefix: 24
hw.ibft.target_lun: 0
hw.ibft.target_port: 3260
hw.ibft.target_address: 192.168.104.10
hw.ibft.target_name: iqn.2002-05.net.jnielsen:max-iscsi
hw.ibft.initiator_address: 192.168.104.9
hw.ibft.initiator_name: iqn.2020-06.com.chelsio.boot:0007432FFBD0

# camcontrol inquiry da5
pass8: <JNC iSCSI 0001> Fixed Direct Access SPC-5 SCSI device
pass8: Serial Number 42
pass8: 300.000MB/s transfers

Supported OS versions: o FreeBSD 12.4 o FreeBSD 13.2 o FreeBSD 14.x

Project website: https://github.com/jnielsendotnet/isboot

The original author's blog (in Japanese) had some additional information: https://web.archive.org/web/20160810012908/http://shell.peach.ne.jp/aoyama/

Authors: Daisuke Aoyama aoyama@peach.ne.jp Michael Zoon zoon01@xigmanas.com John Nielsen john@jnielsen.net