templates/system/README.md

Auxolotl System Template

A ready-to-run NixOS template with sane defaults.

Getting Started

1. Install a fresh copy of NixOS and boot into your new system.
2. Download, copy, or clone this repository onto your new system.
3. Run nixos-generate-config --show-hardware-config to generate your system's hardware-configuration.nix file. Copy this file into the host folder, overwriting the existing file.
4. Edit flake.nix and set the value of hostName to the host name you want to use for this system.
5. Edit the host/configuration.nix file to suit your needs. This file contains all of the available options and is fully documented.
6. Run nixos-rebuild boot --flake .#<your hostname> and restart.
7. Enjoy your new NixOS system!

Additional options

This section is for options that require additional information or setup.

Hardware-specific options

NixOS-Hardware is a community library of NixOS modules to work around quirks with specific kinds of hardware, especially laptops and SBCs like Raspberry Pis. If you know your system's model, you can see if it's available in NixOS-Hardware by checking the project's flake.nix. If so, add its module to your host's flake.nix like so:

modules = [
    ...
    nixos-hardware.nixosModules.framework-13th-gen-intel
    ...
]

Secure Boot support

This configuration supports Secure Boot systems, but with some additional setup required. Secure Boot is a UEFI standard meant to prevent the pre-boot process by requiring boot images to be signed by a trusted authority. The goal is to prevent tampering, e.g. by a malicious third-party replacing your kernel image with a compromised image. In NixOS, Secure Boot support is provided by the Lanzaboote project.

To enable Secure Boot support:

1. Install NixOS using the default systemd-boot bootloader, and with Secure Boot disabled via UEFI. To confirm this, run bootctl status and look for output similar to the following:

   $ bootctl status
   System:
       Firmware: UEFI 2.70 (Lenovo 0.4720)
   Secure Boot: disabled (disabled)
   TPM2 Support: yes
   Boot into FW: supported
   
   Current Boot Loader:
       Product: systemd-boot 251.7
   ...
   

2. Generate a set of Secure Boot keys by running the following command: sudo sbctl create-keys. This creates a set of keys in /etc/secureboot.
3. Enable Secure Boot in your system configuration by setting aux.bootloader.secureboot.enable = true;.
4. Rebuild your system using nixos-rebuild switch --flake ..
5. Confirm that Secure Boot has been set up properly by running sudo sbctl verify:

   Verifying file database and EFI images in /boot...
   ✓ /boot/EFI/BOOT/BOOTX64.EFI is signed
   ✓ /boot/EFI/Linux/nixos-generation-355.efi is signed
   ✓ /boot/EFI/Linux/nixos-generation-356.efi is signed
   ✗ /boot/EFI/nixos/0n01vj3mq06pc31i2yhxndvhv4kwl2vp-linux-6.1.3-bzImage.efi is not signed
   ✓ /boot/EFI/systemd/systemd-bootx64.efi is signed
   

6. Reboot into your system's UEFI firmware. An easy way to do this from a running system is to run systemctl reboot --firmware-setup. In UEFI, set Secure Boot to setup mode. This will vary by system and UEFI vendor. On a ThinkPad, you can find these settings by selecting the "Security" tab, then the "Secure Boot" entry. Set "Secure Boot" to enabled, then select "Reset to Setup Mode". Save your changes and exit.
   • On systems where there is no setup mode, choose the option to erase the existing Platform key, and/or to allow third-party keys.
7. Once you've rebooted into NixOS, run this command to enroll your keys: sudo sbctl enroll-keys --microsoft. You should see the following output:

   Enrolling keys to EFI variables...
   With vendor keys from microsoft...✓
   Enrolled keys to the EFI variables!
   

8. Reboot your system, then verify your keys were installed correctly using bootctl status:

   System:
       Firmware: UEFI 2.70 (Lenovo 0.4720)
       Firmware Arch: x64
       Secure Boot: enabled (user)
       TPM2 Support: yes
       Boot into FW: supported
   

Disabling Secure Boot

To disable Secure Boot, just set aux.bootloader.secureboot.enable = false; and rebuild the system.