Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit 29a8a2828e5c6f3f167a8526a80da992b4626daf

Authored by Heinrich Schuchardt
Committed by Alexander Graf
1 parent 4a8b5e7900
Exists in smarc_8mq_lf_v2020.04 and in 17 other branches 8qm-imx_v2020.04_5.4.70_2.3.0, emb_lf_v2022.04, pitx_8mp_lf_v2020.04, smarc-8m-android-10.0.0_2.6.0, smarc-8m-android-11.0.0_2.0.0, smarc-8mp-android-11.0.0_2.0.0, smarc-imx6_v2018.03_4.14.98_2.0.0_ga, smarc-imx7_v2018.03_4.14.98_2.0.0_ga, smarc-imx_v2018.03_4.14.78_1.0.0_ga, smarc_8m-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8m-imx_v2019.04_4.19.35_1.1.0, smarc_8m_00d0-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8mm-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8mm-imx_v2019.04_4.19.35_1.1.0, smarc_8mm-imx_v2020.04_5.4.24_2.1.0, smarc_8mp_lf_v2020.04, smarc_8mq-imx_v2020.04_5.4.24_2.1.0

efi_loader: add a README.iscsi describing booting via iSCSI 

The appended README explains how U-Boot and iPXE can be used
to boot a diskless system from an iSCSI SAN.

The maintainer for README.efi and README.iscsi is set.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
[agraf: s/Adress/Address/]
Signed-off-by: Alexander Graf <agraf@suse.de>

Showing 2 changed files with 160 additions and 0 deletions Side-by-side Diff

... ... @@ -289,6 +289,7 @@
289 289 M: Alexander Graf <agraf@suse.de>
290 290 S: Maintained
291 291 T: git git://github.com/agraf/u-boot.git
  292 +F: doc/README.iscsi
292 293 F: include/efi*
293 294 F: lib/efi*/
294 295 F: test/py/tests/test_efi*
  1 +# iSCSI booting with U-Boot and iPXE
  2 +
  3 +## Motivation
  4 +
  5 +U-Boot has only a reduced set of supported network protocols. The focus for
  6 +network booting has been on UDP based protocols. A TCP stack and HTTP support
  7 +are expected to be integrated in 2018 together with a wget command.
  8 +
  9 +For booting a diskless computer this leaves us with BOOTP or DHCP to get the
  10 +address of a boot script. TFTP or NFS can be used to load the boot script, the
  11 +operating system kernel and the initial file system (initrd).
  12 +
  13 +These protocols are insecure. The client cannot validate the authenticity
  14 +of the contacted servers. And the server cannot verify the identity of the
  15 +client.
  16 +
  17 +Furthermore the services providing the operating system loader or kernel are
  18 +not the ones that the operating system typically will use. Especially in a SAN
  19 +environment this makes updating the operating system a hassle. After installing
  20 +a new kernel version the boot files have to be copied to the TFTP server
  21 +directory.
  22 +
  23 +The HTTPS protocol provides certificate based validation of servers. Sensitive
  24 +data like passwords can be securely transmitted.
  25 +
  26 +The iSCSI protocol is used for connecting storage attached networks. It
  27 +provides mutual authentication using the CHAP protocol. It typically runs on
  28 +a TCP transport.
  29 +
  30 +Thus a better solution than DHCP/TFTP/NFS boot would be to load a boot script
  31 +via HTTPS and to download any other files needed for booting via iSCSI from the
  32 +same target where the operating system is installed.
  33 +
  34 +An alternative to implementing these protocols in U-Boot is to use an existing
  35 +software that can run on top of U-Boot. iPXE is the "swiss army knife" of
  36 +network booting. It supports both HTTPS and iSCSI. It has a scripting engine for
  37 +fine grained control of the boot process and can provide a command shell.
  38 +
  39 +iPXE can be built as an EFI application (named snp.efi) which can be loaded and
  40 +run by U-Boot.
  41 +
  42 +## Boot sequence
  43 +
  44 +U-Boot loads the EFI application iPXE snp.efi using the bootefi command. This
  45 +application has network access via the simple network protocol offered by
  46 +U-Boot.
  47 +
  48 +iPXE executes its internal script. This script may optionally chain load a
  49 +secondary boot script via HTTPS or open a shell.
  50 +
  51 +For the further boot process iPXE connects to the iSCSI server. This includes
  52 +the mutual authentication using the CHAP protocol. After the authentication iPXE
  53 +has access to the iSCSI targets.
  54 +
  55 +For a selected iSCSI target iPXE sets up a handle with the block IO protocol. It
  56 +uses the ConnectController boot service of U-Boot to request U-Boot to connect a
  57 +file system driver. U-Boot reads from the iSCSI drive via the block IO protocol
  58 +offered by iPXE. It creates the partition handles and installs the simple file
  59 +protocol. Now iPXE can call the simple file protocol to load Grub. U-Boot uses
  60 +the block IO protocol offered by iPXE to fulfill the request.
  61 +
  62 +Once Grub is started it uses the same block IO protocol to load Linux. Via
  63 +the 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 +
  110 +The iSCSI protocol is not encrypted. The traffic could be secured using IPsec
  111 +but neither U-Boot nor iPXE does support this. So we should at least separate
  112 +the iSCSI traffic from all other network traffic. This can be achieved using a
  113 +virtual local area network (VLAN).
  114 +
  115 +## Configuration
  116 +
  117 +### iPXE
  118 +
  119 +For 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 +
  125 +The available commands for the boot script are documented at:
  126 +
  127 +http://ipxe.org/cmd
  128 +
  129 +Credentials are managed as environment variables. These are described here:
  130 +
  131 +http://ipxe.org/cfg
  132 +
  133 +iPXE by default will put the CPU to rest when waiting for input. U-Boot does
  134 +not wake it up due to missing interrupt support. To avoid this behavior create
  135 +file src/config/local/nap.h.
  136 +
  137 + /* nap.h */
  138 + #undef NAP_EFIX86
  139 + #undef NAP_EFIARM
  140 + #define NAP_NULL
  141 +
  142 +The supported commands in iPXE are controlled by an include, too. Putting the
  143 +following 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)