Add clan flash documentation.

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
+```bash
-    ssh root@flash-installer.local nixos-generate-config --no-filesystems --show-hardware-config > machines/jon/hardware-configuration.nix
+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.
 
 
 ---

docs/site/getting-started/deploy.md

@@ -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@<host_or_ip>";
+        };
+    };
+};
 ```
 
 ### 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
+```nix hl_lines="5"
-clan config --machine my-machine clan.deployment.requireExplicitUpdate true
+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.

docs/site/getting-started/installer.md

@@ -39,16 +39,32 @@ 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
+    ```bash
-wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso
+    clan flash flash-installer --disk main /dev/sd<X>
-```
+    ```
 
-### 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
+
+
+
+=== "**Other OS**"
+    ### Step 2. Download Generic Installer
+
+    ```shellSession
+    wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso
+    ```
+
+    ### 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=...`)
 
@@ -56,11 +72,11 @@ wget https://github.com/nix-community/nixos-images/releases/download/nixos-unsta
 
 
 
-Use the `dd` utility to write the NixOS installer image to your USB drive:
+    Use the `dd` utility to write the NixOS installer image to your USB drive:
 
-```shellSession
+    ```shellSession
-sudo dd bs=4M conv=fsync oflag=direct status=progress if=./nixos-installer-x86_64-linux.iso of=/dev/sd<X>
+    sudo dd bs=4M conv=fsync oflag=direct status=progress if=./nixos-installer-x86_64-linux.iso of=/dev/sd<X>
-```
+    ```
 
 ### 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

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 <your_username> <your_public_key>
 ```
 
-!!! note
+It's best to choose the same username as on your Setup/Admin Machine that you use to control the deployment with.
-    Choose the same username as on your Setup/Source 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.<name>.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 <machine1> --machine <machine2> --user <user1> --user <user2> <secret_name>
+```
+You can also just add machines/users to existing secrets:
+
+```bash
+ clan secrets machines add-secret <machine_name> <secret_name>
+```
+
+## 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 <username>
+   ```
+
+2. **Listing Groups**:
+
+   ```bash
+   clan secrets groups list
+   ```
+
+3. **Assigning Secrets to Groups**:
+
+   ```bash
+   clan secrets groups add-secret <group_name> <secret_name>
+   ```
+
+### Adding Machine Keys
+
+New machines in Clan come with age keys stored in `./sops/machines/<machine_name>`. To list these machines:
+
+```bash
+ clan secrets machines list
+```
+
+For existing machines, add their keys:
+
+```bash
+ clan secrets machines add <machine_name> <age_key>
+```
+
+To fetch an age key from an SSH host key:
+
+```bash
+ ssh-keyscan <domain_name> | 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.<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
 
 <!-- TODO: See also [Groups Reference](#groups-reference) -->
 
----
 
-## 2. Adding Machine Keys
-
-New machines in Clan come with age keys stored in `./sops/machines/<machine_name>`. To list these machines:
-
-```bash
-$ clan secrets machines list
-```
-
-For existing machines, add their keys:
-
-```bash
-$ clan secrets machines add <machine_name> <age_key>
-```
-
-### Advanced
-
-To fetch an age key from an SSH host key:
-
-```bash
-$ ssh-keyscan <domain_name> | 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 <machine1> --machine <machine2> --user <user1> --user <user2> <secret_name>
-```
-
-You can add machines/users to existing secrets without modifying the secret:
-
-```bash
-$ clan secrets machines add-secret <machine_name> <secret_name>
-```
-
-## 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 <username>
-   ```
-
-2. **Listing Groups**:
-
-   ```bash
-   $ clan secrets groups list
-   ```
-
-3. **Assigning Secrets to Groups**:
-
-   ```bash
-   $ clan secrets groups add-secret <group_name> <secret_name>
-   ```
-
-## Further
-
-Secrets in the repository follow this structure:
-
-```{.console, .no-copy}
-sops/
-├── secrets/
-│   └── <secret_name>/
-│       ├── secret
-│       └── users/
-│           └── <your_username>/
-```
-
-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.<name>.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.<secrets> = { };` unless you need to specify more options for the secret like owner/group of the secret file.
 
 ---