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.
[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
bypass. A destination on the bypass list goesDIRECT. Nothing else is read.- Route mode.
directsends everythingDIRECT;globalsends everything toglobal-proxy. Onlyrulereads the rule list. - Rules, top to bottom. The first match wins.
FINAL, orfinal-mixed/final-enhancedwhen 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
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}$,Xdoes not load. Parentheses must be balanced. - Spaces around each field are removed.
TYPEand options ignore case.MATCHis another name forFINAL.targetisDIRECT,REJECT, thenameof a[[proxy]]or thenameof a[[proxy-group]]. Targets are case-sensitive:directis notDIRECT.FINALtakes 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 tofinal-mixed/final-enhancedwhen set, otherwiseDIRECT.- 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
| Option | Effect |
|---|---|
include-children | the 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-resolve | accepted 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
| Type | Matches | Example |
|---|---|---|
DOMAIN | exactly this name | DOMAIN,api.github.com,work |
DOMAIN-SUFFIX | this name and every name under it | DOMAIN-SUFFIX,github.com,work |
DOMAIN-KEYWORD | names that contain the text anywhere | DOMAIN-KEYWORD,tracker,REJECT |
DOMAIN-WILDCARD | a wildcard over the whole name | DOMAIN-WILDCARD,*.cdn.example.com,DIRECT |
DOMAIN-REGEX | a PCRE2 regular expression | 'DOMAIN-REGEX,^ci-[0-9]+\.example\.com$,work' |
GEOSITE | a category of a GeoSite file | GEOSITE,github,work |
How they compare:
- Case never matters, for every domain type. Names and patterns are compared in lower case.
DOMAIN-SUFFIX,github.commatchesgithub.comandapi.github.com, notnotgithub.com.DOMAIN-WILDCARD:*matches any run of characters, dots included;?matches one character. The pattern covers the whole name, so*.example.commatchesa.example.comanda.b.example.com, but notexample.com.DOMAIN-REGEXsearches anywhere in the name:REGEX,adsalso matchesuploads.example.com. Anchor with^and$. Matching ignores case. A pattern that does not compile fails the load.GEOSITEcategory names ignore case. A category contains full names, suffixes, keywords and regular expressions, matched as above. Attribute filters such ascn@adsare not supported; they fail withUnknown GeoSite category.- A connection without a name (an IP address only) matches no domain rule.
IP
| Type | Matches | Example |
|---|---|---|
IP-CIDR | an IPv4 network | IP-CIDR,10.0.0.0/8,DIRECT |
IP-CIDR6 | an IPv6 network | IP-CIDR6,fd00::/8,DIRECT |
IP-SUFFIX | the end of the address written as text | IP-SUFFIX,.255,REJECT |
IP-ASN | addresses of an autonomous system | IP-ASN,13335,DIRECT |
GEOIP | a country or category of a GeoIP file | GEOIP,private,DIRECT |
- Always write the prefix length.
IP-CIDR,1.2.3.4,Xloads but never matches; writeIP-CIDR,1.2.3.4/32,X. The same holds forIP-CIDR6. (InsideAND/OR/NOTa missing prefix means a single address.) IP-CIDRtakes only IPv4 networks andIP-CIDR6only IPv6 networks; the wrong family fails to load.IP-SUFFIXcompares text, not numbers:IP-SUFFIX,.255matches10.0.0.255;IP-SUFFIX,1matches 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-ASNaccepts13335orAS13335. It needs an ASN catalog, see Geo data.GEOIPcategory 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
| Type | Matches | Example |
|---|---|---|
DST-PORT | a destination port or range a-b | DST-PORT,22,DIRECT, DST-PORT,6881-6889,DIRECT |
NETWORK | the transport: TCP, UDP or ICMP | NETWORK,UDP,DIRECT |
DST-PORTtakes one port or one range. Lists are not supported; combine withOR.NETWORKignores 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,UDPmatches only Enhanced Mode and gateway traffic.
Source
Source rules match the client that opened the connection.
| Type | Matches | Example |
|---|---|---|
SRC-IP-CIDR | the client's IPv4 network | SRC-IP-CIDR,192.168.1.0/24,DIRECT |
SRC-IP-CIDR6 | the client's IPv6 network | SRC-IP-CIDR6,fd00::/8,DIRECT |
SRC-PORT | the client's source port or range a-b | SRC-PORT,50000-60000,DIRECT |
SRC-MAC | the client's MAC address, aa:bb:cc:dd:ee:ff or aa-bb-… | SRC-MAC,aa:bb:cc:dd:ee:01,DIRECT |
SRC-DEVICE | a 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-MACandSRC-DEVICEuse 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-MACandSRC-DEVICEnever 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.
| Type | Matches | Example |
|---|---|---|
PROCESS-NAME | executable file name; a wildcard if it contains * or ? | PROCESS-NAME,cargo,work |
PROCESS-PATH | full executable path; a wildcard if it contains * or ? | PROCESS-PATH,/usr/bin/git,work |
PROCESS-NAME-WILDCARD | executable file name, wildcard | PROCESS-NAME-WILDCARD,python*,work |
PROCESS-PATH-WILDCARD | full executable path, wildcard | PROCESS-PATH-WILDCARD,/opt/tools/*,work |
PROCESS-NAME-REGEX | executable file name, regular expression | PROCESS-NAME-REGEX,^python3(\.[0-9]+)?$,work |
PROCESS-PATH-REGEX | full executable path, regular expression | PROCESS-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
| Type | Matches | Example |
|---|---|---|
RULE-SET | any entry of a named rule set | RULE-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.
| Type | Matches | Example |
|---|---|---|
AND | all conditions | AND,((PROCESS-NAME,curl),(DOMAIN-SUFFIX,example.com)),work |
OR | any condition | OR,((DOMAIN,a.example.com),(DOMAIN,b.example.com)),work |
NOT | the condition does not hold | AND,((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 anotherAND/OR/NOT.GEOIP,GEOSITEandRULE-SETcannot appear inside a logical rule. - Inside a logical rule
IP-SUFFIXhas 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:
[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| Key | Applies to | Default |
|---|---|---|
final-mixed | connections from the local HTTP/SOCKS5 port | "" (use FINAL) |
final-enhanced | connections 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
FINALapplies. Check the spelling. - On Linux eBPF,
final-enhancedalso decides whether unmatched traffic is captured at all; see what eBPF captures. - The Rules page test and the
FINALrow in the rule list always show theFINALrule itself.
Bypass
[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.
| Entry | Matches |
|---|---|
localhost | exactly that name (case and a trailing dot ignored) |
*.local | names under local, not local itself |
10.1.2.3, fd00::1 | that address |
192.168.0.0/16, fd00::/8 | addresses 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:
[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 point | Name | Address |
|---|---|---|
Local port, request by name (CONNECT github.com:443) | yes | no |
| Local port, request by address | no | yes |
| Enhanced Mode, Fake-IP connection | yes | no (the Fake-IP is not used for rules) |
| Enhanced Mode, connection to a real address Core answered or sniffed | yes | yes |
| Enhanced Mode, connection to an address Core knows nothing about | no | yes |
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
[route]
resolve-unknown-domains = true # default falseThis 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].listeneris 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.
[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.
| Key | Notes |
|---|---|
geoip, geosite | inline tables with type, path, url, proxy |
type | local or remote; remote when url is set, otherwise local |
path | the file; a relative path is relative to the profile's folder. For a remote file, where the download is stored |
url | download location (remote only) |
proxy | download through this proxy. It must be a [[proxy]] of the profile, not a group, DIRECT or REJECT |
asn | path of the ASN catalog, a plain string |
geo-update | how 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:
- the configured
path(relative to the profile's folder), or nothing whenpathis empty; - the data folder, under the same relative path, or
geoip.dat/geosite.dat/asn.txt; 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:
[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.
| Field | Notes |
|---|---|
name | required and unique; the RULE-SET payload |
type | inline, local or remote; when omitted: rules present → inline, url present → remote, otherwise local |
rules | inline entries: TYPE,payload without a target |
path | the file; relative paths are relative to the profile's folder. For a remote set, where the download is stored |
url | download location |
behavior | file format: classical (default), domain or ipcidr. Inline entries are always classical |
proxy | download through this proxy; a [[proxy]] of the profile, not a group |
update_interval | accepted but not used: there is no periodic refresh |
Entries.
- An entry is
TYPE,payload, without a target and without options. The target comes from theRULE-SETrule; a target written on an inline entry is ignored. include-childrengoes on theRULE-SETrule (RULE-SET,dev-tools,work,include-children) and applies to every process entry. On an entry it fails to load.FINAL/MATCH,RULE-SETandSUB-RULEcannot 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 forrule-sets/<name>.txtin the data folder and inresources/next to the executable. - Remote: downloaded every time the profile loads, which includes every rule edit made in the app. Without
pathit is stored asrule-sets/<name>.txtin 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.
behavior | Line format | Becomes |
|---|---|---|
classical | TYPE,payload, for example DOMAIN-SUFFIX,example.com or AND,((DOMAIN,a.com),(NETWORK,TCP)) | that rule |
domain | example.com | DOMAIN-SUFFIX |
full:example.com | DOMAIN | |
domain:example.com | DOMAIN-SUFFIX | |
keyword:example | DOMAIN-KEYWORD | |
regexp:^ads\. | DOMAIN-REGEX | |
ipcidr | 10.0.0.0/8, fd00::/8 | IP-CIDR or IP-CIDR6 |
- In a classical file, everything after the first comma is the payload. A trailing
,no-resolveis removed; any other third field (a target) is an error. - In a domain file, prefixes are lower case. Clash-style
+.example.com,.example.comand*.example.comare not understood and never match; writeexample.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
FINALrule, notfinal-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="…".
| Message | Cause |
|---|---|
route rule is missing payload or target | fewer than three fields, for example DOMAIN,example.com |
route rule has too many fields | more than five fields, often a comma in a regular expression outside parentheses |
Rule requires one nonempty payload | an extra comma outside parentheses inside the payload |
unsupported route rule option: X | a fourth or fifth field that is not no-resolve or include-children |
Unsupported rule type 'X' | misspelled type |
Rule references unknown outbound: X | X is not DIRECT, REJECT, a proxy or a group; check capitalization |
FINAL must be the last rule | move FINAL to the end, and keep only one |
Rule list requires an explicit FINAL target | add "FINAL,<target>" |
RULE-SET references unknown cache: X | no entry with name = "X" in [route] rule-set |
include-children only applies to rules that match a process, or to a RULE-SET | the 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: X | the file has no such category |
IPv4 CIDR predicate requires an IPv4 address | an IPv6 network in IP-CIDR inside a logical rule; use IP-CIDR6 |
A rule that loads but never matches is usually one of these:
- An earlier rule matches first. Connections shows the rule that decided each connection.
- The connection has no name, or no address. See IP rules and domain names.
- An IP rule without a prefix length, such as
IP-CIDR,1.2.3.4,X. Add/32. - A misspelled
final-mixed/final-enhanced, silently replaced byFINAL. - 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.
