Managing NixOS Machines
Add Your First Machine
To start managing a new machine, use the following commands to create and then list your machines:
$ clan machines create my-machine
$ clan machines list
Configure Your Machine
In the example below, we demonstrate how to add a new user named
my-user and set a password. This user will be configured to log in to the machine
Creating a New User
# Add a new user
$ clan config --machine my-machine users.users.my-user.isNormalUser true
# Set a password for the user
$ clan config --machine my-machine users.users.my-user.hashedPassword $(mkpasswd)
$(mkpasswd) command generates a hashed password. Ensure you have the
mkpasswd utility installed or use an alternative method to generate a secure hashed password.
Test Your Machine Configuration Inside a VM
Before deploying your configuration to a live environment, you can run a virtual machine (VM) to test the settings:
$ clan vms run my-machine
This command run a VM based on the configuration of
my-machine, allowing you to verify changes in a controlled environment.
Installing a New Machine
Clan CLI, in conjunction with 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.
- 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.
Creating a Bootable USB Drive on Linux
To create a bootable USB flash drive with the NixOS installer:
Build the Installer Image:
$ nix build git+https://git.clan.lol/clan/clan-core.git#install-iso
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
sdXin the command below with your device identifier (like
sudo umount /dev/sdX*
Write the Image to the USB Drive:
ddutility to write the NixOS installer image to your USB drive:
sudo dd bs=4M conv=fsync oflag=direct status=progress if=./result/stick.raw of=/dev/sdX
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.
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:
$ clan machines install my-machine <target_host>
Update Your Machines
Clan CLI enables you to remotely update your machines over SSH. This requires setting up a target address for each target machine.
Setting the Target Host
host_or_ip with the actual hostname or IP address of your target machine:
$ 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.
Updating Machine Configurations
Execute the following command to update the specified machine:
$ clan machines update my-machine
You can also update all configured machines simultaneously by omitting the machine name:
$ clan machines update
Setting a Build Host
If the machine does not have enough resources to run the NixOS evaluation or build itself,
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.
$ clan config --machine my-machine clan.networking.buildHost root@host_or_ip
Excluding a machine from
clan machine update
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:
$ 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.