This guide covers how to install Hyperbola GNU/Linux-Libre, with full disk encryption, including /boot (the boot directory). On most systems, /boot has to be left unencrypted, while the other partition(s) are encrypted. This is so that GRUB (and therefore the kernel) can be loaded and executed, because most firmware can’t open a LUKS volume; however, with Libreboot, GRUB is already included as a payload, so even /boot can be encrypted; this protects /boot from tampering by someone with physical access to the system.

You can find the minimum requirements to run Hyperbola GNU/Linux-libre on download page.

For this guide we are using Milky Way version, the live image is available on download page.

Refer to the beginner's guide, for finding and choosing the proper installation device, whether you are using an optical disk, or a USB drive.

After downloading the ISO, and creating some kind of bootable media, you will need to boot into the live image. If you are unsure of how to do so, see how to boot a GNU/Linux installer, and move on to the next step; otherwise, just go to the next step.

To begin the installation, you must first select the proper keyboard layout.

You will also need to set up a network connection, to install packages.

You need to prepare the storage device that we will use to install the operating system. You can use same device name that you used earlier, to determine the installation device for the ISO.

You want to make sure that the device you’re using doesn’t contain any plaintext copies of your personal data. If the drive is new, then you can skip the rest of this section; if it’s not new, then there are two ways to handle it:

1. If the drive were not previously encrypted, securely wipe it with the dd command; you can either choose to fill it with zeroes or random data; I chose random data (e.g., urandom), because it’s more secure. Depending on the size of the drive, this could take a while to complete:

   # dd if=/dev/urandom of=/dev/sdX; sync

2. If the drive were previously encrypted, all you need to do is wipe the LUKS header. The size of the header depends upon the specific model of the hard drive; you can find this information by doing some research online. Refer to this article, for more information about LUKS headers. You can either fill the header with zeroes, or with random data; again, I chose random data, using urandom:

   # head -c 3145728 /dev/urandom > /dev/sdX; sync

Also, if you’re using an SSD, there are a two things you should keep in mind:

• There are issues with TRIM; it’s not enabled by default through LUKS, and there are security issues, if you do enable it. See this page for more info.
• Make sure to read this article, for information on managing SSD’s in Arch GNU/Linux (the information applies to Hyperbola, as well).

Now that all the personal data has been deleted from the disk, it’s time to format it. We’ll begin by creating a single, large partition on it, and then encrypting it using LUKS.

You will need the device-mapper kernel module during the installation; this will enable us to set up our encrypted disk. To load it, use the following command:

# modprobe dm-mod

We then need to select the device name of the drive we’re installing the operating system on; see the above method, if needed, for figuring out device names.

Now that we have the name of the correct device, we need to create the partition on it. For this, we will use the cfdisk command:

# cfdisk /dev/sdX

1. Use the arrow keys to select your partition, and if there is already a partition on the drive, select Delete, and then New.
2. For the partition size, leave it as the default, which will be the entire drive.
3. You will see an option for Primary or Logical; choose Primary, and make sure that the partition type is Linux (83).
4. Select Write; it will ask you if you are sure that you want to overwrite the drive.
5. Type yes, and press enter. A message at the bottom will appear, telling you that the partition table has been altered.
6. Select Quit, to return you to the main terminal.

Now that you have created the partition, it’s time to create the encrypted volume on it, using the cryptsetup command, like this:

# cryptsetup -v --cipher serpent-xts-plain64 --key-size 512 --hash whirlpool --iter-time 500 --use-random --verify-passphrase luksFormat /dev/sdXY

These are just recommended defaults; if you want to use anything else, or to find out what options there are, run man cryptsetup.

You will now be prompted to enter a passphrase; be sure to make it secure. For passphrase security, length is more important than complexity (e.g., correct-horse-battery-staple is more secure than bf20$3Jhy3), but it’s helpful to include several different types of characters (e.g., uppercase/lowercase letters, numbers, special characters). The password length should be as long as you are able to remember, without having to write it down, or store it anywhere.

Use of the diceware method is recommended, for generating secure passphrases (rather than passwords).

The next step is to create two logical volumes within the LUKS-encrypted partition: one will contain your main installation, and the other will contain your swap space.

We will create this using, the Logical Volume Manager (LVM).

First, we need to open the LUKS partition, at /dev/mapper/lvm:

# cryptsetup luksOpen /dev/sdXY lvm

Then, we create LVM partition:

# pvcreate /dev/mapper/lvm

Check to make sure that the partition was created:

# pvdisplay

Next, we create the volume group, inside of which the logical volumes will be created. For this example, we will call this group matrix. You can call yours whatever you would like; just make sure that you remember its name:

# vgcreate matrix /dev/mapper/lvm

Check to make sure that the group was created:

# vgdisplay

Lastly, we need to create the logical volumes themselves, inside the volume group; one will be our swap, cleverly named swapvol, and the other will be our root partition, equally cleverly named as rootvol.

1. We will create the swapvol first (again, choose your own name, if you like). Also, make sure to choose an appropriate swap size (e.g., 2G refers to two gigibytes; change this however you see fit):

   # lvcreate -L 2G matrix -n swapvol

2. Now, we will create a single, large partition in the rest of the space, for rootvol:

   # lvcreate -l +100%FREE matrix -n rootvol

You can also be flexible here, for example you can specify a /boot, a /, a /home, a /var, or a /usr volume. For example, if you will be running a web/mail server then you want /var (where logs are stored) in its own partition, so that if it fills up with logs, it won’t crash your system. For a home/laptop system (typical use case), just a root and a swap will do.

Verify that the logical volumes were created correctly:

# lvdisplay

The last steps of setting up the drive for installation are turning swapvol into an active swap partition, and formatting rootvol.

To make swapvol into a swap partition, we run the mkswap (i.e., make swap) command:

# mkswap /dev/mapper/matrix-swapvol

Activate the swapvol, allowing it to now be used as swap, using swapon (i.e., turn swap on) command:

# swapon /dev/matrix/swapvol

Now we have to format rootvol, to make it ready for installation; we do this with the mkfs (i.e., make file system) command. We choose the ext4 filesystem, but you could use a different one, depending on your use case:

# mkfs.ext4 /dev/mapper/matrix-rootvol

Lastly, We need to mount rootvol. Fortunately, GNU/Linux has a directory for this very purpose: /mnt:

# mount /dev/matrix/rootvol /mnt

Now that you have mounted rootvol, you need to create the two most important folders on it: /boot and /home; these folder contain your boot files, as well as each user’s personal documents, videos, etc..

Since you mounted rootvol at /mnt, this is where you must create them; you will do so using mkdir:

# mkdir -p /mnt/home

# mkdir -p /mnt/boot

You could also create two separate partitions for /boot and /home, but such a setup would be for advanced users, and is thus not covered in this guide. For more information on how to do this, refer to the Arch wiki on partitions.

The setup of the drive and partitions is now complete; it’s time to actually install Hyperbola.

We need to install the essential applications needed for your Hyperbola installation to run; refer to Install the base system, on the our wiki.

The next step in the process is to generate a file known as an fstab; the purpose of this file is for the operating system to identify the storage device used by your installation. On the beginner’s guide is the instruction to generate that file.

Now, you need to chroot into your new installation, to complete the setup and installation process. Chrooting refers to changing the root directory of an operating system to a different one; in this instance, it means changing your root directory to the one you created in the previous steps, so that you can modify files and install software onto it, as if it were the host operating system.

To chroot into your installation, follow the instruction on the beginner’s guide.

Locale refers to the language that your operating system will use, as well as some other considerations related to the region in which you live. To set this up, follow the instructions in the beginner’s guide.

This will determine the keyboard layout of your new installation; follow the instructions in the beginner’s guide.

You’ll need to set your current time zone in the operating system; this will enable applications that require accurate time to work properly (e.g., the web browser). To do this, follow the instructions the beginner’s guide.

To make sure that your computer has the right time, you’ll have to set the time in your computer’s internal clock. Follow the instructions in the beginner’s guide to do that.

Now we need to make sure that the kernel has all the modules that it needs to boot the operating system. To do this, we need to edit a file called mkinitcpio.conf. More information about this file can be found in the Arch wiki, but for the sake of this guide, you simply need to run the following command.

# nano /etc/mkinitcpio.conf

There are several modifications that we need to make to the file:

1. Change the value of the uncommented MODULES line to i915.
   • This forces the driver to load earlier, so that the console font you selected earlier isn’t wiped out after getting to login.
   • If you are using a Macbook 2,1 you will also need to add hid-generic, hid, and hid-apple inside the quotation marks, in order to have a working keyboard when asked to enter the LUKS password. Make sure to separate each module by one space.
2. Change the value of the uncommented HOOKS line to the following:

   # nano /etc/mkinitcpio.conf
    
   "base udev autodetect modconf block keyboard keymap consolefont encrypt lvm2 filesystems fsck shutdown"

   Here’s what each module does:

   • keymap adds to initramfs the keymap that you specified in /etc/conf.d/keymaps
   • consolefont adds to initramfs the font that you specified in /etc/conf.d/keymaps
   • lvm2 adds LVM support to the initramfs - needed to mount the LVM partitions at boot time
   • shutdown is needed according to Arch wiki, for unmounting devices (such as LUKS/LVM) during shutdown

After modifying the file and saving it, we need to update the kernel(s) with the new settings.

We will also install the grub package, which we will need later, to make our modifications to the GRUB configuration file:

# pacman -S grub

Then, we update both kernels like this, using the mkinitcpio command:

# mkinitcpio -p linux-libre-lts

Now we need to set up the hostname for the system; this is so that our device can be identified by the network. Refer to the hostname section of the beginner’s guide. You can make the hostname anything you like; for example, if you wanted to choose the hostname hyperbola, you would run the echo command, like this:

# echo hyperbola > /etc/hostname

And then you would modify /etc/hosts like this, adding the hostname to it:

# nano /etc/hosts
 
#<ip-address> <hostname.domain.org>   <hostname>
127.0.0.1               localhost.localdomain       localhost   hyperbola
::1                            localhost.localdomain       localhost   hyperbola

Now that we have a hostname, we need to configure the settings for the rest of the network, we suggest use netifrc to set up your wired/wireless connection. See the Gentoo Handbook which explains netifrc scripts in a high level of detail.

The root account has control over all the files in the computer; for security, we want to protect it with a password. The password requirements given above, for the LUKS passphrase, apply here as well. You will set this password with the passwd command:

# passwd

There are some final changes that we can make to the installation, to make it significantly more secure; these are based on the security section of the Arch wiki.

We will want to open the configuration file for password settings, and increase the strength of our root password:

# nano /etc/pam.d/passwd

Add rounds=65536 at the end of the uncommented ‘password’ line; in simple terms, this will force an attacker to take more time with each password guess, mitigating the threat of brute force attacks.

You can prevent any user, other than the root user, from accessing the most important directories in the system, using the chmod command.

# chmod 700 /boot /etc/{iptables,arptables}

~ man chmod

We can also setup the system to lock a user’s account, after three failed login attempts.

To do this, we will need to edit the file /etc/pam.d/system-login, and comment out this line:

auth required pam\_tally.so onerr=succeed file=/var/log/faillog*\

You could also just delete it. Above it, put the following line:

auth required pam\_tally.so deny=2 unlock\_time=600 onerr=succeed file=/var/log/faillog

This configuration will lock the user out for ten minutes. You can unlock a user’s account manually, using the root account, with this command:

# pam_tally --user *theusername* --reset

Edit configuration in /etc/default/grub, remembering to use UUID when pointing to mbr/gpt partition. Use blkid to get list of devices with their respective UUIDs. Next generate grub.cfg with:

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

If you have separate /boot partition, don’t forget to add boot symlink inside that points to current directory:

# cd /boot

# ln -s . boot

Congratulations! You have finished the installation of Hyperbola GNU/Linux-libre. Now it is time to reboot the system, but first, there are several preliminary steps:

Exit from chroot, using the exit command:

# exit

Unmount all of the partitions from /mnt, and “turn off” the swap volume:

# umount -R /mnt

# swapoff -a

Deactivate the rootvol and swapvol logical volumes:

# lvchange -an /dev/matrix/rootvol

# lvchange -an /dev/matrix/swapvol

Lock the encrypted partition (i.e., close it):

# cryptsetup luksClose lvm

Shutdown the machine:

# openrc-shutdown -p now

After the machine is off, remove the installation media, and turn it on.

When you forget to configure or misconfigure grub on your hdd, you have to manually boot the system by entering a series of commands into the GRUB command line.

After the computer starts, Press C to bring up the GRUB command line. Here are the commands:

grub> cryptomount -a
grub> set root='lvm/matrix-rootvol'
grub> linux /boot/vmlinuz-linux-libre-lts root=/dev/matrix/rootvol cryptdevice=/dev/sda1:root
grub> initrd /boot/initramfs-linux-libre-lts.img
grub> boot

AHCI transfer timed out

Edit /etc/pacman.conf and configure pacman's options, also enabling the repositories you need.

See Pacman and repositories for details.

At this point you should update your system.

See Upgrading packages for instructions.

Finally, add a normal user as described in User management.

Since Hyperbola removed entire systemd support, we suggest you read about OpenRC which is our main default init system.

Your new Hyperbola GNU/Linux-libre base system is now a functional GNU/Linux environment.

This wiki article is released under the GNU Free Documentation License 1.3 with no invariant sections, no front cover texts, and no back cover texts.

This wiki article is based on Libreboot documentation.