Void Handbook

https://docs.voidlinux.org
Admin
This handbook explains how to install, configure, and maintain Void Linux systems, and highlights...
Tokens:71,582
Snippets:1,183
Trust Score:9.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run Void Linux Installer

Source: https://docs.voidlinux.org/installation/live-images/guide.html

After booting the live image, log in as root and execute this command to start the installation process.

```bash
# void-installer

```

--------------------------------

### Install and Run Printer Configuration Tool

Source: https://docs.voidlinux.org/config/print/index.html

Install and launch system-config-printer for a user-friendly printer setup. Root privileges are typically required, but PolicyKit can enable unprivileged use with cups-pk-helper.

```bash
# system-config-printer

```

--------------------------------

### Configure ~/.xinitrc for i3 and xscreensaver

Source: https://docs.voidlinux.org/config/graphical-session/xorg.html

Example of a user's ~/.xinitrc file to start xscreensaver and the i3 window manager. Ensure 'exec' is on the last line.

```bash
xscreensaver &
exec /bin/i3

```

--------------------------------

### Install Base System (UEFI)

Source: https://docs.voidlinux.org/installation/guides/fde.html

Install the base system and necessary packages for a UEFI system.

```bash
# xbps-install -Sy -R https://repo-default.voidlinux.org/current -r /mnt base-system cryptsetup grub-x86_64-efi lvm2
```

--------------------------------

### Install Base System (Standard)

Source: https://docs.voidlinux.org/installation/guides/fde.html

Install the base system and essential packages using xbps-install. Ensure the repository URL is appropriate for your system.

```bash
# xbps-install -Sy -R https://repo-default.voidlinux.org/current -r /mnt base-system lvm2 cryptsetup grub
[*] Updating `https://repo-default.voidlinux.org/current/x86_64-repodata' ...
x86_64-repodata: 1661KB [avg rate: 2257KB/s]
130 packages will be downloaded:
...
```

--------------------------------

### Install HP Printer Drivers

Source: https://docs.voidlinux.org/config/print/index.html

Use hp-setup for guided installation of HP printer drivers. Default selections are usually sufficient.

```bash
# hp-setup -i

```

--------------------------------

### Bootstrap Base System with xbps-install

Source: https://docs.voidlinux.org/installation/guides/chroot.html

Use xbps-install to bootstrap the Void Linux installation by installing the `base-system` metapackage into the chroot environment.

```shell
# XBPS_ARCH=$ARCH xbps-install -S -r /mnt -R "$REPO" base-system
```

--------------------------------

### Install Full TeX Live Scheme

Source: https://docs.voidlinux.org/config/texlive.html

Install all available TeX Live packages by installing the 'scheme-full' collection.

```bash
# tlmgr install scheme-full

```

--------------------------------

### Configuring QEMU for Chroot Installation

Source: https://docs.voidlinux.org/installation/guides/arm-devices/index.html

Install and configure QEMU user emulators and binfmt-support for cross-architecture chroot installations. This is necessary when installing from an incompatible architecture like x86_64 to ARM.

```bash
# xbps-reconfigure -f qemu-user-<arch>

```

--------------------------------

### Bootstrap base-system with xbps-install

Source: https://docs.voidlinux.org/print.html

Use xbps-install to bootstrap the installation by installing the `base-system` metapackage. Ensure XBPS_ARCH and repository are correctly set.

```shell
# XBPS_ARCH=$ARCH xbps-install -S -r /mnt -R "$REPO" base-system

```

--------------------------------

### Manually Install Base System into Chroot

Source: https://docs.voidlinux.org/config/containers-and-vms/chroot.html

Manually set up a chroot by copying keys and using xbps-install to install the base system. Ensure the correct repository and architecture are specified.

```bash
# mkdir -p "<chroot_dir>/var/db/xbps/keys"
# cp -a /var/db/xbps/keys/* "<chroot_dir>/var/db/xbps/keys"
# XBPS_ARCH=<chroot_arch> xbps-install -S -r <chroot_dir> -R <repository> base-container <other_pkgs>

```

--------------------------------

### Exit Chroot and Reboot

Source: https://docs.voidlinux.org/installation/guides/chroot.html

After completing the chroot setup, exit the chroot environment, unmount the target filesystem, and reboot the system to boot into the new Void installation.

```bash
[xchroot /mnt] # exit
# umount -R /mnt
# shutdown -r now
```

--------------------------------

### Install Bootloader

Source: https://docs.voidlinux.org/installation/guides/fde.html

Installs the GRUB bootloader to the specified disk. This command should be run from within the chroot environment.

```bash
[xchroot /mnt] # grub-install /dev/sda

```

--------------------------------

### List All Installed Packages (using xpkg)

Source: https://docs.voidlinux.org/xbps/index.html

If `xtools` is installed, the `xpkg` command offers a simpler way to list all installed packages by name.

```bash
$ xpkg

```

--------------------------------

### Create Filesystems and Swap

Source: https://docs.voidlinux.org/print.html

Format the logical volumes with a filesystem (XFS in this example) and set up the swap space. Ensure the filesystem chosen is supported by GRUB.

```bash
# mkfs.xfs -L root /dev/voidvm/root
meta-data=/dev/voidvm/root       isize=512    agcount=4, agsize=655360 blks
...
# mkfs.xfs -L home /dev/voidvm/home
meta-data=/dev/voidvm/home       isize=512    agcount=4, agsize=2359040 blks
...
# mkswap /dev/voidvm/swap
Setting up swapspace version 1, size = 2 GiB (2147479552 bytes)
# swapon /dev/voidvm/swap

```

--------------------------------

### Install base-system and asahi-base

Source: https://docs.voidlinux.org/installation/guides/arm-devices/apple-silicon.html

During the Void Linux installation, ensure you install the 'base-system' and 'asahi-base' packages. The 'asahi-base' package includes essential configurations and dependencies.

```bash
xbps-install -S base-system asahi-base
```

--------------------------------

### Create Filesystems on LVM Volumes

Source: https://docs.voidlinux.org/installation/guides/fde.html

Format the logical volumes with desired filesystems. This example uses XFS for root and home, and sets up a swap partition.

```bash
# mkfs.xfs -L root /dev/voidvm/root
meta-data=/dev/voidvm/root       isize=512    agcount=4, agsize=655360 blks
... 
# mkfs.xfs -L home /dev/voidvm/home
meta-data=/dev/voidvm/home       isize=512    agcount=4, agsize=2359040 blks
... 
# mkswap /dev/voidvm/swap
Setting up swapspace version 1, size = 2 GiB (2147479552 bytes)
# swapon /dev/voidvm/swap


```

--------------------------------

### List Files Provided by an Installed Package

Source: https://docs.voidlinux.org/xbps/index.html

Employ `xbps-query -f <package_name>` to list all files installed by a specific package. This is useful when trying to locate a file that was expected after a package installation.

```bash
$ xbps-query -f <package_name>

```

--------------------------------

### Install GRUB for UEFI (x86_64)

Source: https://docs.voidlinux.org/print.html

Installs the GRUB bootloader for UEFI systems, specifying the target architecture and EFI directory.

```bash
[xchroot /mnt] # xbps-install -S grub-x86_64-efi
[xchroot /mnt] # grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id="Void"

```

--------------------------------

### Configure Xorg Keyboard Driver

Source: https://docs.voidlinux.org/config/graphical-session/xorg.html

Example configuration for a specific keyboard driver in Xorg. This file should be placed in /etc/X11/xorg.conf.d/.

```xorg.conf
Section "InputClass"
  Identifier "keyboard-all"
  Driver "evdev"
  MatchIsKeyboard "on"
EndSection

```

--------------------------------

### List Available Initramfs Alternatives

Source: https://docs.voidlinux.org/config/kernel.html

Lists all available alternatives within the 'initramfs' group. This is useful to verify installed initramfs generators.

```bash
$ xbps-alternatives -l -g initramfs

```

--------------------------------

### Install GRUB for BIOS systems

Source: https://docs.voidlinux.org/installation/guides/chroot.html

Installs the GRUB bootloader onto a BIOS system's boot disk. Ensure the correct device path is used.

```bash
[xchroot /mnt] # xbps-install -S grub

```

```bash
[xchroot /mnt] # grub-install /dev/sda

```

--------------------------------

### Install a Standalone TeX Package

Source: https://docs.voidlinux.org/config/texlive.html

Install an individual TeX package. First, search for the package using `tlmgr search`, then use this command to install it. Replace '<package>' with the package name.

```bash
# tlmgr install <package>

```

--------------------------------

### Install a TeX Live Collection

Source: https://docs.voidlinux.org/config/texlive.html

Install a specific TeX Live package collection. Replace '<name>' with the collection's name.

```bash
# tlmgr install collection-<name>

```

--------------------------------

### List All Installed Package Names

Source: https://docs.voidlinux.org/print.html

Retrieve a list of all installed packages on the system, excluding their versions. This can be achieved using a combination of xbps-query and awk, or more simply with the xpkg utility if xtools is installed.

```bash
$ xbps-query -l | awk '{ print $2 }' | xargs xbps-uhelper getpkgname

```

```bash
$ xpkg

```

--------------------------------

### Retrieve Debug Packages for a Package

Source: https://docs.voidlinux.org/print.html

Use the 'xdbg' utility to get a list of debug packages, including dependencies, for a specified package. This is useful before installing debug symbols.

```bash
$ xdbg bash
bash-dbg
glibc-dbg
```

```bash
# xbps-install -S $(xdbg bash)
```

--------------------------------

### Download and Run Asahi Linux Installer

Source: https://docs.voidlinux.org/installation/guides/arm-devices/apple-silicon.html

Use these commands to download and execute the Asahi Linux installer script from macOS to prepare your device for Void Linux.

```bash
macos $ curl https://alx.sh > alx.sh
macos $ sh ./alx.sh
```

--------------------------------

### Mount Root and Home Partitions

Source: https://docs.voidlinux.org/installation/guides/fde.html

Mount the root and home partitions to the /mnt directory before installing the base system.

```bash
# mount /dev/voidvm/root /mnt
# mkdir -p /mnt/home
# mount /dev/voidvm/home /mnt/home
```

--------------------------------

### Install GRUB for UEFI systems

Source: https://docs.voidlinux.org/installation/guides/chroot.html

Installs the GRUB bootloader for UEFI systems, specifying the target architecture and EFI directory. A bootloader ID can also be set.

```bash
[xchroot /mnt] # xbps-install -S grub-x86_64-efi

```

```bash
[xchroot /mnt] # grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id="Void"

```

--------------------------------

### Enable a Service

Source: https://docs.voidlinux.org/config/services/index.html

To enable a service, create a symbolic link to its directory in /var/service/. If the system is not running, you can link it directly into the 'default' runsvdir to start it automatically.

```bash
# ln -s /etc/sv/<service> /var/service/

```

```bash
# ln -s /etc/sv/<service> /etc/runit/runsvdir/default/

```

--------------------------------

### Update and Install base-system

Source: https://docs.voidlinux.org/print.html

Update the package manager and install/update the `base-system` metapackage. This ensures the system has the latest packages and essential components.

```shell
# xbps-install -r /mnt -Su xbps
# xbps-install -r /mnt -u
# xbps-install -r /mnt base-system
# xbps-remove -r /mnt -R base-container-full

```

--------------------------------

### Manual GRUB Bootloader Setup for UEFI

Source: https://docs.voidlinux.org/print.html

Manually sets up the GRUB bootloader for UEFI systems by copying the executable to the fallback boot path. This is useful for non-standard UEFI implementations or removable media.

```bash
[xchroot /mnt] # mkdir -p /boot/efi/EFI/boot
[xchroot /mnt] # cp /boot/efi/EFI/Void/grubx64.efi /boot/efi/EFI/boot/bootx64.efi

```

--------------------------------

### Mounting Partitions for Installation

Source: https://docs.voidlinux.org/installation/guides/arm-devices/index.html

Mount the root and boot partitions of your storage device. Replace /dev/mmcblk0p2 and /dev/mmcblk0p1 with your actual partition device names.

```bash
# mount /dev/mmcblk0p2 /mnt
# mkdir /mnt/boot
# mount /dev/mmcblk0p1 /mnt/boot

```

--------------------------------

### List All Installed Packages (without versions)

Source: https://docs.voidlinux.org/xbps/index.html

This command pipeline lists all installed packages by name, excluding versions. It uses `xbps-query -l` to list packages, `awk` to extract the second column (package name), and `xargs xbps-uhelper getpkgname` to format the output.

```bash
$ xbps-query -l | awk '{ print $2 }' | xargs xbps-uhelper getpkgname

```

--------------------------------

### Reconfigure QEMU BinFmt Support

Source: https://docs.voidlinux.org/print.html

Reconfigure QEMU user-mode emulation support after installing or updating it, especially if binFmt support was installed after the QEMU emulator.

```bash
xbps-reconfigure -f qemu-user-<arch>

```

--------------------------------

### Load nftables Ruleset

Source: https://docs.voidlinux.org/config/network/firewalls.html

To load the nftables ruleset defined in `/etc/nftables.conf`, enable and start the `nftables` service using the `sv up` command.

```bash
# sv up nftables

```

--------------------------------

### Mounting Filesystems for Void Linux Installation

Source: https://docs.voidlinux.org/print.html

Mount the root and home partitions before proceeding with the installation. Ensure the EFI system partition is also mounted on UEFI systems.

```bash
# mount /dev/voidvm/root /mnt
# mkdir -p /mnt/home
# mount /dev/voidvm/home /mnt/home
```

```bash
# mkfs.vfat /dev/sda1
# mkdir -p /mnt/boot/efi
# mount /dev/sda1 /mnt/boot/efi
```

--------------------------------

### Verify Repository Public Key Prompt

Source: https://docs.voidlinux.org/print.html

This is an example of the prompt displayed by xbps-install when a Void Linux RSA key has changed. It shows the new key fingerprint and asks for user confirmation to import it.

```text
<repository> repository has been RSA signed by "Void Linux"
Fingerprint: <rsa_fingerprint>
Do you want to import this public key? [Y/n]

```

--------------------------------

### Prevent Service from Starting at Boot

Source: https://docs.voidlinux.org/print.html

Create a 'down' file within a service's directory to prevent it from starting at boot while still allowing runit to manage it. This is useful for disabling default services.

```bash
# touch /etc/sv/<service>/down
```

--------------------------------

### List Disk Partitions (UEFI/GPT)

Source: https://docs.voidlinux.org/print.html

Display partition information for a disk using GPT, suitable for UEFI systems. This example shows an EFI system partition and a Linux filesystem partition.

```bash
# fdisk -l /dev/sda
Disk /dev/sda: 48 GiB, 51539607552 bytes, 100663296 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: EE4F2A1A-8E7F-48CA-B3D0-BD7A01F6D8A0

Device      Start       End   Sectors  Size Type
/dev/sda1    2048    264191    262144  128M EFI System
/dev/sda2  264192 100663262 100399071 47.9G Linux filesystem

```

--------------------------------

### Basic WPA2/PSK Network Configuration for IWD

Source: https://docs.voidlinux.org/config/network/iwd.html

Example of a network configuration file for a WPA2/PSK secured network. Store this in `/var/lib/iwd/` with a filename like `<ssid>.psk`.

```ini
[Security]
Passphrase=<password>

```

--------------------------------

### Exit Chroot, Unmount, and Reboot

Source: https://docs.voidlinux.org/print.html

After completing the installation steps within the chroot environment, exit the chroot, unmount the file systems, and reboot the system.

```bash
[xchroot /mnt] # exit
# umount -R /mnt
# shutdown -r now

```

--------------------------------

### Copy XBPS Keys

Source: https://docs.voidlinux.org/print.html

Copy the RSA keys from the installation medium to the target root directory. This is required for package verification.

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

```

--------------------------------

### Update and Install Base System in Chroot

Source: https://docs.voidlinux.org/installation/guides/chroot.html

Update the package manager and install/update the `base-system` within the chroot. This also removes the `base-container-full` package if present.

```shell
# xbps-install -r /mnt -Su xbps
# xbps-install -r /mnt -u
# xbps-install -r /mnt base-system
# xbps-remove -r /mnt -R base-container-full
```

--------------------------------

### Getting Encrypted Device UUID

Source: https://docs.voidlinux.org/print.html

Retrieve the UUID of the encrypted device (e.g., sda1) using the blkid command.

```bash
[xchroot /mnt] # blkid -o value -s UUID /dev/sda1
```

--------------------------------

### List Files in a TeX Collection

Source: https://docs.voidlinux.org/print.html

See all the files that are included in a specific TeX collection. This is useful for understanding the contents of a collection before installation.

```bash
$ tlmgr info --list collection-<name>

```

--------------------------------

### Enter Chroot and Basic Configuration

Source: https://docs.voidlinux.org/installation/guides/fde.html

Enter the chroot environment using xchroot and perform basic configuration like setting root ownership, permissions, password, and hostname.

```bash
# xchroot /mnt
[xchroot /mnt] # chown root:root /
[xchroot /mnt] # chmod 755 /
[xchroot /mnt] # passwd root
[xchroot /mnt] # echo voidvm > /etc/hostname
```

--------------------------------

### Install GRUB with --removable flag

Source: https://docs.voidlinux.org/installation/guides/arm-devices/apple-silicon.html

When installing GRUB, use the '--removable' flag to ensure it is installed correctly for removable media, which is often necessary in UEFI environments.

```bash
grub-install --removable
```

--------------------------------

### Export and Import ZFS Pool

Source: https://docs.voidlinux.org/print.html

Exports the 'zroot' ZFS pool and then re-imports it with an alternate root path of `/mnt`. This is a necessary step before proceeding with the Void Linux installation.

```bash
# zpool export zroot
# zpool import -N -R /mnt zroot
```

--------------------------------

### Enable a Service on Boot

Source: https://docs.voidlinux.org/print.html

Create a symbolic link to a service directory in /var/service/ to enable it on a running system. For systems not currently running, link into the 'default' runsvdir.

```bash
# ln -s /etc/sv/<service> /var/service/
```

```bash
# ln -s /etc/sv/<service> /etc/runit/runsvdir/default/
```

--------------------------------

### Create ZFS Pool

Source: https://docs.voidlinux.org/installation/guides/zfs.html

Use `zpool create` to set up a new ZFS pool. Adjust options like `ashift`, `compression`, and `autotrim` as needed. Replace the example device path with your actual partition.

```bash
# zpool create -f -o ashift=12 \
    -O compression=lz4 \
    -O acltype=posixacl \
    -O xattr=sa \
    -O relatime=on \
    -o autotrim=on \
    -m none zroot /dev/disk/by-id/wwn-0x5000c500deadbeef-part3

```

--------------------------------

### Configure Subordinate UID/GID Ranges

Source: https://docs.voidlinux.org/print.html

Edit /etc/subuid and /etc/subgid to delegate UID and GID ranges for unprivileged containers. Each entry defines the user, the starting ID, and the number of IDs in the range.

```bash
root:1000000:65536
user:2000000:65536

```

--------------------------------

### Enter chroot environment with xchroot

Source: https://docs.voidlinux.org/installation/guides/chroot.html

Sets up and enters the chroot environment, providing a bash shell for further system configuration.

```bash
# xchroot /mnt /bin/bash

```

--------------------------------

### Troubleshoot 'unresolvable shlib' Error

Source: https://docs.voidlinux.org/print.html

An example error message indicating a broken dependency on a shared library. This can be due to outdated packages or removed repositories. Use `xbps-remove -o` to clean up unneeded dependencies.

```text
libllvm8-8.0.1_2: broken, unresolvable shlib `libffi.so.6'

```

--------------------------------

### Start Tor as a User

Source: https://docs.voidlinux.org/xbps/repositories/mirrors/tor.html

Start the Tor daemon as a regular user. This will open a SOCKS5 proxy on localhost:9050 by default.

```bash
$ tor

```

--------------------------------

### Create ZFS Root and Boot Environments

Source: https://docs.voidlinux.org/installation/guides/zfs.html

Create the ZFS parent for boot environments and a root filesystem with `canmount=noauto` to allow multiple boot environments.

```bash
# zfs create -o mountpoint=none zroot/ROOT
# zfs create -o mountpoint=/ -o canmount=noauto zroot/ROOT/void
```

--------------------------------

### Controlling User Services with sv

Source: https://docs.voidlinux.org/config/services/user-services.html

Examples demonstrating how to check the status of user services and restart them using the 'sv' command. The SVDIR environment variable can be set to simplify service targeting.

```bash
$ sv status ~/service/*
run: /home/duncan/service/gpg-agent: (pid 901) 33102s
run: /home/duncan/service/ssh-agent: (pid 900) 33102s
$ SVDIR=~/service sv restart gpg-agent
ok: run: gpg-agent: (pid 19818) 0s

```

--------------------------------

### Test Service Before Enabling

Source: https://docs.voidlinux.org/config/services/index.html

Before fully enabling a service, you can test its functionality by creating a 'down' file, linking it into /var/service/, and then running 'sv once'. If it works correctly, remove the 'down' file to enable it.

```bash
# touch /etc/sv/<service>/down
# ln -s /etc/sv/<service> /var/service/
# sv once <service>

```

--------------------------------

### Test Service Before Enabling

Source: https://docs.voidlinux.org/print.html

Before fully enabling a service, test its functionality by creating a 'down' file, linking it into /var/service/, and then running 'sv once'. Remove the 'down' file if the service works correctly.

```bash
# touch /etc/sv/<service>/down
# ln -s /etc/sv/<service> /var/service/
# sv once <service>
```

--------------------------------

### Create Chroot with xvoidstrap

Source: https://docs.voidlinux.org/config/containers-and-vms/chroot.html

Use xvoidstrap to quickly create a chroot environment. Specify the architecture and optionally pre-install packages.

```bash
# mkdir <chroot_dir>
# XBPS_ARCH=<chroot_arch> xvoidstrap <chroot_dir> base-container <other_pkgs>

```

--------------------------------

### Enter Chroot with bwrap

Source: https://docs.voidlinux.org/config/containers-and-vms/chroot.html

Use bwrap to enter a chroot environment with additional sandboxing features. This example binds essential directories and files, and runs a specified command. Note that user and group management might be restricted.

```bash
$ bwrap --bind <chroot_dir> / \
	--dev /dev \
	--proc /proc \
	--bind /sys /sys \
	--bind /run /run \
	--ro-bind /etc/resolv.conf /etc/resolv.conf \
	--ro-bind /etc/passwd /etc/passwd \
	--ro-bind /etc/group /etc/group \
	<command>

```

--------------------------------

### Configure GRUB for Pinebook Pro

Source: https://docs.voidlinux.org/installation/guides/arm-devices/pinebook-pro.html

Append these lines to `/etc/default/grub` before running `grub-install` to set kernel command line arguments and specify the default Device Tree Blob for the Pinebook Pro.

```bash
GRUB_CMDLINE_LINUX_DEFAULT="$GRUB_CMDLINE_LINUX_DEFAULT console=ttyS2,115200 video=eDP-1:1920x1080x60"
GRUB_DEFAULT_DTB="rockchip/rk3399-pinebook-pro.dtb"

```

--------------------------------

### Manually Start PulseAudio Daemon

Source: https://docs.voidlinux.org/config/media/pulseaudio.html

Use this command to start the PulseAudio daemon manually. The `--daemonize=no` flag keeps it in the foreground, and `--exit-idle-time=-1` prevents it from exiting when idle.

```bash
$ pulseaudio --daemonize=no --exit-idle-time=-1

```
Tokens:
Raw