mirror of
https://github.com/juanfont/headscale.git
synced 2024-11-26 08:53:05 +00:00
Restructure headscale documentation (#2163)
* 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
This commit is contained in:
nblock
GitHub
parent
b3cda08af6
commit
8c7d8ee34f
41 changed files with 865 additions and 940 deletions
|
|
@ -1,6 +1,2 @@
|
||||||
.github/workflows/test-integration-v2*
|
.github/workflows/test-integration-v2*
|
||||||
docs/dns-records.md
|
docs/about/features.md
|
||||||
docs/running-headscale-container.md
|
|
||||||
docs/running-headscale-linux-manual.md
|
|
||||||
docs/running-headscale-linux.md
|
|
||||||
docs/running-headscale-openbsd.md
|
|
||||||
|
|
|
||||||
26
README.md
26
README.md
|
|
@ -46,31 +46,11 @@ buttons available in the repo.
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- Full "base" support of Tailscale's features
|
Please see ["Features" in the documentation](https://headscale.net/about/features/).
|
||||||
- Configurable DNS
|
|
||||||
- [Split DNS](https://tailscale.com/kb/1054/dns/#using-dns-settings-in-the-admin-console)
|
|
||||||
- Node registration
|
|
||||||
- Single-Sign-On (via Open ID Connect)
|
|
||||||
- Pre authenticated key
|
|
||||||
- Taildrop (File Sharing)
|
|
||||||
- [Access control lists](https://tailscale.com/kb/1018/acls/)
|
|
||||||
- [MagicDNS](https://tailscale.com/kb/1081/magicdns)
|
|
||||||
- Dual stack (IPv4 and IPv6)
|
|
||||||
- Routing advertising (including exit nodes)
|
|
||||||
- Ephemeral nodes
|
|
||||||
- Embedded [DERP server](https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp)
|
|
||||||
|
|
||||||
## Client OS support
|
## Client OS support
|
||||||
|
|
||||||
| OS | Supports headscale |
|
Please see ["Client and operating system support" in the documentation](https://headscale.net/about/clients/).
|
||||||
| ------- | -------------------------------------------------------------------------------------------------- |
|
|
||||||
| Linux | Yes |
|
|
||||||
| OpenBSD | Yes |
|
|
||||||
| FreeBSD | Yes |
|
|
||||||
| Windows | Yes (see [docs](./docs/windows-client.md) and `/windows` on your headscale for more information) |
|
|
||||||
| Android | Yes (see [docs](./docs/android-client.md)) |
|
|
||||||
| macOS | Yes (see [docs](./docs/apple-client.md#macos) and `/apple` on your headscale for more information) |
|
|
||||||
| iOS | Yes (see [docs](./docs/apple-client.md#ios) and `/apple` on your headscale for more information) |
|
|
||||||
|
|
||||||
## Running headscale
|
## Running headscale
|
||||||
|
|
||||||
|
|
@ -99,7 +79,7 @@ Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
|
||||||
### Requirements
|
### Requirements
|
||||||
|
|
||||||
To contribute to headscale you would need the latest version of [Go](https://golang.org)
|
To contribute to headscale you would need the latest version of [Go](https://golang.org)
|
||||||
and [Buf](https://buf.build)(Protobuf generator).
|
and [Buf](https://buf.build) (Protobuf generator).
|
||||||
|
|
||||||
We recommend using [Nix](https://nixos.org/) to setup a development environment. This can
|
We recommend using [Nix](https://nixos.org/) to setup a development environment. This can
|
||||||
be done with `nix develop`, which will install the tools and give you a shell.
|
be done with `nix develop`, which will install the tools and give you a shell.
|
||||||
|
|
|
||||||
|
|
@ -209,7 +209,7 @@ tls_letsencrypt_cache_dir: /var/lib/headscale/cache
|
||||||
|
|
||||||
# Type of ACME challenge to use, currently supported types:
|
# Type of ACME challenge to use, currently supported types:
|
||||||
# HTTP-01 or TLS-ALPN-01
|
# HTTP-01 or TLS-ALPN-01
|
||||||
# See [docs/tls.md](docs/tls.md) for more information
|
# See: docs/ref/tls.md for more information
|
||||||
tls_letsencrypt_challenge_type: HTTP-01
|
tls_letsencrypt_challenge_type: HTTP-01
|
||||||
# When HTTP-01 challenge is chosen, letsencrypt must set up a
|
# When HTTP-01 challenge is chosen, letsencrypt must set up a
|
||||||
# verification endpoint, and it will be listening on:
|
# verification endpoint, and it will be listening on:
|
||||||
|
|
@ -297,7 +297,7 @@ dns:
|
||||||
|
|
||||||
# Extra DNS records
|
# Extra DNS records
|
||||||
# so far only A-records are supported (on the tailscale side)
|
# so far only A-records are supported (on the tailscale side)
|
||||||
# See https://github.com/juanfont/headscale/blob/main/docs/dns-records.md#Limitations
|
# See: docs/ref/dns.md
|
||||||
extra_records: []
|
extra_records: []
|
||||||
# - name: "grafana.myvpn.example.com"
|
# - name: "grafana.myvpn.example.com"
|
||||||
# type: "A"
|
# type: "A"
|
||||||
|
|
|
||||||
15
docs/about/clients.md
Normal file
15
docs/about/clients.md
Normal file
|
|
@ -0,0 +1,15 @@
|
||||||
|
# Client and operating system support
|
||||||
|
|
||||||
|
We aim to support the [**last 10 releases** of the Tailscale client](https://tailscale.com/changelog#client) on all
|
||||||
|
provided operating systems and platforms. Some platforms might require additional configuration to connect with
|
||||||
|
headscale.
|
||||||
|
|
||||||
|
| OS | Supports headscale |
|
||||||
|
| ------- | ----------------------------------------------------------------------------------------------------- |
|
||||||
|
| Linux | Yes |
|
||||||
|
| OpenBSD | Yes |
|
||||||
|
| FreeBSD | Yes |
|
||||||
|
| Windows | Yes (see [docs](../usage/connect/windows.md) and `/windows` on your headscale for more information) |
|
||||||
|
| Android | Yes (see [docs](../usage/connect/android.md)) |
|
||||||
|
| macOS | Yes (see [docs](../usage/connect/apple.md#macos) and `/apple` on your headscale for more information) |
|
||||||
|
| iOS | Yes (see [docs](../usage/connect/apple.md#ios) and `/apple` on your headscale for more information) |
|
||||||
3
docs/about/contributing.md
Normal file
3
docs/about/contributing.md
Normal file
|
|
@ -0,0 +1,3 @@
|
||||||
|
{%
|
||||||
|
include-markdown "../../CONTRIBUTING.md"
|
||||||
|
%}
|
||||||
|
|
@ -1,15 +1,10 @@
|
||||||
---
|
|
||||||
hide:
|
|
||||||
- navigation
|
|
||||||
---
|
|
||||||
|
|
||||||
# Frequently Asked Questions
|
# Frequently Asked Questions
|
||||||
|
|
||||||
## What is the design goal of headscale?
|
## What is the design goal of headscale?
|
||||||
|
|
||||||
`headscale` aims to implement a self-hosted, open source alternative to the [Tailscale](https://tailscale.com/)
|
Headscale aims to implement a self-hosted, open source alternative to the [Tailscale](https://tailscale.com/)
|
||||||
control server.
|
control server.
|
||||||
`headscale`'s goal is to provide self-hosters and hobbyists with an open-source
|
Headscale's goal is to provide self-hosters and hobbyists with an open-source
|
||||||
server they can use for their projects and labs.
|
server they can use for their projects and labs.
|
||||||
It implements a narrow scope, a _single_ Tailnet, suitable for a personal use, or a small
|
It implements a narrow scope, a _single_ Tailnet, suitable for a personal use, or a small
|
||||||
open-source organisation.
|
open-source organisation.
|
||||||
|
|
@ -19,9 +14,7 @@ open-source organisation.
|
||||||
Headscale is "Open Source, acknowledged contribution", this means that any
|
Headscale is "Open Source, acknowledged contribution", this means that any
|
||||||
contribution will have to be discussed with the Maintainers before being submitted.
|
contribution will have to be discussed with the Maintainers before being submitted.
|
||||||
|
|
||||||
Headscale is open to code contributions for bug fixes without discussion.
|
Please see [Contributing](contributing.md) for more information.
|
||||||
|
|
||||||
If you find mistakes in the documentation, please also submit a fix to the documentation.
|
|
||||||
|
|
||||||
## Why is 'acknowledged contribution' the chosen model?
|
## Why is 'acknowledged contribution' the chosen model?
|
||||||
|
|
||||||
|
|
@ -39,18 +32,22 @@ Please be aware that there are a number of reasons why we might not accept speci
|
||||||
- Given that we are reverse-engineering Tailscale to satisfy our own curiosity, we might be interested in implementing the feature ourselves.
|
- Given that we are reverse-engineering Tailscale to satisfy our own curiosity, we might be interested in implementing the feature ourselves.
|
||||||
- You are not sending unit and integration tests with it.
|
- You are not sending unit and integration tests with it.
|
||||||
|
|
||||||
## Do you support Y method of deploying Headscale?
|
## Do you support Y method of deploying headscale?
|
||||||
|
|
||||||
We currently support deploying `headscale` using our binaries and the DEB packages. Both can be found in the
|
We currently support deploying headscale using our binaries and the DEB packages. Visit our [installation guide using
|
||||||
[GitHub releases page](https://github.com/juanfont/headscale/releases).
|
official releases](../setup/install/official.md) for more information.
|
||||||
|
|
||||||
In addition to that, there are semi-official RPM packages by the Fedora infra team https://copr.fedorainfracloud.org/coprs/jonathanspw/headscale/
|
In addition to that, you may use packages provided by the community or from distributions. Learn more in the
|
||||||
|
[installation guide using community packages](../setup/install/community.md).
|
||||||
|
|
||||||
For convenience, we also build Docker images with `headscale`. But **please be aware that we don't officially support deploying `headscale` using Docker**. We have a [Discord channel](https://discord.com/channels/896711691637780480/1070619770942148618) where you can ask for Docker-specific help to the community.
|
For convenience, we also [build Docker images with headscale](../setup/install/container.md). But **please be aware that
|
||||||
|
we don't officially support deploying headscale using Docker**. We have a [Discord
|
||||||
|
channel](https://discord.com/channels/896711691637780480/1070619770942148618) where you can ask for Docker-specific help
|
||||||
|
to the community.
|
||||||
|
|
||||||
## Why is my reverse proxy not working with Headscale?
|
## Why is my reverse proxy not working with headscale?
|
||||||
|
|
||||||
We don't know. We don't use reverse proxies with `headscale` ourselves, so we don't have any experience with them. We have [community documentation](https://headscale.net/reverse-proxy/) on how to configure various reverse proxies, and a dedicated [Discord channel](https://discord.com/channels/896711691637780480/1070619818346164324) where you can ask for help to the community.
|
We don't know. We don't use reverse proxies with headscale ourselves, so we don't have any experience with them. We have [community documentation](../ref/integration/reverse-proxy.md) on how to configure various reverse proxies, and a dedicated [Discord channel](https://discord.com/channels/896711691637780480/1070619818346164324) where you can ask for help to the community.
|
||||||
|
|
||||||
## Can I use headscale and tailscale on the same machine?
|
## Can I use headscale and tailscale on the same machine?
|
||||||
|
|
||||||
31
docs/about/features.md
Normal file
31
docs/about/features.md
Normal file
|
|
@ -0,0 +1,31 @@
|
||||||
|
# Features
|
||||||
|
|
||||||
|
Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is
|
||||||
|
to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. This page
|
||||||
|
provides on overview of headscale's feature and compatibility with the Tailscale control server:
|
||||||
|
|
||||||
|
- [x] Full "base" support of Tailscale's features
|
||||||
|
- [x] Node registration
|
||||||
|
- [x] Interactive
|
||||||
|
- [x] Pre authenticated key
|
||||||
|
- [x] [DNS](https://tailscale.com/kb/1054/dns)
|
||||||
|
- [x] [MagicDNS](https://tailscale.com/kb/1081/magicdns)
|
||||||
|
- [x] [Global and restricted nameservers (split DNS)](https://tailscale.com/kb/1054/dns#nameservers)
|
||||||
|
- [x] [search domains](https://tailscale.com/kb/1054/dns#search-domains)
|
||||||
|
- [x] [Extra DNS records (headscale only)](../ref/dns.md#setting-custom-dns-records)
|
||||||
|
- [x] [Taildrop (File Sharing)](https://tailscale.com/kb/1106/taildrop)
|
||||||
|
- [x] Routing advertising (including exit nodes)
|
||||||
|
- [x] Dual stack (IPv4 and IPv6)
|
||||||
|
- [x] Ephemeral nodes
|
||||||
|
- [x] Embedded [DERP server](https://tailscale.com/kb/1232/derp-servers)
|
||||||
|
- [x] Access control lists ([GitHub label "policy"](https://github.com/juanfont/headscale/labels/policy%20%F0%9F%93%9D))
|
||||||
|
- [x] ACL management via API
|
||||||
|
- [x] `autogroup:internet`
|
||||||
|
- [ ] `autogroup:self`
|
||||||
|
- [ ] `autogroup:member`
|
||||||
|
* [ ] Node registration using Single-Sign-On (OpenID Connect) ([GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC))
|
||||||
|
- [x] Basic registration
|
||||||
|
- [ ] Dynamic ACL support
|
||||||
|
- [ ] OIDC groups cannot be used in ACLs
|
||||||
|
- [ ] [Funnel](https://tailscale.com/kb/1223/funnel) ([#1040](https://github.com/juanfont/headscale/issues/1040))
|
||||||
|
- [ ] [Serve](https://tailscale.com/kb/1312/serve) ([#1234](https://github.com/juanfont/headscale/issues/1921))
|
||||||
11
docs/about/help.md
Normal file
11
docs/about/help.md
Normal file
|
|
@ -0,0 +1,11 @@
|
||||||
|
# Getting help
|
||||||
|
|
||||||
|
Join our Discord server for announcements and community support:
|
||||||
|
|
||||||
|
- [announcements](https://discord.com/channels/896711691637780480/896711692120129538)
|
||||||
|
- [general](https://discord.com/channels/896711691637780480/896711692120129540)
|
||||||
|
- [docker-issues](https://discord.com/channels/896711691637780480/1070619770942148618)
|
||||||
|
- [reverse-proxy-issues](https://discord.com/channels/896711691637780480/1070619818346164324)
|
||||||
|
- [web-interfaces](https://discord.com/channels/896711691637780480/1105842846386356294)
|
||||||
|
|
||||||
|
Please report bugs via [GitHub issues](https://github.com/juanfont/headscale/issues)
|
||||||
10
docs/about/releases.md
Normal file
10
docs/about/releases.md
Normal file
|
|
@ -0,0 +1,10 @@
|
||||||
|
# Releases
|
||||||
|
|
||||||
|
All headscale releases are available on the [GitHub release page](https://github.com/juanfont/headscale/releases). Those
|
||||||
|
releases are available as binaries for various platforms and architectures, packages for Debian based systems and source
|
||||||
|
code archives. Container images are available on [Docker Hub](https://hub.docker.com/r/headscale/headscale).
|
||||||
|
|
||||||
|
An Atom/RSS feed of headscale releases is available [here](https://github.com/juanfont/headscale/releases.atom).
|
||||||
|
|
||||||
|
Join the ["announcements" channel on Discord](https://discord.com/channels/896711691637780480/896711692120129538) for
|
||||||
|
news about headscale.
|
||||||
4
docs/about/sponsor.md
Normal file
4
docs/about/sponsor.md
Normal file
|
|
@ -0,0 +1,4 @@
|
||||||
|
# Sponsor
|
||||||
|
|
||||||
|
If you like to support the development of headscale, please consider a donation via
|
||||||
|
[ko-fi.com/headscale](https://ko-fi.com/headscale). Thank you!
|
||||||
|
|
@ -1,92 +0,0 @@
|
||||||
# Setting custom DNS records
|
|
||||||
|
|
||||||
!!! warning "Community documentation"
|
|
||||||
|
|
||||||
This page is not actively maintained by the headscale authors and is
|
|
||||||
written by community members. It is _not_ verified by `headscale` developers.
|
|
||||||
|
|
||||||
**It might be outdated and it might miss necessary steps**.
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
|
|
||||||
This documentation has the goal of showing how a user can set custom DNS records with `headscale`s magic dns.
|
|
||||||
An example use case is to serve apps on the same host via a reverse proxy like NGINX, in this case a Prometheus monitoring stack. This allows to nicely access the service with "http://grafana.myvpn.example.com" instead of the hostname and portnum combination "http://hostname-in-magic-dns.myvpn.example.com:3000".
|
|
||||||
|
|
||||||
## Setup
|
|
||||||
|
|
||||||
### 1. Change the configuration
|
|
||||||
|
|
||||||
1. Change the `config.yaml` to contain the desired records like so:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
dns:
|
|
||||||
...
|
|
||||||
extra_records:
|
|
||||||
- name: "prometheus.myvpn.example.com"
|
|
||||||
type: "A"
|
|
||||||
value: "100.64.0.3"
|
|
||||||
|
|
||||||
- name: "grafana.myvpn.example.com"
|
|
||||||
type: "A"
|
|
||||||
value: "100.64.0.3"
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Restart your headscale instance.
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
|
|
||||||
Beware of the limitations listed later on!
|
|
||||||
|
|
||||||
### 2. Verify that the records are set
|
|
||||||
|
|
||||||
You can use a DNS querying tool of your choice on one of your hosts to verify that your newly set records are actually available in MagicDNS, here we used [`dig`](https://man.archlinux.org/man/dig.1.en):
|
|
||||||
|
|
||||||
```
|
|
||||||
$ dig grafana.myvpn.example.com
|
|
||||||
|
|
||||||
; <<>> DiG 9.18.10 <<>> grafana.myvpn.example.com
|
|
||||||
;; global options: +cmd
|
|
||||||
;; Got answer:
|
|
||||||
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 44054
|
|
||||||
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
|
|
||||||
|
|
||||||
;; OPT PSEUDOSECTION:
|
|
||||||
; EDNS: version: 0, flags:; udp: 65494
|
|
||||||
;; QUESTION SECTION:
|
|
||||||
;grafana.myvpn.example.com. IN A
|
|
||||||
|
|
||||||
;; ANSWER SECTION:
|
|
||||||
grafana.myvpn.example.com. 593 IN A 100.64.0.3
|
|
||||||
|
|
||||||
;; Query time: 0 msec
|
|
||||||
;; SERVER: 127.0.0.53#53(127.0.0.53) (UDP)
|
|
||||||
;; WHEN: Sat Dec 31 11:46:55 CET 2022
|
|
||||||
;; MSG SIZE rcvd: 66
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Optional: Setup the reverse proxy
|
|
||||||
|
|
||||||
The motivating example here was to be able to access internal monitoring services on the same host without specifying a port:
|
|
||||||
|
|
||||||
```
|
|
||||||
server {
|
|
||||||
listen 80;
|
|
||||||
listen [::]:80;
|
|
||||||
|
|
||||||
server_name grafana.myvpn.example.com;
|
|
||||||
|
|
||||||
location / {
|
|
||||||
proxy_pass http://localhost:3000;
|
|
||||||
proxy_set_header Host $http_host;
|
|
||||||
proxy_set_header X-Real-IP $remote_addr;
|
|
||||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
||||||
proxy_set_header X-Forwarded-Proto $scheme;
|
|
||||||
}
|
|
||||||
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Limitations
|
|
||||||
|
|
||||||
[Not all types of records are supported](https://github.com/tailscale/tailscale/blob/6edf357b96b28ee1be659a70232c0135b2ffedfd/ipn/ipnlocal/local.go#L2989-L3007), especially no CNAME records.
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 35 KiB |
|
|
@ -4,11 +4,11 @@ hide:
|
||||||
- toc
|
- toc
|
||||||
---
|
---
|
||||||
|
|
||||||
# headscale
|
# Welcome to headscale
|
||||||
|
|
||||||
`headscale` is an open source, self-hosted implementation of the Tailscale control server.
|
Headscale is an open source, self-hosted implementation of the Tailscale control server.
|
||||||
|
|
||||||
This page contains the documentation for the latest version of headscale. Please also check our [FAQ](faq.md).
|
This page contains the documentation for the latest version of headscale. Please also check our [FAQ](./about/faq.md).
|
||||||
|
|
||||||
Join our [Discord](https://discord.gg/c84AZQhmpx) server for a chat and community support.
|
Join our [Discord](https://discord.gg/c84AZQhmpx) server for a chat and community support.
|
||||||
|
|
||||||
|
|
@ -23,16 +23,15 @@ open-source organisation.
|
||||||
|
|
||||||
## Supporting headscale
|
## Supporting headscale
|
||||||
|
|
||||||
If you like `headscale` and find it useful, there is a sponsorship and donation
|
Please see [Sponsor](about/sponsor.md) for more information.
|
||||||
buttons available in the repo.
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
Headscale is "Open Source, acknowledged contribution", this means that any
|
Headscale is "Open Source, acknowledged contribution", this means that any
|
||||||
contribution will have to be discussed with the Maintainers before being submitted.
|
contribution will have to be discussed with the Maintainers before being submitted.
|
||||||
|
|
||||||
Please see [CONTRIBUTING.md](https://github.com/juanfont/headscale/blob/main/CONTRIBUTING.md) for more information.
|
Please see [Contributing](about/contributing.md) for more information.
|
||||||
|
|
||||||
## About
|
## About
|
||||||
|
|
||||||
`headscale` is maintained by [Kristoffer Dalby](https://kradalby.no/) and [Juan Font](https://font.eu).
|
Headscale is maintained by [Kristoffer Dalby](https://kradalby.no/) and [Juan Font](https://font.eu).
|
||||||
|
|
|
||||||
|
|
@ -36,12 +36,12 @@ servers.
|
||||||
- billing.internal
|
- billing.internal
|
||||||
- router.internal
|
- router.internal
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## ACL setup
|
## ACL setup
|
||||||
|
|
||||||
Note: Users will be created automatically when users authenticate with the
|
Note: Users will be created automatically when users authenticate with the
|
||||||
Headscale server.
|
headscale server.
|
||||||
|
|
||||||
ACLs have to be written in [huJSON](https://github.com/tailscale/hujson).
|
ACLs have to be written in [huJSON](https://github.com/tailscale/hujson).
|
||||||
|
|
||||||
|
|
@ -87,7 +87,7 @@ Here are the ACL's to implement the same permissions as above:
|
||||||
// to define a single host, use a /32 mask. You cannot use DNS entries here,
|
// to define a single host, use a /32 mask. You cannot use DNS entries here,
|
||||||
// as they're prone to be hijacked by replacing their IP addresses.
|
// as they're prone to be hijacked by replacing their IP addresses.
|
||||||
// see https://github.com/tailscale/tailscale/issues/3800 for more information.
|
// see https://github.com/tailscale/tailscale/issues/3800 for more information.
|
||||||
"Hosts": {
|
"hosts": {
|
||||||
"postgresql.internal": "10.20.0.2/32",
|
"postgresql.internal": "10.20.0.2/32",
|
||||||
"webservers.internal": "10.20.10.1/29"
|
"webservers.internal": "10.20.10.1/29"
|
||||||
},
|
},
|
||||||
39
docs/ref/configuration.md
Normal file
39
docs/ref/configuration.md
Normal file
|
|
@ -0,0 +1,39 @@
|
||||||
|
# Configuration
|
||||||
|
|
||||||
|
- Headscale loads its configuration from a YAML file
|
||||||
|
- It searches for `config.yaml` in the following paths:
|
||||||
|
- `/etc/headscale`
|
||||||
|
- `$HOME/.headscale`
|
||||||
|
- the current working directory
|
||||||
|
- Use the command line flag `-c`, `--config` to load the configuration from a different path
|
||||||
|
- Validate the configuration file with: `headscale configtest`
|
||||||
|
|
||||||
|
!!! example "Get the [example configuration from the GitHub repository](https://github.com/juanfont/headscale/blob/main/config-example.yaml)"
|
||||||
|
|
||||||
|
Always select the [same GitHub tag](https://github.com/juanfont/headscale/tags) as the released version you use to
|
||||||
|
ensure you have the correct example configuration. The `main` branch might contain unreleased changes.
|
||||||
|
|
||||||
|
=== "View on GitHub"
|
||||||
|
|
||||||
|
* Development version: <https://github.com/juanfont/headscale/blob/main/config-example.yaml>
|
||||||
|
* Version {{ headscale.version }}: <https://github.com/juanfont/headscale/blob/v{{ headscale.version }}/config-example.yaml>
|
||||||
|
|
||||||
|
=== "Download with `wget`"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# Development version
|
||||||
|
wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
|
||||||
|
|
||||||
|
# Version {{ headscale.version }}
|
||||||
|
wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/v{{ headscale.version }}/config-example.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Download with `curl`"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# Development version
|
||||||
|
curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
|
||||||
|
|
||||||
|
# Version {{ headscale.version }}
|
||||||
|
curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/v{{ headscale.version }}/config-example.yaml
|
||||||
|
```
|
||||||
80
docs/ref/dns.md
Normal file
80
docs/ref/dns.md
Normal file
|
|
@ -0,0 +1,80 @@
|
||||||
|
# DNS
|
||||||
|
|
||||||
|
Headscale supports [most DNS features](../about/features.md) from Tailscale and DNS releated settings can be configured
|
||||||
|
in the [configuration file](./configuration.md) within the `dns` section.
|
||||||
|
|
||||||
|
## Setting custom DNS records
|
||||||
|
|
||||||
|
!!! warning "Community documentation"
|
||||||
|
|
||||||
|
This page is not actively maintained by the headscale authors and is
|
||||||
|
written by community members. It is _not_ verified by headscale developers.
|
||||||
|
|
||||||
|
**It might be outdated and it might miss necessary steps**.
|
||||||
|
|
||||||
|
Headscale allows to set custom DNS records which are made available via
|
||||||
|
[MagicDNS](https://tailscale.com/kb/1081/magicdns). An example use case is to serve multiple apps on the same host via a
|
||||||
|
reverse proxy like NGINX, in this case a Prometheus monitoring stack. This allows to nicely access the service with
|
||||||
|
"http://grafana.myvpn.example.com" instead of the hostname and port combination
|
||||||
|
"http://hostname-in-magic-dns.myvpn.example.com:3000".
|
||||||
|
|
||||||
|
!!! warning "Limitations"
|
||||||
|
|
||||||
|
[Not all types of records are supported](https://github.com/tailscale/tailscale/blob/6edf357b96b28ee1be659a70232c0135b2ffedfd/ipn/ipnlocal/local.go#L2989-L3007), especially no CNAME records.
|
||||||
|
|
||||||
|
1. Update the [configuration file](./configuration.md) to contain the desired records like so:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
dns:
|
||||||
|
...
|
||||||
|
extra_records:
|
||||||
|
- name: "prometheus.myvpn.example.com"
|
||||||
|
type: "A"
|
||||||
|
value: "100.64.0.3"
|
||||||
|
|
||||||
|
- name: "grafana.myvpn.example.com"
|
||||||
|
type: "A"
|
||||||
|
value: "100.64.0.3"
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Restart your headscale instance.
|
||||||
|
|
||||||
|
1. Verify that DNS records are properly set using the DNS querying tool of your choice:
|
||||||
|
|
||||||
|
=== "Query with dig"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
dig +short grafana.myvpn.example.com
|
||||||
|
100.64.0.3
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Query with drill"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
drill -Q grafana.myvpn.example.com
|
||||||
|
100.64.0.3
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Optional: Setup the reverse proxy
|
||||||
|
|
||||||
|
The motivating example here was to be able to access internal monitoring services on the same host without
|
||||||
|
specifying a port, depicted as NGINX configuration snippet:
|
||||||
|
|
||||||
|
```
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
listen [::]:80;
|
||||||
|
|
||||||
|
server_name grafana.myvpn.example.com;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
proxy_pass http://localhost:3000;
|
||||||
|
proxy_set_header Host $http_host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
proxy_set_header X-Forwarded-Proto $scheme;
|
||||||
|
}
|
||||||
|
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
@ -3,7 +3,7 @@
|
||||||
!!! warning "Community documentation"
|
!!! warning "Community documentation"
|
||||||
|
|
||||||
This page is not actively maintained by the headscale authors and is
|
This page is not actively maintained by the headscale authors and is
|
||||||
written by community members. It is _not_ verified by `headscale` developers.
|
written by community members. It is _not_ verified by headscale developers.
|
||||||
|
|
||||||
**It might be outdated and it might miss necessary steps**.
|
**It might be outdated and it might miss necessary steps**.
|
||||||
|
|
||||||
|
|
@ -121,11 +121,11 @@ The following Caddyfile is all that is necessary to use Caddy as a reverse proxy
|
||||||
|
|
||||||
Caddy v2 will [automatically](https://caddyserver.com/docs/automatic-https) provision a certificate for your domain/subdomain, force HTTPS, and proxy websockets - no further configuration is necessary.
|
Caddy v2 will [automatically](https://caddyserver.com/docs/automatic-https) provision a certificate for your domain/subdomain, force HTTPS, and proxy websockets - no further configuration is necessary.
|
||||||
|
|
||||||
For a slightly more complex configuration which utilizes Docker containers to manage Caddy, Headscale, and Headscale-UI, [Guru Computing's guide](https://blog.gurucomputing.com.au/smart-vpns-with-headscale/) is an excellent reference.
|
For a slightly more complex configuration which utilizes Docker containers to manage Caddy, headscale, and Headscale-UI, [Guru Computing's guide](https://blog.gurucomputing.com.au/smart-vpns-with-headscale/) is an excellent reference.
|
||||||
|
|
||||||
## Apache
|
## Apache
|
||||||
|
|
||||||
The following minimal Apache config will proxy traffic to the Headscale instance on `<IP:PORT>`. Note that `upgrade=any` is required as a parameter for `ProxyPass` so that WebSockets traffic whose `Upgrade` header value is not equal to `WebSocket` (i. e. Tailscale Control Protocol) is forwarded correctly. See the [Apache docs](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html) for more information on this.
|
The following minimal Apache config will proxy traffic to the headscale instance on `<IP:PORT>`. Note that `upgrade=any` is required as a parameter for `ProxyPass` so that WebSockets traffic whose `Upgrade` header value is not equal to `WebSocket` (i. e. Tailscale Control Protocol) is forwarded correctly. See the [Apache docs](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html) for more information on this.
|
||||||
|
|
||||||
```
|
```
|
||||||
<VirtualHost *:443>
|
<VirtualHost *:443>
|
||||||
|
|
@ -3,14 +3,14 @@
|
||||||
!!! warning "Community contributions"
|
!!! warning "Community contributions"
|
||||||
|
|
||||||
This page contains community contributions. The projects listed here are not
|
This page contains community contributions. The projects listed here are not
|
||||||
maintained by the Headscale authors and are written by community members.
|
maintained by the headscale authors and are written by community members.
|
||||||
|
|
||||||
| Name | Repository Link | Description | Status |
|
| Name | Repository Link | Description | Status |
|
||||||
| --------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------ |
|
| --------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------ |
|
||||||
| headscale-webui | [Github](https://github.com/ifargle/headscale-webui) | A simple Headscale web UI for small-scale deployments. | Alpha |
|
| headscale-webui | [Github](https://github.com/ifargle/headscale-webui) | A simple headscale web UI for small-scale deployments. | Alpha |
|
||||||
| headscale-ui | [Github](https://github.com/gurucomputing/headscale-ui) | A web frontend for the headscale Tailscale-compatible coordination server | Alpha |
|
| headscale-ui | [Github](https://github.com/gurucomputing/headscale-ui) | A web frontend for the headscale Tailscale-compatible coordination server | Alpha |
|
||||||
| HeadscaleUi | [GitHub](https://github.com/simcu/headscale-ui) | A static headscale admin ui, no backend enviroment required | Alpha |
|
| HeadscaleUi | [GitHub](https://github.com/simcu/headscale-ui) | A static headscale admin ui, no backend enviroment required | Alpha |
|
||||||
| headscale-admin | [Github](https://github.com/GoodiesHQ/headscale-admin) | Headscale-Admin is meant to be a simple, modern web interface for Headscale | Beta |
|
| headscale-admin | [Github](https://github.com/GoodiesHQ/headscale-admin) | Headscale-Admin is meant to be a simple, modern web interface for headscale | Beta |
|
||||||
| ouroboros | [Github](https://github.com/yellowsink/ouroboros) | Ouroboros is designed for users to manage their own devices, rather than for admins | Stable |
|
| ouroboros | [Github](https://github.com/yellowsink/ouroboros) | Ouroboros is designed for users to manage their own devices, rather than for admins | Stable |
|
||||||
|
|
||||||
You can ask for support on our dedicated [Discord channel](https://discord.com/channels/896711691637780480/1105842846386356294).
|
You can ask for support on our dedicated [Discord channel](https://discord.com/channels/896711691637780480/1105842846386356294).
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# Configuring Headscale to use OIDC authentication
|
# Configuring headscale to use OIDC authentication
|
||||||
|
|
||||||
In order to authenticate users through a centralized solution one must enable the OIDC integration.
|
In order to authenticate users through a centralized solution one must enable the OIDC integration.
|
||||||
|
|
||||||
|
|
@ -54,7 +54,7 @@ oidc:
|
||||||
|
|
||||||
## Azure AD example
|
## Azure AD example
|
||||||
|
|
||||||
In order to integrate Headscale with Azure Active Directory, we'll need to provision an App Registration with the correct scopes and redirect URI. Here with Terraform:
|
In order to integrate headscale with Azure Active Directory, we'll need to provision an App Registration with the correct scopes and redirect URI. Here with Terraform:
|
||||||
|
|
||||||
```hcl
|
```hcl
|
||||||
resource "azuread_application" "headscale" {
|
resource "azuread_application" "headscale" {
|
||||||
|
|
@ -84,7 +84,7 @@ resource "azuread_application" "headscale" {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
web {
|
web {
|
||||||
# Points at your running Headscale instance
|
# Points at your running headscale instance
|
||||||
redirect_uris = ["https://headscale.example.com/oidc/callback"]
|
redirect_uris = ["https://headscale.example.com/oidc/callback"]
|
||||||
|
|
||||||
implicit_grant {
|
implicit_grant {
|
||||||
|
|
@ -125,7 +125,7 @@ output "headscale_client_secret" {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
And in your Headscale `config.yaml`:
|
And in your headscale `config.yaml`:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
oidc:
|
oidc:
|
||||||
|
|
@ -144,7 +144,7 @@ oidc:
|
||||||
|
|
||||||
## Google OAuth Example
|
## Google OAuth Example
|
||||||
|
|
||||||
In order to integrate Headscale with Google, you'll need to have a [Google Cloud Console](https://console.cloud.google.com) account.
|
In order to integrate headscale with Google, you'll need to have a [Google Cloud Console](https://console.cloud.google.com) account.
|
||||||
|
|
||||||
Google OAuth has a [verification process](https://support.google.com/cloud/answer/9110914?hl=en) if you need to have users authenticate who are outside of your domain. If you only need to authenticate users from your domain name (ie `@example.com`), you don't need to go through the verification process.
|
Google OAuth has a [verification process](https://support.google.com/cloud/answer/9110914?hl=en) if you need to have users authenticate who are outside of your domain. If you only need to authenticate users from your domain name (ie `@example.com`), you don't need to go through the verification process.
|
||||||
|
|
||||||
|
|
@ -158,17 +158,16 @@ However if you don't have a domain, or need to add users outside of your domain,
|
||||||
4. Click `Create Credentials` -> `OAuth client ID`
|
4. Click `Create Credentials` -> `OAuth client ID`
|
||||||
5. Under `Application Type`, choose `Web Application`
|
5. Under `Application Type`, choose `Web Application`
|
||||||
6. For `Name`, enter whatever you like
|
6. For `Name`, enter whatever you like
|
||||||
7. Under `Authorised redirect URIs`, use `https://example.com/oidc/callback`, replacing example.com with your Headscale URL.
|
7. Under `Authorised redirect URIs`, use `https://example.com/oidc/callback`, replacing example.com with your headscale URL.
|
||||||
8. Click `Save` at the bottom of the form
|
8. Click `Save` at the bottom of the form
|
||||||
9. Take note of the `Client ID` and `Client secret`, you can also download it for reference if you need it.
|
9. Take note of the `Client ID` and `Client secret`, you can also download it for reference if you need it.
|
||||||
10. Edit your headscale config, under `oidc`, filling in your `client_id` and `client_secret`:
|
10. Edit your headscale config, under `oidc`, filling in your `client_id` and `client_secret`:
|
||||||
|
```yaml
|
||||||
```yaml
|
oidc:
|
||||||
oidc:
|
|
||||||
issuer: "https://accounts.google.com"
|
issuer: "https://accounts.google.com"
|
||||||
client_id: ""
|
client_id: ""
|
||||||
client_secret: ""
|
client_secret: ""
|
||||||
scope: ["openid", "profile", "email"]
|
scope: ["openid", "profile", "email"]
|
||||||
```
|
```
|
||||||
|
|
||||||
You can also use `allowed_domains` and `allowed_users` to restrict the users who can authenticate.
|
You can also use `allowed_domains` and `allowed_users` to restrict the users who can authenticate.
|
||||||
98
docs/ref/remote-cli.md
Normal file
98
docs/ref/remote-cli.md
Normal file
|
|
@ -0,0 +1,98 @@
|
||||||
|
# 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
|
||||||
|
|
@ -47,7 +47,7 @@ Headscale uses [autocert](https://pkg.go.dev/golang.org/x/crypto/acme/autocert),
|
||||||
|
|
||||||
If you want to validate that certificate renewal completed successfully, this can be done either manually, or through external monitoring software. Two examples of doing this manually:
|
If you want to validate that certificate renewal completed successfully, this can be done either manually, or through external monitoring software. Two examples of doing this manually:
|
||||||
|
|
||||||
1. Open the URL for your Headscale server in your browser of choice, and manually inspecting the expiry date of the certificate you receive.
|
1. Open the URL for your headscale server in your browser of choice, and manually inspecting the expiry date of the certificate you receive.
|
||||||
2. Or, check remotely from CLI using `openssl`:
|
2. Or, check remotely from CLI using `openssl`:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|
@ -1,100 +0,0 @@
|
||||||
# Controlling `headscale` with remote CLI
|
|
||||||
|
|
||||||
## 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)
|
|
||||||
|
|
||||||
## 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:
|
|
||||||
|
|
||||||
```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):
|
|
||||||
|
|
||||||
2. Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headscale`
|
|
||||||
|
|
||||||
3. Make `headscale` executable:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
chmod +x /usr/local/bin/headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
4. 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.
|
|
||||||
|
|
||||||
5. 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
|
|
||||||
|
|
@ -1,4 +1,7 @@
|
||||||
cairosvg~=2.7.1
|
cairosvg~=2.7.1
|
||||||
|
mkdocs-include-markdown-plugin~=6.2.2
|
||||||
|
mkdocs-macros-plugin~=1.2.0
|
||||||
mkdocs-material~=9.5.18
|
mkdocs-material~=9.5.18
|
||||||
mkdocs-minify-plugin~=0.7.1
|
mkdocs-minify-plugin~=0.7.1
|
||||||
|
mkdocs-redirects~=1.2.1
|
||||||
pillow~=10.1.0
|
pillow~=10.1.0
|
||||||
|
|
|
||||||
|
|
@ -1,163 +0,0 @@
|
||||||
# Running headscale on Linux
|
|
||||||
|
|
||||||
!!! warning "Outdated and advanced"
|
|
||||||
|
|
||||||
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](./running-headscale-linux.md).
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
|
|
||||||
This documentation has the goal of showing a user how-to set up and run `headscale` on Linux.
|
|
||||||
In additional to the "get up and running section", there is an optional [systemd section](#running-headscale-in-the-background-with-systemd)
|
|
||||||
describing how to make `headscale` run properly in a server environment.
|
|
||||||
|
|
||||||
## Configure and run `headscale`
|
|
||||||
|
|
||||||
1. Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases):
|
|
||||||
|
|
||||||
```shell
|
|
||||||
wget --output-document=/usr/local/bin/headscale \
|
|
||||||
https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Make `headscale` executable:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
chmod +x /usr/local/bin/headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Prepare a directory to hold `headscale` configuration and the [SQLite](https://www.sqlite.org/) database:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
# Directory for configuration
|
|
||||||
|
|
||||||
mkdir -p /etc/headscale
|
|
||||||
|
|
||||||
# Directory for Database, and other variable data (like certificates)
|
|
||||||
mkdir -p /var/lib/headscale
|
|
||||||
# or if you create a headscale user:
|
|
||||||
useradd \
|
|
||||||
--create-home \
|
|
||||||
--home-dir /var/lib/headscale/ \
|
|
||||||
--system \
|
|
||||||
--user-group \
|
|
||||||
--shell /usr/sbin/nologin \
|
|
||||||
headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Create a `headscale` configuration:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
touch /etc/headscale/config.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
**(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository.
|
|
||||||
|
|
||||||
1. Start the headscale server:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
headscale serve
|
|
||||||
```
|
|
||||||
|
|
||||||
This command will start `headscale` in the current terminal session.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
To continue the tutorial, open a new terminal and let it run in the background.
|
|
||||||
Alternatively use terminal emulators like [tmux](https://github.com/tmux/tmux) or [screen](https://www.gnu.org/software/screen/).
|
|
||||||
|
|
||||||
To run `headscale` in the background, please follow the steps in the [systemd section](#running-headscale-in-the-background-with-systemd) before continuing.
|
|
||||||
|
|
||||||
1. Verify `headscale` is running:
|
|
||||||
Verify `headscale` is available:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
curl http://127.0.0.1:9090/metrics
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)):
|
|
||||||
|
|
||||||
```shell
|
|
||||||
headscale users create myfirstuser
|
|
||||||
```
|
|
||||||
|
|
||||||
### Register a machine (normal login)
|
|
||||||
|
|
||||||
On a client machine, execute the `tailscale` login command:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
tailscale up --login-server YOUR_HEADSCALE_URL
|
|
||||||
```
|
|
||||||
|
|
||||||
Register the machine:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
headscale nodes register --user myfirstuser --key <YOUR_MACHINE_KEY>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Register machine using a pre authenticated key
|
|
||||||
|
|
||||||
Generate a key using the command line:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
headscale preauthkeys create --user myfirstuser --reusable --expiration 24h
|
|
||||||
```
|
|
||||||
|
|
||||||
This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
|
|
||||||
```
|
|
||||||
|
|
||||||
## Running `headscale` in the background with systemd
|
|
||||||
|
|
||||||
This section demonstrates how to run `headscale` as a service in the background with [systemd](https://systemd.io/).
|
|
||||||
This should work on most modern Linux distributions.
|
|
||||||
|
|
||||||
1. Copy [headscale's systemd service file](./packaging/headscale.systemd.service) to
|
|
||||||
`/etc/systemd/system/headscale.service` and adjust it to suit your local setup. The following parameters likely need
|
|
||||||
to be modified: `ExecStart`, `WorkingDirectory`, `ReadWritePaths`.
|
|
||||||
|
|
||||||
Note that when running as the headscale user ensure that, either you add your current user to the headscale group:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
usermod -a -G headscale current_user
|
|
||||||
```
|
|
||||||
|
|
||||||
or run all headscale commands as the headscale user:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
su - headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
1. In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with path that is writable by the `headscale` user or group:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
unix_socket: /var/run/headscale/headscale.sock
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Reload systemd to load the new configuration file:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
systemctl daemon-reload
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Enable and start the new `headscale` service:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
systemctl enable --now headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Verify the headscale service:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
systemctl status headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
Verify `headscale` is available:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
curl http://127.0.0.1:9090/metrics
|
|
||||||
```
|
|
||||||
|
|
||||||
`headscale` will now run in the background and start at boot.
|
|
||||||
|
|
@ -1,97 +0,0 @@
|
||||||
# Running headscale on Linux
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Ubuntu 20.04 or newer, Debian 11 or newer.
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
|
|
||||||
Get Headscale up and running.
|
|
||||||
|
|
||||||
This includes running Headscale with systemd.
|
|
||||||
|
|
||||||
## Migrating from manual install
|
|
||||||
|
|
||||||
If you are migrating from the old manual install, the best thing would be to remove
|
|
||||||
the files installed by following [the guide in reverse](./running-headscale-linux-manual.md).
|
|
||||||
|
|
||||||
You should _not_ delete the database (`/var/lib/headscale/db.sqlite`) and the
|
|
||||||
configuration (`/etc/headscale/config.yaml`).
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
1. Download the [latest Headscale package](https://github.com/juanfont/headscale/releases/latest) for your platform (`.deb` for Ubuntu and Debian).
|
|
||||||
|
|
||||||
```shell
|
|
||||||
HEADSCALE_VERSION="" # See above URL for latest version, e.g. "X.Y.Z" (NOTE: do not add the "v" prefix!)
|
|
||||||
HEADSCALE_ARCH="" # Your system architecture, e.g. "amd64"
|
|
||||||
wget --output-document=headscale.deb \
|
|
||||||
"https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Install Headscale:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
sudo apt install ./headscale.deb
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Enable Headscale service, this will start Headscale at boot:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
sudo systemctl enable headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Configure Headscale by editing the configuration file:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
nano /etc/headscale/config.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Start Headscale:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
sudo systemctl start headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Check that Headscale is running as intended:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
systemctl status headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
## Using Headscale
|
|
||||||
|
|
||||||
### Create a user
|
|
||||||
|
|
||||||
```shell
|
|
||||||
headscale users create myfirstuser
|
|
||||||
```
|
|
||||||
|
|
||||||
### Register a machine (normal login)
|
|
||||||
|
|
||||||
On a client machine, run the `tailscale` login command:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
tailscale up --login-server <YOUR_HEADSCALE_URL>
|
|
||||||
```
|
|
||||||
|
|
||||||
Register the machine:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
headscale nodes register --user myfirstuser --key <YOUR_MACHINE_KEY>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Register machine using a pre authenticated key
|
|
||||||
|
|
||||||
Generate a key using the command line:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
headscale preauthkeys create --user myfirstuser --reusable --expiration 24h
|
|
||||||
```
|
|
||||||
|
|
||||||
This will return a pre-authenticated key that is used to
|
|
||||||
connect a node to `headscale` during the `tailscale` command:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
|
|
||||||
```
|
|
||||||
|
|
@ -1,202 +0,0 @@
|
||||||
# Running headscale on OpenBSD
|
|
||||||
|
|
||||||
!!! warning "Community documentation"
|
|
||||||
|
|
||||||
This page is not actively maintained by the headscale authors and is
|
|
||||||
written by community members. It is _not_ verified by `headscale` developers.
|
|
||||||
|
|
||||||
**It might be outdated and it might miss necessary steps**.
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
|
|
||||||
This documentation has the goal of showing a user how-to install and run `headscale` on OpenBSD.
|
|
||||||
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.
|
|
||||||
|
|
||||||
## Install `headscale`
|
|
||||||
|
|
||||||
1. Install from ports
|
|
||||||
|
|
||||||
You can install headscale from ports by running `pkg_add headscale`.
|
|
||||||
|
|
||||||
1. Install from source
|
|
||||||
|
|
||||||
```shell
|
|
||||||
# Install prerequistes
|
|
||||||
pkg_add go
|
|
||||||
|
|
||||||
git clone https://github.com/juanfont/headscale.git
|
|
||||||
|
|
||||||
cd headscale
|
|
||||||
|
|
||||||
# optionally checkout a release
|
|
||||||
# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest
|
|
||||||
# option b. get latest tag, this may be a beta release
|
|
||||||
latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
|
|
||||||
|
|
||||||
git checkout $latestTag
|
|
||||||
|
|
||||||
go build -ldflags="-s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=$latestTag" github.com/juanfont/headscale
|
|
||||||
|
|
||||||
# make it executable
|
|
||||||
chmod a+x headscale
|
|
||||||
|
|
||||||
# copy it to /usr/local/sbin
|
|
||||||
cp headscale /usr/local/sbin
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Install from source via cross compile
|
|
||||||
|
|
||||||
```shell
|
|
||||||
# Install prerequistes
|
|
||||||
# 1. go v1.20+: headscale newer than 0.21 needs go 1.20+ to compile
|
|
||||||
# 2. gmake: Makefile in the headscale repo is written in GNU make syntax
|
|
||||||
|
|
||||||
git clone https://github.com/juanfont/headscale.git
|
|
||||||
|
|
||||||
cd headscale
|
|
||||||
|
|
||||||
# optionally checkout a release
|
|
||||||
# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest
|
|
||||||
# option b. get latest tag, this may be a beta release
|
|
||||||
latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
|
|
||||||
|
|
||||||
git checkout $latestTag
|
|
||||||
|
|
||||||
make build GOOS=openbsd
|
|
||||||
|
|
||||||
# copy headscale to openbsd machine and put it in /usr/local/sbin
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configure and run `headscale`
|
|
||||||
|
|
||||||
1. Prepare a directory to hold `headscale` configuration and the [SQLite](https://www.sqlite.org/) database:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
# Directory for configuration
|
|
||||||
|
|
||||||
mkdir -p /etc/headscale
|
|
||||||
|
|
||||||
# Directory for database, and other variable data (like certificates)
|
|
||||||
mkdir -p /var/lib/headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Create a `headscale` configuration:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
touch /etc/headscale/config.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
**(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository.
|
|
||||||
|
|
||||||
1. Start the headscale server:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
headscale serve
|
|
||||||
```
|
|
||||||
|
|
||||||
This command will start `headscale` in the current terminal session.
|
|
||||||
|
|
||||||
***
|
|
||||||
|
|
||||||
To continue the tutorial, open a new terminal and let it run in the background.
|
|
||||||
Alternatively use terminal emulators like [tmux](https://github.com/tmux/tmux).
|
|
||||||
|
|
||||||
To run `headscale` in the background, please follow the steps in the [rc.d section](#running-headscale-in-the-background-with-rcd) before continuing.
|
|
||||||
|
|
||||||
1. Verify `headscale` is running:
|
|
||||||
|
|
||||||
Verify `headscale` is available:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
curl http://127.0.0.1:9090/metrics
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)):
|
|
||||||
|
|
||||||
```shell
|
|
||||||
headscale users create myfirstuser
|
|
||||||
```
|
|
||||||
|
|
||||||
### Register a machine (normal login)
|
|
||||||
|
|
||||||
On a client machine, execute the `tailscale` login command:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
tailscale up --login-server YOUR_HEADSCALE_URL
|
|
||||||
```
|
|
||||||
|
|
||||||
Register the machine:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
headscale nodes register --user myfirstuser --key <YOUR_MACHINE_KEY>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Register machine using a pre authenticated key
|
|
||||||
|
|
||||||
Generate a key using the command line:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
headscale preauthkeys create --user myfirstuser --reusable --expiration 24h
|
|
||||||
```
|
|
||||||
|
|
||||||
This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
|
|
||||||
```
|
|
||||||
|
|
||||||
## Running `headscale` in the background with rc.d
|
|
||||||
|
|
||||||
This section demonstrates how to run `headscale` as a service in the background with [rc.d](https://man.openbsd.org/rc.d).
|
|
||||||
|
|
||||||
1. Create a rc.d service at `/etc/rc.d/headscale` containing:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
#!/bin/ksh
|
|
||||||
|
|
||||||
daemon="/usr/local/sbin/headscale"
|
|
||||||
daemon_logger="daemon.info"
|
|
||||||
daemon_user="root"
|
|
||||||
daemon_flags="serve"
|
|
||||||
daemon_timeout=60
|
|
||||||
|
|
||||||
. /etc/rc.d/rc.subr
|
|
||||||
|
|
||||||
rc_bg=YES
|
|
||||||
rc_reload=NO
|
|
||||||
|
|
||||||
rc_cmd $1
|
|
||||||
```
|
|
||||||
|
|
||||||
1. `/etc/rc.d/headscale` needs execute permission:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
chmod a+x /etc/rc.d/headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Start `headscale` service:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
rcctl start headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Make `headscale` service start at boot:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
rcctl enable headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Verify the headscale service:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
rcctl check headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
Verify `headscale` is available:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
curl http://127.0.0.1:9090/metrics
|
|
||||||
```
|
|
||||||
|
|
||||||
`headscale` will now run in the background and start at boot.
|
|
||||||
|
|
@ -1,136 +0,0 @@
|
||||||
# Running headscale on Sealos
|
|
||||||
|
|
||||||
!!! warning "Community documentation"
|
|
||||||
|
|
||||||
This page is not actively maintained by the headscale authors and is
|
|
||||||
written by community members. It is _not_ verified by `headscale` developers.
|
|
||||||
|
|
||||||
**It might be outdated and it might miss necessary steps**.
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
|
|
||||||
This documentation has the goal of showing a user how-to run `headscale` on Sealos.
|
|
||||||
|
|
||||||
## Running headscale server
|
|
||||||
|
|
||||||
1. Click the following prebuilt template:
|
|
||||||
|
|
||||||
[](https://cloud.sealos.io/?openapp=system-template%3FtemplateName%3Dheadscale)
|
|
||||||
|
|
||||||
2. Click "Deploy Application" on the template page to start deployment. Upon completion, two applications appear: Headscale, and its [visual interface](https://github.com/GoodiesHQ/headscale-admin).
|
|
||||||
3. Once deployment concludes, click 'Details' on the Headscale application page to navigate to the application's details.
|
|
||||||
4. Wait for the application's status to switch to running. For accessing the headscale server, the Public Address associated with port 8080 is the address of the headscale server. To access the Headscale console, simply append `/admin/` to the Headscale public URL.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
5. Click on 'Terminal' button on the right side of the details to access the Terminal of the headscale application. then create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
headscale users create myfirstuser
|
|
||||||
```
|
|
||||||
|
|
||||||
### Register a machine (normal login)
|
|
||||||
|
|
||||||
On a client machine, execute the `tailscale` login command:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# replace <YOUR_HEADSCALE_URL> with the public domain provided by Sealos
|
|
||||||
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:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
headscale nodes register --user myfirstuser --key <YOUR_MACHINE_KEY>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Register machine using a pre authenticated key
|
|
||||||
|
|
||||||
click on 'Terminal' button on the right side of the headscale application's detail page to access the Terminal of the headscale application, then generate a key using the command line:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
headscale preauthkeys create --user myfirstuser --reusable --expiration 24h
|
|
||||||
```
|
|
||||||
|
|
||||||
This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
### 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, click on 'Terminal' button on the right side of the headscale application's detail page to access the Terminal of the headscale application, then generate a key:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
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:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
headscale apikeys list
|
|
||||||
```
|
|
||||||
|
|
||||||
and to expire a key:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
headscale apikeys expire --prefix "<PREFIX>"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Download and configure `headscale` client
|
|
||||||
|
|
||||||
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`
|
|
||||||
|
|
||||||
3. Make `headscale` executable:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
chmod +x /usr/local/bin/headscale
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Configure the CLI through Environment Variables
|
|
||||||
|
|
||||||
```shell
|
|
||||||
export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:443"
|
|
||||||
export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
|
|
||||||
```
|
|
||||||
|
|
||||||
In the headscale application's detail page, The Public Address corresponding to port 50443 corresponds to the value of <HEADSCALE ADDRESS>.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
for example:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
export HEADSCALE_CLI_ADDRESS="pwnjnnly.cloud.sealos.io:443"
|
|
||||||
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.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
> Reference: [Headscale Deployment and Usage Guide: Mastering Tailscale's Self-Hosting Basics](https://icloudnative.io/en/posts/how-to-set-up-or-migrate-headscale/)
|
|
||||||
25
docs/setup/install/cloud.md
Normal file
25
docs/setup/install/cloud.md
Normal file
|
|
@ -0,0 +1,25 @@
|
||||||
|
# Running headscale in a cloud
|
||||||
|
|
||||||
|
!!! warning "Community documentation"
|
||||||
|
|
||||||
|
This page is not actively maintained by the headscale authors and is
|
||||||
|
written by community members. It is _not_ verified by headscale developers.
|
||||||
|
|
||||||
|
**It might be outdated and it might miss necessary steps**.
|
||||||
|
|
||||||
|
## Sealos
|
||||||
|
|
||||||
|
[Deploy headscale as service on Sealos.](https://icloudnative.io/en/posts/how-to-set-up-or-migrate-headscale/)
|
||||||
|
|
||||||
|
1. Click the following prebuilt template:
|
||||||
|
|
||||||
|
[](https://cloud.sealos.io/?openapp=system-template%3FtemplateName%3Dheadscale)
|
||||||
|
|
||||||
|
2. Click "Deploy Application" on the template page to start deployment. Upon completion, two applications appear: headscale, and one of its [web interfaces](../../ref/integration/web-ui.md).
|
||||||
|
3. Once deployment concludes, click 'Details' on the headscale application page to navigate to the application's details.
|
||||||
|
4. Wait for the application's status to switch to running. For accessing the headscale server, the Public Address associated with port 8080 is the address of the headscale server. To access the headscale console, simply append `/admin/` to the headscale public URL.
|
||||||
|
|
||||||
|
!!! tip "Remote CLI"
|
||||||
|
|
||||||
|
Headscale can be managed remotely via its remote CLI support. See our [Controlling headscale with remote
|
||||||
|
CLI](../../ref/remote-cli.md) documentation for details.
|
||||||
55
docs/setup/install/community.md
Normal file
55
docs/setup/install/community.md
Normal file
|
|
@ -0,0 +1,55 @@
|
||||||
|
# Community packages
|
||||||
|
|
||||||
|
Several Linux distributions and community members provide packages for headscale. Those packages may be used instead of
|
||||||
|
the [official releases](./official.md) provided by the headscale maintainers. Such packages offer improved integration
|
||||||
|
for their targeted operating system and usually:
|
||||||
|
|
||||||
|
- setup a dedicated user account to run headscale
|
||||||
|
- provide a default configuration
|
||||||
|
- install headscale as system service
|
||||||
|
|
||||||
|
!!! warning "Community packages might be outdated"
|
||||||
|
|
||||||
|
The packages mentioned on this page might be outdated or unmaintained. Use the [official releases](./official.md) to
|
||||||
|
get the current stable version or to test pre-releases.
|
||||||
|
|
||||||
|
[](https://repology.org/project/headscale/versions)
|
||||||
|
|
||||||
|
## Arch Linux
|
||||||
|
|
||||||
|
Arch Linux offers a package for headscale, install via:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
pacman -S headscale
|
||||||
|
```
|
||||||
|
|
||||||
|
The [AUR package `headscale-git`](https://aur.archlinux.org/packages/headscale-git) can be used to build the current
|
||||||
|
development version.
|
||||||
|
|
||||||
|
## Fedora, RHEL, CentOS
|
||||||
|
|
||||||
|
A 3rd-party repository for various RPM based distributions is available at:
|
||||||
|
<https://copr.fedorainfracloud.org/coprs/jonathanspw/headscale/>. The site provides detailed setup and installation
|
||||||
|
instructions.
|
||||||
|
|
||||||
|
## Nix, NixOS
|
||||||
|
|
||||||
|
A Nix package is available as: `headscale`. See the [NixOS package site for installation
|
||||||
|
details](https://search.nixos.org/packages?show=headscale).
|
||||||
|
|
||||||
|
## Gentoo
|
||||||
|
|
||||||
|
```shell
|
||||||
|
emerge --ask net-vpn/headscale
|
||||||
|
```
|
||||||
|
|
||||||
|
Gentoo specific documentation is available [here](https://wiki.gentoo.org/wiki/User:Maffblaster/Drafts/Headscale).
|
||||||
|
|
||||||
|
## OpenBSD
|
||||||
|
|
||||||
|
Headscale is available in ports. The port installs headscale as system service with `rc.d` and provides usage
|
||||||
|
instructions upon installation.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
pkg_add headscale
|
||||||
|
```
|
||||||
|
|
@ -3,41 +3,31 @@
|
||||||
!!! warning "Community documentation"
|
!!! warning "Community documentation"
|
||||||
|
|
||||||
This page is not actively maintained by the headscale authors and is
|
This page is not actively maintained by the headscale authors and is
|
||||||
written by community members. It is _not_ verified by `headscale` developers.
|
written by community members. It is _not_ verified by headscale developers.
|
||||||
|
|
||||||
**It might be outdated and it might miss necessary steps**.
|
**It might be outdated and it might miss necessary steps**.
|
||||||
|
|
||||||
## Goal
|
This documentation has the goal of showing a user how-to set up and run headscale in a container.
|
||||||
|
|
||||||
This documentation has the goal of showing a user how-to set up and run `headscale` in a container.
|
|
||||||
[Docker](https://www.docker.com) is used as the reference container implementation, but there is no reason that it should
|
[Docker](https://www.docker.com) is used as the reference container implementation, but there is no reason that it should
|
||||||
not work with alternatives like [Podman](https://podman.io). The Docker image can be found on Docker Hub [here](https://hub.docker.com/r/headscale/headscale).
|
not work with alternatives like [Podman](https://podman.io). The Docker image can be found on Docker Hub [here](https://hub.docker.com/r/headscale/headscale).
|
||||||
|
|
||||||
## Configure and run `headscale`
|
## Configure and run headscale
|
||||||
|
|
||||||
1. Prepare a directory on the host Docker node in your directory of choice, used to hold `headscale` configuration and the [SQLite](https://www.sqlite.org/) database:
|
1. Prepare a directory on the host Docker node in your directory of choice, used to hold headscale configuration and the [SQLite](https://www.sqlite.org/) database:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
mkdir -p ./headscale/config
|
mkdir -p ./headscale/config
|
||||||
cd ./headscale
|
cd ./headscale
|
||||||
```
|
```
|
||||||
|
|
||||||
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. Download the example configuration for your chosen version and save it as: `/etc/headscale/config.yaml`. Adjust the
|
||||||
|
configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
|
||||||
- Using `wget`:
|
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
wget -O ./config/config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
|
sudo mkdir -p /etc/headscale
|
||||||
|
sudo nano /etc/headscale/config.yaml
|
||||||
```
|
```
|
||||||
|
|
||||||
- Using `curl`:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
curl https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml -o ./config/config.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
Modify the config file to your preferences before launching Docker container.
|
|
||||||
|
|
||||||
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`
|
||||||
in the next step.
|
in the next step.
|
||||||
|
|
@ -58,7 +48,7 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca
|
||||||
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.
|
||||||
|
|
||||||
This command will mount `config/` under `/etc/headscale`, forward port 8080 out of the container so the
|
This command will mount `config/` under `/etc/headscale`, forward port 8080 out of the container so the
|
||||||
`headscale` instance becomes available and then detach so headscale runs in the background.
|
headscale instance becomes available and then detach so headscale runs in the background.
|
||||||
|
|
||||||
Example `docker-compose.yaml`
|
Example `docker-compose.yaml`
|
||||||
|
|
||||||
|
|
@ -79,7 +69,8 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca
|
||||||
command: serve
|
command: serve
|
||||||
```
|
```
|
||||||
|
|
||||||
1. Verify `headscale` is running:
|
1. Verify headscale is running:
|
||||||
|
|
||||||
Follow the container logs:
|
Follow the container logs:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
|
|
@ -92,7 +83,7 @@ not work with alternatives like [Podman](https://podman.io). The Docker image ca
|
||||||
docker ps
|
docker ps
|
||||||
```
|
```
|
||||||
|
|
||||||
Verify `headscale` is available:
|
Verify headscale is available:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
curl http://127.0.0.1:9090/metrics
|
curl http://127.0.0.1:9090/metrics
|
||||||
|
|
@ -113,7 +104,7 @@ On a client machine, execute the `tailscale` login command:
|
||||||
tailscale up --login-server YOUR_HEADSCALE_URL
|
tailscale up --login-server YOUR_HEADSCALE_URL
|
||||||
```
|
```
|
||||||
|
|
||||||
To register a machine when running `headscale` in a container, take the headscale command and pass it to the container:
|
To register a machine when running headscale in a container, take the headscale command and pass it to the container:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
docker exec -it headscale \
|
docker exec -it headscale \
|
||||||
|
|
@ -129,7 +120,7 @@ docker exec -it headscale \
|
||||||
headscale preauthkeys create --user myfirstuser --reusable --expiration 24h
|
headscale preauthkeys create --user myfirstuser --reusable --expiration 24h
|
||||||
```
|
```
|
||||||
|
|
||||||
This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command:
|
This will return a pre-authenticated key that can be used to connect a node to headscale during the `tailscale` command:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
|
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
|
||||||
117
docs/setup/install/official.md
Normal file
117
docs/setup/install/official.md
Normal file
|
|
@ -0,0 +1,117 @@
|
||||||
|
# Official releases
|
||||||
|
|
||||||
|
Official releases for headscale are available as binaries for various platforms and DEB packages for Debian and Ubuntu.
|
||||||
|
Both are available on the [GitHub releases page](https://github.com/juanfont/headscale/releases).
|
||||||
|
|
||||||
|
## Using packages for Debian/Ubuntu (recommended)
|
||||||
|
|
||||||
|
It is recommended to use our DEB packages to install headscale on a Debian based system as those packages configure a
|
||||||
|
user to run headscale, provide a default configuration and ship with a systemd service file. Supported distributions are
|
||||||
|
Ubuntu 20.04 or newer, Debian 11 or newer.
|
||||||
|
|
||||||
|
1. Download the [latest headscale package](https://github.com/juanfont/headscale/releases/latest) for your platform (`.deb` for Ubuntu and Debian).
|
||||||
|
|
||||||
|
```shell
|
||||||
|
HEADSCALE_VERSION="" # See above URL for latest version, e.g. "X.Y.Z" (NOTE: do not add the "v" prefix!)
|
||||||
|
HEADSCALE_ARCH="" # Your system architecture, e.g. "amd64"
|
||||||
|
wget --output-document=headscale.deb \
|
||||||
|
"https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Install headscale:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
sudo apt install ./headscale.deb
|
||||||
|
```
|
||||||
|
|
||||||
|
1. [Configure headscale by editing the configuration file](../../ref/configuration.md):
|
||||||
|
|
||||||
|
```shell
|
||||||
|
sudo nano /etc/headscale/config.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Enable and start the headscale service:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
sudo systemctl enable --now headscale
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Verify that headscale is running as intended:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
sudo systemctl status headscale
|
||||||
|
```
|
||||||
|
|
||||||
|
## Using standalone binaries (advanced)
|
||||||
|
|
||||||
|
!!! warning "Advanced"
|
||||||
|
|
||||||
|
This installation method is considered advanced as one needs to take care of the headscale user and the systemd
|
||||||
|
service themselves. If possible, use the [DEB packages](#using-packages-for-debianubuntu-recommended) or a
|
||||||
|
[community package](./community.md) instead.
|
||||||
|
|
||||||
|
This section describes the installation of headscale according to the [Requirements and
|
||||||
|
assumptions](../requirements.md#assumptions). Headscale is run by a dedicated user and the service itself is managed by
|
||||||
|
systemd.
|
||||||
|
|
||||||
|
1. Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases):
|
||||||
|
|
||||||
|
```shell
|
||||||
|
sudo wget --output-document=/usr/local/bin/headscale \
|
||||||
|
https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Make `headscale` executable:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
sudo chmod +x /usr/local/bin/headscale
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Add a dedicated user to run headscale:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
sudo useradd \
|
||||||
|
--create-home \
|
||||||
|
--home-dir /var/lib/headscale/ \
|
||||||
|
--system \
|
||||||
|
--user-group \
|
||||||
|
--shell /usr/sbin/nologin \
|
||||||
|
headscale
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Download the example configuration for your chosen version and save it as: `/etc/headscale/config.yaml`. Adjust the
|
||||||
|
configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
sudo mkdir -p /etc/headscale
|
||||||
|
sudo nano /etc/headscale/config.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Copy [headscale's systemd service file](../../packaging/headscale.systemd.service) to
|
||||||
|
`/etc/systemd/system/headscale.service` and adjust it to suit your local setup. The following parameters likely need
|
||||||
|
to be modified: `ExecStart`, `WorkingDirectory`, `ReadWritePaths`.
|
||||||
|
|
||||||
|
1. In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with a path that is writable by the
|
||||||
|
`headscale` user or group:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
unix_socket: /var/run/headscale/headscale.sock
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Reload systemd to load the new configuration file:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
systemctl daemon-reload
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Enable and start the new headscale service:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
systemctl enable --now headscale
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Verify that headscale is running as intended:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
systemctl status headscale
|
||||||
|
```
|
||||||
63
docs/setup/install/source.md
Normal file
63
docs/setup/install/source.md
Normal file
|
|
@ -0,0 +1,63 @@
|
||||||
|
# Build from source
|
||||||
|
|
||||||
|
!!! warning "Community documentation"
|
||||||
|
|
||||||
|
This page is not actively maintained by the headscale authors and is
|
||||||
|
written by community members. It is _not_ verified by headscale developers.
|
||||||
|
|
||||||
|
**It might be outdated and it might miss necessary steps**.
|
||||||
|
|
||||||
|
Headscale can be built from source using the latest version of [Go](https://golang.org) and [Buf](https://buf.build)
|
||||||
|
(Protobuf generator). See the [Contributing section in the GitHub
|
||||||
|
README](https://github.com/juanfont/headscale#contributing) for more information.
|
||||||
|
|
||||||
|
## OpenBSD
|
||||||
|
|
||||||
|
### Install from source
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# Install prerequistes
|
||||||
|
pkg_add go
|
||||||
|
|
||||||
|
git clone https://github.com/juanfont/headscale.git
|
||||||
|
|
||||||
|
cd headscale
|
||||||
|
|
||||||
|
# optionally checkout a release
|
||||||
|
# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest
|
||||||
|
# option b. get latest tag, this may be a beta release
|
||||||
|
latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
|
||||||
|
|
||||||
|
git checkout $latestTag
|
||||||
|
|
||||||
|
go build -ldflags="-s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=$latestTag" github.com/juanfont/headscale
|
||||||
|
|
||||||
|
# make it executable
|
||||||
|
chmod a+x headscale
|
||||||
|
|
||||||
|
# copy it to /usr/local/sbin
|
||||||
|
cp headscale /usr/local/sbin
|
||||||
|
```
|
||||||
|
|
||||||
|
### Install from source via cross compile
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# Install prerequistes
|
||||||
|
# 1. go v1.20+: headscale newer than 0.21 needs go 1.20+ to compile
|
||||||
|
# 2. gmake: Makefile in the headscale repo is written in GNU make syntax
|
||||||
|
|
||||||
|
git clone https://github.com/juanfont/headscale.git
|
||||||
|
|
||||||
|
cd headscale
|
||||||
|
|
||||||
|
# optionally checkout a release
|
||||||
|
# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest
|
||||||
|
# option b. get latest tag, this may be a beta release
|
||||||
|
latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
|
||||||
|
|
||||||
|
git checkout $latestTag
|
||||||
|
|
||||||
|
make build GOOS=openbsd
|
||||||
|
|
||||||
|
# copy headscale to openbsd machine and put it in /usr/local/sbin
|
||||||
|
```
|
||||||
28
docs/setup/requirements.md
Normal file
28
docs/setup/requirements.md
Normal file
|
|
@ -0,0 +1,28 @@
|
||||||
|
# Requirements
|
||||||
|
|
||||||
|
Headscale should just work as long as the following requirements are met:
|
||||||
|
|
||||||
|
- A server with a public IP address for headscale. A dual-stack setup with a public IPv4 and a public IPv6 address is
|
||||||
|
recommended.
|
||||||
|
- Headscale is served via HTTPS on port 443[^1].
|
||||||
|
- A reasonably modern Linux or BSD based operating system.
|
||||||
|
- A dedicated user account to run headscale.
|
||||||
|
- A little bit of command line knowledge to configure and operate headscale.
|
||||||
|
|
||||||
|
## Assumptions
|
||||||
|
|
||||||
|
The headscale documentation and the provided examples are written with a few assumptions in mind:
|
||||||
|
|
||||||
|
- Headscale is running as system service via a dedicated user `headscale`.
|
||||||
|
- The [configuration](../ref/configuration.md) is loaded from `/etc/headscale/config.yaml`.
|
||||||
|
- SQLite is used as database.
|
||||||
|
- The data directory for headscale (used for private keys, ACLs, SQLite database, …) is located in `/var/lib/headscale`.
|
||||||
|
- URLs and values that need to be replaced by the user are either denoted as `<VALUE_TO_CHANGE>` or use placeholder
|
||||||
|
values such as `headscale.example.com`.
|
||||||
|
|
||||||
|
Please adjust to your local environment accordingly.
|
||||||
|
|
||||||
|
[^1]:
|
||||||
|
The Tailscale client assumes HTTPS on port 443 in certain situations. Serving headscale either via HTTP or via HTTPS
|
||||||
|
on a port other than 443 is possible but sticking with HTTPS on port 443 is strongly recommended for production
|
||||||
|
setups. See [issue 2164](https://github.com/juanfont/headscale/issues/2164) for more information.
|
||||||
10
docs/setup/upgrade.md
Normal file
10
docs/setup/upgrade.md
Normal file
|
|
@ -0,0 +1,10 @@
|
||||||
|
# Upgrade an existing installation
|
||||||
|
|
||||||
|
An existing headscale installation can be updated to a new version:
|
||||||
|
|
||||||
|
- Read the announcement on the [GitHub releases](https://github.com/juanfont/headscale/releases) page for the new
|
||||||
|
version. It lists the changes of the release along with possible breaking changes.
|
||||||
|
- **Create a backup of your database.**
|
||||||
|
- Update headscale to the new version, preferably by following the same installation method.
|
||||||
|
- Compare and update the [configuration](../ref/configuration.md) file.
|
||||||
|
- Restart headscale.
|
||||||
|
|
@ -1,8 +1,6 @@
|
||||||
# Connecting an Android client
|
# Connecting an Android client
|
||||||
|
|
||||||
## Goal
|
This documentation has the goal of showing how a user can use the official Android [Tailscale](https://tailscale.com) client with headscale.
|
||||||
|
|
||||||
This documentation has the goal of showing how a user can use the official Android [Tailscale](https://tailscale.com) client with `headscale`.
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
|
|
@ -1,8 +1,6 @@
|
||||||
# Connecting an Apple client
|
# Connecting an Apple client
|
||||||
|
|
||||||
## Goal
|
This documentation has the goal of showing how a user can use the official iOS and macOS [Tailscale](https://tailscale.com) clients with headscale.
|
||||||
|
|
||||||
This documentation has the goal of showing how a user can use the official iOS and macOS [Tailscale](https://tailscale.com) clients with `headscale`.
|
|
||||||
|
|
||||||
!!! info "Instructions on your headscale instance"
|
!!! info "Instructions on your headscale instance"
|
||||||
|
|
||||||
|
|
@ -1,8 +1,6 @@
|
||||||
# Connecting a Windows client
|
# Connecting a Windows client
|
||||||
|
|
||||||
## Goal
|
This documentation has the goal of showing how a user can use the official Windows [Tailscale](https://tailscale.com) client with headscale.
|
||||||
|
|
||||||
This documentation has the goal of showing how a user can use the official Windows [Tailscale](https://tailscale.com) client with `headscale`.
|
|
||||||
|
|
||||||
!!! info "Instructions on your headscale instance"
|
!!! info "Instructions on your headscale instance"
|
||||||
|
|
||||||
|
|
@ -45,7 +43,7 @@ If you are seeing repeated messages like:
|
||||||
[GIN] 2022/02/10 - 16:39:34 | 200 | 1.105306ms | 127.0.0.1 | POST "/machine/redacted"
|
[GIN] 2022/02/10 - 16:39:34 | 200 | 1.105306ms | 127.0.0.1 | POST "/machine/redacted"
|
||||||
```
|
```
|
||||||
|
|
||||||
in your `headscale` output, turn on `DEBUG` logging and look for:
|
in your headscale output, turn on `DEBUG` logging and look for:
|
||||||
|
|
||||||
```
|
```
|
||||||
2022-02-11T00:59:29Z DBG Machine registration has expired. Sending a authurl to register machine=redacted
|
2022-02-11T00:59:29Z DBG Machine registration has expired. Sending a authurl to register machine=redacted
|
||||||
132
docs/usage/getting-started.md
Normal file
132
docs/usage/getting-started.md
Normal file
|
|
@ -0,0 +1,132 @@
|
||||||
|
# Getting started
|
||||||
|
|
||||||
|
This page helps you get started with headscale and provides a few usage examples for the headscale command line tool
|
||||||
|
`headscale`.
|
||||||
|
|
||||||
|
!!! note "Prerequisites"
|
||||||
|
|
||||||
|
* Headscale is installed and running as system service. Read the [setup section](../setup/requirements.md) for
|
||||||
|
installation instructions.
|
||||||
|
* The configuration file exists and is adjusted to suit your environment, see
|
||||||
|
[Configuration](../ref/configuration.md) for details.
|
||||||
|
* The Tailscale client is installed, see [Client and operating system support](../about/clients.md) for more
|
||||||
|
information.
|
||||||
|
|
||||||
|
## Getting help
|
||||||
|
|
||||||
|
The `headscale` command line tool provides built-in help. To show available commands along with their arguments and
|
||||||
|
options, run:
|
||||||
|
|
||||||
|
=== "Native"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# Show help
|
||||||
|
headscale help
|
||||||
|
|
||||||
|
# Show help for a specific command
|
||||||
|
headscale <COMMAND> --help
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Container"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
# Show help
|
||||||
|
docker exec -it headscale \
|
||||||
|
headscale help
|
||||||
|
|
||||||
|
# Show help for a specific command
|
||||||
|
docker exec -it headscale \
|
||||||
|
headscale <COMMAND> --help
|
||||||
|
```
|
||||||
|
|
||||||
|
## Manage users
|
||||||
|
|
||||||
|
In headscale, a node (also known as machine or device) is always assigned to a specific user, a
|
||||||
|
[tailnet](https://tailscale.com/kb/1136/tailnet/). Such users can be managed with the `headscale users` command. Invoke
|
||||||
|
the built-in help for more information: `headscale users --help`.
|
||||||
|
|
||||||
|
### Create a user
|
||||||
|
|
||||||
|
=== "Native"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
headscale users create <USER>
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Container"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
docker exec -it headscale \
|
||||||
|
headscale users create <USER>
|
||||||
|
```
|
||||||
|
|
||||||
|
### List existing users
|
||||||
|
|
||||||
|
=== "Native"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
headscale users list
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Container"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
docker exec -it headscale \
|
||||||
|
headscale users list
|
||||||
|
```
|
||||||
|
|
||||||
|
## Register a node
|
||||||
|
|
||||||
|
One has to register a node first to use headscale as coordination with Tailscale. The following examples work for the
|
||||||
|
Tailscale client on Linux/BSD operating systems. Alternatively, follow the instructions to connect
|
||||||
|
[Android](connect/android.md), [Apple](connect/apple.md) or [Windows](connect/windows.md) devices.
|
||||||
|
|
||||||
|
### Normal, interactive login
|
||||||
|
|
||||||
|
On a client machine, run the `tailscale up` command and provide the FQDN of your headscale instance as argument:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
tailscale up --login-server <YOUR_HEADSCALE_URL>
|
||||||
|
```
|
||||||
|
|
||||||
|
Usually, a browser window with further instructions is opened and contains the value for `<YOUR_MACHINE_KEY>`. Approve
|
||||||
|
and register the node on your headscale server:
|
||||||
|
|
||||||
|
=== "Native"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Container"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
docker exec -it headscale \
|
||||||
|
headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Using a preauthkey
|
||||||
|
|
||||||
|
It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the
|
||||||
|
headscale instance. By default, the key is valid for one hour and can only be used once (see `headscale preauthkeys
|
||||||
|
--help` for other options):
|
||||||
|
|
||||||
|
=== "Native"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
headscale preauthkeys create --user <USER>
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Container"
|
||||||
|
|
||||||
|
```shell
|
||||||
|
docker exec -it headscale \
|
||||||
|
headscale preauthkeys create --user <USER>
|
||||||
|
```
|
||||||
|
|
||||||
|
The command returns the preauthkey on success which is used to connect a node to the headscale instance via the
|
||||||
|
`tailscale up` command:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
|
||||||
|
```
|
||||||
71
mkdocs.yml
71
mkdocs.yml
|
|
@ -66,9 +66,26 @@ exclude_docs: |
|
||||||
plugins:
|
plugins:
|
||||||
- search:
|
- search:
|
||||||
separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
|
separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
|
||||||
|
- macros:
|
||||||
|
- include-markdown:
|
||||||
- minify:
|
- minify:
|
||||||
minify_html: true
|
minify_html: true
|
||||||
- social: {}
|
- social: {}
|
||||||
|
- redirects:
|
||||||
|
redirect_maps:
|
||||||
|
acls.md: ref/acls.md
|
||||||
|
android-client.md: usage/connect/android.md
|
||||||
|
apple-client.md: usage/connect/apple.md
|
||||||
|
dns-records.md: ref/dns.md
|
||||||
|
exit-node.md: ref/exit-node.md
|
||||||
|
faq.md: about/faq.md
|
||||||
|
iOS-client.md: usage/connect/apple.md#ios
|
||||||
|
oidc.md: ref/oidc.md
|
||||||
|
remote-cli.md: ref/remote-cli.md
|
||||||
|
reverse-proxy.md: ref/integration/reverse-proxy.md
|
||||||
|
tls.md: ref/tls.md
|
||||||
|
web-ui.md: ref/integration/web-ui.md
|
||||||
|
windows-client.md: usage/connect/windows.md
|
||||||
|
|
||||||
# Customization
|
# Customization
|
||||||
extra:
|
extra:
|
||||||
|
|
@ -83,6 +100,8 @@ extra:
|
||||||
link: https://github.com/juanfont/headscale/pkgs/container/headscale
|
link: https://github.com/juanfont/headscale/pkgs/container/headscale
|
||||||
- icon: fontawesome/brands/discord
|
- icon: fontawesome/brands/discord
|
||||||
link: https://discord.gg/c84AZQhmpx
|
link: https://discord.gg/c84AZQhmpx
|
||||||
|
headscale:
|
||||||
|
version: 0.23.0
|
||||||
|
|
||||||
# Extensions
|
# Extensions
|
||||||
markdown_extensions:
|
markdown_extensions:
|
||||||
|
|
@ -128,23 +147,39 @@ markdown_extensions:
|
||||||
|
|
||||||
# Page tree
|
# Page tree
|
||||||
nav:
|
nav:
|
||||||
- Home: index.md
|
- Welcome: index.md
|
||||||
- FAQ: faq.md
|
- About:
|
||||||
- Getting started:
|
- FAQ: about/faq.md
|
||||||
|
- Features: about/features.md
|
||||||
|
- Clients: about/clients.md
|
||||||
|
- Getting help: about/help.md
|
||||||
|
- Releases: about/releases.md
|
||||||
|
- Contributing: about/contributing.md
|
||||||
|
- Sponsor: about/sponsor.md
|
||||||
|
|
||||||
|
- Setup:
|
||||||
|
- Requirements and Assumptions: setup/requirements.md
|
||||||
- Installation:
|
- Installation:
|
||||||
- Linux: running-headscale-linux.md
|
- Official releases: setup/install/official.md
|
||||||
- OpenBSD: running-headscale-openbsd.md
|
- Community packages: setup/install/community.md
|
||||||
- Container: running-headscale-container.md
|
- Container: setup/install/container.md
|
||||||
- Configuration:
|
- Cloud: setup/install/cloud.md
|
||||||
- Web UI: web-ui.md
|
- Build from source: setup/install/source.md
|
||||||
- OIDC authentication: oidc.md
|
- Upgrade: setup/upgrade.md
|
||||||
- Exit node: exit-node.md
|
|
||||||
- Reverse proxy: reverse-proxy.md
|
|
||||||
- TLS: tls.md
|
|
||||||
- ACLs: acls.md
|
|
||||||
- Custom DNS records: dns-records.md
|
|
||||||
- Remote CLI: remote-cli.md
|
|
||||||
- Usage:
|
- Usage:
|
||||||
- Android: android-client.md
|
- Getting started: usage/getting-started.md
|
||||||
- Apple: apple-client.md
|
- Connect a node:
|
||||||
- Windows: windows-client.md
|
- Android: usage/connect/android.md
|
||||||
|
- Apple: usage/connect/apple.md
|
||||||
|
- Windows: usage/connect/windows.md
|
||||||
|
- Reference:
|
||||||
|
- Configuration: ref/configuration.md
|
||||||
|
- OIDC authentication: ref/oidc.md
|
||||||
|
- Exit node: ref/exit-node.md
|
||||||
|
- TLS: ref/tls.md
|
||||||
|
- ACLs: ref/acls.md
|
||||||
|
- DNS: ref/dns.md
|
||||||
|
- Remote CLI: ref/remote-cli.md
|
||||||
|
- Integration:
|
||||||
|
- Reverse proxy: ref/integration/reverse-proxy.md
|
||||||
|
- Web UI: ref/integration/web-ui.md
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue