Use cases · Rule atlas

Every rule you'll actually write.

Start with full scenarios, then scan routing and DNS patterns as one reference atlas. Copy the example, adapt the names, ship the config.

Scenarios

Start here.

These examples show how Orange reads as a product when DNS, routing, and network conditions are combined into one operating pattern.

03 patterns
Primary pattern Direct at home · Tunnel outside
One private destination. Two transport paths. Chosen by location.

Direct at home, tunnel outside

This is the clearest expression of Orange. The same logical destination keeps the same name, but the transport changes automatically depending on where the user is.

On trusted LAN
Private destinations resolve and connect directly, with no tunnel overhead.
When remote
The same logical domain falls back to WireGuard, so remote access does not require a second mental model.
Why it matters
Users learn Orange as a behavioral pattern, not as a pile of isolated DNS and routing features.
config.toml Full example 
# DNS: static mapping for home devices
[dns.rules]
"nas.home"      = { host = "192.168.1.100" }
"router.home"   = { host = "192.168.1.1" }
"pi.home"       = { host = "192.168.1.50" }
"*.home.lab"    = { to = ["192.168.1.1"] }
"default"       = { to = ["8.8.8.8", "1.1.1.1"] }

# Routing: direct when home, tunnel when outside
[[proxy.rules]]
geoip  = "private"
direct = true

[[proxy.rules]]
domain = "*.home.lab"
when   = { src = "192.168.1.0/24" }
direct = true

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

Ad and tracker blocking

Block noisy domains early at the DNS layer, then use routing rules as a second net for anything that still resolves.

Use this when privacy rules need to stay visible and auditable instead of disappearing into a separate blocklist product.

Minimal example 
[dns.rules]
"@geosite:category-ads-all" = "reject"
"*.doubleclick.net"        = "reject"

[[proxy.rules]]
geosite = "category-ads-all"
reject  = true
Scenario C

Multi-site office

Choose the correct path based on the current network location: direct on-site, WireGuard when off-site.

Use this when users should keep one set of internal names even while moving between offices and remote networks.

Minimal example 
[[proxy.rules]]
domain = "*.site-a.internal"
when   = { src = "192.168.1.0/24" }
direct = true

[[proxy.rules]]
domain = "*.site-a.internal"
to     = "wg-site-a"
Reference · Routing

Routing rules.

Scan-first atlas. Each row states the pattern, when to use it, and the shortest example that carries the idea.

20 patterns

Network environment awareness

04 patterns
Pattern Use when Example
Home LAN direct
Access NAS, router, and other private devices directly when the client is already on the trusted home network.
ip_cidr = "192.168.1.0/24"
when    = { src = "192.168.1.0/24" }
direct  = true
Remote home access
Reach the same private range when outside the house by sending those destinations through WireGuard.
ip_cidr = "192.168.1.0/24"
to      = "wg-home"
Home lab domain
Keep one domain name for home lab services while switching between direct access and tunnel access by location.
domain = "*.home.lab"
when   = { src = "192.168.1.0/24" }
direct = true
Office intranet
Keep corporate internal domains direct when the client is physically inside the office network.
domain = "*.internal.corp"
when   = { src = "10.0.0.0/8" }
direct = true

Development environment

04 patterns
Pattern Use when Example
Local dev domains
Make localhost-style domains bypass the gateway so local applications and test hosts behave normally.
domain = "*.localhost"
direct = true
Dev server ports
Keep common app server ports direct during frontend and backend development.
when   = { port = "3000,5173,8080-8999" }
direct = true
Database ports
Avoid proxy interference for MySQL, PostgreSQL, Redis, and similar databases used during development.
when   = { port = "3306,5432,6379,27017" }
direct = true
SSH direct
Keep SSH sessions predictable by excluding them from gateway routing.
when   = { port = "22" }
direct = true

Ads and privacy protection

04 patterns
Pattern Use when Example
GeoSite ad block
Use a maintained category list when you want broad ad blocking without hand-curating domain lists.
geosite = "category-ads-all"
reject  = true
Wildcard ad block
Block a known ad-serving namespace with a domain suffix pattern.
domain = "*.ads.example.com"
reject = true
Tracker block
Reject analytics or user-tracking endpoints without affecting the rest of the application.
domain = "*.tracking.example.com"
reject = true
Telemetry block
Block telemetry uploads when applications should function but stay silent.
domain = "*.telemetry.example.com"
reject = true

Port and protocol routing

04 patterns
Pattern Use when Example
HTTPS via gateway
Send only secure web traffic for a domain through a specific gateway while leaving other ports untouched.
domain = "*.example.com"
when   = { port = "443" }
to     = "gateway-1"
UDP gaming route
Place latency-sensitive UDP traffic on a dedicated line or gateway.
when = { inbound = "udp" }
to   = "gateway-game"
TUN mode only
Limit a rule to packets captured from the TUN stack instead of applying it to every inbound path.
domain = "*.example.com"
when   = { inbound = "tun" }
to     = "gateway-1"
H2 protocol route
Handle HTTP/2 traffic differently when APIs or upstreams need a separate path.
domain = "*.api.example.com"
when   = { alpn = "h2" }
to     = "gateway-h2"

Domain matching patterns

04 patterns
Pattern Use when Example
Exact match
Target one exact hostname when the rule must not apply to siblings or descendants.
domain = "api.internal.corp"
to     = "wg-office"
Subdomain only (+.)
Match subdomains while intentionally excluding the root domain itself.
domain = "+.internal.corp"
to     = "wg-office"
Wildcard (*.)
Match the root domain and all child domains with one pattern.
domain = "*.home.lab"
to     = "wg-home"
GeoSite dataset
Use a named dataset when a maintained domain collection is more practical than writing explicit patterns.
geosite = "category-ads-all"
reject  = true
Reference · DNS

DNS rules.

DNS examples stay visible by default so the section works as a scanning table, not as a collapsed tutorial.

12 patterns

Basic configuration

03 patterns
Pattern Use when Example
Specify upstream DNS
Send one domain to a chosen resolver instead of using the default upstream.
"example.com" = { to = ["8.8.8.8"] }
Concurrent DNS queries
Fan out to multiple upstreams when speed or resolver redundancy matters more than strict ordering.
"example.com" = { to = ["8.8.8.8", "1.1.1.1"] }
Default upstream
Provide a global fallback resolver for domains that do not match any specific rule.
"default" = { to = ["8.8.8.8"] }

Hosts mapping

03 patterns
Pattern Use when Example
Static IP mapping
Return a fixed address for a known internal device without querying an upstream DNS server.
"nas.home" = { host = "192.168.1.100" }
Shorthand syntax
Use the compact host mapping form when you do not need additional rule fields.
"router.home" = "192.168.1.1"
Gateway server IP
Pin the gateway hostname to an address to avoid DNS loops or chicken-and-egg resolver problems.
"gateway.example.com" = { host = "203.0.113.10" }

Reject and block

03 patterns
Pattern Use when Example
Reject (shorthand)
Return an immediate negative response for a blocked namespace with the shortest possible syntax.
"*.ads.example.com" = "reject"
Reject (full form)
Use the explicit object form when the rule may later need more options.
"*.tracking.com" = { reject = true }
GeoSite ad block
Apply a maintained domain collection directly at the DNS layer for broad rejection.
"@geosite:category-ads-all" = "reject"

Conditional DNS

03 patterns
Pattern Use when Example
Source IP condition
Choose a resolver based on the current network so internal names only use internal DNS when appropriate.
"*.internal" = {
  when = { src = "10.0.0.0/8" },
  to   = ["10.0.0.53"]
}
Internal-only resolution
Allow internal clients to resolve a name while rejecting the same name outside the trusted network.
"*.corp.local" = [
  { when = { src = "10.0.0.0/8" },  to     = ["10.0.0.53"] },
  { when = { src = "!10.0.0.0/8" }, reject = true }
]
DNS over WireGuard
Resolve a private namespace through a specific tunnel when the internal resolver is only reachable remotely.
"*.home.lab" = {
  to  = ["192.168.1.1"],
  via = "wg-home"
}
Reference · Quick

Syntax at a glance.

Which fields exist, how matching works, what wins when multiple rules overlap.

Syntax

Condition fields

Field Description Example values
src
Source IP in CIDR form. Supports negation and comma-separated multiple values.
"192.168.1.0/24", "!10.0.0.0/8", "192.168.0.0/16,10.0.0.0/8"
port
Destination port. Supports single values, ranges, and negation.
"443", "80,443", "8000-9000", "!22"
inbound
Inbound type, such as TCP, UDP, or TUN-originated traffic.
"tcp", "udp", "tun", "mixed", "tcp,tun"
alpn
Application-layer protocol for rules that care about HTTP versions and transport negotiation.
"h2", "http/1.1", "h3", "h2,http/1.1"

DNS matching

Pattern Meaning Matches
"example.com"
Exact match only.
example.com
"+.example.com"
Subdomains only. Excludes the root domain.
api.example.com, www.example.com
"*.example.com"
Root domain and all subdomains.
example.com, api.example.com
"@geosite:google"
Named domain collection from the GeoSite dataset.
All domains contained in that dataset entry

Rule priority

Domain rules

  • 1 "api.internal.corp" Exact match
  • 2 "+.internal.corp" Long suffix
  • 3 "*.internal.corp" Long suffix
  • 4 "*.corp" Short suffix

IP rules

  • 1 "10.1.2.0/24" /24 first
  • 2 "10.1.0.0/16" /16 next
  • 3 "10.0.0.0/8" /8 last

Cross-type rules

  • Different rule types, such as domain and geosite, follow the order they appear in the config file.
  • Keep the most specific rules earlier when different types may overlap.
Next step

Ready to wire it up?

Copy any example above into your Orange config — or open the full reference for every field.

Open documentation Back to overview