Skip to content

Commit

Permalink
rework OS pages
Browse files Browse the repository at this point in the history 
- based on work in PR 66 which now has conflicts
linuxboot#66
- re-org OS pages to use subfolder
- add pureOS page with current info not on Purism site
- change link to OS page in parent index
  • Loading branch information
@jtmoree-github-com
jtmoree-github-com committed Aug 3, 2021
1 parent f66e0df commit 62f218c
Show file tree
Hide file tree
Showing 5 changed files with 340 additions and 62 deletions.
118 changes: 118 additions & 0 deletions Installing-and-Configuring/OS/Generic.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
---
layout: default
title: Generic
permalink: /OS/Generic/
parent: Operating Systems
grand_parent: Installing and configuring
nav_order: 1
---

<!-- markdownlint-disable MD033 -->
<details open markdown="block">
<summary>
Table of contents
</summary>
{: .text-delta }
1. TOC
{:toc}
</details>
<!-- markdownlint-enable MD033 -->

Generic OS Installation
===

Insert OS installation media into one of the USB3 ports for maximum performance (blue ports).
Turn the system on and navigate to the USB boot in the graphical heads menu.

Main Menu => Boot Options => USB Boot

From here you will be presented with a menu of the boot options on the USB media. Choose the one you wish to use and Press enter. It is your responsibility to verify the integrity of the media before using it. Check your downloads against the signatures provided by vendors.


Securely Booting Installation Media
----

Heads also supports booting directly from verified ISOs on a standard disk partition. In this scenario heads will check the ISO against a detached PGP signature file. The ISO must be signed by a valid key for the boot process to succeed--either the distribution signing key or your own key.

If not using one of the included Operating Systems--where the vendor public key is [stored in the heads ROM](https://github.com/osresearch/heads/tree/master/initrd/etc/distro/keys)--you must verify the media immediately after download and sign it with your own key to establish a chain of trust.

To verify an ISO with your key, create a partition with a Heads compatible filesystem on a USB storage device and copy the ISO image to it. The most common filesystems are: FAT and ext. The layout might look like this:

```shell
/Qubes-R4.0-x86_64.iso
/Qubes-R4.0-x86_64.iso.asc
/Fedora-Workstation-Live-x86_64-27-1.6.iso
/Fedora-Workstation-Live-x86_64-27-1.6.iso.sig
/tails-amd64-3.7.iso
/tails-amd64-3.7.iso.sig
```

Sign the ISO(s) with your own key:

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

### Distro Specific ISO Boot

Some distros require additional options for a successful boot directly from ISO. See [Boot config files](#boot-config-files) for more information if your OS is not booting by selecting the default boot options from heads GUI.
1. Boot from USB by either running `usb-scan` or reboot into USB boot mode (hit
'u' before the normal boot)
1. 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)
1. Reboot and your new boot options should be available to be chosen by
selecting 'm' at the boot screen

`kexec_iso_add.txt` and `kexec_iso_remove.txt` are useful to inject the
appropriate kernel arguments to allow it to load properly. ISOs for Debian
require that `kexec_iso_add.txt` contains the following to load properly:

```text
findiso=${ISO_PATH}
```

Take a look at [https://mbusb.aguslr.com/howto.html](https://mbusb.aguslr.com/howto.html)
for more variations on the distro-specific ISO mounting command lines
requirements. By default Heads uses two variants of this when booting from
ISO where a `kexec_iso_add.txt` is not specified:

```text
fromiso=/dev/disk/by-uuid/$DEV_UUID/$ISO_PATH iso-scan/filename=/${ISO_PATH}
```


Installation Choices
====

See [OS](/OS/) for a review of various choices that will affect how you setup the Operating System.

bootloader
---

heads reads /boot/grub.cfg in order to boot your system. Since heads is acting as the bootloader you do not need to install grub to your MBR. It won't hurt if you do since the MBR is mostly ignored. If you choose to not install grub make sure you generate the grub.cfg file or heads cannot boot your system.

Injecting LUKS key into OS boot
----

If using LUKS encryption on the root paritition you may need to modify the installation before booting will work to add the LUKS key into the process.

(\*) 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/](https://www.pavelkogan.com/2015/01/25/linux-mint-encryption/)
for this trick).


Default Boot Partition
====

Heads will prompt you to set a default boot after OS installation.

By default heads uses /boot/grub/grub.cfg to dynamically load boot options. You have the option to make persistent modifications to the non-Qubes boot process. See [boot options](/BootOptions/)

72 changes: 72 additions & 0 deletions Installing-and-Configuring/OS/PureOS.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
---
layout: default
title: PureOS
permalink: /OS/PureOS/
parent: Operating Systems
nav_order: 1
grand_parent: Installing and configuring
---

<!-- markdownlint-disable MD033 -->
<details open markdown="block">
<summary>
Table of contents
</summary>
{: .text-delta }
1. TOC
{:toc}
</details>
<!-- markdownlint-enable MD033 -->

PureOS 9
===

Installation
----

Download the [PureOS ISO](https://pureos.net/download/).

There is a [guide](https://tracker.pureos.net/w/installation_guide/live_system_installation/) on the pureos site for installation. The basics are listed below with specifics related to using heads.

* Start Installer
* Partitions
* Enter user information etc.
* Finish Install

### start installer from heads

1. Insert OS installation media into one of the USB3 ports (blue on Thinkpads).
2. Boot from USB by choosing the appropriate options in heads menus and then run the installer inside the live environment.

Options => Boot Options => USB Boot


### partitions

Follow the prompts until you get to the storage and partitioning. You may allow the system to take over the entire disk and do all of the partitions for you or make the changes yourself.

It doesn't matter where the grub boot is installed on disk since heads will not use it. If you choose 'Do not install boot loader' you may need to run grub-mkconfig to generate /etc/grub.cfg which is required by heads.

If you choose to manually partition the disk you must decide if you want encryption or not. Make sure to create a separate boot partition (1G is common) and create the root partition. If you choose LUKS for either the installer should ask you for the passphrases. Make sure you keep them safe. There is a [bug](https://tracker.pureos.net/T752) you may run into here. See [Troubleshooting](#troubleshooting).

### finish install

The rest of the installer is small items such as the default user account on the system. Follow the prompts to the end of the install and reboot.


Configure heads to verify PureOS
----

When heads first boots after install it will be unable to verify any of your newly installed OS. Red and yellow backgrounds will be seen with messages that prompt you to take actions to configure secure booting. Purism has some [documentation](https://docs.puri.sm/PureBoot/GettingStarted.html#first-reboot) on this.


Troubleshooting
----

### LUKS

There is a bug in the pureos 9 installer at this time (Jan 2021) which may cause it to crash during install when using LUKS. I managed to get a few installs but lately no matter what I do it will not install. This bug is a few years old. If you run into it please post on the [tracker](https://tracker.pureos.net/T752).

### grub.cfg

grub.cfg is required for heads to boot. If you are having trouble use the live installer as a rescue CD and check for */boot/grub/grub.cfg*.
74 changes: 13 additions & 61 deletions Installing-and-Configuring/install-os.md → Installing-and-Configuring/OS/Qubes.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
---
layout: default
title: Step 4 - Installing Qubes and other OSes
permalink: /InstallingOS/
nav_order: 8
parent: Installing and configuring
title: Qubes
permalink: /OS/Qubes
nav_order: 1
parent: Operating Systems
grand_parent: Installing and configuring
has_toc: true
---


<!-- markdownlint-disable MD033 -->
<details open markdown="block">
<summary>
Expand All @@ -17,61 +20,6 @@ parent: Installing and configuring
</details>
<!-- markdownlint-enable MD033 -->

Generic OS Installation
===

1. Insert OS installation media into one of the USB3 ports (blue on Thinkpads).
[For certian OSes](https://github.com/osresearch/heads/tree/master/initrd/etc/distro/keys)
, the Heads boot process supports standard OS bootable media (where the USB
drive contains the installation media which as created using `dd` or
`unetbootin` etc.) as well as booting directly from verified ISOs on a plain
old partition. For example, if the USB drive has a single partition, you can
put the ISO image along with a trusted signature in the root directory:

```shell
/Qubes-R4.0-x86_64.iso
/Qubes-R4.0-x86_64.iso.asc
/Fedora-Workstation-Live-x86_64-27-1.6.iso
/Fedora-Workstation-Live-x86_64-27-1.6.iso.sig
/tails-amd64-3.7.iso
/tails-amd64-3.7.iso.sig
```

Each ISO is verified before booting so that you can be sure Live distros and
installation media are not tampered with, so this route is preferred when
available. You can also sign the ISO with your own key:

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

Some distros require additional options to boot properly directly from ISO. See
[Boot config files](/BootOptions) for more information.
2. Boot from USB by either running `usb-scan` or reboot into USB boot mode (hit
'u' before the normal boot)
3. 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)
4. Reboot and your new boot options should be available to be chosen by
selecting 'm' at the boot screen

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 using the TPM allowing
you to use ensure only a boot passphrase and the proper PCR state can unlock this
yet.

(\*) 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/](https://www.pavelkogan.com/2015/01/25/linux-mint-encryption/)
for this trick).

Installing Qubes
===

Expand All @@ -93,13 +41,17 @@ If that completes with no errors it will launch the Xen hypervisor from the

Use default QubesOS partitioning scheme for QubesOS 4.x

![Disk Recovery Key]({{ site.baseurl }}/images/Disk_encryption_recovery_key.jpg)
![Disk Recovery Key]({ site.baseurl }}/images/Disk_encryption_recovery_key.jpg)

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
or if there is a need to recover the disk on an external machine.
You will need it again shortly, so don't lose it yet.

DO NOT lose the Disk recovery key. This key passphrase will need to be [reentered](/Keys/#tpm-disk-encryption-key).

This option is offered from the GUI (again lets not forget that going into recovery invalidates PCR measurements, and that having kernel modules loaded mismatch between the moment of setting the TPM disk encryption key will not fly. This is why this should be done from the GUI by saving a new boot default option and answering Y to `Do you wish to add a disk encryption to the TPM [y/N]`:


![Signing Qubes binaries in /boot]({{ site.baseurl }}/images/Signing_Qubes_binaries_in__boot.jpg)

Expand Down
Loading

0 comments on commit 62f218c

Please sign in to comment.