2.8 KiB
Controlling headscale
with remote CLI
Prerequisit
- A workstation to run
headscale
(could be Linux, macOS, other supported platforms) - A
headscale
server (version0.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 overriden bygrpc_listen_addr
option)
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.
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 not 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/headcale
-
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 your 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.
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.