infra/luci-app-zt-gateway
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1e4a46c4bfb6a3a4309151c7f4b15abe4c79db43
luci-app-zt-gateway/docs/INSTALL.md
Malar Invention 1e4a46c4bf setup wizard: fix routing, DHCP, WiFi AP, firewall, and deploy task 
Setup script fixes:
- _cidr_to_mask: pad to 4 octets (/24 -> 255.255.255.0)
- UCI quoting: remove embedded shell quotes from uci set calls
- Bridge ports: auto-detect zt* interface instead of hardcoding ztabc0
- Bridge netmask: default to /23 (255.255.254.0) for ZT+WIBLAN
- DHCP/WiFi AP: reference interface name (zt_wiblan) not device name (br_zt)
- Firewall zone: add zt_wiblan to LAN zone for nftables fw4
- ZT IP persistence: ensure ZT-assigned IP stays on interface for ARP
- Exit gateway routing: table 100/101 route via exit gateway, not self
- New setup-wifi-ap subcommand for WIBLAN WiFi AP

UBUS handler:
- Add setup-wifi-ap to validation regex and error message

Deploy task:
- Auto-discover files from root/ and htdocs/ instead of hardcoded list
- Clear LuCI cache before restarting services

Documentation:
- New docs/SETUP-GATEWAY.md with architecture, config, pitfalls, checklist
- Updated docs/INSTALL.md with deploy task and setup wizard sections
- Updated docs/PROGRESS.md with session log and learnings
2026-07-13 11:11:19 +05:30

6.1 KiB
Raw Blame History

Installing luci-app-zt-gateway

This package provides a ZeroTier Exit Gateway Switching UI for OpenWrt. It works on OpenWrt 24.10 (opkg) and 25.12+ (apk).

Prerequisites

The target device must have these packages installed:

Package Provides
luci-base LuCI framework
luci-compat luci.ucodebridge (needed by modern LuCI)
ucode Ucode runtime for rpcd backends
rpcd-mod-ucode Ucode rpcd plugin
luci-theme-bootstrap Default LuCI theme

Check with:

# OpenWrt 25.12+ (apk)
apk list --installed | grep -E 'luci-base|luci-compat|ucode|rpcd-mod-ucode|luci-theme'

# OpenWrt 24.10 and older (opkg)
opkg list-installed | grep -E 'luci-base|luci-compat|ucode|rpcd-mod-ucode|luci-theme'

Install missing prerequisites:

# apk
apk add luci-base luci-compat ucode rpcd-mod-ucode luci-theme-bootstrap

# opkg
opkg update
opkg install luci-base luci-compat ucode rpcd-mod-ucode luci-theme-bootstrap

Method 1: Local File Install (Development / Quick Testing)

The fastest way during development. No build step required.

mise run deploy:install
# or with a custom target:
HOST=root@10.0.0.1 mise run deploy:install

The deploy task auto-discovers all files from root/ and htdocs/, maps them to device paths, and restarts services. New files are automatically included without editing the task.

Open http://<device-ip>/cgi-bin/luci/admin/services/zt-gateway.

Note: This method has no dependency tracking. The package manager won't know about the installed files. Use for dev only.

Setting up as Exit Gateway

After deploying, run the setup wizard from the LuCI UI (Setup panel) or CLI:

ssh root@<device-ip> '/usr/sbin/zt-gateway-setup setup-all'

See SETUP-GATEWAY.md for detailed configuration and troubleshooting.

Method 2: Local Package Install via SCP

Build the .ipk (or .apk for 25.12+) with the OpenWrt SDK (see Method 5), then transfer and install:

# Transfer
scp luci-app-zt-gateway_*.ipk root@192.168.15.1:/tmp/

# OpenWrt 24.10 and older (opkg)
ssh root@192.168.15.1 'opkg update && opkg install /tmp/luci-app-zt-gateway_*.ipk'

# OpenWrt 25.12+ (apk)
ssh root@192.168.15.1 'apk add --allow-untrusted /tmp/luci-app-zt-gateway_*.apk'

You can also upload via the LuCI web UI: System → Software → Upload Package → select file → Install.

Method 3: OpenWrt SDK Build

Build from source using the official OpenWrt SDK. Produces a proper .ipk/.apk with dependency metadata.

# 1. Download the SDK matching your target architecture
#    https://downloads.openwrt.org/ → select release → SDK
tar -xf openwrt-sdk-*.tar.xz
cd openwrt-sdk-*

# 2. Place this package in the SDK tree
ln -s /path/to/luci-app-zt-gateway package/luci-app-zt-gateway

# 3. Update feeds (resolves luci-base, ucode, etc.)
./scripts/feeds update -a
./scripts/feeds install -a

# 4. Build just this package
make package/luci-app-zt-gateway/compile V=s

# 5. Find the output
find bin/ -name "luci-app-zt-gateway*"

Then install via Method 2.

To speed up the build:

make package/luci-app-zt-gateway/compile -j$(nproc) V=s

Method 4: Official Feeds Install

If the package is published to an OpenWrt feed (official or third-party):

# OpenWrt 25.12+ (apk)
apk update
apk add luci-app-zt-gateway

# OpenWrt 24.10 and older (opkg)
opkg update
opkg install luci-app-zt-gateway

Or via LuCI: System → Software → search "zt-gateway" → Install.

Method 5: Custom Package Feed

For distributing a third-party package to multiple devices, host the built .ipk/.apk files on an HTTP server and add a feed:

opkg-based (24.10 and older)

# On the router:
echo 'src/gz zt-gateway https://your-server.com/packages' >> /etc/opkg/customfeeds.conf
opkg update
opkg install luci-app-zt-gateway

apk-based (25.12+)

# On the router:
# Add the repo URL to /etc/apk/repositories.d/
echo 'https://your-server.com/packages' >> /etc/apk/repositories.d/custom.list
apk update
apk add --allow-untrusted luci-app-zt-gateway

The HTTP server must host:

  • Package files (.ipk or .apk)
  • An index file (Packages.gz for opkg, APKINDEX.tar.gz for apk)

The OpenWrt SDK's make package/index generates these indices.

Method 6: Image Builder / Attended Sysupgrade

Bake the package into a firmware image so it survives factory resets.

Via LuCI (recommended)

  1. Install the attended sysupgrade tool:
# apk
apk add luci-app-attendedsysupgrade

# opkg
opkg install luci-app-attendedsysupgrade
  1. Open System → Attended Sysupgrade
  2. Click Search for firmware upgrade
  3. Click Advanced Mode → add luci-app-zt-gateway to the package list
  4. Click Request firmware image → wait for the build server to compile
  5. Check Keep settings → Install firmware image

Via Image Builder

# Download the Image Builder for your target
tar -xf openwrt-imagebuilder-*.tar.xz
cd openwrt-imagebuilder-*

# Build with luci-app-zt-gateway included
make image PACKAGES="luci-app-zt-gateway luci-base ucode rpcd-mod-ucode luci-compat"

File Layout

These are the files installed by this package and their target locations:

Source Target Purpose
root/usr/sbin/zt-gateway-setup /usr/sbin/zt-gateway-setup Gateway setup script
root/usr/sbin/zt-gateway-switch /usr/sbin/zt-gateway-switch Gateway switching script
root/usr/share/rpcd/ucode/zt-gateway.uc /usr/share/rpcd/ucode/zt-gateway.uc rpcd backend
root/usr/share/rpcd/ucode/system.uc /usr/share/rpcd/ucode/system.uc system.board rpcd override
root/usr/share/ucode/luci/runtime.uc /usr/share/ucode/luci/runtime.uc LuCI ucode runtime patch
root/usr/share/luci/menu.d/luci-app-zt-gateway.json /usr/share/luci/menu.d/luci-app-zt-gateway.json LuCI menu registration
root/usr/share/rpcd/acl.d/luci-app-zt-gateway.json /usr/share/rpcd/acl.d/luci-app-zt-gateway.json rpcd ACL rules
root/etc/config/zt-gateway /etc/config/zt-gateway UCI config
htdocs/.../overview.js /www/.../overview.js LuCI frontend view
Reference in New Issue View Git Blame Copy Permalink