Skip to content

Rules ​

In route-mode = "rule", every connection is checked against [route].rules from top to bottom. The first rule that matches decides where the connection goes. When no rule matches, FINAL decides.

toml
[route]
rules = [
  "DOMAIN-SUFFIX,corp.example.com,office",
  "PROCESS-NAME,cargo,work",
  "IP-CIDR,10.0.0.0/8,DIRECT",
  "FINAL,DIRECT",
]

The examples on this page are fragments of [route]: work and office stand for proxies or groups defined in your profile.

How a connection is routed ​

  1. bypass. A destination on the bypass list goes DIRECT. Nothing else is read.
  2. Route mode. direct sends everything DIRECT; global sends everything to global-proxy. Only rule reads the rule list.
  3. Rules, top to bottom. The first match wins.
  4. FINAL, or final-mixed / final-enhanced when they are set.

The order in the list is the only priority. A domain rule does not beat an IP rule because it is a domain rule; the earlier one wins.

Syntax ​

text
TYPE,payload,target
TYPE,payload,target,option
TYPE,payload,target,option,option
FINAL,target
  • A rule has at most five fields. More fields fail to load.
  • The rule is split on commas outside parentheses. A comma inside parentheses belongs to the payload, so logical rules and regular expressions such as ^(a{1,3})$ work. A comma outside parentheses ends the payload: DOMAIN-REGEX,^a{1,3}$,X does not load. Parentheses must be balanced.
  • Spaces around each field are removed.
  • TYPE and options ignore case. MATCH is another name for FINAL.
  • target is DIRECT, REJECT, the name of a [[proxy]] or the name of a [[proxy-group]]. Targets are case-sensitive: direct is not DIRECT.
  • FINAL takes no payload and no options. It must be the last rule, and a non-empty rule list must have one. Without any rules, connections go to final-mixed / final-enhanced when set, otherwise DIRECT.
  • Rules that contain a backslash (regular expressions, Windows paths) are easiest as TOML literal strings in single quotes: 'DOMAIN-REGEX,^ci-[0-9]+\.example\.com$,work'. In double quotes every backslash is written twice ("...\\.example..."); a single \. is an invalid TOML escape and the whole file fails to load.

Options ​

OptionEffect
include-childrenthe rule also matches programs started by the matching process. Only on rules that test a process (including AND/OR/NOT that contain one) and on RULE-SET. See Process Rules
no-resolveaccepted and kept, but has no effect in the current build. Specola never resolves a name just to test an IP rule (except with resolve-unknown-domains)

An option may appear once. Any other word in the fourth or fifth field is an error.

Rule types ​

Domain ​

TypeMatchesExample
DOMAINexactly this nameDOMAIN,api.github.com,work
DOMAIN-SUFFIXthis name and every name under itDOMAIN-SUFFIX,github.com,work
DOMAIN-KEYWORDnames that contain the text anywhereDOMAIN-KEYWORD,tracker,REJECT
DOMAIN-WILDCARDa wildcard over the whole nameDOMAIN-WILDCARD,*.cdn.example.com,DIRECT
DOMAIN-REGEXa PCRE2 regular expression'DOMAIN-REGEX,^ci-[0-9]+\.example\.com$,work'
GEOSITEa category of a GeoSite fileGEOSITE,github,work

How they compare:

  • Case never matters, for every domain type. Names and patterns are compared in lower case.
  • DOMAIN-SUFFIX,github.com matches github.com and api.github.com, not notgithub.com.
  • DOMAIN-WILDCARD: * matches any run of characters, dots included; ? matches one character. The pattern covers the whole name, so *.example.com matches a.example.com and a.b.example.com, but not example.com.
  • DOMAIN-REGEX searches anywhere in the name: REGEX,ads also matches uploads.example.com. Anchor with ^ and $. Matching ignores case. A pattern that does not compile fails the load.
  • GEOSITE category names ignore case. A category contains full names, suffixes, keywords and regular expressions, matched as above. Attribute filters such as cn@ads are not supported; they fail with Unknown GeoSite category.
  • A connection without a name (an IP address only) matches no domain rule.

IP ​

TypeMatchesExample
IP-CIDRan IPv4 networkIP-CIDR,10.0.0.0/8,DIRECT
IP-CIDR6an IPv6 networkIP-CIDR6,fd00::/8,DIRECT
IP-SUFFIXthe end of the address written as textIP-SUFFIX,.255,REJECT
IP-ASNaddresses of an autonomous systemIP-ASN,13335,DIRECT
GEOIPa country or category of a GeoIP fileGEOIP,private,DIRECT
  • Always write the prefix length. IP-CIDR,1.2.3.4,X loads but never matches; write IP-CIDR,1.2.3.4/32,X. The same holds for IP-CIDR6. (Inside AND/OR/NOT a missing prefix means a single address.)
  • IP-CIDR takes only IPv4 networks and IP-CIDR6 only IPv6 networks; the wrong family fails to load.
  • IP-SUFFIX compares text, not numbers: IP-SUFFIX,.255 matches 10.0.0.255; IP-SUFFIX,1 matches every address ending in the digit 1. At the top level it tests IPv4 addresses only and accepts */? wildcards (IP-SUFFIX,10.*.0.1).
  • IP-ASN accepts 13335 or AS13335. It needs an ASN catalog, see Geo data.
  • GEOIP category names ignore case (CN, cn, private).
  • IP rules match only when the connection has an address. See IP rules and domain names.

Port and network ​

TypeMatchesExample
DST-PORTa destination port or range a-bDST-PORT,22,DIRECT, DST-PORT,6881-6889,DIRECT
NETWORKthe transport: TCP, UDP or ICMPNETWORK,UDP,DIRECT
  • DST-PORT takes one port or one range. Lists are not supported; combine with OR.
  • NETWORK ignores case and accepts several values separated by / (TCP/UDP). Other words load but never match.
  • The local HTTP/SOCKS5 port carries TCP only, so NETWORK,UDP matches only Enhanced Mode and gateway traffic.

Source ​

Source rules match the client that opened the connection.

TypeMatchesExample
SRC-IP-CIDRthe client's IPv4 networkSRC-IP-CIDR,192.168.1.0/24,DIRECT
SRC-IP-CIDR6the client's IPv6 networkSRC-IP-CIDR6,fd00::/8,DIRECT
SRC-PORTthe client's source port or range a-bSRC-PORT,50000-60000,DIRECT
SRC-MACthe client's MAC address, aa:bb:cc:dd:ee:ff or aa-bb-…SRC-MAC,aa:bb:cc:dd:ee:01,DIRECT
SRC-DEVICEa device name or device group (case ignored)SRC-DEVICE,tv,STREAMING

Where they apply:

  • Router gateway (--gateway, Linux builds with gateway support): the client is the LAN device. SRC-MAC and SRC-DEVICE use the gateway's DHCP leases, its device list and the ARP table. Source rules also decide the DNS answers for that device.
  • TUN and eBPF: the source is this computer's own address and port. SRC-MAC and SRC-DEVICE never match.
  • Local HTTP/SOCKS5 port: no source information reaches the rules. Source rules never match, even for LAN clients with allow-lan.

Process ​

Process rules route by the program that opened the connection. They are covered in full on Process Rules: how names and paths are matched, what each platform reports, which connections carry a process, include-children, and how Linux eBPF pins group members.

TypeMatchesExample
PROCESS-NAMEexecutable file name; a wildcard if it contains * or ?PROCESS-NAME,cargo,work
PROCESS-PATHfull executable path; a wildcard if it contains * or ?PROCESS-PATH,/usr/bin/git,work
PROCESS-NAME-WILDCARDexecutable file name, wildcardPROCESS-NAME-WILDCARD,python*,work
PROCESS-PATH-WILDCARDfull executable path, wildcardPROCESS-PATH-WILDCARD,/opt/tools/*,work
PROCESS-NAME-REGEXexecutable file name, regular expressionPROCESS-NAME-REGEX,^python3(\.[0-9]+)?$,work
PROCESS-PATH-REGEXfull executable path, regular expressionPROCESS-PATH-REGEX,^/opt/tools/,work

Matching ignores case. On Windows the name includes .exe (chrome.exe); on macOS it is the executable inside the bundle (Google Chrome), not the .app.

Rule set ​

TypeMatchesExample
RULE-SETany entry of a named rule setRULE-SET,ads,REJECT

All entries of the set share the place and the target of the RULE-SET rule. See Rule sets.

Logical ​

AND, OR and NOT combine other conditions. Each condition is written without a target and wrapped in parentheses; AND and OR take at least two, NOT exactly one, and they can be nested.

TypeMatchesExample
ANDall conditionsAND,((PROCESS-NAME,curl),(DOMAIN-SUFFIX,example.com)),work
ORany conditionOR,((DOMAIN,a.example.com),(DOMAIN,b.example.com)),work
NOTthe condition does not holdAND,((DST-PORT,443),(NOT,((PROCESS-NAME,updater)))),work
  • The whole condition list is wrapped once more: AND,( … ),target.
  • A condition can be DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD, DOMAIN-WILDCARD, DOMAIN-REGEX, IP-CIDR, IP-CIDR6, IP-SUFFIX, IP-ASN, DST-PORT, NETWORK, a source type, a process type, or another AND/OR/NOT. GEOIP, GEOSITE and RULE-SET cannot appear inside a logical rule.
  • Inside a logical rule IP-SUFFIX has no wildcards, but it tests IPv6 addresses too.

SUB-RULE is not supported.

FINAL and per-entry fallbacks ​

FINAL,target is where a connection goes when no rule matches. Two optional [route] keys replace it for one entry point:

toml
[route]
rules = ["DOMAIN-SUFFIX,corp.example.com,office", "FINAL,DIRECT"]
final-mixed = "work"      # local HTTP/SOCKS5 port
final-enhanced = ""       # Enhanced Mode (TUN, eBPF); empty = use FINAL
KeyApplies toDefault
final-mixedconnections from the local HTTP/SOCKS5 port"" (use FINAL)
final-enhancedconnections captured by TUN or eBPF, and their DNS decisions"" (use FINAL)
  • The value is DIRECT, REJECT, a proxy or a group.
  • A name that does not exist is ignored without a message, and FINAL applies. Check the spelling.
  • On Linux eBPF, final-enhanced also decides whether unmatched traffic is captured at all; see what eBPF captures.
  • The Rules page test and the FINAL row in the rule list always show the FINAL rule itself.

Bypass ​

toml
[route]
bypass = ["localhost", "*.local", "127.0.0.0/8", "192.168.0.0/16", "::1/128"]

A destination on the bypass list goes DIRECT before the route mode and the rules are read, on the local port, TUN and eBPF. It applies in every route mode, global included.

EntryMatches
localhostexactly that name (case and a trailing dot ignored)
*.localnames under local, not local itself
10.1.2.3, fd00::1that address
192.168.0.0/16, fd00::/8addresses in the network

An entry that is none of these fails to load. An IP literal used as a host name is checked against the networks too. In Enhanced Mode a Fake-IP connection is checked under its name.

Ordering ​

First match wins, so put narrow rules above broad ones:

toml
[route]
rules = [
  "DOMAIN,status.corp.example.com,DIRECT",   # exception first
  "DOMAIN-SUFFIX,corp.example.com,office",   # then the general case
  "FINAL,DIRECT",
]

A readable layout for larger lists: blocks (REJECT), process rules, domains, rule sets, IP and GeoIP rules, then FINAL.

IP rules and domain names ​

What a rule can see depends on where the connection comes from:

Entry pointNameAddress
Local port, request by name (CONNECT github.com:443)yesno
Local port, request by addressnoyes
Enhanced Mode, Fake-IP connectionyesno (the Fake-IP is not used for rules)
Enhanced Mode, connection to a real address Core answered or sniffedyesyes
Enhanced Mode, connection to an address Core knows nothing aboutnoyes

So GEOIP,CN,DIRECT does not match CONNECT example.cn:443 on the local port, and does not match a name that Enhanced Mode answered with a Fake-IP. Use domain or GeoSite rules for names. See DNS for when Enhanced Mode hands out Fake-IPs.

resolve-unknown-domains ​

toml
[route]
resolve-unknown-domains = true   # default false

This option lets IP rules see names on the local SOCKS5 port. It applies only when all of these hold:

  • the request comes in on the local port as SOCKS5 with a name (HTTP proxy requests are never looked up);
  • no rule matches the name as it is;
  • the profile has IP rules (IP-CIDR, IP-CIDR6, IP-SUFFIX, GEOIP, IP-ASN, or a logical rule with one of them);
  • Core's DNS module is running: Enhanced Mode is on, [dns].listener is enabled, or Core runs as a gateway. Otherwise the option silently does nothing.

Core then asks for the name's addresses at the system DNS servers directly, and at nameserver-proxy through the FINAL target, all at once, and takes the first usable answer, waiting at most 1.5 seconds. The rules are matched again with each address; the earliest matching rule wins. If it is DIRECT, Core connects to that address; if it is a proxy, the name is still sent to the proxy. If nothing matches, FINAL applies.

The option needs a rule list (route.resolve-unknown-domains requires a rule list with FINAL). Writing a domain rule is usually better than enabling lookups.

Geo data ​

GEOIP, GEOSITE and IP-ASN read data files.

toml
[route]
rules = [
  "GEOIP,private,DIRECT",
  "GEOSITE,github,work",
  "IP-ASN,13335,DIRECT",
  "FINAL,DIRECT",
]
geoip = { path = "geoip.dat" }
geosite = { url = "https://example.org/geosite.dat", proxy = "work" }
asn = "asn.txt"
geo-update = "weekly"

Here work must be a [[proxy]], not a group, and geoip.dat and asn.txt must exist.

KeyNotes
geoip, geositeinline tables with type, path, url, proxy
typelocal or remote; remote when url is set, otherwise local
paththe file; a relative path is relative to the profile's folder. For a remote file, where the download is stored
urldownload location (remote only)
proxydownload through this proxy. It must be a [[proxy]] of the profile, not a group, DIRECT or REJECT
asnpath of the ASN catalog, a plain string
geo-updatehow old a downloaded GeoIP/GeoSite file may get: daily, weekly (default), monthly or never

File formats. geoip.dat and geosite.dat are V2Ray-format files, as published by v2fly and Loyalsoldier. The ASN catalog is text, one AS<number>,<network> per line (AS13335,1.1.1.0/24; IPv6 networks allowed; # starts a comment). An empty catalog fails to load.

When a file is needed. A local geoip.dat / geosite.dat is looked up only when a rule uses GEOIP / GEOSITE (in [route].rules or an inline rule set); the ASN catalog only when a rule uses IP-ASN. A missing file then fails the load with route.geoip file does not exist; tried …, listing every place it looked:

  1. the configured path (relative to the profile's folder), or nothing when path is empty;
  2. the data folder, under the same relative path, or geoip.dat / geosite.dat / asn.txt;
  3. resources/ next to the Specola executable.

The data folder is %LOCALAPPDATA%\Specola on Windows (%ProgramData%\Specola for the service), ~/Library/Application Support/com.specola.Specola on macOS and ~/.config/specola on Linux.

Remote files. A remote GeoIP/GeoSite file is downloaded when the profile loads, if no copy exists or the copy is older than geo-update (never: only when no copy exists). It is downloaded even when no rule uses it. Without path it is stored in the data folder as geoip.dat / geosite.dat. While Core runs it checks every hour and reloads the active profile when a copy has become too old. A download that fails or takes more than 30 seconds keeps the existing copy, with a warning; without a copy the load fails. Downloads are limited to 32 MB.

Do not put GEOIP, GEOSITE or IP-ASN entries in rule-set files: the data file is located only for rules in the profile and in inline sets.

Rule sets ​

A rule set is a named list of conditions that you use with RULE-SET. Declare each one as an inline table in [route] rule-set:

toml
[route]
rules = [
  "RULE-SET,ads,REJECT",
  "RULE-SET,internal,office",
  "RULE-SET,dev-tools,work,include-children",
  "RULE-SET,lan,DIRECT",
  "FINAL,DIRECT",
]
rule-set = [
  { name = "ads", behavior = "domain", url = "https://lists.example.org/ads.txt" },
  { name = "internal", behavior = "classical", path = "internal-rules.txt" },
  { name = "dev-tools", rules = ["PROCESS-NAME,cargo", "PROCESS-NAME,go"] },
  { name = "lan", rules = ["IP-CIDR,192.168.0.0/16", "DOMAIN-SUFFIX,lan"] },
]

Here internal-rules.txt must exist next to the profile.

FieldNotes
namerequired and unique; the RULE-SET payload
typeinline, local or remote; when omitted: rules present → inline, url present → remote, otherwise local
rulesinline entries: TYPE,payload without a target
paththe file; relative paths are relative to the profile's folder. For a remote set, where the download is stored
urldownload location
behaviorfile format: classical (default), domain or ipcidr. Inline entries are always classical
proxydownload through this proxy; a [[proxy]] of the profile, not a group
update_intervalaccepted but not used: there is no periodic refresh

Entries.

  • An entry is TYPE,payload, without a target and without options. The target comes from the RULE-SET rule; a target written on an inline entry is ignored.
  • include-children goes on the RULE-SET rule (RULE-SET,dev-tools,work,include-children) and applies to every process entry. On an entry it fails to load.
  • FINAL/MATCH, RULE-SET and SUB-RULE cannot be entries.
  • An inline set needs at least one entry.

Sources.

  • Inline: the entries are in the profile.
  • Local: the file must exist when the profile loads, even if no rule uses the set. Without path, Specola looks for rule-sets/<name>.txt in the data folder and in resources/ next to the executable.
  • Remote: downloaded every time the profile loads, which includes every rule edit made in the app. Without path it is stored as rule-sets/<name>.txt in the data folder. A failed download uses the stored copy, with a warning; without a copy the load fails.

Rule-set file formats ​

Files are plain text, one entry per line. Empty lines and lines starting with # or // are skipped. A file with no entries fails to load. YAML rule providers and binary .mrs / .srs files are not supported.

behaviorLine formatBecomes
classicalTYPE,payload, for example DOMAIN-SUFFIX,example.com or AND,((DOMAIN,a.com),(NETWORK,TCP))that rule
domainexample.comDOMAIN-SUFFIX
full:example.comDOMAIN
domain:example.comDOMAIN-SUFFIX
keyword:exampleDOMAIN-KEYWORD
regexp:^ads\.DOMAIN-REGEX
ipcidr10.0.0.0/8, fd00::/8IP-CIDR or IP-CIDR6
  • In a classical file, everything after the first comma is the payload. A trailing ,no-resolve is removed; any other third field (a target) is an error.
  • In a domain file, prefixes are lower case. Clash-style +.example.com, .example.com and *.example.com are not understood and never match; write example.com.
  • In ipcidr and classical files, write the prefix length (1.2.3.4/32): a bare address loads but never matches.

In the app, the Rules page can browse every set, edit the entries of inline sets and change the URL of a remote set. Local and remote entries are read-only there; new sets are declared in the profile.

Testing a rule ​

The Rules page has a test: enter a host or IP, optionally with :port, and pick TCP or UDP. It shows the rule that decides, or FINAL, and whether bypass catches the destination first.

The test reads only the destination:

  • A name is matched as a name and is never resolved, so IP and GeoIP rules do not match it.
  • There is no process, so process rules never match. There is no client, so source rules never match.
  • It shows the FINAL rule, not final-mixed / final-enhanced.

How edits apply ​

Saving rules in the app, or re-activating the profile after editing the file, applies the change in place. Core does not restart and existing connections keep running.

  • The new rule table replaces the old one at once. Group choices are kept for groups that remain.
  • Cached DNS answers are dropped, because they carry route decisions. Fake-IP mappings are kept.
  • On Linux eBPF, the capture set is rebuilt from the new rules.
  • Remote rule sets are downloaded again; remote geo files only when they are due.
  • If the new profile does not load, the running one stays unchanged and the error is shown.

Rules switched off in the app are stored in <profile>.disabled-rules next to the profile; the profile itself is not changed. A switched-off rule keeps its number in the list and in statistics.

Troubleshooting ​

Errors in [route].rules name the file, line and column, the entry number and the rule text, for example work.toml:12:3: route.rules entry #4: route rule has too many fields; rule="…".

MessageCause
route rule is missing payload or targetfewer than three fields, for example DOMAIN,example.com
route rule has too many fieldsmore than five fields, often a comma in a regular expression outside parentheses
Rule requires one nonempty payloadan extra comma outside parentheses inside the payload
unsupported route rule option: Xa fourth or fifth field that is not no-resolve or include-children
Unsupported rule type 'X'misspelled type
Rule references unknown outbound: XX is not DIRECT, REJECT, a proxy or a group; check capitalization
FINAL must be the last rulemove FINAL to the end, and keep only one
Rule list requires an explicit FINAL targetadd "FINAL,<target>"
RULE-SET references unknown cache: Xno entry with name = "X" in [route] rule-set
include-children only applies to rules that match a process, or to a RULE-SETthe option is on a rule without a process condition
route.geoip file does not exist; tried …the GeoIP file is in none of the listed places
Unknown GeoIP category: X / Unknown GeoSite category: Xthe file has no such category
IPv4 CIDR predicate requires an IPv4 addressan IPv6 network in IP-CIDR inside a logical rule; use IP-CIDR6

A rule that loads but never matches is usually one of these:

  1. An earlier rule matches first. Connections shows the rule that decided each connection.
  2. The connection has no name, or no address. See IP rules and domain names.
  3. An IP rule without a prefix length, such as IP-CIDR,1.2.3.4,X. Add /32.
  4. A misspelled final-mixed / final-enhanced, silently replaced by FINAL.
  5. In Enhanced Mode, the application resolved the name itself (for example with DNS over HTTPS), so Core never saw it. See DNS and Sniffer.

See also Process Rules, DNS and Sniffer.