From 667295e15eb84583a079a4a85d51ddc8c252966d Mon Sep 17 00:00:00 2001
From: Kristoffer Dalby <kristoffer@tailscale.com>
Date: Wed, 19 Apr 2023 17:04:43 +0200
Subject: [PATCH] add new documentation on how to install on debian/ubuntu

Signed-off-by: Kristoffer Dalby <kristoffer@tailscale.com>
---
 docs/running-headscale-linux.md | 95 +++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 docs/running-headscale-linux.md

diff --git a/docs/running-headscale-linux.md b/docs/running-headscale-linux.md
new file mode 100644
index 00000000..e0a19e7a
--- /dev/null
+++ b/docs/running-headscale-linux.md
@@ -0,0 +1,95 @@
+# 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/headscale/db.sqlite`) and the
+configuration (`/etc/headscale/config.yaml`).
+
+
+## Installation
+
+1. Download the lastest Headscale package for your platform (`.deb` for Ubuntu and Debian) from [Headscale's releases page]():
+
+```shell
+wget --output-document=headscale.deb \
+  https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>.deb
+```
+
+2. Install Headscale:
+
+```shell
+sudo dpkg --install headscale.deb
+```
+
+3. Enable Headscale service, this will start Headscale at boot:
+
+```shell
+sudo systemctl enable headscale
+```
+
+4. Configure Headscale by editing the configuration file:
+
+```shell
+nano /etc/headscale/config.yaml
+```
+
+5. Start Headscale:
+
+```shell
+sudo systemctl start headscale
+```
+
+6. 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 --user myfirstuser nodes register --key <YOUR_MACHINE_KEY>
+```
+
+### Register machine using a pre authenticated key
+
+Generate a key using the command line:
+
+```shell
+headscale --user myfirstuser preauthkeys create --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>
+```