Exherbo – Installation Guide

Posted on (↻ ).

About

Table of Contents

1. Read the documentation

2. Boot a live system

Get Ubuntu (or any distribution if you are not on Linux already) and verify the integrity of the ISO.

curl [--remote-name -O] http://releases.ubuntu.com/disco/ubuntu-19.04-desktop-amd64.iso
curl --remote-name http://releases.ubuntu.com/disco/SHA256SUMS

Verify the integrity of the ISO:

grep ubuntu-19.04-desktop-amd64.iso SHA256SUMS | shasum [--algorithm -a] 256 [--check -c]

Then write Ubuntu on your USB stick (be careful, it’s /dev/sdb in my case).

dd if=ubuntu-19.04-desktop-amd64.iso of=/dev/sdb

Boot Ubuntu then you’re ready for the next step.

3. Prepare the hard disk

Wipe the file system:

wipefs [--all -a] /dev/sda

Create the partitions:

fdisk /dev/sda
# Boot (EFI):
# Press 'n' for new partition
# – Partition type: 'p' for primary – should be default
# – Partition number: 1 – should be default
# – First sector: Use default
# – Last sector: +512M
# Press 't' to change partition type
# – Partition number: 1 – should be default
# – Partition type: 1 for EFI System
# Root:
# Press 'n' for new partition
# – Partition type: 'p' for primary – should be default
# – Partition number: 2 – should be default
# – First sector: Use default
# – Last sector: Use default
# Press 'w' to save and exit

Format and label the file systems for each partition:

mkfs.fat -F 32 /dev/sda1 -n EFI # Boot (EFI)
fatlabel /dev/sda1 EFI # Optional, to label a FAT disk after its creation
mkfs.ext4 /dev/sda2 -L Exherbo # Root
e2label /dev/sda2 Exherbo # Optional, to label an ext disk after its creation

Mount the root partition and navigate to it:

mount /dev/disk/by-label/Exherbo /mnt/exherbo
cd /mnt/exherbo

Get the latest archive of Exherbo from Stages and verify the consistence of the file:

curl --remote-name http://dev.exherbo.org/stages/exherbo-x86_64-pc-linux-gnu-current.tar.xz
curl --remote-name http://dev.exherbo.org/stages/sha256sum
grep exherbo-x86_64-pc-linux-gnu-current.tar.xz sha256sum | shasum --algorithm 256 --check

Extract the stage:

unxz [--to-stdout -c] exherbo-x86_64-pc-linux-gnu-current.tar.xz |
tar [--extract -x] [--preserve-permissions -p] [--preserve-order -s] [--file -f] -

Update /mnt/exherbo/etc/fstab:

/mnt/exherbo/etc/fstab

# FILE SYSTEM MOUNT POINT TYPE OPTIONS DUMP PASS
/dev/disk/by-label/Exherbo / ext4 defaults 0 0
/dev/disk/by-label/EFI /boot vfat defaults 0 0

4. Chroot into the system

Make sure the network can resolve DNS:

/mnt/exherbo/etc/resolv.conf

# Google DNS
# https://developers.google.com/speed/public-dns/docs/using
nameserver 8.8.8.8
nameserver 8.8.4.4

Spawn Exherbo namespace container with systemd-nspawn:

systemd-nspawn

Or mount everything for the chroot manually:

mount [--options -o] rbind /dev /mnt/exhero/dev
mount --options bind /sys /mnt/exherbo/sys
mount [--types -t] proc none /mnt/exherbo/proc
mount /dev/disk/by-label/EFI /mnt/exherbo/boot
env [--ignore-environment -i] TERM=$TERM SHELL=/bin/bash HOME=$HOME $(which chroot) /mnt/exherbo /bin/bash

Then when in Exherbo:

source /etc/profile
PS1="(Exherbo) $PS1"

5. Update the install

Make sure Paludis is configured correctly:

vi /etc/paludis/bashrc /etc/paludis/*.conf

Sync all the trees – now it is safe to sync:

cave sync

You may want to re-install the packages included in the stage:

cave resolve [--execute -x] world

6. Make it bootable

Clone the stable kernel on Linux and navigate to it:

git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux /kernel
cd /kernel

Switch to the latest stable kernel:

git checkout tags/v5.0.7 # 5.0.7 in my case

Configure and install the kernel:

make nconfig
make # Compile kernel to arch/x86/boot/bzImage
make modules_install

Make sure to re-install systemd in order to create a valid machine-id:

cave resolve --execute [--preserve-world -1] --skip-phase test sys-apps/systemd

Install systemd-boot:

bootctl install

You have to install sys-apps/systemd with the efi option enabled to use this command.

Open /etc/paludis/options.conf and add:

/etc/paludis/options.conf

sys-apps/systemd efi

Copy the kernel you just installed into the appropriate directory:

kernel-install add 5.0.7 /boot/vmlinuz-5.0.7

To remove old kernel versions:

kernel-install remove {kernel-version}

Configure your hostname for systemd:

/etc/hostname

kanto

Make sure your hostname is mapped to localhost in /etc/hosts, otherwise some packages test suites will fail because of network sandboxing.

/etc/hosts

127.0.0.1 localhost kanto
::1 localhost kanto

If you need additional kernel support e.g. for an Intel wireless card, install the Linux firmware files.

cave resolve --execute firmware/linux-firmware

Set root password:

passwd

Configure locales:

localdef [--inputfile -i] en_US [--charmap -f] UTF-8 en_US.UTF-8

/etc/locale.conf

LANG=en_US.UTF-8

Set the time-zone:

ln [--symbolic -s] /usr/share/zoneinfo/Europe/Paris /etc/localtime

Sync hardware clock ‘aka BIOS’ with the current system time.

hwclock [--systohc -w] [--utc -u]

Reboot:

reboot

7. Post-installation tasks

Remove the stage tarball:

rm /exherbo-x86_64-pc-linux-gnu-current.tar.xz

The installation images (stages) contain additional tools which are useful for the installation process but are not part of the system nor world sets but the stages set.

You can identify the additional packages using cave show:

cave show stages

If you wish to remove them, you can simply use cave purge:

cave purge

Alternatively, you can add packages you wish to retain to the world set by using the update-world command. As an example, the following adds sys-devel/gdb to the world set:

cave update-world sys-devel/gdb

If you want to add all packages of the stages to the world set:

cave update-world [--set -s] stages

Add a new user for daily use:

useradd [--create-home -m] [--groups -G] adm,disk,wheel,cdrom,audio,video,usb,users taupiqueur

To add groups:

usermod [--append -a] [--groups -G] {groups} taupiqueur

Set user password:

passwd taupiqueur

Install app-admin/sudo:

cave resolve --execute app-admin/sudo

Allow members of wheel to execute sudo with no password:

/etc/sudoers

%wheel ALL=(ALL) NOPASSWD: ALL

8. Configuring your desktop

Power keys

By default, closing the lid suspends your computer and pressing the power key powers off it. Just fix that, by opening logind configuration:

/etc/systemd/logind.conf

[Login]
HandleLidSwitch=ignore
HandlePowerKey=hibernate
HandleSuspendKey=suspend
HandleHibernateKey=hibernate

Take your changes into account:

systemctl restart systemd-logind

Editor

Install Kakoune:

cave resolve --execute app-editors/kakoune

You will be tell Kakoune is masked by unavailable, which means the package comes from an unavailable-unofficial repository.

Let’s add the repository:

cave resolve --execute repository/mawww

The command will install mawww in /etc/paludis/repositories/mawww.conf and populate the contents with /etc/paludis/repository.template.

Shell

Install Nushell:

cave resolve --execute app-shells/nu

You can also change your default shell, but it may be risky to log in a custom shell.

If you want it, first add the full path of Nushell to /etc/shells:

/etc/shells

/bin/nu

Then change your shell with:

chsh [--shell -s] /bin/nu

Networking

Install network tools:

cave resolve --execute sys-apps/iproute2
cave resolve --execute net-wireless/wireless_tools

Install NetworkManager and its applet:

cave resolve --execute net-apps/NetworkManager
cave resolve --execute gnome-desktop/gnome-keyring
cave resolve --execute gnome-desktop/network-manager-applet

Sound

Install ALSA:

cave resolve --execute sys-sound/alsa-utils

Install PulseAudio and its applet:

cave resolve --execute media-sound/pulseaudio
cave resolve --execute media-sound/pulseaudio-applet

Install the graphical volume control:

cave resolve --execute media-sound/pavucontrol

Enable PulseAudio:

systemctl --user enable --now pulseaudio

Window manager

Install X:

cave resolve --execute x11-server/xorg-server

If you need additional x11-drivers e.g. Intel:

cave search x11-drivers/xf86-video
# …
# x11-drivers/xf86-video-intel
# …
cave resolve --execute x11-drivers/xf86-video-intel

Install i3:

cave resolve --execute x11-wm/i3

For other x11-apps or x11-utils:

cave search x11-apps/{package-name}
cave search x11-utils/{package-name}

Fonts

Install DejaVu fonts:

cave resolve --execute fonts/dejavu

Disable bitmap fonts:

ln -s /usr/share/fontconfig/conf.avail/70-no-bitmaps.conf /etc/fonts/conf.d

Browsing

Install Chromium:

cave resolve --execute net-www/chromium-stable

Set Chromium as the default browser:

~/.config/mimeapps.list

[Default Applications]
text/html=chromium-browser.desktop
x-scheme-handler/http=chromium-browser.desktop
x-scheme-handler/https=chromium-browser.desktop

If you wish a test, try:

xdg-open https://exherbo.org

9. Useful commands

Uninstall a package

cave resolve !{package-name}

You can also edit your /etc/paludis/world and cave resolve world to update.

Updating the system

cave resolve world
  [--complete -c]
  [--preserve-world -1]
  [--continue-on-failure -C] [if-satisfied s]
  [--keep -k] [if-same-metadata m]
  [--keep-targets -K] [if-same-metadata m]

Taken from Clément Delafargue – My everyday Exherbo commands.

Show the dependencies of a package

cave show [--complex-keys -c] {package-name}

cave print-id-contents {package-name}

10. Creating your own packages

To start, create a new repository to hold the package’s files.

git init exheres
cd exheres

Create the following files:

profiles/repo_name

alexherbo2

metadata/about.conf

homepage = https://github.com/alexherbo2/exheres
summary = alexherbo2’s supplemental repository
description = alexherbo2’s tasty exhereses
owner = alexherbo2 <alexherbo2@gmail.com>
status = third-party

metadata/layout.conf

layout = exheres
eapi_when_unknown = exheres-0
eapi_when_unspecified = exheres-0
profile_eapi_when_unspecified = exheres-0
masters = arbor

Create your first package. As an example, we’ll create app-editors/kakoune.

packages/app-editors/kakoune/kakoune-scm.exheres-0

SUMMARY='mawww’s experiment for a better code editor'
HOMEPAGE='https://kakoune.org'

require kakoune

LICENSES='Unlicense'
PLATFORMS='~amd64 ~x86'

metadata/categories.conf

app-editors

metadata/repository_mask.conf

app-editors/kakoune[~scm] [[
  author = [ alexherbo2 <alexherbo2@gmail.com> ]
  date = [ 04 Apr 2019 ]
  token = scm
  description = [ Mask -scm version ]
]]

Update your Paludis configuration to include your repository:

/etc/paludis/repositories/alexherbo2.conf

format = e
location = /var/db/paludis/repositories/alexherbo2
sync = git+https://github.com/alexherbo2/exheres

Finally, sync the trees:

cave sync

11. Share your configuration

Because it’s always worth to see how others configure things e.g. Keruspe or me.

12. Contributing

Repositories are configured as normal, with their sync set to point to the usual remote location. In addition, for any repository you are going to work on, you use a sync suffix to specify a local path too. For example:

/etc/paludis/repositories/arbor.conf

sync = git+https://git.exherbo.org/git/arbor.git local: git+file:///home/taupiqueur/exherbo/exheres/arbor

Where ~/exherbo/exheres/arbor is a personal copy of the repository.

Normally, when you sync, you’ll be syncing against upstream. But when you want to do some work:

Clone the repository:

git clone git://git.exherbo.org/arbor.git ~/exherbo/exheres/arbor

Work on and commit your changes.

Sync the local repository rather than the upstream:

cave sync [--source -s] local [--revision -r] {commit-id} arbor

Test your changes.

Push your changes to GitLab. See the documentation for more information.

Create an account on the GitLab instance.

Add your SSH key for easier pushing via SSH instead of HTTPS.

Fork arbor.

Clone your fork of it:

git clone git@gitlab.exherbo.org:alexherbo2/arbor.git

If you already cloned the repo you can add your fork as remote:

git remote set-url origin git@gitlab.exherbo.org:alexherbo2/arbor.git
git remote add upstream https://gitlab.exherbo.org/exherbo/arbor.git

Push your changes.

Create a new pull request.

Go back to syncing without the suffix.