From 5df58aaf20d762fb342d0b26e8bfd6a800bbdcfd Mon Sep 17 00:00:00 2001 From: Qubasa Date: Sat, 24 Aug 2024 13:10:22 +0200 Subject: [PATCH] docs: Improve iwd, vaultwarden, dyndns, disk-encryption and installer documentation --- clanModules/dyndns/README.md | 2 +- clanModules/dyndns/default.nix | 22 +- clanModules/iwd/default.nix | 5 +- clanModules/vaultwarden/README.md | 13 +- docs/site/getting-started/disk-encryption.md | 336 +++++++++++-------- docs/site/getting-started/installer.md | 40 ++- 6 files changed, 237 insertions(+), 181 deletions(-) diff --git a/clanModules/dyndns/README.md b/clanModules/dyndns/README.md index b739c5efb..603ad553d 100644 --- a/clanModules/dyndns/README.md +++ b/clanModules/dyndns/README.md @@ -2,5 +2,5 @@ description = "A dynamic DNS service to update domain IPs" --- - +To understand the possible options that can be set visit the documentation of [ddns-updater](https://github.com/qdm12/ddns-updater?tab=readme-ov-file#versioned-documentation) diff --git a/clanModules/dyndns/default.nix b/clanModules/dyndns/default.nix index 7722005c6..7e0b866d1 100644 --- a/clanModules/dyndns/default.nix +++ b/clanModules/dyndns/default.nix @@ -58,18 +58,6 @@ let in { options.clan.${name} = { - - user = lib.mkOption { - type = lib.types.str; - default = name; - description = "User to run the service as"; - }; - group = lib.mkOption { - type = lib.types.str; - default = name; - description = "Group to run the service as"; - }; - server = { enable = lib.mkEnableOption "dyndns webserver"; domain = lib.mkOption { @@ -150,9 +138,9 @@ in (lib.mkIf (cfg.settings != { }) { clan.core.facts.services = lib.mapAttrs' secret_generator cfg.settings; - users.groups.${cfg.group} = { }; - users.users.${cfg.user} = { - group = cfg.group; + users.groups.${name} = { }; + users.users.${name} = { + group = name; isSystemUser = true; description = "User for ${name} service"; home = "/var/lib/${name}"; @@ -236,8 +224,8 @@ in ExecStartPre = lib.getExe pyscript; ExecStart = lib.getExe pkgs.ddns-updater; LoadCredential = lib.mapAttrsToList (_: opt: "${secret_id opt}:${secret_path opt}") cfg.settings; - User = cfg.user; - Group = cfg.group; + User = name; + Group = name; NoNewPrivileges = true; PrivateTmp = true; ProtectSystem = "strict"; diff --git a/clanModules/iwd/default.nix b/clanModules/iwd/default.nix index afbcbc616..32158e143 100644 --- a/clanModules/iwd/default.nix +++ b/clanModules/iwd/default.nix @@ -31,7 +31,7 @@ in { options = { ssid = lib.mkOption { - type = lib.types.strMatching "^[a-zA-Z0-9._-]+$"; + type = lib.types.str; default = name; description = "The name of the wifi network"; }; @@ -67,6 +67,9 @@ in # disable wpa supplicant networking.wireless.enable = false; + # Set the network manager backend to iwd + networking.networkmanager.wifi.backend = "iwd"; + # Use iwd instead of wpa_supplicant. It has a user friendly CLI networking.wireless.iwd = { enable = true; diff --git a/clanModules/vaultwarden/README.md b/clanModules/vaultwarden/README.md index d2d0b76b8..fa0afd86f 100644 --- a/clanModules/vaultwarden/README.md +++ b/clanModules/vaultwarden/README.md @@ -1,3 +1,14 @@ --- -description = "The server for the password manager bitwarden" +description = "The server for the centralized password manager bitwarden" --- + +After enabling the clan module, user accounts have to be created manually in the webinterface. +This is done by visiting `vaultwarden.example.com/admin` and typing in the admin password. +You can get the admin password for vaultwarden by executing: +```bash +clan secrets get -vaultwarden-admin +``` +To see all secrets tied to vaultwarden execute: +```bash +clan secrets list | grep vaultwarden +``` diff --git a/docs/site/getting-started/disk-encryption.md b/docs/site/getting-started/disk-encryption.md index 1af4ee47d..5efb0492f 100644 --- a/docs/site/getting-started/disk-encryption.md +++ b/docs/site/getting-started/disk-encryption.md @@ -1,167 +1,213 @@ -## Setting up Encryption with Remote Decryption in NixOS -This guide provides an example setup for a single-disk ZFS system with native encryption, accessible for decryption remotely. This configuration only applies to `systemd-boot` enabled systems and requires UEFI booting. +This guide provides an example setup for a single-disk ZFS system with native encryption, accessible for decryption remotely. -For a mirrored disk setup, add `mode = "mirror";` to `zroot`. Under the `disk` option, provide the additional disk identifier, e.g., `y = mirrorBoot /dev/disk/by-id/`. +!!! Warning + This configuration only applies to `systemd-boot` enabled systems and **requires** UEFI booting. -Replace the disk `nvme-eui.002538b931b59865` with your own. -Below is the configuration for `disko.nix` -```nix -{ lib, ... }: -let - mirrorBoot = idx: { - type = "disk"; - device = "/dev/disk/by-id/${idx}"; - content = { - type = "gpt"; - partitions = { - boot = { - size = "1M"; - type = "EF02"; # for grub MBR - priority = 1; - }; - ESP = lib.mkIf (idx == "nvme-eui.002538b931b59865") { - size = "1G"; - type = "EF00"; - content = { - type = "filesystem"; - format = "vfat"; - mountpoint = "/boot"; - mountOptions = [ "nofail" ]; - }; - }; - zfs = { - size = "100%"; - content = { - type = "zfs"; - pool = "zroot"; - }; - }; - }; - }; - }; -in -{ - boot.loader.systemd-boot.enable = true; - - disko.devices = { - disk = { - x = mirrorBoot "nvme-eui.002538b931b59865"; - }; - zpool = { - zroot = { - type = "zpool"; - rootFsOptions = { - compression = "lz4"; - acltype = "posixacl"; - xattr = "sa"; - "com.sun:auto-snapshot" = "true"; - mountpoint = "none"; - }; - datasets = { - "root" = { - type = "zfs_fs"; - options = { - mountpoint = "none"; - encryption = "aes-256-gcm"; - keyformat = "passphrase"; - keylocation = "file:///tmp/secret.key"; - }; - }; - "root/nixos" = { - type = "zfs_fs"; - options.mountpoint = "/"; - mountpoint = "/"; - }; - "root/home" = { - type = "zfs_fs"; - options.mountpoint = "/home"; - mountpoint = "/home"; - }; - "root/tmp" = { - type = "zfs_fs"; - mountpoint = "/tmp"; - options = { - mountpoint = "/tmp"; - sync = "disabled"; - }; - }; - }; - }; - }; - }; -} +Replace the highlighted lines with your own disk-id. +You can find our your disk-id by executing: +```bash +lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT ``` -Add this to networking.nix and **replace** the `default` values as well as the name `gchq-local` and `networking.hostId` with your own. -```nix -{ config, lib, ... }: -{ - options = { - networking.gchq-local.ipv4.address = lib.mkOption { - type = lib.types.str; - default = "192.168.178.177"; - }; - networking.gchq-local.ipv4.cidr = lib.mkOption { - type = lib.types.str; - default = "24"; +=== "**Single Disk**" + Below is the configuration for `disko.nix` + ```nix hl_lines="14 40" + { lib, ... }: + let + mirrorBoot = idx: { + type = "disk"; + device = "/dev/disk/by-id/${idx}"; + content = { + type = "gpt"; + partitions = { + boot = { + size = "1M"; + type = "EF02"; # for grub MBR + priority = 1; + }; + ESP = lib.mkIf (idx == "nvme-eui.002538b931b59865") { + size = "1G"; + type = "EF00"; + content = { + type = "filesystem"; + format = "vfat"; + mountpoint = "/boot"; + mountOptions = [ "nofail" ]; + }; + }; + zfs = { + size = "100%"; + content = { + type = "zfs"; + pool = "zroot"; + }; + }; + }; + }; }; + in + { + boot.loader.systemd-boot.enable = true; - networking.gchq-local.ipv4.gateway = lib.mkOption { - type = lib.types.str; - default = "192.168.178.1"; + disko.devices = { + disk = { + x = mirrorBoot "nvme-eui.002538b931b59865"; + }; + zpool = { + zroot = { + type = "zpool"; + rootFsOptions = { + compression = "lz4"; + acltype = "posixacl"; + xattr = "sa"; + "com.sun:auto-snapshot" = "true"; + mountpoint = "none"; + }; + datasets = { + "root" = { + type = "zfs_fs"; + options = { + mountpoint = "none"; + encryption = "aes-256-gcm"; + keyformat = "passphrase"; + keylocation = "file:///tmp/secret.key"; + }; + }; + "root/nixos" = { + type = "zfs_fs"; + options.mountpoint = "/"; + mountpoint = "/"; + }; + "root/home" = { + type = "zfs_fs"; + options.mountpoint = "/home"; + mountpoint = "/home"; + }; + "root/tmp" = { + type = "zfs_fs"; + mountpoint = "/tmp"; + options = { + mountpoint = "/tmp"; + sync = "disabled"; + }; + }; + }; + }; + }; }; + } + ``` - networking.gchq-local.ipv6.address = lib.mkOption { - type = lib.types.str; - default = "2003:100:6701:d500:fbbc:40fb:cff3:3b87"; + + +=== "**Raid 1**" + Below is the configuration for `disko.nix` + ```nix hl_lines="14 40 41" + { lib, ... }: + let + mirrorBoot = idx: { + type = "disk"; + device = "/dev/disk/by-id/${idx}"; + content = { + type = "gpt"; + partitions = { + boot = { + size = "1M"; + type = "EF02"; # for grub MBR + priority = 1; + }; + ESP = lib.mkIf (idx == "nvme-eui.002538b931b59865") { + size = "1G"; + type = "EF00"; + content = { + type = "filesystem"; + format = "vfat"; + mountpoint = "/boot"; + mountOptions = [ "nofail" ]; + }; + }; + zfs = { + size = "100%"; + content = { + type = "zfs"; + pool = "zroot"; + }; + }; + }; + }; }; + in + { + boot.loader.systemd-boot.enable = true; - networking.gchq-local.ipv6.cidr = lib.mkOption { - type = lib.types.str; - default = "64"; + disko.devices = { + disk = { + x = mirrorBoot "nvme-eui.002538b931b59865"; + y = mirrorBoot "myOtherDrive" + }; + zpool = { + zroot = { + type = "zpool"; + rootFsOptions = { + compression = "lz4"; + acltype = "posixacl"; + xattr = "sa"; + "com.sun:auto-snapshot" = "true"; + mountpoint = "none"; + }; + datasets = { + "root" = { + type = "zfs_fs"; + options = { + mountpoint = "none"; + encryption = "aes-256-gcm"; + keyformat = "passphrase"; + keylocation = "file:///tmp/secret.key"; + }; + }; + "root/nixos" = { + type = "zfs_fs"; + options.mountpoint = "/"; + mountpoint = "/"; + }; + "root/home" = { + type = "zfs_fs"; + options.mountpoint = "/home"; + mountpoint = "/home"; + }; + "root/tmp" = { + type = "zfs_fs"; + mountpoint = "/tmp"; + options = { + mountpoint = "/tmp"; + sync = "disabled"; + }; + }; + }; + }; + }; }; - networking.gchq-local.ipv6.gateway = lib.mkOption { - type = lib.types.str; - default = "fe80::3ea6:2fff:feef:3435"; - }; - }; + } + ``` - config = { - networking.dhcpcd.enable = false; - networking.nameservers = [ "127.0.0.1" ]; - networking.hostId = "a76ebcca"; # Needs to be unique for each host - - # The '10' in the network name is the priority, so this will be the first network to be configured - systemd.network.networks."10-eth" = { - matchConfig.Type = "ether"; - addresses = [ - { - Address=config.networking.gchq-local.ipv4.address + "/" + config.networking.gchq-local.ipv4.cidr; - } - { - Address=config.networking.gchq-local.ipv6.address + "/" + config.networking.gchq-local.ipv6.cidr; - } - ]; - DHCP = "yes"; - }; - }; -} -``` - -Put this into initrd.nix and add your pubkey to `authorizedKeys`. -Replace `kernelModules` with the ethernet module loaded one on your system. -```nix +Below is the configuration for `initrd.nix`. +Replace `` with your ssh public key. +Replace `kernelModules` with the ethernet module loaded one on your target machine. +```nix hl_lines="18 29" {config, pkgs, ...}: { boot.initrd.systemd = { enable = true; - network.networks."10-eth" = config.systemd.network.networks."10-eth"; }; + + # uncomment this if you want to be asked for the decryption password on login + #users.root.shell = "/bin/systemd-tty-ask-password-agent"; + boot.initrd.network = { enable = true; @@ -178,8 +224,8 @@ Replace `kernelModules` with the ethernet module loaded one on your system. "xhci_pci" ]; - # Check the network card by running `lspci -k` on the target machine - boot.initrd.kernelModules = [ "r8169" ]; + # Find out the required network card driver by running `lspci -k` on the target machine + boot.initrd.kernelModules = [ "r8169" ]; } ``` @@ -298,4 +344,4 @@ systemd-tty-ask-password-agent --query After completing these steps, your NixOS should be successfully installed and ready for use. -**Note:** Replace `root@nixos-installer.local` and `192.168.178.141` with the appropriate user and IP addresses for your setup. Also, adjust `` to reflect the correct system path for your environment. \ No newline at end of file +**Note:** Replace `root@nixos-installer.local` and `192.168.178.141` with the appropriate user and IP addresses for your setup. Also, adjust `` to reflect the correct system path for your environment. diff --git a/docs/site/getting-started/installer.md b/docs/site/getting-started/installer.md index 797e6fec5..d4d7f2ab8 100644 --- a/docs/site/getting-started/installer.md +++ b/docs/site/getting-started/installer.md @@ -42,8 +42,8 @@ sudo umount /dev/sdb1 === "**Linux OS**" ### Step 2. Flash Custom Installer - Using clan flash enables the inclusion of ssh public keys. - It also allows to set language and keymap currently in the installer image. + Using clan flash enables the inclusion of ssh public keys and wifi access points. + It also allows to set language and keymap in the installer image. ```bash clan flash --flake git+https://git.clan.lol/clan/clan-core \ @@ -54,12 +54,6 @@ sudo umount /dev/sdb1 flash-installer ``` - The `--ssh-pubkey`, `--language` and `--keymap` are optional. - You can get a list of all keymaps with the following command: - - ``` - $ find $(nix-build 'https://github.com/NixOS/nixpkgs/archive/refs/heads/nixpkgs-unstable.tar.gz' --no-out-link -A kbd)/share/keymaps -type f -name '*.map.gz' - ``` Replace `$HOME/.ssh/id_ed25519.pub` with a path to your SSH public key. If you do not have an ssh key yet, you can generate one with `ssh-keygen -t ed25519` command. @@ -67,6 +61,25 @@ sudo umount /dev/sdb1 The `clan flash` utility will erase the disk. Make sure to specify the correct device + !!! Note + To add wifi credentials into the installer image append the option: + ``` + --wifi + ``` + + !!! Note + You can get a list of all keymaps with the following command: + ``` + clan flash asd --list-keymaps + ``` + + !!! Note + You can get a list of all languages with the following command: + ``` + clan flash asd --list-languages + ``` + + === "**Other OS**" @@ -95,9 +108,7 @@ sudo umount /dev/sdb1 ### Step 4. Boot and Connect to your network After writing the installer to the USB drive, use it to boot the target machine. - -!!! info - Plug it into the target machine and select the USB drive as a temporary boot device. +To do this plug the USB drive into the target machine and select the USB drive as a temporary boot device. ??? tip "Here you can find the key combinations for selection used by most vendors." - **Dell**: F12 (Boot Menu), F2/Del (BIOS Setup) @@ -112,16 +123,13 @@ After writing the installer to the USB drive, use it to boot the target machine. - **Apple**: Option (Alt) Key (Boot Menu for Mac) - If your hardware was not listed read the manufacturers instructions how to enter the boot Menu/BIOS Setup. -**During Boot** - -Select `NixOS` to boot into the clan installer. **After Booting** -For deploying your configuration the machine needs to be connected via LAN (recommended). +Now you can deploy your clan configuration onto the machine -## (Optional) Connect to Wifi +## (Optional) Connect to Wifi Manually If you don't have access via LAN the Installer offers support for connecting via Wifi.