mirror of
https://github.com/juanfont/headscale.git
synced 2024-12-20 19:09:07 +01:00
Add apple endpoint to readme
This commit is contained in:
parent
59c3d4bcfe
commit
237a14858a
132
README.md
132
README.md
@ -22,27 +22,25 @@ Headscale implements this coordination server.
|
|||||||
- [x] Namespace support (~equivalent to multi-user in Tailscale.com)
|
- [x] Namespace support (~equivalent to multi-user in Tailscale.com)
|
||||||
- [x] Routing (advertise & accept, including exit nodes)
|
- [x] Routing (advertise & accept, including exit nodes)
|
||||||
- [x] Node registration via pre-auth keys (including reusable keys, and ephemeral node support)
|
- [x] Node registration via pre-auth keys (including reusable keys, and ephemeral node support)
|
||||||
- [X] JSON-formatted output
|
- [x] JSON-formatted output
|
||||||
- [X] ACLs
|
- [x] ACLs
|
||||||
- [X] Support for alternative IP ranges in the tailnets (default Tailscale's 100.64.0.0/10)
|
- [x] Support for alternative IP ranges in the tailnets (default Tailscale's 100.64.0.0/10)
|
||||||
- [X] DNS (passing DNS servers to nodes)
|
- [x] DNS (passing DNS servers to nodes)
|
||||||
- [X] Share nodes between ~~users~~ namespaces
|
- [x] Share nodes between ~~users~~ namespaces
|
||||||
- [ ] MagicDNS / Smart DNS
|
- [ ] MagicDNS / Smart DNS
|
||||||
|
|
||||||
|
|
||||||
## Roadmap 🤷
|
## Roadmap 🤷
|
||||||
|
|
||||||
Suggestions/PRs welcomed!
|
Suggestions/PRs welcomed!
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Running it
|
## Running it
|
||||||
|
|
||||||
1. Download the Headscale binary https://github.com/juanfont/headscale/releases, and place it somewhere in your PATH or use the docker container
|
1. Download the Headscale binary https://github.com/juanfont/headscale/releases, and place it somewhere in your PATH or use the docker container
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
docker pull headscale/headscale:x.x.x
|
docker pull headscale/headscale:x.x.x
|
||||||
```
|
```
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
or
|
or
|
||||||
```shell
|
```shell
|
||||||
@ -51,63 +49,75 @@ Suggestions/PRs welcomed!
|
|||||||
|
|
||||||
2. (Optional, you can also use SQLite) Get yourself a PostgreSQL DB running
|
2. (Optional, you can also use SQLite) Get yourself a PostgreSQL DB running
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
docker run --name headscale -e POSTGRES_DB=headscale -e \
|
docker run --name headscale -e POSTGRES_DB=headscale -e \
|
||||||
POSTGRES_USER=foo -e POSTGRES_PASSWORD=bar -p 5432:5432 -d postgres
|
POSTGRES_USER=foo -e POSTGRES_PASSWORD=bar -p 5432:5432 -d postgres
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Set some stuff up (headscale Wireguard keys & the config.json file)
|
3. Set some stuff up (headscale Wireguard keys & the config.json file)
|
||||||
```shell
|
|
||||||
wg genkey > private.key
|
|
||||||
wg pubkey < private.key > public.key # not needed
|
|
||||||
|
|
||||||
# Postgres
|
```shell
|
||||||
cp config.json.postgres.example config.json
|
wg genkey > private.key
|
||||||
# or
|
wg pubkey < private.key > public.key # not needed
|
||||||
# SQLite
|
|
||||||
cp config.json.sqlite.example config.json
|
# Postgres
|
||||||
```
|
cp config.json.postgres.example config.json
|
||||||
|
# or
|
||||||
|
# SQLite
|
||||||
|
cp config.json.sqlite.example config.json
|
||||||
|
```
|
||||||
|
|
||||||
4. Create a namespace (a namespace is a 'tailnet', a group of Tailscale nodes that can talk to each other)
|
4. Create a namespace (a namespace is a 'tailnet', a group of Tailscale nodes that can talk to each other)
|
||||||
```shell
|
|
||||||
headscale namespaces create myfirstnamespace
|
```shell
|
||||||
```
|
headscale namespaces create myfirstnamespace
|
||||||
or docker:
|
```
|
||||||
```shell
|
|
||||||
docker run -v ./private.key:/private.key -v ./config.json:/config.json headscale/headscale:x.x.x headscale namespace create myfirstnamespace
|
or docker:
|
||||||
```
|
|
||||||
|
```shell
|
||||||
|
docker run -v ./private.key:/private.key -v ./config.json:/config.json headscale/headscale:x.x.x headscale namespace create myfirstnamespace
|
||||||
|
```
|
||||||
|
|
||||||
5. Run the server
|
5. Run the server
|
||||||
```shell
|
|
||||||
headscale serve
|
```shell
|
||||||
```
|
headscale serve
|
||||||
or docker:
|
```
|
||||||
```shell
|
|
||||||
docker run -v $(pwd)/private.key:/private.key -v $(pwd)/config.json:/config.json -v $(pwd)/derb.yaml:/derb.yaml -p 127.0.0.1:8080:8080 headscale/headscale:x.x.x headscale serve
|
or docker:
|
||||||
```
|
|
||||||
|
```shell
|
||||||
|
docker run -v $(pwd)/private.key:/private.key -v $(pwd)/config.json:/config.json -v $(pwd)/derb.yaml:/derb.yaml -p 127.0.0.1:8080:8080 headscale/headscale:x.x.x headscale serve
|
||||||
|
```
|
||||||
|
|
||||||
6. If you used tailscale.com before in your nodes, make sure you clear the tailscaled data folder
|
6. If you used tailscale.com before in your nodes, make sure you clear the tailscaled data folder
|
||||||
```shell
|
|
||||||
systemctl stop tailscaled
|
```shell
|
||||||
rm -fr /var/lib/tailscale
|
systemctl stop tailscaled
|
||||||
systemctl start tailscaled
|
rm -fr /var/lib/tailscale
|
||||||
```
|
systemctl start tailscaled
|
||||||
|
```
|
||||||
|
|
||||||
7. Add your first machine
|
7. Add your first machine
|
||||||
```shell
|
|
||||||
tailscale up -login-server YOUR_HEADSCALE_URL
|
```shell
|
||||||
```
|
tailscale up -login-server YOUR_HEADSCALE_URL
|
||||||
|
```
|
||||||
|
|
||||||
8. Navigate to the URL you will get with `tailscale up`, where you'll find your machine key.
|
8. Navigate to the URL you will get with `tailscale up`, where you'll find your machine key.
|
||||||
|
|
||||||
9. In the server, register your machine to a namespace with the CLI
|
9. In the server, register your machine to a namespace with the CLI
|
||||||
```shell
|
|
||||||
headscale -n myfirstnamespace node register YOURMACHINEKEY
|
```shell
|
||||||
```
|
headscale -n myfirstnamespace node register YOURMACHINEKEY
|
||||||
or docker:
|
```
|
||||||
```shell
|
|
||||||
docker run -v ./private.key:/private.key -v ./config.json:/config.json headscale/headscale:x.x.x headscale -n myfirstnamespace node register YOURMACHINEKEY
|
or docker:
|
||||||
```
|
|
||||||
|
```shell
|
||||||
|
docker run -v ./private.key:/private.key -v ./config.json:/config.json headscale/headscale:x.x.x headscale -n myfirstnamespace node register YOURMACHINEKEY
|
||||||
|
```
|
||||||
|
|
||||||
Alternatively, you can use Auth Keys to register your machines:
|
Alternatively, you can use Auth Keys to register your machines:
|
||||||
|
|
||||||
@ -116,9 +126,10 @@ Alternatively, you can use Auth Keys to register your machines:
|
|||||||
headscale -n myfirstnamespace preauthkeys create --reusable --expiration 24h
|
headscale -n myfirstnamespace preauthkeys create --reusable --expiration 24h
|
||||||
```
|
```
|
||||||
or docker:
|
or docker:
|
||||||
```shell
|
|
||||||
docker run -v ./private.key:/private.key -v ./config.json:/config.json headscale/headscale:x.x.x headscale -n myfirstnamespace preauthkeys create --reusable --expiration 24h
|
```shell
|
||||||
```
|
docker run -v ./private.key:/private.key -v ./config.json:/config.json headscale/headscale:x.x.x headscale -n myfirstnamespace preauthkeys create --reusable --expiration 24h
|
||||||
|
```
|
||||||
|
|
||||||
2. Use the authkey from your machine to register it
|
2. Use the authkey from your machine to register it
|
||||||
```shell
|
```shell
|
||||||
@ -129,7 +140,6 @@ If you create an authkey with the `--ephemeral` flag, that key will create ephem
|
|||||||
|
|
||||||
Please bear in mind that all the commands from headscale support adding `-o json` or `-o json-line` to get a nicely JSON-formatted output.
|
Please bear in mind that all the commands from headscale support adding `-o json` or `-o json-line` to get a nicely JSON-formatted output.
|
||||||
|
|
||||||
|
|
||||||
## Configuration reference
|
## Configuration reference
|
||||||
|
|
||||||
Headscale's configuration file is named `config.json` or `config.yaml`. Headscale will look for it in `/etc/headscale`, `~/.headscale` and finally the directory from where the Headscale binary is executed.
|
Headscale's configuration file is named `config.json` or `config.yaml`. Headscale will look for it in `/etc/headscale`, `~/.headscale` and finally the directory from where the Headscale binary is executed.
|
||||||
@ -145,6 +155,7 @@ Headscale's configuration file is named `config.json` or `config.yaml`. Headscal
|
|||||||
```
|
```
|
||||||
"log_level": "debug"
|
"log_level": "debug"
|
||||||
```
|
```
|
||||||
|
|
||||||
`log_level` can be used to set the Log level for Headscale, it defaults to `debug`, and the available levels are: `trace`, `debug`, `info`, `warn` and `error`.
|
`log_level` can be used to set the Log level for Headscale, it defaults to `debug`, and the available levels are: `trace`, `debug`, `info`, `warn` and `error`.
|
||||||
|
|
||||||
```
|
```
|
||||||
@ -175,7 +186,6 @@ Headscale's configuration file is named `config.json` or `config.yaml`. Headscal
|
|||||||
|
|
||||||
The fields starting with `db_` are used for the PostgreSQL connection information.
|
The fields starting with `db_` are used for the PostgreSQL connection information.
|
||||||
|
|
||||||
|
|
||||||
### Running the service via TLS (optional)
|
### Running the service via TLS (optional)
|
||||||
|
|
||||||
```
|
```
|
||||||
@ -209,21 +219,21 @@ Alternatively, `tls_letsencrypt_challenge_type` can be set to `TLS-ALPN-01`. In
|
|||||||
Headscale implements the same policy ACLs as Tailscale.com, adapted to the self-hosted environment.
|
Headscale implements the same policy ACLs as Tailscale.com, adapted to the self-hosted environment.
|
||||||
|
|
||||||
For instance, instead of referring to users when defining groups you must
|
For instance, instead of referring to users when defining groups you must
|
||||||
use namespaces (which are the equivalent to user/logins in Tailscale.com).
|
use namespaces (which are the equivalent to user/logins in Tailscale.com).
|
||||||
|
|
||||||
Please check https://tailscale.com/kb/1018/acls/, and `./tests/acls/` in this repo for working examples.
|
Please check https://tailscale.com/kb/1018/acls/, and `./tests/acls/` in this repo for working examples.
|
||||||
|
|
||||||
|
### Apple devices
|
||||||
|
|
||||||
|
An endpoint with information on how to connect your Apple devices (currently macOS only) is available at `/apple` on your running instance.
|
||||||
|
|
||||||
## Disclaimer
|
## Disclaimer
|
||||||
|
|
||||||
1. We have nothing to do with Tailscale, or Tailscale Inc.
|
1. We have nothing to do with Tailscale, or Tailscale Inc.
|
||||||
2. The purpose of writing this was to learn how Tailscale works.
|
2. The purpose of writing this was to learn how Tailscale works.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## More on Tailscale
|
## More on Tailscale
|
||||||
|
|
||||||
- https://tailscale.com/blog/how-tailscale-works/
|
- https://tailscale.com/blog/how-tailscale-works/
|
||||||
- https://tailscale.com/blog/tailscale-key-management/
|
- https://tailscale.com/blog/tailscale-key-management/
|
||||||
- https://tailscale.com/blog/an-unlikely-database-migration/
|
- https://tailscale.com/blog/an-unlikely-database-migration/
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user