homelab/cheatsheet.md

You’ll also need to import the modules in your host config (they aren’t wired in flake.nix yet), e.g.:

imports = [
  ./hardware-configuration.nix
  ../../modules/core
  ../../modules/networking
  ../../modules/virtualization
];

---

homelab.core

Base system setup: kernel, bootloader, primary user, SSH, unfree packages.

Option	Type	Default	Notes
kernel	"stable" | "lts" | "latest"	"lts"	Maps to linuxPackages, linuxPackages_lts, linuxPackages_latest
bootloader.type	"grub" | "systemd"	"grub"	Which bootloader path to use
bootloader.grub.enable	bool	false	Set true when type = "grub"
bootloader.grub.device	string	"nodev"	GRUB install target, e.g. "/dev/sda"
bootloader.systemd.enable	bool	false	Set true when type = "systemd"
bootloader.systemd.efiSupport	bool	true
user.name	string	"river"
user.fullName	string	"Maaz Khokhar"
user.shell	string (typed as list in options — likely a bug)	"fish"	Used as programs.${shell}.enable
allowUnfree	bool	true
ssh.permitRootLogin	bool	false

Minimal core block:

homelab.core = {
  kernel = "lts";
  bootloader = {
    type = "systemd";
    systemd.enable = true;
  };
  # user / allowUnfree / ssh all have sensible defaults
};

What you actually need to set: bootloader details for your hardware (grub.device or systemd.enable). Everything else can stay default.

---

homelab.networking

Split into core (always active when module is imported), wireguard, and tailscale.

Top-level

Option	Type	Default
user	string	"river"	Used by Tailscale as --operator

homelab.networking.core (always on)

Option	Type	Default
firewall.allowPing	bool	true
firewall.ports.tcp	list of ints	[ 22 80 ]
firewall.ports.udp	list of ints	[ 53 ]
extraHosts	list of { ip_address, hostname }	[]
nameservers	list of strings	["192.168.1.193" "1.1.1.1" "1.0.0.1"]

Required only when you add extraHosts entries: ip_address and hostname (no defaults on those sub-options).

Minimal core block:

homelab.networking = {
  core = {
    nameservers = [ "1.1.1.1" "1.0.0.1" ];
    # firewall defaults are usually fine
  };
};

homelab.networking.wireguard (optional)

Option	Type	Default
enable	bool	false
interfaces	attrset of interface configs	(no default — use {} or omit if disabled)

Per interface (interfaces.<name>):

Option	Required?	Default
enable	no	false
address	no	[]
privateKeyFile	yes (when interface enabled)	—
peers	no	[]

Per peer:

Option	Required?	Default
publicKey	yes	—
allowedIPs	no	[]
endpoint	no	""
persistentKeepalive	no	null

Example when enabled:

homelab.networking.wireguard = {
  enable = true;
  interfaces.wg0 = {
    enable = true;
    address = [ "10.0.0.2/24" ];
    privateKeyFile = "/path/to/private.key";
    peers = [{
      publicKey = "...";
      allowedIPs = [ "0.0.0.0/0" ];
      endpoint = "vpn.example.com:51820";
    }];
  };
};

Note: wireguard.nix exists but is not imported in modules/networking/default.nix — only core and tailscale are. You’d need to add ./wireguard.nix to that imports list for WireGuard to work.

homelab.networking.tailscale (optional)

Option	Type	Default
enable	bool	false

Minimal:

homelab.networking.tailscale.enable = true;
# uses homelab.networking.user (default "river") as operator

---

homelab.virtualization

Split into podman and qemu.

Top-level

Option	Type	Default
user	string	"river"	Added to libvirtd/kvm/podman groups

homelab.virtualization.podman

Option	Type	Default
enable	bool	false
packages.enable	bool	false	Installs podman, podman-compose, podman-desktop

Minimal:

homelab.virtualization.podman = {
  enable = true;
  packages.enable = true;  # optional
};

homelab.virtualization.qemu

Option	Type	Default
enable	bool	false
containers.enable	bool	false	(defined in options but not wired in qemu.nix — containers are always enabled when qemu is)
spiceUSBRedirection	bool	false
virtManager	bool	false
bootModules	list of strings	[ "kvm-intel" "kvm-amd" ]

Minimal:

homelab.virtualization.qemu = {
  enable = true;
  virtManager = true;  # optional GUI
};

When qemu.enable = true, the module sets up libvirtd, adds your user to libvirtd/kvm, and loads KVM modules.

---

Full skeleton for hosts/test/configuration.nix

{ config, lib, pkgs, ... }:

{
  imports = [
    ./hardware-configuration.nix
    ../../modules/core
    ../../modules/networking
    ../../modules/virtualization
  ];

  homelab.core = {
    kernel = "lts";
    bootloader = {
      type = "systemd";
      systemd.enable = true;
    };
  };

  homelab.networking = {
    core.nameservers = [ "1.1.1.1" "1.0.0.1" ];
    tailscale.enable = true;
  };

  homelab.virtualization = {
    podman.enable = true;
    qemu = {
      enable = true;
      virtManager = true;
    };
  };
}