Void Linux rEFInd encrypted LVM installation

2025-05-15

You might prefer to refer to reliable resources instead:

The plan

Partitions:

  • sda1 fat32 100MB esp partition mounted to /efi
  • sda2 ext4 1GB boot partition mounted to /boot
  • sda3 iso 2GB live void image for recovery purposes
  • sda4 encrypted LVM: system, swap, data

Disc setup

I prefer to prepare my partitions in gparted. Be sure to do this on a disc where you don’t mind that all the data will be lost. Be sure to do it on that disc and not another disc by mistake. Don’t forget to set boot, esp flags (on some devices you need both, other times having both can be a problem) for the esp partition. Do not set these flags for other partitions.

Encryption

Change amazingname for something even better and think up a password. (If you won’t setup your keyboard in chroot, you will need to be able to type this password on english keyboard.)

# cryptsetup luksFormat /dev/sda4
Enter passphrase for /dev/sda4: 
Verify passphrase: 

# cryptsetup luksOpen /dev/sda4 amazingname
Enter passphrase for /dev/sda4: 

Logical volumes

Create volume group and logical volumes:

# vgcreate amazingname /dev/mapper/amazingname
Volume group "amazingname" successfully created

# lvcreate --name void -L 50G amazingname
Logical volume "void" created.

I have not used swap in almost 20 years, but with maximum 16GB RAM possible, I think I might need it.

# lvcreate --name swap -L 16G amazingname
Logical volume "swap" created.

People often put their home on a separate partition. I prefer to have home with the rest of the system and mount my data partition to a folder in home.

# lvcreate --name data -l 100%FREE amazingname
Logical volume "data" created.

Create filesystems on the new partitions:

# mkfs.ext4 -L void /dev/amazingname/void 
mke2fs 1.47.2 (1-Jan-2025)
Creating filesystem with 13107200 4k blocks and 3276800 inodes
Filesystem UUID: 441f6b6d-45c7-4151-86c4-c9ecc7961be2
Superblock backups stored on blocks: 
	32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208, 
	4096000, 7962624, 11239424

Allocating group tables: done                            
Writing inode tables: done                            
Creating journal (65536 blocks): done
Writing superblocks and filesystem accounting information: done   


# mkfs.ext4 -L data /dev/amazingname/data 
mke2fs 1.47.2 (1-Jan-2025)
Creating filesystem with 226071552 4k blocks and 56524800 inodes
Filesystem UUID: 62fe25aa-9f48-4e85-ac77-a92ae7f79668
Superblock backups stored on blocks: 
	32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208, 
	4096000, 7962624, 11239424, 20480000, 23887872, 71663616, 78675968, 
	102400000, 214990848

Allocating group tables: done                            
Writing inode tables: done                            
Creating journal (262144 blocks): done
Writing superblocks and filesystem accounting information: done     


# mkswap /dev/amazingname/swap 
Setting up swapspace version 1, size = 16 GiB (17179865088 bytes)
no label, UUID=e7425ad0-8cdf-415c-a094-8129bcbfd17e

How to access logical volumes next time

If you reboot, disconnect the disk, or close the logical volumes, here’s how to access them again.
You need to unlock your encrypted partition and activate the logical volumes:

# cryptsetup luksOpen /dev/sda4 amazingname
 Enter passphrase for /dev/sda4: 

# vgchange -ay amazingname
  3 logical volume(s) in volume group "amazingname" now active

Now you may proceed with mounting and chrooting as described in the next section.

Closing

If you want to close them, or if you can’t open them again because something is still mounted or in use, try these:

# umount /mnt/boot
# umount /mnt/efi
# umount /mnt
# lvchange -an
# cryptsetup luksClose amazingname

System installation

Now mount the partitions the system will need:

# mount /dev/amazingname/void /mnt/
# mkdir /mnt/boot
# mkdir /mnt/efi
# mount /dev/sda1 /mnt/efi/
# mount /dev/sda2 /mnt/boot

Copy keys for verifying packages:

# mkdir -p /mnt/var/db/xbps/keys
# cp /var/db/xbps/keys/* /mnt/var/db/xbps/keys/

Install the basics:
(I set the XBPS_ARCH variable since i am installing a musl system from glibc system)

# XBPS_ARCH=x86_64-musl xbps-install -Sy -R https://repo-default.voidlinux.org/current/musl -r /mnt base-system cryptsetup lvm2

You may want to add to the list of installed packages here a comfortable text editor and shell, if they are not already included in base-system, since you will be using them a lot.

System setup

Both xgenfstab and xchroot are in the xtools-minimal package.

Generate /etc/fstab:
If you have multiple disks, consider using xgenfstab -U to identify partitions by UUID, or xgenfstab -L to use labels.
Or skip this for now, you will edit this file later anyway.

# xgenfstab /mnt > /mnt/etc/fstab

Chroot into your new system:

# xchroot /mnt

If you don’t have xchroot, do this instead:

# mount -t proc /proc /mnt/proc/
# mount --rbind /sys /mnt/sys/
# mount --rbind /dev /mnt/dev/
# chroot /mnt

Ensure owner and permission of /:

[xchroot /mnt] # chown root:root /
[xchroot /mnt] # chmod 755 /

Set root password and set hostname:

[xchroot /mnt] # passwd root
[xchroot /mnt] # echo amazinghostname > /etc/hostname

To allow members of wheel group to use sudo, edit the sudoers file using:

[xchroot /mnt] # visudo

And uncomment this line:

%wheel ALL=(ALL:ALL) ALL

Add this to allow the user to reboot and shut down the system without password:

username ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/poweroff

Create your user and set password:\

[xchroot /mnt] # useradd -m -G wheel,storage,lp,audio,video,cdrom,optical,scanner,network,kvm,xbuilder -s /bin/bash username
[xchroot /mnt] # passwd username

Data partition

Once the user’s home directory exists, I can make my data directory and copy the data.

# mkdir /mnt/home/username/data
# mount /dev/amazingname/data /mnt/home/username/data
# rsync -avh /path/to/data /mnt/home/username/data
  • -a archive mode (preserve symlinks, permissions, ownerships)
  • -v verbose
  • -h human readable

/etc/fstab

# <file system>       	        <dir>         	<type>  <options> 	<dump> <pass>
/dev/mapper/amazingname-void	/               ext4    rw                      0 1
/dev/mapper/amazingname-data	/home/user/data ext4    defaults                0 2
/dev/mapper/amazingname-swap	none           	swap    defaults,discard        0 0
/dev/sda1           	        /efi           	vfat    rw,umask=007            0 0
/dev/sda2           	        /boot          	ext4    defaults                0 2
tmpfs               	        /tmp           	tmpfs   defaults,nosuid,nodev   0 0

The EFI partition uses umask=0077 because FAT32 does not support UNIX permissions.

If you have other encrypted drives, other than what yoour root resides on, that you want to mount automatically, you should configure them in /etc/cryptab.

Booting

Do this section in chroot with /boot and /efi mounted.

Tell dracut to include crypt and lvm modules in initramfs. Create file /etc/dracut.conf.d/10-crypt.conf with contents:

add_dracutmodules+=" crypt lvm "
hostonly="yes"
  • hostonly - Host-only mode: Install only what is needed for booting the local host instead of a generic host and generate host-specific configuration

rEFInd

https://www.rodsbooks.com/refind/linux.html
https://wiki.archlinux.org/title/REFInd

Theoretically you could use the scripts to install rEFInd and place the config files (you still may need to edit them):

[xchroot /mnt] # xbps-install refind
[xchroot /mnt] # refind-install
[xchroot /mnt] # mkrlconf 

(refind-install and mkrlconf are scripts that come with rEFInd)

Version 0.14 from system package was crashing for me. When I selected the disc it was installed on from UEFI boot menu, the screen blinked and displayed UEFI boot menu again. Seemingly nothing happened, but when I recorded the blink on a video, I discovered that an error was briefly displayed:

rEFInd error in yellow text: Fatal error: %s %setting GOP mode to %d (%d%d) setting text mode %d: available modes are: allocating z_streame!

Manual download

Skip this if you installed the package.
I decided to try version 0.13.3.1 - and it worked.
Download whatever version you prefer from sourceforge.

Install unzip and unzip the zip:

[xchroot /mnt] # xbps-install unzip
[xchroot /mnt] # unzip refind-bin-0.13.3.1.zip
[xchroot /mnt] # cd refind-bin-0.13.3.1

Manual install

Skip this if you used refind-install.

/efi/EFI/refind is the proper path to install it. We will need to create an entry for it in NVRAM. /efi/EFI/BOOT/BOOTX64.EFI is a fallback path, used when no entry from NVRAM boots. I put rEFInd with no configuration there, in case NVRAM is deleted or disc is placed into another machine, it will load, find rEFInd at the proper path and save me some trouble.

[xchroot /mnt] # mkdir /efi/EFI/refind
[xchroot /mnt] # mkdir /efi/EFI/BOOT
[xchroot /mnt] # cp refind/refind_x64.efi /efi/EFI/BOOT/BOOTX64.EFI
[xchroot /mnt] # cp refind/refind_x64.efi /efi/EFI/refind/

Create the NVRAM entry:

[xchroot /mnt] # efibootmgr --create --disk /dev/sda --part 1 --loader /EFI/refind/refind_x64.efi --label "rEFInd Boot Manager" --unicode

If you get error about efivars not supported, you might need to mount them first:

[xchroot /mnt] # mkdir -p /sys/firmware/efi/efivars
[xchroot /mnt] # mount -t efivarfs efivarfs /sys/firmware/efi/efivars

You should see rEFInd entry added when you list settings:

[xchroot /mnt] # efibootmgr --unicode

Copy drivers for filesystems that you want rEFInd to be able to read (because for example you have kernel image there):

[xchroot /mnt] # cp refind/drivers_x64/ext4_x64.efi /efi/EFI/refind/drivers_x64/

Configuration

Create or edit /efi/EFI/refind/refind.conf with contents:

timeout 20
log_level 5
textonly
scanfor external,internal,optical,manual

Create or edit /boot/refind_linux.conf (it should be in the same directory as your kernel image) and specify kernel parameters in it:

"amazingname"   "root=/dev/mapper/amazingname-void rd.luks.name=123-456-789=amazingname rd.luks.options=discard rw loglevel=4 net.ifnames=0"

where you replace 123-456-789 with real UUID of your encrypted drive (sda4 for me):

[xchroot /mnt] #  blkid | grep crypto
  • root: tells the kernel where your root filesystem is, points to a decrypted logical volume
  • rd.luks.name: tells initramfs to decrypt LUKS volume with UUID 123-456-789 and map it to /dev/mapper/amazingname
  • rd.luks.options: sets options when opening LUKS device (discard - SSD trim support)
  • rw: mount the filesystem for read-write
  • loglevel: verbosity of kernel log (0 - emergency only, 4 - warnings and more severe, 7 - debugging)
  • net.ifnames: old interface names (wlan0 instead of wlp2s0)

Regenarate initramfs

You may need to specify kernel version since you are in chroot and your installed kernel might be different version than your running kernel.

Find out version of your installed kernel.

[xchroot /mnt] # xbps-query --regex -s '^linux[0-9.]+-[0-9._]+'
[*] linux6.12-6.12.24_1 Linux kernel and modules (6.12 series)

Regenerate initramfs:

[xchroot /mnt] # dracut --force --kver 6.12.24_1

You should be able to boot now.

I am not able to boot now

Do not connect your disc by USB; some UEFI implementations fail to detect EFI files on external devices.
Try booting rEFInd live usb drive https://www.rodsbooks.com/refind/getting.html, see if it detects your esp and your kernel.

You are stuck in UEFI boot menu

rEFInd is not found or crashes, try using older version and placing it to fallback path /efi/EFI/BOOT/BOOTX64.EFI.

Check if your esp partition has boot, esp flags and GUID c12a7328-f81f-11d2-ba4b-00a0c93ec93b.

Some firmwares may not feel like reading files from “small” fat32 esp, the solution is to use fat16. Unless you are also using windows, which might require fat32, try making the partition bigger than 550MB then.

rEFInd menu contains no linux

Check if rEFInd has driver to read the filesystem of the partition with your kernel. For example the file /efi/EFI/refind/drivers_x64/ext4_x64.efi.

Check /efi/EFI/refind/refind.log for information, look for lines like in the examples:

  • are the drivers used?
'EFI\refind\drivers_x64\iso9660_x64.efi' is a valid loader file
  • does rEFInd scan partition (boot is the label of the partition) and directory with your kernel image?
Scanning EFI files on boot
Beginning to scan directory '\' for '*.efi,*.EFI,vmlinuz*,bzImage*,kernel*'

If not, Booting ISO with rEFInd has information about making rEFInd find things.

rEFInd contains linux option, but it leads to blank screen

If you are not prompted for password to unlock amazingname, ensure that dracut included cryptsetup in initramfs. Try:

[xchroot /mnt] # lsinitrd /boot/initramfs-6.1XX.img | grep cryptsetup
-rwxr-xr-x   1 root     root       235112 Feb 14 06:28 usr/bin/cryptsetup

If not, try adding it to the command:

[xchroot /mnt] # dracut --force --kver 6.1XX --add "crypt lvm"

If yes, check if these configuration files use correct names and UUIDs: /boot/refind_linux.conf` should contain:

root=/dev/mapper/amazingname-void rd.luks.name=123-456-789=amazingname

/etc/fstab should contain:

/dev/mapper/amazingname-void	/               ext4    rw                      0 1

Make sure these point to the correct logical volume and UUID. Replace 123-456-789 with the actual UUID of your encrypted partition (you can find it using blkid | grep crypto).

Look at your disc structure with:

[xchroot /mnt] # lsblk -f

Check dracut cmdline:

lsinitrd /boot/initramfs-6.12.43_1.img | sed -n '/dracut cmdline:/,$p'
dracut cmdline:
 rd.luks.uuid=luks-123-456-789
 rd.lvm.lv=amazingname/swap   rd.lvm.lv=amazingname/void  
 resume=/dev/mapper/amazingname-swap
 root=/dev/mapper/amazingname-void rootfstype=ext4 rootflags=rw,relatime

It should contain your encrypted partition UUID and lvm names. If it does not, you are not passing hostonly=“yes” to dracut. Create /etc/dracut.conf.d/*.conf containing:

hostonly="yes"

What next?

Live ISO partition

Described in detail here: Booting ISO with rEFInd.