From a5e2af9b3000de908ba659be192be5598a092247 Mon Sep 17 00:00:00 2001 From: Aarnav Tale Date: Sun, 29 Mar 2026 20:30:53 -0400 Subject: [PATCH] docs: update some option docs --- docs/CONTRIBUTING.md | 2 +- docs/NixOS-options.md | 50 ++++++++++++++++++++++--------------------- nix/options.nix | 38 +++++++++++++++++--------------- 3 files changed, 48 insertions(+), 42 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 1a6d747..48b5d2f 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -42,7 +42,7 @@ for me to review and merge your contributions. This is very easy and self-explanatory. [oxlint/oxfmt](https://oxc.rs) is used as a linter and formatter for the TypeScript, while Go's default formatting and -lint tooling are used within `agent/` code. I've setup a git hook to run +lint tooling are used within `cmd/` code. I've setup a git hook to run before commit to make these changes automatically. > All of these guidelines are fairly simple to follow and are flexible if needed. diff --git a/docs/NixOS-options.md b/docs/NixOS-options.md index fabbfb5..31cb5b8 100644 --- a/docs/NixOS-options.md +++ b/docs/NixOS-options.md @@ -47,6 +47,17 @@ _Type:_ submodule _Default:_ `{ }` +## settings.headscale.api_key_path + +_Description:_ Path to a file containing the Headscale API key. +Required for OIDC authentication and the Headplane agent. + +_Type:_ null or absolute path + +_Default:_ `null` + +_Example:_ `"config.sops.secrets.headscale_api_key.path"` + ## settings.headscale.config_path _Description:_ Path to the Headscale configuration file. @@ -131,14 +142,6 @@ _Type:_ submodule _Default:_ `{ }` -## settings.integration.agent.cache_path - -_Description:_ Where to store the agent cache. - -_Type:_ absolute path - -_Default:_ `"/var/lib/headplane/agent_cache.json"` - ## settings.integration.agent.cache_ttl _Description:_ How long to cache agent information (in milliseconds). @@ -150,14 +153,24 @@ _Default:_ `180000` ## settings.integration.agent.enabled -_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. +_Description:_ The Headplane agent periodically syncs node information (version, OS, etc.) +from your Tailnet. It auto-generates ephemeral pre-auth keys using +headscale.api_key, so no manual key configuration is needed. +Requires Headscale 0.28 or newer. _Type:_ boolean _Default:_ `false` +## settings.integration.agent.executable_path + +_Description:_ Path to the Headplane agent binary. +The default is correct if using the NixOS module package. + +_Type:_ absolute path + +_Default:_ `"/usr/libexec/headplane/agent"` + ## settings.integration.agent.host_name _Description:_ Optionally change the name of the agent in the Tailnet @@ -174,18 +187,6 @@ _Type:_ package _Default:_ `pkgs.headplane-agent` -## settings.integration.agent.pre_authkey_path - -_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. - -_Type:_ null or absolute path - -_Default:_ `null` - -_Example:_ `"config.sops.secrets.agent_pre_authkey.path"` - ## settings.integration.agent.work_dir _Description:_ Do not change this unless you are running a custom deployment. @@ -253,7 +254,8 @@ _Default:_ `false` ## settings.oidc.headscale_api_key_path -_Description:_ Path to a file containing the Headscale API key. +_Description:_ DEPRECATED: Use `headscale.api_key_path` instead. +Path to a file containing the Headscale API key. _Type:_ null or absolute path diff --git a/nix/options.nix b/nix/options.nix index b53dd9e..35df7dc 100644 --- a/nix/options.nix +++ b/nix/options.nix @@ -166,6 +166,16 @@ in { ''; }; + api_key_path = mkOption { + type = types.nullOr types.path; + default = null; + description = '' + Path to a file containing the Headscale API key. + Required for OIDC authentication and the Headplane agent. + ''; + example = "config.sops.secrets.headscale_api_key.path"; + }; + dns_records_path = mkOption { type = types.nullOr types.path; default = null; @@ -192,23 +202,13 @@ in { 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. + The Headplane agent periodically syncs node information (version, OS, etc.) + from your Tailnet. It auto-generates ephemeral pre-auth keys using + headscale.api_key, so no manual key configuration is needed. + Requires Headscale 0.28 or newer. ''; }; - 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"; @@ -224,10 +224,13 @@ in { ''; }; - cache_path = mkOption { + executable_path = mkOption { type = types.path; - default = "/var/lib/headplane/agent_cache.json"; - description = "Where to store the agent cache."; + default = "/usr/libexec/headplane/agent"; + description = '' + Path to the Headplane agent binary. + The default is correct if using the NixOS module package. + ''; }; work_dir = mkOption { @@ -338,6 +341,7 @@ in { type = types.nullOr types.path; default = null; description = '' + DEPRECATED: Use headscale.api_key_path instead. Path to a file containing the Headscale API key. ''; example = "config.sops.secrets.headscale_api_key.path";