README

   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