luci-app-easytier: managing EasyTier from the OpenWrt web interface

What the package adds to OpenWrt

luci-app-easytier is the LuCI interface for EasyTier, which the documentation describes as a simple, secure, decentralised internal network penetration VPN networking solution. The package itself is the OpenWrt installation package, in both IPK and APK form.

The feature list describes what the interface gives you. A modern user interface with automatic light and dark theme switching. Proper adaptation to both mobile and desktop. Complete Chinese and English internationalisation. Real-time traffic monitoring and network interface status. Live display of resource usage and version information. Support for uploading both archives and individual binary files. And flexible configuration management with backup and restore.

The important structural point is that the package is not the software. EasyTier's own core is a separate binary, and the LuCI package is the management surface around it. The upload page is where you put the binary, and the documentation lists the three single files it accepts, easytier-core, easytier-cli and easytier-web-embed, along with .zip, .tar.gz and .tar archives, and it also accepts an ipk or apk that already contains the core.

That separation is deliberate and it is what makes the package work across OpenWrt versions: the LuCI part is small and stable, and the core is swapped in by the user rather than pinned by the package.

Compatibility across OpenWrt versions and architectures

The compatibility section is the most useful thing in the documentation, because OpenWrt spans a decade of releases and two package formats.

On the operating system side, the package supports OpenWrt 18.06 and 18.08, and OpenWrt 19.x through 26.x, with IPK packages for 22.03.x and APK packages for SNAPSHOT. The badge in the README says the same range.

On architecture, the list covers ARM with aarch64, armv7 and arm, MIPS with mips and mipsel, and x86 with x86_64. That is the standard set of targets for a consumer router, and the absence of anything else is deliberate, because a build matrix has to be built and tested somewhere.

The dependencies are two. kmod-tun is the TUN/TAP kernel module and it is required, and luci-compat is the LuCI compatibility layer. The documentation asks you to install the kernel module before the package, with an opkg update followed by opkg install kmod-tun.

The reason for the wide version range becomes clear in the development guide, which sets out a compatibility principle. The package must be compatible with OpenWrt 18.06 through 26.x, it must use the LuCI Lua 1 architecture while also remaining compatible with Lua 2, and it must not use the LuCI JavaScript framework, which names view.js, form.js and rpc.js, and it must not use ES6 or later syntax, naming let, const, arrow functions and fetch by name.

That is an unusual set of constraints to impose on your own code, and it is entirely a consequence of wanting one package to work on both ends of a ten year range. A LuCI app written for a current OpenWrt would use the JavaScript framework and modern syntax and would simply not load on 18.06.

Installing a prebuilt package on the router

The fast path is to download a prebuilt package for your architecture from the releases page, upload it to the router's /tmp directory, and install it.

# IPK包 (OpenWrt 22.03.x)
opkg install /tmp/luci-app-easytier_*.ipk

# APK包 (OpenWrt SNAPSHOT)
apk add --allow-untrusted /tmp/luci-app-easytier_*.apk

The two commands differ in more than the package manager. The APK invocation needs --allow-untrusted, which is the flag that lets a locally uploaded package through the trust checks, and an IPK on a release build is installed with opkg. The wildcard is doing the work of selecting the right architecture build from whatever you uploaded.

After the install you refresh the browser or log back into LuCI, and a new entry appears under VPN, then EasyTier, where the EasyTier binary is uploaded.

The second path is GitHub Actions, for anyone who wants to build for themselves. You fork the repository, optionally edit the architecture list in the build workflow file, go to the Actions page and trigger the Build-OpenWrt-EasyTier workflow by hand, fill in a version number and a release description, and wait for it to finish and appear in the releases. That workflow is the same one that produces the published packages, so a fork can produce a build for an architecture the published set does not cover.

Building locally against the OpenWrt SDK

The third path builds the package from source against an OpenWrt SDK, and the sequence is the standard one for any LuCI package.

# 1. 下载OpenWrt SDK
wget https://downloads.openwrt.org/releases/22.03.7/targets/rockchip/armv8/openwrt-sdk-22.03.7-rockchip-armv8_gcc-11.2.0_musl.Linux-x86_64.tar.xz
tar -xJf openwrt-sdk-*.tar.xz
cd openwrt-sdk-*/

# 2. 克隆项目
git clone https://github.com/EasyTier/luci-app-easytier.git package/luci-app-easytier

# 3. 更新feeds并配置
./scripts/feeds update -a
./scripts/feeds install -a
make defconfig

# 4. 编译
make package/luci-app-easytier/compile V=s

# 5. 查找生成的ipk
find bin/ -name "luci-app-easytier*.ipk"

The download URL in the example is a rockchip armv8 SDK for the 22.03.7 release, and the file name carries the toolchain details, gcc 11.2.0 and musl, which tells you that the SDK is itself built for the target architecture and runs on a Linux x86_64 host. The V=s on the make line is the verbose flag, which is what you want for a package build that can fail in many places.

Cloning into the package/ directory of the SDK is the step that makes the package part of the OpenWrt build system, and the feeds update and install plus make defconfig are what pull in the dependencies. The final find is the practical one, since the output lands in a bin/ tree keyed by target and package.

The cost of this route is a full SDK download, which is large, and a build that has to resolve the whole package graph. For a one-off install, the prebuilt package is the sensible choice.

The interface pages and the two configuration routes

After installation you configure the node through four or five pages, and the layout is straightforward.

The Status page shows the running state, the version, the connection information and live traffic. The EasyTier Core page is where the core parameters are set, including the network name, the key and the nodes. A separate page configures the self-hosted EasyTier web console. The logs page shows the run log with level filtering. And the upload program page is where the binaries go.

Configuration can be done two ways. Through command line arguments, with the various parameters set from the LuCI interface, or through a configuration file, and the file lives at /etc/easytier/config.toml.

The backing store is UCI, the OpenWrt configuration system, and the directory layout in the development guide shows how the pieces are arranged. The luasrc tree holds the controller, the CBI model files for the configuration and status pages, and the view templates for the status, log and upload pages. The root tree holds the UCI configuration, the init.d startup script and a configuration directory, along with a download script under usr/share/easytier/. The po/ directory holds the Simplified Chinese translation and the translation template, and the Makefile is the OpenWrt package definition.

The API design is conventional LuCI. A route is registered with an entry call taking a path tuple and a function name, the leaf is set to true so it appears in the menu, and the handler sets the content type and writes a JSON object with a success flag, a data field and a message.

Where luci-app-easytier is the wrong choice

The first limitation is that the core binary is uploaded by the user rather than shipped. That gives the package its wide compatibility and its small size, and it also means the version of EasyTier running on your router is whatever you uploaded, which can be older than the upstream project and is not tracked by the package manager.

The second is that the interface is a thin one. The Core page exposes network name, key and nodes, and the other pages are status, logs, console and upload. There is no peer management dashboard, no per-node policy, no traffic accounting over time and no way to change the configuration of a running core beyond editing the fields and saving. If you are used to a full VPN management console, this is thinner than you may expect.

The third is the deliberate conservatism of the code. ES5, no let or const, no arrow functions, no fetch, no LuCI JavaScript framework, and server-side rendering only. That is the right call for a package that has to load on OpenWrt 18.06, and it is a real constraint for anyone who wants to write a modern front end against it.

The fourth is the compatibility floor of the old Lua architecture. The development guide requires the LuCI Lua 1 API and forbids Lua 2 only syntax, and the troubleshooting section includes a fix for a util.pcdata warning that has to be applied by hand, which is the kind of thing that signals the package is running against a LuCI version it was not designed for.

The fifth is that the configuration file conflict behaviour is a blunt instrument. When an upgrade prompts about a configuration file conflict, the old configuration is kept and the new one is saved as /etc/config/easytier-opkg, and the documentation says the error can be ignored. That is fine for a package whose defaults rarely change and awkward for one that does.

How this compares with running EasyTier in a container and with the upstream configuration

The comparison with running EasyTier in a container on the router is the first one, and the difference in approach is integration. A container gives the core its own filesystem and a clean version pin, and it needs a tun device and the usual container plumbing on a router that often has a small amount of storage. The LuCI package puts the core on the host filesystem, which the router's own init system starts and stops, and which the LuCI interface can therefore report on.

The second comparison is with configuring the core by hand. EasyTier's own documentation and its TOML file format are the ground truth for what the core can do, and a hand-edited /etc/easytier/config.toml will always be able to express more than the LuCI form does, because the form has to map a set of fields onto a file. The interface is a convenience layer over the file, and a power user will edit the file.

The third comparison is with a general purpose VPN package for OpenWrt, the ones that come with the firmware. The difference is that EasyTier is a decentralised mesh, so the LuCI package is managing a node that joins a network rather than a service that a router provides.

The fourth is the opposite comparison, with running the core on a server instead of a router. The LuCI package is for the case where the router itself is the node, which is the case the packaging is designed around, given the architecture list and the TUN kernel module dependency.

Licence, maintenance and what to check before you flash it

The licence field on the repository records Apache-2.0, with a LICENSE file at the root, and the documentation states the project uses the Apache License 2.0. The README also links the official EasyTier repository and its documentation site, along with the OpenWrt site, and there is a DeepWiki badge linking to an auto-generated wiki for the repository.

The project is not archived and the last push was on 2026-10-14, so it is being worked on. The recent releases are v2.6.4 from 2026-05-16, v2.6.2 from 2026-04-27 and v2.6.1 from 2026-04-23, and there is also a version.mk file at the root alongside easytier/ and easytier-noweb/ directories, which appear to be the core source trees alongside the LuCI package directory luci-app-easytier/.

Five things to check before you install it on a router.

That kmod-tun is already installed, since the package requires it and a missing TUN device means the core cannot start.

Which package format your firmware uses, IPK for a 22.03.x release and APK for a SNAPSHOT build, since the two are installed with different commands and the APK path needs the untrusted flag.

Whether the interface shows up at all, because the first documented fix for a missing interface is to clear the LuCI cache with rm -rf on the /tmp/luci- files and log back in.

Which EasyTier core you are going to upload, since the package does not ship one and the version you choose is the version you run.

And, for anyone modifying the code, the two compatibility tests the contribution guide asks for, on OpenWrt 18.06 and on the newest release, because the whole point of the ES5 and Lua 1 constraints is that both ends of that range keep working.

Editorial conclusion

luci-app-easytier suits an OpenWrt operator who wants EasyTier managed from LuCI rather than from a command line, and who needs the node to survive a router that has no display and no shell access at hand. It is the wrong tool if you want the newest EasyTier features, because the core binary is uploaded separately and can lag the upstream project, and the wrong choice if you expect a full management experience, since the pages are a thin layer over a handful of configuration fields. Before installing, confirm that kmod-tun is present, since the package lists it as required, and read the compatibility section, because the front end is written in ES5 and Lua 1 specifically so that one package keeps working across a decade of OpenWrt releases.

Frequently asked questions

Official sources

1. EasyTier/luci-app-easytier on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases