nix-git

This repository contains my NixOS configuration files with some guidance on how to use them.

See also:

• TODO.md
• NixOS.md

Table of Contents

• nix-git
  • Table of Contents
  • NixOS installation
    • Graphical installation
    • Remote installation: disko and nixos-anywhere
    • ARM: SD image for the Raspberry Pi 3B+
      • ISO creation
      • Default configuration
      • Apply modified configuration
    • ARM: Vanilla UEFI bootloader for the Raspberry Pi 3B+
  • Update, build and switch
    • tldr
    • Update
    • Build and switch: Using Colmena
    • Build and switch: Manually
      • Option I: Build new config and activate it:
      • Option II: Build new config and activate it during next boot:
      • Option III: Build config and view changes:
  • Colmena: Deployment and secret management
  • BTRFS swap file
  • BTRFS CoW
  • Automount encrypted drive
  • List active and failed services
  • View system log
  • Server maintenance with a smartphone

NixOS installation

Graphical installation

For beginners, NixOS can be installed with a graphical installer.

Getting the ISO:

• There is no official torrent as they are not needed due to CDN.
• ISO and checksum are available here: https://nixos.org/download#nixos-iso
• There are unofficial torrents. If the checksum is compared with the one from the official website, these can be used as well: https://github.com/AnimMouse/NixOS-ISO-Torrents/releases

During installation:

• If the installation target is a SSD
  • Trim the whole disk to mark all cells as unused and restore its initial performance
  • sudo blkdiscard -f /dev/nvmeXXX
• Select manual partitioning:
  • One 512MB (or larger) Fat32 partition, mounted at /boot, "boot" flag enabled
  • Another partition (e.g. BTRFS) covering the rest of the drive, mounted at /, encryption enabled

Remote installation: disko and nixos-anywhere

Install NixOS via SSH everywhere.

There is a separate repository for these steps. Its README can be found here: https://codeberg.org/privacy1st/nixos-anywhere-example/src/template/README.md

ARM: SD image for the Raspberry Pi 3B+

ISO creation

If you are on an architecture other than aarch64, enable emulation: boot.binfmt.emulatedSystems = [ "aarch64-linux" ];.

An ISO for the Raspberry Pi 3B+ can then be built with:

# If on aarch64
#nix-build '<nixpkgs/nixos>' -A config.system.build.sdImage -I nixos-config=./iso-aarch64.nix
# If not on aarch64
nix-build '<nixpkgs/nixos>' -A config.system.build.sdImage -I nixos-config=./iso-aarch64.nix --argstr system aarch64-linux

ls result/sd-image/*.img

Note about cross compilation

Alternatively to emulating the aarch64 architecture we could also cross compile from e.g. x86 to it. However, this has one big drawback: The binary cache (https://cache.nixos.org/) won't be used. The reason for this is that packages built with cross compilation are (slightly) different from native built ones. Their checksums don't match.

Default configuration

When the Raspberry Pi is booted, run nixos-generate-config to generate the default configuration.nix and hardware-configuration.nix files.

A slightly modified config can be found in ./hosts/pi3bplus

Apply modified configuration

The Raspberry Pi 3B+ has only 1GB RAM, which is not enough for nixos-rebuild. It is recommended to create and activate a SWAP file first: https://wiki.archlinux.org/title/swap#Swap_file_creation

nix-channel --list
#=> nixos https://nixos.org/channels/nixos-23.05
nix-channel --update nixos

passwd

nixos-rebuild boot
reboot

ARM: Vanilla UEFI bootloader for the Raspberry Pi 3B+

TODO: The EFI menu was working. But I got many squashfs errors when booting an USB stick with the NixOS installer.

• https://www.eisfunke.com/posts/2023/uefi-boot-on-raspberry-pi-3.html

Preparing a micro SD card with an UEFI bootloader:

nix-shell -p parted gptfdisk

sudo parted --script /dev/SDX -- \
	mklabel gpt \
	mkpart ESP fat32 2Mib 512MiB \
	set 1 esp on \
	mkpart primary 512MiB 100% \
	print

sudo wipefs --all /dev/SDX1
sudo wipefs --all /dev/SDX2

sudo mkfs.fat -F32 /dev/SDX1

sudo gdisk /dev/SDX
# r
# p
# h
# 1
# N
# 0c
# N
# N
# o
# w
# Y

In addition to the SD card, attach an USB stick with NixOS ARM (https://nixos.org/download.html#nixos-iso, https://hydra.nixos.org/job/nixos/release-23.05/nixos.iso_minimal.aarch64-linux, https://hydra.nixos.org/job/nixos/release-23.05/nixos.iso_minimal_new_kernel_no_zfs.aarch64-linux or https://hydra.nixos.org/job/nixos/trunk-combined/nixos.iso_minimal.aarch64-linux) to the Raspberry Pi.

sudo umount /dev/SDX
sudo dd if=nixos-minimal-XXX-aarch64-linux.iso of=/dev/SDX bs=4M conv=fsync

Then install NixOS the way you prefer, but don't touch/modify the partition table!

See https://nixos.wiki/wiki/NixOS_on_ARM/UEFI#Installing

Update, build and switch

tldr

Local node (e.g. yodaTux):

sudo nix-channel --update && niv update
colmena build --on $(hostname) -v --show-trace && colmena apply-local --sudo boot

Single remote node (e.g. deploy to yodaTab):

niv update
colmena build --on remoteTab -v --show-trace && colmena apply --on remoteTab boot
colmena exec --on remoteTab "nix-channel --update"

Multiple remote nodes (e.g. deploy to all nodes with tag @server):

niv update
colmena build --on @server -v --show-trace && colmena apply --on @server boot
colmena exec --on @server "nix-channel --update"

Update

• Updating NixOS. https://superuser.com/a/1604695

Update channel and configuration:

sudo nix-channel --update && niv update

To apply the updates, continue with "Build and switch".

Build and switch: Using Colmena

See section "Colmena: Deployment and secret management" to build and apply updates.

Build and switch: Manually

• https://nixos.wiki/wiki/Nixos-rebuild
• https://discourse.nixos.org/t/how-to-get-this-pending-updates-notification-in-gnome/16344/3
• https://discourse.nixos.org/t/how-to-get-this-pending-updates-notification-in-gnome/16344/6

Option I: Build new config and activate it:

sudo nixos-rebuild -I nixos-config=hosts/$(hostname)/configuration.nix switch

To view changes, see section "Compare two versions of NixOS system profile".

Option II: Build new config and activate it during next boot:

sudo nixos-rebuild -I nixos-config=hosts/$(hostname)/configuration.nix boot

Option III: Build config and view changes:

# This leaves a symlink named `result` in the current directory.
sudo nixos-rebuild -I nixos-config=hosts/$(hostname)/configuration.nix build
nix --extra-experimental-features nix-command store diff-closures /run/current-system ./result
#=> ...
#=> linux: 6.1.47, 6.1.47-modules → 6.1.51, 6.1.51-modules, -11.8 KiB

Depending on if there are large kernel changes, either switch to it directly or wait until next boot:

sudo ./result/bin/switch-to-configuration switch
# or
sudo ./result/bin/switch-to-configuration boot

Note: The Perl script executed by both above commands should create a new bootloader menu entry and mark it as default. However, if I remember correctly, the menu entry was once missing and the configuration change thus not permanent. This might need further testing. See also: https://nixos.wiki/wiki/Nixos-rebuild#Internals

Colmena: Deployment and secret management

• https://github.com/zhaofengli/colmena#colmena

Colmena is a simple, stateless NixOS deployment tool modeled after NixOps and morph, written in Rust.

Alternative: Deployment with Morph: https://xeiaso.net/blog/morph-setup-2021-04-25

Configuration is done inside hive.nix.

Build config:

colmena build -v

Apply to all non-local nodes:

colmena apply --on @server switch
#colmena apply --on @server boot

#colmena apply --on remoteTab switch
#colmena apply --on remoteTab boot

Apply to local node:

colmena apply-local --sudo switch
#colmena apply-local --sudo boot

Filtering:

• You can filter hosts by tags with --on @tag-a,@tag-b.
• You can use globs in tag matching as well: colmena apply --on '@infra-*'

BTRFS swap file

• Detailed instructions: https://nixos.wiki/wiki/Btrfs#Swap_file
• https://wiki.archlinux.org/title/btrfs#Swap_file

Summary:

• Create subvolume @swap directly below top-level subvolume.
• Mount at /swap
• Create swapfile: sudo btrfs filesystem mkswapfile --size 8g --uuid clear /swap/swapfile
• Regenerate hardware-configuration: sudo nixos-generate-config --dir hosts/$(hostname)
• Add swapDevices = [ { device = "/swap/swapfile"; } ]; to hardware configuration and run nixos-rebuild switch (see above).

BTRFS CoW

• https://wiki.archlinux.org/title/btrfs#Disabling_CoW

The Arch wiki has the following warning about disabling CoW:

Disabling CoW in Btrfs also disables checksums. Btrfs will not be able to detect corrupted nodatacow files. When combined with RAID 1, power outages or other sources of corruption can cause the data to become out of sync.

Thus, we e.g. don't disable CoW for increased DB performance.

When systemd initially creates its journal file, it warns us about enabled CoW:

Creating journal file /var/log/journal/.../system.journal on a btrfs file system, and copy-on-write is enabled. This is likely to slow down journal access substantially, please consider turning off the copy-on-write file attribute on the journal directory, using chattr +C.

As corruption of log files is not dramatic, we disable CoW for /var/log with

sudo chattr +C /var/log

Note from Arch wiki:

If the 'C' flag is set on a directory, it will have no effect on the directory, but new files created in that directory will have the No_COW attribute.

Automount encrypted drive

• Use the same password for all attached LUKS devices to be only prompted once while booting
  • Discussion: https://discourse.nixos.org/t/how-to-unlock-some-luks-devices-with-a-keyfile-on-a-first-luks-device/18949/11
  • Related NixOS config option: ed2ccd4d17/nixos/modules/system/boot/luksroot.nix (L570-L584)
• luksOpen and mount drive, e.g. to /mnt/data1
• Re-generate hardware configuration:

sudo nixos-generate-config --dir hosts/$(hostname)

• If it is an SSD, enable boot.initrd.luks.devices.<name>.allowDiscards

List active and failed services

If there are e.g. file conflicts due to preexisting dotfiles, the Home Manager user service might fail. To list all failed services, run:

systemctl --failed

List all active services:

systemctl list-units --type=service --state=running
systemctl --user list-units --type=service --state=running

View system log

# Kernel message log with timestamps
dmesg --ctime
# System journal: Errors since last boot.
journalctl -p err -b
# GNOME session logs since last boot. https://help.gnome.org/admin/system-admin-guide/stable/session-debug.html.en
journalctl _UID="${UID}" -b

Server maintenance with a smartphone

While I was on a bike tour I did some config changes to update my NixOS servers using only my smartphone and Nitrokey (GPG smartcard):

• home-manager.users.yoda.programs.git.signing.signByDefault = false;
• Import ../../modules/git.nix in hosts/yodaNas/configuration.nix
• Import ./../modules/docker-pushrm.nix in hosts/yodaNas/configuration.nix
• In hieve.nix, set allowLocalDeployment to true for yodaNas and yodaHedgehog

This allowed me to connect with my servers via ssh, git clone this NixOS configuration, build and switch to it with colmena and git commit and git push any changes.

On my smartphone I was using a terminal emulator with ssh and GPG smartcard support.

Another approach would have been to run colmena directly on the phone.