Void Linux Installation Guide with Disk Encryption (except boot), Btrfs, rEFInd

Warning: Follow this guide at your own risk!.

Late 2023: early version of this article;
October, 29th 2024: first version;
March, 12th 2026: fix some typos, remove wrong instruction saying to choose 2 for fsck order digits for Btrfs subvolumes in /etc/fstab (it should be 0), remove wrong assumption claiming rEFInd does not work on the musl variant of Void Linux (thank you to a reader for pointing that out!).

Installation Image

First we need to install a Void live image on an external drive. Here I will show you how to do this from a Linux machine.

Get the Void image here. In most cases, the one you want is in sections x86_64, base, “live image” (choose either glibc or musl, based on your preference). Also get just above the x86_64 button the sha256sum.txt and sha256sum.sig files.

Install minisign with your package manager. Check the integrity and signatures of the files with ¹:

# Check
# "https://github.com/void-linux/void-packages/tree/master/srcpkgs/void-release-keys/files/"
# for the up-to-date link
wget 'https://raw.githubusercontent.com/void-linux/void-packages/refs/heads/master/srcpkgs/void-release-keys/files/void-release-20240314.pub'
minisign -V -p void-release-20240314.pub -x sha256sum.sig -m sha256sum.txt
sha256sum -c --ignore-missing sha256sum.txt

Example of correct minisign output:

Signature and comment signature verified
Trusted comment: This key is only valid for images with date 20240314.

For sha256sum:

void-live-x86_64-20240314-base.iso: OK

Flash the image on an external drive ². Everything on it will be deleted!

lsblk  # Find your USB key
umount /dev/sdX  # Check it is not mounted (should return `umount: /dev/sdX: not mounted`)

cat void-live-x86_64-20240314-base.iso > /dev/sdX
sync

Void Linux Installation

Boot the external driver. Choose the RAM option for better performance ³. Log in with root and password voidlinux.

Run bash for a better shell (completion…).

If your keyboard is not QWERTY:

ls /usr/share/kbd/keymaps/i386  # Find your keyboard
loadkeys fr-latin9  # Replace fr-latin9 with your keyboard

Internet Connectivity

For Wi-Fi connection (here with WPA-PSK, that is, personal Wi-Fi), find the right interface with ip a. We suppose here that it’s wlan0. Then run:

wpa_cli -i wlan0

Using wpa_cli, execute:

scan
scan_results
add_network
set_network 0 ssid "MySSID"
set_network 0 psk "passphrase"
enable_network 0
save_config
quit

If your Wi-Fi network does not have any password, run instead set_network 0 key_mgnt NONE.

Test connectivity with ping. If it’s still not working, try ip link set up wlan0 or sv restart dhcpd.

Partitioning

Create two partitions, one for the /boot partition with 1 GiB ⁴ and one for the rest. To do so, use for instance cfdisk -z /dev/nvme0n1 where /dev/nvme0n1 is the disk where you want to install Void (check with lsblk) ⁵. Be careful with this command as you will lose any files on the disk. Choose gpt for the label, and choose EFI System for the type of the first partition. Leave the default for the second (Linux filesystem). Finish with Write.

Filesystem and Disk Encryption

mkfs.vfat -F32 /dev/nvme0n1p1
cryptsetup luksFormat /dev/nvme0n1p2  # Choose a password
cryptsetup open /dev/nvme0n1p2 cryptroot
mkfs.btrfs /dev/mapper/cryptroot

mount /dev/mapper/cryptroot /mnt
btrfs subvol create /mnt/@
btrfs subvol create /mnt/@home
btrfs subvol create /mnt/@snapshots
btrfs subvol create /mnt/@var_log
btrfs subvol create /mnt/@swap
umount /mnt

mount -o defaults,subvol=@ /dev/mapper/cryptroot /mnt
mkdir -p /mnt/boot && mount /dev/nvme0n1p1 /mnt/boot
mkdir -p /mnt/home && mount -o defaults,subvol=@home /dev/mapper/cryptroot /mnt/home
mkdir -p /mnt/.snapshots && mount -o defaults,subvol=@snapshots /dev/mapper/cryptroot /mnt/.snapshots
mkdir -p /mnt/var/log && mount -o defaults,subvol=@var_log /dev/mapper/cryptroot /mnt/var/log
mkdir -p /mnt/swap && mount -o defaults,subvol=@swap /dev/mapper/cryptroot /mnt/swap

System Installation

Choose an official mirror close to you, and run this accordingly ⁶:

REPO=https://repo-default.voidlinux.org/current
ARCH=x86_64

Copy the Void keys to install packages:

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

Install the system:

XBPS_ARCH=$ARCH xbps-install -S -r /mnt -R "$REPO" base-system btrfs-progs cryptsetup refind vim  # Or nano

Chroot Environment

System Configuration

xchroot /mnt /bin/bash

Then in the Chroot environment:

vim /etc/hostname  # Choose a hostname
vim /etc/rc.conf  # Or nano. Change the keyboard if needed
ln -sf /usr/share/zoneinfo/Europe/Paris /etc/localtime  # Pick your own timezone

# For glibc distributions
vim /etc/default/libc-locales  # Uncomment the relevant locales for you
xbps-reconfigure -f glibc-locales

Then:

passwd  # Root password
useradd -m myuser  # Create a given user
passwd myuser  # Set its password
gpasswd -a myser wheel  # Make them able to run sudo commands
visudo  # Remove comments on one of the wheel lines

`fstab` File

cp /proc/mounts /etc/fstab

Edit the fstab file and remove all lines except the ones with /dev/mapper/cryptroot and /dev/nvme0n1p1 (/boot). Then change the last 0 with 2 only for the line containing /boot (this is for file system checks) ⁷. Then run:

BOOT_UUID=$(blkid -s UUID -o value /dev/nvme0n1p1)
ROOT_UUID=$(blkid -s UUID -o value /dev/mapper/cryptroot)
sed -i "s/\/dev\/nvme0n1p1/UUID=$BOOT_UUID/" /etc/fstab
sed -i "s/\/dev\/mapper\/cryptroot/UUID=$ROOT_UUID/" /etc/fstab

echo "/swap/swapfile none swap defaults 0 0" >> /etc/fstab
echo "tmpfs /tmp tmpfs defaults,nosuid,nodev 0 0" >> /etc/fstab

Check the file. It should look like this:

UUID=c52c0f6d-b6b5-4871-8330-8f46c335d5ee /           btrfs rw,relatime,space_cache=v2,subvolid=256,subvol=/@ 0 0
UUID=D5FA-4678                            /boot       vfat  rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixes,utf8,errors=remount-ro 0 2
UUID=c52c0f6d-b6b5-4871-8330-8f46c335d5ee /home       btrfs rw,relatime,space_cache=v2,subvolid=257,subvol=/@home 0 0
UUID=c52c0f6d-b6b5-4871-8330-8f46c335d5ee /var/log    btrfs rw,relatime,space_cache=v2,subvolid=258,subvol=/@var_log 0 0
UUID=c52c0f6d-b6b5-4871-8330-8f46c335d5ee /swap       btrfs rw,relatime,space_cache=v2,subvolid=260,subvol=/@swap 0 0
UUID=c52c0f6d-b6b5-4871-8330-8f46c335d5ee /.snapshots btrfs rw,relatime,space_cache=v2,subvolid=259,subvol=/@snapshots 0 0
/swap/swapfile                            none        swap  defaults 0 0
tmpfs                                     /tmp        tmpfs defaults,nosuid,nodev 0 0

Create a swap file. For 8 to 64 GB RAMs, the recommended size is 3/2 the size of the RAM if you plan to use hibernation ⁵. Example for a RAM of 8 GB:

btrfs filesystem mkswapfile --size 12G --uuid clear /swap/swapfile
swapon /swap/swapfile
SWAP_OFFSET=$(btrfs inspect-internal map-swapfile -r /swap/swapfile)

rEFInd

refind-install

We update the /boot/refind_linux.conf file with:

echo "" > /boot/refind_linux.conf
echo "\"Boot (quietly)\" \"rw root=UUID=$ROOT_UUID resume=UUID=$ROOT_UUID resume_offset=$SWAP_OFFSET quiet\"" >> /boot/refind_linux.conf
echo "\"Boot\" \"rw root=UUID=$ROOT_UUID resume=UUID=$ROOT_UUID resume_offset=$SWAP_OFFSET\"" >> /boot/refind_linux.conf

Optimize the generation of initramfs images with ⁸:

echo "hostonly=yes" > /etc/dracut.conf.d/hostonly.conf

And finally:

xbps-reconfigure -fa

swapoff /swap/swapfile
exit  # Exit chroot
umount -R /mnt
reboot

Now Void Linux is installed on your machine!

< Previous Next >