About

Void is an independent Linux distribution developed in the spare time of a handful of developers. We do this for fun and hope that our work will be useful to others. Void is generally considered stable enough for daily use, and breaking changes are few and far between.

Some things that make Void unique in the crowded world of Linux distributions include our package manager, XBPS, which is developed in-house and is extremely fast. XBPS performs checks when installing updates to ensure that libraries aren't moved to incompatible versions, thus preventing a random update from breaking your system. XBPS is developed at https://github.com/void-linux/xbps/.

Void is also set apart from other projects by our first class support of the musl C library, which focuses on standards compliance and correctness. The musl C project allows us to also build very resilient systems as it is practical to statically link certain components on our musl flavors whereas it would not be practical to do so with glibc.

Along with our support of musl C, we also use the LibreSSL libraries instead of the more traditional OpenSSL counterpart. LibreSSL developers have shown time and time again that they are dedicated to the security, quality, and maintainability of this critical library.

A final distinguishing characteristic of Void is our choice of program for init(8). Void Linux boots with smarden runit, a very small service supervision system. The small codebase of runit allows us to support a second libc without significant effort, something that would not have been possible with other options available today. You can learn more about runit on its website http://smarden.org/runit/.

History

Knowledge of the ancients...

This section includes the history of void, important milestones and happenings that happened, and why things are the way they are.

How to Read the Handbook

Examples

Examples in this guide may have snippets of commands to be run in your shell. When you see these, any line beginning with $ is run as your normal user. Lines beginning with # are run as root. After either of these lines, there may be example output from the command.

Installation

This section includes all the information you could ever want to know about the process of installing Void in the abstract. For specific guides, see the Guides subsection.

Base System Requirements

Void can be installed on very minimalist hardware, though we recommend the following minimums for most installations:

Architecture CPU RAM Storage
x86_64-glibc EM64T 96MB 350MB
x86_64-musl EM64T 96MB 350MB
i686-glibc Pentium 4 (SSE2) 96MB 350MB

Note: Flavor installations require more resources. How much more depends on the flavor.

Void is not available for i386, i486, or i586 architectures.

It is highly recommended to have a network connection available during install to download updates, but this is not required. ISO images contain installation data on-disc and can be installed without network connectivity.

Live Installer Images

Void releases include two types of images: base images and "flavor" images. Both types of image, and the different flavor images, are described below.

Base Images

Void provides installer images containing a base set of utilities, an installer program, and package files to install a Void base system. Images are provided for glibc based systems on both i686 and x86_64 processors, as well as musl based systems on x86_64-compatible processors.

Flavor Images

In addition to the base image, Void provides additional "flavors" which each include a full desktop environment and web browser, and are pre-configured with basic applications for that system. The install process for each of these images is the same as the base image. The flavor images only differ from the base image by which packages are included and installed.

Note: we encourage Linux beginners to try one of the flavor images. Users comfortable with a more advanced setup may prefer to install Void from a base image.

Comparison of Flavor Images

Here's a quick overview of the main components and applications included with each flavor:

Enlightenment Cinnamon LXDE LXQT MATE XFCE
Window Manager Enlightenment Window Manager Mutter (Muffin) Openbox Openbox Metacity (Macro) xfwm4
File Manager Enlightenment File Manager Nemo PCManFM PCManFM-Qt Caja Thunar
Web Browser Firefox ESR Firefox ESR Firefox ESR QupZilla Firefox ESR Firefox ESR
Terminal Terminology gnome-terminal LXTerminal QTerminal MATE terminal xfce4-Terminal
Document Viewer - - - - Atril (PS/PDF) -
Plain text viewer - - - - Pluma Mousepad
Image viewer - - GPicView LXImage Eye of MATE Ristretto
Archive unpacker - - - - Engrampa -
Other Mixer, EConnMan (connection manager), Elementary Test - LXTask (task manager), MIME type editor Screen grabber Screen grabber, file finder, MATE color picker, MATE font viewer, Disk usage analyzer, Power statistics, System monitor (task manager), Dictionary, Log file viewer Bulk rename, Orage Globaltime, Orage Calendar, Task Manager, Parole Media Player, Audio Mixer, MIME type editor, Application finder

Downloading Images

The most recent live images can be downloaded from https://alpha.de.repo.voidlinux.org/live/current/. Previous releases can be found under https://alpha.de.repo.voidlinux.org/live/, organized by date.

Verify Images

Each image releases's directory contains two files used to verify the image(s) you download. First, there is a sha256sums.txt file containing image checksums to verify the integrity of the downloaded images. Second is the sha256sums.txt.sig file, used to verify the authenticity of the checksums.

We want to verify both the image's integrity and authenticity, so for this, we want to download both files:

$ wget http://alpha.de.repo.voidlinux.org/live/current/sha256sums.txt{,.sig}

Verify Image Integrity

You can verify the integrity of a downloaded file using sha256sum(1) with the sha256sums.txt file we downloaded above. The following sha256sum command will check (-c) the integrity of only the image(s) you've downloaded:

$ sha256sum -c --ignore-missing sha256sums.txt
void-live-x86_64-musl-20170220.iso: OK

This verifies that the image is not corrupt.

Verify Image Authenticity

To verify that the downloaded sha256sums.txt file is the one that the Void Linux maintainers published and signed, we use PGP. For this, we need the sha256sums.txt.sig downloaded above.

The file is signed with the Void Images key:

  • Signer: Void Linux Image Signing Key <images@voidlinux.eu>
  • KeyID: B48282A4
  • Fingerprint: CF24 B9C0 3809 7D8A 4495 8E2C 8DEB DA68 B482 82A4

You can use gpg(1) to receive the key from a keyserver using the command in the following example. You can also download it from https://alpha.de.repo.voidlinux.org/live/current/void_images.asc.

$ gpg --recv-keys B48282A4
gpg: requesting key B48282A4 from hkp server keys.gnupg.net
gpg: key B48282A4: public key "Void Linux Image Signing Key <images@voidlinux.eu>" imported
gpg: no ultimately trusted keys found
gpg: Total number processed: 1
gpg:               imported: 1  (RSA: 1)

With the key stored locally, you can use gpg(1) verify the signature of sha256sums.txt using the sha256sums.txt.sig file:

$ gpg --verify sha256sums.txt.sig 
gpg: assuming signed data in `sha256sums.txt'
gpg: Signature made Sat Oct  7 17:18:35 2017 CDT using RSA key ID B48282A4
gpg: Good signature from "Void Linux Image Signing Key <images@voidlinux.eu>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: CF24 B9C0 3809 7D8A 4495  8E2C 8DEB DA68 B482 82A4

This verifies that the signature for the checksums is authentic. In turn, we can assert that the downloaded images are also authentic if their checksums match.

Prepare Installation Media

After downloading a live image, it must be written to bootable media, such as a USB drive, SD card, or CD/DVD.

Create a Bootable USB Drive or SD Card on Linux

Identify the Device

Before writing the image, identify the device you'll write it to. You can do this using fdisk(8). After connecting the storage device, identify the device path by running:

# fdisk -l
Disk /dev/sda: 7.5 GiB, 8036286464 bytes, 15695872 sectors
Disk model: Your USB Device's Model
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes

In the example above, the output shows the USB device as /dev/sda. On Linux, the path to the device will typically be in the form of /dev/sdX (where X is a number) for USB devices, /dev/mmcblkX for SD cards, or other variations depending on the device. You can use the model and size (7.5GiB above, after the path) to identify the device if you're not sure what path it will have.

Once you've identified the device you'll use, ensure it's not mounted by unmounting it with umount(8):

# umount /dev/sdX
umount: /dev/sdX: not mounted.

Write the Live Image

The dd(1) command can be used to copy a live image to a storage device. Using dd, write the live image to the device:

Warning: this will destroy any data currently on the referenced device. Exercise caution.

# dd bs=4M if=/path/to/void-live-ARCH-DATE-VARIANT.iso of=/dev/sdX
90+0 records in
90+0 records out
377487360 bytes (377 MB, 360 MiB) copied, 0.461442 s, 818 MB/s

dd won't print anything until it's completed (or if it failed), so depending on the device, this can take a few minutes or longer.

Finally, ensure all data is flushed before disconnecting the device:

$ sync

The number of records, amount copied, and rates will all vary depending on the device and the live image you chose.

Burning to a CD or DVD

Any disk burning application should be capable of writing the .iso file to a CD or DVD. The following free software applications are available (cross-platform support may vary):

Note: with a CD or DVD, live sessions will be less responsive than with a USB or hard drive.

Partitioning Notes

Partitioning for a modern Linux distribution is generally very simple, however the introduction of GPT and UEFI booting does bring new complexity to the process. When creating your new partition table you will need a partition for the root filesystem, along with a swap partition and possibly another partition or two to facilitate booting, if required.

The following sections will detail the options for partition configuration.

BIOS System Notes

It is recommended that you create an MBR partition table if you are using a BIOS boot system. This will limit the number of partitions you create to four. It is possible to install a GPT partition table on a BIOS system, but grub will need a special partition to boot properly.

UEFI System Notes

UEFI users are recommended to create a GPT partition table. UEFI booting with grub also requires a special partition of the type EFI System with a vfat filesystem mounted at /boot/efi. A reasonable size for this partition could be between 200MB and 1GB. With this partition setup during the live image installation, the installer should successfully set up the bootloader automatically.

Swap Partitions

A swap partition is not strictly required, but recommended for systems with low RAM. If you want to use hibernation, you will need a swap partition. The following table has recommendations for swap partition size.

System RAM Recommended swap space Swap space if using hibernation
< 2GB 2x the amount of RAM 3x the amount of RAM
2-8GB Equal to amount of RAM 2x the amount of RAM
8-64GB At least 4GB 1.5x the amount of RAM
64GB At least 4GB Hibernation not recommended

Boot Partition (Optional)

On most modern systems, a separate /boot partition is no longer necessary to boot properly. If you choose to use one, remember that Void does not remove old kernels after updates by default and each image will take at least 20MB, so plan accordingly.

Other Partitions

It is fine to install your system with only a large root partition, but you may create other partitions if you want. One helpful addition could be a separate partition for your /home directory. This way if you need to reinstall Void (or another distribution) you can save the data and configuration files in your home directory for your new system.

Installation Guide

Once you have downloaded a Void image to install and prepared your install media, you are ready to install Void Linux.

Note: before you begin installation, you should determine whether your machine boots using BIOS or UEFI. This will affect how you plan partitions. See Partitioning Notes for more detail.

Booting

Boot your machine from the install media you created. If you have enough RAM, there is an option on the boot screen to load the entire image into ram, which will take some time but speed up the rest of the install process.

Once the live image has booted, log in as root with password voidlinux and run:

# void-installer

The following sections will detail each screen of the installer.

Keyboard

Select the keymap for your keyboard; standard "qwerty" keyboards will generally use the "us" keymap.

Network

Select your primary network interface. If you do not choose to use DHCP, you will be prompted to provide an IP address, gateway, and DNS servers.

If you intend to use a wireless connection during the installation, you may need to configure it manually using wpa_supplicant and dhcpcd manually before running void-installer.

Source

To install packages provided on the install image, select Local. Otherwise, you may select Network to download the latest packages from the Void repository.

Note: if you are installing a desktop environment from a ''flavor'' image, you MUST choose Local for the source!

Hostname

Select a hostname for your computer (that is all lowercase, with no spaces.)

Locale

Select your default locale settings. This option is for glibc only, as musl does not currently support locales.

Timezone

Select your timezone based on standard timezone options.

Root Password

Enter and confirm your root password for the new installation. The password will not be shown on screen.

User Account

Choose a login (default void) and a descriptive name for that login. Then enter and confirm the password for the new user. You will then be prompted to verify the groups for this new user. They are added to the wheel group by default and will have sudo access.

Bootloader

Select the disk to install a bootloader on when Void is installed. You may select none to skip this step and install a bootloader manually after completing the installation process. If installing a bootloader, you will also be asked whether or not you want a graphical terminal for the GRUB menu.

Partition

Next, you will need to partition your disks. Void does not provide a preset partition scheme, so you will need to create your partitions manually with cfdisk(8). You will be prompted with a list of disks. Select the disk you want to partition and the installer will launch cfdisk for that disk. Remember you must write the partition table to the drive before you exit the partition editor.

UEFI users are recommended to select GPT for the partition table and create a partition (typically between 200MB-1GB) of type EFI System which will be mounted at /boot/efi.

BIOS users are recommended to choose MBR. Advanced users may use GPT but will need to create a special BIOS partition for grub to boot.

See the Partitioning Notes for more details about partitioning your disk.

Filesystems

Create the filesystems for each partition you have created. For each partition you will be prompted to choose a filesystem type, whether you want to create a new filesystem on the partition, and a mount point, if applicable. When you are finished, select Done to return to the main menu.

UEFI users will need to create a vfat filesystem, and mount it at /boot/efi.

Review Settings

It is a good idea to review your settings before proceeding. Use the right arrow key to select the settings button and hit <enter>. All your selections will be shown for review.

Install

Selecting Install from the menu will start the installer. The installer will create all the filesystems selected, and install the base system packages. It will then generate an initramfs and install a GRUB2 bootloader to the bootable partition.

These steps will all run automatically, and after the installation is completed successfully, you can reboot into your new Void Linux install!

Post Installation

See the Post Installation guide for some tips on setting up your new system.

Installation Guides

Got weird hardware or an unusual setup? This is the section for guides about how to install Void on things that it doesn't usually like.

Configuration

Everything from basic network config to where to find tuning constants and basic ricing.

Post Installation

This page contains a common set of tasks to take after installing Void on a new machine.

Updates

Installation media contains a snapshot of packages from the day it was made. After installing and connecting the the network, new systems should be updated:

# xbps-install -Su

This will ensure that your system has applicable security patches and software upgrades that happened after the installation media was created.

Note: XBPS must use a separate transaction to update itself. If your first update includes the package xbps, you will need to run an additional update for the rest of the system.

Services and daemons

Void uses the runit(8) supervision suite to run system services and daemons.

Services are enabled by simply linking them into the /var/service service directory.

# ln -s /etc/sv/<service name> /var/service/

To disable them again you just remove the link.

# rm /var/service/<service name>

Activated services can be controlled with the sv(8) command, following commands are available and can be used like sv <command> <services...>.

  • up to start, down to stop and once to start services once.
  • pause, cont, hup, alarm, interrupt, quit, 1, 2, term and kill to send the corresponding signal.
  • start, stop, reload and restart for LSB init compatibility.

See the sv(8) manual page for further information.

The status command can be used to retrieve the current status of one or more services. It accepts either service names or service directories, which makes it possible to use shell wildcards to retrieve the status for all activated services.

# sv status dhcpcd
run: /var/service/dhcpcd: (pid 659) 561392s
# sv status /var/service/*
run: /var/service/agetty-tty1: (pid 658) 561392s
run: /var/service/agetty-tty2: (pid 639) 561392s
run: /var/service/agetty-tty3: (pid 662) 561392s
run: /var/service/agetty-ttyS0: (pid 650) 561392s
run: /var/service/dhcpcd: (pid 659) 561392s
run: /var/service/nanoklogd: (pid 666) 561391s
run: /var/service/ntpd: (pid 665) 561391s; run: log: (pid 664) 561391s
run: /var/service/opensmtpd: (pid 661) 561392s
run: /var/service/socklog-unix: (pid 646) 561392s; run: log: (pid 645) 561392s
run: /var/service/sshd: (pid 674) 561391s
run: /var/service/udevd: (pid 660) 561392s
run: /var/service/uuidd: (pid 640) 561392s

Extra options can be passed to most services using a conf file in the service directory.

$ cat /etc/sv/sshd/run
#!/bin/sh
ssh-keygen -A >/dev/null 2>&1 # Will generate host keys if they don't already exist
[ -r conf ] && . ./conf
exec /usr/bin/sshd -D $OPTS
# echo 'OPTS="-p 2222"' >>/etc/sv/sshd/conf

Another example is the wpa_supplicant service which has other available variables.

# cat /etv/sv/wpa_supplicant/run
#!/bin/sh
[ -r ./conf ] && . ./conf
exec 2>&1
exec wpa_supplicant -c ${CONF_FILE:=/etc/wpa_supplicant/wpa_supplicant.conf} -i ${WPA_INTERFACE:=wlan0} ${OPTS:=-s}
# echo WPA_INTERFACE=wlp3s0 >>/etc/sv/wpa_supplicant/conf

Per user services

Sometimes it would be nice to have user-specific runit services. Services that, for example, open an ssh tunnel as your current user, run a virtual machine, or regularly run daemons on your behalf. The most common way to do this to ask a system-level runsv daemon to start a runsvdir daemon as your user for your personal service directory.

Create a service as /etc/sv/$username/run with the below contents:

#!/bin/sh

UID=$(pwd -P)
UID=${UID##*/}

if [ -d "/home/${UID}/service" ]; then
    chpst -u"${UID}" runsvdir /home/${UID}/service
fi

Then you can create runit services and symlink them under ${HOME}/service and then runit will take care of starting and restarting those services for you.

One important caveat: if any services you have need group permissions instead of just your user permissions, you will want to append those groups in a colon separated list to your username, such as /etc/sv/anon:void1:void2:void3/run instead of just /etc/sv/anon/run.

Cron

Void Linux comes without a default cron daemon, you can choose one of multiple cron implementations, by installing the package and enabling the system service.

Available choices include cronie, dcron, fcron and more.

As alternative to the standard cron implementations you can use something like snooze or runwhen which go hand in hand with service supervision.

Logging

Syslog

The default installation comes with no syslog daemon, there are different implementations available.

socklog is the implementation from the runit(8) author and Void Linux provides a package with some basic configuration for it, this makes it a good choice if you don't know which one to choose.

# xbps-install -S socklog-void # usermod -aG socklog <your username>
# ln -s /etc/sv/socklog-unix /var/service/
# ln -s /etc/sv/nanoklogd /var/service/

Other syslog implementations like rsyslog and metalog are available in the package repository too.

Console

Disabling default ttys

Void Linux enables agetty(8) services for the ttys 1 to 6 by default.

To disable agetty services remove the service symlink and create a down file in the agetty service directory to avoid that updates of the runit-void package re-enable the service.

# rm /var/service/agetty-tty6
# touch /etc/sv/agetty-tty6/down

Shell

Changing users default shell

The default shell for users can be changed with the chsh(1) tool.

$ chsh -s /bin/bash <user name>

Make sure to use the same path to the shell as its in /etc/shells or listed by the chsh(1) list command.

A list of available installed shells can be retrieved with the chsh(1) list command.

$ chsh -l
/bin/sh
/bin/bash
/bin/mksh
/bin/zsh
/bin/rc
/bin/ksh
/bin/oksh
/bin/yash

Following packages are available in the package repository and provide usable shells.

  • bash
  • dash
  • elvish
  • es
  • fish-shell
  • heirloom-sh
  • ksh
  • mksh
  • oksh
  • posh
  • rc
  • tcsh
  • yash
  • zsh

Kernel

Kernel series

Void Linux provides many kernel series in the default repository,

$ xbps-query --regex -Rs 'linux[34]' | grep -Ev '(dbg|headers)'
[-] linux3.14-3.14.79_1           The Linux kernel and modules (3.14 series)
[-] linux3.18-3.18.60_1           The Linux kernel and modules (3.18 series)
[-] linux4.1-4.1.41_1             The Linux kernel and modules (4.1 series)
[-] linux4.10-4.10.17_1           The Linux kernel and modules (4.10 series)
[*] linux4.11-4.11.11_1           The Linux kernel and modules (4.11 series)
[-] linux4.12-4.12.3_1            The Linux kernel and modules (4.12 series)
[-] linux4.13-4.13.0rc1_1         The Linux kernel and modules (4.13 series)
[-] linux4.4-4.4.76_1             The Linux kernel and modules (4.4 series)
[-] linux4.8-4.8.17_1             The Linux kernel and modules (4.8 series)
[-] linux4.9-4.9.37_1             The Linux kernel and modules (4.9 series)

The linux meta package which is installed by default depends on one of the kernel packages, usually the latest mainline kernel that works with all dkms modules.

Removing old kernels

$ vkpurge list
3.8.2_1

You can now remove a specific kernel version like 3.8.2_1 or all which removes all kernels expect the latest kernel of each series and the kernel that is currently booted.

# vkpurge rm 3.8.2_1
# vkpurge rm all

Kernel modules

Loading kernel modules at boot

To load kernel modules at boot time, a .conf file like /etc/modules-load.d/virtio.conf can be created.

# load virtio-net
virtio-net

Blacklisting kernel modules

There are two different methods to blacklist kernel modules, for the initramfs and for the booted system. Some modules are loaded by the initramfs very early in the boot process, those have to be blacklisted in the initramfs.

You can blacklist modules with a .conf file like /etc/modprobe.d/radeon.conf.

blacklist radeon

dracut

To blacklist modules from being included in a dracut initramfs you need to create a .conf file like /etc/dracut.conf.d/radeon.conf.

omit_drivers+=" radeon "

Now you need to regenerate the initramfs to make the changes take effect on the next reboot.

# dracut --force

mkinitcpio

XXX: add example of blacklisting kernel modules for mkinitcpio

Kernel hooks

Void Linux provides directories for kernel hooks in /etc/kernel.d/{pre-install,post-install,pre-remove,post-remove}.

Bootloaders like grub, gummiboot and lilo use those hooks to update the bootmenu. Initramfs tools like dracut and mkinitcpio use the hooks to generate initramfs files for newly installed kernels.

Dynamic Kernel Module Support (dkms)

There are kernel modules that are not part of the linux source tree that are build at install time using dkms and kernel hooks.

$ xbps-query -Rs dkms
[-] acpi_call-dkms-1.2.0_2             Kernel module allowing calls to ACPI methods through /proc/acpi/call
[-] dkms-2.4.0_2                       Dynamic Kernel Modules System
[-] exfat-dkms-1.2.8_2                 Exfat kernel driver (nofuse)
[-] spl-0.6.5.10_1                     Solaris Porting Layer -- userland and kernel modules (using DKMS)
[-] tp_smapi-dkms-0.42_2               IBM ThinkPad hardware functions driver
[-] virtualbox-ose-dkms-5.1.24_1       General-purpose full virtualizer for x86 hardware - kernel module sources for dkms
[-] virtualbox-ose-guest-dkms-5.1.24_1 General-purpose full virtualizer for x86 hardware - guest addition module source for dkms
[-] zfs-0.6.5.10_1                     Z File System -- userland and kernel modules (using DKMS)
[-] zfs-32bit-0.6.5.10_1               Z File System -- userland and kernel modules (using DKMS) (32bit)
[-] broadcom-wl-dkms-6.30.223.271_6    Broadcom proprietary wireless drivers for Linux - DKMS kernel module
[-] catalyst-dkms-15.302_2             AMD catalyst driver 15.12 for Linux - DKMS kernel module
[-] nvidia-dkms-381.22_2               NVIDIA drivers for linux (long-lived series) - DKMS kernel module
[-] nvidia304-dkms-304.135_4           NVIDIA drivers (For GeForce 5 FX, 6, 7, 8 series) - DKMS kernel module
[-] nvidia340-dkms-340.102_5           NVIDIA drivers (GeForce 8, 9, 9M, 100, 100M, 200, 300 series) - DKMS kernel module

cmdline

grub

Kernel command line arguments can be added through the grub bootloader by editing /etc/default/grub and changing the GRUB_CMDLINE_LINUX_DEFAULT variable and then regenerating the grub configuration.

# vi /etc/default/grub
# grub-mkconfig -o /boot/grub/grub.cfg

dracut

Dracut can be configured to add additional cmdline arguments to the kernel by creating a configuration file and regenerating the initramfs, make sure to reconfigure the right kernel version like linux4.12 as example.

# mkdir -p /etc/dracut.conf.d
# echo 'kernel_cmdline+="<extra cmdline arguments>"' >> /etc/dracut.conf.d/cmdline.sh
# xbps-reconfigure -f linux4.12

Network

The Network configuration in Void Linux can be done with different methods, the default installation comes with dhcpcd(8).

Interface names

In newer versions udev changed the well known traditional linux naming scheme (eth0, eth0, wlan0, ...).

This behaviour can be reverted by adding net.ifnames=0 to the kernel cmdline.

Static configuration

A static network in Void Linux can be configured with ip(8).

A simple way to configure the static network at boot is to add the necessary ip(8) commands to the /etc/rc.local file.

# Static IP configuration via iproute
ip link set dev eth0 up
ip addr add 192.168.1.2/24 brd + dev eth0
ip route add default via 192.168.1.1

dhcpcd

To run dhcpcd(8) on all interfaces you can enable the dhcpcd service.

# ln -s /etc/sv/dhcpcd /var/service

If you want to run dhcpcd just on a specific interface you can use the dhcpcd-eth0 service if this matches your interface name. Otherwise you can just copy dhcpcd-eth0 and change it to match your interface.

$ ip link show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
        link/ether ff:ff:ff:ff:ff:ff brd ff:ff:ff:f
# cp -R /etc/sv/dhcpcd-eth0 /etc/sv/dhcpcd-enp3s0
# sed -i 's/eth0/enp3s0/' /etc/sv/dhcpcd-enp3s0/run
# ln -s /etc/sv/dhcpcd-enp3s0 /var/service

For more information on configuring dhcpcd see dhcpcd.conf(5)

wpa_supplicant

The wpa_supplicant package is installed by default on the base system and includes utilities to configure wireless interfaces and, more specifically, to handle wireless security protocols.

wpa_supplicant(8) is a daemon that manages wireless interfaces based on a wpa_supplicant.conf(5) configuration files. wpa_passphrase(8) and wpa_cli(8) are frontends to manage the configuration files and the running service.

Configuring wpa_supplicant

First, you must create a configuration file for your interface:

$ cp /etc/wpa_supplicant/wpa_supplicant.conf /etc/wpa_supplicant/wpa_supplicant-<device>.conf

WEP Configuration

For WEP configuration, you can just add the following lines to your device's wpa-supplicant.conf :

# Default configuration file for wpa_supplicant.conf(5).

ctrl_interface=/run/wpa_supplicant
ctrl_interface_group=wheel
eapol_version=1
ap_scan=1
fast_reauth=1
update_config=1

# Add here your networks.
network={
    ssid="MYSSID"
    key_mgmt=NONE
    wep_key0="YOUR AP WEP KEY"
    wep_tx_keyidx=0
    auth_alg=SHARED
}

WPA-PSK encryption

For WPA-PSK encryption, we must generate a pre shared key with wpa_passphrase(8). To do so, run the following command:

$ wpa_passphrase <MYSSID> <key>

You must append the output to your wpa_supplicant.conf file like so:

$ wpa_passphrase <MYSSID> <key> >> /etc/wpa_supplicant/wpa_supplicant-<device_name>.conf

The resulting file should look something like this:

# Default configuration file for wpa_supplicant.conf(5).

ctrl_interface=/run/wpa_supplicant
ctrl_interface_group=wheel
eapol_version=1
ap_scan=1
fast_reauth=1
update_config=1

# Add your networks here.
network={
    ssid="MYSSID"
    #psk="YOUR AP KEY"
    psk=a8c34100ab4e5afac33cad7184d45a29ee0079001577d579bec6b74e4d7b5ac8
}

Running wpa_supplicant

There are two options for running wpa_supplicant.conf(5). You may simply run dhcpcd(8), which will start processes automatically for your wireless interfaces, or you can run wpa_supplicant manually.

Starting through dhcpcd hooks

You may run dhcpcd(8), which has hooks to start wpa_supplicant(8) automatically.

See dhcpcd for more information on starting/configuring dhcpcd.

Running wpa_supplicant manually

You may start wpa_supplicant.conf(5) manually, if you are not already running dhcpcd(8) :

# wpa_supplicant -B -i <interface_name> -c <path/to/configuration/file>
# dhcpcd <interface_name>

Now you can test the connection:

$ ping google.com

NetworkManager

wicd

Xorg

Drivers

Display managers

Session and seat management

Session and seat management is not necessary for every setup, it is used to provide device access on the fly for the currently active user session.

For desktop environments like Gnome elogind is necessary.

ConsoleKit2

Install ConsoleKit2 and activate its service and make sure the dbus and the cgmanager services are activated too.

# xbps-install -S ConsoleKit2
# ln -s /etc/sv/dbus /var/service/
# ln -s /etc/sv/cgmanager /var/service/
# ln -s /etc/sv/consolekit /var/service/

If you don't use a display manager or your display manager doesn't start a ConsoleKit2 session on its own you need to start a ConsoleKit2 session from your .xinitrc. ConsoleKit2 comes with a xinitrc.d script (/etc/X11/xinit/xinitrc.d/90-consolekit) which sets the STARTUP variable to the appropriate way to start the session.

The following .xinitrc script sources all scripts in /etc/X11/xinit/xinitrc.d and starts the window manager of your choice with a session.

#!/bin/sh
#
# ~/.xinitrc
#
# Executed by startx (run your window manager from here)

if [ -d /etc/X11/xinit/xinitrc.d ]; then
  for f in /etc/X11/xinit/xinitrc.d/*; do
    [ -x "$f" ] && . "$f"
  done
  unset f
fi

exec $STARTUP <window manager>

elogind

# xbps-install -S elogind

Multimedia

Audio setup

To setup audio on your Void Linux system you have to decide if you want to use PulseAudio or just alsa.

Some applications require PulseAudio, especially closed source programs.

ALSA

Install the alsa-utils package make sure your user is part of the audio group to access audio devices.

# xbps-install -S alsa-utils
# usermod -a -G audio <username>

The alsa-utils package comes with the system service /etc/sv/alsa which can be activated to save and restore the state of alsa controls like the volume at shutdown and boot respectively.

If the soundcard you want to use is not the default you can either use kernel module options or the alsa config to change the default card.

The current module order can be retrieved from the procfs filesystem.

$ cat /proc/asound/modules
 0 snd_hda_intel
 1 snd_hda_intel
 2 snd_usb_audio

To use the kernel module options you can create a file like /etc/modprobe.d/alsa.conf with following content.

options snd_usb_audio index=0

Alternatively using the alsa configuration file /etc/asound.conf or the per-user configuration file ~/.asoundrc to set a different card as the default.

defaults.ctl.card 2;
defaults.pcm.card 2;

PulseAudio

PulseAudio depends on a dbus system daemon, make sure its enabled.

# xbps-install -S alsa-utils pulseaudio
# ln -s /etc/sv/dbus /var/service/

The PulseAudio package comes with a services file, which is not necessary in most setups and its discouraged by the PulseAudio maintainers to use the system wide setup.

There are different methods that work with PulseAudio to allow access to the audio devices, the simplest one is to just the audio group alternatively you can use a session manager, like elogind or ConsoleKit2.

Printing

CUPS (C Unix Printing System) is the supported mechanism for connecting to printers on Void Linux. This section explains how to install and configure CUPS.

Installing Printing Packages

The CUPS daemon can be installed by running:

# xbps-install -S cups

Drivers

If the printer is being accessed over the network and supports PostScript or PCL, CUPS alone should be sufficient. However, additional driver packages are necessary for local printer support. The cups-filters package provides driver support for CUPS; it can be installed by running:

Some CUPS drivers contain proprietary or binary-only extensions, these are available only in the nonfree repository and sometimes only for specific architectures.

# xbps-install -S cups-filters

Depending on the hardware in question, additional drivers may be necessary.

Gutenprint drivers

Gutenprint provides support for a considerable amount of printers. These drivers can be installed by running:

# xbps-install -S gutenprint

HP drivers

Printers from Hewlett-Packard require the hplip package, which can be installed by running:

# xbps-install -S hplip

Running the following command will guide you through the driver installation process. The default configuration selections it suggests are typically sufficient.

# hp-setup -i

Brother drivers

For Brother printer support, install the foomatic drivers by running:

# xbps-install -S foomatic-db foomatic-db-nonfree

Configuration Software

CUPS has a built-in web interface that can be used to configure printers, but native GUI options exist and may be better suited depending on the use case.

One such option is the system-config-printer package, which can be installed by running:

# xbps-install -S system-config-printer

Normally this tool would require root privileges to configure printers, but unprivileged access through PolicyKit can be achieved with a helper. This helper can be installed by running:

# xbps-install -S cups-pk-helper

Configuring a New Printer

Enable the CUPS service:

# ln -s /etc/sv/cupsd /var/service/

Wait until the service is marked available:

# sv status cupsd

Then, power the printer on and connect it.

There are multiple ways to configure a CUPS printer. The standard is to use the web interface, but other mechanisms exist as well.

Web interface

To configure the printer using the CUPS web interface, navigate to http://localhost:631 in a browser. Under the "Administration" tab, select "Printers > Add Printer".

Command line

The lpadmin(8) tool may be used to configure a printer using the command line.

Graphical interface

To configure the printer using a native GUI interface, run the following:

# xbps-install -S system-config-printer
# system-config-printer

This command does not need to be run as root if PolicyKit is in use and cups-pk-helper is installed.

While system-config-printer is shown here, your desktop environment may have a native printer dialog which may be found by consulting the documentation for your DE.

Maintenance

Void Linux is generally fairly low maintenance. As a general rule the system should be updated regularly, and when running Void Linux in production, services need to be restarted periodically to upgrade to the latest version.

This section contains detailed information on maintaining Void Linux long term.

Updating

Like any other system it is important to keep Void Linux up to date.

In general Void should be updated with an XBPS invocation:

# xbps-install -Su

Note: XBPS must use a separate transaction to update itself. If your first update includes the package xbps, you will need to run an additional update for the rest of the system.

Restarting Services

If you are installing Void in production or otherwise have long lived services, its important to note that XBPS does not restart services when they are updated. This task is left to the administrator so they can orchestrate maintenance windows, ensure reasonable backup capacity, and generally be present for service upgrades.

To find processes running different versions than are present on disk, use the xcheckrestart tool provided by the xtools package:

# xbps-install -S xtools
$ xcheckrestart
11339 /opt/google/chrome/chrome (deleted) (google-chrome)

xcheckrestart will print out the PID, path to the executable, status of the path that was launched (almost always deleted) and the process name.

xcheckrestart can and should be run as an unprivileged user.

Kernel Panic after Update

Your system likely ran out of space in /boot. XBPS installs kernels and requests that hooks such as DKMS and Dracut be run, but it doesn't remove kernels that are obsolete. This is left as a task for the administrator to permit the retention of obsolete but still booted or known working kernels.

Remove kernels with vkpurge(8).

Packages

Packages are managed by XBPS, the in-house package manager for Void Linux.

This section contains information about using the package manager and pointers to more advanced information on building packages.

General Package Management

General package management is done with xbps-query, xbps-install, and xbps-remove.

Most questions can be answered by consulting the man pages for these tools.

Building from Source

Building packages from source is an advanced topic that is best left to the documentation in the void-packages repository.

This repository can be found at http://github.com/void-linux/void-packages/.

Finding files

To search a file in packages you can use one of two methods

The xtools package contains the xlocate utility that works like locate(1) but for all files in the void package repository.

# xbps-install -Su xtools

$ xlocate -S
From https://repo.voidlinux.org/xlocate/xlocate +
16d97bfe86...2ad1a4a8d1 master -> master (forced update)
$ xlocate fizz
nim-0.17.0_1 /usr/lib/nim/examples/fizzbuzz.nim ponysay-3.0.2_1
/usr/share/ponysay/ponies/cherryfizzy.pony ->
/usr/share/ponysay/ponies/cherrycola.pony ponysay-3.0.2_1
/usr/share/ponysay/ttyponies/cherryfizzy.pony ->
/usr/share/ponysay/ttyponies/cherrycola.pony supertux2-data-0.5.1_1
/usr/share/supertux2/sounds/fizz.wav

It is also possible to use xbps-query to find files, but this is strongly discouraged. It requires xbps-query to download parts of every package to find the file requested. xlocate, on the other hand, is able to query a locally cached index of all files, so no network is required to query for files.

$ xbps-query -Ro /usr/bin/xlocate
xtools-0.46_1: /usr/bin/xlocate (regular file)

Repositories

Repositories are the heart of the xbps package system. Repositories can be locally or remotely available. A repository contains binary package files, which may have signatures, and a data file named $ARCH-repodata (i.e. x86_64-repodata) which may also be signed.

Note that, while local repositories do not require signatures, remote repositories must be signed.

Official Repositories

Void provides other official repositories, which are maintained by the Void project, but not installed in the default configuration:

  • debug: contains debugging symbols for packages
  • multilib: contains 32-bit libraries for 64-bit systems (glibc only)
  • multilib/nonfree: contains non-free multilib packages
  • nonfree: contains software packages with non-free licenses

The next sections provide information on installing repositories, and summaries of the different repositories offered.

Installing Repositories

Void provides official repositories that may be installed via a package. For example, to install the nonfree repository, install the package void-repo-nonfree:

# xbps-install -S void-repo-nonfree

These packages only install a repository configuration file in /usr/share/xbps.d.

debug

Void Linux packages come without debugging symbols, if you want to debug software or look at a coredump you will need the debugging symbols. These packages are contained in the debug repo. Install the void-repo-debug package to enable this repository.

Installing debugging symbols

To get debugging symbols for packages, activate the void-repo-debug repo. Once enabled, symbols may be obtained for package by installing package-dbg.

# xbps-install -S <package>-dbg

Finding debug dependencies

The xtools package contains the xdbg utility to retrieve a list of debug packages including dependencies for a package.

$ xdbg bash
bash-dbg
glibc-dbg
# xbps-install -S $(xdbg bash)

multilib

The multilib repository provides 32-bit packages as a compatibility layer inside a 64-bit system and is available through the package void-repo-multilib.

These repositories are only available for x86_64 systems running the glibc C library.

multilib/nonfree

The multilib/nonfree repository (available through the package void-repo-multilib-nonfree) provides additional 32-bit packages which have non-free licenses. See nonfree for more information about why these packages are separated.

nonfree

Void has a nonfree repository for packages that don't have free licenses. Install the void-repo-nonfree package to enable this repository.

Packages can end up in the nonfree repository for a number of reasons:

  • Non-Free licensed software with released source-code.
  • Software released only as redistributable binary packages.
  • Patented technology, which may or may not have an (otherwise) open implementation.

Mirrors

Void Linux maintains mirrors in several geographic regions for you to use. In normal use your traffic will be routed to the nearest mirror to you based on your IP Address. If you would like to directly use a particular mirror you can set this manually. This can also be handy if you are on a different continent than the primary mirror, or if you are not on the same continent as any officially managed mirrors.

Tier 1 mirrors

Tier 1 mirrors sync directly from the build-master and will always have the latest packages available. These repositories are maintained by the Void Linux Infrastructure Team. In rare occasions we may permit a mirror that we don’t manage to sync directly from our primary servers if there are extenuating circumstances.

Tier 2 mirrors

Tier 2 mirrors sync from a nearby tier 1 mirror when possible, but there is no guarantee of a mirror being nearby. These mirrors are not managed by Void nor do they have any specific guarantees for staleness or completeness of packages. Tier 2 mirrors are free to sync only specific architectures and exclude sub-repositories (nonfree/multilib).

Mirror List

Tier 1 mirrors

Repository Location
http://alpha.de.repo.voidlinux.org EU: Germany
http://beta.de.repo.voidlinux.org EU: Germany
http://alpha.us.repo.voidlinux.org USA: Kansas City
http://mirror.clarkson.edu/voidlinux/ USA: New York
http://mirrors.servercentral.com/voidlinux/ USA: Chicago

Tier 2 mirrors

Repository Location
http://mirror.aarnet.edu.au/pub/voidlinux/ AU: Canberra
http://ftp.swin.edu.au/voidlinux/ AU: Melbourne
http://ftp.acc.umu.se/mirror/voidlinux.eu/ EU: Sweden
https://mirrors.dotsrc.org/voidlinux/ EU: Denmark
http://www.gtlib.gatech.edu/pub/VoidLinux/ USA: Atlanta

Changing Mirrors

Repository files define URLs for the repository mirror used. These files are installed by the package manager in /usr/share/xbps.d, but if duplicate files are found in /etc/xbps.d, those values are used instead.

To modify mirror URLs cleanly, copy all the repository configuration files to to /etc/xbps.d and change the URLs in each repository file in /etc/xbps.d.

# mkdir -p /etc/xbps.d
# cp /usr/share/xbps.d/*-repository-*.conf /etc/xbps.d/
# sed -i 's|https://alpha.de.repo.voidlinux.org|<repository>|g' /etc/xbps.d/*-repository-*.conf

After changing the URLs, you must synchronize xbps with the new mirrors:

# xbps-install -S

You should see the new repository URLs while synchronizing. You can also use xbps-query to verify the repository URLs, but only after they have been synchronized:

$ xbps-query -L
 9970 https://alpha.de.repo.voidlinux.org/current (RSA signed)
   27 https://alpha.de.repo.voidlinux.org/current/multilib/nonfree (RSA signed)
 4230 https://alpha.de.repo.voidlinux.org/current/multilib (RSA signed)
   47 https://alpha.de.repo.voidlinux.org/current/nonfree (RSA signed)
 5368 https://alpha.de.repo.voidlinux.org/current/debug (RSA signed)

Restricted Packages

Void offers some packages that are officially maintained, but not distributed. These packages are marked as restricted and must be built from their void-packages template locally.

Packages can be restricted from distribution by either the upstream author or Void. Void reserves the right to restrict distribution of any package for effectively any reason, massive size being the most common. Another common reason is restrictive licensing that does not allow third-party redistribution of source or binary packages.

Building manually

You can use xbps-src in the void-packages repository to build the restricted packages from templates. For instructions on building packages from templates see the void-packages documentation, and specifically the quick setup section of the README.

Remember that the building of restricted packages must be enabled explicitly by setting XBPS_ALLOW_RESTRICTED=yes in your xbps-src configuration (in the etc/conf file in the repository.)

Automated building

There is also a tool, xbps-mini-builder which automates the process of building a list of packages. The script can be called periodically and will only rebuild packages if their templates have changed.

Custom Repositories

Void supports user created repositories available locally, or remotely. This is only recommended for serving custom packages created personally, or packages from another trusted source. The Void project does not support any third party package repositories, and the use of third party software packages poses very serious security concerns, and risks serious damage your system.

Adding custom repositories

To add custom repositories create a file in /etc/xbps.d with the format:

repository=<URL>

Where <URL> is either a local directory or a URL to a remote repository.

For example, to define a remote repository:

# echo 'repository=http://my.domain.com/repo' > /etc/xbps.d/my-remote-repo.conf

Or, to define a local repository:

# echo 'repository=/path/to/repo' > /etc/xbps.d/my-local-repo.conf

Manual pages

Void packages come with manual pages and the default installation includes the mandoc manpage toolset.

The man(1) command can be used to show manual pages.

$ man 1 chroot

The mandoc toolset contains apropos(1) to search for manual pages, apropos(1) uses a database that can be updated and generated with the makewhatis(8) command.

# makewhatis -a
$ apropos chroot
chroot(1) - run command or interactive shell with special root directory
xbps-uchroot(1) - XBPS utility to chroot and bind mount with Linux namespaces
xbps-uchroot(1) - XBPS utility to chroot and bind mount with Linux namespaces
xbps-uunshare(1) - XBPS utility to chroot and bind mount with Linux user namespaces
xbps-uunshare(1) - XBPS utility to chroot and bind mount with Linux user namespaces
chroot(2) - change root directory

There are two extra packages for development and POSIX manuals that are not installed by default.

$ xbps-query -Rs man-pages
[*] man-pages-4.11_1        Linux Documentation Project (LDP) manual pages
[-] man-pages-devel-4.11_1  Linux Documentation Project (LDP) manual pages - development pages
[-] man-pages-posix-2013a_3 Manual pages about POSIX systems
# xbps-install -S man-pages-devel man-pages-posix

Troubleshooting

Although the maintainers make every effort not to break anything, sometimes things go wrong. This section explains how to get yourself out of a jam.

Troubleshooting XBPS

Sometimes the package manager gets in a weird spot and can't fix itself without help. This section documents important fixes and things that can go wrong when working with XBPS.

Static XBPS

In rare cases, it is possible to break the system sufficiently that XBPS can no longer function. This usually happens while trying to do unsupported things with libc, but can also happen when an update contains a corrupt glibc archive or otherwise fails to unpack and configure fully.

In these cases it is possible to recover your system with a separate, statically compiled copy of XBPS.

Obtaining Static XBPS

Statically compiled versions of XBPS are available in all mirrors in the static/ directory. The link below points to the static copies on the primary mirror in Germany:

https://alpha.de.repo.voidlinux.org/static

Download and unpack the latest version, or the version that matches the broken copy on your system (with a preference for the latest copy).

Using Static XBPS

The tools in the static set are identical to the normal ones found on most systems. The only distinction is that these tools are statically linked to the musl C library, and should work on systems where nothing else does. In systems where the platform can no longer boot, it is recommended to chroot in with Void installation media and use the static tools from there, as it is unlikely that even a shell will work correctly on the target system.

Contributing

There's more to running a distribution than just writing code. This section explains how to be an active part of Void.

Contributing to the void-docs project

If you would like to contribute to the void-docs project, the repository is hosted at https://github.com/void-linux/void-docs/. Please follow our style guide and submit a pull-request.

Style Guide

This style guide outlines the standards for contributing to the void-docs project. It is a work in progress.

This section details the specific format of the markdown files to use in the void-docs mdBook.

Formatting

Each line should be less than 80 characters, unless there is special formatting that requires a longer line. Exceptions may include:

  • links which start at the beginning of a new line
  • tables
  • code blocks

Headers

Headers shall only be in the ATX heading format, and are only to be used hierarchically (i.e do not skip from # to ###.)

Commands

Command code-blocks should start with a # or $ character, indicating whether the command should be run as root or a regular user, respectively.

For example:

# xbps-install -Su

And not:

$ sudo xbps-install -Su

And also not:

xbps-install -Su

Links

Auto links (links with the same title as url) should use the following notation:

<https://www.example.com/>

They should not be formatted like this:

[https://www.example.com/](https://www.example.com/)

Case

Filenames and directories should use kebab case when splitting words. For example the filename should be post-install.md not postinstall.md.

Words that are part of trademarks or well known package names are exempt from this rule. Examples include pulseaudio and networkmanager which are well known by their squashed names.

Voice

Prefer the active imperative voice when writing documentation. Consider the following examples:

Now we need to install the CUPS drivers and configure them.

This version is conversational and friendlier, but contains unnecessary language that may not be as clear to an ESL reader.

Install and configure the CUPS drivers, then configure them as shown.

This version contains a clear command to act, and a follow up that shows what will be done next. It is clear both to native English speakers, ESL readers, and to translators.