mirror of https://github.com/juanfont/headscale.git synced 2024-12-20 19:09:07 +01:00

Restructure headscale documentation (#2163 )

* Setup mkdocs-redirects

* Restructure existing documentation

* Move client OS support into the documentation

* Move existing Client OS support table into its own documentation page
* Link from README.md to the rendered documentation
* Document minimum Tailscale client version

* Reuse CONTRIBUTING.md" in the documentation

* Include "CONTRIBUTING.md" from the repository root
* Update FAQ and index page and link to the contributing docs

* Add configuration reference

* Add a getting started page and explain the first steps with headscale

* Use the existing "Using headscale" sections and combine them into a
  single getting started guide with a little bit more explanation.
* Explain how to get help from the command line client.
* Remove duplicated sections from existing installation guides

* Document requirements and assumptions

* Document packages provided by the community

* Move deb install guide to official releases

* Move manual install guide to official releases

* Move container documentation to setup section

* Move sealos documentation to cloud install page

* Move OpenBSD docs to build from source

* Simplify DNS documentation

* Add sponsor page

* Add releases page

* Add features page

* Add help page

* Add upgrading page

* Adjust mkdocs nav

* Update wording

Use the term headscale for the project, Headscale on the beginning of a
sentence and `headscale` when refering to the CLI.

* Welcome to headscale

* Link to existing documentation in the FAQ

* Remove the goal header and use the text as opener

* Indent code block in OIDC

* Make a few pages linter compatible

Also update ignored files for prettier

* Recommend HTTPS on port 443

Fixes: #2164

* Use hosts in acl documentation

thx @efficacy38 for noticing this

Ref: #1863

* Use mkdocs-macros to set headscale version once

2024-10-10 15:24:04 +02:00

3.3 KiB

Raw Blame History

Controlling headscale with remote CLI

This documentation has the goal of showing a user how-to set control a headscale instance from a remote machine with the headscale command line binary.

Prerequisite

A workstation to run headscale (could be Linux, macOS, other supported platforms)
A headscale server (version 0.13.0 or newer)
Access to create API keys (local access to the headscale server)
headscale must be served over TLS/HTTPS
- Remote access does not support unencrypted traffic.
Port 50443 must be open in the firewall (or port overridden by grpc_listen_addr option)

Create an API key

We need to create an API key to authenticate our remote headscale when using it from our workstation.

To create a API key, log into your headscale server and generate a key:

headscale apikeys create --expiration 90d

Copy the output of the command and save it for later. Please note that you can not retrieve a key again, if the key is lost, expire the old one, and create a new key.

To list the keys currently assosicated with the server:

headscale apikeys list

and to expire a key:

headscale apikeys expire --prefix "<PREFIX>"

Download and configure headscale

Download the latest headscale binary from GitHub's release page:
Put the binary somewhere in your PATH, e.g. /usr/local/bin/headscale
Make headscale executable:
```
chmod +x /usr/local/bin/headscale
```
Configure the CLI through environment variables
```
export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:<PORT>"
export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
```
for example:
```
export HEADSCALE_CLI_ADDRESS="headscale.example.com:50443"
export HEADSCALE_CLI_API_KEY="abcde12345"
```
This will tell the headscale binary to connect to a remote instance, instead of looking for a local instance (which is what it does on the server).

The API key is needed to make sure that you are allowed to access the server. The key is not needed when running directly on the server, as the connection is local.
Test the connection

Let us run the headscale command to verify that we can connect by listing our nodes:
```
headscale nodes list
```
You should now be able to see a list of your nodes from your workstation, and you can now control the headscale server from your workstation.

Behind a proxy

It is 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.

Troubleshooting

Checklist:

Make sure you have the same headscale version on your server and workstation
Make sure you use version 0.13.0 or newer.
Verify that your TLS certificate is valid and trusted
- If you do not have access to a trusted certificate (e.g. from Let's Encrypt), add your self signed certificate to the trust store of your OS or
- Set HEADSCALE_CLI_INSECURE to 0 in your environment

3.3 KiB Raw Blame History