Elegantly Managing Tailscale on OpenWrt: luci-app-tailscale-community

项目地址

https://github.com/tokisaki-galaxy/luci-app-tailscale-community

简介

Tailscale 作为一种基于 WireGuard 的零配置 VPN，极大地简化了设备之间的安全连接。对于在 OpenWrt 路由器上运行 Tailscale 的用户来说，通过命令行进行管理虽然可行，但远不如图形化界面来得直观和高效。为了解决这一问题，我开发了 luci-app-tailscale-community，一个专为 OpenWrt LuCI 界面设计的 Tailscale 管理插件。

luci-app-tailscale-community 旨在提供一个原生集成、功能全面的 Web 界面，让用户可以轻松地监控 Tailscale 网络状态并调整各项配置，而无需登录 SSH。

核心功能概览

该插件将 Tailscale 的核心功能无缝集成到 LuCI 的“服务”菜单下，主要分为“状态”和“设置”两个部分。

1. 状态仪表盘

提供对 Tailscale 网络健康状况的即时洞察：

• 服务状态: 清晰地显示 tailscaled 守护进程是“运行中”还是“未运行”。
• 设备 IP: 展示当前设备的 Tailscale IPv4 和 IPv6 地址。
• 网络设备列表: 以表格形式详尽列出 Tailnet 中的所有对等节点（Peers），包含以下关键信息：
  • 在线状态: 通过颜色标识节点是在线还是离线。
  • 主机名与 DNS: 显示设备的主机名和完整的 Tailscale DNS 名称。
  • 连接类型: 指明连接是“直连 (Direct)”还是通过“中继 (Relay)”，并显示中继服务器信息。
  • 操作系统 和 Tailscale IP。
  • 最后在线时间: 对于离线设备，显示其最后一次活跃的时间。

2. 强大的设置管理

设置页面通过两个标签页，区分了即时生效的节点设置和需要重启服务的守护进程设置。

• 节点设置 (Node Settings)
  这些设置通过调用 tailscale set 命令实现，更改会立即生效，无需中断服务。支持的配置项包括：

  • 接受/通告路由 (Accept Routes / Advertise Routes)
  • 作为或使用出口节点 (Advertise as Exit Node / Use Exit Node)
  • 为子网路由启用 SNAT
  • 启用内置 SSH 服务器
  • 切换 Shields Up 模式以增强安全性
  • 设置自定义主机名

• 守护进程环境设置 (Daemon Environment Settings)
  这些高级选项通过修改 tailscaled 启动时的环境变量来实现，因此在保存后需要重启服务。

  • 自定义 MTU: 解决特定网络环境下的连接问题。
  • 减少内存使用: 针对内存有限的设备进行优化，通过设置 GOGC=10 环境变量，以少量 CPU 开销换取更低的内存占用。

技术实现

luci-app-tailscale-community 主要使用 Lua 编写，并遵循 LuCI 的 MVC 架构。

• 数据模型: luasrc/model/tailscale_data.lua 是核心数据加载器。它通过执行 tailscale status --json 和 tailscale ip 命令获取实时状态，并解析 /etc/tailscale/tailscaled.state 文件以获取更详细的运行时配置。
• CBI 界面: luasrc/model/cbi/tailscale_status.lua 和 tailscale_settings.lua 文件使用 LuCI 的 CBI (Configuration Binding Interface) 框架来构建用户界面，并将前端选项与后端配置和命令关联起来。
• 配置应用: 对于守护进程设置，插件会动态创建或更新位于 /etc/profile.d/ 的一个 shell 脚本，确保在 tailscaled 服务启动时能加载正确的环境变量。

安装与使用

安装过程非常简单：

1. 前提条件: 确保您的 OpenWrt 设备已安装 tailscale 和 coreutils-base64。

   opkg update
   opkg install tailscale coreutils-base64

2. 安装插件: 从项目的 GitHub Release 页面下载最新的 .ipk 软件包，上传到路由器并使用 opkg 安装。

   opkg install luci-app-tailscale-community_*.ipk

   也可以从项目的action下载
   安装完成后，刷新 LuCI 页面，即可在“服务”菜单下找到“Tailscale”入口。

Project Address

https://github.com/tokisaki-galaxy/luci-app-tailscale-community

Introduction

Tailscale, as a zero-configuration VPN based on WireGuard, greatly simplifies secure connections between devices. For users running Tailscale on OpenWrt routers, while management via the command line is possible, it is far less intuitive and efficient than a graphical interface. To solve this problem, I developed luci-app-tailscale-community, a Tailscale management plugin specifically designed for the OpenWrt LuCI interface.

luci-app-tailscale-community aims to provide a natively integrated, feature-complete web interface, allowing users to easily monitor Tailscale network status and adjust various configurations without needing to SSH into the device.

Core Feature Overview

This plugin seamlessly integrates Tailscale’s core features under LuCI’s “Services” menu, primarily divided into two sections: “Status” and “Settings”.

1. Status Dashboard

Provides instant insight into the health of the Tailscale network:

• Service Status: Clearly indicates whether the tailscaled daemon is “Running” or “Not Running”.
• Device IP: Displays the current device’s Tailscale IPv4 and IPv6 addresses.
• Network Device List: Presents a detailed table of all peer nodes in the Tailnet, including the following key information:
  • Online Status: Indicates whether a node is online or offline via color coding.
  • Hostname & DNS: Shows the device’s hostname and full Tailscale DNS name.
  • Connection Type: Specifies whether the connection is “Direct” or via “Relay”, and displays relay server information.
  • Operating System and Tailscale IP.
  • Last Seen Time: For offline devices, shows the time they were last active.

2. Powerful Settings Management

The Settings page uses two tabs to distinguish between node settings that take effect immediately and daemon settings that require a service restart.

• Node Settings
  These settings are implemented by calling the tailscale set command. Changes take effect immediately without interrupting the service. Supported configurations include:

  • Accept/Advertise Routes (Accept Routes / Advertise Routes)
  • Acting as or Using an Exit Node (Advertise as Exit Node / Use Exit Node)
  • Enable SNAT for Subnet Routes
  • Enable the built-in SSH server
  • Toggle Shields Up mode for enhanced security
  • Set a custom hostname

• Daemon Environment Settings
  These advanced options are implemented by modifying environment variables for tailscaled startup, thus requiring a service restart after saving.

  • Custom MTU: Resolves connection issues in specific network environments.
  • Reduce Memory Usage: Optimized for devices with limited memory by setting the GOGC=10 environment variable, trading a small CPU overhead for lower memory consumption.

Technical Implementation

luci-app-tailscale-community is primarily written in Lua and follows LuCI’s MVC architecture.

• Data Model: luasrc/model/tailscale_data.lua is the core data loader. It executes tailscale status --json and tailscale ip commands to obtain real-time status, and parses the /etc/tailscale/tailscaled.state file to obtain more detailed runtime configuration.
• CBI Interface: The luasrc/model/cbi/tailscale_status.lua and tailscale_settings.lua files use LuCI’s CBI (Configuration Binding Interface) framework to build the user interface, linking frontend options with backend configurations and commands.
• Configuration Application: For daemon settings, the plugin dynamically creates or updates a shell script located in /etc/profile.d/, ensuring the correct environment variables are loaded when the tailscaled service starts.

Installation & Usage

The installation process is very straightforward:

1. Prerequisites: Ensure your OpenWrt device has tailscale and coreutils-base64 installed.

   opkg update
   opkg install tailscale coreutils-base64

2. Install the Plugin: Download the latest .ipk package from the project’s GitHub Release page, upload it to the router, and install it using opkg.

   opkg install luci-app-tailscale-community_*.ipk

   Alternatively, download from the project’s Actions.
   After installation, refresh the LuCI page to find the “Tailscale” entry under the “Services” menu.