Installation

0. Boot a base live image of Void and login as root.

1. Set keyboard layout and desired font

The default keyboard layout is us, and the default small font is iso01.16.

Available layouts are located in /usr/share/kbd/keymaps/. You can set one with loadkeys.

Console fonts reside in /usr/share/kbd/consolefonts/. You can set one with setfont.

2. Set up filesystems

You will minimally need to set up a root partition, and an EFI system partition (ESP) under UEFI.

• If you already have an ESP on the target device and want to preserve it (for example, when dual-booting with a different OS on the same drive) you could use it as Void’s ESP as well.
• If you are re-purposing a whole drive, you can wipe all signatures from the device with the wipefs command.

• If wishing to use hibernation, create a swap partition as well.
• The ESP should be at least 200MB in size to allow for multiple kernel installs. Make sure to set the partition type of the ESP accordingly (typically named “EFI System”).
• fdisk handles partition alignment automatically.

• mkfs.vfat, mkfs.ext4 and mkfs.btrfs are some filesystem specific frontends for this purpose.
• For most UEFI implementations the ESP must be formatted as FAT. The appropriate FAT type (FAT16, FAT32) is determined automatically by mkfs.vfat.

d) Finally, mount the created partitions—you can mount the root partition to /mnt/, create the directory /mnt/boot, and then mount the ESP to such directory.

3. Connect to the internet

If you are on a wired network, you will likely already be connected to the internet. Verify this with a tool like ping, for example (hitting Ctrl+C to interrupt it):

# ping voidlinux.org

If you are on a wireless network, the connection will have to be configured:

i) Make sure the interface is not hard or soft blocked. Do the latter using rfkill:

# rfkill unblock wlan

ii) Check that the wireless interface is listed with the ip link command, then set it up:

# ip link set ❬wireless_interface❭ up

iii) Configure the wireless network using wpa_supplicant:

# wpa_passphrase ❬ssid❭ ❬passphrase❭ >> /etc/wpa_supplicant/wpa_supplicant.conf

# wpa_supplicant -B -i ❬wireless_interface❭ -c /etc/wpa_supplicant/wpa_supplicant.conf

iv) Disable dhcpcd's Link-local IPv4 addressing and issue an interface rebind:

# echo 'noipv4ll' >> /etc/dhcpcd.conf

# dhcpcd -n

4. Install Void on the mounted filesystem

Set up the parameters that xbps-install will use to install the new system:

a) Define your preferred main repository mirror from which to download the packages, e.g:

# REPO=https://alpha.us.repo.voidlinux.org/current

Define any other repositories you need—e.g. the non-free repo, for proprietary firmware:

# REPONF=https://alpha.us.repo.voidlinux.org/current/nonfree

b) Set the architecture and C standard library implementation flavor to install, e.g:

# ARCH=x86_64

c) Select the packages to install. It can be as simple as installing the base-system and efibootmgr packages, or something more selective, such as:

Basic components, including base files, XBPS, runit, shell, kernel, firmware and other core utilities and libraries:

# PACKS='base-minimal linux kbd file ncurses libgcc libstdc++

… essential services to manage input, device and time-based events:

> acpid eudev snooze

… along with our selected filesystems’ tools:

> dosfstools e2fsprogs (btrfs-progs)

… utilities to query and configure boot entries and system bus devices:

> efibootmgr pciutils (usbutils)

… those you need to set up networking:

> iproute2 dhcpcd (iwd|wpa_supplicant)

… documentation and utilities to access it:

> mdocml man-pages void-docs

… any extra firmware you need, if using the non-free repo enabling it for the new install:

> (intel-ucode void-repo-nonfree)

… and any additional software you may want to initially install, like an application to easily edit text files and utilities to test network connectivity:

> nano mtr'

Note: AMD device firmware is already included in the kernel meta-package. Microcode updates are applied automatically once configured by XBPS.

d) Issue the installation of the packages to the new root partition mount (here /mnt):

# XBPS_ARCH=$ARCH xbps-install -S -r /mnt -R "$REPO" \

… optionally:

> -R "$REPONF" \

… then:

> $PACKS

5. Chroot into the newly installed system

a) Mount the pseudo-filesystems needed for a chroot:

# mount --rbind /sys /mnt/sys && mount --make-rslave /mnt/sys

# mount --rbind /dev /mnt/dev && mount --make-rslave /mnt/dev

# mount --rbind /proc /mnt/proc && mount --make-rslave /mnt/proc

b) Copy the DNS configuration into the new root in case more packages are to be downloaded:

# cat /etc/resolv.conf > /mnt/etc/resolv.conf

c) And chroot to the new installation:

# chroot /mnt/

Note: Having installed void-docs on the new system, you can now access Void’s documentation directly using that command with the option ”-r“, which displays items as regular man pages.

6. Configure the basics

a) Set the system’s hostname:

# echo ❬system_hostname❭ > /etc/hostname

b) Edit /etc/rc.conf with your text editor of choice, setting the system’s time settings and the console’s default keyboard layout and fonts.

c) If installing a glibc distribution, uncomment desired locales in /etc/default/libc-locales and generate locale files by reconfiguring the glibc-locales package:

# xbps-reconfigure -f glibc-locales

You can then set specific locale options in /etc/locale.conf, as displayed by locale.

d) Set the root password:

# passwd

e) Configure fstab. This can be as simple as adding entries for the root and ESP partitions to the existing file, setting the appropriate parameters for each. You can look up current mount information in /proc/mounts or by using findmnt:

# findmnt -kl -o SOURCE,UUID,TARGET,FSTYPE,OPTIONS --real

# <file system>  	<dir>  		<type>		<options> 			<dump><pass>
# /dev/sda2
UUID=a1b2(...)		/		ext4		defaults			0	1
# /dev/sda1
UUID=9Z8Y(...)		/boot		vfat		defaults,umask=022,utf8		0	2
# /tmp tmpfs
tmpfs 	       		/tmp		tmpfs		defaults,nosuid,nodev 		0	0

f) If you used another mirror in place of the default one for installation, add that to your XBPS configuration by overriding the corresponding system configuration file—e.g:

# echo 'repository=https://alpha.us.repo.voidlinux.org/current' > \

> /etc/xbps.d/00-repository-main.conf

The corresponding name of the non-free repo system file is 10-repository-nonfree.conf.

g) If you had to unblock wireless interfaces with rfkill previously, add the command to /etc/rc.local to do this automatically on system initialization, before services are executed:

# echo 'rfkill unblock wlan' >> /etc/rc.local

7. Set up swap

Setting up swap is required if you will use hibernation, and necessary on systems with low to moderate amounts of physical memory (and otherwise simply prudent).
If you have created a swap partition, start in step d below replacing "/swap" with your swap partition (prefer UUID for the fstab entry). Or else, set up a swap file going through the following steps:

a) If not using btrfs, jump to step b. For btrfs filesystems there is some prior setup to be done:

i) First create a zero length file:

# truncate -s 0 /swap

ii) Then disable COW (copy-on-write) on it:

# chattr +C /swap

iii) And make sure compression is disabled:

# btrfs property set /swap compression none

b) Allocate the swap file, replacing ❬count❭ with the number of MB you wish swap to have:

# dd if=/dev/zero of=/swap bs=1MiB count=❬count❭

c) Set the appropriate permissions to it—it should only be accessible to priviliged processes:

# chmod 600 /swap

d) Set up a Linux swap area on the file:

# mkswap /swap

e) Finally, add an entry for it in fstab:

# echo '/swap none swap sw 0 0' >> /etc/fstab

8. Make the new installation bootable

You can boot the kernel directly as an EFI executable or use a separate bootloader.

To set up the bootloader GRUB, consult the Void documentation with the void-docs command:

# void-docs -r chroot

Note: Many UEFI implementations allow choosing boot entries on startup, which may make using a separate bootloader/manager for multi-booting superfluous.

 

To load the kernel directly as an EFI executable, use efibootmgr:

i) Go through the options in /etc/default/efibootmgr-kernel-hook, enabling modification of EFI entries so that a boot entry is automatically generated on kernel package reconfiguration.

• OPTIONS needs to supply the root partition, in the form ”root=UUID=a1b2(...)“. You can use blkid or lslbk to add the UUID string to the file. Common kernel parameters to add here are ”resume=❬swap_partition❭“ if using hibernation and ”quiet“ if wishing to see fewer log messages during system startup.

• DISK + PART point to the ESP. Due to a potential issue with block device name persistence (where a device sdX may later on surface as sdY) set the DISK parameter dynamically using findmnt, where ❬ESP_dir❭ below is your ESP mount directory (e.g. /boot):
DISK="$(findmnt -enrs -o SOURCE -M ❬ESP_dir❭ | cut -c -8)"

Note that for NVMe drives, the device name will have to be formatted differently.

ii) Add an entry for the system's efivars to fstab, and mount them manually so that the boot entry can be generated in the next step:

# echo 'efivarfs /sys/firmware/efi/efivars efivarfs defaults 0 0' >> /etc/fstab

# mount efivarfs

9. Reconfigure and reboot

Use xbps-reconfigure to ensure all installed packages are set up properly:

# xbps-reconfigure -fa

This also generates a boot entry for the new installation. Review the generated boot configuration with the efibootmgr command, as you may need to update the boot order on first install.

At this point, the installation is complete. exit the chroot, unmount or sync the new filesystems manually to be sure no writes are pending, and reboot the computer with “shutdown -r now”.