current/SOURCES/elilo.txt

        --------------------------------------------------------------------
        ELILO.EFI: Linux boot loader for EFI/IA-64 and EFI/IA-32 based systems
        --------------------------------------------------------------------
                       Stephane Eranian <eranian@hpl.hp.com>

                                 August 2002

                   Copyright (C) 2000-2002 Hewlett-Packard Co.


I/ Introduction
   ------------

This document describes how to use ELILO on for both IA-64 and IA-32 EFI-based platforms.
This document describes ELILO version 3.3a. 

II/ Command line options
    --------------------

        elilo [-hDpPVva] [-d nsec] [-C config] [-i initrd] [kernel [kernel options...]]

        -h      Display a list of all possible command line options.

        -V      Print the version number and exit.

        -d nsec Specify the number of 10th of seconds before loading the
                kernel.

        -C file Specify the config file to use. The default is elilo.conf

        -P      Verify config file syntax only. this option causes ELILO to 
                parse the config file and generate a report on the console.
                No kernel is loaded.

        -v      Turn on verbose mode. ELILO prints more message about what it 
                is doing. For each occurrence of this option the verbosity level
                is increased by one. The maximum level is 5.

        -a      Always check for alternate kernel image. The default behavior
                of ELILO is to NOT look for an alternate image. This 
                option overrides this behavior and ELILO is checking for 
                alternate images no matter what. Alternate images are
                specified using the EliloAlt EFI variable.

        -p      force interactive prompt mode. Valid when no kernel image is 
                specified on the command line.

        -D      print debug output.

        -E      don't force EDD30 variable to TRUE when FALSE.

        -i file Use file as the initial ramdisk (boot strapping system).

        -c name Specify which kernel chooser to use.  Default is 'simple', and
                the only other choice at present is 'textmenu'.

        In addition, elilo supports platform specific options:

        For IA-64:
        ----------
                -r      the kernel image can be relocated if initial load address is not
                        available. This options requires a special version of the kernel.

                -F file will try to load the FPSWA driver indicated by 'file'. Only this file
                        will be attempted. When no specific file is given, elilo will try
                        loading \efi\intel firmware\fpswa.efi from all accessible EFI system
                        partitions.
        For IA-32:
        ----------
                no option defined.

        All file names (including the kernel file) can include a device name using the 
        following syntax:

                dev_name:/path/to/my/kernel

        The 'dev_name' component depends on the naming scheme selected and the detected
        devices for your system.  Some choosers may print the information automatically
        or on demand, see chooser specific documentation for more on this. See README.devschemes 
        for more information on device naming schemes. The slash character '/' can be used as 
        a directory separator on any file systems including the EFI file system (FAT32).


III/ Configuration File
     ------------------

     ELILO supports a config file with options similar to the LILO/x86 boot loader.

     Elilo will use the following sequence (shown in order) when looking for its config 
     file when none is specified on the command line:

        1/ AABBCCDD.conf (netbooting with regular DHCP)
           where AABBCCDD is the hexadecimal representation
           of the IP address assigned during the DHCP phase.

        2/ elilo-ia64.conf or elilo-ia32.conf
           The choice depends on the client platform. This step allows
           the same DHCP/PXE server to provide files for both types of clients.

        3/ elilo.conf

     Unless explicitly specified on the command line, elilo looks for its config file ONLY 
     on the device it was loaded from.
     
     The configuration file is an ASCII file and not a UNICODE file.

     The config file contains addition options to change the behavior of the loader. 
     If the same option is specified in the config file AND on the command line, the
     latter takes precedence. Not all options available in the config file have an 
     equivalent command line option.

     When elilo is invoked with the -h option, it prints the list of support command line
     options but also the list of config file options. For each option it also prints
     the type of data expected.

     The config file options are divided in 2 groups:


        - image options which are specific to a particular kernel image. Each kernel image
          must be identified with a logical name called a label. 

        - global options which affect the behavior of ELILO and apply to all images.

     The ELILO config file follows the LILO/x86 syntax. First come the global
     options, then the list of images and options for each of them, if
     necessary. At least one image MUST be defined and it is possible to have
     an empty list of global options.

     Options have types. Three types are defined:
        - boolean: set or not set
        - string : a string of characters which can be quoted if necessary
        - number (in decimal) 
        - filename: a string interpreted as a file name

    
    The config file supports the following options:

    Global Options:
    ---------------
    default=value       Name the default image to boot. If not defined ELILO
                        will boot the first defined image.

    timeout=number      The number of 10th of seconds to wait while in
                        interactive mode before auto booting default kernel.
                        Default is infinity.

    delay=number        The number of 10th of seconds to wait before
                        auto booting when not in interactive mode. 
                        Default is 0.
   
    prompt              Force interactive mode

    verbose=number      Set level of verbosity [0-5]. Default 0 (no verbose)

    root=filename       Set global root filesystem for Linux/ia64

    read-only           Force root filesystem to be mounted read-only

    append=string       Append a string of options to kernel command line

    initrd=filename     Name of initrd file

    image=filename      Define a new image

    chooser=name        Specify kernel chooser to use: 'simple' or 'textmenu'.

    message=filename    a message that is printed on the main screen if supported by 
                        the chooser.

    fX=filename         Some choosers may take advantage of this option to
                        display the content of a file when a certain function
                        key X is pressed. X can vary from 1-12 to cover 
                        function keys F1 to F12.

    noedd30             do not force the EDD30 EFI variable to TRUE when FALSE. In other
                        words, don't force the EDD30 mode if not set.

    Image options:
    --------------
    root=filename       Set root filesystem for kernel

    read-only           Force root filesystem to be mounted read-only

    append=string       Append a string of options to kernel command line

    initrd=filename     Name of initrd file

    label=string        Logical name of image (used in interactive mode)

    description=string  One line text description of the image.

    IA-64 specific options:
    -----------------------

    Global options:
    ---------------
    fpswa=file          Specify the filename for a specific FPSWA to load. 
                        If this option is used then no other file will be tried.

    relocatable         In case of memory allocation error at initial load point of
                        kernel, allow attempt to relocate (assume kernels is relocatable)

    Image options:
    --------------
    relocatable         In case of memory allocation error at initial load point of
                        kernel, allow attempt to relocate (assume this kernel is relocatable)

    IA-32 specific options:
    -----------------------
    legacy-free         Indicate that the host machine does not have a legacy BIOS at all.


    The user can specify a kernel and related kernel options using the image label. Alternatively,
    the user can also specify a kernel file that is not specified in the config file. In any case,
    some of the global options (such as append) are always concatenated to whatever the user type.


IV/ Booting from the local system
    -----------------------------

    The elilo.efi binary must be in an EFI system partition (FAT32). The config
    file, kernel image, and optional initrd ramdisk can be on the same partition
    or even another EFI partition. Alternatively, they can also be in an ext2fs
    partition (if ext2fs support is compiled in elilo). In the following discussion
    we assume that all files are on the same EFI partition which is recognized
    by the EFI shell (nshell) as fs0. The kernel and initrd can be copied from the any 
    linux filesystems to the EFI partition using either the mtools (mcopy) or by mounting 
    the EFI partition as a vfat partition. However you do not really need this because
    most linux distributions install both files in the EFI partition and mount this partition
    in /boot/efi.

    To boot a kernel, simply power cycle the machine. Once you get to the EFI
    shell prompt, change to the filesystem that maps to the partition where elilo is.

        Shell> fs0:
        fs0:\>

        You might need to make sure that the Shell Path is set such that it will load
        ELILO from fs0:. You can verify this by typing:
        fs0:\> set
        path : fs0:\
        
        At this point you can invoke ELILO:

        fs0:\> elilo

        If there is no config file, then it will: 
                - pick up the kernel image named vmlinux if it exists, otherwise it will abort.
                - pass no argument to the kernel.
        
        You can specify the kernel image and its options on the command line.
        For instance you can do:

        fs0:\> elilo vmlinux root=/dev/sda5

        You can specify as many parameters as you want. The syntax follows the kernel
        rule, i.e., list of value pairs (or even single values) separated by space.
        A more complicated example would be:

        fs0:\> elilo -i initrd-2.4.9 vmlinuz-2.4.9 root=/dev/sda2 console=tty0 console=ttyS0,115200n8


    In the case a config file is found, then elilo will behaves according to
    the options in that file. However if elilo is invoked with command line options, they
    will be combined or they will override (if conflicting) what is defined in the config file.

    As of version 3.3, elilo is fully compliant with the EFI specification (1.10) with regards
    to where the bootloader (elilo.efi) must be located in the EFI system partition. In 
    section 11.2.1.3 of the EFI1.10 specification, it is said that in order to avoid conflicts
    between various loaders for various OSes or distributions of the same OS, every vendor MUST
    use a dedicated directory: \EFI\vendor\. The bootloader must be placed in this directory.
    This as always been possible as this is a matter of creating the directory and copying
    elilo.efi in it. However up until version 3.3, elilo would look for its config  file
    and kernel/initrd in the root (/) of the partition it was loaded from. As of version 3.3,
    elilo will now ONLY look for its configuration file FROM THE DIRECTORY IT WAS LOADED FROM. The
    same applies to the kernel and initrd files. Let us look at a simple example:

        - suppose elilo.efi is in \EFI\DIST if fs0:  (for the EFI Shell)

        - if you invoke elilo as follows:

                fs0:\> \efi\dist\elilo -v -p
                default file path: \efi\dist\
                config file      : \efi\dist\elilo.conf
                ELILO boot: 


          Note that this is the same if you invoke elilo directly from \efi or \efi\dist.
 
    File references in the configuration file are treated as relative to the directory
    elilo was loaded from except if they use an absolute path. 

   Note that this behavior ONLY applies to local boot. Network booting remains unchanged
   as it can be configured completely from the dhcpd.conf file.

V/ Interactive mode
   ----------------

   Elilo can be forced into interactive mode using the "prompt" option in the config
   file or with the -p option. In this mode, the user can select a kernel to load.

   The interface depends on the chooser, it may be a simple command line prompt as provided
   by the simple chooser or a more sophisticated screen with scroll menus as provided by
   textmenu. Most choosers depends on the elilo config file to get the information they
   display. The simple chooser can operated without the elilo config file. However it
   is always better to have this file, to create handy logical names for each possible
   boot choices. The logical names are specified with the "label" option in the config
   file. They represent a specific kernel "image" and its specific options.

   In elilo, the user can select a particular kernel image using the corresponding label
   name. A simple example is as follows:

      If we suppose that the following is defined in elilo.conf:

        image=vmlinuz-2.4.9
        label=linux-up
        initrd=initrd-2.4.9
        root=/dev/sda2
        append="console=tty0 console=ttyS0,115200n8"

      then the user can specify linux-up at the prompt and elilo will load the 
      vmlinuz-2.4.9 kernel file and the initrd-2.4.9 ramdisk and will pass 

         "root=/dev/sda2 console=tty0 console=ttyS0,115200n8"

      as command line arguments to the kernel.

      This behavior is identical to Lilo/x86. However, elilo further allows the user
      to specify actual kernel files names as well, i.e., kernels that are not defined
      in the configuration file. If we reuse the above example and the simple chooser, 
      the user can type:

      ELILO boot: vmlinux-2.4.18 root=/dev/sda2

      and elilo will boot the vmlinuz-2.4.18 kernel if it exists.

VI/ The alternate kernel image
    --------------------------

    Oftentimes when debugging kernels you want to reboot the machine once with
    your test kernel and, if something goes wrong, you want to fall back to a more
    stable kernel. In addition you want to be able to do this from a remote machine. 
    Many things can go wrong when doing kernel debugging. It could be that you don't
    even reach user-mode. In this case however, you still want to fall back to
    a stable kernel. The feature you'd like from a boot loader is 'boot once and
    then fall back to safe kernel'.

    Elilo offers this feature and it's called 'alternate kernel image'.  
    You can configure elilo to load a kernel only once and then whatever 
    happens the next reboot falls back to a different kernel hopefully more stable.

    To do this, elilo relies on an EFI variable called 'EliloAlt' with a NULL GUID.
    The content of this variable is a UNICODE string containing the kernel file name
    and its command line options.

    When the -a option is specified on the command line or if the "checkalt" option
    is present in the config file, elilo will check for the presence of this variable.
    If found and the content is a valid UNICODE string, elilo will use it as the kernel
    to boot. There is no verification made on the validity of the kernel name or options.
    Then the variable is deleted. If the variable is rejected because it does not look
    sane, it is also deleted.

    The variable can be set from a running Linux system using the /proc/efi/vars
    interface. In the tools directory of this package, there is a Linux tool called
    elilovar which can be used to create, modify, print, and delete the EliloAlt
    variable. Refer to eliloalt.txt for more information on this tool.

VII/ Auto booting the machine
     -----------------------

    Once you're satisfied with your machine setup, it is good to install an 
    auto boot procedure.  You have two options to do this:
        - from the EFI boot manager menu
        - from the EFI shell

    The first option is preferred and is used by most Linux distributions.
    Elilo can be invoked directly from the boot manager. You need to get into
    the 'boot maintenance' menu and use load file a file. This can be tedious
    so instead it is recommended that you use a Linux tool called efibootmgr
    which is also shipped in most distributions. With this tool, you can
    create your own boot option and change the boot order.

    
    The second approach use the EFI shell and a shell script with a special name: 'startup.nsh'.

    When the system boots, it looks for EFI partitions and if it finds
    a 'startup.nsh' file in ANY of these it will jumpstart execution from it.

    So the typical way of auto booting your Linux/ia64 system is to simply create
    such a file with the following content:

        # cat /boot/startup.nsh
        elilo vmlinuz root=/dev/sda2

    Of course, this can be simplified if there is a configuration file.


VII/ Netbooting 
     ----------

     Please refer to netbooting.txt for a complete description of how to boot
     from the network.


XII/ Booting on EFI/ia32 platforms
     -----------------------------

        Until PC comes with the EFI firmware built in, you need to boot from a
        floppy that has the EFI firmware on it. Such floppy can be
        constructed from the EFI sample implementation and toolkit that is
        available from the Intel Developer Web site at:

                http://developer.intel.com/technology/efi/

        To use elilo on IA-32, you can put it on a floppy and
        on a FAT32 partition (msdos partition). You can also
        netbooting if you network adapter has support for UNDI/PXE.

        Elilo/ia32 is capable of booting unmodified 2.2.x. and 2.4.x kernels
        as they are shipped by distributors today (such as Redhat7.2). You don't need 
        to recompile the kernel with special options. Elilo ONLY takes compressed kernel
        image which are typically obtained via a 'make bzImage'. Plain elf/32 kernel can't 
        be booted (plain vmlinux will not work). Similarly, existing initial ramdisks can 
        be used without modifications. 

IX/ Credits
    -------

        Intel Corp.
        Stephane Eranian <eranian@hpl.hp.com>
        David Mosberger  <davidm@hpl.hp.com>
        Johannes Erdfelt <jerdfelt@valinux.com>
        Richard Hirst    <rhirst@linuxcare.com>
        Chris Ahna       <christopher.j.ahna@intel.com>
        Mike Johnston    <michael.johnston@intel.com>

X/ Bug reports
   -----------

        You can submit bugs to <eranian@hpl.hp.com> or to the Linux/ia64
        mailing list at linux-ia64@linuxia64.org. Visit http://www.linuxia64.org
        to subscribe to this list.

XIII/ Reference
      ---------

        EFI v1.02 specifications are available from the following web site:

        http://developer.intel.com/technology/efi/

        The latest sources of ELILO can be downloaded at:

                ftp://ftp.hpl.hp.com/pub/linux-ia64

1	--------------------------------------------------------------------
2	ELILO.EFI: Linux boot loader for EFI/IA-64 and EFI/IA-32 based systems
3	--------------------------------------------------------------------
4	Stephane Eranian <eranian@hpl.hp.com>
5
6	August 2002
7
8	Copyright (C) 2000-2002 Hewlett-Packard Co.
9
10
11	I/ Introduction
12	------------
13
14	This document describes how to use ELILO on for both IA-64 and IA-32 EFI-based platforms.
15	This document describes ELILO version 3.3a.
16
17	II/ Command line options
18	--------------------
19
20	elilo [-hDpPVva] [-d nsec] [-C config] [-i initrd] [kernel [kernel options...]]
21
22	-h Display a list of all possible command line options.
23
24	-V Print the version number and exit.
25
26	-d nsec Specify the number of 10th of seconds before loading the
27	kernel.
28
29	-C file Specify the config file to use. The default is elilo.conf
30
31	-P Verify config file syntax only. this option causes ELILO to
32	parse the config file and generate a report on the console.
33	No kernel is loaded.
34
35	-v Turn on verbose mode. ELILO prints more message about what it
36	is doing. For each occurrence of this option the verbosity level
37	is increased by one. The maximum level is 5.
38
39	-a Always check for alternate kernel image. The default behavior
40	of ELILO is to NOT look for an alternate image. This
41	option overrides this behavior and ELILO is checking for
42	alternate images no matter what. Alternate images are
43	specified using the EliloAlt EFI variable.
44
45	-p force interactive prompt mode. Valid when no kernel image is
46	specified on the command line.
47
48	-D print debug output.
49
50	-E don't force EDD30 variable to TRUE when FALSE.
51
52	-i file Use file as the initial ramdisk (boot strapping system).
53
54	-c name Specify which kernel chooser to use. Default is 'simple', and
55	the only other choice at present is 'textmenu'.
56
57	In addition, elilo supports platform specific options:
58
59	For IA-64:
60	----------
61	-r the kernel image can be relocated if initial load address is not
62	available. This options requires a special version of the kernel.
63
64	-F file will try to load the FPSWA driver indicated by 'file'. Only this file
65	will be attempted. When no specific file is given, elilo will try
66	loading \efi\intel firmware\fpswa.efi from all accessible EFI system
67	partitions.
68	For IA-32:
69	----------
70	no option defined.
71
72	All file names (including the kernel file) can include a device name using the
73	following syntax:
74
75	dev_name:/path/to/my/kernel
76
77	The 'dev_name' component depends on the naming scheme selected and the detected
78	devices for your system. Some choosers may print the information automatically
79	or on demand, see chooser specific documentation for more on this. See README.devschemes
80	for more information on device naming schemes. The slash character '/' can be used as
81	a directory separator on any file systems including the EFI file system (FAT32).
82
83
84	III/ Configuration File
85	------------------
86
87	ELILO supports a config file with options similar to the LILO/x86 boot loader.
88
89	Elilo will use the following sequence (shown in order) when looking for its config
90	file when none is specified on the command line:
91
92	1/ AABBCCDD.conf (netbooting with regular DHCP)
93	where AABBCCDD is the hexadecimal representation
94	of the IP address assigned during the DHCP phase.
95
96	2/ elilo-ia64.conf or elilo-ia32.conf
97	The choice depends on the client platform. This step allows
98	the same DHCP/PXE server to provide files for both types of clients.
99
100	3/ elilo.conf
101
102	Unless explicitly specified on the command line, elilo looks for its config file ONLY
103	on the device it was loaded from.
104
105	The configuration file is an ASCII file and not a UNICODE file.
106
107	The config file contains addition options to change the behavior of the loader.
108	If the same option is specified in the config file AND on the command line, the
109	latter takes precedence. Not all options available in the config file have an
110	equivalent command line option.
111
112	When elilo is invoked with the -h option, it prints the list of support command line
113	options but also the list of config file options. For each option it also prints
114	the type of data expected.
115
116	The config file options are divided in 2 groups:
117
118
119	- image options which are specific to a particular kernel image. Each kernel image
120	must be identified with a logical name called a label.
121
122	- global options which affect the behavior of ELILO and apply to all images.
123
124	The ELILO config file follows the LILO/x86 syntax. First come the global
125	options, then the list of images and options for each of them, if
126	necessary. At least one image MUST be defined and it is possible to have
127	an empty list of global options.
128
129	Options have types. Three types are defined:
130	- boolean: set or not set
131	- string : a string of characters which can be quoted if necessary
132	- number (in decimal)
133	- filename: a string interpreted as a file name
134
135
136	The config file supports the following options:
137
138	Global Options:
139	---------------
140	default=value Name the default image to boot. If not defined ELILO
141	will boot the first defined image.
142
143	timeout=number The number of 10th of seconds to wait while in
144	interactive mode before auto booting default kernel.
145	Default is infinity.
146
147	delay=number The number of 10th of seconds to wait before
148	auto booting when not in interactive mode.
149	Default is 0.
150
151	prompt Force interactive mode
152
153	verbose=number Set level of verbosity [0-5]. Default 0 (no verbose)
154
155	root=filename Set global root filesystem for Linux/ia64
156
157	read-only Force root filesystem to be mounted read-only
158
159	append=string Append a string of options to kernel command line
160
161	initrd=filename Name of initrd file
162
163	image=filename Define a new image
164
165	chooser=name Specify kernel chooser to use: 'simple' or 'textmenu'.
166
167	message=filename a message that is printed on the main screen if supported by
168	the chooser.
169
170	fX=filename Some choosers may take advantage of this option to
171	display the content of a file when a certain function
172	key X is pressed. X can vary from 1-12 to cover
173	function keys F1 to F12.
174
175	noedd30 do not force the EDD30 EFI variable to TRUE when FALSE. In other
176	words, don't force the EDD30 mode if not set.
177
178	Image options:
179	--------------
180	root=filename Set root filesystem for kernel
181
182	read-only Force root filesystem to be mounted read-only
183
184	append=string Append a string of options to kernel command line
185
186	initrd=filename Name of initrd file
187
188	label=string Logical name of image (used in interactive mode)
189
190	description=string One line text description of the image.
191
192	IA-64 specific options:
193	-----------------------
194
195	Global options:
196	---------------
197	fpswa=file Specify the filename for a specific FPSWA to load.
198	If this option is used then no other file will be tried.
199
200	relocatable In case of memory allocation error at initial load point of
201	kernel, allow attempt to relocate (assume kernels is relocatable)
202
203	Image options:
204	--------------
205	relocatable In case of memory allocation error at initial load point of
206	kernel, allow attempt to relocate (assume this kernel is relocatable)
207
208	IA-32 specific options:
209	-----------------------
210	legacy-free Indicate that the host machine does not have a legacy BIOS at all.
211
212
213	The user can specify a kernel and related kernel options using the image label. Alternatively,
214	the user can also specify a kernel file that is not specified in the config file. In any case,
215	some of the global options (such as append) are always concatenated to whatever the user type.
216
217
218	IV/ Booting from the local system
219	-----------------------------
220
221	The elilo.efi binary must be in an EFI system partition (FAT32). The config
222	file, kernel image, and optional initrd ramdisk can be on the same partition
223	or even another EFI partition. Alternatively, they can also be in an ext2fs
224	partition (if ext2fs support is compiled in elilo). In the following discussion
225	we assume that all files are on the same EFI partition which is recognized
226	by the EFI shell (nshell) as fs0. The kernel and initrd can be copied from the any
227	linux filesystems to the EFI partition using either the mtools (mcopy) or by mounting
228	the EFI partition as a vfat partition. However you do not really need this because
229	most linux distributions install both files in the EFI partition and mount this partition
230	in /boot/efi.
231
232	To boot a kernel, simply power cycle the machine. Once you get to the EFI
233	shell prompt, change to the filesystem that maps to the partition where elilo is.
234
235	Shell> fs0:
236	fs0:\>
237
238	You might need to make sure that the Shell Path is set such that it will load
239	ELILO from fs0:. You can verify this by typing:
240	fs0:\> set
241	path : fs0:\
242
243	At this point you can invoke ELILO:
244
245	fs0:\> elilo
246
247	If there is no config file, then it will:
248	- pick up the kernel image named vmlinux if it exists, otherwise it will abort.
249	- pass no argument to the kernel.
250
251	You can specify the kernel image and its options on the command line.
252	For instance you can do:
253
254	fs0:\> elilo vmlinux root=/dev/sda5
255
256	You can specify as many parameters as you want. The syntax follows the kernel
257	rule, i.e., list of value pairs (or even single values) separated by space.
258	A more complicated example would be:
259
260	fs0:\> elilo -i initrd-2.4.9 vmlinuz-2.4.9 root=/dev/sda2 console=tty0 console=ttyS0,115200n8
261
262
263	In the case a config file is found, then elilo will behaves according to
264	the options in that file. However if elilo is invoked with command line options, they
265	will be combined or they will override (if conflicting) what is defined in the config file.
266
267	As of version 3.3, elilo is fully compliant with the EFI specification (1.10) with regards
268	to where the bootloader (elilo.efi) must be located in the EFI system partition. In
269	section 11.2.1.3 of the EFI1.10 specification, it is said that in order to avoid conflicts
270	between various loaders for various OSes or distributions of the same OS, every vendor MUST
271	use a dedicated directory: \EFI\vendor\. The bootloader must be placed in this directory.
272	This as always been possible as this is a matter of creating the directory and copying
273	elilo.efi in it. However up until version 3.3, elilo would look for its config file
274	and kernel/initrd in the root (/) of the partition it was loaded from. As of version 3.3,
275	elilo will now ONLY look for its configuration file FROM THE DIRECTORY IT WAS LOADED FROM. The
276	same applies to the kernel and initrd files. Let us look at a simple example:
277
278	- suppose elilo.efi is in \EFI\DIST if fs0: (for the EFI Shell)
279
280	- if you invoke elilo as follows:
281
282	fs0:\> \efi\dist\elilo -v -p
283	default file path: \efi\dist\
284	config file : \efi\dist\elilo.conf
285	ELILO boot:
286
287
288	Note that this is the same if you invoke elilo directly from \efi or \efi\dist.
289
290	File references in the configuration file are treated as relative to the directory
291	elilo was loaded from except if they use an absolute path.
292
293	Note that this behavior ONLY applies to local boot. Network booting remains unchanged
294	as it can be configured completely from the dhcpd.conf file.
295
296	V/ Interactive mode
297	----------------
298
299	Elilo can be forced into interactive mode using the "prompt" option in the config
300	file or with the -p option. In this mode, the user can select a kernel to load.
301
302	The interface depends on the chooser, it may be a simple command line prompt as provided
303	by the simple chooser or a more sophisticated screen with scroll menus as provided by
304	textmenu. Most choosers depends on the elilo config file to get the information they
305	display. The simple chooser can operated without the elilo config file. However it
306	is always better to have this file, to create handy logical names for each possible
307	boot choices. The logical names are specified with the "label" option in the config
308	file. They represent a specific kernel "image" and its specific options.
309
310	In elilo, the user can select a particular kernel image using the corresponding label
311	name. A simple example is as follows:
312
313	If we suppose that the following is defined in elilo.conf:
314
315	image=vmlinuz-2.4.9
316	label=linux-up
317	initrd=initrd-2.4.9
318	root=/dev/sda2
319	append="console=tty0 console=ttyS0,115200n8"
320
321	then the user can specify linux-up at the prompt and elilo will load the
322	vmlinuz-2.4.9 kernel file and the initrd-2.4.9 ramdisk and will pass
323
324	"root=/dev/sda2 console=tty0 console=ttyS0,115200n8"
325
326	as command line arguments to the kernel.
327
328	This behavior is identical to Lilo/x86. However, elilo further allows the user
329	to specify actual kernel files names as well, i.e., kernels that are not defined
330	in the configuration file. If we reuse the above example and the simple chooser,
331	the user can type:
332
333	ELILO boot: vmlinux-2.4.18 root=/dev/sda2
334
335	and elilo will boot the vmlinuz-2.4.18 kernel if it exists.
336
337	VI/ The alternate kernel image
338	--------------------------
339
340	Oftentimes when debugging kernels you want to reboot the machine once with
341	your test kernel and, if something goes wrong, you want to fall back to a more
342	stable kernel. In addition you want to be able to do this from a remote machine.
343	Many things can go wrong when doing kernel debugging. It could be that you don't
344	even reach user-mode. In this case however, you still want to fall back to
345	a stable kernel. The feature you'd like from a boot loader is 'boot once and
346	then fall back to safe kernel'.
347
348	Elilo offers this feature and it's called 'alternate kernel image'.
349	You can configure elilo to load a kernel only once and then whatever
350	happens the next reboot falls back to a different kernel hopefully more stable.
351
352	To do this, elilo relies on an EFI variable called 'EliloAlt' with a NULL GUID.
353	The content of this variable is a UNICODE string containing the kernel file name
354	and its command line options.
355
356	When the -a option is specified on the command line or if the "checkalt" option
357	is present in the config file, elilo will check for the presence of this variable.
358	If found and the content is a valid UNICODE string, elilo will use it as the kernel
359	to boot. There is no verification made on the validity of the kernel name or options.
360	Then the variable is deleted. If the variable is rejected because it does not look
361	sane, it is also deleted.
362
363	The variable can be set from a running Linux system using the /proc/efi/vars
364	interface. In the tools directory of this package, there is a Linux tool called
365	elilovar which can be used to create, modify, print, and delete the EliloAlt
366	variable. Refer to eliloalt.txt for more information on this tool.
367
368	VII/ Auto booting the machine
369	-----------------------
370
371	Once you're satisfied with your machine setup, it is good to install an
372	auto boot procedure. You have two options to do this:
373	- from the EFI boot manager menu
374	- from the EFI shell
375
376	The first option is preferred and is used by most Linux distributions.
377	Elilo can be invoked directly from the boot manager. You need to get into
378	the 'boot maintenance' menu and use load file a file. This can be tedious
379	so instead it is recommended that you use a Linux tool called efibootmgr
380	which is also shipped in most distributions. With this tool, you can
381	create your own boot option and change the boot order.
382
383
384
385	The second approach use the EFI shell and a shell script with a special name: 'startup.nsh'.
386
387	When the system boots, it looks for EFI partitions and if it finds
388	a 'startup.nsh' file in ANY of these it will jumpstart execution from it.
389
390	So the typical way of auto booting your Linux/ia64 system is to simply create
391	such a file with the following content:
392
393	# cat /boot/startup.nsh
394	elilo vmlinuz root=/dev/sda2
395
396	Of course, this can be simplified if there is a configuration file.
397
398
399	VII/ Netbooting
400	----------
401
402	Please refer to netbooting.txt for a complete description of how to boot
403	from the network.
404
405
406	XII/ Booting on EFI/ia32 platforms
407	-----------------------------
408
409	Until PC comes with the EFI firmware built in, you need to boot from a
410	floppy that has the EFI firmware on it. Such floppy can be
411	constructed from the EFI sample implementation and toolkit that is
412	available from the Intel Developer Web site at:
413
414	http://developer.intel.com/technology/efi/
415
416	To use elilo on IA-32, you can put it on a floppy and
417	on a FAT32 partition (msdos partition). You can also
418	netbooting if you network adapter has support for UNDI/PXE.
419
420	Elilo/ia32 is capable of booting unmodified 2.2.x. and 2.4.x kernels
421	as they are shipped by distributors today (such as Redhat7.2). You don't need
422	to recompile the kernel with special options. Elilo ONLY takes compressed kernel
423	image which are typically obtained via a 'make bzImage'. Plain elf/32 kernel can't
424	be booted (plain vmlinux will not work). Similarly, existing initial ramdisks can
425	be used without modifications.
426
427	IX/ Credits
428	-------
429
430	Intel Corp.
431	Stephane Eranian <eranian@hpl.hp.com>
432	David Mosberger <davidm@hpl.hp.com>
433	Johannes Erdfelt <jerdfelt@valinux.com>
434	Richard Hirst <rhirst@linuxcare.com>
435	Chris Ahna <christopher.j.ahna@intel.com>
436	Mike Johnston <michael.johnston@intel.com>
437
438	X/ Bug reports
439	-----------
440
441	You can submit bugs to <eranian@hpl.hp.com> or to the Linux/ia64
442	mailing list at linux-ia64@linuxia64.org. Visit http://www.linuxia64.org
443	to subscribe to this list.
444
445	XIII/ Reference
446	---------
447
448	EFI v1.02 specifications are available from the following web site:
449
450	http://developer.intel.com/technology/efi/
451
452	The latest sources of ELILO can be downloaded at:
453
454	ftp://ftp.hpl.hp.com/pub/linux-ia64
455