diff --git a/.gitea/workflows/check-nixos.yml b/.gitea/workflows/check-nixos.yml index 27c5c9a..5edd218 100644 --- a/.gitea/workflows/check-nixos.yml +++ b/.gitea/workflows/check-nixos.yml @@ -20,7 +20,7 @@ jobs: - name: Evaluate all NixOS hosts run: | set -euo pipefail - for host in nixos docker kuma server nix-cache nix-minimal; do + for host in nixos docker kuma server nix-cache nix-minimal pxe-boot; do echo "Evaluating ${host}" nix --extra-experimental-features 'nix-command flakes' eval \ ".#nixosConfigurations.${host}.config.system.build.toplevel.drvPath" --raw diff --git a/.github/workflows/check-nixos.yml b/.github/workflows/check-nixos.yml index 27c5c9a..5edd218 100644 --- a/.github/workflows/check-nixos.yml +++ b/.github/workflows/check-nixos.yml @@ -20,7 +20,7 @@ jobs: - name: Evaluate all NixOS hosts run: | set -euo pipefail - for host in nixos docker kuma server nix-cache nix-minimal; do + for host in nixos docker kuma server nix-cache nix-minimal pxe-boot; do echo "Evaluating ${host}" nix --extra-experimental-features 'nix-command flakes' eval \ ".#nixosConfigurations.${host}.config.system.build.toplevel.drvPath" --raw diff --git a/AGENTS.md b/AGENTS.md index 04fb443..793f61c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,8 @@ ## Repo purpose -This repository contains flake-based NixOS configurations for Wayne’s LAN servers and workstation. +This repository contains flake-based NixOS configurations for Wayne's LAN +servers and workstation. The flake currently exposes these NixOS configurations: @@ -12,16 +13,22 @@ The flake currently exposes these NixOS configurations: - `server` - `nix-cache` - `nix-minimal` +- `pxe-boot` -Do not deploy, switch, reboot, repartition, format disks, or run destructive install commands from this repository unless explicitly asked. +Do not deploy, switch, reboot, repartition, format disks, or run destructive +install commands from this repository unless explicitly asked. ## Safety rules -- Never run `nixos-rebuild switch`, `boot`, `test`, `nixos-install`, `parted`, `mkfs`, `mkswap`, `swapon`, `mount`, or destructive disk commands in Codex. -- Validation work should be limited to evaluation, linting, formatting checks, and `nix build --dry-run --no-link`. -- Do not add secrets, tokens, private keys, password hashes, or live credentials to the repo. +- Never run `nixos-rebuild switch`, `boot`, `test`, `nixos-install`, `parted`, + `mkfs`, `mkswap`, `swapon`, `mount`, or destructive disk commands in Codex. +- Validation work should be limited to evaluation, linting, formatting checks, + and `nix build --dry-run --no-link`. +- Do not add secrets, tokens, private keys, password hashes, or live credentials + to the repo. - Treat `flake.nix`, Home Manager config, and Nix config files as public. -- If you find committed tokens or hashes, flag them immediately and recommend rotation/removal. +- If you find committed tokens or hashes, flag them immediately and recommend + rotation/removal. ## Expected commands @@ -31,3 +38,10 @@ Use these commands when validating changes: bash scripts/codex-setup.sh bash scripts/codex-maintenance.sh bash scripts/codex-maintenance.sh dry-run +``` + +Host evaluation is safe when limited to drvPath checks: + +```bash +nix eval .#nixosConfigurations..config.system.build.toplevel.drvPath --raw +``` diff --git a/README.md b/README.md index 4010c1b..1ecb38e 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,72 @@ - -## `README.md` - -```markdown # NixOS LAN Configurations -Flake-based NixOS configuration repository for Wayne’s LAN machines. +Flake-based NixOS configuration repository for Wayne's LAN servers and +workstation. ## Hosts This flake currently defines: | Host | Purpose | -|---|---| -| `nixos` | Main NixOS workstation / desktop | +| --- | --- | +| `nixos` | Main NixOS workstation / Cinnamon desktop | | `docker` | Docker host for the main container stack | | `kuma` | Docker-enabled Uptime Kuma style host | -| `server` | Storage / NFS / backup style server | -| `nix-cache` | Local Nix binary cache host | -| `nix-minimal` | Minimal NixOS host profile | +| `server` | Storage, NFS, backup, and monitoring exporter host | +| `nix-cache` | Local Nix binary cache and remote builder | +| `nix-minimal` | Minimal NixOS host profile with SSHFS tooling | +| `pxe-boot` | HTTP/iPXE boot asset host | List hosts with: ```bash nix eval --json .#nixosConfigurations --apply builtins.attrNames | jq -r '.[]' +``` + +## Layout + +| Path | Purpose | +| --- | --- | +| `flake.nix` | Flake inputs and `nixosConfigurations` outputs | +| `hosts//configuration.nix` | Host-specific NixOS configuration | +| `hosts/nixos/home.nix` | Workstation-specific Home Manager config | +| `common/` | Shared NixOS, Home Manager, aliases, and hardware config | +| `modules/nix/` | Binary cache and remote builder client/server modules | +| `docs/` | Operational notes for cache, builders, lock updates, and boot services | +| `scripts/` | Codex setup and validation helpers | + +## Validation + +Safe validation commands for Codex and local review: + +```bash +bash scripts/codex-setup.sh +bash scripts/codex-maintenance.sh dry-run +bash scripts/codex-maintenance.sh +``` + +For individual host evaluation: + +```bash +nix eval .#nixosConfigurations..config.system.build.toplevel.drvPath --raw +``` + +Use `nix build --dry-run --no-link` when build planning is needed. Do not run +deployment, install, disk formatting, mount, or reboot commands from automated +review sessions. + +## Operations + +- Host rebuilds should consume the committed `flake.lock`. +- Routine dependency updates should happen through the flake lock automation + described in `docs/flake-lock-automation.md`. +- `nix-cache` serves substitutes over HTTP and can act as a remote builder for + client hosts. +- `pxe-boot` serves iPXE boot files over HTTP from `/srv/pxe`. + +## Security Notes + +Do not commit tokens, private keys, live credentials, or new password hashes. +This repository currently contains committed password hashes in shared NixOS +configuration; rotate those passwords and move hashes into host-local secret +management before treating the repository as public or widely shared. diff --git a/docs/flake-lock-automation.md b/docs/flake-lock-automation.md index 8ac34b9..6867c24 100644 --- a/docs/flake-lock-automation.md +++ b/docs/flake-lock-automation.md @@ -1,6 +1,7 @@ # flake.lock automation -This repository uses CI workflows to keep `flake.lock` up to date on a schedule and to verify that all declared NixOS hosts still evaluate after dependency updates. +This repository uses CI workflows to keep `flake.lock` up to date on a schedule +and to verify that declared NixOS hosts still evaluate after dependency updates. ## What this automation does @@ -14,6 +15,7 @@ This repository uses CI workflows to keep `flake.lock` up to date on a schedule - `server` - `nix-cache` - `nix-minimal` + - `pxe-boot` ## Why hosts should stop using `--upgrade-all` @@ -27,6 +29,9 @@ sudo nixos-rebuild switch --flake git+https://gitea.lan.ddnsgeek.com/beatzaplent Using the committed lock file keeps all hosts aligned and makes updates auditable through CI and code review. +Codex and automated review sessions must not run rebuilds. Limit checks to +evaluation, linting, formatting, and dry-run builds. + ## Command differences - `nix flake update` diff --git a/docs/nix-cache.md b/docs/nix-cache.md index 8dbcaf5..ccdb36d 100644 --- a/docs/nix-cache.md +++ b/docs/nix-cache.md @@ -8,6 +8,8 @@ This repository configures `nix-cache` as a **binary cache server** and a **remo - Every machine still keeps and uses its own local `/nix/store`. - Clients prefer `http://nix-cache` for substitutes and keep `https://cache.nixos.org/` as fallback. - Clients can offload builds to `nix-cache` through SSH (`nix.distributedBuilds`). +- Client hosts import `modules/nix/cache-client.nix` and, when remote building is enabled, `modules/nix/remote-builder-client.nix`. +- The `nix-cache` host imports `modules/nix/cache-server.nix`. ## Binary cache signing keys (on nix-cache) @@ -20,6 +22,8 @@ cat /etc/nix/cache-pub.pem ``` Do not commit private keys. +Do not commit new password hashes or live credentials. Existing committed hashes +should be rotated and moved to host-local secret management. ## Remote builder SSH keys @@ -33,6 +37,9 @@ sudo ssh -i /root/.ssh/nixremote nixremote@nix-cache nix-store --version On `nix-cache`, install the matching public key used by `nixremote` authorized keys. +The committed `nixremote` authorized keys are public SSH keys only. Keep the +matching private keys on client hosts and out of the repository. + ## Manual verification After deployment: diff --git a/docs/pxe-boot.md b/docs/pxe-boot.md new file mode 100644 index 0000000..f5e709d --- /dev/null +++ b/docs/pxe-boot.md @@ -0,0 +1,52 @@ +# pxe-boot + +The `pxe-boot` host serves HTTP boot assets for iPXE clients. + +## Host Role + +- Hostname: `pxe-boot` +- Web service: nginx on TCP port 80 +- PXE root: `/srv/pxe` +- Generated iPXE menu: `/srv/pxe/boot/menu.ipxe` +- Boot binaries copied from the Nix `ipxe` package: + - `/srv/pxe/boot/ipxe.efi` + - `/srv/pxe/boot/undionly.kpxe` + +## Directory Layout + +The host creates these directories with systemd tmpfiles: + +```text +/srv/pxe +/srv/pxe/boot +/srv/pxe/nixos +/srv/pxe/ubuntu +/srv/pxe/rescue +``` + +The generated menu currently exposes entries for: + +- NixOS installer +- Rescue environment +- iPXE shell +- Reboot + +Kernel and initrd artifacts for installer or rescue entries must be placed under +the matching `/srv/pxe//` directories by an operator or a separate build +process. This repository defines the service and menu, not the installer images. + +## Validation + +Safe evaluation check: + +```bash +nix eval .#nixosConfigurations.pxe-boot.config.system.build.toplevel.drvPath --raw +``` + +After deployment by an operator, basic service checks are: + +```bash +curl http://pxe-boot/boot/menu.ipxe +curl -I http://pxe-boot/boot/ipxe.efi +curl -I http://pxe-boot/boot/undionly.kpxe +```