PaoPao GateWay: a FakeIP gateway built as a bootable appliance

What it is, and the appliance idea

PaoPao GateWay is described as a small, stable and powerful FakeIP gateway, and the core is a Rust implementation called sniffbox that does smart sniffing and uses an efficient rapidhash FakeIP algorithm. It supports Full Cone NAT, several ways of delivering configuration, and several ways of getting traffic out, including a custom socks5, a custom OpenVPN, a custom yaml node, a subscription mode and a free outbound. There is also node speed testing with automatic selection, node exclusion, and a web panel for viewing logs and connection information.

The word that explains the design is ISO. PaoPao GateWay is an ISO image, designed to run as a virtual machine, and the README says the way to use it is to add a network interface and a virtual CD-ROM, put the ISO in it, and start. On boot the virtual machine initialises its eth0 interface over DHCP automatically, and the virtual machine also scrolls the IP address and MAC information it obtained so you can find it on your network.

That is an unusual distribution choice for a piece of networking software in 2026, and the reasoning is visible in the configuration section. The gateway has to be reachable before it has any configuration, so the config is delivered over the network after boot, which means the image itself stays unchanged and updating the config is a file operation rather than a rebuild.

The primary language is Rust, the licence is GPL-3.0, the default branch is main, and the homepage is a blog post explaining how the FakeIP gateway works. The last push was on 2026-09-14 with the project not archived. The recent releases are named with dates and commit hashes, 20260914-67600f7 and two from August, which is a versioning scheme that works well for an appliance that is rebuilt rather than upgraded in place.

The topics list names clash, fakeip, gateway, openwrt, paopao, paopaodns and paopaogateway, so the intended deployment is a small server or virtual machine on a home network, and the pairing with the author's separate PaoPaoDNS project is the intended companion setup.

The configuration download chain, and why it is four attempts

To separate configuration from the machine, the appliance uses DHCP to get its own network settings and then fetches its config file over HTTP. The README describes the assumption as: after the system starts and gets its details over DHCP, you have something like this:

IP: 10.10.10.3
DNS1: 10.10.10.8
DNS2: 10.10.10.9

And then it tries four sources in order, remembering the last one that worked and preferring it on the next cycle.

The first attempt is a hostname, http://paopao.dns:7889/ppgw.ini, which you resolve to your own static file server. The README explains the pairing with PaoPaoDNS: set the SERVER_IP parameter, set HTTP_FILE=yes, map the 7889 port, and put the ppgw.ini file in the PaoPaoDNS data directory. The paopao.dns name is resolved through the network interface's DNS, and if that result is unusable it falls back to a DNS previously specified in ppgw.ini.

The second attempt is the gateway address from the DHCP details, http://10.10.10.1:7889/ppgw.ini, for the case where you map the port on the main router. The third and fourth are the two DNS server addresses, which is the case where you are running PaoPaoDNS as the DNS service itself.

So the order goes from most abstract to most specific: a magic hostname, then the default gateway, then the DNS servers. Each fallback covers a different network topology, and the ordering means the most portable configuration is tried first.

The system keeps trying until it succeeds, and then fetches the config again periodically, with a default of thirty seconds. When a configuration value changes it reloads the gateway. And you can also enter the virtual machine's local terminal and type reload to force an immediate reload of all configuration.

That last detail is the one that makes the design workable. A headless appliance with no way to force a reload is a support call waiting to happen, and a reload command typed into the local console is the minimum escape hatch that appliance needs.

Reading ppgw.ini, and the rules the format imposes

The configuration file format has two rules stated up front, and they are worth repeating because they catch people.

The first line of the configuration file must start with #paopao-gateway, and the format is option="value", with no spaces on either side of the equals sign. So it is an INI-like format with a mandatory magic first line, and the strictness about spaces is not stylistic, because the parser is evidently strict too.

The beginning of a file looks like this:

#paopao-gateway

# mode=socks5|ovpn|yaml|suburl|free
# default: free
mode=free

# Set fakeip's CIDR here
# default: fake_cidr=7.0.0.0/8
fake_cidr=7.0.0.0/8

# Set your trusted DNS here
# default: dns_ip=223.5.5.5
dns_ip=10.10.10.8
# default: dns_port=53
# If used with PaoPaoDNS, you can set the 5304 port
dns_port=5304

The mode option is the gateway's run mode, which is how traffic arriving on the static route leaves the machine. There are five: socks5, ovpn, yaml, suburl and free, and the default is free.

The free mode is the least interesting and the most telling. It is for the case where you have already routed the virtual machine's own IP egress through a dedicated line at the IP layer, so the traffic just goes straight out and the gateway's job is only the FakeIP mapping and the DNS side.

The socks5 mode is the simplest and most general, where you run some other program that offers a socks5 proxy and point the gateway at it. The ovpn mode is for dedicated-line scenarios using OpenVPN. The yaml mode takes your own Clash-format yaml file, and the README is specific that only the proxies: field is needed, with rules: optional, and if you include rules then they are followed, while if you only include proxies then you pick the node from the web panel.

The suburl mode downloads a remote Clash subscription from a URL, with the same caveats as the yaml mode, and the recommendation is a nodelist-style subscription or one converted with a tool such as subconverter.

The FakeIP CIDR and the trusted DNS follow:

# Web dashboard password
clash_web_password="clashpass"

# default：openport=no
# socks+http mixed 1080
openport=no
#openport_auth="username:password"

# default: udp_enable=no

The web panel password is a separate option, and the panel is at a fixed address, http://gateway-IP:80. The openport option controls whether a proxy port is opened to the local network, on the mixed socks5 and http port 1080, and it defaults to no. When it is set to yes and no openport_auth is configured, the port is reachable without authentication, so openport_auth is worth setting if you enable it at all.

FakeIP, the address pool and the Chrome warning

The FakeIP mechanism is the core of the system, and the fake_cidr option is where you configure it. The default is 7.0.0.0/8, and you need a static route for that range on your main router pointing at the gateway.

The guidance is to use address ranges that look like public addresses but are not actually used, for example experimental ranges or the DoD network ranges. If you have other real public address ranges the gateway needs to handle, you write the corresponding static routes for those, and apart from the specified fake_cidr range, which gets a domain mapping, other public address ranges are handled by the gateway as ordinary traffic.

There is a specific warning about 198.18.0.0/15, which is the range most FakeIP setups use, and the reason is a browser behaviour rather than a networking one: Chrome treats that range as a local network range and warns about it. The README links to the Chrome local network access documentation and the WICG local network access repository for the reasoning.

The dns_ip and dns_port options set the trusted DNS server, and the word trusted is doing careful work. It means the real, uncontaminated original resolution result. The README explains an important subtlety: this DNS is not actually used when traffic goes out through a proxy, because the traffic is sent to the far end as a domain name. The trusted DNS matters for node resolution in the other modes and for rule matching.

The openport and udp_enable options come next. udp_enable controls whether UDP traffic is allowed through the gateway, and it defaults to no. The warning is specific: if your node does not support UDP, or if it is unstable, it is not recommended to turn it on, because enabling UDP will cause QUIC to fail and produce the symptom of some websites sometimes not loading at all. That is a useful piece of operational knowledge, because the failure mode it describes is baffling when you have not seen the explanation.

The access control options, admin_cidr and proxy_cidr, are optional. admin_cidr limits which source networks can reach the port 80 web panel, and proxy_cidr limits which source networks can use TPROXY or the inbound proxy, and an empty value allows everything. Multiple ranges are separated by commas.

The outbound modes, node testing and the web panel

Beyond the five modes, the configuration has a set of features that are about picking a good path rather than defining one.

fast_node is set to check, yes or no, and it works with a test_node_url that defaults to the Cloudflare generate_204 endpoint. The ext_node option is a filter expression with the shape Traffic|Expire| GB|Days|Date, so you can exclude nodes by traffic used, expiry date, region, and days remaining. And there is a fall_direct setting, which defaults to no.

The dns_burn option is described as depending on the subscription tool or on fast_node being enabled with the suburl or yaml mode, and it comes with ex_dns listing the resolvers to use, for example 223.5.5.5:53 and 1.0.0.1:53. The name suggests the point: it burns the DNS resolution early rather than on the critical path.

The traffic records section has net_rec, which defaults to no, and max_rec at 5000, with a commented net_cleanday of 15 for retention.

There is also a Cloudflare Tunnel section, with a cloudflared token, a cf_proxy setting for the replicas, and cf_protocol with the options auto, quic or http2, where auto means measure both and pick. The comment explains the replica arrangement: cloudflared is run as two replicas, one direct and one through the gateway proxy, and cf_proxy chooses which of those to run, with yes for proxied only, no for direct only, and both for both.

The README also names the built-in core and its data. The gateway has mihomo built in with the Geo data, GeoSite.dat, GeoIP.dat and ASN.mmdb, so GEOSITE and GEOIP rules work out of the box without replacing the core. The advice is still to prefer domain rules, because IP-type rules trigger extra DNS resolution and reduce efficiency.

And there is a warning against over-complex rule sets. If downloading a remote RULE-SET file fails at startup the core may not start properly, and if the core does not start the file may not download properly, which puts the system in a deadlock. That is a specific failure mode and the README is explicit about avoiding it.

The final feature worth naming is the OpenVPN file reference. The ovpnfile option accepts either a filename in the same directory as ppgw.ini, downloaded through the local port 7889 path, or a full remote URL. An embedded file at /www/custom.ovpn, baked into the ISO or Docker image, takes priority when it is present.

The image build, and how to evaluate the project

The Dockerfile shows how the appliance is assembled, and the first stage is worth reading closely.

It starts from alpine:edge as a downloader stage, installs Go, git, curl and gzip, and then clones the MetaCubeX meta-rules-dat repository on the release branch with a shallow clone. The critical detail is the checksum verification: it runs sha256sum -c against GeoLite2-ASN.mmdb.sha256sum, geoip.dat.sha256sum and geosite.dat.sha256sum before using any of the files. So the Geo data is verified against published checksums rather than trusted because it came from the expected URL.

After the move, the stage records the date of the release commit into an update.log by reading the commit atom feed, which gives the packaged data a timestamp. The same stage then fetches the mihomo core, parsing the releases page to find the version, downloading both the compatible and the v3 builds, and installing the compatible one to /usr/bin/mihomo_compatible.

That is the whole design in a build file: a minimal Alpine downloader that gathers verified Geo data and the proxy core, and the rest of the system layered on top of it.

For an evaluation, four things decide it.

First, whether you want an appliance at all. A virtual machine ISO with DHCP and HTTP-delivered configuration is a very different deployment from a container. For someone running OpenWrt or with a spare virtual machine and a taste for self-contained images, that is a feature. For someone running everything in Docker, it is a constraint.

Second, the hardware requirements are modest: x86-64 with three cores or more recommended, 512 MB of memory as a minimum and 1024 MB or more recommended, no disk, one network interface and one optical drive. The note is that with many nodes, many connections or a complex configuration file, you should increase memory and CPU cores.

Third, the trust model of the outbound. The gateway's job includes connecting out through a proxy or a subscription, and the yaml and suburl modes pull remote configuration, and the README is explicit that a subscription must not contain rules beyond the open-source Clash feature set. Whatever you point it at, it becomes part of your network path.

Fourth, that this is a personal project with a blog post as its documentation, and a GPL-3.0 licence. The Chinese-language README is thorough and unusually honest about the failure modes, including the QUIC and UDP interaction, the rule download deadlock and the Chrome address range warning, but the operational documentation lives in that post rather than in the repository, and the repository also has a FILES/ directory, a sniffbox/ directory with the Rust core, a rust-musl-builder/ for static builds, and separate scripts for building the ISO and the box for each architecture, arm64 included.

Editorial conclusion

Adopt PaoPao GateWay if you want a FakeIP gateway that boots as a virtual machine on your own network and configures itself over DHCP and HTTP, since that design lets you change the routing without rebuilding anything. Do not adopt it if you want a container you can compose with the rest of your stack, because the ISO appliance and the DHCP-delivered configuration are the point of the project rather than an implementation detail. Before you commit, pick a fake_cidr range that Chrome does not treat as a local network, which rules out 198.18.0.0/15, and set openport_auth if you enable openport at all, since the mixed socks5 and http port 1080 is otherwise reachable from the local network without a password. Also read the blog post on how the FakeIP gateway works, because the operational detail lives there rather than in the repository, and keep udp_enable off unless your node handles UDP reliably, since the QUIC failure it causes is hard to diagnose from the symptom alone.

Frequently asked questions

Official sources

1. kkkgo/PaoPaoGateWay on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases