This is an old revision of the document!

Installing Hyperbola GNU/Linux-libre with full-disk encryption (including /boot)

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.

This guide is only for the GRUB payload. If you use the depth-charge payload, ignore this section entirely.
This guide has been used for those new to our system, check Beginner section for an overview.

Minimum requirements

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


Download the live image

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

You should never blindly copy-and-paste any commands. In this guide, copying and pasting is to ensure that no errors are made when entering the commands, so that you don’t effectively brick your installation, and have to start over. It’s important to understand what each command does before you use it, so be sure to read the man page.
Only choose HyperTalking live image, if you blind or visually impaired.

Choose the installation device

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

Boot Hyperbola’s install environment

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.

Setting up keyboard layout

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

Establish an internet connection

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

Preparing the storage device for installation

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.

Wipe storage device

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).

Formatting the storage device

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.

Create the LUKS partition

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.

The default iteration time is 2000ms (2 seconds), if not specified when running the cryptsetup command. You should set a lower time than this; otherwise, there will be an approximately 20-second delay when booting your system. We recommend 500ms (0.5 seconds), and this is included in the prepared cryptsetup command above. Keep in mind that the iteration time is for security purposes (it mitigates brute force attacks), so anything lower than 5 seconds is probably not very secure.

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).

Create the volume group and logical volumes

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

Make the rootvol and swapvol partitions ready for installation

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

Create the /boot and /home directories

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.