Rules Overview

Surge decides how to handle every request by testing it against the rule list in the [Rule] section of the profile. Each rule pairs a matching condition with a policy: forward the request to a proxy, connect directly, or reject it.

[Rule]
DOMAIN-SUFFIX,company.com,ProxyA
DOMAIN-KEYWORD,google,DIRECT
GEOIP,US,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,ProxyB

Composition

Each rule consists of three parts: a rule type, a value to match, and a policy.

           TYPE,          VALUE,          POLICY
Example:   DOMAIN-SUFFIX, apple.com,      DIRECT
           IP-CIDR,       192.168.0.0/16, ProxyA

• TYPE: one of the rule types listed in the index below.
• VALUE: what the rule matches against. The FINAL rule has no value. If a value contains commas (e.g. a regex), wrap it in double or single quotes.
• POLICY: the name of a proxy policy, a policy group, a built-in policy such as DIRECT or the REJECT family, or a DEVICE:<name> policy targeting a Surge Ponte device.

Optional parameters may be appended after the policy, separated by commas:

IP-CIDR,192.168.0.0/16,DIRECT,no-resolve

Inline comments starting with //, #, or ; are allowed at the end of a rule line.

The rule list must end with an enabled FINAL rule, which defines the default policy for requests that match nothing else.

Evaluation Order

Rules are evaluated strictly from top to bottom. The first rule that matches decides the policy; all later rules are ignored. Order your rules from most specific to most general.

Two things bypass the normal top-to-bottom evaluation:

• Rules tagged with pre-matching are extracted and checked before everything else (see Pre-matching).
• When the outbound mode is set to Direct or Global instead of Rule-Based, the rule list is not consulted at all.

Rules and DNS

Domain-based rules only inspect the requested hostname, so they never require a DNS lookup. IP-based rules (IP-CIDR, IP-CIDR6, GEOIP, IP-ASN) match against the resolved IP address:

• If the request already targets an IP literal, IP-based rules match it directly, and GEOIP/IP-ASN look it up without a DNS query.
• If the request targets a domain, evaluation pauses at the first IP-based rule, Surge performs the DNS lookup, and evaluation resumes at the same rule. The result is cached, so at most one lookup is performed per request.
• With the no-resolve parameter, an IP-based rule is simply skipped for requests whose address has not been resolved, instead of triggering a lookup.

If the DNS lookup fails, rule evaluation aborts and the request fails with a DNS error — unless the FINAL rule carries the dns-failed parameter, in which case the FINAL policy is used instead.

Pre-matching

Normally a rule decision happens only after Surge receives the first packet of a connection. Rules tagged with pre-matching and using a REJECT-family policy are additionally evaluated at the DNS-query and TCP-handshake stages, so unwanted requests are rejected with minimal overhead:

DOMAIN,ad.example.com,REJECT,pre-matching

Pre-matched rules have the highest priority. Only certain rule types support the tag, and the policy must be one of the REJECT family. See REJECT Policy for the full behavior details and the list of supported types.

Rule Parameters

The following optional parameters can be appended to rule lines. Each rule page documents the parameters relevant to its types in detail.

Unknown parameters are silently ignored.

notification-text and notification-interval

Use these parameters to get notified when a specific rule fires:

DOMAIN-SUFFIX,example.com,Proxy,notification-text=Example matched,notification-interval=600

Notifications for the same rule are throttled to one per notification-interval seconds (default 300).

Rule Type Index