Merge pull request 'docs: Improve iwd, vaultwarden, dyndns, disk-encryption and installer documentation' (#1965) from Qubasa/clan-core:Qubasa-main into main

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)
 

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.groups.${name} = { };
-      users.users.${cfg.user} = {
+      users.users.${name} = {
-        group = cfg.group;
+        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;
+            User = name;
-            Group = cfg.group;
+            Group = name;
             NoNewPrivileges = true;
             PrivateTmp = true;
             ProtectSystem = "strict";

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;

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  <machine-name>-vaultwarden-admin
+```
+To see all secrets tied to vaultwarden execute:
+```bash
+clan secrets list | grep vaultwarden
+```

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/<second_disk_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`
+Replace the highlighted lines with your own disk-id.
-```nix
+You can find our your disk-id by executing:
-{ lib, ... }:
+```bash
-let
+lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
-  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";
-            };
-          };
-        };
-      };
-    };
-  };
-}
 ```
 
-Add this to networking.nix and **replace** the `default` values as well as the name `gchq-local` and `networking.hostId` with your own.
 
-```nix
+=== "**Single Disk**"
-{ config, lib, ... }:
+    Below is the configuration for `disko.nix`
-{
+    ```nix hl_lines="14 40"
-  options = {
+    { lib, ... }:
-    networking.gchq-local.ipv4.address = lib.mkOption {
+    let
-      type = lib.types.str;
+    mirrorBoot = idx: {
-      default = "192.168.178.177";
+        type = "disk";
-    };
+        device = "/dev/disk/by-id/${idx}";
-    networking.gchq-local.ipv4.cidr = lib.mkOption {
+        content = {
-      type = lib.types.str;
+            type = "gpt";
-      default = "24";
+            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 {
+    disko.devices = {
-      type = lib.types.str;
+        disk = {
-      default = "192.168.178.1";
+            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 {
+    disko.devices = {
-      type = lib.types.str;
+        disk = {
-      default = "64";
+            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 = {
+Below is the configuration for `initrd.nix`.  
-    networking.dhcpcd.enable = false;
+Replace `<yourkey>` with your ssh public key.  
-    networking.nameservers = [ "127.0.0.1" ];
+Replace `kernelModules` with the ethernet module loaded one on your target machine.
-    networking.hostId = "a76ebcca"; # Needs to be unique for each host
+```nix hl_lines="18 29"
-
-    # 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
 {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
+  # Find out the required network card driver by running `lspci -k` on the target machine
-  boot.initrd.kernelModules = [ "r8169" ];
+  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 `<SYS_PATH>` to reflect the correct system path for your environment.
+**Note:** Replace `root@nixos-installer.local` and `192.168.178.141` with the appropriate user and IP addresses for your setup. Also, adjust `<SYS_PATH>` to reflect the correct system path for your environment.

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.
+    Using clan flash enables the inclusion of ssh public keys and wifi access points.
-    It also allows to set language and keymap currently in the installer image.
+    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 <ssid> <password>  
+        ```
+
+    !!! 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.
-
+To do this plug the USB drive into the target machine and select the USB drive as a temporary boot device.
-!!! info 
-    Plug it 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.