# Rule > Domain-based, IP-based, HTTP, process, and logical rules [← Back to index](/llms.txt) --- # Proxy Rule ## Rule Surge forwards requests to proxy servers or direct connections based on customized rules. ### Priority "Rules are matched from the first one to the last one, in the order they appear in the config file." Rules positioned earlier in the configuration have precedence over subsequent ones. ### Composition Each rule contains three components: the rule type, a matcher (except for FINAL rules), and a proxy policy: ``` TYPE, VALUE, POLICY DOMAIN-SUFFIX,apple.com, DIRECT IP-CIDR, 192.168.0.0/16,ProxyA ``` Surge supports multiple rule types (detailed in subcategories). Policies can be built-in options, proxy policies, or policy groups. All rule sets must conclude with a FINAL rule to establish default behavior. ### Example Configuration ``` [Rule] DOMAIN-SUFFIX,company.com,ProxyA DOMAIN-KEYWORD,google,DIRECT GEOIP,US,DIRECT IP-CIDR,192.168.0.0/16,DIRECT FINAL,ProxyB ``` Domain-based rules include DOMAIN, DOMAIN-SUFFIX, and DOMAIN-KEYWORD. IP-based rules encompass IP-CIDR and GEOIP. ## Domain based # Domain-based Rule Domain-based rules determine proxy routing by matching request domains. There are three main types available. ## Rule Types **DOMAIN** ``` DOMAIN,www.apple.com,Proxy ``` Matches when the domain exactly equals the specified value. **DOMAIN-SUFFIX** ``` DOMAIN-SUFFIX,apple.com,Proxy ``` Matches domains that end with the specified suffix. For instance, `google.com` will match `www.google.com`, `mail.google.com`, and `google.com` itself, but it will not match `content-google.com`. **DOMAIN-KEYWORD** ``` DOMAIN-KEYWORD,google,Proxy ``` Matches when the domain contains the specified keyword anywhere within it. **DOMAIN-SET** Optimized for matching large numbers of domains with efficient searching capabilities. Lines beginning with a period (`.`) match the specified domain and all its subdomains, making this useful for ad-blocking scenarios. ## Extended Matching Parameter The `extended-matching` parameter (iOS 5.8.0+, Mac 5.4.0+) enables matching against both SNI and HTTP Host Header (or `:authority`). This parameter applies to `DOMAIN`, `DOMAIN-SUFFIX`, and `DOMAIN-KEYWORD` rules, and can be propagated to `DOMAIN-SET` entries by appending it to the corresponding ruleset line. ## Final # Final Rule The FINAL rule serves as a catch-all mechanism that must appear after all other rules in a configuration. It establishes the default policy for any requests that don't match preceding rule conditions. ## Example Configuration ``` [Rule] DOMAIN-SUFFIX,company.com,ProxyA DOMAIN-KEYWORD,google,DIRECT GEOIP,US,DIRECT IP-CIDR,192.168.0.0/16,DIRECT FINAL,ProxyB ``` ## Options ### dns-failed "Use the FINAL rule if the DNS lookup fails during rule evaluation." This option applies only when paired with a non-DIRECT policy, allowing fallback behavior when domain resolution encounters errors. ## Http # HTTP Rule HTTP rules apply to HTTP and HTTPS requests but do not affect TCP connections. ## USER-AGENT ``` USER-AGENT,Instagram*,DIRECT ``` This rule type matches requests based on the user agent string. The pattern supports wildcard characters `*` and `?`. ## URL-REGEX ``` URL-REGEX,^http://google\.com,DIRECT ``` This rule matches requests where the URL conforms to the specified regular expression pattern. ### Extended Matching Option You can add the `extended-matching` parameter to also evaluate the HTTP Host header (or `:authority`) and SNI values, which is useful when TLS handshake details are required: ``` URL-REGEX,^https://example\.com,Proxy,extended-matching ``` ## Ip based # IP-based Rule IP-based rules match requests based on their IP addresses. There are three main types available in Surge. ## Rule Types **IP-CIDR** Matches when the request's IP address falls within a specified CIDR range: ``` IP-CIDR,192.168.0.0/16,DIRECT IP-CIDR,10.0.0.0/8,DIRECT IP-CIDR,172.16.0.0/12,DIRECT IP-CIDR,127.0.0.1/8,DIRECT ``` Starting with Surge Mac 6.0.0, single IPv4 addresses can be written without a mask (treated as `/32`). **IP-CIDR6** Matches when the request's IPv6 address falls within a specified range: ``` IP-CIDR6,2001:db8:abcd:8000::/50,DIRECT ``` Single IPv6 addresses are supported similarly to IPv4. **GEOIP** ``` GEOIP,US,DIRECT ``` Matches based on the country code derived from GeoIP lookups. **IP-ASN** ``` IP-ASN,1234,DIRECT ``` Matches when the autonomous system number of the remote IP address corresponds to the specified value. ## Important Behavior "An IP-based rule will trigger a DNS lookup if the hostname of the request is a domain. If the DNS lookup fails, Surge will abort the rule testing and report an error." ## Parameters **no-resolve** ``` GEOIP,US,DIRECT,no-resolve IP-CIDR,172.16.0.0/12,DIRECT,no-resolve ``` This parameter skips DNS queries for domain-based requests, preventing rule testing failures when domains cannot be resolved locally. ## Logical rule # Logical Rule Logical Rule allows you to "combine multiple rules for complex scenarios" and enables nesting of logical rules within one another. ## AND Rule This rule type matches when all sub-rules evaluate as true. **Syntax:** `AND,((#Rule1), (#Rule2), (#Rule3)...),Policy` **Example:** ``` AND,((SRC-IP,192.168.1.110), (DOMAIN, example.com)),DIRECT ``` ## OR Rule This rule type matches when at least one sub-rule evaluates as true. **Syntax:** `OR,((#Rule1), (#Rule2), (#Rule3)...),Policy` **Example:** ``` OR,((SRC-IP,192.168.1.110), (SRC-IP,192.168.1.111)),DIRECT ``` ## NOT Rule This rule type inverts the evaluation result of the wrapped rule. **Syntax:** `NOT,((#Rule1)),Policy` **Example:** ``` AND,((NOT,((SRC-IP,192.168.1.110))),(DOMAIN, example.com)),DIRECT ``` ## Misc rule # Misc Rule ## Miscellaneous Rule ### Port Number Rules Port number rules support three expression types: - Direct port numbers: `IN-PORT,6153` - Closed intervals: `DEST-PORT,10000-20000` - Operators (>, <, <=, >=): `SRC-PORT,>=50000` (iOS 5.8.4+, Mac 5.4.4+) #### DEST-PORT Matches if the target port of the request corresponds to the specified value. ``` DEST-PORT,80-81,DIRECT ``` #### IN-PORT Matches if the incoming port where Surge is listening matches. Useful when Surge listens on multiple ports. ``` IN-PORT,6152,DIRECT ``` #### SRC-PORT Matches if the client port number matches the specified value. ``` SRC-PORT,>=50000,DIRECT ``` ### Other Rule Types #### SRC-IP Matches if the client IP address matches. Only applies to remote machines. Supports CIDR notation. ``` SRC-IP,192.168.20.100,DIRECT SRC-IP,192.168.20.0/24,DIRECT ``` #### PROTOCOL Matches if the request protocol corresponds to specified values: HTTP, HTTPS, TCP, UDP, DOH, DOH3, DOQ, QUIC, STUN. ``` PROTOCOL,HTTP,DIRECT ``` Notes: TCP covers HTTP/HTTPS; DOH/DOH3/DOQ match encrypted DNS from Surge; UDP can match QUIC traffic; STUN filters P2P traffic. #### SCRIPT Executes JavaScript to determine if a match occurs. ``` SCRIPT,ScriptName,DIRECT ``` #### CELLULAR-RADIO iOS only. Matches cellular radio technology: GPRS, Edge, WCDMA, HSDPA, HSUPA, CDMA1x, CDMAEVDORev0, CDMAEVDORevA, CDMAEVDORevB, eHRPD, HRPD, LTE, NRNSA, NR. ``` CELLULAR-RADIO,LTE,DIRECT ``` #### DEVICE-NAME Matches the client device name from system settings or custom names in the device view. #### MAC-ADDRESS Matches the MAC address of accessing devices on the same local area network (Mac 6.1.0+). #### HOSTNAME-TYPE Matches hostname forms. Supported keywords: `IPv4`, `IPv6`, `DOMAIN`, `SIMPLE` (Mac 5.7.3+). ``` HOSTNAME-TYPE,IPv6,REJECT HOSTNAME-TYPE,SIMPLE,DIRECT ``` ## Process # Process Rule Process Rule enables you to assign a proxy policy to requests from a specified process. This feature is available exclusively for Surge Mac; Surge iOS does not support process rules. ## PROCESS-NAME (Mac Only) **Syntax:** ``` PROCESS-NAME,Telegram,Proxy ``` **Functionality:** The rule matches when the process name associated with the request corresponds to the specified value. The rule supports wildcard characters `*` and `?` for pattern matching. **Note on Specification:** You can designate either the filename or the complete path of the executable file. For macOS application packages, the executable is typically located within the `.app/Contents/MacOS` directory structure. ## Ruleset # Ruleset Rulesets allow bundling multiple rules from files or URLs. Surge provides two internal rulesets and supports external sources. ## Internal Rulesets ### SYSTEM `RULE-SET,SYSTEM,DIRECT` "Includes rules for most requests sent by macOS and iOS itself." This covers system services like Maps, Find My, and Weather Foundation, though App Store and iTunes content services are excluded. Sample rules include USER-AGENT matching for Apple services, domains like `api.smoot.apple.com` and `captive.apple.com`, and process-based filtering. > "These rules may be updated with Surge updates." ### LAN `RULE-SET,LAN,DIRECT` "Includes rules for LAN IP addresses and .local suffix." This ruleset triggers DNS lookups and covers: - Local domain suffix - Private IP ranges (192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12, 127.0.0.0/8, 100.64.0.0/10) - IPv6 link-local addresses (fe80::/10) ## External Rulesets External rulesets reference text files from URLs or local storage. Each line contains a rule without a policy assignment: ``` DOMAIN,exampleA.com DOMAIN,exampleB.com ``` Optional parameters for `RULE-SET` include: - `no-resolve`: Skip DNS resolution during matching - `extended-matching`: Match domain rules against both SNI and HTTP Host headers ## Inline Rulesets (Mac 5.3.1+) Rules can be embedded directly in profiles using `[Ruleset Streaming]` sections: ``` [Ruleset Streaming] DOMAIN-SUFFIX,netflix.com DOMAIN-SUFFIX,netflix.net [Rule] RULE-SET,Streaming,StreamingProxy ``` Inline rulesets use identical syntax to external files with the same optimization benefits. ## Subnet # Subnet Expression & Rule ## Subnet Rule ### Subnet Expression A subnet expression can match networks using one of these formats: - **SSID matching**: `SSID:value` matches Wi-Fi network names (wildcards supported) - **BSSID matching**: `BSSID:value` matches Wi-Fi hardware addresses (wildcards supported) - **Router IP**: `ROUTER:value` matches the router's IP address - **Network type**: `TYPE:WIFI`, `TYPE:WIRED`, or `TYPE:CELLULAR` for broad categorization - **Legacy format**: Omitting a prefix attempts to match SSID/BSSID/Router for backward compatibility ### SUBNET Rule The SUBNET rule applies a policy when the subnet expression matches the current network environment. **Examples:** ``` SUBNET,TYPE:WIRED,DIRECT SUBNET,SSID:MyHome,Proxy ``` These examples demonstrate routing traffic directly for wired connections and through a proxy when connected to the "MyHome" Wi-Fi network.