yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improve documentation

Browse Source
This commit is contained in:
Qubasa
2024-04-07 21:07:02 +02:00
parent f505e0f5db
commit 52a18fd1a4
4 changed files with 169 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
docs/admins/install-iso.md Normal file
View File

@@ -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<X>
```
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@<ip>
```
Use the root password displayed on your screen as login.

85
docs/admins/machines.md
View File

@@ -1,94 +1,11 @@
# Managing NixOS Machines with Clan # 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. 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. This process involves preparing a suitable hardware and disk partitioning configuration and ensuring the target machine is accessible via SSH.
### Prerequisites ### Prerequisites
- [x] 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.
- [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<X>
```
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 ### 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: # TODO:
* clan facts generate
* clan machine check / build (CI is missing)
* TODO: How to join others people zerotier * TODO: How to join others people zerotier
* `services.zerotier.joinNetworks = [ "network-id" ]` * `services.zerotier.joinNetworks = [ "network-id" ]`
* Controller needs to approve over webinterface or cli * Controller needs to approve over webinterface or cli

33
docs/admins/quickstart.md
View File

@@ -39,7 +39,38 @@ Look for `.clan-flake`, `flake.lock`, and `flake.nix` among your files to confir
### **Understanding `.clan-flake`** ### **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. 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@<jon-ip>:/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@<IP_ADDRESS>";`
- `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** ### **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).
--- ---

14
nixosModules/installer/default.nix
View File

@@ -5,6 +5,12 @@
... ...
}: }:
{ {
############################################
# #
# For install image debugging execute: #
# $ qemu-kvm result/stick.raw -snapshot #
# #
############################################
systemd.tmpfiles.rules = [ "d /var/shared 0777 root root - -" ]; systemd.tmpfiles.rules = [ "d /var/shared 0777 root root - -" ];
imports = [ imports = [
(modulesPath + "/profiles/installation-device.nix") (modulesPath + "/profiles/installation-device.nix")
@@ -59,12 +65,15 @@
fi fi
''; '';
# boot.loader.systemd-boot.enable = true;
# Grub doesn't find devices for both BIOS and UEFI? # 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. # NOTE: We need grub here. Otherwise, the system won't boot in some machines.
# example: Lenovo E495 didn't boot without grub. # example: Lenovo E495 didn't boot without grub.
boot.loader.grub.efiInstallAsRemovable = true; boot.loader.grub.efiInstallAsRemovable = true;
boot.loader.grub.efiSupport = true; boot.loader.grub.efiSupport = true;
disko.devices = { disko.devices = {
disk = { disk = {
stick = { stick = {
@@ -75,8 +84,9 @@
type = "gpt"; type = "gpt";
partitions = { partitions = {
boot = { boot = {
size = "1M"; priority = 1;
type = "EF02"; # for grub MBR size = "1M";
type = "EF02"; # for grub MBR
}; };
ESP = { ESP = {
size = "100M"; size = "100M";