1 How to netboot using ELILO
2 --------------------------
4 Copyright (C) 2002-2003 Hewlett-Packard Co.
5 Contributed by Stephane Eranian <eranian@hpl.hp.com>
6 Updated by Jason Fleischli <jason.fleischli@hp.com>
8 Last updated: 10/19/2009
10 x86_64 and uefi support was added @ elilo version 3.8 and linux kernel >= 2.6.24
12 EFI has full support for the PXE and DHCP protocol. As such
13 it is relatively easy to boot a machine from the network using EFI.
14 The elilo loader has full support for both PXE and DHCP, therefore
15 it is possible to download the elilo config file, the Linux kernel image
16 and the initial ramdisk from a remote server. There are many ways
17 netbooting can be configured but in this document we focus
18 only on two very common cases:
20 - netboot but use local root filesystem.
21 - booting a diskless machine, i.e., use a NFS root filesystem.
23 1/ How to get EFI to netboot?
25 You do not need any additional software to get EFI to start a netboot session.
26 Any EFI machine can be configured to start a PXE/DHCP session IF it has a network
27 adapter that has support for the UNDI/PXE protocol. Most modern cards do have such
30 To enable netbooting, you need to go into the EFI boot manager maintenance menu
31 and 'Add a boot option'. On the screen you see the list of devices to boot from.
32 At least one of them should be of the form:
34 Load File [Acpi(PNP0A03,0)/Pci(5|0)/Mac(00D0B7A6FC25)]
36 which represent Ethernet card (Mac address). If you don't have such option, it means that
37 you either do not have a network adapter in your machine or it does not have the
38 UNDI/PXE support in its option ROM.
40 You need to select this option and give it a logical name such as 'netboot', for instance.
41 Next, you leave the maintenance menu and go back to the main menu. You now have a new
42 boot menu option. If you select 'netboot' then EFI will start the PXE/DCHP discovery
43 request and look for a server to get an IP address.
45 On the server side, you can use a standard DHCP server, such as the one shipped on
46 Redhat7.2 (dhcpd) or a PXE server (not yet available for Linux, probably available for Windows).
47 In this document we show both options. You also need a TFTP server somewhere on the network,
48 it will be used to download the actual files.
51 2/ Netbooting using DHCP
53 There is nothing specific to EFI that needs to be set in the /etc/dhcpd.conf file.
54 Clearly the filename option must contains the path to the elilo.efi binary.
56 Elilo will auto-detect whether it was downloaded via PXE or DHCP and it will adapt
57 the kind of requests it makes to download the other files that it needs, such as
60 A simple dhcpd.conf file which uses fixed IP addresses could be as follows:
62 subnet 192.168.2.0 netmask 255.255.255.0 {
64 hardware ethernet 00:D0:B7:A6:FC:25;
65 fixed-address 192.168.2.10;
67 option domain-name "mydomain.com";
68 option host-name "test_machine";
69 option routers 192.168.2.1;
70 option subnet-mask 255.255.255.0;
75 For the tftp server, you need to make sure that it is ACTIVATED by inetd or xinetd depending
76 on your distribution. In most distributions, it is disabled by default for security reasons.
77 On distributions using xinetd, you need to check /etc/xinet.d/tftp. For inetd you need to
78 check /etc/inetd.conf. It is typical to have the root directory for tftp be /tftpboot but it
79 can be anything. In this document we will use /tftpboot as the root directory. The files
80 that we need are as follows:
82 - the elilo config file
84 - the initial ramdisk (optional)
87 a/ Location of the files in the tftp directory tree
89 For elilo version 3.3b or higher, it is possible to place the files listed above
90 in any subdirectory below the tftp root. Of course the dhcpd.conf file must
91 point to the location of elilo.efi and provide the path from the tftp root
94 Elilo will look for its config file, the kernel image, the initial ramdisk (optional)
95 only from the directory it was loaded from. This is useful when the same tftp server
96 is used to services many different kind of clients.
98 Here is a simple example, suppose the dhcpd.conf file contains the following definition:
100 subnet 192.168.2.0 netmask 255.255.255.0 {
102 hardware ethernet 00:D0:B7:A6:FC:25;
103 fixed-address 192.168.2.10;
105 filename "/rx6000/elilo.efi";
107 option domain-name "mydomain.com";
108 option host-name "test_machine";
109 option routers 192.168.2.1;
110 option subnet-mask 255.255.255.0;
115 Elilo will be downloaded from /tftpboot/rx6000. Then elilo will look
116 for all the other files it needs in /tftpboot/rx6000. This rule is
117 applied to all files, including the all the variation of the config
120 b/ Getting the config file
122 With DHCP, elilo will first try to download its configuration file. It will try
123 several file names and they are as follows:
126 where AABBCCDD is the hexadecimal representation of the IP address assigned to
127 the machine by DHCP. The hexadecimal string (AABBCCDD) MUST use upper case
130 This filename is an opportunity to specify a machine specific configuration file.
132 2) AA[BB[CC]][-ia32|ia64|x86_64].conf
133 As of version 3.5, elilo will also look for IPv4 class A,B,C
134 subnet-specific versions of the config file. This is useful when you
135 want to have a common config file for all machines connected to a
138 For example, if your IP address is 10.0.0.1 (0A000001 in hex), elilo
139 will look first for 0A000001.conf, then 0A0000.conf, then 0A00.conf,
142 Elilo will also try architecture-specific versions of subnet-specific
143 config files first (So for example, on an Itanium system,
144 "0A0000-ia64.conf" will be tried before "0A0000.conf")
146 3) elilo-ia32.conf, elilo-x86_64.conf, or elilo-ia64.conf
148 Depending on the machine (client side) architecture elilo will try the matching
149 architecture specific filename.
151 This filename is an opportunity to specify a architecture specific configuration file.
152 This distinction between the architectures is useful when the same TFTP server services
153 the three types of clients : ia32, x86_64, and ia64 machines.
157 All files use the same format. Elilo will stop at the first match. In case no file is found,
158 it will try to download a default kernel file name (vmlinux).
160 c/ Getting the kernel
162 The second request from elilo is typically the kernel image. The filename is based on what
163 is in the elilo config file. The path name depends on how the TFTP server is configured.
164 For security reasons it is customary to have the server do a change root in /tftpboot.
165 Hence filenames are relative to /tftpboot and therefore you don't need to specify it.
167 For instance if elilo.conf contains:
172 and the user selects linux-up, then elilo will request a filename of 'vmlinux.249'
173 which must therefore be in /tftpboot. Check the configuration of your TFTP server for
176 d/ Getting the initial ramdisk
178 This step is optional. It follows exactly the same naming rules explained for the kernel image.
179 The initial ramdisk file must therefore be somewhere under /tftpboot.
181 For instance if elilo.conf contains:
185 initrd=ramdisk/initrd.249
187 and the user selects linux-up, then elilo will request a filename of 'ramdisk/initrd.249'
188 which must therefore be under /tftpboot.
191 e/ Getting IP address information
193 When elilo is netbooted, the network filesystem module initializes some elilo variables
194 with the information it received from the DHCP server. At a minimum, it received the
197 The following information is stored in the elilo variables indicated below:
198 - assigned IP address -> %I
199 - assigned netmask -> %M
200 - assigned domainname -> %D
201 - assigned gateway -> %G
203 These variables can be used to dynamically adjust the command line arguments passed to the kernel.
204 See section 5/ below for an example.
206 3/ Netbooting using PXE
208 EFI has builtin support for PXE. In fact it first tries PXE and then default to DHCP
209 when it does not find a valid PXE server.
211 There is a PXE server package available from Linux/ia32 however this package does not
212 have the necessary extensions to talk to the EFI side, at least on IA-64 platforms.
214 There is no need for special options or compile time flags to get elilo to work
215 with PXE instead of standard DHCP. When netbooted, elilo will automatically detect
216 if it has been downloaded via PXE or DHCP and it will adujst how subsequent files
219 You need a special version of the DHCPD server developed by the Internet Software Consortium
220 (http://www.isc.org) with a special patch to add the PXE extensions. Unfortunately as of
221 version 3.0xx, the patch has not yet made it into the official tree. It is supposed to show
222 up in version 3.1 of the dhcpd server.
224 In any case, the elilo package contains a simple example of how you can configure the
225 /etc/dhcpd.conf file for a PXE-aware DHCP server using the extensions provided in the
226 patch. You can look in examples/dhcpd-pxe.conf. The syntax is very different from
227 a standard dhcpd server.
229 The key elements to keep in mind are the PXE layers used by elilo to request the different
232 Layer 0 : to get the name of the boot loader (elilo.efi)
233 Layer 1 : to get the name of the elilo config file
234 Layer 2 : to get the name of the kernel image
236 There is an IMPORTANT distinction between those layers. The first two (0,1) and requested
237 systematically whereas the last one is used only when the configuration file is not found, i.e.,
238 what is the default kernel to boot. The actual files are STILL downloaded via TFTP. Therefore
239 the TFTP server must also be configured (see previous section for more on this).
242 a/ Getting the config file
244 In this mode, elilo use the PXE layer 1 to get the config file to use. Therefore this must
245 be set on the server side. Elilo will use the following sequence when
246 looking for a config file:
248 - use the name provide by the PXE server Layer 1 or
250 - elilo-ia64.conf/elilo-ia32.conf/elilo-x86_64 or
254 Elilo stops at the first match. With PXE, elilo does not try to download a config file named after
255 the assigned IP address as it does for DHCP because there is enough flexibility in the PXE server
256 configuration to do this.
258 b/ Getting the kernel image
260 When there is no config file, elilo will use the kernel name returned by
261 PXE layer 2. If it is not specified there, then it default to 'vmlinux'.
263 c/ Getting the initial ramdisk
265 The filename for the ramdisk MUST come from the config file. Elilo does not use a PXE layer
266 to ask for a default name.
268 d/ Getting IP address information
270 When elilo is netbooted, the network filesystem module initializes some elilo variables
271 with the information it received from the DHCP server. At a minimum, it received the
274 The following information is stored in the variables indicated below:
275 - assigned IP address -> %I
276 - assigned netmask -> %M
277 - assigned domainname -> %D
278 - assigned gateway -> %G
280 These variables can be used to dynamically adjust the command line arguments passed to the kernel.
281 See section 5/ below for an example of how to use the variable.
284 4/ Netbooting and using a local root filesystem
286 This is the simplest configuration where the boot loader, its config file, the kernel
287 and its optional initial ramdisk are downloaded from the network BUT the kernel uses
288 the local disk for its root filesystem.
290 For such configuration there is no special option necessary in the elilo config file.
291 You simply need to specify which partition is the root partition. A typical elilo.conf
292 would look as follows:
297 initrd=ramdisk/initrd.249
299 5/ Netbooting a diskless machine
301 In this configuration we do not use the local machine's disks but instead rely on
302 a remote server to provide the root filesystem via NFS.
306 By default most kernels shipped by distributors do not have the support
307 compiled in for such configuration. This means that you need to recompile
308 your own kernel. For instance, vmlinuz-2.4.9 as shipped in Redhat7.2 on
309 both ia32 and ia64 platforms does not have the support builtin.
311 To get this configuration to work, you need to have a kernel compiled
312 such that it accepts a root filesystem over NFS (CONFIG_ROOT_NFS). This
313 necessitates that the network stack be configured with the, so called,
314 IP plug-and-play support (CONFIG_IP_PNP).
316 b/ On the server side
319 - a NFS file server to provide the root filesystem.
320 - a DHCP/PXE server to get the IP address and download the boot loader.
322 Note that both do not need to be on the same machine. There is no special
323 DHCP/PXE configuration option required to get this working. All you need
324 is a kernel compiled with the options mentioned in a/. You also need to
325 make sure that the permission on the NFS server are set appropriately
326 to allow root access from the client machine (no_root_squash), see
327 man 'exports' for more on this.
329 c/ The elilo configuration file
331 To boot successfully, the kernel needs to:
332 - get an IP address and related networking parameters
333 - contact the NFS server to get its root filesystem
335 The 2.4.x kernel series provides several options to get the IP address:
336 - it can do an internal DHCP request (CONFIG_IP_PNP_DHCP)
337 - it can do an internal RARP request (CONFIG_IP_PNP_RARP)
338 - it can do an internal BOOTP request (CONFIG_IP_PNP_BOOTP)
339 - it can get the IP address from the command line
341 The choice is up to you but it is a little bit stupid to go through a
342 DHCP/BOOTP/RARP phase again when this is already done by the EFI firmware.
343 So in this document, we describe how you can pass the information provided
344 by EFI on the command line of the kernel.
346 The syntax used to pass IP information on the command line is described in
347 the kernel source tree in Documentation/nfsroot.txt. The option is called
348 "ip=" and has the following syntax:
350 ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>
352 To designate the NFS server, you must use the "nfsroot=" option. It has the
354 nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]
356 Depending on how you want your system configured you can hardcode the
357 values of the parameters in the elilo configuration file. For instance:
361 description="kernel with NFS root"
362 append="root=/dev/nfs nfsroot=192.168.2.22:/ia64_rootfs ip=192.168.2.5::192.168.2.1:255.255.255.0:test_machine:eth0:on"
364 Note the root=/dev/nfs indicates that the root filesystem is over NFS.
366 This example works fine however, it is not very flexible because the IP
367 address, the gateway, netmask and hostname are fixed and do not used the
368 values EFI used to download the boot loader and the kernel.
370 Elilo provides a way to dynamically customize the parameters passed on the
371 command line using substitution variables. We describe those variables in
372 elilovar.txt. The basic idea is to allow the parameters to use the dynamic
373 information obtained by the DHCP/PXE phase.
375 The network support in elilo defines several variables which contained
376 network related information produced by the DHCP/PXE phase. The set of
378 %I -> the IP address obtained by DHCP/PXE
379 %M -> the netmask obtained by DHCP/PXE
380 %G -> the gateway obtained by DHCP/PXE
381 %H -> the hostname obtained by DHCP/PXE
382 %D -> the domain name obtained by DHCP/PXE
384 So, the configuration file can then be customized as follows:
387 description="kernel with NFS root"
388 append="root=/dev/nfs nfsroot=192.168.2.22:/ia64_rootfs ip=%I::%G:%M:%H:eth0:on"
390 Not all parameters are necessary or even used by the kernel or the user level
391 configuration scripts. There is no variable to substitute the NFS server or
392 the mount point on that server.
395 In the case of a DHCP boot, this type of customization makes sense only for
396 the shared configuration file, elilo-ia64.conf/elilo-ia32.conf/elilo-x86_64 or elilo.conf.
397 The configuration file based on the IP address (such as C0A80205.conf in this
398 case) would provide another way of customizing parameters for a specific
399 client (IP address). The same thing holds if the name of the config file
400 returned by the PXE server is specific to a client.
405 More information on the PXE protocol can be found at the following web site:
407 http://developer.intel.com/ial/wfm/
409 The source code for the standard and (possibly) PXE-enhanced DHCPD can be