infra/luci-app-zt-gateway
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cd429291ef1a0bec1f527db6dcda5b6966a48202
luci-app-zt-gateway/docs/INSTALL.md
Malar Invention 13301772ab docs: add installation guide and deploy:install mise task 
- docs/INSTALL.md covers all 6 install methods (local SCP, package install,
  SDK build, official feeds, custom feed, Image Builder/ASU)
- deploy:install mise task: one-command SCP + service restart to an OpenWrt device
  with HOST env var support (default root@192.168.15.1)
2026-07-12 23:49:47 +05:30

6.5 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.

HOST=root@192.168.15.1

# Upload files
scp root/usr/sbin/zt-gateway-switch              $HOST:/usr/sbin/
scp root/usr/share/rpcd/ucode/zt-gateway.uc       $HOST:/usr/share/rpcd/ucode/
scp root/usr/share/rpcd/ucode/system.uc           $HOST:/usr/share/rpcd/ucode/
scp root/usr/share/ucode/luci/runtime.uc          $HOST:/usr/share/ucode/luci/
scp root/usr/share/luci/menu.d/luci-app-zt-gateway.json   $HOST:/usr/share/luci/menu.d/
scp root/usr/share/rpcd/acl.d/luci-app-zt-gateway.json    $HOST:/usr/share/rpcd/acl.d/
scp root/etc/config/zt-gateway                             $HOST:/etc/config/
scp htdocs/luci-static/resources/view/zt-gateway/overview.js $HOST:/www/luci-static/resources/view/zt-gateway/

# Set permissions and restart services
ssh $HOST 'chmod +x /usr/sbin/zt-gateway-switch; /etc/init.d/rpcd restart; /etc/init.d/uhttpd restart'

Or use the mise task (same thing, one command):

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

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.

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-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