templates/system/README.md

93 lines
6.3 KiB
Markdown
Raw Permalink Normal View History

# Auxolotl New User System Configuration
A ready-to-run NixOS configuration with opinionated defaults.
The goal of this config is to make it as easy as possible to build a NixOS system for an out-of-the-box experience similar to user-friendly distributions like Ubuntu, Fedora, or Mint. Nearly all configuration is done by editing `host/configuration.nix`. Where possible, we provided simple boolean (true/false) flags for enabling things like GPU drivers and desktop environments. These options are made available under the `aux.system` namespace. You can, of course, extend this template however you'd like.
## Getting Started
1. [Install a fresh copy of NixOS and boot into your new system](https://nixos.org/manual/nixos/stable/index.html#ch-installation).
2. Open a terminal and create a new copy of this template by running `nix --extra-experimental-features nix-command --extra-experimental-features flakes flake new -t github:auxolotl/templates#system nixos-config`.
3. Change into the new folder using `cd nixos-config`.
4. 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 `hardware-configuration.nix` file.
5. Edit `flake.nix` and set the following variables:
1. Change `hostName` to the hostname you want to give this system.
2. If your system is running on an architecture other than 64-bit Linux, change `platform` to the architecture that you're using. Details on the various options are documented in `flake.nix`.
6. Edit the `host/configuration.nix` file to suit your needs. This file documents all of the different options available. In most cases, you can enable an option by changing `false` to `true`.
1. Change the `username` variable. If you installed NixOS using the standard install medium, you can change this to match the username you chose during installation. Otherwise, it will create a new user account.
2. If you're creating a new user account, don't forget to set its password by running `sudo passwd <username>`.
7. Run `sudo nixos-rebuild boot --flake .#<your hostname>` and restart.
8. 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](https://github.com/NixOS/nixos-hardware/blob/master/flake.nix). If so, add its module to your host's `flake.nix` like so:
```nix
modules = [
...
nixos-hardware.nixosModules.framework-13th-gen-intel
...
]
```
#### Nvidia GPU support
For users with a hybrid Nvidia GPU setup (e.g. laptop users), there's some additional setup you need to do. This setup requires you to find the PCI bus IDs for your Nvidia GPU and your secondary GPU (usually an integrated Intel or AMD GPU). [The NixOS wiki has instructions on how to find these](https://nixos.wiki/wiki/Nvidia#Laptop_Configuration:_Hybrid_Graphics_.28Nvidia_Optimus_PRIME.29). Once you have the bus IDs, you can set `aux.system.gpu.nvidia.hybrid.busIDs.intel` or `aux.system.gpu.nvidia.hybrid.busIDs.amd`.
### Secure Boot support
This configuration supports [Secure Boot](https://wiki.archlinux.org/title/Unified_Extensible_Firmware_Interface/Secure_Boot) systems, but with some additional setup required. Secure Boot is a UEFI standard meant to prevent tampering with the pre-boot process, 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](https://github.com/nix-community/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` on a fresh NixOS installation and look for output similar to the following:
```sh
$ 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.system.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`:
```sh
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:
```sh
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`:
```sh
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.system.bootloader.secureboot.enable = false;` and rebuild the system.