Orange configuration.

Orange uses TOML format for configuration. The configuration file controls all aspects of the network engine including DNS resolution, proxy services, routing rules, and TUN mode settings.

Copy the bundled example to start from a known-good baseline, then edit as needed.

Global settings for the Orange engine including logging and IP address family policy.

Core DNS server settings — listener, concurrency, and cache. Other DNS concerns are covered in their own sections: Reverse Cache, Rate Limit, Bootstrap, Local Network, DoT, DoH, Rules, and Fake-IP.

IP-to-domain reverse lookup cache. Used by TUN mode to recover the original hostname from a destination IP so that domain-based routing rules and logging still work after DNS has been resolved. Set either threshold to 0 to disable.

Defends against DNS amplification attacks by limiting requests per client IP over a sliding time window.

DNS servers used to resolve infrastructure hostnames (upstream proxies, DoH/DoT providers, WireGuard endpoints). Bootstrap queries are forced to bypass the TUN tunnel and go out on the physical interface, preventing circular routing. Static hostname-to-IP mappings for infrastructure are now unified under [dns.rules].

Opts local-network domains (mDNS, LAN suffixes, service discovery) out of upstream DNS so they stay on the local link and do not leak to external resolvers. Matched queries return NoError + empty Answer (not NXDOMAIN) so that RFC 2308 negative caching does not block subsequent mDNS attempts.

Exposes the DNS service over TLS, typically on port 853. Requires a valid TLS certificate and private key in PEM format.

Exposes the DNS service over HTTPS, typically on port 443. Standard query path is /dns-query (RFC 8484).

Unified DNS routing table. The same rule set applies to every inbound (TUN, HTTP, SOCKS). Shorthand syntax covers reject and simple host mappings; the full { ... } form is required for DNS upstreams, conditional matches, and rewrites. Infrastructure hostnames (upstream proxies, DoH/DoT providers, WireGuard endpoints) should use { host = "..." } mappings here so they resolve without a circular lookup.

Rule values can be a shorthand string ("reject" or a literal IP hosts mapping), a single full-form object, or an array of objects evaluated top-to-bottom. Conditions use the when object; today the supported field is src (CIDR, supports negation with ! and multi-value with ,).

# Shorthand — reject
"*.ads.com" = "reject"

# Shorthand — hosts mapping
"example.com" = "127.0.0.1"

# Full form — hosts mapping
"example.com" = { host = "127.0.0.1" }

# DNS upstream
"@geosite:cn" = { to = ["223.5.5.5"] }

# Multiple upstreams (concurrent)
"example.com" = { to = ["8.8.8.8", "1.1.1.1"] }

# With specific outbound
"*.internal" = { to = ["10.0.0.53"], via = "wg-home" }

# Conditional rules (by source IP)
"*.corp" = [
  { when = { src = "10.0.0.0/8" },  to     = ["10.0.0.53"] },
  { when = { src = "!10.0.0.0/8" }, reject = true },
]

# Suffix rewrite — ask the router for .loc while the client queries .local
# rewrite requires a wildcard pattern (*.local / +.local) and must start with '.'
"*.local" = [
  { when = { src = "192.168.0.0/16" }, to = ["192.168.1.2"], rewrite = ".loc" },
]

# Default upstream (required)
"default" = { to = ["8.8.8.8"] }

Assigns virtual IPs from 198.18.0.0/15 to hostnames so that clients can start a connection immediately; Orange then recovers the hostname at the TUN/proxy boundary to make routing decisions. Best suited to TUN transparent proxy mode. IPv4 only — AAAA queries return empty responses, and the 198.18.0.0/15 range must not be used for anything else.

Top-level settings that apply across every inbound proxy: shared authentication, domain-resolution policy for IP-based rule matching, and the routing-rule match cache. Inbound listeners (HTTP, SOCKS5, Mixed), TLS, Physical interface binding, Upstreams, Upstream Health Check, and Routing Rules each have their own section.

HTTP/HTTPS proxy on a single port. Handles HTTP forward proxy, HTTPS CONNECT tunnels, and WebSocket upgrades from the same listener.

Optional connection reuse to reduce handshake overhead to upstream HTTP/HTTPS proxies.

RFC 1928 SOCKS5 implementation focused on the CONNECT command. Supports domain, IPv4, and IPv6 targets. Authentication is either none or RFC 1929 username/password (configured via [proxy] auth). The BIND command is not supported.

Serves HTTP and SOCKS5 on the same port. Orange sniffs the first byte: 0x05 routes into the SOCKS5 handler, anything else is treated as HTTP (including CONNECT tunnels). The mixed listener can run alongside dedicated HTTP/SOCKS5 listeners. Routing rules apply uniformly to every inbound.

TLS settings that apply to upstream encrypted connections.

Prevents routing loops in TUN mode by binding upstream connections to the physical network interface rather than the TUN device. Only relevant when TUN mode is active; HTTP/SOCKS-only deployments do not need this. On macOS/iOS the recommended alternative is Swift-side excludedRoutes.

Define the upstream proxies Orange can route traffic through. Each upstream is referenced from [[proxy.rules]] by its name. The primary types are https and wireguard; trojan and shadowsocks (SIP022) are also available for specific deployments. Every upstream can override the global health check with its own health_check block or disable probing entirely via health_check = { disabled = true }.

[[proxy.upstreams]]
type = "https"
name = "http-us"

[proxy.upstreams.config]
addr = "gateway.example.com:443"
auth = "user:pass"

# H2 connection pool (optional)
[proxy.upstreams.config.h2]
soft_max_age_secs = 120    # Soft TTL, no new requests after
idle_timeout_secs = 30     # Close idle connections
max_streams       = 100    # Max concurrent streams per conn
max_conns         = 2      # Max H2 connections per upstream

Encrypted TLS transport authenticated by password. Available for deployments that already use a compatible upstream.

[[proxy.upstreams]]
type = "trojan"
name = "trojan-01"

[proxy.upstreams.config]
addr     = "gateway.example.com:443"
password = "your-password-here"

Encrypted transport with a pre-shared key (SIP022). Available for deployments that already use a compatible upstream.

[[proxy.upstreams]]
type = "shadowsocks"
name = "ss-01"

[proxy.upstreams.config]
addr   = "gateway.example.com:8388"
method = "2022-blake3-aes-256-gcm"
psk    = "your-base64-encoded-psk"

[[proxy.upstreams]]
type = "wireguard"
name = "wg-home"

[proxy.upstreams.config]
endpoint   = "vpn.example.com:51820"
publicKey  = "xxxxxxxxxxx="
privateKey = "yyyyyyyyyyy="
address    = "10.0.0.2/24"
allowedIPs = "0.0.0.0/0,::/0"
dns        = "10.0.0.1"
# mode = "auto"  # auto (default) | userspace | kernel
# mtu  = 1420    # Default 1420. PPPoE: 1412. Range: 576-9000.

Kernel mode requires privileges: Linux needs CAP_NET_ADMIN and the ip command; macOS needs sudo, ifconfig, and route; Windows is not supported. Userspace mode has no such requirements but needs separate route setup.

# Override target and timeout
health_check = { url = "http://cp.cloudflare.com", timeout_secs = 3 }

# WireGuard probe uses IP:Port
health_check = { url = "1.1.1.1:443" }

# Disable probing for this upstream
health_check = { disabled = true }

Periodically probes each upstream and exposes the result through /health, Prometheus metrics, and logs. The values here form the global default; any upstream can override them inline (see the Upstreams section).

Decides what each connection does: stay direct, take a tunnel, or be rejected. Rules can match on domain, IP CIDR, GeoSite tag, or GeoIP tag, and can be filtered by a when object covering source IP, port, inbound type, and ALPN.

# Exact domain match — office intranet
[[proxy.rules]]
domain = "api.internal.corp"
to     = "wg-office"

# Wildcard domain — home network
[[proxy.rules]]
domain = "*.home.lab"
to     = "wg-home"

# Reject ad subdomains (does not match the apex)
[[proxy.rules]]
domain = "+.ads.example.com"
reject = true

# Conditional: home network direct, others via WireGuard
[[proxy.rules]]
domain = "*.home.lab"
when   = { src = "192.168.1.0/24" }
direct = true

[[proxy.rules]]
domain = "*.home.lab"
to     = "wg-home"

# GeoSite match — block ads
[[proxy.rules]]
geosite = "category-ads-all"
reject  = true

# GeoIP private IPs direct
[[proxy.rules]]
geoip  = "private"
direct = true

# SSH direct
[[proxy.rules]]
port   = 22
direct = true

# Force resolve so IP/GeoIP rules can match this domain
[[proxy.rules]]
domain     = "audit.example"
resolve_ip = true
to         = "http-us"

# Fallback (no match condition) — auto moved to end
[[proxy.rules]]
direct = true

System-level network gateway over a virtual interface. Captures all OS-level traffic and feeds it into the routing engine. Requires admin privileges on Linux/macOS and is not supported on Windows. SNI/HTTP sniffing lives in its own section.

Extracts TLS SNI or HTTP Host from the first bytes of a TCP connection so that domain-based routing rules still work when only an IP destination is visible. Sniffing requires the client to speak first; enabling it on server-first protocols (MySQL, SMTP, SSH) introduces timeout delays. The default port allow-list keeps it limited to HTTP/HTTPS-style traffic.

Connection timeout settings.

HTTP endpoints for health, metrics, live streams, and configuration reload. Target: Kubernetes liveness/readiness probes, load balancer checks, monitoring systems, and real-time dashboards.

{
  "status": "ok",
  "upstreams": [
    {
      "name":                 "http-us",
      "type":                 "https",
      "latency_ms":           120,
      "average_latency_ms":   115,
      "available":            true,
      "last_check_ago_secs":  15
    }
  ]
}

curl http://127.0.0.1:9898/health | jq
curl http://127.0.0.1:9898/metrics
curl -N http://127.0.0.1:9898/api/metrics/live

Tunes the Server-Sent Events push cadence for /api/metrics/live. Orange only computes and broadcasts when at least one subscriber is attached — no background work happens while idle. Subscribers that cannot handle 1 Hz (mobile apps in background, embedded devices) should throttle or pause on the client side; raise interval_ms only when that is not an option.

Real-time request lifecycle tracing. Traces are pushed to UI clients over WebSocket so dashboards can observe every proxied request as it flows through the engine.

Controls how trace events are aggregated before being delivered to WebSocket subscribers. Tighter flush intervals reduce end-to-end latency; larger batches reduce frame overhead.

Adaptive protection for memory-constrained environments (e.g. iOS NetworkExtension's ~50 MB limit). A background monitor polls the Rust allocator and triggers tiered mitigations when thresholds are crossed, preventing the process from being killed by the OS.

[memory_pressure]
warning_bytes     = 31457280   # 30 MB
critical_bytes    = 39845888   # 38 MB
emergency_bytes   = 46137344   # 44 MB
check_interval_ms = 5000

GeoSite and GeoIP datasets for large-scale domain/IP classification. Supports local files and HTTP URLs with automatic caching.

[dataset]
geosite = ["./data/sites.dat"]
geoip   = ["./data/ips.dat"]