Skip to main content
Version: 031

Tailscale VPN

The pv-tailscale container joins the device to a Tailscale tailnet, so you can reach it (SSH, the pvtx web UI on port 12368, and any container on the host network) from anywhere, with no port forwarding. Once it is installed, you turn it on and configure it entirely through user metadata, either from the device or from Pantahub.

note

The container ships disabled. Until the user-meta key tailscale.enabled is true, the Tailscale daemon does not start. tailscale commands inside the container then fail with dial unix /var/run/tailscale/tailscaled.sock: connect: no such file or directory.

Add it to an image​

pv-tailscale is a recipe in this layer (recipes-containers/pantavisor/pv-tailscale_<version>.bb). It packages a prebuilt pvrexport of registry.gitlab.com/highercomve/ph-tailscale. Add it to the image's containers, and enable the tailscale feature so the kernel gets the TUN, WireGuard, and netfilter options it needs:

PVROOT_CONTAINERS_CORE:append = " pv-tailscale"
PANTAVISOR_FEATURES:append = " tailscale"

The kernel fragment depends on the firewall backend. recipes-kernel/linux/files/tailscale-nftables.cfg is used when nftables is in IMAGE_INSTALL; otherwise the image gets tailscale-iptables.cfg.

Enable and configure​

The container reads two user-meta keys, mounted inside it under /pantavisor/user-meta/:

KeyValueEffect
tailscale.enabledtrueStarts tailscaled and brings the connection up. Any other value or no key: the client runs tailscale down
tailscale.configJSON object (below)Options for tailscale up. Without this key, the container uses /etc/tailscale/config.json, which only has placeholders

From a shell on the device:

pvcontrol usrmeta save tailscale.config '{"key":"tskey-auth-XXXXXXXX","ssh":false,"acceptroutes":true,"acceptdns":true}'
pvcontrol usrmeta save tailscale.enabled true

You can also set the same keys in the device's user metadata on Pantahub. This works for devices you can't reach locally yet.

tailscale.config keys​

Each key maps to a tailscale up flag. Keys you leave out are not passed.

KeyTypetailscale up flag
keystring--authkey. Only used while the node has no valid credentials (NeedsLogin/NoState)
hostnamestring--hostname. Ignored when /pantavisor/device-id is set; the Pantahub device ID is used instead
sshbool--ssh
acceptdnsbool--accept-dns
acceptroutesbool--accept-routes
advertiseroutesstring--advertise-routes
advertisetagsstring--advertise-tags
hostroutesbool--host-routes
loginserverstring--login-server (e.g. a Headscale server)
netfiltermodestring--netfilter-mode
shieldsupbool--shields-up
snatsubnetroutesbool--snat-subnet-routes

Every connection attempt also passes --reset, so settings not in the config fall back to Tailscale's defaults.

If you leave key out, the client logs Node needs authentication but no auth key configured and waits. You can log in by hand instead from the container (below).

Check the connection​

Open a shell in the container. On the serial console or the host SSH shell, run:

pventer -c tailscale

Then:

ls /pantavisor/user-meta/ # tailscale.enabled (and tailscale.config) listed
pgrep tailscaled # daemon running once tailscale.enabled is true
tailscale status
tailscale login # interactive login, if no auth key is configured

Disable​

pvcontrol usrmeta save tailscale.enabled false

The client runs tailscale down within about a second. The daemon itself keeps running until the container restarts, because it only reads tailscale.enabled at startup.

Expected boot-log noise​

These lines from the container's logs are harmless:

  • rsyslogd: cannot create '/dev/log': Address in use. Pantavisor mounts its own log socket at /dev/log in every container, so the image's rsyslog can't bind it. Syslog from the container still reaches Pantavisor through that socket.
  • pvlogger tailscale ... Cannot init log file. Pantavisor's default loggers watch /var/log/syslog and /var/log/messages, and these files don't exist yet (or never will) in this Alpine image. pvlogger keeps polling for them.
  • Service 'hwdrivers' needs non existent service 'dev' (same for machine-id). Neither service is in a runlevel, so neither runs.