Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Tailscale docs #12

Merged
merged 3 commits into from
Oct 2, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions docs/remote/tailscale/advanced.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Advanced Tailscale Settings

## Log in to Tailscale Settings

1. Log in to the Unraid server and switch to the **Settings** tab.
2. Click on **Tailscale**.

![!settings-menu](settings-menu.png)

3. On the **Tailscale** tab, click the **Viewing** button.

![!settings-viewing](settings-viewing.png)

4. Click **Sign in to confirm identity**

![!confirm-identity](confirm-identity.png)

5. A new window will open. Click **Viewing** in this window, then **Sign in to confirm identity**.
6. Log in to Tailscale. Click **Close window** to return to the Tailscale settings once you have logged in.

## Subnet Router

1. Click **Subnet router**.

![!subnet-router](subnet-router.png)

2. Enter the desired routes and click **Advertise routes**.

![!subnet-advertise](subnet-advertise.png)

3. The routes will be displayed with a **Pending approval** message. The routes must be approved in the Tailscale
admin console before they can be used.

![!subnet-pending](subnet-pending.png)

4. Open the [Tailscale admin console](https://login.tailscale.com/admin/machines).
5. Locate the server in the machine list. It will have a blue **Subnets** badge with an exclamation point indicating
that the server has routes that have not yet been approved.

![!subnet-approve](subnet-approve.png)

6. Click the three dots at the end of the row, then **Edit route settings...**.

![!exit-menu](exit-menu.png)

7. Check the routes to approve and save.

![!subnet-routes](subnet-routes.png)

## Exit Node

1. Click the down arrow under **EXIT NODE**.
2. Select **Run as exit node**.

![!exit-select](exit-select.png)

3. The server will now advertise itself as an exit node. This must be approved in the Tailscale admin console before
it can be used.

![!exit-pending](exit-pending.png)

4. Open the [Tailscale admin console](https://login.tailscale.com/admin/machines).
5. Locate the server in the machine list. It will have a blue **Exit Node** badge with an exclamation point indicating
that the server has not yet been approved as an exit node.

![!exit-approve](exit-approve.png)

6. Click the three dots at the end of the row, then **Edit route settings...**.

![!exit-menu](exit-menu.png)

7. Check **Use as exit node** and save.

![!exit-routes](exit-routes.png)
85 changes: 85 additions & 0 deletions docs/remote/tailscale/basic.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# Basic Tailscale Setup

These instructions will help you create a Tailnet and connect an Unraid server. Once finished, you should be able to
connect to the following services via the Tailscale IP / MagicDNS name of the Unraid server:

- WebGUI
- File shares (SMB/NFS)
- SSH
- Bridge mode Docker containers (default or custom bridge networks)

!!! note
Docker containers running on ipvlan/macvlan networks (e.g., br0) cannot be accessed via the Tailscale IP for the
Unraid server. To connect to these containers, you should either [configure a subnet router](advanced.md) or
[add Tailscale to the container](docker.md).

## Create a Tailnet

1. Go to [Tailscale](https://www.tailscale.com) and click the **Get Started** button.

![!get-started](get-started.png)

2. Select an identity provider and log in.

![!identity-provider](identity-provider.png)

3. Select either **Business use** or **Personal use**.

![!personal-use](personal-use.png)

4. Follow the provided instructions to install Tailscale on a client device (phone/laptop/etc.).

![!first-device](first-device.png)

5. Once you have installed Tailscale on the device, it will appear on the screen.

![!second-device](second-device.png)

## Install the Unraid Tailscale Plugin

1. Log in to the Unraid server and switch to the **Apps** tab.
2. Search for **Tailscale**.
3. Install **Tailscale (Plugin)**.

![!install-plugin](install-plugin.png)

4. Click **Done** once the window shows that Tailscale has been installed.

![!install-complete](install-complete.png)

5. Switch to the **Settings** tab, then click on **Tailscale**.

![!settings-menu.png](settings-menu.png)

6. Click **Reauthenticate**.

![!reauthenticate](reauthenticate.png)

7. Click **Connect**.

![!connect-device](connect-device.png)

8. After the connection is complete, the browser will redirect to the Tailscale admin console, which should show both
devices are connected.

![!tailscale-console](tailscale-console.png)

## Finish Tailscale Setup

1. Open the [Tailscale DNS Settings](https://login.tailscale.com/admin/dns).

2. (Optional) Click **Rename tailnet...** . This will allow you to select a more friendly .ts.net domain name for your
devices.

![!rename-tailnet](rename-tailnet.png)

3. At the bottom of the DNS page, click **Enable HTTPS**. This will allow Tailscale to generate SSL certificates for
your devices (e.g., to avoid certificate warnings when accessing the Unraid WebGUI.)

!!! note
Machine names are published in a public certificate ledger when HTTPS is enabled. The public ledger only provides
information about the names of the TLS certificates; access to your devices is still restricted by Tailscale.

For more information, see the [Tailscale HTTPS documentation](https://tailscale.com/kb/1153/enabling-https#machine-names-in-the-public-ledger).

![!enable-https](enable-https.png)
Binary file added docs/remote/tailscale/confirm-identity.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/connect-device.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
149 changes: 149 additions & 0 deletions docs/remote/tailscale/docker.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
# Directly Connecting Containers to Tailscale

!!! info
Docker containers running on bridge networks do not need to have Tailscale installed within the container if the
Tailscale plugin is installed. Bridge containers will automatically work on the Unraid server's Tailscale IP.

Installing Tailscale directly on a container is useful in other scenarios:

- Containers running on ipvlan/macvlan networks (e.g. br0)
- Sharing a specific container via Tailscale.

## Methods

Several options are available to connect a container directly to Tailscale:

- Using the Tailscale Docker Mod for LinuxServer.io containers
- Running Tailscale as a sidecar container

### Using the Tailscale Docker Mod for LinuxServer.io containers

1. Edit the Docker container that you wish to connect to Tailscale.

![!lsio-add-var](lsio-add-var.png)

2. Add a variable:

- Name: **DOCKER_MODS**
- Key: **DOCKER_MODS**
- Value: `ghcr.io/tailscale-dev/docker-mod:main`

![!lsio-docker-mods](lsio-docker-mods.png)

3. Add a variable:

- Name: **TAILSCALE_STATE_DIR**
- Key: **TAILSCALE_STATE_DIR**
- Value: `/var/lib/tailscale`

![!lsio-state-var](lsio-state-var.png)

4. Add a path:

- Name: **TS_STATE_PATH**
- Container Path: `/var/lib/tailscale`
- Host Path: A unique name to create a Docker volume for the Tailscale state.

!!! note
You can also use a filesystem path to create a bind mount instead of a Docker volume.

![!lsio-state-path](lsio-state-path.png)

5. Apply the changes to the container.

!!! warning
If the Tailscale state variable or path are not configured, Tailscale will be logged out any time the container
restarts.

!!! tip
If you would like to have Tailscale automatically log in instead of using the logs to get a login link, you can
create an auth key from the Tailscale admin console and add another variable named `TAILSCALE_AUTHKEY`
containing the key.

6. Open the logs for the container. Locate the line that says **AuthURL is**. Click the link to log in to Tailscale.

![!lsio-login](lsio-login.png)

!!! tip
The docker mod can be customized further using variables (e.g., to enable Tailscale serve). Refer to the
[mod documentation](https://github.com/tailscale-dev/docker-mod/pkgs/container/docker-mod) for the complete list
of variables.

### Running Tailscale as a sidecar container

1. Install **Tailscale-Docker** from Community Applications.

!!! tip
You can create an auth key from the Tailscale admin console and add that as the **Authentication Key** in the
container settings. If you do not use an auth key, you will need to open the logs after starting the container
to get the login link.

![!sidecar-install](sidecar-install.png)

2. If you did not use an authentication key, open the logs for the created container and use the link to log in.

!!! warning
The container will automatically stop after 60 seconds if the login has not been completed. If using the login
link to authenticate, you should start the container, then immediately open the logs and log in to Tailscale.

![!sidecar-login](sidecar-login.png)

3. Edit the container that you wish to connect to Tailscale:

??? info "Alternate instructions for Unraid 7.0 beta 2 and earlier"
The option to connect container networks was added after Unraid 7 beta 2. On earlier versions of Unraid, you can
manually configure the connection:

- **Network Type**: **None**
- **Extra Parameters**: `--net=container:CONTAINERNAME`

- **Network Type**: **Container**
- **Container Network**: The Tailscale container

![!sidecar-connect](sidecar-connect.png)

??? note "Published ports"
When a container is connected directly to Tailscale, the container ports are used, not the published ports.

For example, for a container with these ports:

![!sidecar-ports](sidecar-ports.png)

The service would become available on **http://server.tailnet.ts.net/** (using port 80) and
**https://server.tailnet.ts.net/** (using port 443). Ports 7080 and 7443 are not used.

If you wish to publish ports on a local address in addition to the Tailscale address, you must add the ports
to the settings for the Tailscale container.

![!sidecar-ts-ports](sidecar-ts-ports.png)

#### Enable Kernel Networking

!!! info
Userspace networking (the default) is fine for most scenarios (e.g., allowing container to be accessed via
Tailscale).

Enabling kernel networking may be required in scenarios where the container must be able to make MagicDNS
queries or initiate connections to other Tailscale devices, for example:

- A backup container that either ***pulls data from*** or ***pushes data to*** another system via Tailscale.
(Backup containers where clients push data to the container via Tailscale do not require kernel networking.)
- A monitoring container that connects to other systems via Tailscale to monitor system status (e.g., Uptime Kuma)

1. Edit the Tailscale container.
2. Set **Privileged** to **On**.

![!sidecar-kernel-privileged](sidecar-kernel-privileged.png)

3. Expand the settings, then set **TS_USERSPACE** to `false`.

![!sidecar-kernel-userspace](sidecar-kernel-userspace.png)

4. Add a device:

- **Name**: `/dev/net/tun`
- **Value**: `/dev/net/tun`

![!sidecar-kernel-tun](sidecar-kernel-tun.png)

5. Apply the changes.
Binary file added docs/remote/tailscale/enable-https.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/exit-approve.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/exit-menu.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/exit-pending.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/exit-routes.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/exit-select.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/first-device.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/get-started.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/identity-provider.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/install-complete.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/install-plugin.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/lsio-add-var.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/lsio-docker-mods.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/lsio-login.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/lsio-state-path.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/lsio-state-var.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/personal-use.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/reauthenticate.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/rename-tailnet.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/second-device.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/settings-menu.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/settings-viewing.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/sidecar-connect.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/remote/tailscale/sidecar-install.png
Binary file added docs/remote/tailscale/sidecar-kernel-tun.png
Binary file added docs/remote/tailscale/sidecar-login.png
Binary file added docs/remote/tailscale/sidecar-ports.png
Binary file added docs/remote/tailscale/sidecar-ts-ports.png
Binary file added docs/remote/tailscale/subnet-advertise.png
Binary file added docs/remote/tailscale/subnet-approve.png
Binary file added docs/remote/tailscale/subnet-pending.png
Binary file added docs/remote/tailscale/subnet-router.png
Binary file added docs/remote/tailscale/subnet-routes.png
Binary file added docs/remote/tailscale/tailscale-console.png
5 changes: 5 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -78,3 +78,8 @@ nav:
- VPN:
- Route a container trough a VPN with PfSense: docker/pfsense_vlan_vpn/pfsense_vlan_vpn.md
- Writing a template compatible for Unraid: docker/templating/templating.md
- Remote Access:
- Tailscale:
- Basic Setup: remote/tailscale/basic.md
- Advanced Settings: remote/tailscale/advanced.md
- Docker Containers: remote/tailscale/docker.md