Generic OS Installation

1. Insert OS installation media into one of the USB3 ports (blue on Thinkpads). For certain OSes , Heads boot process supports standard OS ISO bootable media (where the USB drive contains the ISO installation media alongside of its detached signature). For other OS, you will need to create USB installation media with using dd or unetbootin etc.).

For supported OSes, on a EXT3/EXT4 formatted partition on USB drive, you can put the ISO image along with a trusted detached signature in the root directory:

/Qubes-R4.0-x86_64.iso
/Qubes-R4.0-x86_64.iso.asc
/tails-amd64-3.7.iso
/tails-amd64-3.7.iso.sig

• Some distros will require additional options to boot directly from ISO. See Boot config files for more information.
• Boot from USB by Boot menu options, or by calling usb-scan from the recovery shell.
  • Select the install boot option for your distro of choice and work through the standard OS installation procedures (including setting up LUKS disk encryption if desired)
• Reboot and your new boot option should be available through boot options: show boot options.

Each ISO file is verified for integrity and authenticity before booting so that you can be sure Live distros and installation media are not tampered with or corrupted, so this route is preferred when available. You can also sign the ISO with your own key from Heads recovery shell menu option :

gpg --output <iso_name>.sig --detach-sig <iso_name>

If you want to set a default option so that you don’t have to choose at every boot, you can do so from the menu by selecting ‘d’ on the confirmation screen. You will also be able to seal your Disk Unlock Key into the TPM, which would be unsealed only when provided with the good TPM disk encryption key passphrase and when firmware measurement and LUKS header are the same as when the Disk Unlock Key was sealed when booting from detached signed default boot option selection.

(*) Ubuntu/Debian Note: These systems don’t read /etc/crypttab in their initrd, so you need to adjust the crypttab in the OS and update-initramfs -u to have it attempt to use the injected key. Due to oddities in the cryptroot hooks, you also need keyscript to be in /etc/crypttab even as a no-op /bin/cat:

sda5_crypt UUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX /secret.key luks,keyscript=/bin/cat

(Credit to https://www.pavelkogan.com/2015/01/25/linux-mint-encryption/ for this trick).

Installing Qubes 4.1

Qubes OS and Tails can boot directly from ISO when provided with accompanying detached signatures (iso.asc or iso.sig), thanks to distribution signing keys being provided under Heads, permitting to validate both integrity and authenticity of the ISOs prior of booting into them.

Plug in the ext3/ext4 formatted USB stick containing Qubes R4.1 iso and iso.asc files into one of the USB port and boot it from USB mode:

If that completes with no errors it will launch the Xen hypervisor, kernel and initrd provided from ISO and start the Qubes installer:

Use default QubesOS partitioning scheme for QubesOS 4.x:

The Disk Recovery Key that you enter here will be used as the “recovery password” later. It should be a long value since you won’t have to enter it very often; only when upgrading the Heads firmware, when setting a new boot default and desiring to change TPM released disk encryption key (Disk Unlock Key), or if there is a need to recover the disk on an external machine. First stage install is finished.

Disconnect your USB Security dongle (and any external keyboard/mouses) prior of going further. Otherwise Qubes might detect those as USB Keyboards (HID devices) and will prevent sys-usb from being created properly:

You should now have Qubes 4.1 installed!

Taking ownership of the states

Taking ownership of the TPM

Heads keeps TPM and HOTP rollback counters under /boot. Since we just installed, those doesn’t exist and we need to create them. First things first, we need to acknowledge current firmware state for the newly installed OS.

That’s it. You now have TOTP scanned over your preferred TOTP smartphone app, or have entered manually the challenge secret under your favorite external TOTP app on another computer because you do not own a smartphone.

Signing /boot content

Now that firmware state is sealed under TPM and remotely attested through TOTP/HOTP, now is the time to sign /boot content until your next dom0 upgrade, which will most probably update Xen, initrd and kernel binaries, as well as grub configuration. This will be prompted automatically when selecting default boot option, since we have no digests nor detached signature of /boot content as of now.

Setting a new boot default

If you choose to add the Disk Unlock Key to the TPM, you’ll need to specify which LUKS volume. A default Qubes install will work if you leave the ‘Encrypted LVM group?’ response blank and enter /dev/sda2 when asked about ‘Encrypted devices?’. For more details see the TPM Disk Unlock Keys section below. You’ll then be asked to enter the Disk Recovery Key as well as the new boot passphrase you’ll use to unseal that key.

Until next dom0 upgrade, this is the normal boot process

When updating dom0 from Qubes OS update widget

You need to reboot directly after applying dom0 upgrades:

!!! Boot entry has changed - please set a new default

Applying dom0 (or OS updates) that changed the boot related binaries and config files (updating the kernel, Xen, or the initramfs, etc) will modify /boot content. If someone has tampered with your /boot partition, this can also happen, so if you’re not sure of the situation, don’t proceed and investigate. The onlyway to make sure you are the origin of the changes is to reboot and sign /boot content right after the upgrade. On Qubes OS, that should only happen when upgrading dom0. For Other OSes, that can happen in any unattended upgrades, which requires you to inspect system upgrade logs or be aware of updates propositions: if a kernel update is involved, you sure need to reboot and sign now.

Choose the first option again (‘1’), then make it the new default (‘d’), confirm that you’re modifying the boot partition (‘y’), and that you don’t need to reseal the disk key (‘n’). You’ll be asked to insert your USB Security dongle and enter the GPG User PIN to sign the new configs and the system will reboot and allow you to proceed as normal.

Installing extra software

sudo qubes-dom0-update

powertop is useful for debugging power drain issues. In dom0 run:

sudo qubes-dom0-update powertop

You might want to make the middle button into a scroll wheel. Add this to /etc/X11/xorg.conf.d/20-thinkpad-scrollwheel.conf

Section "InputClass"
  Identifier  "Trackpoint Wheel Emulation"
  MatchProduct  "TPPS/2 IBM TrackPoint|DualPoint Stick|Synaptics Inc. Composite TouchPad / TrackPoint|ThinkPad USB Keyboard with TrackPoint|USB Trackpoint pointing device|Composite TouchPad / TrackPoint"
  MatchDevicePath  "/dev/input/event*"
  Option    "EmulateWheel"    "true"
  Option    "EmulateWheelButton"  "2"
  Option    "Emulate3Buttons"  "false"
  Option    "XAxisMapping"    "6 7"
  Option    "YAxisMapping"    "4 5"
EndSection

You’ll probably want to enable fan control, as described on ThinkWiki.

Disabling the ethernet might make sense to save power