Refactor and document the lib/ folder

README.md

@@ -7,6 +7,7 @@
 ## Why Nix/NixOS?
 
 Pros:
+- Functional: Each package with its dependencies gets built separately. No more dependency hell like on Debian!
 - Declarative: Almost all of the system and services configuration can be set through options. No more manually editing `/etc` files!
 - Reproducible: Building the configuration leads to the exact same result no matter from where and how often you deploy the configuration.
   A configuration can be built from literally anywhere where nix is installed.
@@ -83,9 +84,7 @@ nix build -f . deploy.all && ./result switch
 This will generate a script which calls all deployment script as described in the section [...deploy a configuration change to production](#deploy-a-configuration-change-to-production).
 
 
-### ...unlock a virtual machine with full disk encryption
-
-**NOTE: These instructions are a work in progress**
+### ...unlock a machine with full disk encryption
 
 ```
 nix-build -A unlock.HOSTNAME && ./result
@@ -129,7 +128,7 @@ Alternatively, use the [official ISO](https://nixos.org/download.html).
 nix build -f . isoImage
 ```
 
-Afterwards, extract the resulting .tar.xz to `/` on the target host and execute `./kexec_nixos`.
+Afterwards, extract the resulting .tar.xz to `/` on the target host and execute `./kexec_nixos`. This will jump to the new kernel via the [kexec(8)](https://man7.org/linux/man-pages/man8/kexec.8.html) syscall.
 
 
 ### ...add a new server to the configuration
@@ -139,12 +138,12 @@ Create a new directory with the hostname under `hosts/` and copy the configurati
 
 ## Nix caveats and how we solve them
 
-* Nix can not manage state
-  * Create backups of stateful data (databases, etc.) to ensure rollbacks are always possible
-* Nix can not manage secrets, because all files in the nix store are world-readable
-  * Deploy secrets to /var/src/secrets/ from local password-store
-  * Services read the secrets they need from there at runtime
-  * Services that don't support reading the secret from a file use a ExecStartPre script to template secrets into the configuration file
+- Nix can not manage state
+  - Create backups of stateful data (databases, etc.) to ensure rollbacks are always possible
+- Nix can not manage secrets, because all files in the nix store are world-readable
+  - Deploy secrets to /var/src/secrets/ from local password-store
+  - Services read the secrets they need from there at runtime
+  - Services that don't support reading the secret from a file use a ExecStartPre script to template secrets into the configuration file
 
 ## Things to note when working on NixOS systems
 
@@ -152,7 +151,7 @@ Create a new directory with the hostname under `hosts/` and copy the configurati
   - Instead of creating users with `useradd`, add them to the NixOS system configuration (in [](common/users.nix)
   - Don't touch files in /etc/! They are automatically generated. If you want to change an option, look for the corresponding NixOS module option on [nixos.org/nixos/options.html](https://nixos.org/nixos/options.html)
   - If you want use an application that is not available on the system:
-    - Use the package search on [nixos.org/nixos/packages.html](https://nixos.org/nixos/packages.html?channel=nixpkgs-unstable) to find the application's **Attribute name**
+    - Use the package search on [nixos.org/nixos/packages.html](https://nixos.org/nixos/packages.html?channel=nixpkgs-unstable) to find the application's **attribute name**
     - Use nix-shell, for example: `nix-shell -p tcpdump --run "tcpdump -i enp4s0"`
     - If you use an application a lot, consider adding it to the [list here](common/default.nix)
     - Avoid nix-env, because it will install applications into your user profile and these won't be updated with the system configuration.

default.nix

@@ -18,9 +18,9 @@ in {
   inherit (pkgs) lib; # the syntax means: "inherit lib from pkgs"
   
   # The following commands are available:
-  kexec_tarball = import ./lib/kexec-tarball.nix { inherit pkgs; };
+  kexec_tarball = import ./lib/kexec-tarball { inherit pkgs; };
   isoImage = import ./lib/iso-image.nix { inherit pkgs; };
-  deploy = import ./lib/deploy.nix { inherit pkgs; };
+  deploy = import ./lib/deploy { inherit pkgs; };
   #unlock = import ./lib/unlock-fde.nix { inherit pkgs; }; # not needed right now
 }
-  // (import ./lib/hosts.nix { inherit pkgs; })
+  // (import ./lib/deploy/hosts.nix { inherit pkgs; })

lib/README.md

+# lib/
+
+This folder contains various scripts that aid the management of this repository.
+
+## Structure
+```
+└── lib/
+   ├── deploy/        # Build and deploy a host configuration
+   ├── kexec-tarball/ # Build a kexec tarball for installing a new host on a remote machine
+   ├── iso-image.nix  # Build a NixOS ISO for installing a new host with NixOS
+   ├── new-key.sh     # Add a new GPG public key of an admin or host to the password store
+   ├── pass.sh        # A wrapper around pass(1) that sets the password store folder to ../secrets
+   └── reencrypt-password-store # Reencrypts the password store after adding a new host/admin
+```

lib/deploy.nix → lib/deploy/default.nix

+# Builds and deploys a configuraiton change
+# 
+# To build the configuration:
+#
+# ```sh
+# $ nix build -f ../../ deploy.HOSTNAME
+# ```
+# where HOSTNAME is the hostname you wish to build the configuration for.
+# Use `deploy.all` to build the configuration for all hosts at once
+#
+#
+# To deploy the configuration:
+#
+# ```sh
+# $ ./result MODE
+# ```
+# where MODE is one of the following:
+# - `switch`
+#   - Builds and activates the new configuration, and makes it the boot default.
+# - `boot`
+#   - Builds the new configuration and makes it the boot default (as with `switch`), but does not activate it.
+#     That is, the system continues to run the previous configuration until the next reboot.
+# - `test`
+#   - Builds and activates the new configuration, but does not add it to the GRUB boot menu. Thus, if you reboot the
+#     system (or if it crashes), you will automatically revert to the default configuration.
+#
+# There are some more commands that can be found in nixos-rebuild(8)
 { pkgs }:
 
 with pkgs.lib;

lib/hosts.nix → lib/deploy/hosts.nix

-{ pkgs ? import ../pkgs { /* TODO system */} }:
+# This file does some magic in order to use the handy deploy command defined in ./default.nix
+{ pkgs ? import ../../pkgs { /* TODO system */} }:
 
 with pkgs.lib;
 
 rec {
-  hostsDir = ../hosts;
+  hostsDir = ../../hosts;
 
   hostNames = attrNames (
     filterAttrs (
@@ -29,7 +30,7 @@ rec {
     ).system or "x86_64-linux"
   ;
 
-  nixpkgsFor = hostName: (import ../pkgs {
+  nixpkgsFor = hostName: (import ../../pkgs {
     system = hostArch hostName;
   }).path;
 
@@ -39,12 +40,12 @@ rec {
     };
     imports = [
       (import (hostsDir + "/${hostName}/configuration.nix"))
-      ../modules
+      ../../modules
     ];
     networking = {
       inherit hostName;
     };
-    nixpkgs.pkgs = import ../pkgs {
+    nixpkgs.pkgs = import ../../pkgs {
       inherit (config.nixpkgs) config system;
     };
   };

lib/ip-util.nix → lib/deploy/ip-util.nix

+# Not being used right now. You can safely ignore this file.
 { lib ? import <nixpkgs/lib> }:
 
 with lib;

lib/iso-image.nix

+# Builds a NixOS ISO with a preconfigured OpenSSH server.
+# Users from ../common/users.nix can ssh to the booted Image with their SSH keys.
+#
+# To build the iso, run:
+# ```sh
+# $ nix build -f ../ isoImage
+# ```
+# The result of that operation can be found in the `./result` folder
 { pkgs, ... }:
 
 let

lib/kexec-tarball.nix

-{ pkgs }:
-
-let
-  nixos = import (pkgs.path + "/nixos") {
-    configuration = import ./kexec-host.nix;
-  };
-in
-  nixos.config.system.build.kexec_tarball

lib/kexec-tarball/default.nix

+# Builds a NixOS kexec tarball with a preconfigured OpenSSH server.
+# Users from ../common/users.nix can ssh to the booted Image with their SSH keys.
+#
+# To build the tarball, run:
+# ```sh
+# $ nix build -f ../../ kexec_tarball
+# ```
+#
+# The result of that operation can be found in the `./result` folder.
+# Copy the resulting `.tar.gz` to your destination, extract it to `/` (`tar -xJf kexec_nixos.tar.gz -C /`)
+# and run `./kexec_nixos`
+{ pkgs }:
+
+let
+  nixos = import (pkgs.path + "/nixos") {
+    configuration = import ./kexec-host.nix;
+  };
+in
+  nixos.config.system.build.kexec_tarball

lib/kexec-host.nix → lib/kexec-tarball/kexec-host.nix

-{ lib, pkgs, config, modulesPath, ... }:
+# This file builds a kexec tarball and includes the configuration from ../../common.
+{ config, lib, pkgs, modulesPath, ... }:
 
 {
   imports = [
     (modulesPath + "/installer/netboot/netboot.nix")
-    ../common
+    ../../common
   ];
 
   boot.loader.grub.enable = false;