HyperWiki

Migrate from Milky Way v0.2 to v0.3

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 Milky Way v0.2.

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 the Milky Way v0.3 from scratch rather than attempt migration to ensure a successful and less invasive update.
It is required to use a 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/sdXY /mnt
If you are using an encrypted file system, you will need to unlock it first and then mount it.
# cryptsetup luksOpen /dev/sdXY 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.

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)

Update database

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

Update the live image environment's package database: 

# pacman -Syy

Update the /mnt environment's package database. 

# pacman --root /mnt -Syy

Export the missing binaries folders to the PATH variable 

# export PATH="$PATH:/bin:/sbin:/usr/sbin"
Note: Exporting the path is only required for older live cd images (eg. Milky Way ⇐0.2.9)

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

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)

Reinstall Bootloader

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

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
# grub-mkconfig -o /boot/grub/grub.cfg

UEFI

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

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 the new Milky Way v0.3!

After migration

This version of Milky Way contains 3 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
  • All UXP applications now have their own profile directory.

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.

UXP applications

Beginning with v0.3, Iceweasel-UXP, Icedove-UXP, and Iceape-UXP now reside in ~/.hyperbola rather than ~/.mozilla which was kept for compatibility reasons during the Firefox 52 era.

In order to use your existing UXP application profiles, they must be renamed to the fit the new syntax.
For Iceweasel-UXP:
$ mkdir -p ~/.hyperbola/iceweasel-uxp
$ cp -a ~/.mozilla/firefox/* ~/.hyperbola/iceweasel-uxp

For Icedove-UXP: 

$ mkdir -p ~/.hyperbola/icedove-uxp
$ cp -a ~/.mozilla/thunderbird/* ~/.hyperbola/icedove-uxp

For Iceape-UXP: 

$ mkdir -p ~/.hyperbola/iceape-uxp
$ cp -a ~/.mozilla/seamonkey/* ~/.hyperbola/iceape-uxp

When you are certain all applications have been successfully migrated, you may delete the old ~/.mozilla folder and it's sub-directories.