Verified Commit dc92e187 authored by Matthias Adamczyk's avatar Matthias Adamczyk
Browse files

Refactor and document the lib/ folder

parent 73a9eacf
Pipeline #792 passed with stages
in 6 minutes and 3 seconds
...@@ -7,6 +7,7 @@ ...@@ -7,6 +7,7 @@
## Why Nix/NixOS? ## Why Nix/NixOS?
Pros: 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! - 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. - 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. A configuration can be built from literally anywhere where nix is installed.
...@@ -83,9 +84,7 @@ nix build -f . deploy.all && ./result switch ...@@ -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). 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 ### ...unlock a machine with full disk encryption
**NOTE: These instructions are a work in progress**
``` ```
nix-build -A unlock.HOSTNAME && ./result nix-build -A unlock.HOSTNAME && ./result
...@@ -129,7 +128,7 @@ Alternatively, use the [official ISO](https://nixos.org/download.html). ...@@ -129,7 +128,7 @@ Alternatively, use the [official ISO](https://nixos.org/download.html).
nix build -f . isoImage 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 ### ...add a new server to the configuration
...@@ -139,12 +138,12 @@ Create a new directory with the hostname under `hosts/` and copy the configurati ...@@ -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 caveats and how we solve them
* Nix can not manage state - Nix can not manage state
* Create backups of stateful data (databases, etc.) to ensure rollbacks are always possible - 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 - 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 - Deploy secrets to /var/src/secrets/ from local password-store
* Services read the secrets they need from there at runtime - 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 - 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 ## 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 ...@@ -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) - 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) - 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: - 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"` - 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) - 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. - Avoid nix-env, because it will install applications into your user profile and these won't be updated with the system configuration.
......
...@@ -18,9 +18,9 @@ in { ...@@ -18,9 +18,9 @@ in {
inherit (pkgs) lib; # the syntax means: "inherit lib from pkgs" inherit (pkgs) lib; # the syntax means: "inherit lib from pkgs"
# The following commands are available: # 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; }; 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 #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/
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
```
# 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 }: { pkgs }:
with pkgs.lib; with pkgs.lib;
......
{ 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; with pkgs.lib;
rec { rec {
hostsDir = ../hosts; hostsDir = ../../hosts;
hostNames = attrNames ( hostNames = attrNames (
filterAttrs ( filterAttrs (
...@@ -29,7 +30,7 @@ rec { ...@@ -29,7 +30,7 @@ rec {
).system or "x86_64-linux" ).system or "x86_64-linux"
; ;
nixpkgsFor = hostName: (import ../pkgs { nixpkgsFor = hostName: (import ../../pkgs {
system = hostArch hostName; system = hostArch hostName;
}).path; }).path;
...@@ -39,12 +40,12 @@ rec { ...@@ -39,12 +40,12 @@ rec {
}; };
imports = [ imports = [
(import (hostsDir + "/${hostName}/configuration.nix")) (import (hostsDir + "/${hostName}/configuration.nix"))
../modules ../../modules
]; ];
networking = { networking = {
inherit hostName; inherit hostName;
}; };
nixpkgs.pkgs = import ../pkgs { nixpkgs.pkgs = import ../../pkgs {
inherit (config.nixpkgs) config system; inherit (config.nixpkgs) config system;
}; };
}; };
......
# Not being used right now. You can safely ignore this file.
{ lib ? import <nixpkgs/lib> }: { lib ? import <nixpkgs/lib> }:
with lib; with lib;
......
# 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, ... }: { pkgs, ... }:
let let
......
{ pkgs }:
let
nixos = import (pkgs.path + "/nixos") {
configuration = import ./kexec-host.nix;
};
in
nixos.config.system.build.kexec_tarball
# 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, pkgs, config, modulesPath, ... }: # This file builds a kexec tarball and includes the configuration from ../../common.
{ config, lib, pkgs, modulesPath, ... }:
{ {
imports = [ imports = [
(modulesPath + "/installer/netboot/netboot.nix") (modulesPath + "/installer/netboot/netboot.nix")
../common ../../common
]; ];
boot.loader.grub.enable = false; boot.loader.grub.enable = false;
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment