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