### Quick Start: User Password Generation and Usage (Nix)

Source: https://docs.clan.lol/25.11/guides/vars/vars-overview

A complete example demonstrating the setup of a user password generator using Clan's vars system. It defines the generator, prompts for the password, specifies the output file, and then uses the generated hash in the user configuration. This snippet is intended to be saved in a `generator.nix` file.

```nix
# generator.nix
{
  config,
  pkgs,
  ... 
}: 
{
  clan.core.vars.generators.user-password = {
    prompts.password = {
      description = "User password";
      type = "hidden";
    };
    files.hash = { secret = false; };
    script = ''
      mkpasswd -m sha-512 < $prompts/password > $out/hash
    '';
    runtimeInputs = [ pkgs.mkpasswd ];
  };

  users.users.myuser = {
    hashedPasswordFile =
      config.clan.core.vars.generators.user-password.files.hash.path;
  };
}
```

--------------------------------

### Default Package List Configuration

Source: https://docs.clan.lol/25.11/services/official/packages

This example shows the default configuration for the 'packages' option, which is a list of strings representing package names. It illustrates how to declare packages to be installed on a machine.

```nix
[
  "cowsay"
]
```

--------------------------------

### Prepare Secret Key and Partition Disks for NixOS Installation

Source: https://docs.clan.lol/25.11/guides/disk-encryption

These commands are used to prepare the target machine for NixOS installation. They involve accessing the installer via SSH, creating a secret key file, discarding existing disk partition data, and initiating the installation process with specific phases.

```bash
ssh root@nixos-installer.local

nano /tmp/secret.key

blkdiscard /dev/disk/by-id/<installdisk>

clan machines install gchq-local --target-host root@nixos-installer --phases kexec,disko

```

--------------------------------

### Syncthing Example Configuration

Source: https://docs.clan.lol/25.11/services/official/syncthing

Provides an example of how to configure Syncthing, specifying roles, peer settings, and folders to synchronize. It highlights the use of absolute paths for folder synchronization.

```nix
{
  instances.syncthing = {
    roles.peer.tags.all = { };
    roles.peer.settings.folders = {
      documents = {
        path = "/home/youruser/syncthing/documents";
      };
    };
  };
}

```

--------------------------------

### Configure BorgBackup Client and Server Roles in Clan Inventory

Source: https://docs.clan.lol/25.11/guides/backups/minimal-example

This configuration defines BorgBackup settings within the Clan inventory. It specifies machines acting as clients ('bob', 'jon') that will back up their 'clan-core' input to a server machine ('alice') with a specified address. The 'startAt' attribute for 'bob' indicates a scheduled backup time.

```nix
inventory.instances = {
  borgbackup = {
    module = {
      name = "borgbackup";
      input = "clan-core";
    };
    roles.client.machines = {
        "bob" = {
            startAt = "*-*-* 04:00:00";
        };
        "jon" = {
        };
    };
    roles.server.machines = {
        "alice" = {
            address = "alice.example.org";
        };
    };
  };
};

```

--------------------------------

### Download Generic Installer (x86_64)

Source: https://docs.clan.lol/25.11/getting-started/prepare-physical-machines

Downloads the generic NixOS installer ISO for x86_64 architecture using wget. This is an alternative if a custom installer is not required.

```bash
wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso

```

--------------------------------

### Configure Pre and Post Backup Scripts for Services

Source: https://docs.clan.lol/25.11/guides/backups/backup-intro

Configures pre and post backup scripts for a service (e.g., Nextcloud) to stop and start related systemd services before and after the backup process. This ensures data consistency during backups.

```nix
clan.core.state.nextcloud = {
  folders = [ "/var/lib/nextcloud" ];
  preBackupScript = ''
    export PATH=${lib.makeBinPath [
        config.systemd.package
      ]}

      systemctl stop phpfpm-nextcloud.service
      systemctl stop nextcloud-cron.timer
  '';

  postBackupScript = ''
    export PATH=${lib.makeBinPath [
        config.systemd.package
      ]}

    systemctl start phpfpm-nextcloud.service
    systemctl start nextcloud-cron.timer
  '';
};

```

--------------------------------

### Example Certificate Search Domains (Nix)

Source: https://docs.clan.lol/25.11/services/official/admin

This example shows how to configure a list of domains to be included in the certificate for the admin service. The machine name is prepended to each domain before adding it to the certificate.

```Nix
[
  "mydomain.com"
]

```

--------------------------------

### Import ZFS Pool and Configure System Installation

Source: https://docs.clan.lol/25.11/guides/disk-encryption

This section details steps for importing a ZFS pool, setting key locations for decryption, and securely copying generated SSH host keys to the installer's mount point before initiating the main NixOS installation.

```bash
ssh root@nixos-installer.local

zfs set keylocation=prompt zroot/root

# Disconnect from the SSH session
# CTRL+D

ssh-keygen -q -N "" -C "" -t ed25519 -f ./initrd_host_ed25519_key
ssh-keygen -q -N "" -C "" -t rsa -b 4096 -f ./initrd_host_rsa_key

scp ./initrd_host* root@nixos-installer.local:/mnt/var/lib/

clan machines install gchq-local --target-host root@nixos-installer --phases install

```

--------------------------------

### Install Machine using QR Code Image

Source: https://docs.clan.lol/25.11/getting-started/prepare-physical-machines

This command installs a machine by extracting deployment information from a QR code image file. It updates the hardware configuration with `nixos-facter` and utilizes the `kexec` phase. This is convenient when deployment details are available as an image.

```bash
clan machines install [MACHINE] --png [PATH] \
    --update-hardware-config nixos-facter \
    --phases kexec
```

--------------------------------

### Start and Verify BorgBackup Service

Source: https://docs.clan.lol/25.11/guides/backups/advanced-example

Commands to start the BorgBackup service on the client machine and inspect its logs. Starting the service initiates the backup process, and checking the logs verifies successful operation and helps in troubleshooting.

```bash
systemctl start borgbackup-job-storagebox.service &
journalctl -u borgbackup-job-storagebox.service

```

--------------------------------

### Example Host Var File Reference

Source: https://docs.clan.lol/25.11/reference/options/clan

Provides an example of referencing a 'var' file for host configuration. This allows dynamic values to be read directly from a configuration file.

```nix
"hostname"
```

--------------------------------

### User Groups Configuration Example

Source: https://docs.clan.lol/25.11/services/official/users

This example shows how to configure additional groups for a user. The 'groups' option allows specifying any existing system group, such as 'wheel' for sudo access, 'networkmanager' for network management, or 'video' and 'input' for device access.

```nix
[
  "wheel"
  "networkmanager"
  "video"
  "input"
]

```

--------------------------------

### Download Generic Installer with curl

Source: https://docs.clan.lol/25.11/getting-started/prepare-physical-machines

Provides an alternative method to download the generic NixOS installer ISO using curl. This is useful if wget is not installed on the system. Replace '<url>' with the actual download link.

```bash
curl --progress-bar -OL <url>

```

--------------------------------

### Display Installer Information (Text and QR Code)

Source: https://docs.clan.lol/25.11/getting-started/prepare-physical-machines

The installer displays crucial deployment information, including a root password and network addresses, in both a text format and a QR code. The QR code contains a JSON object with the password, Tor address, and IP addresses. This information is essential for connecting to and configuring the newly installed system.

```text
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ ┌───────────────────────────┐                                                       │
│ │███████████████████████████│ # This is the QR Code (1)                             │
│ │██ ▄▄▄▄▄ █▀▄█▀█▀▄█ ▄▄▄▄▄ ██│                                                       │
│ │██ █   █ █▀▄▄▄█ ▀█ █   █ ██│                                                       │
│ │██ █▄▄▄█ █▀▄ ▀▄▄▄█ █▄▄▄█ ██│                                                       │
│ │██▄▄▄▄▄▄▄█▄▀ ▀▄▀▄█▄▄▄▄▄▄▄██│                                                       │
│ │███▀▀▀ █▄▄█ ▀▄   ▄▀▄█   ███│                                                       │
│ │██▄██▄▄█▄▄▀▀██▄▀ ▄▄▄ ▄▀█▀██│                                                       │
│ │██ ▄▄▄▄▄ █▄▄▄▄ █ █▄█ █▀ ███│                                                       │
│ │██ █   █ █ █  █ ▄▄▄  ▄▀▀ ██│                                                       │
│ │██ █▄▄▄█ █ ▄ ▄    ▄ ▀█ ▄███│                                                       │
│ │██▄▄▄▄▄▄▄█▄▄▄▄▄▄█▄▄▄▄▄█▄███│                                                       │
│ │███████████████████████████│                                                       │
│ └───────────────────────────┘                                                       │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │Root password: cheesy-capital-unwell  # password (2)                             │ │
│ │Local network addresses:                                                         │ │
│ │enp1s0           UP    192.168.178.169/24 metric 1024 fe80::21e:6ff:fe45:3c92/64 │ │
│ │enp2s0           DOWN                                                            │ │
│ │wlan0            DOWN # connect to wlan (3)                                      │ │
│ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion    │ │
│ │Multicast DNS: nixos-installer.local                                             │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ Press 'Ctrl-C' for console access                                                   │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘

```

--------------------------------

### Configure initrd.nix for NixOS Installation

Source: https://docs.clan.lol/25.11/guides/disk-encryption

This Nix configuration enables systemd in the initrd, sets up network access via SSH with a specified port and authorized keys, and loads necessary kernel modules like 'xhci_pci' and 'r8169'. Replace `<yourkey>` with your SSH public key and `r8169` with your target machine's ethernet module.

```nix
{config, pkgs, ...}:

{

  boot.initrd.systemd = {
    enable = true;
  };

  # uncomment this if you want to be asked for the decryption password on login
  #users.root.shell = "/bin/systemd-tty-ask-password-agent";

  boot.initrd.network = {
    enable = true;

    ssh = {
      enable = true;
      port = 7172;
      authorizedKeys = [ "<yourkey>" ];
      hostKeys = [
        "/var/lib/initrd_host_ed25519_key"
        "/var/lib/initrd_host_rsa_key"
      ];
    };
  };
  boot.initrd.availableKernelModules = [
    "xhci_pci"
  ];

  # Find out the required network card driver by running `lspci -k` on the target machine
  boot.initrd.kernelModules = [ "r8169" ];
}


```

--------------------------------

### Markdown README for Single Disk Setup

Source: https://docs.clan.lol/25.11/guides/disko-templates/community

This Markdown file serves as the README for a single disk setup template. It includes frontmatter with a description and a main heading, providing a brief overview of the schema's purpose.

```markdown
---
description = "Simple disk schema for single disk setups"
---

# Single disk

Use this schema for simple setups where ....

```

--------------------------------

### Download Generic Installer (ARM64)

Source: https://docs.clan.lol/25.11/getting-started/prepare-physical-machines

Downloads the generic NixOS installer ISO for ARM64 (aarch64) architecture using wget. Note that this may not be compatible with all ARM devices, such as Raspberry Pi.

```bash
wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-aarch64-linux.iso

```

--------------------------------

### Example: Run Service-Dummy-Test

Source: https://docs.clan.lol/25.11/guides/contributing/testing

This example demonstrates the two-step process for running the 'service-dummy-test', which requires variable generation. First, test variables are generated, and then the test is executed.

```bash
# First, generate the test vars
nix run .#checks.x86_64-linux.service-dummy-test.update-vars

# Then run the test
nix run .#checks.x86_64-linux.service-dummy-test

```

--------------------------------

### Example Host Var Generator Reference

Source: https://docs.clan.lol/25.11/reference/options/clan

Shows an example of using a generator for 'var' configuration, such as 'tor-ssh'. This allows for generating host variables dynamically.

```nix
"tor-ssh"
```

--------------------------------

### Complete Example Configuration for Internal Services

Source: https://docs.clan.lol/25.11/guides/internal-ssl-services

A comprehensive configuration example integrating CoreDNS and Certificates services for a custom TLD. It demonstrates setting up a DNS server, CA, and multiple web services on different machines within the clan network.

```inventory
nventory = {
  machines = {
    caserver = { };  # DNS server + CA + web services
    webserver = { }; # Additional web services
    client = { };    # Client machine
  };

  instances = {
    coredns = {

      # Add the default role to all machines
      roles.default.tags = [ "all" ];

      # DNS server for the .c TLD
      roles.server.machines.caserver.settings = {
        ip = "192.168.8.5";
        tld = "c";
      };

      # machine hosting https://ca.c (our CA for SSL)
      roles.default.machines.caserver.settings = {
        ip = "192.168.8.5";
        services = [ "ca" ];
      };

      # machine hosting https://blub.c (some internal web-service)
      roles.default.machines.webserver.settings = {
        ip = "192.168.8.6";
        services = [ "blub" ];
      };
    };

    # Provide https for the .c top-level domain
    certificates = {

      roles.ca.machines.caserver.settings = {
        tlds = [ "c" ];
        acmeEmail = "admin@example.com";
      };

      roles.default.tags = [ "all" ];
    };
  };
};

```

--------------------------------

### List Available Keymaps

Source: https://docs.clan.lol/25.11/getting-started/prepare-physical-machines

This command retrieves a list of all supported keyboard layouts (keymaps) that can be configured for the installer. This is useful for setting the correct input method.

```bash
clan flash list keymaps

```

--------------------------------

### Install Machine with Hardware Configuration Update

Source: https://docs.clan.lol/25.11/getting-started/prepare-physical-machines

This command initiates the installation of a machine, updating its hardware configuration using `nixos-facter`. The `--phases kexec` flag ensures that the system boots into a NixOS kernel without immediately formatting disks, allowing for flexible deployment scenarios. The `--target-host` specifies the remote host to install.

```bash
clan machines install [MACHINE] \
    --update-hardware-config nixos-facter \
    --phases kexec \
    --target-host root@192.168.178.169
```

--------------------------------

### Install Nix Package Manager on Linux/macOS

Source: https://docs.clan.lol/25.11/getting-started/creating-your-first-clan

Installs the Nix package manager using the recommended installer script. After installation, it configures Nix to enable experimental features like nix-command and flakes.

```shell
curl -sSfL https://artifacts.nixos.org/nix-installer | sh -s -- install

# Add to ~/.config/nix/nix.conf:
# experimental-features = nix-command flakes
```

--------------------------------

### Install Machine using JSON Configuration

Source: https://docs.clan.lol/25.11/getting-started/prepare-physical-machines

This command installs a machine using a JSON configuration provided either as a string or a file path. It also updates the hardware configuration with `nixos-facter` and uses the `kexec` phase for booting into the NixOS kernel. This method is suitable for automated deployments where configuration is managed externally.

```bash
clan machines install [MACHINE] --json [JSON] \
    --update-hardware-config nixos-facter \
    --phases kexec
```

--------------------------------

### Example Host Var Machine Reference

Source: https://docs.clan.lol/25.11/reference/options/clan

Illustrates referencing a specific machine for 'var' configuration. This is useful for associating host variables with particular machines.

```nix
"jon"
```

--------------------------------

### List Available Languages

Source: https://docs.clan.lol/25.11/getting-started/prepare-physical-machines

This command retrieves a list of all supported language and locale settings for the installer. This helps in configuring the system's language preferences.

```bash
clan flash list languages

```

--------------------------------

### Generate Certificate Authority with Intermediate Certificates

Source: https://docs.clan.lol/25.11/guides/vars/vars-advanced-examples

This example shows how to create a complete certificate authority (CA) with root and intermediate certificates using dependencies. It generates a root CA key and certificate, an intermediate key, and an intermediate certificate signed by the root CA. The generated certificates are then configured for use with Nginx.

```nix
{
  # Generate root CA (not deployed to machines)
  clan.core.vars.generators.root-ca = {
    files."ca.key" = {
      secret = true;
      deploy = false;  # Keep root key offline
    };
    files."ca.crt".secret = false;
    runtimeInputs = [ pkgs.step-cli ];
    script = ''
      step certificate create "My Root CA" \
        $out/ca.crt $out/ca.key \
        --profile root-ca \
        --no-password \
        --insecure \
        --not-after 87600h
    '';
  };

  # Generate intermediate key
  clan.core.vars.generators.intermediate-key = {
    files."intermediate.key" = {
      secret = true;
      deploy = true;
    };
    runtimeInputs = [ pkgs.step-cli ];
    script = ''
      step crypto keypair \
        $out/intermediate.pub \
        $out/intermediate.key \
        --no-password \
        --insecure
    '';
  };

  # Generate intermediate certificate signed by root
  clan.core.vars.generators.intermediate-cert = {
    files."intermediate.crt".secret = false;
    dependencies = [
      "root-ca"
      "intermediate-key"
    ];
    runtimeInputs = [ pkgs.step-cli ];
    script = ''
      step certificate create "My Intermediate CA" \
        $out/intermediate.crt \
        --key $in/intermediate-key/intermediate.key \
        --ca $in/root-ca/ca.crt \
        --ca-key $in/root-ca/ca.key \
        --profile intermediate-ca \
        --not-after 8760h \
        --no-password \
        --insecure
    '';
  };

  # Use the certificates in services
  services.nginx.virtualHosts."example.com" = {
    sslCertificate = config.clan.core.vars.generators.intermediate-cert.files."intermediate.crt".value;
    sslCertificateKey = config.clan.core.vars.generators.intermediate-key.files."intermediate.key".path;
  };
}

```

--------------------------------

### Example Host Var Flake Reference

Source: https://docs.clan.lol/25.11/reference/options/clan

Demonstrates how to reference a 'var' from a flake for host configuration. This enables using values defined within the flake's configuration.

```nix
"config.clan.core.settings.directory"
```

--------------------------------

### WireGuard Hostname Resolution Examples (Bash)

Source: https://docs.clan.lol/25.11/services/official/wireguard

Demonstrates how to use automatically generated hostnames for network communication within the WireGuard VPN. It shows examples for pinging and SSHing to other machines using their hostnames.

```bash
# Ping another machine by hostname
ping6 server1.vpn

# SSH to another machine
ssh user@laptop1.vpn

```

--------------------------------

### Define WiFi Network Options (Nix)

Source: https://docs.clan.lol/25.11/services/official/wifi

This example shows the default configuration for the 'networks' option, which is an empty attribute set. It also provides an example of how to configure a specific network ('guest') with custom settings like 'autoConnect' and 'keyMgmt'.

```nix
{
  guest = {
    autoConnect = false;
    keyMgmt = "wpa-eap";
  };
  home = { };
}

```

--------------------------------

### Clan Service Per-Machine Darwin Module Example (Nix)

Source: https://docs.clan.lol/25.11/reference/options/clan_service

Provides an example of configuring a Darwin-specific Nix module within the per-machine settings of a clan service. This allows for machine-specific configurations on macOS.

```nix
#              ↓ machine.roles ...
perMachine = { machine, ... }:
{
              # ↓ darwin-config
  darwinModule = { config ,... }:
{
    launchd.daemons.foo = {
      enable = true;
    };
  }
}

```

--------------------------------

### sshd Client Role: certificate.searchDomains Option Example (Nix)

Source: https://docs.clan.lol/25.11/services/official/sshd

This example shows how to configure the `certificate.searchDomains` option for the sshd client role. It specifies a list of domains that the client will trust for verifying server certificates, enabling zero-trust connections.

```nix
[
  "mydomain.com"
]
```

--------------------------------

### Example Allowed SSH Public Key (Nix)

Source: https://docs.clan.lol/25.11/services/official/admin

An example demonstrating how to define an allowed public SSH key for the admin user. This is used within the `allowedKeys` attribute set to grant SSH access to specific keys.

```Nix
{
  key_1 = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQD...";
}

```

--------------------------------

### Client Role Configuration Example (Nix)

Source: https://docs.clan.lol/25.11/decisions/01-Clan-Modules

An example Nix module demonstrating how to configure a 'client' role. It shows the use of `perInstance` to generate a NixOS module for each client instance and `perMachine` to apply configurations to machines with the 'client' role, including importing shared modules and setting debug options.

```nix
# Some example module
{
  _class = "clan.service";

  # Analog to flake-parts 'perSystem' only that it takes instance
  # The exact arguments will be specified and documented along with the actual implementation.
  roles.client.perInstance = {
      # attrs : settings of that instance
      settings,
      # string : name of the instance
      instanceName,
      # { name :: string , roles :: listOf string; }
      machine,
      # { {roleName} :: { machines :: listOf string; } }
      roles,
      ... 
    }:
    {
      # Return a nixos module for every instance.
      # The module author must be aware that this may return multiple modules (one for every instance) which are merged natively
      nixosModule = {
        config.debug."${instanceName}-client" = instanceConfig;
      };
    };
  # Function that is called once for every machine with the role "client" 
  # Receives at least the following parameters:
  # 
  # machine :: { name :: String, roles :: listOf string; }
  # Name of the machine
  # 
  # instances :: { instanceName :: { roleName :: { machines :: [ string ]; }}} 
  # Resolved roles
  # Same type as currently in `clan.inventory.services.<ServiceName>.<InstanceName>.roles`
  # 
  # The exact arguments will be specified and documented along with the actual implementation.
  perMachine = {machine, instances, ... }: {
    nixosModule =
      { lib, ... }:
      {
        # Some shared code should be put into a shared file
        # Which is then imported into all/some roles
        imports = [
          ../shared.nix
        ] ++ 
        (lib.optional (builtins.elem "client" machine.roles) 
        {
          options.debug = lib.mkOption {
            type = lib.types.attrsOf lib.types.raw;
          };
        });
      };
  };
}

```

--------------------------------

### Example Directory Structure

Source: https://docs.clan.lol/25.11/reference/options/clan

Illustrates a typical directory structure for a clan, including essential directories like 'flake.nix', 'assets', 'machines', 'modules', and 'sops'.

```plaintext
.
├── flake.nix
├── assets
├── machines
├── modules
└── sops

```

--------------------------------

### Nix Configuration for Single Disk Setup

Source: https://docs.clan.lol/25.11/guides/disko-templates/community

This Nix configuration defines the disk setup for a single disk. It uses placeholders like '{{mainDisk}}' which are filled with machine-specific options. The configuration is copied to 'machines/{machineName}/disko.nix'.

```nix
{
  disko.devices = {
    disk = {
      main = {
        device = "{{mainDisk}}";
        ...
      };
    };
  };
}

```

--------------------------------

### Finalize ZFS Configuration and Export Pool

Source: https://docs.clan.lol/25.11/guides/disk-encryption

After NixOS installation, these commands unmount boot partitions, adjust ZFS mount points to their correct locations, and export the ZFS pool to finalize the setup before rebooting.

```bash
umount /mnt/boot
cd /
zfs set -u mountpoint=/ zroot/root/nixos
zfs set -u mountpoint=/tmp zroot/root/tmp
zfs set -u mountpoint=/home zroot/root/home
zpool export zroot

```

--------------------------------

### Instantiate Borgbackup Service with Roles

Source: https://docs.clan.lol/25.11/guides/services/introduction-to-services

Demonstrates how to instantiate the 'borgbackup' service and assign roles (client and server) to specific machines. This example shows the basic structure for defining service participation across different hosts.

```nix
inventory.instances = {
  borgbackup = {
    roles.client.machines."laptop" = {};
    roles.client.machines."workstation" = {};

    roles.server.machines."backup-box" = {};
  };
}
```

--------------------------------

### Generate SSH Host Keys Signed by a CA

Source: https://docs.clan.lol/25.11/guides/vars/vars-advanced-examples

This example illustrates how to generate SSH host keys and sign them with a Certificate Authority (CA). It sets up an SSH CA, generates host-specific keys, signs the public key with the CA, and configures the SSH service to use these generated keys.

```nix
{
  # SSH Certificate Authority (shared)
  clan.core.vars.generators.ssh-ca = {
    share = true;
    files."ca" = { secret = true; deploy = false; };
    files."ca.pub" = { secret = false; };
    runtimeInputs = [ pkgs.openssh ];
    script = ''
      ssh-keygen -t ed25519 -N "" -f $out/ca
      mv $out/ca.pub $out/ca.pub
    '';
  };

  # Host-specific SSH keys
  clan.core.vars.generators.ssh-host = {
    files."ssh_host_ed25519_key" = {
      secret = true;
      owner = "root";
      group = "root";
      mode = "0600";
    };
    files."ssh_host_ed25519_key.pub" = { secret = false; };
    files."ssh_host_ed25519_key-cert.pub" = { secret = false; };
    dependencies = [ "ssh-ca" ];
    runtimeInputs = [ pkgs.openssh ];
    script = ''
      # Generate host key
      ssh-keygen -t ed25519 -N "" -f $out/ssh_host_ed25519_key

      # Sign with CA
      ssh-keygen -s $in/ssh-ca/ca \
        -I "host:${config.networking.hostName}" \
        -h \
        -V -5m:+365d \
        $out/ssh_host_ed25519_key.pub
    '';
  };

  # Configure SSH to use the generated keys
  services.openssh = {
    hostKeys = [{
      path = config.clan.core.vars.generators.ssh-host.files."ssh_host_ed25519_key".path;
      type = "ed25519";
    }];
  };
}

```

--------------------------------

### Full Porkbun Example in clan.nix for dyndns

Source: https://docs.clan.lol/25.11/services/official/dyndns

This Nix configuration provides a comprehensive example for managing dynamic DNS records with the Porkbun provider using the clan.nix framework. It sets up multiple host records for a domain, specifies the update period, and includes provider-specific extra settings. This configuration is designed for advanced users managing multiple subdomains.

```nix
inventory.instances = {
  dyndns = {
    roles.default.machines."jon" = { };
    roles.default.settings = {
      period   = 15;                # minutes
      settings = {
        "all-jon-blog" = {
          provider         = "porkbun";
          domain           = "jon.blog";

          #  tell the secret-manager which key we are going to store
          secret_field_name = "secret_api_key";

          # everything below is copied verbatim into config.json
          extraSettings = {
            host         = "@,home,test";   #  comma-separated list of sub-domains
            ip_version   = "ipv4";
            ipv6_suffix  = "";
            api_key      = "pk1_4bb2b231275a02fdc23b7e6f3552s01S213S"; #  public – safe to commit
          };
        };
      };
    };
  };
};

```

--------------------------------

### Scale Borgbackup Service Using Tags

Source: https://docs.clan.lol/25.11/guides/inventory/inventory

This example shows how to scale the Borgbackup service by assigning tags to machines and then referencing those tags in the service configuration. This allows a service to be applied to multiple machines that share a common tag.

```nix
{
    inventory = {
        machines = {
            "jon" = {
                tags = [ "backup" ];
            };
            "sara" = {
                tags = [ "backup" ];
            };
        };

        instances.instance_1 = {
            module = {
                name = "borgbackup";
                input = "clan-core";
            };

            roles.client.tags = [ "backup" ];
            roles.server.machines."backup_server" = {};
        };
    };
}
```

--------------------------------

### Copy SSH Public Key to NixOS Installer

Source: https://docs.clan.lol/25.11/guides/disk-encryption

This command copies your SSH public key to the NixOS installer, allowing passwordless SSH access. It specifies password authentication first and disables public key authentication for this initial connection.

```bash
ssh-copy-id -o PreferredAuthentications=password -o PubkeyAuthentication=no root@nixos-installer.local

```

--------------------------------

### Admin Role: Bootstrap Nodes Configuration

Source: https://docs.clan.lol/25.11/services/official/data-mesher

Example configuration for bootstrap nodes in the data-mesher admin role. These nodes serve as an initial gateway for joining the cluster. The type is a list of strings, each representing a node address and port.

```nix
[
  "192.168.1.1:7946"
  "192.168.1.2:7946"
]
```

--------------------------------

### Manually Create Machine Configuration File

Source: https://docs.clan.lol/25.11/getting-started/add-machines

This example shows the structure of a manually created 'configuration.nix' file for a machine. It demonstrates how to import additional modules, such as enabling the GNOME desktop environment, and provides a placeholder for setting NixOS options.

```nix
{
    imports = [
        # enables GNOME desktop (optional)
        ../../modules/gnome.nix
    ];

    # Set nixosOptions here
    # Or import your own modules via 'imports'
    # ...
}

```

--------------------------------

### Default BorgBackup Client Start Time

Source: https://docs.clan.lol/25.11/services/official/borgbackup

Sets the default time for initiating client backups. The format allows for specifying a recurring schedule for automated backups.

```nix
"*-*-* 01:00:00"
```

--------------------------------

### Minimal Namecheap Configuration for dyndns

Source: https://docs.clan.lol/25.11/services/official/dyndns

This JSON configuration demonstrates a minimal setup for the Namecheap provider within the ddns-updater service. It specifies the provider, the domain to be updated, and the necessary password for authentication. This is a basic example for integrating with Namecheap.

```json
{
  "settings": [
    {
      "provider": "namecheap",
      "domain": "sub.example.com",
      "password": "e5322165c1d74692bfa6d807100c0310"
    }
  ]
}
```

--------------------------------

### Configure Borgbackup Service Settings

Source: https://docs.clan.lol/25.11/guides/services/introduction-to-services

Illustrates how to configure settings for the 'borgbackup' service, both on a per-machine basis and for an entire role. This example sets backup folders for a specific machine and a default directory for all server roles.

```nix
inventory.instances = {
    borgbackup = {
        # Settings for 'machine-a'
        roles.client.machines."machine-a" = {
            settings = {
                backupFolders = [
                    /home
                    /var
                ];
            };
        };

        # Settings for all machines of the role "server"
        roles.server.settings = {
            directory = "/var/lib/borgbackup";
        };
    };
}
```

--------------------------------

### Conditionally Generate Secrets Based on Machine Role

Source: https://docs.clan.lol/25.11/guides/vars/vars-advanced-examples

Generates different secrets based on machine configuration. All machines receive basic authentication credentials generated using `htpasswd`. Servers specifically get API tokens generated with `openssl rand` if the `services.myapi.enable` option is true.

```nix
{
  clan.core.vars.generators = lib.mkMerge [
    # All machines get basic auth
    {
      basic-auth = {
        files."htpasswd" = {};
        prompts.username = {
          description = "Username for basic auth";
          type = "line";
        };
        prompts.password = {
          description = "Password for basic auth";
          type = "hidden";
        };
        runtimeInputs = [ pkgs.apacheHttpd ];
        script = ''
          htpasswd -nbB "$prompts/username" "$prompts/password" > $out/htpasswd
        '';
      };
    }

    # Only servers get API tokens
    (lib.mkIf config.services.myapi.enable {
      api-tokens = {
        files."admin-token" = {};
        files."readonly-token" = {};
        runtimeInputs = [ pkgs.openssl ];
        script = ''
          openssl rand -hex 32 > $out/admin-token
          openssl rand -hex 16 > $out/readonly-token
        '';
      };
    })
  ];
}

```

--------------------------------

### Configure ZeroTier Service in Clan's flake.nix

Source: https://docs.clan.lol/25.11/guides/networking/mesh-vpn

This Nix configuration snippet defines the ZeroTier service within Clan's inventory system. It specifies roles for machines, assigning one as the controller and others as peers. This setup is crucial for managing the VPN network.

```nix
{
  inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/25.11.tar.gz";
  inputs.nixpkgs.follows = "clan-core/nixpkgs";

  outputs = 
    { self, clan-core, ... }:
    let
      # Sometimes this attribute set is defined in clan.nix
      clan = clan-core.lib.clan {
        inherit self;

        meta.name = "myclan";
        meta.domain = "ccc";

        inventory.machines = {
          controller = {};
          new_machine = {};
        };

        inventory.instances = {
          zerotier = {
            # Assign the controller machine to the role "controller"
            roles.controller.machines."controller" = {};

            # All clan machines are zerotier peers
            roles.peer.tags."all" = {};
          };
        };
      };
    in
    {
      inherit (clan) nixosConfigurations nixosModules clanInternals;
    };
}

```

--------------------------------

### Minimal matrix-synapse Configuration with Element, PostgreSQL, and Nginx

Source: https://docs.clan.lol/25.11/services/official/matrix-synapse

This Nix configuration demonstrates a basic setup for the matrix-synapse service. It includes the Element web client, a Synapse homeserver backed by PostgreSQL, and nginx for serving the client and proxying requests. It also sets up an administrator user and a regular user.

```nix
instances = {
    matrix-synapse = {
        roles.default.machines."jon".settings = {
            acmeEmail = "admins@clan.lol";
            server_tld = "clan.test";
            app_domain = "matrix.clan.test";
            users.admin.admin = true;
            users.someuser = { };
        };
    };
};

```

--------------------------------

### Setup Development Shell for clan-cli

Source: https://docs.clan.lol/25.11/guides/contributing/debugging

Configures a Nix development shell to use a local checkout of clan-cli. This avoids installation and allows direct use of the development version. It requires cloning the clan-core repository and adding the clan-cli bin directory to the PATH. Ensure `direnv allow` is run after cloning to set up necessary symlinks.

```nix
pkgs.mkShell {
    packages = [
        pkgs.python3
    ];
    shellHook = ''
            export GIT_ROOT="$(git rev-parse --show-toplevel)"
            export PATH=$PATH:~/Projects/clan-core/pkgs/clan-cli/bin
    '';
}

```

--------------------------------

### NixOS Disko Configuration for Mirrored ZFS Encryption

Source: https://docs.clan.lol/25.11/guides/disk-encryption

This NixOS configuration snippet defines a mirrored disk setup using disko for ZFS encryption. It includes GPT partitioning for boot and ESP, and two ZFS pools ('zroot') for redundancy. The root dataset is encrypted with AES-256-GCM, using a passphrase stored in a file.

```nix
{
    lib,
    ...
  }:
  let
    mirrorBoot = idx: {
      # suffix is to prevent disk name collisions
      name = idx;
      type = "disk";
      device = "/dev/disk/by-id/${idx}";
      content = {
        type = "gpt";
        partitions = {
          "boot" = {
            size = "1M";
            type = "EF02"; # for grub MBR
            priority = 1;
          };
          "ESP" = lib.mkIf (idx == "nvme-eui.002538b931b59865") {
            size = "1G";
            type = "EF00";
            content = {
              type = "filesystem";
              format = "vfat";
              mountpoint = "/boot";
              mountOptions = [ "nofail" ];
            };
          };
          "root" = {
            size = "100%";
            content = {
              type = "zfs";
              pool = "zroot";
            };
          };
        };
      };
    };
  in
  {
    imports = [ ];

    config = {
      boot.loader.systemd-boot.enable = true;

      disko.devices = {
        disk = {
          x = mirrorBoot "nvme-eui.002538b931b59865";
          y = mirrorBoot "my-other-disk";
        };
        zpool = {
          zroot = {
            type = "zpool";
            rootFsOptions = {
              compression = "lz4";
              acltype = "posixacl";
              xattr = "sa";
              "com.sun:auto-snapshot" = "true";
              mountpoint = "none";
            };
            datasets = {
              "root" = {
                type = "zfs_fs";
                options = {
                  mountpoint = "none";
                  encryption = "aes-256-gcm";
                  keyformat = "passphrase";
                  keylocation = "file:///tmp/secret.key";
                };
              };
              "root/nixos" = {
                type = "zfs_fs";
                options.mountpoint = "/";
                mountpoint = "/";
              };
              "root/home" = {
                type = "zfs_fs";

```

--------------------------------

### NixOS Disko Configuration for Single Disk ZFS Encryption

Source: https://docs.clan.lol/25.11/guides/disk-encryption

This NixOS configuration snippet defines a single disk setup using disko. It includes GPT partitioning for a boot partition, an EFI System Partition (ESP), and a ZFS root filesystem with AES-256-GCM encryption. The key is stored in a file for passphrase-based decryption.

```nix
{
    lib,
    ...
  }:
  let
    mirrorBoot = idx: {
      # suffix is to prevent disk name collisions
      name = idx;
      type = "disk";
      device = "/dev/disk/by-id/${idx}";
      content = {
        type = "gpt";
        partitions = {
          "boot" = {
            size = "1M";
            type = "EF02"; # for grub MBR
            priority = 1;
          };
          "ESP" = lib.mkIf (idx == "nvme-eui.002538b931b59865") {
            size = "1G";
            type = "EF00";
            content = {
              type = "filesystem";
              format = "vfat";
              mountpoint = "/boot";
              mountOptions = [ "nofail" ];
            };
          };
          "root" = {
            size = "100%";
            content = {
              type = "zfs";
              pool = "zroot";
            };
          };
        };
      };
    };
  in
  {
    imports = [ ];

    config = {
      boot.loader.systemd-boot.enable = true;

      disko.devices = {
        disk = {
          x = mirrorBoot "nvme-eui.002538b931b59865";
        };
        zpool = {
          zroot = {
            type = "zpool";
            rootFsOptions = {
              compression = "lz4";
              acltype = "posixacl";
              xattr = "sa";
              "com.sun:auto-snapshot" = "true";
              mountpoint = "none";
            };
            datasets = {
              "root" = {
                type = "zfs_fs";
                options = {
                  mountpoint = "none";
                  encryption = "aes-256-gcm";
                  keyformat = "passphrase";
                  keylocation = "file:///tmp/secret.key";
                };
              };
              "root/nixos" = {
                type = "zfs_fs";
                options.mountpoint = "/";
                mountpoint = "/";
              };
              "root/home" = {
                type = "zfs_fs";
                options.mountpoint = "/home";
                mountpoint = "/home";
              };
              "root/tmp" = {
                type = "zfs_fs";
                mountpoint = "/tmp";
                options = {
                  mountpoint = "/tmp";
                  sync = "disabled";
                };
              };
            };
          };
        };
      };
    };
  }
```

--------------------------------

### Instantiate Borgbackup Service with Module Specification

Source: https://docs.clan.lol/25.11/guides/services/introduction-to-services

Shows how to instantiate the 'borgbackup' service, explicitly referencing its module source. It includes optional parameters for module name and input flake, along with role assignments for machines.

```nix
inventory.instances = {

    borgbackup = {

        # This can be partially/fully specified,
        # - If the instance name is not the name of the module
        # - If the input is not clan-core
        # module =  {
        #     name = "borgbackup";  # Name of the module (optional)
        #     input = "clan-core"; # The flake input where the service is defined (optional)
        # };

        # Participation of the machines is defined via roles
        roles.client.machines."machine-a" = {};
        roles.server.machines."backup-host" = {};
    };
}
```

--------------------------------

### Machines Init Hardware Config API

Source: https://docs.clan.lol/25.11/reference/cli/machines

Uses kexec to boot the target into a minimal NixOS environment to gather hardware information. The target must be a Linux-based system reachable via SSH.

```APIDOC
## POST /machines/init-hardware-config

### Description
Uses kexec to boot the target into a minimal NixOS environment to gather hardware information. The target must be a Linux-based system reachable via SSH.

### Method
POST

### Endpoint
/machines/init-hardware-config

### Parameters
#### Query Parameters
- **target-host** (string) - Required - Address of the target machine, in the format of user@host:1234.
- **--ssh-key** (string) - Optional - Path to the SSH private key for authentication.

### Request Example
```bash
clan machines init-hardware-config --target-host "user@192.168.1.100:22" --ssh-key "~/.ssh/id_ed25519"
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that hardware information gathering has started.
- **ip_address** (string) - The IP address of the target machine.

#### Response Example
```json
{
  "message": "Hardware information gathering initiated on 192.168.1.100.",
  "ip_address": "192.168.1.100"
}
```
```

--------------------------------

### Share Additional Nix Configuration with ExtraModules

Source: https://docs.clan.lol/25.11/guides/services/introduction-to-services

Shows how to include custom NixOS configurations alongside Clan services using the `extraModules` option. This example demonstrates direct module references, using `self`, and inline module definitions.

```nix
inventory.instances = {
    borgbackup = {
        roles.client = {
            # Direct module reference
            extraModules = [ ../nixosModules/borgbackup.nix ];

            # Or using self (needs to be json serializable)
            # See next example, for a workaround.
            extraModules = [ self.nixosModules.borgbackup ];

            # Or inline module definition, (needs to be json compatible)
            extraModules = [
              {
                # Your module configuration here
                # ...
                #
                # If the module needs to contain non-serializable expressions:
                imports = [ ./path/to/non-serializable.nix ];
              }
            ];
        };
    };
}
```

--------------------------------

### Complex Yggdrasil Deployment with Network Services

Source: https://docs.clan.lol/25.11/services/official/yggdrasil

This example shows a sophisticated Yggdrasil setup integrating with other clan network services like 'internet', 'mycelium', and 'tor'. It configures a custom domain 'ccc' for host resolution and leverages Yggdrasil's ability to route traffic through various available network transports for resilience.

```nix
inventory = {

  machines = {
    peer1 = {};
    peer2 = {};
  };

  meta.domain = "ccc";

  instances = {

    # Deploy yggdraisl on all machines
    yggdrasil = {
      roles.default.tags.all = [ "all" ];
    };

    internet = {
      roles.default.machines = {
        peer1.settings.host = "85.139.10.1";
        peer2.settings.host = "85.139.10.2";
      };
    };

    mycelium = {
      roles.peer.tags.all = {};
    };

    tor = {

      roles.client.tags = [ "all" ];
      roles.server.tags = [ "all" ];

      roles.server.settings = {

        secretHostname = false;

        # yggdrasil ports need to be mapped
        portMapping = [
          {
            port = 6443;
            target.port = 6443;
          }
          {
            port = 6446;
            target.port = 6446;
          }
        ];
      };
    };
  };
};

```

--------------------------------

### Configure localbackup Service with External Target

Source: https://docs.clan.lol/25.11/services/official/localbackup

This snippet demonstrates how to enable the localbackup service and configure an external backup target. It specifies the module name, input source, and settings for the external target, including the directory and mountpoint for backups.

```nix
instances = {
  localbackup = {
    module.name = "@clan/localbackup";
    module.input = "self";
    roles.default.machines."machine".settings = {
      targets.external = {
        directory = "/mnt/backup";
        mountpoint = "/mnt/backup";
      };
    };
  };
};

```

--------------------------------

### Add SSH Public Key to Installer

Source: https://docs.clan.lol/25.11/getting-started/prepare-physical-machines

This option allows you to include an SSH public key in the installer image. This enables passwordless SSH access to the installer later. Generate a key with `ssh-keygen -t ed25519` if you don't have one.

```bash
--ssh-pubkey <pubkey_path>

```