gsadmin/headplane
1
0
Fork 0
mirror of https://github.com/tale/headplane.git synced 2026-07-26 07:48:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update some option docs

Browse Source
This commit is contained in:
Aarnav Tale
2026-03-29 20:30:53 -04:00
parent 9ac3ab1861
commit a5e2af9b30
3 changed files with 48 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CONTRIBUTING.md
+1 -1
View File
@@ -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.
docs/NixOS-options.md
+26 -24
View File
@@ -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
nix/options.nix
+21 -17
View File
@@ -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";