1# iSCSI booting with U-Boot and iPXE 2 3## Motivation 4 5U-Boot has only a reduced set of supported network protocols. The focus for 6network booting has been on UDP based protocols. A TCP stack and HTTP support 7are expected to be integrated in 2018 together with a wget command. 8 9For booting a diskless computer this leaves us with BOOTP or DHCP to get the 10address of a boot script. TFTP or NFS can be used to load the boot script, the 11operating system kernel and the initial file system (initrd). 12 13These protocols are insecure. The client cannot validate the authenticity 14of the contacted servers. And the server cannot verify the identity of the 15client. 16 17Furthermore the services providing the operating system loader or kernel are 18not the ones that the operating system typically will use. Especially in a SAN 19environment this makes updating the operating system a hassle. After installing 20a new kernel version the boot files have to be copied to the TFTP server 21directory. 22 23The HTTPS protocol provides certificate based validation of servers. Sensitive 24data like passwords can be securely transmitted. 25 26The iSCSI protocol is used for connecting storage attached networks. It 27provides mutual authentication using the CHAP protocol. It typically runs on 28a TCP transport. 29 30Thus a better solution than DHCP/TFTP/NFS boot would be to load a boot script 31via HTTPS and to download any other files needed for booting via iSCSI from the 32same target where the operating system is installed. 33 34An alternative to implementing these protocols in U-Boot is to use an existing 35software that can run on top of U-Boot. iPXE is the "swiss army knife" of 36network booting. It supports both HTTPS and iSCSI. It has a scripting engine for 37fine grained control of the boot process and can provide a command shell. 38 39iPXE can be built as an EFI application (named snp.efi) which can be loaded and 40run by U-Boot. 41 42## Boot sequence 43 44U-Boot loads the EFI application iPXE snp.efi using the bootefi command. This 45application has network access via the simple network protocol offered by 46U-Boot. 47 48iPXE executes its internal script. This script may optionally chain load a 49secondary boot script via HTTPS or open a shell. 50 51For the further boot process iPXE connects to the iSCSI server. This includes 52the mutual authentication using the CHAP protocol. After the authentication iPXE 53has access to the iSCSI targets. 54 55For a selected iSCSI target iPXE sets up a handle with the block IO protocol. It 56uses the ConnectController boot service of U-Boot to request U-Boot to connect a 57file system driver. U-Boot reads from the iSCSI drive via the block IO protocol 58offered by iPXE. It creates the partition handles and installs the simple file 59protocol. Now iPXE can call the simple file protocol to load Grub. U-Boot uses 60the block IO protocol offered by iPXE to fulfill the request. 61 62Once Grub is started it uses the same block IO protocol to load Linux. Via 63the EFI stub Linux is called as an EFI application. 64 65``` 66 +--------+ +--------+ 67 | | Runs | | 68 | U-Boot |=========>| iPXE | 69 | EFI | | snp.efi| 70+--------+ | | DHCP | | 71| |<====|********|<=========| | 72| DHCP | | | Get IP | | 73| Server | | | Address | | 74| |====>|********|=========>| | 75+--------+ | | Response | | 76 | | | | 77 | | | | 78+--------+ | | HTTPS | | 79| |<====|********|<=========| | 80| HTTPS | | | Load | | 81| Server | | | Script | | 82| |====>|********|=========>| | 83+--------+ | | | | 84 | | | | 85 | | | | 86+--------+ | | iSCSI | | 87| |<====|********|<=========| | 88| iSCSI | | | Auth | | 89| Server |====>|********|=========>| | 90| | | | | | 91| | | | Loads | | 92| |<====|********|<=========| | +--------+ 93| | | | Grub | | Runs | | 94| |====>|********|=========>| |=======>| Grub | 95| | | | | | | | 96| | | | | | | | 97| | | | | | Loads | | 98| |<====|********|<=========|********|<=======| | +--------+ 99| | | | | | Linux | | Runs | | 100| |====>|********|=========>|********|=======>| |=====>| Linux | 101| | | | | | | | | | 102+--------+ +--------+ +--------+ +--------+ | | 103 | | 104 | | 105 | ~ ~ ~ ~| 106``` 107 108## Security 109 110The iSCSI protocol is not encrypted. The traffic could be secured using IPsec 111but neither U-Boot nor iPXE does support this. So we should at least separate 112the iSCSI traffic from all other network traffic. This can be achieved using a 113virtual local area network (VLAN). 114 115## Configuration 116 117### iPXE 118 119For running iPXE on arm64 the bin-arm64-efi/snp.efi build target is needed. 120 121 git clone http://git.ipxe.org/ipxe.git 122 cd ipxe/src 123 make bin-arm64-efi/snp.efi -j6 EMBED=myscript.ipxe 124 125The available commands for the boot script are documented at: 126 127http://ipxe.org/cmd 128 129Credentials are managed as environment variables. These are described here: 130 131http://ipxe.org/cfg 132 133iPXE by default will put the CPU to rest when waiting for input. U-Boot does 134not wake it up due to missing interrupt support. To avoid this behavior create 135file src/config/local/nap.h. 136 137 /* nap.h */ 138 #undef NAP_EFIX86 139 #undef NAP_EFIARM 140 #define NAP_NULL 141 142The supported commands in iPXE are controlled by an include, too. Putting the 143following into src/config/local/general.h is sufficient for most use cases. 144 145 /* general.h */ 146 #define NSLOOKUP_CMD /* Name resolution command */ 147 #define PING_CMD /* Ping command */ 148 #define NTP_CMD /* NTP commands */ 149 #define VLAN_CMD /* VLAN commands */ 150 #define IMAGE_EFI /* EFI image support */ 151 #define DOWNLOAD_PROTO_HTTPS /* Secure Hypertext Transfer Protocol */ 152 #define DOWNLOAD_PROTO_FTP /* File Transfer Protocol */ 153 #define DOWNLOAD_PROTO_NFS /* Network File System Protocol */ 154 #define DOWNLOAD_PROTO_FILE /* Local file system access */ 155 156## Links 157 158* https://ipxe.org - iPXE open source boot firmware 159* https://www.gnu.org/software/grub/ - GNU Grub (Grand Unified Bootloader) 160