From 52a18fd1a48293a39aabb348db4240747d873885 Mon Sep 17 00:00:00 2001 From: Qubasa Date: Sun, 7 Apr 2024 21:07:02 +0200 Subject: [PATCH] Improve documentation --- docs/admins/install-iso.md | 125 +++++++++++++++++++++++++++++ docs/admins/machines.md | 85 -------------------- docs/admins/quickstart.md | 33 +++++++- nixosModules/installer/default.nix | 14 +++- 4 files changed, 169 insertions(+), 88 deletions(-) create mode 100644 docs/admins/install-iso.md diff --git a/docs/admins/install-iso.md b/docs/admins/install-iso.md new file mode 100644 index 000000000..e969efa09 --- /dev/null +++ b/docs/admins/install-iso.md @@ -0,0 +1,125 @@ +# Clan Hardware Installation + +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: + +### Build the Installer Image + +```bash +nix build git+https://git.clan.lol/clan/clan-core.git#install-iso +``` + +> Make sure you do this inside + +### Prepare the USB Flash Drive + +1. Insert your USB flash drive into your computer. + +2. Identify your flash drive with `lsblk`. + ```shellSession + $ lsblk + NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS + sdb 8:0 1 117,2G 0 disk + └─sdb1 8:1 1 117,2G 0 part /run/media/qubasa/INTENSO + nvme0n1 259:0 0 1,8T 0 disk + ├─nvme0n1p1 259:1 0 512M 0 part /boot + └─nvme0n1p2 259:2 0 1,8T 0 part + └─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0 0 1,8T 0 crypt /nix/store / + ``` + + In this case it's `sdb` + +3. Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.): + + ```bash + sudo umount /dev/sdb1 + ``` + +### Write the Image to the USB Drive + +Use the `dd` utility to write the NixOS installer image to your USB drive: + + ```bash + sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sd + ``` + + 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. + +1. For this secure boot needs to be disabled. Go into your UEFI / Bios settings by pressing one of the keys outlined below while booting: + + - **Dell**: F2/Del (BIOS Setup) + - **HP**: Esc (Startup Menu) + - **Lenovo**: F2/Fn+F2/Novo Button (IdeaPad Boot Menu/BIOS Setup) + - **Acer**: F2/Del (BIOS Setup) + - **Asus**: F2/Del (BIOS Setup) + - **Toshiba**: Esc then F12 (Alternate Method) + - **Sony**: F11 + - **Samsung**: F2 (BIOS Setup) + - **MSI**: 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. + +2. Inside the UEFI/Bios Menu go to `Security->Secure Boot` and disable secure boot + +3. Save your settings. Put in the USB stick and reboot. + +4. Press one of keys outlined below to go into the Boot Menu + - **Dell**: F12 (Boot Menu) + - **HP**: F9 (Boot Menu) + - **Lenovo**: F12 (ThinkPad Boot Menu) + - **Acer**: F12 (Boot Menu) + - **Asus**: F8/Esc (Boot Menu) + - **Toshiba**: F12/F2 (Boot Menu) + - **Sony**: F11 + - **Samsung**: F2/F12/Esc (Boot Menu) + - **MSI**: F11 + - **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. + + + + +5. Select `NixOS` to boot into the clan installer + + +6. 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. + +7. Set your keyboard language. Important for writing passwords correctly. + ```bash + loadkeys de + ``` + +8. If you only have Wifi available, execute: + 1. Bring up the `iwd` shell + ```bash + iwctl + ``` + 2. List available networks. Double press tab after station for autocompleting your wlan device. In this case `wlan0` + ```shellSession + [iwd] station wlan0 get-networks + ``` + 3. Connect to a Wifi network. Replace `SSID` with the wlan network name. + ```shellSession + [iwd] station wlan0 connect SSID + ``` +9. Now that you have internet re-execute the init script by pressing `Ctrl+D` or by executing: + ```bash + bash + ``` + +10. Connect to the machine over ssh + ```bash + ssh-copy-id -o PreferredAuthentications=password root@ + ``` + Use the root password displayed on your screen as login. + diff --git a/docs/admins/machines.md b/docs/admins/machines.md index ecd7731d5..ba2dc6122 100644 --- a/docs/admins/machines.md +++ b/docs/admins/machines.md @@ -1,94 +1,11 @@ # Managing NixOS Machines with Clan -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 - Clan CLI, in conjunction with [nixos-anywhere](https://github.com/nix-community/nixos-anywhere), provides a seamless method for installing NixOS on various machines. This process involves preparing a suitable hardware and disk partitioning configuration and ensuring the target machine is accessible via SSH. ### Prerequisites - [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: - -### Build the Installer Image - -```bash -nix build git+https://git.clan.lol/clan/clan-core.git#install-iso -``` - -### Prepare the USB Flash Drive - -1. Insert your USB flash drive into your computer. - -2. Identify your flash drive with `lsblk`. - ```shellSession - $ lsblk - NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS - sdb 8:0 1 117,2G 0 disk - └─sdb1 8:1 1 117,2G 0 part /run/media/qubasa/INTENSO - nvme0n1 259:0 0 1,8T 0 disk - ├─nvme0n1p1 259:1 0 512M 0 part /boot - └─nvme0n1p2 259:2 0 1,8T 0 part - └─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0 0 1,8T 0 crypt /nix/store / - ``` - - In this case it's `sdb` - -3. Ensure all partitions on the drive are unmounted. Replace `sdX` in the command below with your device identifier (like `sdb`, etc.): - - ```bash - sudo umount /dev/sdb1 - ``` - -### Write the Image to the USB Drive - -Use the `dd` utility to write the NixOS installer image to your USB drive: - - ```bash - sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sd - ``` - - 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 @@ -151,8 +68,6 @@ This is useful for machines that are not always online or are not part of the re --- # 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/docs/admins/quickstart.md b/docs/admins/quickstart.md index c66a0ba1c..3136a3bcf 100644 --- a/docs/admins/quickstart.md +++ b/docs/admins/quickstart.md @@ -39,7 +39,38 @@ Look for `.clan-flake`, `flake.lock`, and `flake.nix` among your files to confir ### **Understanding `.clan-flake`** The `.clan-flake` file, while optional, is instrumental in helping the Clan CLI identify your project's root directory, easing project management. +### Edit Flake.nix +Open the `flake.nix` file and set a unique `clanName` if you want you can also set an optional `clanIcon` or even a per `machineIcon`. These will be used by our future clan GUI. + +### Remote into the target machine +**Right now clan assumes that you already have NixOS running on the target machine.** +If that is not the case you can use our [installer image](./install-iso.md) that automatically generates an endpoint reachable over TOR with a random ssh password. + +On the remote execute: +1. Generate a hardware-config.nix + ```bash + nixos-generate-config --root /etc/nixos --no-filesystems + ``` +2. Copy it over and put it into you `machines/jon/hardware-config.nix` folder + ```bash + scp -r root@:/etc/nixos/hardware-config.nix ./machines/jon + ``` +3. Find the remote disk id by executing on the remote: + ```bash + lsblk --output NAME,PTUUID,FSTYPE,SIZE,MOUNTPOINT + ``` +4. Edit the following fields inside the `flake.nix` + - `clan.networking.targetHost = pkgs.lib.mkDefault "root@";` + - `clan.diskLayouts.singleDiskExt4 = { + device = "/dev/disk/by-id/__CHANGE_ME__"; + };` + +5. Generate secrets used by clan modules by executing + ```bash + clan facts generate + ``` + ### **Next Steps** -Ready to expand? Explore how to add new machines to your project with the helpful documentation [here](./machines.md). +Ready to expand? Explore how to install a new machine with the helpful documentation [here](./machines.md). --- diff --git a/nixosModules/installer/default.nix b/nixosModules/installer/default.nix index 68ff28f0b..6e161dbbc 100644 --- a/nixosModules/installer/default.nix +++ b/nixosModules/installer/default.nix @@ -5,6 +5,12 @@ ... }: { + ############################################ + # # + # For install image debugging execute: # + # $ qemu-kvm result/stick.raw -snapshot # + # # + ############################################ systemd.tmpfiles.rules = [ "d /var/shared 0777 root root - -" ]; imports = [ (modulesPath + "/profiles/installation-device.nix") @@ -59,12 +65,15 @@ fi ''; + # boot.loader.systemd-boot.enable = true; # Grub doesn't find devices for both BIOS and UEFI? + # Mic92: Please write where this exactly breaks if you want to comment out grub again. # NOTE: We need grub here. Otherwise, the system won't boot in some machines. # example: Lenovo E495 didn't boot without grub. boot.loader.grub.efiInstallAsRemovable = true; boot.loader.grub.efiSupport = true; + disko.devices = { disk = { stick = { @@ -75,8 +84,9 @@ type = "gpt"; partitions = { boot = { - size = "1M"; - type = "EF02"; # for grub MBR + priority = 1; + size = "1M"; + type = "EF02"; # for grub MBR }; ESP = { size = "100M";