8000 GitHub - zaolin/traytail: Minimal Tailscale tray icon for Wayland bars (SNI) · GitHub
[go: up one dir, main page]

Skip to content
zaolinPublic

About

Minimal Tailscale tray icon for Wayland bars (SNI)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

traytail

CI Release License: MIT

A minimal Tailscale tray icon for Wayland bars that host the StatusNotifierItem protocol — built and tested against ashell (see ashell for configuration notes).

No GUI toolkit. Pure Go, one dependency (github.com/godbus/dbus/v5), ~900 lines.

Features

  • Status icon: connected (filled) / offline (hollow) / exit node in use (green ring) / login required or captive portal (amber)
  • Captive portal handling — reads NetworkManager's connectivity state over DBus (no nmcli shell-outs): when a Wi-Fi portal hijacks the network, traytail disconnects tailscale, shows Open portal login in the menu (opens the discovered login URL in chromium), and reconnects tailscale once the portal clears
  • Multiple profiles — switch accounts (tailscale switch) from the Profile submenu
  • Exit nodes, derived straight from tailscale status --json (Location data), cleanly split:
    • Own exit nodes — regular tailnet peers with ExitNodeOption
    • Mullvad VPN — grouped by country (Location.Country)
  • Connect / Disconnect, copy Tailscale IP, open admin console
  • Left-click on the bar icon opens the menu; updates are pushed via NewIcon / LayoutUpdated signals (5s poll, deduplicated)

Requirements

  • tailscale CLI in $PATH, tailscaled running
  • You must be the Tailscale "operator" once:
    sudo tailscale set --operator=$USER
    

Build & run

go build .
./traytail

Menu

Haruhi — zaolin.github          (click = admin console)
Copy IP: 100.121.168.35
────────────
Profile: zaolin@github ▸        (if >1 account; parent shows active)
  ● zaolin@github               (active: click does nothing)
  ○ philipp@binarly.io          (click = switch, refreshes menu)
Exit node: Berlin ▸             (parent shows full city of the active node)
  ● Auto (smart: away→own, home→Mullvad)
  ○ Off
  ──
  ○ zds-nabara                  (own nodes, first DNS label)
  ──
  Mullvad ▸
     ● Germany ▸                (active country hoisted to top)
     Albania ▸  Argentina ▸ …   (full country names, sorted)
        ● Berlin                (city labels; ● marks the active one)
Disconnect
────────────
Admin console
Quit

While disconnected the menu keeps the Profile submenu: switching profiles offline switches and connects (tailscale up uses the selected profile's own preferences). The login-required menu shows profiles too, so you can switch accounts before re-authenticating.

Captive portals: when NetworkManager reports PORTAL connectivity (the machine's configured connectivity-check gets hijacked), traytail

  1. disconnects tailscale automatically (exit-node traffic bypasses the portal), 2. switches the menu to a portal view with Open portal login (it reads the check URI from NM over DBus and fetches it without redirects to discover the login URL, then opens it in chromium), and
  2. reconnects tailscale automatically once connectivity is restored. The Retry connectivity check entry re-runs discovery by hand.

Detection details and hardening:

  • traytail triggers a fresh NM CheckConnectivity once a minute (NM's own retry interval defaults to 300s) so a newly joined portal is noticed within ~60s instead of 5; between triggers the cached verdict is read.
  • Portal activation is slow and deliberate: tailscale is only disconnected after an unbroken portal-ish reading lasting ~90s (and the required tick count). Any clear reading resets the evidence. Tower handovers and phone-hotspot flaps therefore do not cause down/up churn.
  • No portal verdict from DNS alone: ad-filtering resolvers (Pi-hole, AdGuard, enterprise policy DNS) can NXDOMAIN the control domains while normal internet works. A usable control A record plus a consistently blocked TCP :80 connection, while the allowlisted check domain remains reachable, is required for the walled-garden verdict.
  • Portals serve their login page in two shapes: HTTP-redirects of the check request (the Location header is the login URL) and direct-200 HTML at the same URL. For the second shape, traytail falls back to the default gateway read from NM (PrimaryConnection -> Ip4Config -> Gateway) and offers http://<gateway>/ as the login URL.
  • Walled-garden portals (German ICE trains / wifionice class): these deliberately allowlist the standard check domains (Apple, fedoraproject — verified live), so the checks always "pass" while the wall is up, and they often leave native IPv6 unfiltered, which defeats dual-stack probes. traytail detects them with a matrix through the portal's own DNS server (read from NM over DBus): IPv4 A-record resolvability plus TCP :80 reachability of control domains (neverssl.com, tailscale.com) against the always-allowed Apple check domain. Control TCP blocked + check alive = portal. DNS-only failures are treated as insufficient evidence. If no redirect URL was captured, the menu offers the discovered gateway as Open portal login (gateway). With no known gateway it shows No login URL discovered yet instead of opening an external host that the routing check has already found unreachable.
  • Apple's exact 69-byte Success body is used as a content-injection detector for hijack portals (a replaced body fails the match).
  • If the NM connectivity check is disabled entirely, traytail logs a one-time warning and relies on the self-probes instead.

Known limitations: detection is NM-only (no iwd/networkd support); while a tailscale tunnel is active NM's check rides the tunnel and cannot see the portal — the self-probe (with cap_net_admin fwmark bypass, granted by sudo make install) covers that case.

Exit node selection: entries are labelled with full city/country names taken from the tailnet's own Location data (via tailscale status --json — the same source as tailscale exit-node list, minus one subprocess). The active country is hoisted to the top of the Mullvad list, and every item carries a ●/○ radio marker — including an explicit Off entry, so there is no click-active-to-disable trick. State is shown as a text glyph instead of checkmark properties because SNI hosts like ashell render toggle-type: checkmark items as switches.

Smart auto replaces tailscale's native auto:any with a policy traytail manages itself: when your machine is away (no local interface address inside the LAN routes advertised by your own exit node) it routes through the own exit node; when at home it switches to the last-used Mullvad node (persisted across restarts). The policy re-applies only when the home/away state flips — manual selections and Off stay untouched while the state is stable, and any manual pick or Off disables smart auto. Smart auto re-applies after reconnecting and after switching profiles (profiles carry their own exit-node preferences), so it keeps working across disconnects and account switches.

Deselecting the own exit node (clicking its ● item) applies the last-used Mullvad node instead — regardless of whether smart auto is on. Active nodes are matched by Tailscale IP, so a user-renamed device (Nabara vs zds-nabara.tailb4e47d.ts.net) still shows as selected.

Notes

  • Exit node selection uses tailscale set --exit-node=<hostname>; labels and grouping come from the tailnet's own Location data in tailscale status --json.
  • Captive-portal detection reads NetworkManager over the system DBus directly (org.freedesktop.NetworkManager.Connectivity + ConnectivityCheckUri) — no nmcli subprocesses. NM's connectivity check must be enabled for it to work. Some distros ship it disabled even with a uri configured — Arch-based systems often need:
    # /etc/NetworkManager/conf.d/connectivity.conf
    [connectivity]
    enabled=true
    When disabled, traytail logs a one-time warning at startup.
  • Works with any SNI host (ashell, waybar, KDE Plasma), not just ashell.

ashell

traytail is developed against ashell's tray module and works out of the box with its defaults — the module only appears once a tray icon exists, so no configuration is needed. Notes for ashell setups:

  • Menu opens on left click by default (ashell's right_click is unset → left click opens the context menu). If you set right_click = "Menu", left click switches to activating the app instead — traytail has no window, so keep the default or use right_click = "Open".
  • ashell renders checkmark items as switches, which is why traytail carries all selection state as ●/○ text glyphs on plain items — every menu entry renders as a normal button and closes the menu on click.
  • Submenus render inline with ▸ toggles; the exit-node menu nests Mullvad ▸ country ▸ city, which ashell displays fine (indentation per level).
  • traytail registers under the name traytail; add it to ashell's [tray] blocklist only if you don't want it shown.
  • Other SNI hosts (waybar with SNI support, KDE Plasma) should work too, but are untested — ashell is the reference host.

Development

make build    # go build
make test     # unit tests with -race
make cover    # unit + integration coverage (~93%)
make integration  # DBus integration tests under a session bus

Install

sudo make install        # build + install to /usr/local/bin
sudo make uninstall      # remove it again

Custom location (no root needed):

make install PREFIX=$HOME/.local/bin

The recommended setup is the systemd service, which also grants CAP_NET_ADMIN (portal probes can bypass an active tailscale tunnel), restarts on failure, and starts on boot:

sudo make install-system USER=$USER
journalctl -u traytail@$USER -f

Re-running install-system restarts the service so the running process always uses the just-installed binary. Logs also go to journald through /dev/log for any invocation, so journalctl -t traytail -f works whether or not the service is used.

License

MIT

About

Minimal Tailscale tray icon for Wayland bars (SNI)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0