feat: add headscale
Headscale is an open source implementation of the tailscale server.
We've written a module that will allow you to easily run it with some
basic but sensible options, and set it up for running on a1d1.
Change-Id: If67dd498cbe0b0c3c81c66a0216845d0eaf1282c
Reviewed-on: https://git.clicks.codes/c/Infra/NixFiles/+/728
Tested-by: Samuel Shuert <coded@clicks.codes>
Reviewed-by: Samuel Shuert <coded@clicks.codes>
diff --git a/modules/nixos/clicks/services/headscale/README.md b/modules/nixos/clicks/services/headscale/README.md
new file mode 100644
index 0000000..fd5cc1a
--- /dev/null
+++ b/modules/nixos/clicks/services/headscale/README.md
@@ -0,0 +1,78 @@
+<!--
+SPDX-FileCopyrightText: 2024 Clicks Codes
+
+SPDX-License-Identifier: GPL-3.0-only
+-->
+
+# Clicks Headscale
+
+Our module provides much more basic options than the NixOS headscale module, but we believe this saves you some of the
+hassle of configuring it.
+
+```nix
+clicks.services.headscale = {
+ enable = true;
+ url = "clicks.domains";
+};
+```
+
+The `url` is both the address you'll use to access your headscale server, as well as the base address that devices are
+suffixed with (e.g. a device called `albatross` owned by `minion` would become `albatross.minion.<url>`)
+
+---
+
+```nix
+clicks.services.headscale = {
+ addr = "0.0.0.0";
+ port = 80;
+};
+```
+
+By default, we host on port 80 without using SSL. We expect you to host a reverse proxy server, such as caddy or nginx
+to remedy this. To that end, your base URL *must* be accessible only over https.
+
+If you keep the default `0.0.0.0` address, we'll also open the port you set.
+
+These defaults will change when we have an nginx module, as the headscale module will automatically create a route.
+
+---
+
+```nix
+clicks.services.headscale = {
+ oidc = {
+ enable = true;
+ issuer = "https://login.clicks.codes/realms/master";
+ allowed_groups = [ "/clicks" ];
+ client_id = "headscale";
+ client_secret_path = config.clicks.secrets."${lib.clicks.secrets.name ./headscale.sops.a1d1.json}".paths.oidc_client_secret;
+ };
+};
+```
+
+If you have an OIDC server, we strongly recommend using it. It allows you to automatically create users and provision
+devices rather than needing to use the command line to do so.
+
+If you're using keycloak and want to use `allowed_groups`, you'll need to create a group membership mapper with the
+name `groups`. If you set "full group path" to enabled in Keycloak, you'll also need to prefix the group with a leading
+`/`. (We recommend you do this, as not doing it will mean that other groups could be unintentionally matched, for example
+`admins` would match `/clicks/admins` and `/transplace/admins`)
+
+The secret specified in your `client_secret_path` must be readable by the `headscale` group.
+
+---
+
+```nix
+clicks.services.headscale = {
+ database_password_path = config.clicks.secrets."${lib.clicks.secrets.name ./headscale.sops.a1d1.json}".paths.database_password;
+ noise_private_key_path = config.clicks.secrets."${lib.clicks.secrets.name ./headscale.sops.a1d1.json}".paths.noise_private_key;
+ private_key_path = config.clicks.secrets."${lib.clicks.secrets.name ./headscale.sops.a1d1.json}".paths.private_key;
+}
+```
+
+Finally, we have a few more secrets: the database_password_path, the noise_private_key_path, and the private_key_path.
+
+The "noise private key" and "private key" are generated by tailscale at launch if you don't specify them.
+
+The database password need not match an existing database; the headscale module automatically provisions the database using the Clicks Postgres module.
+
+All of these secrets must be readable by the `headscale` group.
diff --git a/modules/nixos/clicks/services/headscale/default.nix b/modules/nixos/clicks/services/headscale/default.nix
new file mode 100644
index 0000000..84be617
--- /dev/null
+++ b/modules/nixos/clicks/services/headscale/default.nix
@@ -0,0 +1,118 @@
+# SPDX-FileCopyrightText: 2024 Clicks Codes
+#
+# SPDX-License-Identifier: GPL-3.0-only
+
+{ lib, config, ... }:
+let
+ cfg = config.clicks.services.headscale;
+in
+{
+ options.clicks.services.headscale = {
+ enable = lib.mkEnableOption "The headscale control server for tailscale";
+ url = lib.mkOption {
+ type = lib.types.str;
+ description = "The url users should connect to to register a new device";
+ };
+ addr = lib.mkOption {
+ type = lib.types.str;
+ description = "Where to host headscale";
+ default = "0.0.0.0";
+ };
+ port = lib.mkOption {
+ type = lib.types.int;
+ description = "Port to host headscale on";
+ default = 80;
+ };
+ oidc = {
+ enable = lib.mkEnableOption "Enable OIDC";
+ issuer = lib.mkOption {
+ type = lib.types.str;
+ description = "Issuer URL for your OIDC provider";
+ };
+ allowed_groups = lib.mkOption {
+ type = lib.types.nullOr (lib.types.listOf lib.types.str);
+ description = "List of groups to allow authentication from";
+ };
+ client_id = lib.mkOption {
+ type = lib.types.str;
+ description = "Client ID";
+ default = "headscale";
+ };
+ client_secret_path = lib.mkOption {
+ type = lib.types.str;
+ description = "Client secret file path";
+ };
+ };
+ database_password_path = lib.mkOption {
+ type = lib.types.str;
+ description = "Database password file path";
+ };
+ noise_private_key_path = lib.mkOption {
+ type = lib.types.nullOr lib.types.str;
+ description = "Noise private key file path";
+ default = null;
+ };
+ private_key_path = lib.mkOption {
+ type = lib.types.nullOr lib.types.str;
+ description = "Headscale private key file path";
+ default = null;
+ };
+ };
+
+ config = lib.mkIf cfg.enable {
+ clicks = {
+ services.postgres.enable = true;
+ services.postgres.databases.headscale = cfg.database_password_path;
+ services.postgres.secretRequiredGroups = [ "headscale" ];
+ };
+
+ services.headscale = {
+ enable = true;
+
+ address = cfg.addr;
+ port = cfg.port;
+
+ settings.db_type = "postgres";
+ settings.db_port = config.services.postgresql.settings.port;
+ settings.db_user = "headscale";
+ settings.db_password_file = cfg.database_password_path;
+ settings.db_name = "headscale";
+ settings.db_host = lib.clicks.constants.hosts.standard;
+
+ settings.server_url = "https://${cfg.url}";
+
+ settings.ip_prefixes = "100.64.0.0/10";
+
+ settings.noise.private_key_path = lib.mkIf (
+ cfg.noise_private_key_path != null
+ ) cfg.noise_private_key_path;
+ settings.private_key_path = lib.mkIf (cfg.private_key_path != null) cfg.private_key_path;
+
+ settings.dns_config = {
+ nameservers = [
+ "1.1.1.1"
+ "1.0.0.1"
+ ];
+ override_local_dns = true;
+ base_domain = cfg.url;
+ };
+
+ settings.oidc = lib.mkIf cfg.oidc.enable {
+ only_start_if_oidc_is_available = true;
+
+ issuer = cfg.oidc.issuer;
+
+ client_id = cfg.oidc.client_id;
+ client_secret_path = cfg.oidc.client_secret_path;
+
+ allowed_groups = lib.mkIf (cfg.oidc.allowed_groups != null) cfg.oidc.allowed_groups;
+ strip_email_domain = true;
+ };
+ };
+
+ systemd.services.headscale.requires = [ "postgresql.service" ];
+ systemd.services.headscale.after = [ "postgresql.service" ];
+
+ networking.firewall.allowedTCPPorts = lib.mkIf (cfg.addr == "0.0.0.0") [ cfg.port ];
+ };
+}