| | 1 | (U)EFI boot loaders updater |
| | 2 | ========================== |
| | 3 | |
| | 4 | What is this for? |
| | 5 | ----------------- |
| | 6 | |
| | 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'. |
| | 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 |
| | 20 | /etc/efi-boot/update.d/*.conf files (efi-boot-update modules). |
| | 21 | |
| | 22 | efi-boot-update will also manage EFI boot manager configuration, adding |
| | 23 | the configured boot loaders to the platform boot menu, provided the |
| | 24 | 'efibootmgr' package is installed and functional. |
| | 25 | |
| | 26 | |
| | 27 | What is this not? |
| | 28 | ----------------- |
| | 29 | |
| | 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. |
| | 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 | |
| | 48 | efi-boot-update should be manually called whenever any of these files |
| | 49 | have been edited. |
| | 50 | |
| | 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). |
| | 71 | EFI path to this directory (\EFI\...) will be available as |
| | 72 | '@EFI_PLATFORM_PATH@' for setting the $ARGS module parameter. |
| | 73 | |
| | 74 | modules in /etc/efi-boot/update.d |
| | 75 | ................................. |
| | 76 | |
| | 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. |
| | 79 | |
| | 80 | Following variables can be be set for each module: |
| | 81 | |
| | 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 |
| | 88 | * ARGS – command line arguments for the EFI application (can contain |
| | 89 | '@EFI_PLATFORM_PATH@' and '@ARCH@' macros) |
| | 90 | * ARCH – architecture the binary is built for |
| | 91 | |
| | 92 | The module may define more configurable variables, but should use own unique |
| | 93 | prefix for them. |
| | 94 | |
| | 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. |
| | 97 | |
| | 98 | It can contain any shell code, but should not define any new global variables. |
| | 99 | For convenience following are defined: |
| | 100 | |
| | 101 | * '$DESTDIR' variable – defines the directory where the files should be |
| | 102 | copied to that will be /boot/efi/EFI/$PLATFORM_DIR |
| | 103 | |
| | 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 |
| | 113 | --missingok – when used, he command will not complain when the SOURCE |
| | 114 | does not exist |
| | 115 | |
| | 116 | update_file behaviour depends on the '--verbose' and '--force' options |
| | 117 | passed to the efi-boot-update script. |
| | 118 | |
| | 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 | |
projects / packages / efi-boot-update.git / blame_incremental