From 1c2781267b985be68d515805cafbf5ce7282f701 Mon Sep 17 00:00:00 2001 From: Qubasa Date: Tue, 14 May 2024 16:13:50 +0200 Subject: [PATCH] Add clan flash documentation. --- docs/site/getting-started/configure.md | 21 +- docs/site/getting-started/deploy.md | 27 ++- docs/site/getting-started/installer.md | 43 ++-- docs/site/getting-started/secrets.md | 274 ++++++++++++------------- 4 files changed, 195 insertions(+), 170 deletions(-) diff --git a/docs/site/getting-started/configure.md b/docs/site/getting-started/configure.md index f0d2ea89..f3a2d80d 100644 --- a/docs/site/getting-started/configure.md +++ b/docs/site/getting-started/configure.md @@ -66,6 +66,9 @@ Adding or configuring a new machine requires two simple steps: ssh root@flash-installer.local lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT ``` + !!! Note + Replace `flash-installer.local` with the IP address of the machine if you don't have the avahi service running which resolves mDNS local domains. + Which should show something like: ```bash hl_lines="6" @@ -155,14 +158,20 @@ Adding or configuring a new machine requires two simple steps: These steps will allow you to update your machine later. #### Step 2: Detect Drivers -1. Generate the `hardware-configuration.nix` file for your machine using the following command: +Generate the `hardware-configuration.nix` file for your machine using the following command: - ```bash - ssh root@flash-installer.local nixos-generate-config --no-filesystems --show-hardware-config > machines/jon/hardware-configuration.nix - ``` +```bash +ssh root@flash-installer.local nixos-generate-config --no-filesystems --show-hardware-config > machines/jon/hardware-configuration.nix +``` + +#### Step 3: Custom Disk Formatting +In `./modules/disko.nix` a simple `ext4` disk partioning is defined for the disko module. +If you want a more complicated disk partioning setup look into the [disko examples](https://github.com/nix-community/disko/tree/master/example) + + +#### Step 4: Custom Configuration +In `./machines/jon/configuration.nix`, you can personalize the settings to suit your needs. -#### Step 3: Custom Configuration -1. In `./machines/jon/configuration.nix`, you can personalize the settings to suit your needs. --- diff --git a/docs/site/getting-started/deploy.md b/docs/site/getting-started/deploy.md index 038712f3..9fe0ffa8 100644 --- a/docs/site/getting-started/deploy.md +++ b/docs/site/getting-started/deploy.md @@ -20,9 +20,9 @@ This process involves preparing a suitable hardware and disk partitioning config - [x] **USB Flash Drive**: See [Clan Installer](installer.md) !!! Steps - + 1. Create a NixOS installer image and transfer it to a bootable USB drive as described in the [installer](./installer.md). - + 2. Boot the target machine and connect it to a network that makes it reachable from your setup computer. === "**Remote Machines**" @@ -191,8 +191,16 @@ If the machine does not have enough resources to run the NixOS evaluation or bui it is also possible to specify a build host instead. During an update, the cli will ssh into the build host and run `nixos-rebuild` from there. -```bash -clan config --machine my-machine clan.networking.buildHost root@host_or_ip + +```nix hl_lines="5" +buildClan { + # ... + machines = { + "jon" = { + clan.networking.buildHost = "root@"; + }; + }; +}; ``` ### Excluding a machine from `clan machine update` @@ -200,8 +208,15 @@ clan config --machine my-machine clan.networking.buildHost root@host_or_ip To exclude machines from being updated when running `clan machines update` without any machines specified, one can set the `clan.deployment.requireExplicitUpdate` option to true: -```bash -clan config --machine my-machine clan.deployment.requireExplicitUpdate true +```nix hl_lines="5" +buildClan { + # ... + machines = { + "jon" = { + clan.deployment.requireExplicitUpdate = true; + }; + }; +}; ``` This is useful for machines that are not always online or are not part of the regular update cycle. diff --git a/docs/site/getting-started/installer.md b/docs/site/getting-started/installer.md index b6a74be2..292efc15 100644 --- a/docs/site/getting-started/installer.md +++ b/docs/site/getting-started/installer.md @@ -39,28 +39,44 @@ Follow our step-by-step guide to create and transfer this image onto a bootable ```shellSession sudo umount /dev/sdb1 ``` +=== "**Linux OS**" + ### Step 2. Flash Custom Installer -### Step 2. Download the Installer + Using clan flash enables the inclusion of ssh public keys and disables ssh password authentication. + It also includes the language and keymap currently used into the installer image. -```shellSession -wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso -``` + ```bash + clan flash flash-installer --disk main /dev/sd + ``` -### Step 3. Flash the Installer to the USB Drive + !!! Danger "Specifying the wrong device can lead to unrecoverable data loss." -!!! Danger "Specifying the wrong device can lead to unrecoverable data loss." + The `clan flash` utility will erase the disk. Make sure to specify the correct device - The `dd` utility will erase the disk. Make sure to specify the correct device (`of=...`) - For example if the USB device is `sdb` use `of=/dev/sdb`. - +=== "**Other OS**" + ### Step 2. Download Generic Installer -Use the `dd` utility to write the NixOS installer image to your USB drive: + ```shellSession + wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso + ``` -```shellSession -sudo dd bs=4M conv=fsync oflag=direct status=progress if=./nixos-installer-x86_64-linux.iso of=/dev/sd -``` + ### Step 3. Flash the Installer to the USB Drive + + !!! Danger "Specifying the wrong device can lead to unrecoverable data loss." + + The `dd` utility will erase the disk. Make sure to specify the correct device (`of=...`) + + For example if the USB device is `sdb` use `of=/dev/sdb`. + + + + Use the `dd` utility to write the NixOS installer image to your USB drive: + + ```shellSession + sudo dd bs=4M conv=fsync oflag=direct status=progress if=./nixos-installer-x86_64-linux.iso of=/dev/sd + ``` ### Step 4. Boot and Connect to your network @@ -110,6 +126,7 @@ Now run the following command to connect to your Wifi: ```shellSession # Identify your network device. device list + # Replace 'wlan0' with your wireless device name # Find your Wifi SSID. station wlan0 scan diff --git a/docs/site/getting-started/secrets.md b/docs/site/getting-started/secrets.md index 9267b5b5..141502b6 100644 --- a/docs/site/getting-started/secrets.md +++ b/docs/site/getting-started/secrets.md @@ -4,8 +4,6 @@ Clan enables encryption of secrets (such as passwords & keys) ensuring security Clan utilizes the [sops](https://github.com/getsops/sops) format and integrates with [sops-nix](https://github.com/Mic92/sops-nix) on NixOS machines. -This documentation will guide you through managing secrets with the Clan CLI - ### Create Your Master Keypair @@ -40,8 +38,7 @@ Also add your age public key to the repository with 'clan secrets users add YOUR clan secrets users add ``` -!!! note - Choose the same username as on your Setup/Source Machine that you use to control the deployment with. +It's best to choose the same username as on your Setup/Admin Machine that you use to control the deployment with. Once run this will create the following files: @@ -61,8 +58,136 @@ If you followed the quickstart tutorial all necessary secrets are initialized at --- +## More on Secrets + +If you want to know more about how to save and share passwords in your clan read further! + +### Adding a Secret + +```shellSession +clan secrets set mysecret +Paste your secret: +``` + +### Retrieving a Stored Secret + +```bash +clan secrets get mysecret +``` + +### List all Secrets + +```bash +clan secrets list +``` + +### NixOS integration + +A NixOS machine will automatically import all secrets that are encrypted for the +current machine. At runtime it will use the host key to decrypt all secrets into +an in-memory, non-persistent filesystem using [sops-nix](https://github.com/Mic92/sops-nix). +In your nixos configuration you can get a path to secrets like this `config.sops.secrets..path`. For example: + +```nix +{ config, ...}: { + sops.secrets.my-password.neededForUsers = true; + + users.users.mic92 = { + isNormalUser = true; + passwordFile = config.sops.secrets.my-password.path; + }; +} +``` + +### Assigning Access + +By default, secrets are encrypted for your key. To specify which users and machines can access a secret: + +```bash +clan secrets set --machine --machine --user --user +``` +You can also just add machines/users to existing secrets: + +```bash + clan secrets machines add-secret +``` + +## Advanced + +In this section we go into more advanced secret management topics. + +### Groups + +Clan CLI makes it easy to manage access by allowing you to create groups. + +All users within a group inherit access to all secrets of the group. + +This feature eases the process of handling permissions for multiple users. + +Here's how to get started: + +1. **Creating Groups**: + + Assign users to a new group, e.g., `admins`: + + ```bash + clan secrets groups add admins + ``` + +2. **Listing Groups**: + + ```bash + clan secrets groups list + ``` + +3. **Assigning Secrets to Groups**: + + ```bash + clan secrets groups add-secret + ``` + +### Adding Machine Keys + +New machines in Clan come with age keys stored in `./sops/machines/`. To list these machines: + +```bash + clan secrets machines list +``` + +For existing machines, add their keys: + +```bash + clan secrets machines add +``` + +To fetch an age key from an SSH host key: + +```bash + ssh-keyscan | nix shell nixpkgs#ssh-to-age -c ssh-to-age +``` + +### Migration: Importing existing sops-based keys / sops-nix + +`clan secrets` stores each secret in a single file, whereas [sops](https://github.com/Mic92/sops-nix) commonly allows to put all secrets in a yaml or json document. + +If you already happened to use sops-nix, you can migrate by using the `clan secrets import-sops` command by importing these files: + +```bash +% clan secrets import-sops --prefix matchbox- --group admins --machine matchbox nixos/matchbox/secrets/secrets.yaml +``` + +This will create secrets for each secret found in `nixos/matchbox/secrets/secrets.yaml` in a `./sops` folder of your repository. +Each member of the group `admins` in this case will be able to decrypt the secrets with their respective key. + +Since our clan secret module will auto-import secrets that are encrypted for a particular nixos machine, +you can now remove `sops.secrets. = { };` unless you need to specify more options for the secret like owner/group of the secret file. + + + ## Indepth Explanation + + The secrets system conceptually knows two different entities: - **Machine**: consumes secrets @@ -117,9 +242,6 @@ Rel_R(secret, machine, "Decrypt", "", "machine privkey" ) @enduml ``` -### Groups - -It is possible to create semantic groups to make access control more convenient. #### User groups @@ -181,149 +303,11 @@ Rel(secret, c1, "Decrypt", "", "Both machine A or B can decrypt using their priv ---- -## 2. Adding Machine Keys - -New machines in Clan come with age keys stored in `./sops/machines/`. To list these machines: - -```bash -$ clan secrets machines list -``` - -For existing machines, add their keys: - -```bash -$ clan secrets machines add -``` - -### Advanced - -To fetch an age key from an SSH host key: - -```bash -$ ssh-keyscan | nix shell nixpkgs#ssh-to-age -c ssh-to-age -``` - -## 3. Assigning Access - -By default, secrets are encrypted for your key. To specify which users and machines can access a secret: - -```bash -$ clan secrets set --machine --machine --user --user -``` - -You can add machines/users to existing secrets without modifying the secret: - -```bash -$ clan secrets machines add-secret -``` - -## 4. Adding Secrets - -```bash -$ clan secrets set mysecret -Paste your secret: -``` - -!!! note - As you type your secret won't be displayed. Press Enter to save the secret. - -## 5. Retrieving Stored Secrets - -```bash -$ clan secrets get mysecret -``` - -### List all Secrets - -```bash -$ clan secrets list -``` - -## 6. Groups - -Clan CLI makes it easy to manage access by allowing you to create groups. - -All users within a group inherit access to all secrets of the group. - -This feature eases the process of handling permissions for multiple users. - -Here's how to get started: - -1. **Creating Groups**: - - Assign users to a new group, e.g., `admins`: - - ```bash - $ clan secrets groups add admins - ``` - -2. **Listing Groups**: - - ```bash - $ clan secrets groups list - ``` - -3. **Assigning Secrets to Groups**: - - ```bash - $ clan secrets groups add-secret - ``` - -## Further - -Secrets in the repository follow this structure: - -```{.console, .no-copy} -sops/ -├── secrets/ -│ └── / -│ ├── secret -│ └── users/ -│ └── / -``` - -The content of the secret is stored encrypted inside the `secret` file under `mysecret`. - -By default, secrets are encrypted with your key to ensure readability. - -### NixOS integration - -A NixOS machine will automatically import all secrets that are encrypted for the -current machine. At runtime it will use the host key to decrypt all secrets into -an in-memory, non-persistent filesystem using [sops-nix](https://github.com/Mic92/sops-nix). -In your nixos configuration you can get a path to secrets like this `config.sops.secrets..path`. For example: - -```nix -{ config, ...}: { - sops.secrets.my-password.neededForUsers = true; - - users.users.mic92 = { - isNormalUser = true; - passwordFile = config.sops.secrets.my-password.path; - }; -} -``` See the [readme](https://github.com/Mic92/sops-nix) of sops-nix for more examples. -### Migration: Importing existing sops-based keys / sops-nix - -`clan secrets` stores each secret in a single file, whereas [sops](https://github.com/Mic92/sops-nix) commonly allows to put all secrets in a yaml or json document. - -If you already happened to use sops-nix, you can migrate by using the `clan secrets import-sops` command by importing these files: - -```bash -% clan secrets import-sops --prefix matchbox- --group admins --machine matchbox nixos/matchbox/secrets/secrets.yaml -``` - -This will create secrets for each secret found in `nixos/matchbox/secrets/secrets.yaml` in a `./sops` folder of your repository. -Each member of the group `admins` in this case will be able to decrypt the secrets with their respective key. - -Since our clan secret module will auto-import secrets that are encrypted for a particular nixos machine, -you can now remove `sops.secrets. = { };` unless you need to specify more options for the secret like owner/group of the secret file. ---