Warning: THE VOID WIKI IS DEPRECATED. It is no longer being maintained, contains outdated and incorrect information, and will eventually be shut down. Please refer to the Void Handbook, https://docs.voidlinux.org/, for the official documentation. If you can't find the information you're seeking, please raise an issue at https://github.com/void-linux/void-docs/issues


From Void Linux Wiki
Jump to navigation Jump to search
Warning: Work in progress.
  • Manual, chroot installation
  • Simulates partitions with btrfs subvolumes
  • /boot is encrypted along with everything else in the main partition
  • GRUB unlocks /boot on boot; keyfile is embedded in initramfs so as not to have to enter passphrase again
  • Optional swap partition, also encrypted
  • Assumes BIOS installation; modify for UEFI



Download the live Void ISO.

Additionally download sha256sums.txt and its associated signature file sha256sums.txt.sig.


First check the GPG signature of sha256sums.txt:

$ gpg --keyserver-options auto-key-retrieve --verify sha256sums.txt.sig

See [1] for the key ID and fingerprint.

Now verify the checksum of the ISO file:

$ sha256sum -c <(grep void-live-version.iso sha256sums.txt)

Create disk

Create a bootable USB drive by doing the following on an existing Linux installation:

# dd bs=4M if=/path/to/void-live-version.iso of=/dev/sdx status=progress && sync

where /dev/sdx is the USB drive.


Now boot from the USB drive.


Connect to the internet

If you have a wireless connection do the following.

A list of interfaces can be found with:

# ip link

Then connect to a wifi network with:

# wpa_supplicant -B -i interface -C/run/wpa_supplicant
# wpa_cli
> scan
> scan_results
> add_network
> set_network 0 ssid "SSID"
> set_network 0 psk "passphrase"
> enable_network 0
> quit

For both wired and wireless connections, get an ip address:

# dhcpcd

Then, check your connection with:

# ping voidlinux.eu

Update system clock

# ntpd -u ntp:ntp

Partition the disk

First install gptfdisk:

# xbps-install gptfdisk

Partition the disk:

# gdisk /dev/sda

Create at least one partition for your system and a swap partition. A BIOS boot partition, type EF02 is needed as well.

  • This guide assumes your disk is at /dev/sda with the main partition at /dev/sda1 and the swap partition at /dev/sda2. Change if needed.
  • Do not mark the swap partition as swap if it is going to be encrypted. Instead, use type 8300, the code for a normal Linux partition.

See gdisk(8).

Create filesystems and mount

To create an encrypted system do:

# cryptsetup lukFormat /dev/sda1
# cryptsetup open /dev/sda1 cryptroot
# mkfs.btrfs /dev/mapper/cryptroot
# mount /dev/mapper/cryptroot /mnt

To create a regular (not encrypted) system, do:

# mkfs.btrfs /dev/sda1
# mount /dev/sda1 /mnt

See cryptsetup(8), mkfs.btrfs(8), and mount(8).

Create btrfs subvolumes and remount

For example:

# btrfs subvolume create /mnt/@void
# btrfs subvolume create /mnt/@home
# umount /mnt
# mount -o compress=lzo,subvol=@void /mnt
# mkdir -p /mnt/home
# mount -o compress=lzo,subvol=@home /mnt/home

See btrfs-subvolume(8).


Install needed packages

For a glibc system do:

# xbps-install -S -R http://repo.voidlinux.eu/current -r /mnt base-system grub

For a musl system do:

# export XBPS_ARCH=x86_64-musl
# xbps-install -S -R http://repo.voidlinux.eu/current/musl -r /mnt base-system grub
Tip: Append any additional packages you desire to the end of this line, or install later while in the chroot environment.
Note: For an encrypted system, be sure to append cryptsetup to the list of packages.


Modify crypttab for encrypted swap

This section is only needed if using an encrypted system and only supports suspend-to-RAM and not suspend-to-disk.

Uncomment the line starting with swap in /mnt/etc/crypttab. Then change the device column to the id of the swap partition:

# find -L /dev/disk/by-id -samefile /dev/sda2
# <name>       <device>                          <password>              <options>
swap           /dev/disk/by-id/swap-partition-id /dev/urandom            swap
Warning: Using a swap file instead of a swap partition will result in data loss on a btrfs system.

Create fstab

# <spec>     <file>     <vfstype>    <mntops>                        <freq> <passno>
UUID=UUID    /          btrfs        rw,compress=lzo,subvol=@void    0 0
UUID=UUID    /home      btrfs        rw,compress=lzo,subvol=@home    0 0
swapdevice   none       swap         defaults                        0 0
  • For a low-end SSD, the ssd_spread mount option may improve performance with btrfs.
  • The noatime mount option may significantly improve performance with btrfs.
See btrfs(5).

For an encrypted system UUID is the UUID of the decrypted partition:

# blkid --match-tag UUID /dev/mapper/cryptroot

Additionally swapdevice corresponds with the line in /etc/crypttab, so set it to /dev/mapper/swap.

For a regular system, it is of the root partition:

# blkid --match-tag UUID /dev/sda1

Additionally swapdevice is the swap partition, and can be specified as UUID=UUID, where UUID is

# blkid --match-tag UUID /dev/sda2


# mount -t proc proc /mnt/proc
# mount -t sysfs sys /mnt/sys
# mount -o bind /dev /mnt/dev
# mount -t devpts pts /mnt/dev/pts
# cp -L /etc/resolv.conf /mnt/etc/
# cd /mnt
# chroot /mnt /bin/bash

Set locale

If using a glibc installation, uncomment the needed locales in /etc/default/libc-locales. Then do:

# xbps-reconfigure -f glibc-locales

Set the timezone

# ln -sf /usr/share/zoneinfo/Region/City /etc/localtime

Set hardware clock from system clock

# hwclock --systohc

Set hostname

/etc/hosts	localhost.localdomain	localhost
::1		localhost.localdomain	localhost	hostname.localdomain	hostname

Setup root user

# passwd
# chown root:root /
# chmod 755 /
# chsh -s /bin/bash

Add normal user

# useradd -m -G wheel,users,audio,video,cdrom,input user
# passwd user

Open the sudoers file and uncomment the wheel group:

# visudo

Generate keyfile for intramfs

This section is only needed for an encrypted system.

# dd bs=512 count=4 if=/dev/urandom of=/crypto_keyfile.bin
# chmod 000 /crypto_keyfile.bin
# chmod 600 /boot/initramfs-*
# cryptsetup luksAddKey /dev/sda1 /crypto_keyfile.bin
Note: This keyfile should be used to automate unlocking the root partition only if GRUB unlocks the partition with /boot using a passphrase first. Do not use a keyfile if you use a separate /boot partition that is not encrypted.

Generate initramfs

For an encrypted system with a key file, generate your initramfs, embedding the kefyile:

# dracut --install /crypto_keyfile.bin --kver kver
Note: Add --install /crypto_keyfile.bin to an alias to automatically embed the key in future kernel updates.

For a regular system or an encrypted system with an unencrypted boot partition, do:

# dracut --kver kver

kver is the version of the linux kernel found by looking in /usr/lib/modules.

In any case, reconfigure the linuxkver package:

# xbps-reconfigure linuxkver

Configure and install GRUB

Use dracut --print-cmdline to generate your boot line and add it to /etc/default/grub:


If using an encrypted boot partition, you also need:


If you are using an embedded initramfs keyfile, append rd.luks.key=/crypto_keyfile.bin:/ to GRUB_CMDLINE_LINUX.

  • Append rd.luks.all-discards to GRUB_CMDLINE_LINUX to allow trimming if using an SSD with an encypted system.
  • Setup a cron job to run /usr/bin/fstrim -a weekly to periodically trim an SSD.

Now run:

# grub-install /dev/sda
# grub-mkconfig -o /boot/grub/grub.cfg

Exit chroot and reboot

# exit
# reboot

When you reboot you should be prompted for your LUKS password if you decided to encrypt the system. See User:Rdeckard/Post installation.