machine.md: clean up guide
This commit is contained in:
parent
49d83fd659
commit
55f3878e67
@ -1,16 +1,8 @@
|
|||||||
# Managing NixOS Machines with Clan
|
# 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
|
## Installing a New Machine
|
||||||
|
|
||||||
@ -19,47 +11,75 @@ This process involves preparing a suitable hardware and disk partitioning config
|
|||||||
|
|
||||||
### Prerequisites
|
### 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
|
## Creating a Bootable USB Drive on Linux
|
||||||
|
|
||||||
To create a bootable USB flash drive with the NixOS installer:
|
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
|
### 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:
|
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
|
## 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:
|
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
|
### Updating Machine Configurations
|
||||||
|
|
||||||
Execute the following command to update the specified machine:
|
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:
|
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
|
### 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.
|
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.
|
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`
|
### 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,
|
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:
|
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.
|
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
|
@ -7,6 +7,10 @@ let
|
|||||||
self.nixosModules.installer
|
self.nixosModules.installer
|
||||||
self.inputs.nixos-generators.nixosModules.all-formats
|
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;
|
system.stateVersion = config.system.nixos.version;
|
||||||
nixpkgs.pkgs = self.inputs.nixpkgs.legacyPackages.x86_64-linux;
|
nixpkgs.pkgs = self.inputs.nixpkgs.legacyPackages.x86_64-linux;
|
||||||
|
Loading…
Reference in New Issue
Block a user