1
0
mirror of https://github.com/juanfont/headscale.git synced 2024-12-30 11:47:50 +00:00
headscale/docs/remote-cli.md

101 lines
3.3 KiB
Markdown
Raw Permalink Normal View History

2022-01-25 22:11:15 +00:00
# Controlling `headscale` with remote CLI
## Prerequisite
2022-01-25 22:11:15 +00:00
- 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
2022-01-25 22:11:15 +00:00
- Remote access does _not_ support unencrypted traffic.
- Port `50443` must be open in the firewall (or port overridden by `grpc_listen_addr` option)
2022-01-25 22:11:15 +00:00
## Goal
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.
2022-01-25 22:11:15 +00:00
## Create an API key
2022-01-25 22:11:15 +00:00
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
```
2022-05-07 16:23:26 -04:00
Copy the output of the command and save it for later. Please note that you can not retrieve a key again,
2022-01-25 22:11:15 +00:00
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):
2. Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headscale`
2022-01-25 22:11:15 +00:00
3. Make `headscale` executable:
2024-09-04 07:55:16 +02:00
```shell
chmod +x /usr/local/bin/headscale
```
2022-01-25 22:11:15 +00:00
4. Configure the CLI through environment variables
2022-01-25 22:11:15 +00:00
2024-09-04 07:55:16 +02:00
```shell
export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:<PORT>"
export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
```
2022-01-25 22:11:15 +00:00
2024-09-04 07:55:16 +02:00
for example:
2022-02-12 19:08:59 +00:00
2024-09-04 07:55:16 +02:00
```shell
export HEADSCALE_CLI_ADDRESS="headscale.example.com:50443"
export HEADSCALE_CLI_API_KEY="abcde12345"
```
2022-02-12 19:08:59 +00:00
2024-09-04 07:55:16 +02:00
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).
2022-01-25 22:11:15 +00:00
2024-09-04 07:55:16 +02:00
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.
2022-01-25 22:11:15 +00:00
5. Test the connection
2024-09-04 07:55:16 +02:00
Let us run the headscale command to verify that we can connect by listing our nodes:
2022-01-25 22:11:15 +00:00
2024-09-04 07:55:16 +02:00
```shell
headscale nodes list
```
2022-01-25 22:11:15 +00:00
2024-09-04 07:55:16 +02:00
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.
2022-01-25 22:11:15 +00:00
## 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).
2022-01-25 22:11:15 +00:00
## 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