Gecko [ www.prositehelp.com ]

Name	Size	Permission	Date
pictures	[ DIR ]	drwxr-xr-x	2026-04-01 09:39
00-relax-and-recover-user-guide.md	354 B	-rw-r--r--	2026-04-01 09:39
01-introduction.md	4.23 KB	-rw-r--r--	2026-04-01 09:39
02-getting-started.md	4.87 KB	-rw-r--r--	2026-04-01 09:39
03-configuration.md	8.09 KB	-rw-r--r--	2026-04-01 09:39
04-scenarios.md	55.4 KB	-rw-r--r--	2026-04-01 09:39
05-integration.md	4.08 KB	-rw-r--r--	2026-04-01 09:39
06-layout-configuration.md	33.13 KB	-rw-r--r--	2026-04-01 09:39
07-tips-and-tricks.md	1.8 KB	-rw-r--r--	2026-04-01 09:39
08-troubleshooting.md	5.3 KB	-rw-r--r--	2026-04-01 09:39
09-design-concepts.md	9.34 KB	-rw-r--r--	2026-04-01 09:39
10-integrating-external-backup.md	5 KB	-rw-r--r--	2026-04-01 09:39
11-multiple-backups.md	13.3 KB	-rw-r--r--	2026-04-01 09:39
12-BLOCKCLONE.md	30.25 KB	-rw-r--r--	2026-04-01 09:39
13-tcg-opal-support.md	15.12 KB	-rw-r--r--	2026-04-01 09:39
14-ZYPPER-and-YUM.md	12.32 KB	-rw-r--r--	2026-04-01 09:39
15-EFISTUB.md	12.43 KB	-rw-r--r--	2026-04-01 09:39
16-Rubrik-CDM.md	5.41 KB	-rw-r--r--	2026-04-01 09:39
17-Portable-Mode.md	2.4 KB	-rw-r--r--	2026-04-01 09:39
Makefile	438 B	-rw-r--r--	2026-04-01 09:39

Rename

# EFISTUB support

EFISTUB booting allows EFI firmware to directly load Linux kernel as an EFI executable. At the time of writing, EFISTUB support in kernel is widely available across all major distributions like SLES, Debian, Ubuntu, Fedora, Arch ...
When using traditional boot-loaders ((E)LILO, Grub), ReaR does not auto-magically recreate booting information on restore, but respective code must exist and this also applies for EFISTUB booting.

## Prerequisites
There is plenty of ways how EFISTUB can be setup on source system but for the start I've decided to keep first EFISTUB implementation as simple as possible and eventually cover more robust configuration later (if need arise). For this reason ReaR currently offers very basic implementation, where:

- active Linux kernel must be compiled with **CONFIG_EFI_STUB=y**
- active Linux kernel and initrd are located directly on **vfat** partition
- **no intermediate boot loader** (ELILO, Grub, systemd-boot, ...) is in use and OS is booted directly from UEFI boot menu
- systemd-boot binary (for booting of ReaR recovery system) is available on system (usually as part of Systemd)
- currently works only with **OUTPUT=ISO**

## ReaR Configuration
By default EFISTUB is disabled in ReaR and user must explicitly enable this functionality. Detection of EFISTUB booting is quite a problematic topic since it can co-exist with traditional boot loaders. Many Linux distributions are shipping Linux kernels with enabled EFISTUB support despite a fact that it is not used, and OS is using traditional intermediate boot loaders instead. You should enable EFISTUB in ReaR only if your system is really configured to boot this way, otherwise ReaR will try to perform migration.

To enable EFISTUB booting in ReaR one must specify following variable in _local.conf_ or _site.conf_

EFI_STUB="yes"

## Migration
Migrating from traditional boot-loader to EFISTUB is kind of side effect of current implementation. Current EFISTUB code can't reliably determine if system is configured with EFISTUB boot hence user must explicitly specify that he wishes his system is considered EFISTUB bootable by ReaR.
If operating system is set to boot using intermediate boot loaders and despite this `EFI_STUB="yes"` is explicitly set, ReaR will omit installation of intermediate boot loaders and just creates UEFI boot entry pointing directly to EFISTUB boot capable kernel when system is restored.

## Checks done by ReaR
When user enables EFISTUB, ReaR does some basic checks and tries to ensure that ReaR recovery runs without problems and resulting operating system is able to boot. However it is very hard to cover all configuration possibilities and corner cases, so it is important to ALWAYS TEST full ReaR backup and restore before relying on it. Short list of checks done by ReaR during `rear mkbackup/mkrescue` includes:

- check if Systemd boot loader (systemd-bootx64.efi) exists and is regular file
- check if some of basic EFISTUB symbols are present in Linux kernel file in use
- check if Linux kernel in use is located on vfat partition

## Tests
Current code was primarily created and tested with Arch Linux, since most requests for EFISTUB functionality in ReaR keeps coming from this community.
Test system was running under VirtualBox host with following configuration:

* OS version

arch-efi:(/root)(root)# lsb_release -a
        LSB Version:    1.4
        Distributor ID: Arch
        Description:    Arch Linux
        Release:    rolling
        Codename:   n/a
        
        arch-efi:(/root)(root)# uname -a
        Linux arch-efi.virtual.sk 4.20.5-arch1-1-ARCH #1 SMP PREEMPT Sat Jan 26 12:59:18 UTC 2019 x86_64 GNU/Linux

* boot entry for Arch Linux (_Boot0003_) created in UEFI

arch-efi:(/root)(root)# efibootmgr -v
        BootCurrent: 0003
        BootOrder: 0003,0000,0001,0002
        Boot0000* EFI DVD/CDROM PciRoot(0x0)/Pci(0x1,0x1)/Ata(1,0,0)
        Boot0001* EFI Hard Drive    PciRoot(0x0)/Pci(0xd,0x0)/Sata(0,0,0)
        Boot0002* EFI Internal Shell    MemoryMapped(11,0x2100000,0x28fffff)/FvFile(7c04a583-9e3e-4f1c-ad65-e05268d0b4d1)
        Boot0003* Arch Linux    HD(1,GPT,e3b3601c-8037-4bf6-a938-4772cfb1ad9f,0x800,0x113000)/File(vmlinuz-linux)i.n.i.t.r.d.=.i.n.i.t.r.a.m.f.s.-.l.i.n.u.x...i.m.g. .r.o.o.t.=./.d.e.v./.s.d.a.2.

* ReaR configuration

arch-efi:(/root)(root)# cat /etc/rear/local.conf
        BACKUP=NETFS
        OUTPUT=ISO
        
        BACKUP_URL=nfs://backup.virtual.sk/mnt/rear
        OUTPUT_URL=nfs://backup.virtual.sk/mnt/rear/iso
        
        BACKUP_OPTIONS="nfsvers=3,nolock"
        
        EFI_STUB=yes

* File system layout

arch-efi:(/root)(root)# df -Th
        Filesystem     Type      Size  Used Avail Use% Mounted on
        dev            devtmpfs  485M     0  485M   0% /dev
        run            tmpfs     492M  404K  491M   1% /run
        /dev/sda2      ext4      7.3G  2.1G  4.9G  30% /
        tmpfs          tmpfs     492M     0  492M   0% /dev/shm
        tmpfs          tmpfs     492M     0  492M   0% /sys/fs/cgroup
        /dev/sda1      vfat      549M   41M  509M   8% /boot
        tmpfs          tmpfs      99M     0   99M   0% /run/user/0

- Content of /boot

arch-efi:(/root)(root)# ls -l /boot
        total 41684
        -rwxr-xr-x 1 root root    31232 Jan 22 10:14 amd-ucode.img
        -rwxr-xr-x 1 root root 29094161 Feb  3 09:09 initramfs-linux-fallback.img
        -rwxr-xr-x 1 root root  7686652 Feb  3 09:09 initramfs-linux.img
        drwxr-xr-x 2 root root     4096 Jan 31 14:56 syslinux
        -rwxr-xr-x 1 root root  5855104 Jan 31 09:17 vmlinuz-linux

## Migration from GRUB2 to EFISTUB on SLES12 SP2
WARNING: Do not start migration to EFISTUB until you are familiar with all the eventualities. It might happen that you end up with un-bootable system. Most of the time it is possible to fix un-bootable system, but some deeper knowledge might be required to succeed.

When prerequisites are fulfilled one can use ReaR EFISTUB code to migrate system from intermediate boot loaders like GRUB, ELILO to EFISTUB.
For the demonstration purposes I've tried migration from GRUB2 to EFISTUB on SLES12 SP2.

* OS version

sp2:~ # cat /etc/os-release
        NAME="SLES_SAP"
        VERSION="12-SP2"
        VERSION_ID="12.2"
        PRETTY_NAME="SUSE Linux Enterprise Server for SAP Applications 12 SP2"
        ID="sles_sap"
        ANSI_COLOR="0;32"
        CPE_NAME="cpe:/o:suse:sles_sap:12:sp2"

* Basic ReaR configuration (does not include all EFISTUB configuration pieces yet)

sp2:~ # cat /etc/rear/local.conf
        BACKUP=NETFS
        OUTPUT=ISO
        
        BACKUP_URL=nfs://backup.virtual.sk/mnt/rear
        OUTPUT_URL=nfs://backup.virtual.sk/mnt/rear/iso
        
        BACKUP_OPTIONS="nfsvers=3,nolock"
        
        BACKUP_PROG_EXCLUDE+=( /mnt )
        
        #BTRFS stuff
        REQUIRED_PROGS+=( snapper chattr lsattr xfs_repair )
        COPY_AS_IS+=( /usr/lib/snapper/installation-helper /etc/snapper/config-templates/default )
        BACKUP_PROG_INCLUDE=( $(findmnt -n -r -t btrfs | cut -d ' ' -f 1 | grep -v '^/$' | grep -Ev 'snapshots|crash' ) )
        
        EFI_STUB=y

* File system layout

Filesystem              Type      Size  Used Avail Use% Mounted on
        devtmpfs                devtmpfs  235M     0  235M   0% /dev
        tmpfs                   tmpfs     8.0G     0  8.0G   0% /dev/shm
        tmpfs                   tmpfs     244M  4.8M  239M   2% /run
        tmpfs                   tmpfs     244M     0  244M   0% /sys/fs/cgroup
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/lib/named
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /home
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/lib/pgsql
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/cache
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/tmp
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/lib/mailman
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/log
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/lib/libvirt/images
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /usr/local
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /boot/grub2/x86_64-efi
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/spool
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/crash
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /opt
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/lib/mariadb
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /tmp
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/opt
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /srv
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/lib/mysql
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /var/lib/machines
        /dev/mapper/system-root btrfs     7.8G  3.9G  3.3G  55% /boot/grub2/i386-pc
        /dev/sda1               vfat      156M   26M  131M  17% /boot/efi
        tmpfs                   tmpfs      49M     0   49M   0% /run/user/0

Since we don't have condition that active Linux kernel and initrd must reside on vfat file system, we can fulfill this requirement in two ways:

**1. Copy active Linux kernel and initrd files to vfat file system and configure ReaR to use alternate kernel file.**

In this particular case active kernel and initrd image are represented by following files:

sp2:~ # ls -al /boot/vmlinuz-* /boot/initrd-*
        -rw------- 1 root root 16365388 Aug 30 17:29 /boot/initrd-4.4.21-69-default
        -rw-r--r-- 1 root root  5742352 Oct 25  2016 /boot/vmlinuz-4.4.21-69-default

To copy files to vfat file system _/boot/efi_:

sp2:~ # cp /boot/initrd-4.4.21-69-default /boot/efi
        sp2:~ # cp /boot/vmlinuz-4.4.21-69-default /boot/efi

Now we need to tell ReaR that we have kernel on vfat file system by adding `KERNEL_FILE="/boot/efi/vmlinuz-4.4.21-69-default"` configuration option into _/etc/rear/local.conf_

WARNING: Using kernel and initrd from other location than _/boot_, might require to perform some additional steps every time kernel and initrd changes (e.g. after each kernel or initrd update), like copy updated files to alternate location.

**2. Convert /boot to vfat file system**

There is several ways how one can convert _/boot_ into vfat. Easiest one is to create additional partition, format it with vfat and mount it under _/boot_.
As to cover this topic can be quite exhausting, it is not part of this document. In general if you don't know how to migrate _/boot_ to vfat, you should consider your decision to migrate system to EFISTUB carefully once more...

Whether you've decided to use _1st_ or _2nd_ method, last thing remaining is to configure custom boot attributes for EFISTUB. Normally when ReaR is configured to backup EFISTUB enabled system, it takes boots option from `/proc/cmdline`. During migration however `/proc/cmdline` does not contain sufficient information for successful EFISTUB boot. In our case:

sp2:~ # cat /proc/cmdline
        BOOT_IMAGE=/boot/vmlinuz-4.4.21-69-default root=/dev/mapper/system-root ro resume=/dev/system/swap splash=silent quiet showopts

lacks information about which _initrd_ image should be booted. This information can be passed to ReaR by `EFI_STUB_EFIBOOTMGR_ARGS` configuration option. In our case we will add

EFI_STUB_EFIBOOTMGR_ARGS="initrd=initrd-4.4.21-69-default root=/dev/mapper/system-root ro resume=/dev/system/swap splash=silent quiet showopts"

configuration directive into _/etc/rear/local.conf_.

With ReaR configured as described in previous lines, we can start OS backup with `rear mkbackup`.

When ReaR recovery system is booted, we can start restore process as usual with `rear recover`. Once operation is over and you've used 1st method (_Copy active Linux kernel and initrd files to vfat file system and configure ReaR to use alternate kernel file_) you must copy _initrd_ image file, recently modified by ReaR, from _/mnt/local/boot_ into its alternate location (_/mnt/local/boot/efi_ in our case)

RESCUE sp2:~ # cp /mnt/local/boot/initrd-4.4.21-69-default /mnt/local/boot/efi/

because of reason mentioned in _WARNING_ section of 1st method. If you've been using 2nd method (_Convert /boot to vfat file system_), you can reboot ReaR recovery system without any further modifications.

Now restored system is ready for reboot!