Skip to main content

IP Providers

These providers manage text IP/CIDR sets or V2Ray geoip data.

ip_set​

Purpose​

Provides IP and CIDR rule sets that can be referenced by matchers such as client_ip, resp_ip, and ptr_ip.

Example Configuration​

- tag: lan_ip_set
  type: ip_set
  args:
    ips:
      # Single IPv4
      - "192.168.1.1"
      # IPv4 CIDR
      - "192.168.0.0/16"
      - "10.0.0.0/8"
      # Single IPv6
      - "2001:db8::1"
      # IPv6 CIDR
      - "fd00::/8"
    files:
      # Merge more IP / CIDR entries from files
      - "/etc/oxidns/ips.txt"
    sets:
      # Reuse another IP-capable provider
      - "shared_ip_set"
      - "shared_geoip"

Configuration Details​

ips​

  • Type: array; Required: no; Default: empty array
  • Purpose: Defines inline IP or CIDR rules.
  • Examples:
    • - "1.1.1.1"
    • - "192.168.0.0/16"
    • - "2400:3200::/32"
  • Supported forms:
    • Individual IPv4 addresses
    • Individual IPv6 addresses
    • IPv4 CIDRs
    • IPv6 CIDRs
  • Runtime impact:
    • Compiled into address matching structures during initialization.

files​

  • Type: array; Required: no; Default: empty array
  • Purpose: Lists external IP rule files.
  • Example: - "/etc/oxidns/ips.txt"
  • File requirements:
    • One IP or CIDR rule per line.
    • Empty lines and comment lines are ignored.
  • Runtime impact:
    • File contents are re-read during initialization or reload_provider and compiled into the current provider's local matcher.

sets​

  • Type: array; Required: no; Default: empty array
  • Purpose: References other providers with IP match capability.
  • Example: - "shared_ip_set"
  • Constraints:
    • ip_set, geoip, and other IP-capable providers are allowed.
  • Runtime impact:
    • The current provider keeps stable handles to referenced providers instead of copying their rules.
    • After a downstream provider reloads, the current ip_set sees the new result without reloading itself.

Behavior​

  • Initialization and reload only compile local ips and files.
  • IPv4 and IPv6 rule indexes are maintained separately.
  • Runtime matching checks the local matcher first and then evaluates referenced providers in sets declaration order.

Rule Formats​

  • 1.1.1.1
  • 192.168.0.0/16
  • 2400:3200::/32

Typical Uses​

  • Define LAN, WAN, overlay, or infrastructure address groups.
  • Build allowlists, bypass lists, or target network sets.
  • Combine local CIDRs with shared geoip or ip_set providers behind one reusable entrypoint.
Notes
  • sets may reference any provider with IP match capability.
  • Changing provider topology, tags, or config structure still requires a full reload; reload_provider only refreshes the current provider's existing config and external data files.

geoip​

Purpose​

Loads reusable IP and CIDR rules from v2ray-rules-dat geoip.dat.

Example Configuration​

- tag: geoip_cn
  type: geoip
  args:
    file: "/etc/oxidns/geoip.dat"
    selectors:
      - "cn"

Configuration Details​

  • file
    • Type: string; Required: yes
    • Path to geoip.dat.
  • selectors
    • Type: array; Required: no; Default: empty array
    • Case-insensitive exact code filter.
    • Multiple selectors are merged as a union.
    • Omit it or pass [] to load the full union of every entry in the dat file.

Composition Examples​

Match either the client source address or addresses in a DNS response directly:

plugins:
  - tag: geoip_cn
    type: geoip
    args:
      file: "/etc/oxidns/geoip.dat"
      selectors: ["cn"]

  - tag: match_client_cn
    type: client_ip
    args: ["$geoip_cn"]

  - tag: match_answer_cn
    type: resp_ip
    args: ["$geoip_cn"]

Combine GeoIP data with local CIDRs for reuse by several matchers:

- tag: cn_or_private_network
  type: ip_set
  args:
    ips:
      - "10.0.0.0/8"
      - "fd00::/8"
    sets:
      - "geoip_cn"

- tag: match_cn_or_private_client
  type: client_ip
  args: ["$cn_or_private_network"]

Behavior​

  • Exposes IP-only membership checks.
  • Can be referenced directly by client_ip, resp_ip, and ptr_ip, or composed by ip_set.
  • Supports independent refresh through reload_provider or POST /plugins/<tag>/reload.
  • To pre-export selected rules into text files before runtime, use oxidns export-dat --kind geoip.
Selector Notes
  • GeoIP selectors accept codes only; @attribute, wildcards, and exclusion expressions are not supported.
  • Startup and provider reload fail when a requested selector matches no entry. Validate it first with oxidns export-dat --kind geoip --selector <selector>.
  • Omitting selectors loads the whole dat file, which is usually large. Prefer the codes that the production policy actually needs.