yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
clan-bot
2024-08-24 11:15:24 +00:00
parent aba4a1494f ca60743b2b
commit 72653f537f
6 changed files with 237 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
clanModules/dyndns/README.md
View File

@@ -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)

22
clanModules/dyndns/default.nix
View File

@@ -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";

5
clanModules/iwd/default.nix
View File

@@ -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;

13
clanModules/vaultwarden/README.md
View File

@@ -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
```

332
docs/site/getting-started/disk-encryption.md
View File

@@ -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`
```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 `<yourkey>` 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,7 +224,7 @@ 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" ];
}
```

40
docs/site/getting-started/installer.md
View File

@@ -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 <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.
!!! 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.