]>
Commit | Line | Data |
---|---|---|
b32e97c8 | 1 | (U)EFI boot loaders updater |
7a63766a JK |
2 | ========================== |
3 | ||
4 | What is this for? | |
5 | ----------------- | |
6 | ||
24e7240b JK |
7 | (U)EFI systems boot using boot loaders on a special EFI System Partition. |
8 | Many different boot loaders may be present at a time. These are not only | |
9 | traditional boot loaders like GRUB, but arbitrary 'EFI applications'. | |
7a63766a JK |
10 | |
11 | Xen or Linux kernel can be built as an EFI application too and booted directly | |
12 | from the EFI firmware. The problem is the kernels and data or config files | |
13 | needed for boot must be stored on the EFI System Partition, but that is not | |
14 | the place where they are installed on package upgrade. And it is hard to | |
15 | install files from RPM packages there directly. | |
16 | ||
17 | efi-boot-update script makes it easy to manage the files on the EFI system | |
18 | partition. Those files are to be installed in the regular Linux system and | |
19 | will be copied to the EFI system partition using rules defined in | |
24e7240b | 20 | /etc/efi-boot/update.d/*.conf files (efi-boot-update modules). |
7a63766a JK |
21 | |
22 | efi-boot-update will also manage EFI boot manager configuration, adding | |
b32e97c8 JK |
23 | the configured boot loaders to the platform boot menu, provided the |
24 | 'efibootmgr' package is installed and functional. | |
7a63766a JK |
25 | |
26 | ||
24e7240b JK |
27 | What is this not? |
28 | ----------------- | |
29 | ||
b32e97c8 JK |
30 | This is not another configuration interface for the boot loaders. |
31 | efi-boot-update can copy boot loader configuration files to the EFI system | |
32 | partition, but it doesn't care about their contents or syntax. | |
24e7240b JK |
33 | |
34 | User Guide | |
35 | ---------- | |
36 | ||
37 | When efi-boot-update is installed it should be automatically called whenever | |
38 | any package containing EFI boot loader/application (or data for such | |
39 | application) is installed, upgraded or removed. | |
40 | ||
41 | The administrator may alter efi-boot-update operation editing the | |
42 | global /etc/efi-boot/update.conf file and the efi-boot-update modules | |
43 | in /etc/efi-boot/update.d (these configure rules for a specific application). | |
44 | ||
45 | The administrator is also responsible to edit any configuration files used by | |
46 | the boot loaders (usually in /etc/efi-boot). | |
47 | ||
b32e97c8 JK |
48 | efi-boot-update should be manually called whenever any of these files |
49 | have been edited. | |
50 | ||
24e7240b JK |
51 | /etc/efi-boot/update.conf |
52 | ......................... | |
53 | ||
54 | This file provide global settings for the efi-boot-update script. The | |
55 | file uses POSIX shell syntax to set shell variables. Values containing | |
56 | spaces should be quoted with double quotes. | |
57 | ||
58 | Following variables can be set there: | |
59 | ||
60 | * LABEL_PREFIX – the text to be prepended to every boot manager entry label | |
61 | created by efi-boot-update. | |
62 | * ORDER – preferred boot loader order. The value should contain | |
63 | space-separated names of efi-boot-update modules in /etc/efi/update.d | |
64 | (filenames there with '.conf' stripped). | |
65 | * PLATFORM_DIR – subdirectory of the 'EFI' directory in the EFI system | |
66 | partition where the EFI applications and data files will be stored. | |
67 | The value may contain '@ARCH@', which will be replaced with the | |
68 | architecture ('x64' or 'x32') for which the application was built (boot | |
69 | loaders may have both 32-bit and 64-bit versions and it may be different | |
70 | architecture that the one Linux is running). | |
3c17787a JK |
71 | EFI path to this directory (\EFI\...) will be available as |
72 | '@EFI_PLATFORM_PATH@' for setting the $ARGS module parameter. | |
24e7240b JK |
73 | |
74 | modules in /etc/efi-boot/update.d | |
75 | ................................. | |
76 | ||
b32e97c8 JK |
77 | The *.conf files in the /etc/efi-boot/update.d directory provide rules for |
78 | installing a boot loader and creating the EFI boot manager label for it. | |
24e7240b JK |
79 | |
80 | Following variables can be be set for each module: | |
81 | ||
b32e97c8 JK |
82 | * ENABLED – when 'yes', then the files will be copied and a boot manager |
83 | entry will be created for the application (provided BINARY is also set) | |
84 | * LABEL – label to use for the boot manager entry (defaults to the module | |
85 | name) | |
86 | * BINARY – name of the EFI binary installed in /boot/efi/EFI/$PLATFORM_DIR | |
87 | or a path to any EFI binary existing on the EFI system partition | |
3c17787a JK |
88 | * ARGS – command line arguments for the EFI application (can contain |
89 | '@EFI_PLATFORM_PATH@' and '@ARCH@' macros) | |
24e7240b JK |
90 | * ARCH – architecture the binary is built for |
91 | ||
b32e97c8 JK |
92 | The module may define more configurable variables, but should use own unique |
93 | prefix for them. | |
24e7240b | 94 | |
b32e97c8 JK |
95 | The module file should also contain a install_files() function definition |
96 | which defines what files are to be installed on the EFI system partition. | |
24e7240b | 97 | |
b32e97c8 JK |
98 | It can contain any shell code, but should not define any new global variables. |
99 | For convenience following are defined: | |
24e7240b | 100 | |
b32e97c8 JK |
101 | * '$DESTDIR' variable – defines the directory where the files should be |
102 | copied to that will be /boot/efi/EFI/$PLATFORM_DIR | |
3c17787a | 103 | |
24e7240b JK |
104 | * 'update_file' function – copies a file to the EFI partition |
105 | ||
106 | Usage: | |
107 | update_file [--missingok] SOURCE DEST | |
108 | ||
109 | Where: | |
110 | SOURCE – absolute path to the file to be copied | |
111 | DEST – destination file name. Absolute (but should be in | |
112 | /boot/efi) or, preferably, Relative to $DESTDIR | |
b32e97c8 JK |
113 | --missingok – when used, he command will not complain when the SOURCE |
114 | does not exist | |
24e7240b JK |
115 | |
116 | update_file behaviour depends on the '--verbose' and '--force' options | |
117 | passed to the efi-boot-update script. | |
118 | ||
b32e97c8 JK |
119 | Trouble shooting |
120 | ---------------- | |
121 | ||
122 | > efi-boot-update: EFI system partition not mounted. | |
123 | ||
124 | To boot from EFI you need a GUID Partition Table on your HDD containing the | |
125 | EFI system partition. And efi-boot-update needs the partition mounted at | |
126 | /boot/efi | |
127 | ||
128 | When used with '--mount' option, efi-boot-update will try to find an mount the | |
129 | partition, but for proper operation during package installation/upgrades the | |
130 | partition should be always mounted. | |
131 | ||
132 | > efi-boot-update: efibootmgr missing, won't update the boot manager | |
133 | > configuration | |
134 | ||
135 | efi-boot-update needs the 'efibootmgr' utility to update the EFI boot manager | |
136 | configuration. | |
137 | ||
138 | > efi-boot-update: efibootmgr does not work (efivars interface not available?) | |
139 | > efi-boot-update: won't update boot manager configuration | |
140 | ||
141 | The 'efibootmgr' does not always wark. It needs the 'efivars' kernel module | |
142 | loaded (efi-boot-update takes care of that) and functioning correctly. This is | |
143 | not always the case. The 'efivars' module works only when the kernel was | |
144 | booted via EFI. If kernel has been started from from BIOS or is running | |
145 | under Xen 'efibootmgr' won't work. | |
146 | ||
147 | This causes a little boot strapping problem – you cannot use efi-boot-update | |
148 | alone to configure system for the first UEFI boot. | |
149 | ||
150 | efi-boot-update can still copy the files to the EFI partition, but one has | |
151 | to manually select the boot loader via the EFI platform configuration | |
152 | interface. | |
153 |