# PassWall2 on OpenWrt: a LuCI proxy front end for Xray, Sing-Box and Shadowsocks

> PassWall2 is a LuCI application that manages proxy cores on OpenWrt routers. It is aimed at people who want per-device routing rules and subscription-based node lists without touching core config files by hand.

**Openwrt-Passwall/openwrt-passwall2** — A simple powerful OpenWrt LuCI proxy application.

- Repository: https://github.com/Openwrt-Passwall/openwrt-passwall2
- Stars: 3,645 · Forks: 754
- Language: Lua
- License: GPL-3.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/openwrt-passwall-openwrt-passwall2

## What PassWall2 does on an OpenWrt router

PassWall2 is a LuCI web interface application for OpenWrt that provides proxy functionality, in the README's words "a comprehensive solution for network traffic management, proxy services, and access control on OpenWrt-based routers." The audience is the router owner who wants traffic from selected devices or domains to leave through a remote node, and who prefers a web form to editing JSON for a proxy core. The application itself is written in Lua and sits inside LuCI; the actual proxying is done by separate cores that PassWall2 installs and drives. The README lists Xray, Sing-Box, Shadowsocks-Rust, ShadowsocksR and HAProxy as the optional protocol packages, chosen during installation based on your needs. That split matters: PassWall2 is a control plane. If a protocol is not implemented by one of those cores, PassWall2 cannot offer it. The feature list covers load balancing across multiple nodes, domain-based and geo-based routing, DNS filtering with DoH and DoT, subscription import, latency testing, failover, QR code sharing, per-device rules, domain and IP filtering, and time-based scheduling. Those are configuration surfaces over the cores, not separate network stacks.

## How the LuCI app, the cores and the routing rules fit together

The repository has one top-level directory of interest, luci-app-passwall2/, which is the LuCI application; the README says language files live in luci-app-passwall2/po/ subdirectories. Configuration is stored in UCI, which is why libuci-lua appears in the dependency list, and the LuCI pages under Services then PassWall2 are the editing surface. When you save and apply, the app renders the selected core's own configuration and starts it; the cores are ordinary OpenWrt packages, so they are upgraded by the package manager rather than by PassWall2 itself. Routing decisions come from the rule sets you define: domain and IP lists, geo data from v2ray-geoip and v2ray-geosite, and the transparent proxy switch that redirects traffic into the core. Node data can be typed in manually or imported from subscription URLs, and node testing probes latency and connectivity so failover and load balancing have something to rank. One consequence of this design is that the failure surface is split. A node that will not connect can be a bad subscription entry, a core that is not installed, a firewall rule that was not applied, or DNS answering from the wrong resolver. The README's troubleshooting section points at logread | grep passwall2 first, which is where the app and core messages land.

## Installing PassWall2: ipk on OPKG, apk on APK

The README does not ship an install script. It tells you to visit the GitHub Releases page and download the package matching your router's architecture and package manager, then asks you to confirm which manager you have:

```bash
opkg --version
apk --version
```

On an OPKG build, download the ipk asset named luci-app-passwall2_{VERSION}_all.ipk, upload it, and install it. The README's example uses wget with the version substituted, then opkg:

```bash
wget https://github.com/Openwrt-Passwall/openwrt-passwall2/releases/download/{VERSION}/luci-app-passwall2_{VERSION}_all.ipk
opkg update
opkg install luci-app-passwall2_*.ipk
```

On an APK build the asset is luci-app-passwall2_{VERSION}_all.apk and the install command differs. The README flags that --allow-untrusted bypasses package signature verification, so treat it as a temporary step:

```bash
apk add --allow-untrusted luci-app-passwall2_*.apk
```

The README recommends the repository route instead, which enables updates through the package manager. It fetches the signing key into /etc/apk/keys and appends three feeds to /etc/apk/repositories.d/customfeeds.list, derived from /etc/openwrt_release:

```bash
. /etc/openwrt_release
wget -O /etc/apk/keys/passwall.pub https://sourceforge.net/projects/openwrt-passwall-build/files/apk.pub
apk update
apk add luci-app-passwall2
```

After either path, restart rpcd so LuCI picks up the new pages:

```bash
/etc/init.d/rpcd restart
```

Your first real use is in the web interface: open Services then PassWall2, go to Node List then Add Node, pick a protocol, fill in the server details, select the node as default, set DNS, enable transparent proxy, and click Save & Apply. If the service does not come up, the README's first diagnostic is logread | grep passwall2.

## Dependencies, the package feed and the 256MB floor

Two constraints decide whether PassWall2 is practical on a given router. The first is the feed. The README warns that if installation fails because dependencies such as xray-core are missing, you need to add the PassWall packages feed to /etc/opkg/customfeeds.conf. On APK builds the equivalent is the repository block shown above. Without that feed, you are installing a LuCI interface with no core behind it, and nothing will route. The second is hardware. The README states a minimum of 256MB RAM and "sufficient storage for packages (varies by protocol selection)." That is a floor, not a target. Running Xray or Sing-Box with geo data files, plus the geoip and geosite packages, consumes flash as well as memory, and the README does not publish a size table per protocol. The dependency list is also longer than the single install command suggests: coreutils, coreutils-base64, coreutils-nohup, curl, ip-full, libuci-lua, lua, luci-compat, luci-lib-jsonc, resolveip, tcping, unzip, geoview, v2ray-geoip and v2ray-geosite, with the README noting that actual dependencies vary by selected features and by your OpenWrt build. On a stock image, several of those may not be in your configured feeds. An OpenWrt 21.02 or later release and LuCI 17.01 or later are required; older builds are out of scope.

## Where PassWall2 breaks, and when it is the wrong tool

DNS is the most common soft failure. The README's troubleshooting entry for DNS issues does not describe a PassWall2 setting to change. It tells you to disable the browser's built-in secure DNS, with Chrome named as Settings then Privacy & Security then "Use secure DNS", and to clear the client cache with ipconfig /flushdns on Windows or by toggling airplane mode on mobile. That is an admission that a browser using DoH will bypass the router's resolution path, and it is the kind of problem that looks like a broken proxy. The connection-problem entry is similarly manual: test node connectivity, check firewall rules, verify transparent proxy settings. There is no documented rollback path. The README does not describe how to revert a configuration that broke connectivity, nor does it describe a safe mode or a revert command, so an operator who misapplies a rule set should expect to recover through LuCI or the filesystem rather than through a documented undo. PassWall2 is the wrong tool if you want a single self-contained proxy binary you configure with a text file. It is also a poor fit for a router below the stated memory and storage floor, or for one whose feeds you cannot extend, because the cores and geo data come from the package manager. And it is not a client for a laptop or phone: it is an OpenWrt package, tied to LuCI and to UCI.

## PassWall2 against PassWall, and against a plain core

The comparison people actually search for is PassWall against PassWall2. Both are LuCI proxy applications from the same project family, and the README of PassWall2 describes it as a separate application rather than a version bump of the first. The visible difference in this repository is the core set: PassWall2 lists Xray and Sing-Box as first-class options alongside Shadowsocks-Rust, legacy ShadowsocksR and HAProxy, with Sing-Box bringing protocols the README attributes to it, including TUIC, Hysteria, Hysteria2, AnyTLS and SSH. Anyone deciding between the two should compare the protocol and core coverage they need rather than assume the newer name is a drop-in replacement; the README does not publish a migration path from PassWall, so treat the two as separate installs. The other alternative is to skip the LuCI layer entirely and run one core by hand. Xray or Sing-Box can be installed as packages and configured with their own files, which removes the Lua application, the UCI schema and the web interface from the picture. You lose subscription import, latency testing, per-device rules and the geo-routing forms, and you gain a configuration you can version and diff. For a router with one node and one routing rule, that trade can be worth it. For a household with several devices and a rotating node list, the LuCI layer is the reason to use PassWall2 at all.

## Maintenance, releases and the licence

PassWall2 is not archived, and the last push to the repository was on 2026-09-20. The release cadence is visible in the tags: 26.9.16-1 on 2026-09-16, 26.9.12-2 on 2026-09-13, and 26.9.9-2 on 2026-09-09. Version strings follow a date-based scheme, so the release name tells you the day it was cut. Upgrading means reinstalling the package, or running apk upgrade if you added the repository as the README recommends. There is no documented in-place migration, so a version jump is a package replacement, and the README's only post-install step is restarting rpcd. Budget for that: the LuCI app, the cores and the geo data packages move independently, and a core upgrade can change behaviour under an unchanged PassWall2 configuration. The licence is GPL-3.0, per the LICENSE file at the repository root and the badge in the README. PassWall2 is distributed as a package that links against and drives separate cores, each with its own licence, so redistributing a firmware image that bundles it means accounting for the licences of those cores as well. That is a compliance question for whoever ships the image, not a legal opinion here.

## Conclusion

PassWall2 fits OpenWrt users who want proxy routing controlled from the LuCI web interface and who can live with the package feed requirements: install it from the release ipk or apk, or add the passwall2 repository first. It is the wrong choice if your router has less than the documented 256MB of RAM, if you cannot add the PassWall package feed for core dependencies such as xray-core, or if you want a single binary you configure by hand rather than a LuCI application. Before committing, verify which package manager your build uses with opkg --version or apk --version, confirm the release asset matches your router architecture, and check that logread | grep passwall2 reports a clean start after your first node is saved.

## FAQ

### What is OpenWrt PassWall2?

It is a LuCI web interface application for OpenWrt that provides proxy functionality, traffic management and access control. It is written in Lua and drives separate proxy cores such as Xray, Sing-Box, Shadowsocks-Rust, ShadowsocksR and HAProxy.

### What are the differences between PassWall2 and PassWall?

The README presents PassWall2 as its own application rather than a version bump of PassWall, and it lists Xray and Sing-Box as first-class cores alongside Shadowsocks-Rust, legacy ShadowsocksR and HAProxy. The README does not publish a migration path between the two, so compare the protocol and core coverage you need before switching.

### How do I install PassWall2 on OpenWrt?

Download the release asset matching your router architecture, then install the ipk with opkg install or the apk with apk add --allow-untrusted. The README recommends adding the PassWall2 APK repository instead, so updates arrive through apk, and restarting rpcd afterwards so LuCI shows the new pages.

### Why does the PassWall2 core not start?

The README's first diagnostic is logread | grep passwall2. It also notes that installation can fail when dependencies such as xray-core are missing, in which case the PassWall packages feed must be added to /etc/opkg/customfeeds.conf.

### Which OpenWrt versions and hardware does PassWall2 support?

The README states OpenWrt 21.02 or later and LuCI 17.01 or later, with a minimum of 256MB RAM and sufficient storage for the packages you select. Actual dependencies vary by feature selection and by the OpenWrt build.

## Sources

- [Issues](https://github.com/Openwrt-Passwall/openwrt-passwall2/issues)
- [License: GPL-3.0](https://github.com/Openwrt-Passwall/openwrt-passwall2/blob/main/LICENSE)
- [Openwrt-Passwall/openwrt-passwall2 on GitHub](https://github.com/Openwrt-Passwall/openwrt-passwall2)
- [README](https://github.com/Openwrt-Passwall/openwrt-passwall2/blob/main/README.md)
- [Releases](https://github.com/Openwrt-Passwall/openwrt-passwall2/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openwrt-passwall-openwrt-passwall2