Keenetic: Entware (opkg) package #32

Summary

Ship vtesse as an Entware (opkg) package for Keenetic routers, so a router can act as a vtesse client next to KeeneticOS and give the LAN access to devices behind a VTun server.

KeeneticOS (NDMS) is closed firmware, but its OPKG component installs Entware into /opt (USB storage or internal flash). VPN software such as OpenVPN and wireguard-go already runs this way on top of /dev/net/tun.

vtesse has two backends, and both matter here:

• lwIP (default): no /dev/net/tun, no root, no changes to the router's routes or firewall. SOCKS5 and port forwards on the router; works even where TUN is unavailable.
• TAP/TUN (--tap): a kernel interface with DHCP and option 121 routes through vtesse-hook.sh; LAN clients reach tunnel devices directly. Needs /dev/net/tun and survives NDMS rewriting routes and iptables only with hooks.

Targets

Plan

1. Static builds in CI. Done: vtesse-mipsel, vtesse-mips (OpenWrt 23.05 toolchains, musl, soft-float, run on an MT7620 router without FPU, Acceptance on real cameras and routers (stage 1-2 scenarios) #30) and vtesse-arm64 are already in the latest release, plus vtesse-tap-* (TAP-only) variants.

2. QEMU user-mode test in CI. Done for the unit tests and --version under qemu-mips, qemu-mipsel and qemu-aarch64 (Unit tests, reference vectors and big-endian CI #9, big-endian included). Still missing: a client against the bench under QEMU.

3. .ipk package. One per Entware arch. A CI artifact, not a release.

   Path	Content
   /opt/sbin/vtesse	static binary (full: lwIP + TAP)
   /opt/etc/init.d/S99vtesse	Entware rc.func init script, disabled by default
   /opt/etc/vtesse/vtesse.conf	sample config (host, port, session or id_from, password)
   /opt/etc/vtesse/vtesse.env	ARGS= for the init script (backend, --socks, forwards)
   /opt/share/vtesse/	vtesse-hook.sh, vtesse-udhcpc.script for --tap

4. NDMS hooks (TAP backend). KeeneticOS rewrites iptables and routes on its own. Restore the tunnel's forwarding/NAT rules from /opt/etc/ndm/netfilter.d/ and the option 121 routes from /opt/etc/ndm/ifstatechanged.d/.

5. Docs. Add a Keenetic section to all three READMEs and the results to docs/testing.md → Real devices.

Out of scope

• Kernel modules. No public kernel headers or SDK exist for KeeneticOS.
• KeeneticOS web UI integration. The UI is closed. The vtesse interface will not show up there, so the tunnel is managed from the CLI or config only.
• Server mode. vtesse is a client; the patched vtund is built for PCs/servers only.

To check on a real router

• Model, SoC, KeeneticOS version, uname -a, Entware arch (opkg print-architecture)
• lwIP backend: tunnel up against the bench, DHCP + option 121, SOCKS5 and a port forward to a camera from a LAN client (--listen on the LAN address)
• /dev/net/tun exists and opens. If it needs a KeeneticOS component, note which one.
• ip (BusyBox or Entware ip-full) and udhcpc can set the address, MTU and routes the hook uses
• TAP backend: interface up, ping a device through it, LAN clients reach tunnel devices, survives a WAN reconnect and NDMS rewriting routes
• Init script: start, stop and restart, and autostart after a reboot
• CPU load, memory and throughput on MT7621 (both backends)

Testing follows the usual rules: against the bench, not the production server; nothing on the router's own configuration is changed without the owner's consent, and it is restored afterwards.

Test samples

Static binaries and .ipk packages for the three arches come from CI as artifacts of the keenetic job. A link will be added here.