From 406208244557827d911d04b5e8b73fc00a6def2d Mon Sep 17 00:00:00 2001 From: tituspijean Date: Sun, 11 Jun 2023 12:23:27 +0200 Subject: [PATCH] Documentation --- doc/ADMIN.md | 9 ++++++++ doc/DESCRIPTION.md | 53 ++++++++++++++++++++++++++++++++++++++++------ doc/DISCLAIMER.md | 12 ----------- manifest.toml | 17 ++++++++------- 4 files changed, 65 insertions(+), 26 deletions(-) create mode 100644 doc/ADMIN.md delete mode 100644 doc/DISCLAIMER.md diff --git a/doc/ADMIN.md b/doc/ADMIN.md new file mode 100644 index 0000000..79eb5fc --- /dev/null +++ b/doc/ADMIN.md @@ -0,0 +1,9 @@ +You are encouraged to tweak Headscale's configuration in `__INSTALL_DIR__/config.yaml`. +Feel free to experiment and report your use cases in YunoHost's forum and chatrooms! + +Some technical notes: +- [Internal DERP server](https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp) is not enabled +- The server is allowed to use the [DERP servers operated by Tailscale](https://controlplane.tailscale.com/derpmap/default) +- The database used to store user and nodes information is SQLite. It should be fine for YunoHost's current small-scale self-hosting mindset. +- Headscale will push DNS servers to its clients. The configuration includes FDN's open resolvers. ([French Data Network](https://www.fdn.fr/actions/dns/), associative ISP) + diff --git a/doc/DESCRIPTION.md b/doc/DESCRIPTION.md index 0685205..fa6f659 100644 --- a/doc/DESCRIPTION.md +++ b/doc/DESCRIPTION.md @@ -1,9 +1,50 @@ -Some long and extensive description of what the app is and does, lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. +An open source, self-hosted implementation of the Tailscale control server. + +### What is Tailscale + +Tailscale is [a modern VPN](https://tailscale.com/) built on top of +[Wireguard](https://www.wireguard.com/). +It [works like an overlay network](https://tailscale.com/blog/how-tailscale-works/) +between the computers of your networks - using +[NAT traversal](https://tailscale.com/blog/how-nat-traversal-works/). + +Everything in Tailscale is Open Source, except the GUI clients for proprietary OS +(Windows and macOS/iOS), and the control server. + +The control server works as an exchange point of Wireguard public keys for the +nodes in the Tailscale network. It assigns the IP addresses of the clients, +creates the boundaries between each user, enables sharing machines between users, +and exposes the advertised routes of your nodes. + +A [Tailscale network (tailnet)](https://tailscale.com/kb/1136/tailnet/) is private +network which Tailscale assigns to a user in terms of private users or an +organisation. + +### Design goal + +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. +It implements a narrow scope, a single Tailnet, suitable for a personal use, or a small +open-source organisation. ### Features -- Ut enim ad minim veniam, quis nostrud exercitation ullamco ; -- Laboris nisi ut aliquip ex ea commodo consequat ; -- Duis aute irure dolor in reprehenderit in voluptate ; -- Velit esse cillum dolore eu fugiat nulla pariatur ; -- Excepteur sint occaecat cupidatat non proident, sunt in culpa." + +- Full "base" support of Tailscale's 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) +- Support for multiple IP ranges in the tailnet +- 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) + +*from Headscale's README. See Links section below.* diff --git a/doc/DISCLAIMER.md b/doc/DISCLAIMER.md deleted file mode 100644 index aded581..0000000 --- a/doc/DISCLAIMER.md +++ /dev/null @@ -1,12 +0,0 @@ -* Any known limitations, constrains or stuff not working, such as (but not limited to): - * requiring a full dedicated domain ? - * architectures not supported ? - * not-working single-sign on or LDAP integration ? - * the app requires an important amount of RAM / disk / .. to install or to work properly - * etc... - -* Other infos that people should be aware of, such as: - * any specific step to perform after installing (such as manually finishing the install, specific admin credentials, ...) - * how to configure / administrate the application if it ain't obvious - * upgrade process / specificities / things to be aware of ? - * security considerations ? diff --git a/manifest.toml b/manifest.toml index 08b5104..958928b 100644 --- a/manifest.toml +++ b/manifest.toml @@ -10,21 +10,22 @@ maintainers = ["tituspijean"] [upstream] license = "BSD-3-Clause" -admindoc = "https://github.com/juanfont/headscale/tree/main/docs" +admindoc = "https://headscale.net/" userdoc = "https://tailscale.com/kb/" code = "https://github.com/juanfont/headscale" -website = "https://tailscale.com/" +website = "https://headscale.net/" cpe = "cpe:2.3:a:tailscale:tailscale" +fund = "https://ko-fi.com/headscale [integration] yunohost = ">= 11.0.0" architectures = "all" multi_instance = false -ldap = "?" # FIXME: replace with true, false, or "not_relevant". Not to confuse with the "sso" key : the "ldap" key corresponds to wether or not a user *can* login on the app using its YunoHost credentials. -sso = "?" # FIXME: replace with true, false, or "not_relevant". Not to confuse with the "ldap" key : the "sso" key corresponds to wether or not a user is *automatically logged-in* on the app when logged-in on the YunoHost portal. -disk = "50M" # FIXME: replace with an **estimate** minimum disk requirement. e.g. 20M, 400M, 1G, ... -ram.build = "50M" # FIXME: replace with an **estimate** minimum ram requirement. e.g. 50M, 400M, 1G, ... -ram.runtime = "50M" # FIXME: replace with an **estimate** minimum ram requirement. e.g. 50M, 400M, 1G, ... +ldap = "true" +sso = "false" +disk = "50M" +ram.build = "50M" +ram.runtime = "50M" [install] [install.domain] @@ -43,7 +44,7 @@ ram.runtime = "50M" # FIXME: replace with an **estimate** minimum ram requiremen [install.base_domain] type = "domain" ask.en = "Choose the base domain for Headscale's MagicDNS feature" - help.en = "MagiDNS will allow you to access your hosts with a domain like `myhost.mynamespace.basedomain.tld`" + help.en = "MagiDNS will allow you to access your hosts with a domain like `myhost.username.basedomain.tld`" [resources] [resources.sources.main]