Tailscale

Related articles
WireGuard
Tailscale builds on top of
WireGuard
and provides OAuth2 (SSO), OpenID, and SAML authentication for peers to build a mesh network. It is crossplatform, has ACL settings and internal DNS.
Installation
Install
tailscale
and reboot your system.
It is also possible to run tailscale as a
Docker
container. This way, one can run multiple exit nodes on a single machine, each with its own tailnet.
System tray application
Note
This feature is currently in beta.
Introduced with v1.88, tailscale ships with the systray application. To launch the systray run:
# tailscale systray
To run the systray at startup as a systemd user service:
# tailscale configure systray --enable-startup=systemd
More information is available at
tailscale's official documentation
.
Third-party clients
KTailctl
— GUI to monitor and manage Tailscale.
https://github.com/f-koehler/KTailctl
||
ktailctl
AUR
trayscale
— An unofficial GUI wrapper for the Tailscale CLI client.
https://github.com/DeedleFake/trayscale
||
trayscale
AUR
tailscaledesktop
— Unnofficial Tailscale desktop application.
https://gitlab.com/tailscaledesktop/application
||
tailscaledesktop
AUR
tailscale-systray-git
— Linux port of tailscale system tray menu.
https://github.com/mattn/tailscale-systray
||
tailscale-systray-git
AUR
Usage
To use
tailscale
,
enable/start
tailscaled.service
and run the server as follows:
# tailscale up
You can authenticate a headless machine by specifying the
auth key
:
# tailscale up --authkey=tskey-
KEY
Note
By default tailscale will send
logs to their servers for central storage
. You may want to opt out with one of the following steps:
Edit
/etc/default/tailscaled
to include
TS_NO_LOGS_NO_SUPPORT=true
Edit
/etc/default/tailscaled
and add
--no-logs-no-support
to
FLAGS
If you opt out of centralized logging, Tailscale may not be able to provide technical support.
Advanced usage
Using a custom Control Server
Using a custom control server like
headscale
is possible.
To login run
# tailscale up --login-server
https://example.com
On headless systems a non-interactive login using a token is possible.
# tailscale up --login-server
https://example.com
--authkey
your_auth_key
You may create user and auth-key using following commands after
starting
headscale.service
:
# headscale users create USER -e email@example.com
# headscale users list
# headscale preauthkeys create -u <ID> --reusable
Share nodes between users
Create file with policy:
{
 "tagOwners": {
   "tag:shared": ["user1@"]
 },
 "groups": {
   "group:all": ["user1@", "user2@", "user3@"]
 },
 "acls": [
   {
     "action": "accept",
     "src": ["group:all"],
     "dst": ["tag:shared:*"]
   }
 ]
}
Point this file in config.yaml:
policy:
 mode: file
 path: "/etc/headscale/policy.json"
Advertise tag:
tailscale up --advertise-tags=tag:shared --login-server=
https://headscale.localdomain/
Integration with nextcloud or another OIDC provider
Install
nextcloud-app-oidc
AUR
and create client key, use
https://headscale.localdomain/oidc/callback
as redirection uri.
Add following snippet into config.yaml:
oidc:
 issuer: "
https://cloud.example.com
"
 client_id: "<client-id>"
 client_secret: "<client-secret>"
 scope: ["openid", "profile", "email"]
 user_map:
   name: "preferred_username"
   email: "email"
Running as a Docker container
Follow
this guide
for a general idea of how to run tailscale as a docker container.
As an exit node
In order to be able to use a tailscale instance running as a docker container as an exit node, we need to use a smaller MTU for the container's network. This is due to an
MTU-related issue
.
If you do not have one already, create a custom network:
# docker network create --opt com.docket.network.driver.mtu=1280
my_custom_network
Then, use that network for the container instance:
# docker run --detach --name=
my_tailscale_container
--network=
my_custom_network
--volume /var/lib/tailscale-exitnode-1:/var/lib/tailscale --env TS_STATE_DIR=/var/lib/tailscale --env TS_USERSPACE=1 --env TS_AUTHKEY=
tskey-auth-XXX
--env TS_EXTRA_ARGS='--advertise-exit-node' tailscale/tailscale
Note that:
By default, docker will create a network of type
bridge
, so no need to specify it here.
Use an auth key to authenticate the node. Authenticating with the regular SSO method usually takes too long, and the process may time out before initial authentication is successful.
Define
TS_USERSPACE=1
so that the container does not need elevated permissions (
CAP_NET_ADMIN
and
CAP_NET_RAW
).
Bind mount an unused directory on the host (
/var/lib/tailscale-exitnode-1
) to
/var/lib/tailscale
inside the container, and also define
TS_STATE_DIR=/var/lib/tailscale
, so that tailscale will use a persistent state file. Without these, the exit node will use volatile memory to keep state, and thus get a new ID and tailnet IP address
every time the container is restarted
.
Tips and tricks
Using with NetworkManager
If you use
NetworkManager
, you may notice connection issues with other devices within your tailnet. This is due to a management conflict that is happening between NetworkManager and tailscaled.
To clear this up, we need NetworkManager to unmanage the tailscale network devices (e.g.
tailscale0
).
To do so, simply create a config like
/etc/NetworkManager/conf.d/99-tailscale.conf
with the contents of:
[keyfile]
unmanaged-devices=interface-name:tailscale0
Then
restart
NetworkManager.service
and
tailscaled.service
.
You may also need to cycle tailscale:
# tailscale down
# tailscale up
After this, you should be able to
ping
other devices on your tailnet.
Magic DNS
Tailscale expects system with working
systemd-resolved
to set up DNS server and search suffixes from tailnet configuration, otherwise it
tries to overwrite
/etc/resolv.conf
.
Security Hardening
Tailscale can be made to run in its own user and with just the capabilities it needs to operate. See the
official knowledge base article
for detail.
Troubleshooting
Tailscale crash on launch
After starting
tailscaled.service
, it may crash and get stuck on a restart loop. This may be due to the absence of the
tun
kernel module. To verify that this is indeed the case, view the logs of
tailscaled.service
via
systemd
# systemctl status tailscaled.service
Or, run the binary as root in your terminal
# /usr/sbin/tailscaled
The following, or similar error may appear in
systemctl status
or by running the binary:
...is CONFIG_TUN enabled in your kernel? modprobe tun failed with: modprobe: FATAL: Module tun not found in directory /lib/modules/5.17.4-arch1-1 kernel/drivers/net/tun.ko found on disk, but not for current kernel; are you in middle of a system update and haven't rebooted? found: /lib/modules/5.17.8-arch1-1/kernel/drivers/net/tun.ko.zst wgengine.NewUserspaceEngine(tun "tailscale0") error: tstun.New("tailscale0"): no such device
If so, simply reboot your system and observe if
tailscaled.service
is active instead of loaded with
systemctl status
.
See also
https://tailscale.com/
https://github.com/juanfont/headscale