gsadmin/headplane
1
0
Fork 0
mirror of https://github.com/tale/headplane.git synced 2026-08-05 19:57:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: switch agent to a periodic dump rather than long running process

Browse Source
This commit is contained in:
Aarnav Tale
2026-03-27 13:19:16 -04:00
parent 2c57187628
commit ee59a2d06d
17 changed files with 521 additions and 464 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/agent.md
+23 -10
View File
@@ -10,9 +10,21 @@ description: Configure the Headplane Agent for enhanced functionality.
<figcaption>SSH access via the browser</figcaption>
</figure>
The Headplane Agent is an optional component that can be enabled on your
Headplane instance in order to unlock additional features such as remote
web-based SSH and detailed machine information.
The Headplane Agent is an optional component that periodically syncs node
information (such as version and OS details) from the Tailnet. Unlike previous
versions, the agent no longer runs as a persistent Tailnet node — it
auto-generates pre-auth keys and performs periodic syncs instead.
## Prerequisites
Before enabling the agent, ensure the following:
1. **Headscale 0.28 or newer** is required. The agent uses tag-only pre-auth
keys which are only available in Headscale 0.28+.
2. **`headscale.api_key`** must be set in your Headplane configuration file.
The agent uses this key to auto-generate ephemeral pre-auth keys for
connecting to the Tailnet.
## Configuration
@@ -22,15 +34,16 @@ please refer to the
[example configuration](https://github.com/tale/headplane/blob/main/config.example.yaml)
for details.
| Field | Description |
|---------------------|--------------------------------------------------------|
| **`integration.agent.enabled`** | Set to `true` to enable the agent. |
| **`integration.agent.pre_authkey`** | A reusable pre-auth-key (see below). |
| `integration.agent.host_name` | *Optional*. Host name to register as. |
| `integration.agent.cache_path` | *Optional*. Cache path for the agent. |
| `integration.agent.work_dir` | *Optional*. Working directory for the agent. |
| Field | Description |
| ----------------------------------- | ------------------------------------------------------------------------------- |
| **`integration.agent.enabled`** | Set to `true` to enable the agent. |
| `integration.agent.host_name` | _Optional_. Headscale user name for the agent (default: `headplane-agent`). |
| `integration.agent.cache_ttl` | _Optional_. How often to sync in milliseconds (default: `180000` / 3 minutes). |
| `integration.agent.work_dir` | _Optional_. Working directory for the agent's tailnet state. |
| `integration.agent.executable_path` | _Optional_. Path to the agent binary (default: `/usr/libexec/headplane/agent`). |
## Native Mode Configuration
Once you've built Headplane locally, there will be a binary in the `./build`
folder called `hp_agent`. Please move this binary to
`/usr/libexec/headplane/agent` and ensure that it is executable.
docs/features/sso.md
+5 -2
View File
@@ -54,8 +54,11 @@ To enable OIDC authentication in Headplane, add the following to your
configuration file:
```yaml
headscale:
url: "http://headscale:8080"
api_key: "<generated-api-key>"
oidc:
headscale_api_key: "<generated-api-key>"
issuer: "https://your-idp.com"
client_id: "your-client-id"
client_secret: "your-client-secret"
@@ -211,7 +214,7 @@ flow can be skipped. Once completed, users are taken to the main dashboard.
setting. If Headplane is behind a reverse proxy with HTTPS, set it to `true`.
If running without HTTPS (eg. local development), set it to `false`.
- **Invalid API Key**: The `oidc.headscale_api_key` may have expired. Generate
- **Invalid API Key**: The `headscale.api_key` may have expired. Generate
a new one with `headscale apikeys create --expiration 999d`.
- **Missing the `sub` claim**: Ensure your IdP includes the `sub` claim in the