Service eligibility and regional restrictions
PuppyIP serves only compliant overseas businesses and their authorized personnel. Proxy services are not available in mainland China. The service may only be used for lawful business activities outside mainland China. Use of this service within mainland China is prohibited.
Hosting a proxy IP or server overseas does not change these restrictions. The service must not be provided to end users in mainland China through relaying, forwarding, sharing or resale. Before use, read the Terms of Service.
Key Takeaways
- Missing geodata can prevent PassWall's Xray routing core from starting without indicating that the Xray binary is damaged.
- Check only the active config's paths, filenames, nonempty files, overlay space and the precise run-test error.
- A reduced GeoIP dataset applies only when the rules reference cn and private; other categories need a dataset that covers them.
- Do not run an Xray config-test process alongside the active core on a low-memory router; verify wireless and UDP separately.
Confirm a data-file error before blaming the core binary
If PassWall logs explicitly report missing Geo rules and an Xray config test reports a missing data file while loading a GeoIP or GeoSite category, first inspect the data used by the active core. An exited Xray process does not prove that its binary is missing; configuration, data paths and rule categories can all prevent startup.
One historical combination was ImmortalWrt 24.10.5, PassWall 25.12.16-r1 and Xray 25.2.21. This version record bounds that observation; it is not a current recommendation or a compatibility claim for other firmware. Record the versions actually installed on the device.
Check the active config path, files and available storage
Read the active PassWall Xray configuration to find the actual GeoIP and GeoSite directory and filenames. Some OpenWrt/ImmortalWrt builds use /usr/share/v2ray/geoip.dat and geosite.dat, but a custom path or core can differ. Do not copy files to a default directory until you confirm that the running core reads it.
Check that each file exists and is nonempty, read the first Geo-related PassWall startup error and confirm that overlay space can hold the selected data. In one historical environment, the complete GeoIP and GeoSite assets exceeded available storage. Repeatedly downloading full files can fail or affect the system.
Read Geo files, logs and overlay space
shGEODATA_DIR='REPLACE_WITH_DIRECTORY_FROM_ACTIVE_XRAY_CONFIG'
for name in geoip.dat geosite.dat; do
if test -s "$GEODATA_DIR/$name"; then printf '%s present\n' "$name"; else printf '%s missing-or-empty\n' "$name"; fi
done
logread | grep -iE 'geodata|geoip|geosite|passwall|xray' | tail -n 80
df -k /overlay
Choose full or reduced GeoIP data from the actual rules
Check every geoip:<category> and geosite:<category> referenced by the PassWall routing rules. A reduced cn/private GeoIP dataset covers the existing rules only when the configured GeoIP categories are limited to cn and private. If rules use other country or region categories, select a matching dataset that contains them. GeoSite data must still cover the referenced domain categories.
Use filenames expected by the core: install the reduced GeoIP file under the configured geoip.dat name and the domain-rule resource as a matching geosite.dat. Match the source release and checksums to the device's PassWall/Xray versions. Do not use an unverified mirror or present an old data revision as current.
Verify the files before installing them
Choose GeoIP and GeoSite resources that cover the categories in the active rules from a trusted release by the resource maintainer. Stage the files locally and verify each SHA-256. The command below does not download files or change PassWall update settings. Only when the current rules use cn and private GeoIP categories exclusively, and the release provides a matching reduced-data update entry, change global_rules.geoip_url separately in LuCI after recording its old value. Leave the GeoSite update entry, nodes and DNS unchanged.
Before writing, stop PassWall orderly through LuCI, confirm no Xray core is active and keep wired LAN management available. Confirm the active data directory exists and overlay has room for old-file backups and temporary files. Replace every path and published checksum before running the command; it verifies the sources, backs up existing regular files, then installs and verifies the destination files. Do not run it if any source or checksum is unverified.
Verify and install the GeoIP and GeoSite files
shset -eu
GEODATA_DIR='REPLACE_WITH_DIRECTORY_FROM_ACTIVE_XRAY_CONFIG'
GEOIP_SOURCE='REPLACE_WITH_VERIFIED_GEOIP_FILE'
GEOSITE_SOURCE='REPLACE_WITH_VERIFIED_GEOSITE_FILE'
EXPECTED_GEOIP_SHA256='REPLACE_WITH_PUBLISHED_GEOIP_SHA256'
EXPECTED_GEOSITE_SHA256='REPLACE_WITH_PUBLISHED_GEOSITE_SHA256'
verify_sha256() {
printf '%s %s\n' "$2" "$1" | sha256sum -c -
}
test -d "$GEODATA_DIR"
for name in geoip.dat geosite.dat; do
target="$GEODATA_DIR/$name"
staged="$GEODATA_DIR/.$name.new"
if [ -L "$target" ] || { [ -e "$target" ] && [ ! -f "$target" ]; }; then
printf 'Target is not a regular file; stop: %s\n' "$target" >&2
exit 1
fi
if [ -e "$staged" ] || [ -L "$staged" ]; then
printf 'Temporary path already exists; stop: %s\n' "$staged" >&2
exit 1
fi
done
verify_sha256 "$GEOIP_SOURCE" "$EXPECTED_GEOIP_SHA256"
verify_sha256 "$GEOSITE_SOURCE" "$EXPECTED_GEOSITE_SHA256"
BACKUP_DIR="/root/passwall-geodata-$(date +%Y%m%d-%H%M%S)"
mkdir -m 700 "$BACKUP_DIR"
[ ! -e "$GEODATA_DIR/geoip.dat" ] || cp -p "$GEODATA_DIR/geoip.dat" "$BACKUP_DIR/"
[ ! -e "$GEODATA_DIR/geosite.dat" ] || cp -p "$GEODATA_DIR/geosite.dat" "$BACKUP_DIR/"
install -m 0644 "$GEOIP_SOURCE" "$GEODATA_DIR/.geoip.dat.new"
install -m 0644 "$GEOSITE_SOURCE" "$GEODATA_DIR/.geosite.dat.new"
verify_sha256 "$GEODATA_DIR/.geoip.dat.new" "$EXPECTED_GEOIP_SHA256"
verify_sha256 "$GEODATA_DIR/.geosite.dat.new" "$EXPECTED_GEOSITE_SHA256"
mv -f "$GEODATA_DIR/.geoip.dat.new" "$GEODATA_DIR/geoip.dat"
mv -f "$GEODATA_DIR/.geosite.dat.new" "$GEODATA_DIR/geosite.dat"
Avoid concurrent Xray starts on low-memory devices
On a low-memory router, Xray run -test still creates a validation process. Running it while PassWall's main core is active can exhaust memory and trigger an OOM kill. Stop PassWall orderly through LuCI first, confirm no Xray core remains, then run the config test once. If it fails, keep the error and do not retry it concurrently or bulk-kill processes.
Use the command form below only when the device's Xray version supports it, the active config path is confirmed and no Xray process is running. After a successful test, start the service once through PassWall and observe the expected single core and logs. Do not manually launch a second Xray instance.
If the config test fails or startup remains unhealthy, first restore the recorded value of global_rules.geoip_url in the same PassWall setting, then restore the Geo files individually from the backup directory. Remove only a file added by this change when it did not exist before. Do not clear the entire Geo-data directory or restore unrelated router configuration.
Restore only the GeoIP and GeoSite files
shset -eu
GEODATA_DIR='REPLACE_WITH_DIRECTORY_FROM_ACTIVE_XRAY_CONFIG'
BACKUP_DIR='REPLACE_WITH_BACKUP_DIRECTORY_CREATED_ABOVE'
for name in geoip.dat geosite.dat; do
if [ -e "$BACKUP_DIR/$name" ]; then cp -p "$BACKUP_DIR/$name" "$GEODATA_DIR/$name"; else rm -f "$GEODATA_DIR/$name"; fi
done
Verify the client and protocol scope
After repair, confirm that config testing passes, PassWall has only the expected core, listeners are correct and logs no longer report missing Geo data. From a wired LAN client, test one domestic direct TCP request and one overseas proxied TCP request. Confirm the routing result and target response separately; use an authorized target when checking egress.
The historical verification covered domestic direct TCP and overseas proxied TCP from a wired LAN client only. It does not establish wireless-client access, UDP forwarding or long-term stability. Before updating global_rules.geoip_url, confirm that the resource matches the current rule categories. If new GeoIP categories are added, select data that covers them and recheck storage. Keep network, DHCP, firewall, wireless and PassWall backups private because they may contain credentials.
Sources
Frequently Asked Questions
Does a missing Xray process mean the binary is gone?
Not necessarily. If logs and a config test point to missing Geo data, check the active config path, data files and referenced categories before changing the binary.
Can a reduced cn/private GeoIP file cover every rule?
No. It applies only when all referenced GeoIP categories are cn and private. Other categories require data that includes them.
Can I run Xray run-test while PassWall is active?
Avoid it on a low-memory router. Stop PassWall orderly, confirm no core is active, then run one config test to reduce OOM risk.