Merge pull request #262 from kradalby/improve-docs

Rewrite main documentation

cmd/headscale/headscale_test.go

@@ -54,9 +54,8 @@ func (*Suite) TestConfigLoading(c *check.C) {
 	// Test that config file was interpreted correctly
 	c.Assert(viper.GetString("server_url"), check.Equals, "http://127.0.0.1:8080")
 	c.Assert(viper.GetString("listen_addr"), check.Equals, "0.0.0.0:8080")
-	c.Assert(viper.GetStringSlice("derp.paths")[0], check.Equals, "derp-example.yaml")
 	c.Assert(viper.GetString("db_type"), check.Equals, "sqlite3")
-	c.Assert(viper.GetString("db_path"), check.Equals, "db.sqlite")
+	c.Assert(viper.GetString("db_path"), check.Equals, "/var/lib/headscale/db.sqlite")
 	c.Assert(viper.GetString("tls_letsencrypt_hostname"), check.Equals, "")
 	c.Assert(viper.GetString("tls_letsencrypt_listen"), check.Equals, ":http")
 	c.Assert(viper.GetString("tls_letsencrypt_challenge_type"), check.Equals, "HTTP-01")

config-example.yaml

@@ -1,39 +1,65 @@
 ---
+# headscale will look for a configuration file named `config.yaml` (or `config.json`) in the following order:
+#
+# - `/etc/headscale`
+# - `~/.headscale`
+# - current working directory
+
 # The url clients will connect to.
-# Typically this will be a domain.
+# Typically this will be a domain like:
+#
+# https://myheadscale.example.com:443
+#
 server_url: http://127.0.0.1:8080
 
 # Address to listen to / bind to on the server
+#
 listen_addr: 0.0.0.0:8080
 
-# Private key file which will be
+# Private key used encrypt the traffic between headscale
+# and Tailscale clients.
+# The private key file which will be
 # autogenerated if it's missing
-private_key_path: private.key
+private_key_path: /var/lib/headscale/private.key
 
+# DERP is a relay system that Tailscale uses when a direct
+# connection cannot be established.
+# https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp
+#
+# headscale needs a list of DERP servers that can be presented
+# to the clients.
 derp:
   # List of externally available DERP maps encoded in JSON
   urls:
     - https://controlplane.tailscale.com/derpmap/default
 
   # Locally available DERP map files encoded in YAML
-  paths:
-    - derp-example.yaml
+  #
+  # This option is mostly interesting for people hosting
+  # their own DERP servers:
+  # https://tailscale.com/kb/1118/custom-derp-servers/
+  #
+  # paths:
+  #   - /etc/headscale/derp-example.yaml
+  paths: []
 
   # If enabled, a worker will be set up to periodically
   # refresh the given sources and update the derpmap
   # will be set up.
   auto_update_enabled: true
 
-  # How often should we check for updates?
+  # How often should we check for DERP updates?
   update_frequency: 24h
 
-# Disables the automatic check for updates on startup
+# Disables the automatic check for headscale updates on startup
 disable_check_updates: false
+
+# Time before an inactive ephemeral node is deleted?
 ephemeral_node_inactivity_timeout: 30m
 
 # SQLite config
 db_type: sqlite3
-db_path: db.sqlite
+db_path: /var/lib/headscale/db.sqlite
 
 # # Postgres config
 # db_type: postgres
@@ -43,35 +69,87 @@ db_path: db.sqlite
 # db_user: foo
 # db_pass: bar
 
+### TLS configuration
+#
+## Let's encrypt / ACME
+#
+# headscale supports automatically requesting and setting up
+# TLS for a domain with Let's Encrypt.
+#
+# URL to ACME directory
 acme_url: https://acme-v02.api.letsencrypt.org/directory
+
+# Email to register with ACME provider
 acme_email: ""
 
+# Domain name to request a TLS certificate for:
 tls_letsencrypt_hostname: ""
-tls_letsencrypt_listen: ":http"
-tls_letsencrypt_cache_dir: ".cache"
+
+# Path to store certificates and metadata needed by
+# letsencrypt
+tls_letsencrypt_cache_dir: /var/lib/headscale/cache
+
+# Type of ACME challenge to use, currently supported types:
+# HTTP-01 or TLS_ALPN-01
+# See [docs/tls.md](docs/tls.md) for more information
 tls_letsencrypt_challenge_type: HTTP-01
+# When HTTP-01 challenge is chosen, letsencrypt must set up a
+# verification endpoint, and it will be listning on:
+# :http = port 80
+tls_letsencrypt_listen: ":http"
 
+## Use already defined certificates:
 tls_cert_path: ""
 tls_key_path: ""
 
 log_level: info
 
 # Path to a file containg ACL policies.
+# Recommended path: /etc/headscale/acl.hujson
 acl_policy_path: ""
 
+## DNS
+#
+# headscale supports Tailscale's DNS configuration and MagicDNS.
+# Please have a look to their KB to better understand the concepts:
+#
+# - https://tailscale.com/kb/1054/dns/
+# - https://tailscale.com/kb/1081/magicdns/
+# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
+#
 dns_config:
-  # Upstream DNS servers
+  # List of DNS servers to expose to clients.
   nameservers:
     - 1.1.1.1
+
+  # Split DNS (see https://tailscale.com/kb/1054/dns/),
+  # list of search domains and the DNS to query for each one.
+  #
+  # restricted_nameservers:
+  #   foo.bar.com:
+  #     - 1.1.1.1
+  #   darp.headscale.net:
+  #     - 1.1.1.1
+  #     - 8.8.8.8
+
+  # Search domains to inject.
   domains: []
 
+  # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
+  # Only works if there is at least a nameserver defined.
   magic_dns: true
+
+  # Defines the base domain to create the hostnames for MagicDNS.
+  # `base_domain` must be a FQDNs, without the trailing dot.
+  # The FQDN of the hosts will be
+  # `hostname.namespace.base_domain` (e.g., _myhost.mynamespace.example.com_).
   base_domain: example.com
 
 # Unix socket used for the CLI to connect without authentication
 # Note: for local development, you probably want to change this to:
 # unix_socket: ./headscale.sock
 unix_socket: /var/run/headscale.sock
+#
 # headscale supports experimental OpenID connect support,
 # it is still being tested and might have some bugs, please
 # help us test it.

docs/README.md

@@ -1,7 +1,42 @@
-# Official headscale documentation
+# headscale documentation
 
-- [Configuration](Configuration.md)
-- [Running](Running.md)
-- [DNS](DNS.md)
-- [TLS](TLS.md)
-- [Glossary](Glossary.md)
+This page contains the official and community contributed documentation for `headscale`.
+
+If you are having trouble with following the documentation or get unexpected results,
+please ask on [Discord](https://discord.gg/XcQxk2VHjx) instead of opening an Issue.
+
+## Official documentation
+
+### How-to
+
+- [Running headscale on Linux](running-headscale-linux.md)
+
+### References
+
+- [Configuration](../config-example.yaml)
+- [Glossary](glossary.md)
+- [TLS](tls.md)
+
+## Community documentation
+
+Community documentation 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**.
+
+- [Running headscale in a container](running-headscale-container.md)
+
+## Misc
+
+### Policy ACLs
+
+Headscale implements the same policy ACLs as Tailscale.com, adapted to the self-hosted environment.
+
+For instance, instead of referring to users when defining groups you must
+use namespaces (which are the equivalent to user/logins in Tailscale.com).
+
+Please check https://tailscale.com/kb/1018/acls/, and `./tests/acls/` in this repo for working examples.
+
+### Apple devices
+
+An endpoint with information on how to connect your Apple devices (currently macOS only) is available at `/apple` on your running instance.