mirror of
https://github.com/juanfont/headscale.git
synced 2024-12-20 19:09:07 +01:00
8c7d8ee34f
* 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
99 lines
3.3 KiB
Markdown
99 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
```shell
|
|
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:
|
|
|
|
```shell
|
|
headscale apikeys list
|
|
```
|
|
|
|
and to expire a key:
|
|
|
|
```shell
|
|
headscale apikeys expire --prefix "<PREFIX>"
|
|
```
|
|
|
|
## Download and configure headscale
|
|
|
|
1. Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases):
|
|
|
|
1. Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headscale`
|
|
|
|
1. Make `headscale` executable:
|
|
|
|
```shell
|
|
chmod +x /usr/local/bin/headscale
|
|
```
|
|
|
|
1. Configure the CLI through environment variables
|
|
|
|
```shell
|
|
export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:<PORT>"
|
|
export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
|
|
```
|
|
|
|
for example:
|
|
|
|
```shell
|
|
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.
|
|
|
|
1. Test the connection
|
|
|
|
Let us run the headscale command to verify that we can connect by listing our nodes:
|
|
|
|
```shell
|
|
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](https://github.com/kradalby/dotfiles/blob/4489cdbb19cddfbfae82cd70448a38fde5a76711/machines/headscale.oracldn/headscale.nix#L61-L91).
|
|
|
|
## 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
|