Improve documentation
This commit is contained in:
parent
4faba7c8e1
commit
1e0d73e8a9
125
docs/admins/install-iso.md
Normal file
125
docs/admins/install-iso.md
Normal 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.
|
||||
|
||||
|
|
@ -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<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
|
||||
|
||||
|
|
@ -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
|
||||
|
|
@ -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@<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**
|
||||
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).
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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";
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user