Skip to content

Configuration - How to configure clan with your own machines

Managing machine configurations can be done in the following ways:

  • writing nix expressions in a flake.nix file,
  • placing autoincluded files into your machine directory,
  • configuring everything in a simple UI (upcoming).

Clan currently offers the following methods to configure machines:

Recommended for nix people

  • flake.nix (i.e. via buildClan)

    • machine argument
    • inventory argument

  • machines/machine_name/configuration.nix (autoincluded if it exists)

Used by CLI & UI
  • inventory.json
  • machines/machine_name/hardware-configuration.nix (autoincluded if it exists)

Deprecated

machines/machine_name/settings.json

Global configuration

In the flake.nix file:

  • set a unique name.
flake.nix
buildClan {
    # Set a unique name
    meta.name = "Lobsters";
    # Should usually point to the directory of flake.nix
    directory = ./.;

    machines = {
        jon = {
            # ...
        };
        # ...
    }
}

See Clan with flake-parts for help migrating to flake-parts.

flake.nix
clan = {
    # Set a unique name
    meta.name = "Lobsters";

    machines = {
        jon = {
            # ...
        };
        # ...
    }
};

Machine configuration

Adding or configuring a new machine requires two simple steps:

Step 1. Identify Target Disk-ID

  1. Find the remote disk id by executing:

    setup computer
    ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT

    Note

    Replace <IP> with the IP address of the machine if you don't have the avahi service running which resolves mDNS local domains.

    Which should show something like:

    NAME        ID-LINK                                         FSTYPE   SIZE MOUNTPOINT
sda         usb-ST_16GB_AA6271026J1000000509-0:0                    14.9G
├─sda1      usb-ST_16GB_AA6271026J1000000509-0:0-part1                 1M
├─sda2      usb-ST_16GB_AA6271026J1000000509-0:0-part2      vfat     100M /boot
└─sda3      usb-ST_16GB_AA6271026J1000000509-0:0-part3      ext4     2.9G /
nvme0n1     nvme-eui.e8238fa6bf530001001b448b4aec2929              476.9G
├─nvme0n1p1 nvme-eui.e8238fa6bf530001001b448b4aec2929-part1 vfat     512M
├─nvme0n1p2 nvme-eui.e8238fa6bf530001001b448b4aec2929-part2 ext4   459.6G
└─nvme0n1p3 nvme-eui.e8238fa6bf530001001b448b4aec2929-part3 swap    16.8G

  2. Edit the following fields inside the ./machines/jon/configuration.nix and/or ./machines/sara/configuration.nix

./machines//configuration.nix
{
   imports = [
     ./hardware-configuration.nix
     # contains your disk format and partitioning configuration.
     ../../modules/disko.nix
     # this file is shared among all machines
     ../../modules/shared.nix
     # enables GNOME desktop (optional)
     ../../modules/gnome.nix
   ];

   # Put your username here for login
   users.users.user.username = "__YOUR_USERNAME__";

   # Set this for clan commands use ssh i.e. `clan machines update`
   # If you change the hostname, you need to update this line to root@<new-hostname>
   # This only works however if you have avahi running on your admin machine else use IP
   clan.core.networking.targetHost = "root@__IP__";

   # You can get your disk id by running the following command on the installer:
   # Replace <IP> with the IP of the installer printed on the screen or by running the `ip addr` command.
   # ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
   disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";

   # IMPORTANT! Add your SSH key here
   # e.g. > cat ~/.ssh/id_ed25519.pub
   users.users.root.openssh.authorizedKeys.keys = [ "__YOUR_SSH_KEY__" ];

   # ...
}

Replace __YOUR_USERNAME__ with the ip of your machine, if you use avahi you can also use your hostname

Replace __IP__ with the ip of your machine, if you use avahi you can also use your hostname

Replace __CHANGE_ME__ with the appropriate identifier, such as nvme-eui.e8238fa6bf530001001b448b4aec2929

Replace __YOUR_SSH_KEY__ with your personal key, like ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILoMI0NC5eT9pHlQExrvR5ASV3iW9+BXwhfchq0smXUJ jon@jon-desktop

These steps will allow you to update your machine later.

Step 2: Detect Drivers

Generate the hardware-configuration.nix file for your machine by executing the following command:

clan machines update-hardware-config [MACHINE_NAME] [HOSTNAME]

replace [MACHINE_NAME] with the name of the machine i.e. jon and [HOSTNAME] with the ip_address or hostname of the machine within the network. i.e. <IP>

Example

clan machines update-hardware-config jon

This command connects to the ip configured in the previous step, runs nixos-generate-config to detect hardware configurations (excluding filesystems), and writes them to machines/jon/hardware-configuration.nix.

Step 3: Custom Disk Formatting

In ./modules/disko.nix, a simple ext4 disk partitioning scheme is defined for the Disko module. For more complex disk partitioning setups, refer to the Disko templates or Disko examples.

Step 4: Custom Configuration

Modify ./machines/jon/configuration.nix to personalize the system settings according to your requirements. If you wish to name your machine to something else, do the following steps:

mv ./machines/jon/configuration.nix ./machines/newname/configuration.nix

Than rename jon to your preferred name in machines in flake.nix as well as the import line:

- imports = [ ./machines/jon/configuration.nix ];
+ imports = [ ./machines/__NEW_NAME__/configuration.nix ];

Replace __NEW_NAME__ with the name of the machine

Note that our clan lives inside a git repository. Only files that have been added with git add are recognized by nix. So for every file that you add or rename you also need to run:

git add ./path/to/my/file

For renaming jon to your own machine name, you can use the following command:

git mv ./machines/jon ./machines/newname

If you only want to setup a single machine at this point, you can delete sara from flake.nix as well as from the machines directory:

git rm ./machines/sara

Step 5: Check Configuration

Validate your configuration by running:

nix flake check

This command helps ensure that your system configuration is correct and free from errors.

Tip

You can integrate this step into your Continuous Integration workflow to ensure that only valid Nix configurations are merged into your codebase.

Whats next?