machine.md: clean up guide

docs/admins/machines.md

@@ -1,16 +1,8 @@
 # Managing NixOS Machines with Clan
 
-Begin your journey in machine management by introducing a new machine into your Clan environment. Follow these streamlined steps to get started:
+Integrating a new machine into your cLan environment is a very easy yet flexible process, allowing for the centralized management of multiple NixOS configurations.
-
-
-
-# TODO:
-* clan facts generate
-* clan machine check / build (CI is missing)
-* TODO: How to join others people zerotier
-  * `services.zerotier.joinNetworks = [ "network-id" ]`
-* Controler needs to approve over webinterface or cli
 
+The Guide below showcases how to introduce a new machine into an existing cLan setup.
 
 ## Installing a New Machine
 
@@ -19,47 +11,75 @@ This process involves preparing a suitable hardware and disk partitioning config
 
 ### Prerequisites
 
-- A running Linux system with SSH on the target machine is required. This is typically pre-configured for many server providers.
+- [x] A running Linux system with SSH on the target machine is required. This is typically pre-configured for many server providers.
-- For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below.
+- [x] For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below.
 
 ## Creating a Bootable USB Drive on Linux
 
 To create a bootable USB flash drive with the NixOS installer:
 
-1. **Build the Installer Image**:
+### Build the Installer Image
 
-   ```shellSession
+```bash
-   $ nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
+nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
-   ```
+```
 
-2. **Prepare the USB Flash Drive**:
+### Prepare the USB Flash Drive
 
-   - Insert your USB flash drive into your computer.
+- Insert your USB flash drive into your computer.
-   - Identify your flash drive with `lsblk`. Look for the device with a matching size.
+- Identify your flash drive with `lsblk`. Look for the device with a matching size.
-   - Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.):
+- Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.):
 
-     ```shellSession
+```bash
-     sudo umount /dev/sdX*
+sudo umount /dev/sdX*
-     ```
+```
 
-3. **Write the Image to the USB Drive**:
+### Write the Image to the USB Drive
 
-   - 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
+```bash
-     sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sdX
+sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sdX
-     ```
+```
 
-4. **Boot and Connect**:
+In case your USB device is `sdb` use `of=/dev/sdb`
-   - After writing the installer to the USB drive, use it to boot the target machine.
+
-   - The installer will display an IP address and a root password, which you can use to connect via SSH.
+### Boot and Connect
+
+After writing the installer to the USB drive, use it to boot the target machine.
+
+> i.e. Plug it into the target machine and select the USB drive as a temporary boot device.
+
+For most hardware you can find the Key-combination below:
+
+- **Dell**: F12 (Boot Menu), F2/Del (BIOS Setup)
+- **HP**: F9 (Boot Menu), Esc (Startup Menu)
+- **Lenovo**: F12 (ThinkPad Boot Menu), F2/Fn+F2/Novo Button (IdeaPad Boot Menu/BIOS Setup)
+- **Acer**: F12 (Boot Menu), F2/Del (BIOS Setup)
+- **Asus**: F8/Esc (Boot Menu), F2/Del (BIOS Setup)
+- **Toshiba**: F12/F2 (Boot Menu), Esc then F12 (Alternate Method)
+- **Sony**: F11/Assist Button (Boot Menu/Recovery Options)
+- **Samsung**: F2/F12/Esc (Boot Menu), F2 (BIOS Setup)
+- **MSI**: F11 (Boot Menu), Del (BIOS Setup)
+- **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**
+
+The installer will display an IP address and a root password, which you can use to connect via SSH.
+
+Alternatively you can also use the displayed QR code.
 
 ### Finishing the installation
 
 With the target machine running Linux and accessible via SSH, execute the following command to install NixOS on the target machine, replacing `<target_host>` with the machine's hostname or IP address:
 
-```shellSession
+```bash
-$ clan machines install my-machine <target_host>
+clan machines install my-machine <target_host>
 ```
 
 ## Update Your Machines
@@ -70,25 +90,25 @@ Clan CLI enables you to remotely update your machines over SSH. This requires se
 
 Replace `host_or_ip` with the actual hostname or IP address of your target machine:
 
-```shellSession
+```bash
-$ clan config --machine my-machine clan.networking.targetHost root@host_or_ip
+clan config --machine my-machine clan.networking.targetHost root@host_or_ip
 ```
 
-_Note: The use of `root@` in the target address implies SSH access as the root user.
+> Note: The use of `root@` in the target address implies SSH access as the `root` user.
-Ensure that the root login is secured and only used when necessary._
+> Ensure that the root login is secured and only used when necessary.
 
 ### Updating Machine Configurations
 
 Execute the following command to update the specified machine:
 
-```shellSession
+```bash
-$ clan machines update my-machine
+clan machines update my-machine
 ```
 
 You can also update all configured machines simultaneously by omitting the machine name:
 
-```shellSession
+```bash
-$ clan machines update
+clan machines update
 ```
 
 ### Setting a Build Host
@@ -97,8 +117,8 @@ 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.
 
-```shellSession
+```bash
-$ clan config --machine my-machine clan.networking.buildHost root@host_or_ip
+clan config --machine my-machine clan.networking.buildHost root@host_or_ip
 ```
 
 ### Excluding a machine from `clan machine update`
@@ -106,9 +126,17 @@ $ clan config --machine my-machine clan.networking.buildHost root@host_or_ip
 To exclude machines from beeing updated when running `clan machines update` without any machines specified,
 one can set the `clan.deployment.requireExplicitUpdate` option to true:
 
-
+```bash
-```shellSession
+clan config --machine my-machine clan.deployment.requireExplicitUpdate true
-$ clan config --machine my-machine clan.deployment.requireExplicitUpdate true
 ```
 
 This is useful for machines that are not always online or are not part of the regular update cycle.
+
+---
+
+# TODO:
+* clan facts generate
+* clan machine check / build (CI is missing)
+* TODO: How to join others people zerotier
+  * `services.zerotier.joinNetworks = [ "network-id" ]`
+* Controller needs to approve over webinterface or cli

pkgs/installer/flake-module.nix

@@ -7,6 +7,10 @@ let
         self.nixosModules.installer
         self.inputs.nixos-generators.nixosModules.all-formats
       ];
+      # Provide convenience for connecting to wifi      
+      networking.networkmanager.enable = true;
+      networking.wireless.enable = false;
+      users.users.root.extraGroups = [ "networkmanager" ];
 
       system.stateVersion = config.system.nixos.version;
       nixpkgs.pkgs = self.inputs.nixpkgs.legacyPackages.x86_64-linux;