rsp2k/headplane
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: nix: match NixOS module to the config schema

Browse Source
This commit is contained in:
Igor Ramazanov 2025-07-27 02:20:09 +00:00 committed by Aarnav Tale
parent 89e38e1356
commit c59632a0b7
1 changed files with 157 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

291
nix/module.nix
View File

@ -6,63 +6,61 @@
}: let }: let
inherit inherit
(lib) (lib)
attrsToList filterAttrs
listToAttrs filterAttrsRecursive
map
mkEnableOption mkEnableOption
mkIf mkIf
mkOption mkOption
mkPackageOption mkPackageOption
typeOf recursiveUpdate
types types
updateManyAttrsByPath
; ;
cfg = config.services.headplane; cfg = config.services.headplane;
settingsFormat = pkgs.formats.yaml {}; settingsFormat = pkgs.formats.yaml {};
settingsFile = settingsFormat.generate "headplane-config.yaml" cfg.settings; settingsWithAgentExecutablePath = recursiveUpdate cfg.settings {
agentEnv = listToAttrs (map (n: { integration.agent.executable_path = "${cfg.settings.integration.agent.package}/bin/hp_agent";
name = n.name; };
value = settingsWithoutAgentPackage =
if ((typeOf n.value) == "bool") updateManyAttrsByPath [
then {
( path = ["integration" "agent"];
if (n.value) update = old: filterAttrs (key: value: key != "package") old;
then "true" }
else "false" ]
) settingsWithAgentExecutablePath;
else n.value; settingsWithoutNulls = filterAttrsRecursive (key: value: value != null) settingsWithoutAgentPackage;
}) (attrsToList cfg.agent.settings)); settingsFile = settingsFormat.generate "headplane-config.yaml" settingsWithoutNulls;
in { in {
options.services.headplane = { options.services.headplane = {
enable = mkEnableOption "headplane"; enable = mkEnableOption "headplane";
package = mkPackageOption pkgs "headplane" {}; package = mkPackageOption pkgs "headplane" {};
settings = lib.mkOption { settings = mkOption {
description = '' description = ''
Headplane configuration options. Generates a YAML config file. Headplane configuration options. Generates a YAML config file.
See: https://github.com/tale/headplane/blob/main/config.example.yaml See: https://github.com/tale/headplane/blob/main/config.example.yaml
''; '';
type = lib.types.submodule { type = types.submodule {
freeformType = settingsFormat.type;
options = { options = {
server = lib.mkOption { server = mkOption {
type = lib.types.submodule { type = types.submodule {
options = { options = {
host = lib.mkOption { host = mkOption {
type = lib.types.str; type = types.str;
default = "127.0.0.1"; default = "127.0.0.1";
description = "The host address to bind to."; description = "The host address to bind to.";
example = "0.0.0.0"; example = "0.0.0.0";
}; };
port = lib.mkOption { port = mkOption {
type = lib.types.port; type = types.port;
default = 3000; default = 3000;
description = "The port to listen on."; description = "The port to listen on.";
}; };
cookie_secret_path = lib.mkOption { cookie_secret_path = mkOption {
type = lib.types.nullOr lib.types.path; type = types.nullOr types.path;
default = null; default = null;
description = '' description = ''
Path to a file containing the cookie secret. Path to a file containing the cookie secret.
@ -71,8 +69,8 @@ in {
example = "config.sops.secrets.headplane_cookie.path"; example = "config.sops.secrets.headplane_cookie.path";
}; };
cookie_secure = lib.mkOption { cookie_secure = mkOption {
type = lib.types.bool; type = types.bool;
default = true; default = true;
description = '' description = ''
Should the cookies only work over HTTPS? Should the cookies only work over HTTPS?
@ -81,33 +79,15 @@ in {
''; '';
}; };
agent = lib.mkOption { data_path = mkOption {
type = lib.types.submodule { type = types.path;
options = { default = "/var/lib/headplane";
authkey_path = lib.mkOption { description = ''
type = lib.types.nullOr lib.types.path; The path to persist Headplane specific data.
default = null; All data going forward is stored in this directory, including the internal database and any cache related files.
description = '' Data formats prior to 0.6.1 will automatically be migrated.
Path to a file containing the agent auth key. '';
''; example = "/var/lib/headplane";
example = "config.sops.secrets.agent_authkey.path";
};
ttl = lib.mkOption {
type = lib.types.int;
default = 180000;
description = "How long to cache agent information (in milliseconds).";
};
cache_path = lib.mkOption {
type = lib.types.str;
default = "/var/lib/headplane/agent_cache.json";
description = "Where to store the agent cache.";
};
};
};
default = {};
description = "Agent configuration for the Headplane agent.";
}; };
}; };
}; };
@ -115,11 +95,11 @@ in {
description = "Server configuration for Headplane web application."; description = "Server configuration for Headplane web application.";
}; };
headscale = lib.mkOption { headscale = mkOption {
type = lib.types.submodule { type = types.submodule {
options = { options = {
url = lib.mkOption { url = mkOption {
type = lib.types.str; type = types.str;
default = "http://127.0.0.1:8080"; default = "http://127.0.0.1:8080";
description = '' description = ''
The URL to your Headscale instance. The URL to your Headscale instance.
@ -130,8 +110,8 @@ in {
example = "https://headscale.example.com"; example = "https://headscale.example.com";
}; };
tls_cert_path = lib.mkOption { tls_cert_path = mkOption {
type = lib.types.nullOr lib.types.path; type = types.nullOr types.path;
default = null; default = null;
description = '' description = ''
Path to a file containing the TLS certificate. Path to a file containing the TLS certificate.
@ -139,17 +119,15 @@ in {
example = "config.sops.secrets.tls_cert.path"; example = "config.sops.secrets.tls_cert.path";
}; };
tls_key_path = lib.mkOption { public_url = mkOption {
type = lib.types.nullOr lib.types.path; type = types.nullOr types.str;
default = null; default = null;
description = '' description = "Public URL if differrent. This affects certain parts of the web UI.";
Path to a file containing the TLS private key. example = "https://headscale.example.com";
'';
example = "config.sops.secrets.tls_key.path";
}; };
config_path = lib.mkOption { config_path = mkOption {
type = lib.types.nullOr lib.types.path; type = types.nullOr types.path;
default = null; default = null;
description = '' description = ''
Path to the Headscale configuration file. Path to the Headscale configuration file.
@ -160,8 +138,8 @@ in {
example = "/etc/headscale/config.yaml"; example = "/etc/headscale/config.yaml";
}; };
config_strict = lib.mkOption { config_strict = mkOption {
type = lib.types.bool; type = types.bool;
default = true; default = true;
description = '' description = ''
Headplane internally validates the Headscale configuration Headplane internally validates the Headscale configuration
@ -169,20 +147,93 @@ in {
If you want to disable this validation, set this to false. If you want to disable this validation, set this to false.
''; '';
}; };
dns_records_path = mkOption {
type = types.nullOr types.path;
default = null;
description = ''
If you are using `dns.extra_records_path` in your Headscale configuration, you need to set this to the path for Headplane to be able to read the DNS records.
Ensure that the file is both readable and writable by the Headplane process.
When using this, Headplane will no longer need to automatically restart Headscale for DNS record changes.
'';
example = "/var/lib/headplane/extra_records.json";
};
}; };
}; };
default = {}; default = {};
description = "Headscale specific settings for Headplane integration."; description = "Headscale specific settings for Headplane integration.";
}; };
integration = lib.mkOption { integration = mkOption {
type = lib.types.submodule { type = types.submodule {
options = { options = {
proc = lib.mkOption { agent = mkOption {
type = lib.types.submodule { type = types.submodule {
options = { options = {
enabled = lib.mkOption { enabled = mkOption {
type = lib.types.bool; type = types.bool;
default = false;
description = ''
The Headplane agent allows retrieving information about nodes.
This allows the UI to display version, OS, and connectivity data.
You will see the Headplane agent in your Tailnet as a node when it connects.
'';
};
pre_authkey_path = mkOption {
type = types.nullOr types.path;
default = null;
description = ''
Path to a file containing the agent preauth key.
To connect to your Tailnet, you need to generate a pre-auth key.
This can be done via the web UI or through the `headscale` CLI.
'';
example = "config.sops.secrets.agent_pre_authkey.path";
};
host_name = mkOption {
type = types.str;
default = "headplane-agent";
description = "Optionally change the name of the agent in the Tailnet";
};
cache_ttl = mkOption {
type = types.int;
default = 180000;
description = ''
How long to cache agent information (in milliseconds).
If you want data to update faster, reduce the TTL, but this will increase the frequency of requests to Headscale.
'';
};
cache_path = mkOption {
type = types.path;
default = "/var/lib/headplane/agent_cache.json";
description = "Where to store the agent cache.";
};
work_dir = mkOption {
type = types.path;
default = "/var/lib/headplane/agent";
description = ''
Do not change this unless you are running a custom deployment.
The work_dir represents where the agent will store its data to be able to automatically reauthenticate with your Tailnet.
It needs to be writable by the user running the Headplane process.
'';
};
package = mkPackageOption pkgs "headplane-agent" {};
};
};
default = {};
description = "Agent configuration for the Headplane agent.";
};
proc = mkOption {
type = types.submodule {
options = {
enabled = mkOption {
type = types.bool;
default = true; default = true;
description = '' description = ''
Enable "Native" integration that works when Headscale and Enable "Native" integration that works when Headscale and
@ -202,25 +253,25 @@ in {
description = "Integration configurations for Headplane to interact with Headscale."; description = "Integration configurations for Headplane to interact with Headscale.";
}; };
oidc = lib.mkOption { oidc = mkOption {
type = lib.types.submodule { type = types.submodule {
options = { options = {
issuer = lib.mkOption { issuer = mkOption {
type = lib.types.str; type = types.str;
default = ""; default = "";
description = "URL to OpenID issuer."; description = "URL to OpenID issuer.";
example = "https://provider.example.com/issuer-url"; example = "https://provider.example.com/issuer-url";
}; };
client_id = lib.mkOption { client_id = mkOption {
type = lib.types.str; type = types.str;
default = ""; default = "";
description = "The client ID for the OIDC client."; description = "The client ID for the OIDC client.";
example = "your-client-id"; example = "your-client-id";
}; };
client_secret_path = lib.mkOption { client_secret_path = mkOption {
type = lib.types.nullOr lib.types.path; type = types.nullOr types.path;
default = null; default = null;
description = '' description = ''
Path to a file containing the OIDC client secret. Path to a file containing the OIDC client secret.
@ -228,23 +279,24 @@ in {
example = "config.sops.secrets.oidc_client_secret.path"; example = "config.sops.secrets.oidc_client_secret.path";
}; };
disable_api_key_login = lib.mkOption { disable_api_key_login = mkOption {
type = lib.types.bool; type = types.bool;
default = false; default = false;
description = "Whether to disable API key login."; description = "Whether to disable API key login.";
}; };
token_endpoint_auth_method = lib.mkOption { token_endpoint_auth_method = mkOption {
type = lib.types.enum [ type = types.enum [
"client_secret_post" "client_secret_post"
"client_secret_basic" "client_secret_basic"
"client_secret_jwt"
]; ];
default = "client_secret_post"; default = "client_secret_post";
description = "The token endpoint authentication method."; description = "The token endpoint authentication method.";
}; };
headscale_api_key_path = lib.mkOption { headscale_api_key_path = mkOption {
type = lib.types.nullOr lib.types.path; type = types.nullOr types.path;
default = null; default = null;
description = '' description = ''
Path to a file containing the Headscale API key. Path to a file containing the Headscale API key.
@ -252,8 +304,8 @@ in {
example = "config.sops.secrets.headscale_api_key.path"; example = "config.sops.secrets.headscale_api_key.path";
}; };
redirect_uri = lib.mkOption { redirect_uri = mkOption {
type = lib.types.str; type = types.str;
default = ""; default = "";
description = '' description = ''
This should point to your publicly accessible URL This should point to your publicly accessible URL
@ -261,6 +313,15 @@ in {
''; '';
example = "https://headscale.example.com/admin/oidc/callback"; example = "https://headscale.example.com/admin/oidc/callback";
}; };
user_storage_file = mkOption {
type = types.path;
default = "/var/lib/headplane/users.json";
description = ''
Path to a file containing the users and their permissions for Headplane.
'';
example = "/var/lib/headplane/users.json";
};
}; };
}; };
default = {}; default = {};
@ -270,20 +331,6 @@ in {
}; };
default = {}; default = {};
}; };
agent = mkOption {
type = types.submodule {
options = {
enable = mkEnableOption "headplane-agent";
package = mkPackageOption pkgs "headplane-agent" {};
settings = mkOption {
type = types.attrsOf [types.str types.bool];
description = "Headplane agent env vars config. See: https://github.com/tale/headplane/blob/main/docs/Headplane-Agent.md";
default = {};
};
};
};
};
}; };
config = mkIf cfg.enable { config = mkIf cfg.enable {
@ -292,30 +339,6 @@ in {
etc."headplane/config.yaml".source = "${settingsFile}"; etc."headplane/config.yaml".source = "${settingsFile}";
}; };
systemd.services.headplane-agent =
mkIf cfg.agent.enable
{
description = "Headplane side-running agent";
wantedBy = ["multi-user.target"];
after = ["headplane.service"];
requires = ["headplane.service"];
environment = agentEnv;
serviceConfig = {
User = config.services.headscale.user;
Group = config.services.headscale.group;
ExecStart = "${pkgs.headplane-agent}/bin/hp_agent";
Restart = "always";
RestartSec = 5;
# TODO: Harden `systemd` security according to the "The Principle of Least Power".
# See: `$ systemd-analyze security headplane-agent`.
};
};
systemd.services.headplane = { systemd.services.headplane = {
description = "Headscale Web UI"; description = "Headscale Web UI";