From 8b4f092f688ed439a6b4a6ee0f1bd0f512615294 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sun, 7 Apr 2024 14:32:23 +0200 Subject: [PATCH] machine.md: clean up guide --- docs/admins/machines.md | 120 ++++++++++++++++++++------------ pkgs/installer/flake-module.nix | 4 ++ 2 files changed, 78 insertions(+), 46 deletions(-) diff --git a/docs/admins/machines.md b/docs/admins/machines.md index 08cbd7f07..96a115051 100644 --- a/docs/admins/machines.md +++ b/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: - - - -# 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 +Integrating a new machine into your cLan environment is a very easy yet flexible process, allowing for the centralized management of multiple NixOS configurations. +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. -- For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below. +- [x] A running Linux system with SSH on the target machine is required. This is typically pre-configured for many server providers. +- [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 - $ nix build git+https://git.clan.lol/clan/clan-core.git#install-iso - ``` +```bash +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. - - 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.): +- Insert your USB flash drive into your computer. +- 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.): - ```shellSession - sudo umount /dev/sdX* - ``` +```bash +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 - sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sdX - ``` +```bash +sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sdX +``` -4. **Boot and Connect**: - - 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. +In case your USB device is `sdb` use `of=/dev/sdb` + +### 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 `` with the machine's hostname or IP address: -```shellSession -$ clan machines install my-machine +```bash +clan machines install my-machine ``` ## 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 -$ clan config --machine my-machine clan.networking.targetHost root@host_or_ip +```bash +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. -Ensure that the root login is secured and only used when necessary._ +> 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. ### Updating Machine Configurations Execute the following command to update the specified machine: -```shellSession -$ clan machines update my-machine +```bash +clan machines update my-machine ``` You can also update all configured machines simultaneously by omitting the machine name: -```shellSession -$ clan machines update +```bash +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 -$ clan config --machine my-machine clan.networking.buildHost root@host_or_ip +```bash +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: - -```shellSession -$ clan config --machine my-machine clan.deployment.requireExplicitUpdate true +```bash +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 \ No newline at end of file diff --git a/pkgs/installer/flake-module.nix b/pkgs/installer/flake-module.nix index 6de665776..51589a633 100644 --- a/pkgs/installer/flake-module.nix +++ b/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;