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

Refactor and document the lib/ folder

parent 31d4e46d
Pipeline #362 passed with stages
in 1 minute and 4 seconds
......@@ -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.
......
......@@ -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/
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 }:
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;
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;
};
};
......
# Not being used right now. You can safely ignore this file.
{ lib ? import <nixpkgs/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, ... }:
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 = [
(modulesPath + "/installer/netboot/netboot.nix")
../common
../../common
];
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