How nikkinikki-org/openwrt-momo works
1. What this repo is
- This is an OpenWrt package repository for Momo, a transparent proxy solution built around sing-box.
- It is split into two installable packages: the core runtime package momo and the LuCI web UI package luci-app-momo.
2. High-level architecture
- The system has a control plane and a data plane.
- The control plane is the LuCI app plus OpenWrt config/init scripts.
- The data plane is the runtime proxy process (sing-box) plus firewall and routing rules that intercept traffic and steer it into the proxy.
3. Core runtime package: momo/
- momo contains the service-side OpenWrt package metadata and runtime assets.
- Key files include:
- momo.init for service startup and lifecycle
- momo.conf for default config
- momo.upgrade for upgrade handling
- uci-defaults/* for first-run setup and migrations
- This package is responsible for turning config into an active proxy/routing setup on the router.
4. Proxy orchestration and routing
- The README describes the runtime sequence: start sing-box, read profile parameters, set IP rules/routes, then generate and apply firewall rules.
- That implies Momo is not just a proxy launcher; it also owns policy routing and traffic interception setup.
- Supported modes include Redirect, TPROXY, and TUN, with IPv4 and IPv6 coverage.
5. Firewall and kernel integration
- The repo explicitly targets OpenWrt firewall4 and Linux kernel features needed for packet interception.
- Under momo/files/firewall/ are nftables fragments such as geoip_cn.nft and geoip6_cn.nft, indicating country-based routing/filtering support.
- Dependencies like kmod-nft-tproxy, kmod-nft-socket, kmod-tun, and ip-full show the architecture depends on kernel networking primitives, not just user-space proxying.
6. Configuration generation and templating
- The momo/files/ucode/ directory contains .uc/.ut files such as mixin.uc, include.uc, and hijack.ut.
- These are used to generate or compose configuration logic for the service, especially for reusable routing/firewall/profile behavior.
- This suggests a template-driven pipeline: UCI config + ucode templates → generated runtime config/firewall rules.
7. LuCI web UI package: luci-app-momo/
- luci-app-momo provides the web interface for configuring and observing Momo in LuCI.
- The main view modules are:
- app.js for overall app settings
- proxy.js for proxy mode/configuration
- profile.js for profile management
- editor.js for editing config/profile content
- log.js for log viewing
- mixin.js for shared UI logic
- This UI is the operator-facing boundary into the backend service.
8. LuCI-to-backend boundary
- luci-app-momo/root/usr/share/luci/menu.d/ defines how the app appears in LuCI.
- rpcd/acl.d/ defines permissions for accessing service data and configuration through OpenWrt’s RPC layer.
- rpcd/ucode/luci.momo is the bridge that likely exposes backend state/configuration to the UI.
- In architecture terms, LuCI does not run the proxy; it calls into OpenWrt’s config/RPC interfaces to control it.
9. Shared resource and data model
- The repo is centered around OpenWrt UCI configuration as the persistent source of truth.
- Profiles, proxy settings, restart scheduling, and access control are all presented as configurable state, then converted into runtime behavior by the backend.
- The po/ directories show the UI is localized, with templates plus Chinese translations.
10. External runtime dependencies
- The repo depends on sing-box >= 1.12 as the actual proxy engine.
- It also relies on OpenWrt system tools and libraries such as curl, ca-bundle, firewall4, and ip-full.
- The architecture assumes OpenWrt 24.10+ and kernel 5.13+, because those versions provide the networking and firewall capabilities needed for transparent proxying.
11. Install/build/deploy pipeline
- This is packaged as an OpenWrt feed with build scripts and GitHub Actions for package builds/releases.
- feed.sh, install.sh, and uninstall.sh are deployment helpers for adding/removing the feed or release packages.
- The CI workflows under .github/workflows/ automate package build, release publication, stale issue handling, and cleanup.
12. Operational behavior
- The README’s “How does it work” sequence maps directly to the system design:
1) run sing-box
2) optionally schedule restarts
3) read profile parameters
4) apply policy routing
5) generate/apply firewall rules
- So the main flow is: user configures in LuCI → config stored in UCI → backend generates routing/firewall/proxy state → router transparently intercepts traffic and forwards it through sing-box.
Main entry points: momo/Makefile momo · luci-app-momo/Makefile luci-app-momo · mixin.uc Templates · luci.momo RPC bridge
Components 21
Control plane
LuCI UI and RPC/config boundary used to operate Momo.
- luci-app-momo · Operator-facing web UI for configuring and observing Momo.
luci-app-momo/Makefile - UI views · Main configuration and status screens for app, proxy, profile, editor, and logs.
luci-app-momo/htdocs/luci-static/resources/view/momo/app.js - UI helpers · Reusable front-end helper code shared by the LuCI views.
luci-app-momo/htdocs/luci-static/resources/tools/momo.js - LuCI menu · Registers the package in the LuCI navigation tree.
luci-app-momo/root/usr/share/luci/menu.d/luci-app-momo.json - RPC bridge · Exposes backend state and config to the LuCI UI through OpenWrt RPC.
luci-app-momo/root/usr/share/rpcd/ucode/luci.momo - ACL · Defines UI permissions for accessing Momo service data and configuration.
luci-app-momo/root/usr/share/rpcd/acl.d/luci-app-momo.json - Translations · User-facing strings and templates for multilingual LuCI views.
luci-app-momo/po/templates/momo.pot
Runtime package
Core OpenWrt package that boots and maintains the transparent proxy service.
- momo · Service-side package that turns UCI config into active proxy and routing behavior.
momo/Makefile - Startup · Starts and supervises the Momo service lifecycle on OpenWrt.
momo/files/momo.init - Defaults · Baseline package configuration and runtime defaults.
momo/files/momo.conf - Upgrade · Handles package upgrade and migration behavior.
momo/files/momo.upgrade - First-run · Initial setup and migration scripts applied on install or upgrade.
momo/files/uci-defaults/init.sh - Templates · Reusable ucode templates that compose config, profile, and hijack logic.
momo/files/ucode/mixin.uc
Data plane
Proxy engine, routing, and firewall interception path used at runtime.
- Firewall rules · Firewall4-compatible nft fragments for country-based routing and interception.
momo/files/firewall/geoip_cn.nft - sing-box · External proxy runtime used for transparent forwarding.
- Policy routing · Applies IP rules and routes to steer selected traffic into the proxy path.
- Intercept modes · Redirect, TPROXY, and TUN-based packet interception paths.
- Kernel deps · Kernel features used for socket matching, tproxy, and tun-based interception.
Delivery
Feed scripts and CI workflows for packaging and release automation.
- Build & release · Package build, release publication, and maintenance workflows.
.github/workflows/build-packages.yml - Feed scripts · Shell helpers for installing, updating, and removing the feed or packages.
feed.sh
Other components
- openwrt-momo · Package repository for Momo, split into runtime and LuCI UI packages.
Connections 22
- openwrt-momo → momo: contains · Repository includes the core runtime package.
- openwrt-momo → luci-app-momo: contains · Repository includes the LuCI frontend package.
- openwrt-momo → Build & release: automates · CI workflows build and release packages.
- openwrt-momo → Feed scripts: ships · Top-level scripts support feed and package deployment.
- momo → Startup: boots · Package startup logic is defined by the init script.
- momo → Defaults: defaults · Package behavior is seeded by default config.
- momo → Upgrade: migrates · Upgrade hook preserves or transforms state across versions.
- momo → First-run: initializes · UCI defaults handle first-run setup and migrations.
- momo → Templates: generates · Ucode templates compose runtime config and rules.
- momo → Firewall rules: installs · Runtime package provides nftables rule fragments.
- Templates → Policy routing: builds · Templates generate routing and service control behavior.
- Templates → Intercept modes: selects · Templates support the different transparent proxy modes.
- Firewall rules → Kernel deps: depends on · Firewall interception requires kernel netfilter features.
- Policy routing → sing-box: steers traffic to · Policy routing directs traffic into the proxy engine.
- Intercept modes → Kernel deps: requires · Redirect, TPROXY, and TUN rely on kernel primitives.
- luci-app-momo → UI views: implements · Main configuration and status screens live in the view modules.
- luci-app-momo → UI helpers: shares logic · Common UI behavior is factored into helper code.
- luci-app-momo → LuCI menu: registers · LuCI menu definition exposes the app in navigation.
- luci-app-momo → RPC bridge: calls · UI talks to backend state through rpcd ucode.
- luci-app-momo → ACL: authorized by · RPC access is constrained by ACL definitions.
- luci-app-momo → Translations: localizes · View text is translated through PO templates and language files.
- RPC bridge → momo: reads state from · The bridge surfaces backend config and runtime information.