rework OS pages

Installing-and-Configuring/OS/Generic.md

@@ -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 detached, signed ISOs on a standard disk partition.  In this scenario heads will check the ISO against a detached PGP signature file which must be stored with the iso at the root of the partition in the standard .sig or .asc format.  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 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 partition you may need to add the TPM released LUKS key into the boot process before booting.
+
+(\*) 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/)
+

Installing-and-Configuring/OS/PureOS.md

@@ -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*.

Installing-and-Configuring/install-os.md → Installing-and-Configuring/OS/Qubes.md

@@ -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>
@@ -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
 ===
 
@@ -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)