public/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-07-08 00:50:20 +09:00
Code Issues Packages Projects Releases Wiki Activity

docs: add changelog and refresh the API reference for the v1 API

Browse Source
This commit is contained in:
Kristoffer Dalby
2026-06-19 06:14:55 +00:00
parent 560b6d81ad
commit 72adc5ff2a
6 changed files with 46 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ref/api.md
+13 -16
View File
@@ -1,10 +1,10 @@
# API
Headscale provides a [HTTP REST API](#rest-api) and a [gRPC interface](#grpc) which may be used to integrate a [web
interface](integration/web-ui.md), [remote control Headscale](#setup-remote-control) or provide a base for custom
Headscale provides a [HTTP REST API](#rest-api) which may be used to integrate a [web
interface](integration/web-ui.md), [remote control Headscale](#remote-control) or provide a base for custom
integration and tooling.
Both interfaces require a valid API key before use. To create an API key, log into your Headscale server and generate
The API requires a valid API key before use. To create an API key, log into your Headscale server and generate
one with the default expiration of 90 days:
```shell
@@ -58,15 +58,14 @@ Headscale server at `/swagger` for details.
https://headscale.example.com/api/v1/auth/register
```
## gRPC
## Remote control
The gRPC interface can be used to control a Headscale instance from a remote machine with the `headscale` binary.
The `headscale` binary can control a Headscale instance from a remote machine over the HTTP API.
### Prerequisite
- A workstation to run `headscale` (any supported platform, e.g. Linux).
- A Headscale server with gRPC enabled.
- Connections to the gRPC port (default: `50443`) are allowed.
- The Headscale server reachable over HTTP(S).
- Remote access requires an encrypted connection via TLS.
- An [API key](#api) to authenticate with the Headscale server.
@@ -88,19 +87,20 @@ The gRPC interface can be used to control a Headscale instance from a remote mac
```yaml title="config.yaml"
cli:
address: <HEADSCALE_ADDRESS>:<PORT>
address: <HEADSCALE_URL>
api_key: <API_KEY>
```
=== "Environment variables"
```shell
export HEADSCALE_CLI_ADDRESS="<HEADSCALE_ADDRESS>:<PORT>"
export HEADSCALE_CLI_ADDRESS="<HEADSCALE_URL>"
export HEADSCALE_CLI_API_KEY="<API_KEY>"
```
This instructs the `headscale` binary to connect to a remote instance at `<HEADSCALE_ADDRESS>:<PORT>`, instead of
connecting to the local instance.
This instructs the `headscale` binary to connect to a remote instance at `<HEADSCALE_URL>` (e.g.
`https://headscale.example.com`), instead of connecting to the local instance. A bare host without a scheme is
assumed to be `https`.
1. Test the connection by listing all nodes:
@@ -113,15 +113,12 @@ The gRPC interface can be used to control a Headscale instance from a remote mac
### Behind a proxy
It's possible to run the gRPC remote endpoint behind a reverse proxy, like Nginx, and have it run on the _same_ port as Headscale.
While this is _not a supported_ feature, an example on how this can be set up on
[NixOS is shown here](https://github.com/kradalby/dotfiles/blob/4489cdbb19cddfbfae82cd70448a38fde5a76711/machines/headscale.oracldn/headscale.nix#L61-L91).
The remote CLI uses the same HTTP API as everything else, so it works through the reverse proxy already in front of
Headscale with no extra setup.
### Troubleshooting
- Make sure you have the _same_ Headscale version on your server and workstation.
- Ensure that connections to the gRPC port are allowed.
- Verify that your TLS certificate is valid and trusted.
- If you don't have access to a trusted certificate (e.g. from Let's Encrypt), either:
- Add your self-signed certificate to the trust store of your OS _or_
docs/ref/integration/reverse-proxy.md
+1 -4
View File
@@ -69,7 +69,6 @@ on inbound requests with sanitized values. Headscale picks the first valid IP ad
- A reverse proxy adds another layer of complexity that needs to be able to handle the [Tailscale Control
Protocol](#websocket) properly. Be sure to test your setup without a reverse proxy before raising an issue.
- STUN (used along with the [embedded DERP server](../derp.md)) requires udp/3478 to be served publicly.
- [gRPC](../api.md#grpc) (used to remote control Headscale) may not be proxied.
## Reverse proxy specific configuration
@@ -84,14 +83,12 @@ is [assumed](../../setup/requirements.md):
- Service for Tailscale clients is served via HTTPS on port 443.
- The reverse proxy redirects HTTP to HTTPS and is terminating TLS.
- Both Headscale and the reverse proxy are running on the same host.
- [Metrics](../debug.md#metrics-and-debug-endpoint) and [gRPC](../api.md#grpc) are not proxied, those are available via
localhost.
- [Metrics](../debug.md#metrics-and-debug-endpoint) are not proxied, those are available via localhost.
```yaml title="config.yaml" hl_lines="1"
server_url: https://<SERVER_NAME>
listen_addr: 127.0.0.1:8080
metrics_listen_addr: 127.0.0.1:9090
grpc_listen_addr: 127.0.0.1:50443
trusted_proxies:
- 127.0.0.1/32
- ::1/128