devproje/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2024-11-26 08:53:05 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Update documentation for 0.23 (#2096)

Browse source 
* docs/acl: fix path to policy file

* docs/exit-node: fixup for 0.23

* Add newlines between commands to improve readability
* Use nodes instead on name
* Remove query parameter from link to Tailscale docs

* docs/remote-cli: fix formatting

* Indent blocks below line numbers to restore numbering
* Fix minor typos

* docs/reverse-proxy: remove version information

* Websocket support is always required now
* s/see detail/see details

* docs/exit-node: add warning to manual documentation

* Replace the warning section with a warning admonition
* Fix TODO link back to the regular linux documentation

* docs/openbsd: fix typos

* the database is created on-the-fly

* docs/sealos: fix typos

* docs/container: various fixes

* Remove a stray sentence
* Remove "headscale" before serve
* Indent line continuation
* Replace hardcoded 0.22 with <VERSION>
* Fix path in debug image to /ko-app/headscale

Fixes: #1822

aa
This commit is contained in:
nblock 2024-09-03 13:04:20 +02:00 committed by GitHub
parent 3101f895a7
commit d66c5e144f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 58 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/acls.md
View file

@ -52,7 +52,7 @@ a server they can register, the check of the tags is done on headscale server
and only valid tags are applied. A tag is valid if the user that is and only valid tags are applied. A tag is valid if the user that is
registering it is allowed to do it. registering it is allowed to do it.
To use ACLs in headscale, you must edit your config.yaml file. In there you will find a `acl_policy_path: ""` parameter. This will need to point to your ACL file. More info on how these policies are written can be found [here](https://tailscale.com/kb/1018/acls/). To use ACLs in headscale, you must edit your `config.yaml` file. In there you will find a `policy.path` parameter. This will need to point to your ACL file. More info on how these policies are written can be found [here](https://tailscale.com/kb/1018/acls/).
Here are the ACL's to implement the same permissions as above: Here are the ACL's to implement the same permissions as above:

24
docs/exit-node.md
View file

@ -21,21 +21,23 @@ To use a node as an exit node, IP forwarding must be enabled on the node. Check
```console ```console
$ # list nodes $ # list nodes
$ headscale routes list $ headscale routes list
ID | Machine | Prefix | Advertised | Enabled | Primary ID | Node | Prefix | Advertised | Enabled | Primary
1 | | 0.0.0.0/0 | false | false | - 1 | | 0.0.0.0/0 | false | false | -
2 | | ::/0 | false | false | - 2 | | ::/0 | false | false | -
3 | phobos | 0.0.0.0/0 | true | false | - 3 | phobos | 0.0.0.0/0 | true | false | -
4 | phobos | ::/0 | true | false | - 4 | phobos | ::/0 | true | false | -
$ # enable routes for phobos $ # enable routes for phobos
$ headscale routes enable -r 3 $ headscale routes enable -r 3
$ headscale routes enable -r 4 $ headscale routes enable -r 4
$ # Check node list again. The routes are now enabled. $ # Check node list again. The routes are now enabled.
$ headscale routes list $ headscale routes list
ID | Machine | Prefix | Advertised | Enabled | Primary ID | Node | Prefix | Advertised | Enabled | Primary
1 | | 0.0.0.0/0 | false | false | - 1 | | 0.0.0.0/0 | false | false | -
2 | | ::/0 | false | false | - 2 | | ::/0 | false | false | -
3 | phobos | 0.0.0.0/0 | true | true | - 3 | phobos | 0.0.0.0/0 | true | true | -
4 | phobos | ::/0 | true | true | - 4 | phobos | ::/0 | true | true | -
``` ```
## On the client ## On the client
@ -46,4 +48,4 @@ The exit node can now be used with:
$ sudo tailscale set --exit-node phobos $ sudo tailscale set --exit-node phobos
``` ```
Check the official [Tailscale documentation](https://tailscale.com/kb/1103/exit-nodes/?q=exit#step-3-use-the-exit-node) for how to do it on your device. Check the official [Tailscale documentation](https://tailscale.com/kb/1103/exit-nodes#use-the-exit-node) for how to do it on your device.

46
docs/remote-cli.md
View file

@ -47,40 +47,40 @@ headscale apikeys expire --prefix "<PREFIX>"
3. Make `headscale` executable: 3. Make `headscale` executable:
```shell ```shell
chmod +x /usr/local/bin/headscale chmod +x /usr/local/bin/headscale
``` ```
4. Configure the CLI through Environment Variables 4. Configure the CLI through environment variables
```shell ```shell
export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:<PORT>" export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:<PORT>"
export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>" export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
``` ```
for example: for example:
```shell ```shell
export HEADSCALE_CLI_ADDRESS="headscale.example.com:50443" export HEADSCALE_CLI_ADDRESS="headscale.example.com:50443"
export HEADSCALE_CLI_API_KEY="abcde12345" export HEADSCALE_CLI_API_KEY="abcde12345"
``` ```
This will tell the `headscale` binary to connect to a remote instance, instead of looking 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). 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_ 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. needed when running directly on the server, as the connection is local.
5. Test the connection 5. Test the connection
Let us run the headscale command to verify that we can connect by listing our nodes: Let us run the headscale command to verify that we can connect by listing our nodes:
```shell ```shell
headscale nodes list headscale nodes list
``` ```
You should now be able to see a list of your nodes from your workstation, and you can 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. now control the `headscale` server from your workstation.
## Behind a proxy ## Behind a proxy

6
docs/reverse-proxy.md
View file

@ -11,9 +11,9 @@ Running headscale behind a reverse proxy is useful when running multiple applica
### WebSockets ### WebSockets
The reverse proxy MUST be configured to support WebSockets, as it is needed for clients running Tailscale v1.30+. The reverse proxy MUST be configured to support WebSockets to communicate with Tailscale clients.
WebSockets support is required when using the headscale embedded DERP server. In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our [config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml). WebSockets support is also required when using the headscale embedded DERP server. In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our [config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml).
### Cloudflare ### Cloudflare
@ -80,7 +80,7 @@ Sending local reply with details upgrade_failed
### Envoy ### Envoy
You need add a new upgrade_type named `tailscale-control-protocol`. [see detail](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-upgradeconfig) You need to add a new upgrade_type named `tailscale-control-protocol`. [see details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-upgradeconfig)
### Istio ### Istio

27
docs/running-headscale-container.md
View file

@ -22,12 +22,6 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca
cd ./headscale cd ./headscale
``` ```
1. Create an empty SQlite datebase in the headscale directory:
```shell
touch ./config/db.sqlite
```
1. **(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository. 1. **(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository.
- Using `wget`: - Using `wget`:
@ -43,7 +37,6 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca
``` ```
Modify the config file to your preferences before launching Docker container. Modify the config file to your preferences before launching Docker container.
Here are some settings that you likely want:
Alternatively, you can mount `/var/lib` and `/var/run` from your host system by adding Alternatively, you can mount `/var/lib` and `/var/run` from your host system by adding
`--volume $(pwd)/lib:/var/lib/headscale` and `--volume $(pwd)/run:/var/run/headscale` `--volume $(pwd)/lib:/var/lib/headscale` and `--volume $(pwd)/run:/var/run/headscale`
@ -59,7 +52,7 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca
--publish 127.0.0.1:8080:8080 \ --publish 127.0.0.1:8080:8080 \
--publish 127.0.0.1:9090:9090 \ --publish 127.0.0.1:9090:9090 \
headscale/headscale:<VERSION> \ headscale/headscale:<VERSION> \
headscale serve serve
``` ```
Note: use `0.0.0.0:8080:8080` instead of `127.0.0.1:8080:8080` if you want to expose the container externally. Note: use `0.0.0.0:8080:8080` instead of `127.0.0.1:8080:8080` if you want to expose the container externally.
@ -74,16 +67,16 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca
services: services:
headscale: headscale:
image: headscale/headscale:0.22.3 image: headscale/headscale:<VERSION>
restart: unless-stopped restart: unless-stopped
container_name: headscale container_name: headscale
ports: ports:
- "127.0.0.1:8080:8080" - "127.0.0.1:8080:8080"
- "127.0.0.1:9090:9090" - "127.0.0.1:9090:9090"
volumes: volumes:
# pls change [config_path] to the fullpath of the config folder just created # Please change <CONFIG_PATH> to the fullpath of the config folder just created
- [config_path]:/etc/headscale - <CONFIG_PATH>:/etc/headscale
command: headscale serve command: serve
``` ```
1. Verify `headscale` is running: 1. Verify `headscale` is running:
@ -109,7 +102,7 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca
```shell ```shell
docker exec headscale \ docker exec headscale \
headscale users create myfirstuser headscale users create myfirstuser
``` ```
### Register a machine (normal login) ### Register a machine (normal login)
@ -124,7 +117,7 @@ To register a machine when running `headscale` in a container, take the headscal
```shell ```shell
docker exec headscale \ docker exec headscale \
headscale --user myfirstuser nodes register --key <YOU_+MACHINE_KEY> headscale --user myfirstuser nodes register --key <YOUR_MACHINE_KEY>
``` ```
### Register machine using a pre authenticated key ### Register machine using a pre authenticated key
@ -152,7 +145,7 @@ To run the debug Docker container, use the exact same commands as above, but rep
### Executing commands in the debug container ### Executing commands in the debug container
The default command in the debug container is to run `headscale`, which is located at `/bin/headscale` inside the container. The default command in the debug container is to run `headscale`, which is located at `/ko-app/headscale` inside the container.
Additionally, the debug container includes a minimalist Busybox shell. Additionally, the debug container includes a minimalist Busybox shell.
@ -162,10 +155,10 @@ To launch a shell in the container, use:
docker run -it headscale/headscale:x.x.x-debug sh docker run -it headscale/headscale:x.x.x-debug sh
``` ```
You can also execute commands directly, such as `ls /bin` in this example: You can also execute commands directly, such as `ls /ko-app` in this example:
``` ```
docker run headscale/headscale:x.x.x-debug ls /bin docker run headscale/headscale:x.x.x-debug ls /ko-app
``` ```
Using `docker exec` allows you to run commands in an existing container. Using `docker exec` allows you to run commands in an existing container.

12
docs/running-headscale-linux-manual.md
View file

@ -1,9 +1,9 @@
# Running headscale on Linux # Running headscale on Linux
## Note: Outdated and "advanced" !!! warning "Outdated and advanced"
This documentation is considered the "legacy"/advanced/manual version of the documentation, you most likely do not This documentation is considered the "legacy"/advanced/manual version of the documentation, you most likely do not
want to use this documentation and rather look at the distro specific documentation (TODO LINK)[]. want to use this documentation and rather look at the [distro specific documentation](./running-headscale-linux.md).
## Goal ## Goal
@ -45,12 +45,6 @@ describing how to make `headscale` run properly in a server environment.
headscale headscale
``` ```
1. Create an empty SQLite database:
```shell
touch /var/lib/headscale/db.sqlite
```
1. Create a `headscale` configuration: 1. Create a `headscale` configuration:
```shell ```shell

12
docs/running-headscale-openbsd.md
View file

@ -10,7 +10,7 @@
## Goal ## Goal
This documentation has the goal of showing a user how-to install and run `headscale` on OpenBSD. This documentation has the goal of showing a user how-to install and run `headscale` on OpenBSD.
In additional to the "get up and running section", there is an optional [rc.d section](#running-headscale-in-the-background-with-rcd) In addition to the "get up and running section", there is an optional [rc.d section](#running-headscale-in-the-background-with-rcd)
describing how to make `headscale` run properly in a server environment. describing how to make `headscale` run properly in a server environment.
## Install `headscale` ## Install `headscale`
@ -77,16 +77,10 @@ describing how to make `headscale` run properly in a server environment.
mkdir -p /etc/headscale mkdir -p /etc/headscale
# Directory for Database, and other variable data (like certificates) # Directory for database, and other variable data (like certificates)
mkdir -p /var/lib/headscale mkdir -p /var/lib/headscale
``` ```
1. Create an empty SQLite database:
```shell
touch /var/lib/headscale/db.sqlite
```
1. Create a `headscale` configuration: 1. Create a `headscale` configuration:
```shell ```shell
@ -135,7 +129,7 @@ tailscale up --login-server YOUR_HEADSCALE_URL
Register the machine: Register the machine:
```shell ```shell
headscale --user myfirstuser nodes register --key <YOU_+MACHINE_KEY> headscale --user myfirstuser nodes register --key <YOUR_MACHINE_KEY>
``` ```
### Register machine using a pre authenticated key ### Register machine using a pre authenticated key

4
docs/running-headscale-sealos.md
View file

@ -13,7 +13,7 @@ This documentation has the goal of showing a user how-to run `headscale` on Seal
## Running headscale server ## Running headscale server
1. Click the following prebuilt template(version [0.23.0-alpha2](https://github.com/juanfont/headscale/releases/tag/v0.23.0-alpha2)): 1. Click the following prebuilt template:
[![](https://cdn.jsdelivr.net/gh/labring-actions/templates@main/Deploy-on-Sealos.svg)](https://cloud.sealos.io/?openapp=system-template%3FtemplateName%3Dheadscale) [![](https://cdn.jsdelivr.net/gh/labring-actions/templates@main/Deploy-on-Sealos.svg)](https://cloud.sealos.io/?openapp=system-template%3FtemplateName%3Dheadscale)
@ -41,7 +41,7 @@ tailscale up --login-server YOUR_HEADSCALE_URL
To register a machine when running headscale in [Sealos](https://sealos.io), click on 'Terminal' button on the right side of the headscale application's detail page to access the Terminal of the headscale application, then take the headscale command: To register a machine when running headscale in [Sealos](https://sealos.io), click on 'Terminal' button on the right side of the headscale application's detail page to access the Terminal of the headscale application, then take the headscale command:
```bash ```bash
headscale --user myfirstuser nodes register --key <YOU_+MACHINE_KEY> headscale --user myfirstuser nodes register --key <YOUR_MACHINE_KEY>
``` ```
### Register machine using a pre authenticated key ### Register machine using a pre authenticated key