---
title: Installing Debian or Devuan GNU+Linux with full disk encryption (including /boot)
...

This guide is written for the Debian distribution, but it should also
work for Devuan with the net installer. This guide is written under the
assumption that you use the GNU GRUB bootloader as your *main* payload.

If you are using SeaBIOS (or other payload such as Tianocore), you cannot use
an encrypted /boot/ directory because these payloads do not support decrypting
LUKS partitions; you *can* do it on those setups, but you then need to somehow
boot a GRUB payload externally, use BIOS/UEFI GRUB *or* (way cooler option) use
a *Linux kernel payload* or bootloader such as *linuxboot* (this is *planned*
for Retroboot!)

NOTE: This guide was last checked roughly in mid 2020 (back then, Retroboot did
not exist but this guide was forked from the Libreboot documentation so this
assertion relates to the version hosted by the Libreboot project, which on
26 December 2020 was exactly the same, more or less, as the version you are
now reading on this page). If a step is out of date or if something needs to be
added, please tell us!

If booting in legacy VGA text mode using libgfxinit
===================================================

To boot the Debian net installer, make sure to specify `fb=false` on the linux
kernel parameters in GRUB. This will boot the installer in text mode instead
of using a framebuffer.

If you do not specify this parameter, you will see an error message pertaining
to video modes; this is not a bug, just a design quirk on this particular
coreboot setup.

Specifying the `fb=false` parameter is not required on GRUB setups in text mode
when a Video BIOS Option ROM is in use (as supplied by the manufactured of the
video chipset in use), because mode switching is fully supported in that setup.

Moving on...
============

Retroboot on x86 provides an option to use the GNU GRUB bootloader as a
[payload](http://www.coreboot.org/Payloads#GRUB_2), which
means that the GRUB configuration file (where your GRUB menu comes from)
is stored directly alongside retroboot and its GRUB payload executable,
inside the flash chip. In context, this means that installing
distributions and managing them is handled slightly differently compared
to traditional BIOS systems.

On other setups, the `/boot` partition/directory has to be left unencrypted
while the others are encrypted. This is so that GRUB, and therefore the
kernel, can be loaded and executed since those setups can't open a LUKS
volume. Not so with Retroboot! Since GRUB is already included directly
as a payload, even '/boot' can be encrypted. This protects '/boot' from
tampering by someone with physical access to the system, when the system is
powered down.

This guide is written for Debian net installer. You can download the ISO
from the homepage on [debian.org](https://www.debian.org/). Use this on
the GRUB terminal to boot it from USB (for 64-bit Intel or AMD):

    set root='usb0'
    linux /install.amd/vmlinuz
    initrd /install.amd/initrd.gz
    boot
    
If you are on a 32-bit system (e.g. X60):

    set root='usb0'
    linux /install.386/vmlinuz
    initrd /install.386/initrd.gz
    boot
    
[This guide](grub_boot_installer.md) shows how to create a boot USB
drive with the Debian ISO image.

NOTE: on some thinkpads, a faulty DVD drive can cause the `cryptomount -a` step
during boot to stall. If this happens to you, try removing the drive or don't
use the `-a` option but instead directly specify the target drive/partition.

Set a strong user password (lots of lowercase/uppercase, numbers and symbols).

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

When the installer asks you to set up encryption (ecryptfs) for your home
directory, select 'Yes' if you want to: *LUKS is already secure and performs
well. Having ecryptfs on top of it will add noticeable performance penalty, for
little security gain in most use cases. This is therefore optional, and not
recommended. Choose 'no'.*

*Your user password should be different from the LUKS password which
you will set later on. Your LUKS password should, like the user
password, be secure.*

Partitioning
============

Choose 'Manual' partitioning:

-   Select drive and create new partition table
-   Single large partition. The following are mostly defaults:
    -   Use as: physical volume for encryption
    -   Encryption: aes
    -   key size: whatever default is given to you
    -   IV algorithm: whatever default is given to you
    -   Encryption key: passphrase
    -   erase data: Yes (only choose 'No' if it's a new drive that
        doesn't contain your private data)

-   Select 'configure encrypted volumes'
    -   Create encrypted volumes
    -   Select your partition
    -   Finish
    -   Really erase: Yes
    -   (erase will take a long time. be patient)
    -   (if your old system was encrypted, just let this run for about a
        minute to make sure that the LUKS header is wiped out)
-   Select encrypted space:
    -   use as: physical volume for LVM
    -   Choose 'done setting up the partition'
-   Configure the logical volume manager:
    -   Keep settings: Yes
-   Create volume group:
    -   Name: `matrix` (use this exact name)
    -   Select crypto partition
-   Create logical volume
    -   select `matrix` (use this exact name)
    -   name: `rootvol` (use this exact name)
    -   size: default, minus 2048 MB
-   Create logical volume
    -   select `matrix` (use this exact name)
    -   name: `swap` (user this exact name)
    -   size: press enter

Further partitioning
====================

Now you are back at the main partitioning screen. You will simply set
mountpoints and filesystems to use.

-   LVM LV rootvol
    -   use as: btrfs
    -   mount point: /
    -   done setting up partition
-   LVM LV swap
    -   use as: swap area
    -   done setting up partition
-   Now you select 'Finished partitioning and write changes to disk'.

Kernel
======

Installation will ask what kernel you want to use. linux-generic is
fine.

Tasksel
=======

For Debian, use the *MATE* option, or one of the others if you want. The
retroboot project recommends MATE, unless you're saavy enough to choose
something else.

If you want debian-testing, then you should only select barebones
options here and change the entries in /etc/apt/sources.list after
install to point to the new distro, and then run `apt-get update` and
`apt-get dist-upgrade` as root, then reboot and run `tasksel` as
root. This is to avoid downloading large packages twice.

NOTE: If you want the latest up to date version of the Linux kernel,
Debian's kernel is sometimes outdated, even in the testing distro. You
might consider using [this repository](https://jxself.org/linux-libre/)
instead, which contains the most up to date versions of the Linux
kernel. These kernels are also deblobbed, like Debian's kernels, so you
can be sure that no binary blobs are present, if this is something you care
about; otherwise, the repository also provides updated versions of the Linux
kernel and it is actively maintained by the owner for use on Debian-like
systems.

Postfix configuration
=====================

If asked, choose *"No Configuration"* here (or maybe you want to
select something else. It's up to you.)

Install the GRUB boot loader to the master boot record
======================================================

Choose 'Yes'. It will fail, but don't worry. Then at the main menu,
choose 'Continue without a bootloader'. You could also choose 'No'.
Choice is irrelevant here.

*Don't forget to have grub-coreboot package installed, even though installing grub to MBR is irrelevant
on retroboot system, grub tools are still needed to eg. generate config (`grub-mkconfig`)*

Clock UTC
=========

Just say 'Yes'.

Booting your system
===================

At this point, you will have finished the installation. At your GRUB
payload, press C to get to the command line, and enter:

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

ecryptfs
========

If you didn't encrypt your home directory, then you can safely ignore
this section.

Immediately after logging in, do that:

    $ sudo ecryptfs-unwrap-passphrase

This will be needed in the future if you ever need to recover your home
directory from another system, so write it down and keep the note
somewhere secret. Ideally, you should memorize it and then burn the note
(or not even write it down, and memorize it still)>

Generate distro's grub.cfg
======================

Now you need to set it up so that the system will automatically boot,
without having to type a bunch of commands.

Install grub-coreboot if not already installed:

    # apt-get install grub-coreboot

Modify or add following lines to /etc/default/grub

    GRUB_CMDLINE_LINUX="cryptdevice=/dev/mapper/matrix-rootvol:root"
    GRUB_ENABLE_CRYPTODISK=y

Copy fonts/backgrounds to /boot/grub and
generate grub.cfg using following command:

    # grub-install --target=i386-coreboot

[Refer to this guide](grub_hardening.md) for further guidance on
hardening your GRUB configuration, for security purposes.

LUKSv2 compatibility
======================

Retroboot uses a version of GRUB that supports LUKSv2, but it does not support
any special features. You *may* have to downgrade to LUKSv1; doing so will
*not* compromise your security, but you will lose access to many new features
in LUKSv2. LUKSv1 is still actively maintained.

[Debian's cryptsetup-team page shows how to downgrade](https://cryptsetup-team.pages.debian.net/cryptsetup/encrypted-boot.html#downgrading-luks2-to-luks1).

Copyright © 2014, 2015, 2016, 2020 Leah Rowe <info@minifree.org>\

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License Version 1.3 or any later
version published by the Free Software Foundation
with no Invariant Sections, no Front Cover Texts, and no Back Cover Texts.
A copy of this license is found in [../fdl-1.3.md](../fdl-1.3.md)
