# Integration Patterns for Consuming Generated GeoIP Files in Proxy Clients

> Learn integration patterns for consuming generated GeoIP files in proxy clients. loyalsoldier/geoip provides V2Ray dat, Clash YAML & sing-box SRS formats for CDN or local loading.

- Repository: [Loyalsoldier/geoip](https://github.com/loyalsoldier/geoip)
- Tags: architecture
- Published: 2026-03-06

---

**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/main/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/main/plugin/v2ray/dat_in.go)](https://github.com/Loyalsoldier/geoip/blob/master/plugin/v2ray/dat_in.go).

```yaml

# 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/main/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.

```yaml
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/main/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.

```ini
[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/main/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.

```json
{
  "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/main/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.

```yaml
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/main/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.

```yaml

# 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`](https://github.com/loyalsoldier/geoip/blob/main/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/main/plugin/plaintext/nginx_out.go)](https://github.com/Loyalsoldier/geoip/blob/master/plugin/plaintext/nginx_out.go), creating files like [`allow.conf`](https://github.com/loyalsoldier/geoip/blob/main/allow.conf) with ready-to-use directives.

```nginx
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/main/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.

```bash

# 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/main/lib/entry.go)](https://github.com/Loyalsoldier/geoip/blob/master/lib/entry.go) and [[`lib/container.go`](https://github.com/loyalsoldier/geoip/blob/main/lib/container.go)](https://github.com/Loyalsoldier/geoip/blob/master/lib/container.go).

The process flow reads a [`config.json`](https://github.com/loyalsoldier/geoip/blob/main/config.json), aggregates inputs through various parsers, deduplicates entries, and dispatches to **output plugins** implementing the `Output` interface:

```go
// 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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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.