Free your Arch GNU/Linux to Hyperbola GNU/Linux-libre

Since Hyperbola migrated from systemd's Filesystem Hierarchy used by Arch to the Filesystem Hierarchy Standard (FHS), it is required that you follow this migration article carefully and in the proper sequence when migrating from Arch.

What is the Filesystem Hierarchy Standard (FHS)?

The Filesystem Hierarchy Standard (FHS) defines the main directories and their contents in GNU/Linux and other Unix-like computer operating systems such as HyperbolaBSD. See our article for further details.

Warning

Please read the whole warning
It is strongly recommended to make a complete backup of all data prior to attempting a this migration. Users may also prefer to install Hyperbola from scratch rather than attempt migration to ensure a successful and less invasive update.
It is required to use the Milky Way v0.3 live image to make this migration.
To the fullest extent permitted by applicable laws, Hyperbola Project excludes and disclaims liability for any losses and expenses of whatever nature and howsoever arising, including without limitation, any direct, indirect, general, special, punitive, incidental, or consequential damages; loss of use; loss of data; loss caused by a virus; loss of income or profit; loss of or damage to property; claims of third-parties or other losses of any kind or character.

Migration

Run the live image and mount your root partition to /mnt. Replace /dev/sdX with your actual root partition.

# mount /dev/sdX /mnt
If you are using an encrypted file system, you will need to unlock it first and then mount it.
# cryptsetup luksOpen /dev/sdX hdd
# mount /dev/mapper/hdd /mnt

If you are using LVM, you will need to mount the volume as the root partition.

# mount /dev/mapper/matrix-rootvol /mnt

If you are having trouble locating your root partition, try using:

# lsblk

This command will print a list of drives, partitions, and volume groups.

Install Hyperbola keyring and mirror list

Disable signature verification manually by modifying the line in /mnt/etc/pacman.conf:

RemoteFileSigLevel = Never

Install Hyperbola keyring package and mirror list for Hyperbola repositories in /mnt/etc/pacman.d/mirrorlist:

# pacman --root /mnt -U https://www.hyperbola.info/packages/core/any/hyperbola-keyring/download/
# pacman --root /mnt -U https://www.hyperbola.info/packages/core/any/pacman-mirrorlist/download/

Reenable signature verification in /mnt/etc/pacman.conf:

#RemoteFileSigLevel = Required

Rename mirrorlist.pacnew as mirrorlist:

# cp -av /mnt/etc/pacman.d/mirrorlist.pacnew /mnt/etc/pacman.d/mirrorlist

Remove custom packages and orphaned ones

# pacman --root /mnt -R $(pacman --root /mnt -Qqm)
If [multilib] packages are installed, you will need to additionally run
# pacman --root /mnt -Rdd $(pacman --root /mnt -Qqm)

Replace Arch packages with Hyperbola ones

If you are using [multilib] you should enable it in the live image too:
# nano -w /etc/pacman.conf
-------------------------------------------------------------------------
[multilib]
Include = /etc/pacman.d/mirrorlist

Clean the /mnt environment's package database.

# pacman --root /mnt -Scc

Update the live image environment's package database:

# pacman -Syy

Update the /mnt environment's package database.

# pacman --root /mnt -Syy

Fix package database

# pacman --root /mnt -D --asdeps $(pacman --root /mnt -Qqe)
# pacman --root /mnt -D --asexplicit $(pacman --root /mnt -Qqtd)

Update the filesystem

The filesystem has significantly changed since v0.2.9, and requires manual upgrading.

It is normal to have permission warnings and an execv errors beyond this point, as FHS changes have increased our folder permission security since version v0.2.9
# pacman --root /mnt --cachedir /mnt/var/cache/pacman/pkg -S filesystem

Update all packages

# pacman --root /mnt --cachedir /mnt/var/cache/pacman/pkg -Suu base
If you want to ignore extra prompts and accept all confirmations over replaced packages, you can optionally use –noconfirm
If some of your packages have higher version than in Hyperbola repos they will be downgraded to lower version of libre packages to eliminate packages that are nonfree and because we are a long-term support distro.
Since Hyperbola is a long-term support distro, linux-libre-lts is our default kernel.
Hyperbola is a long-term support distro based on Arch plus stability and security from Debian. It isn't a rolling release distro like Arch because Hyperbola is using Arch snapshots for its versions and Parabola's blacklist as base to keep it 100% libre. Also Hyperbola is using Debian patches, therefore all packages are being stabilized with improvements through its development. See the Packaging Guidelines and Social Contract for further details.

Install your-freedom to remove nonfree packages that do not have libre replacements:

# pacman --root /mnt --cachedir /mnt/var/cache/pacman/pkg -S your-freedom

Reinstall all non-explicitly installed packages

# pacman --root /mnt --cachedir /mnt/var/cache/pacman/pkg -S --asdeps $(pacman --root /mnt -Qqd)

Reinstall all explicitly installed packages

# pacman --root /mnt --cachedir /mnt/var/cache/pacman/pkg -S $(pacman --root /mnt -Qqe)

Chroot into the installed system

# arch-chroot /mnt

Reinstall all packages again

# pacman -S --asdeps $(pacman -Qqd)
# pacman -S $(pacman -Qqe)

Regenerate the kernel image

# mkinitcpio -p linux-libre-lts

Reinstall Bootloader

Depending on your installed bootloader, you will need to reinstall it to obtain the latest changes.

Reinstalling the bootloader is not required for LibreBoot systems as GRUB resides in the BIOS and not on the internal storage drive.

GRUB

Note: This is only required for installed system with GRUB on the internal drive, see GRUB manual for further details.
# grub-install /dev/sdX

For grub regenerate your grub.cfg file, run:

# grub-mkconfig -o /boot/grub/grub.cfg

Syslinux

Note: This is only required for installed system with Syslinux on the internal drive, see Syslinux manual for further details.

Manually change following lines in /boot/syslinux/syslinux.cfg to reflect change:

  LABEL hyperbola
     MENU LABEL Hyperbola GNU/Linux-libre
     LINUX ../vmlinuz-linux-libre-lts
     ...
     INITRD ../initramfs-linux-libre-lts.img
 
  LABEL hyperbolafallback
     MENU LABEL Hyperbola GNU/Linux-libre Fallback
     LINUX ../vmlinuz-linux-libre-lts
     ...
     INITRD ../initramfs-linux-libre-lts-fallback.img
Alternatively you can remove the configuration file and reinstall syslinux.

UEFI

Note: This is only required for installed system with UEFI, see UEFI manual for further details
# mkdir /boot/efi
# mount /dev/sdY /boot/efi
# cp -vi initramfs-linux-libre-lts* vmlinuz-linux-libre-lts /boot/efi/efi/hyperbola/

Other bootloaders

OpenRC

Since Hyperbola has announced the end of systemd support, migration to OpenRC is required.

What is OpenRC?

OpenRC is a dependency based init system maintained by the Gentoo developers, that works with the system provided init program, normally SysVinit.

Warning

Please read the whole warning

netctl works with systemd only, therefore it will not work anymore from Milky Way v0.2 since OpenRC is the main init system of Hyperbola. We will assume you already have an alternative, in our case, it is netifrc.

Groups

Before Arch migrated to systemd, users had to be manually added to some groups in order to be able to access the corresponding devices. Read more about here.

Make sure your user is on the audio group, you won't have sound otherwise:

# gpasswd -a <your-user> audio

In the case of some graphical environments, such as KDE, you´ll need to edit /etc/pulse/client.conf and remove the autospawn = no line, and it should look something like this:

...
; default-sink =
; default-source =
; default-server =
; default-dbus-server =

; autospawn = yes
; daemon-binary = /usr/bin/pulseaudio
; extra-arguments = --log-target=syslog

; cookie-file =

; enable-shm = yes
; shm-size-bytes = 0 # setting this 0 will use the system-default, usually 64 MiB 

; auto-connect-localhost = no
; auto-connect-display = no
This is just in the case you use PulseAudio. For more information refer to this topic from the Manjaro forum.
For security reasons, we have plans to use sndio as PulseAudio replacement. Since it requires a hard transition, it will be made for the next version, aka Milky Way v0.4. We will make an announcement when it is ready.

Same for video, your games might be laggy otherwise:

# gpasswd -a <your-user> video

For networking:

# gpasswd -a <your-user> network

For webcam:

# gpasswd -a <your-user> optical

Also for storage:

# gpasswd -a <your-user> storage
# gpasswd -a <your-user> disk

And for CUPS:

# gpasswd -a <your-user> sys
First try these features before adding your user to these groups, for example, in some cases adding your user to the optical group may not be necessary.

Migration

Since OpenRC is included by default and systemd is blacklisted by your-freedom, one may get messages on migrating like:

run 'rc-update add cronie default'
run 'rc-update add haveged default'

Running these command(s) adds the service(s) to the specified runlevels. For example on running:

# rc-update add cronie default

The cronie service would be added to the default runlevel and would automatically be started at boot.

cronie (for cron) and haveged (for entropy harvesting) are some common services that can be enabled.

Also you need to install polkit to gain enough desktop privileges for operations like shutdown, mounting usb device:

# pacman -S polkit
Currently, NetworkManager and any display manager such as GDM or LightDM runs the elogind service in Hyperbola automatically, however if you will use the xinit program to start the X Window System server or Weston/Sway to start Wayland and use netifrc instead of NetworkManager, you need add the elogind service to a runlevel (eg. default) to be started at boot automatically.
For security reasons, we have plans to use ConsoleKit as elogind replacement. Since it requires a hard transition, it will be made for the next version, aka Milky Way v0.4. We will make an announcement when it is ready.

Configuration

Services often required

Once you migrate to OpenRC, you might need to add lvm2 etc.

There is the procedure for lvm2:

# rc-update add lvm boot

For cryptsetup:

# rc-update add dmcrypt boot

For alsa-utils:

# rc-update add alsasound default

For cronie:

# rc-update add cronie default

On each package containing an OpenRC service, you will have have this message :

      ==> rc 'rc-update add ... default'
Make sure what services you was using in systemd to re-enable them in OpenRC:
$ ls -ls /etc/systemd/system/multi-user.target.wants/

Sometimes, there are target files such as remote-fs.target which are useless in OpenRC.

Hostname

OpenRC has its configuration in /etc/conf.d/, in order to have your hostname, edit /etc/conf.d/hostname:

# nano -w /etc/conf.d/hostname

And replace localhost with the name that you want:

# Set to the hostname of this machine
hostname="localhost"

NetworkManager settings

You need to enable the software at boot:

# rc-update add NetworkManager default

In order to not change the computer's hostname when you're connecting to Internet (provided by dhcp), uncomment the part [keyfile] in the file /etc/NetworkManager/NetworkManager.conf as follow :

# Static hostname
[keyfile]
hostname=**Votre hostname**

For NetworkManager to work correctly in OpenRC, make sure that /etc/hostname has the same localhost as in /etc/conf.d/hostname. Optionally, you can safely remove /etc/hostname

For security reasons, we have plans to remove NetworkManager. Since it requires a hard transition, it will be made for the next version, aka Milky Way v0.4. We will make an announcement when it is ready, so we recommend you use netifrc as alternative.

Kepmap

As the hostname, you need to setup the keymap in the file /etc/conf.d/keymaps:

keymap="us"

If you have an advanced usage of your keymap, you can watch the other functionalities, documented in the comments. You can find all the available keymaps in /usr/share/kbd/keymaps. Then run:

# rc-service keymaps restart
This only applies for CLI, is you are using X11, this won't affect your graphical environment.

Login display manager

Unlike another distros with OpenRC support, the DM is launched directly.

For example, with lightdm, you just need enable the service.

# rc-update add lightdm default

Adaptation between systemctl and rc-update

Add or delete a service

You can add a service using this way:

# rc-update add <service> <runlevel>

And delete it as follow:

# rc-update del <service> <runlevel>

Services currently running

In order to have a summary of all the services running, stopped etc, you can run this command:

# rc-status --all -v

Stop/Start/Restart a service

To restart a service, you need to use rc-service:

# rc-service <service> restart

Troubleshooting

Consistent network device naming is not disabled

To disable consistent network device naming, disable the assignment of fixed names, so that the unpredictable kernel names are used again, by masking udev's rule file for the default policy. This “masking” can be done by making a symbolic link to /dev/null. As root, issue a command as follows:

# ln -s /dev/null /etc/udev/rules.d/80-net-name-slot.rules

Sysctl.conf is missing

You can encounter an issue if /etc/sysctl.conf is missing. To fix this, you need to create the file:

# touch /etc/sysctl.conf

/usr/libexec/rc/cache doesn't exist

If you have this error when you shutdown the computer:

WARNING: /usr/libexec/rc/cache is not writable!

The solution is to create the folder:

# mkdir /usr/libexec/rc/cache

Swap isn't enabled

Systemd used to mount the swap automatically, you need to manually add the swap in /etc/fstab as follow:

# /dev/sda2
UUID=0c3e9434-bc5c-461c-a5e4-4e9fe5f9a149	swap	swap	sw	0	0

tmpfs isn't present

As the swap, systemd automatically mounts the tmpfs. Add it manually in /etc/fstab:

tmpfs		/tmp		tmpfs   nodev,nosuid          	0  	0

The system can't shutdown correctly

Begin with OpenRC 0.28 SysVinit is replaced with openrc-init, shutdown is replaced with openrc-shutdown. If you use startx to start your desktop, you also need to modify ~/.xinitrc for xfce4, replace exec ck-launch-session startxfce4 to startxfce4.

Complete the migration

Exit from chroot

# exit
You can also press Ctrl+D in order to exit from a chroot

Unmount and reboot

# umount -l /mnt

Reboot system

# reboot

Then login into Hyperbola!

After installation

Welcome, you are now in Hyperbola!

Independent of OpenRC, Hyperbola contains 2 notable changes:

  • The adoption of LibreSSL as default provider of Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols
  • The adoption of Xenocara as default provider of display server for the X Window System

LibreSSL

LibreSSL is a version of the TLS/crypto stack forked from OpenSSL in 2014, with goals of modernizing the codebase, improving security, and applying best practice development processes.

It was forked from the OpenSSL in April 2014 as a response by OpenBSD developers to the Heartbleed security vulnerability in OpenSSL, with the aim of refactoring the OpenSSL code so as to provide a more secure implementation.

If you have local or custom OpenSSL linked packages, they need to be rebuild against LibreSSL. There will likely be broken packages.

It includes packages with direct dependencies on:

  • openssl
  • openssl-1.0
  • lib32-openssl
  • lib32-openssl-1.0

Also packages with link to:

  • libssl.so.1.1
  • libssl.so.1.0
  • libcrypto.so.1.1
  • libcrypto.so.1.0

Xenocara

Xenocara provides a framework to host OpenBSD modifications and to automate the build of the modular X.Org components, including 3rd party packages and some software maintained by OpenBSD developers.

It includes a customised X.Org X server that utilises a dedicated _x11 user by default to drop privileges and perform privilege separation in accordance to OpenBSD's least privilege policy. Furthermore, Xenocara includes several other projects, such as cwm, a stacking window manager for the X Window System.

If you have local or custom X.Org linked packages, they need to be rebuild against Xenocara. There will likely be broken packages.

It includes packages with direct dependencies on:

  • xorg-*

Also packages with link to:

  • libX*.so*
If you did not already have xorg-server installed during migration, you can test the new Xenocara by installing it.
# pacman -S xenocara-server
The perform privilege separation feature was disabled in Hyperbola GNU/Linux-libre because it requires OpenBSD-specific system calls such as pledge and unveil, however it will be implemented for HyperbolaBSD, an operating system which is being developed by Hyperbola Project.

Troubleshooting

Do you encounter some hardware not working after installing your-freedom? This most likely means that there's no free driver or firmware available for the device (check dmesg). It's common for Wi-Fi cards to require a firmware to be loaded into the card. Many cards don't work at all if the firmware is missing. The firmware is often proprietary, thus we don't distribute it. It's the case for almost any internal Wi-Fi card.

The usual fix to the problem is either to replace the card or use an external USB Wi-Fi dongle. You can buy one with Atheros chipset (eg. ath9k_htc for external USB dongle or ath9k for PCI and PCI-Express expansion slots) or RTL818x chipset (eg. rtl8187 for external USB dongle or rtl818x_pci for PCI and PCI-Express expansion slots) since there is a free firmware for these Wi-Fi adapters. You can also search the h-node database to find Wi-Fi adapters known to work well with free software or scripts/deblob-$ver to check Wi-Fi adapters included in the Linux-libre device blacklist.

If you find any trouble applying these instructions please report it on our Bug Tracker!

Acknowledgement

This wiki article is based on ParabolaWiki.