Integration Patterns for Consuming Generated GeoIP Files in Proxy Clients

The loyalsoldier/geoip repository produces specialized GeoIP databases in formats like V2Ray .dat, Clash RuleSet YAML, and sing-box SRS, which proxy clients consume by loading from CDN URLs or local filesystem paths referenced in their routing configurations.

The loyalsoldier/geoip repository automates the aggregation and categorization of IP address ranges for network traffic routing decisions. Mastering the integration patterns for consuming the generated GeoIP files allows administrators to implement precise geo-based rules across diverse proxy infrastructures. This article details nine distinct consumption patterns, mapping each output format to its specific client configuration and the underlying Go source files that implement the generators.

V2Ray, Xray, and Compatible Clients (Dat Format)

The V2Ray dat format is a binary file containing categorized CIDR entries indexed by country or tag codes like geoip:cn or geoip:private. Clients including V2Ray, Xray, mihomo, hysteria, and Trojan-Go consume this format by loading the geoip.dat file from a local path or remote URL.

To integrate, place the generated geoip.dat adjacent to your client executable or reference it via your client’s geolocation URL configuration. The file is generated by [plugin/v2ray/dat_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/v2ray/dat_out.go), which serializes the internal data structure into the V2Ray-specific binary protocol. For parsing existing dat files (used during CLI lookup operations), the repository uses [plugin/v2ray/dat_in.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/v2ray/dat_in.go).

# V2Ray/Xray configuration snippet

geoip:
  path: "/usr/local/share/xray/geoip.dat"

Clash Premium and Core (YAML RuleSet)

Clash Premium and Clash Core ingest GeoIP data as YAML-based IP CID RuleSets. The generator produces files where each entry lists CIDR ranges under a specific category.

Configure a rule-provider with type: http, behavior: ipcidr, and format: yaml, pointing to the CDN-hosted file. The implementation resides in [plugin/plaintext/clash_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/plaintext/clash_out.go), which structures the output as ipcidr YAML compatible with Clash's rule engine.

rule-providers:
  geoip-cn:
    type: http
    behavior: ipcidr
    format: yaml
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/geoip@release/clash/ipcidr/cn.txt"
    path: "./ruleset/cn.yaml"
    interval: 86400

Surge (Plain-Text RuleSet)

Surge consumes GeoIP data as plain-text RuleSet files containing one CIDR per line. The client loads these lists at startup using the RULE-SET directive.

The plain-text output for Surge is generated by [plugin/plaintext/surge_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/plaintext/surge_out.go). Reference the remote URL directly in your Surge configuration to fetch the categorized IP lists.

[Rule]
RULE-SET,https://cdn.jsdelivr.net/gh/Loyalsoldier/geoip@release/surge/cn.txt,DIRECT

sing-box (SRS Binary Format)

sing-box utilizes the SRS (sing-box RuleSet) binary format for efficient IP matching. Define a remote rule_set with format: binary to consume the generated .srs files.

The binary serialization is handled by [plugin/singbox/srs_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/singbox/srs_out.go), which converts the internal CIDR containers into the SRS binary protocol.

{
  "route": {
    "rule_set": [
      {
        "tag": "geoip-cn",
        "type": "remote",
        "format": "binary",
        "url": "https://cdn.jsdelivr.net/gh/Loyalsoldier/geoip@release/srs/cn.srs"
      }
    ]
  }
}

mihomo (MetaCubeX) and MRS Format

mihomo (formerly MetaCubeX/Clash.Meta) supports the MRS (mihomo RuleSet) format for IP CIDR groups. Configure an HTTP rule-provider with format: mrs to fetch the binary representation.

The implementation in [plugin/mihomo/mrs_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/mihomo/mrs_out.go) generates these .mrs files, optimizing them for mihomo's rule-matching engine.

rule-providers:
  geoip-cn:
    type: http
    behavior: ipcidr
    format: mrs
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/geoip@release/mrs/cn.mrs"
    path: "./mrs/cn.mrs"
    interval: 86400

Universal Clients via MaxMind MMDB

For clients like Shadowrocket, Quantumult X, and legacy Clash versions, the repository generates a MaxMind Country MMDB (Country.mmdb). This binary format is the de facto standard for GeoIP lookups.

Configure your client’s geox-url setting to point to the generated MMDB file. The writer is implemented in [plugin/maxmind/maxmind_country_mmdb_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/maxmind/maxmind_country_mmdb_out.go), which constructs a binary MMDB containing both standard country codes and custom categories.

# Clash configuration

geox-url:
  mmdb: "https://cdn.jsdelivr.net/gh/Loyalsoldier/geoip@release/Country.mmdb"

Nginx Access Control

Nginx servers consume GeoIP data as configuration snippets containing allow or deny directives for specific CIDR ranges. Include these files in your nginx.conf to implement IP-based access control.

The generator produces these snippets in the nginx directory via [plugin/plaintext/nginx_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/plaintext/nginx_out.go), creating files like allow.conf with ready-to-use directives.

http {
    include /etc/nginx/geoip/allow.conf;
}

Plain-Text CIDR Lists for Custom Scripts

For firewall rules, custom routing scripts, or clients requiring raw data, the repository emits simple plain-text CIDR lists (.txt). Each line contains one CIDR range.

This generic output is generated by [plugin/plaintext/text_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/plaintext/text_out.go), suitable for any consumer that can parse newline-separated IP ranges.

# iptables example using plain-text list

while read cidr; do
  iptables -A INPUT -s $cidr -j ACCEPT
done < /path/to/cn.txt

Generation Architecture

Understanding the source architecture clarifies how these integration patterns function. The loyalsoldier/geoip CLI orchestrates a data pipeline defined in [lib/entry.go](https://github.com/Loyalsoldier/geoip/blob/master/lib/entry.go) and [lib/container.go](https://github.com/Loyalsoldier/geoip/blob/master/lib/container.go).

The process flow reads a config.json, aggregates inputs through various parsers, deduplicates entries, and dispatches to output plugins implementing the Output interface:

// lib/entry.go
type Output interface {
    Name() string
    Write(*Container, string) error
}

Each plugin directory under plugin/—such as v2ray/, singbox/, mihomo/, maxmind/, and plaintext/—contains a writer translating the Container (holding categorized CIDR slices) into the target format. This modular design ensures that adding support for new proxy clients requires only implementing the Write method for that specific binary or text protocol.

Summary

• V2Ray/Xray consume binary geoip.dat files via [plugin/v2ray/dat_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/v2ray/dat_out.go), referenced by geoip:xx tags.
• Clash Premium loads YAML RuleSets from [plugin/plaintext/clash_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/plaintext/clash_out.go) using HTTP rule-providers.
• Surge ingests plain-text lists generated by [plugin/plaintext/surge_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/plaintext/surge_out.go) via RULE-SET directives.
• sing-box parses binary SRS files from [plugin/singbox/srs_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/singbox/srs_out.go) as remote rule sets.
• mihomo utilizes MRS format files from [plugin/mihomo/mrs_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/mihomo/mrs_out.go) with format: mrs providers.
• MaxMind MMDB output from [plugin/maxmind/maxmind_country_mmdb_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/maxmind/maxmind_country_mmdb_out.go) provides universal compatibility for clients expecting standard GeoIP databases.
• Nginx configurations generated by the plaintext plugin enable direct IP access control.
• Plain-text CIDR lists from [plugin/plaintext/text_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/plaintext/text_out.go) support generic scripting and firewall integration.
• All generators implement the Output interface defined in [lib/entry.go](https://github.com/Loyalsoldier/geoip/blob/master/lib/entry.go), consuming the shared Container structure from [lib/container.go](https://github.com/Loyalsoldier/geoip/blob/master/lib/container.go).

Frequently Asked Questions

How do I update the GeoIP files automatically in my proxy client?

Configure the interval parameter in your rule-provider or set an external cron job to restart the client after downloading fresh files from the CDN. Most modern clients like Clash and mihomo support automatic HTTP polling with configurable refresh intervals.

Can I use the same GeoIP file for multiple different proxy clients?

Generally no, because each client requires a specific format—V2Ray uses proprietary binary .dat, sing-box uses SRS, and Clash uses YAML. However, the MaxMind MMDB format is widely supported across Shadowrocket, Quantumult X, and legacy Clash versions, serving as a universal fallback.

What is the difference between the Clash YAML format and the MRS format?

The Clash YAML format (generated by [plugin/plaintext/clash_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/plaintext/clash_out.go)) is a text-based list of CIDR ranges in YAML structure, readable and editable. The MRS format (generated by [plugin/mihomo/mrs_out.go](https://github.com/Loyalsoldier/geoip/blob/master/plugin/mihomo/mrs_out.go)) is a binary serialization optimized for mihomo's memory-efficient rule matching, offering faster lookup speeds at the cost of human readability.

Where does the repository store the generated output files?

The CI/CD pipeline publishes generated files to the release branch of the repository, mirrored automatically to jsDelivr CDN at https://cdn.jsdelivr.net/gh/Loyalsoldier/geoip@release/. You can reference these URLs directly in client configurations without hosting the files locally.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}