Proxy Groups
A [[proxy-group]] gives one name to several proxies and decides which one a connection uses. Rules, global-proxy and dialer-proxy can name a group exactly like a proxy.
[[proxy]]
name = "office"
type = "http"
server = "office.example.org"
port = 8080
[[proxy]]
name = "office-backup"
type = "http"
server = "backup.example.org"
port = 8080
[[proxy-group]]
name = "work"
type = "fallback"
proxies = ["office", "office-backup", "DIRECT"]
url = "https://www.gstatic.com/generate_204"
interval = 300The group sections below that start with [[proxy-group]] are fragments: they name the proxies office, office-backup and home, which you declare as in this example.
Types
type | Picks |
|---|---|
select | the member you chose in the app; the first member until you choose |
url-test | the healthy member with the lowest measured latency |
fallback | the first member, in list order, that has not failed its last check |
load-balance | a member for each connection, by strategy, among the members that have not failed |
A group decides for each new connection. Connections already open keep the member they started with.
Keys
| Key | Required | Default | Value |
|---|---|---|---|
name | yes | — | unique among proxies and groups; not DIRECT or REJECT; no comma, no :: |
type | yes | — | select, url-test, fallback or load-balance |
proxies | yes | — | non-empty array of member names, see Members |
url | no | http://www.gstatic.com/generate_204 | health-check URL; used by url-test and fallback only |
interval | no | none | seconds between checks, a positive integer. Without it, no periodic checks run |
tolerance | no | 0 | milliseconds, not negative; url-test only |
strategy | no | consistent-hashing | consistent-hashing or round-robin; load-balance only |
dialer-proxy | no | none | a proxy every member connects through, see Proxy Chains |
icon | no | none | icon shown for the group in the app |
[[proxy-group]] is strict: any other key is rejected with unknown field '<key>', and a value of the wrong type (interval = "300") is rejected too. url, tolerance and strategy on a type that does not use them are accepted and ignored. A url-test or fallback group without url loads with a warning and uses the default URL.
Write the section as [[proxy-group]]. The plural proxy-groups is dropped with a warning, and the groups in it are lost.
Members
- A member is the name of a
[[proxy]], orDIRECT, orREJECT. - Groups cannot contain groups. A group name in
proxiesis rejected withProxy group '<group>' references unknown proxy: <name>, the same error as a misspelled name. To combine two groups, list their proxies directly. - A group with a
dialer-proxymay contain proxies only, noDIRECTorREJECT. - Member order matters for
select(the default member) andfallback(the preference order).
How each type picks
select
The member you chose in the app, or the first member until you choose. Health checks do not change a select group's choice; they only show latency.
url-test
- Among members whose last check succeeded, the one with the lowest latency wins.
- Members never checked, and members whose last check failed, are not candidates.
- When no member has a successful check, the group uses the first member, even if it failed.
toleranceavoids flapping: the group keeps its current member while that member's latency is at mosttolerancems above the fastest. Withtolerance = 0it moves to any member that is faster.
fallback
The first member, in list order, whose last check did not fail. A member never checked counts as up, so without health checks the group always uses the first member. When every member failed its last check, the group uses the first member.
Add DIRECT as the last member if traffic should keep flowing when every proxy is down. Leave it out if that traffic must never go direct.
load-balance
The group picks among members whose last check did not fail; if all failed, among all members.
strategy | Picks |
|---|---|
consistent-hashing (default) | a member from a hash of the destination, so the same site keeps the same member |
round-robin | the next member for each connection |
For consistent-hashing, the key is the last two labels of the destination name: a.example.com and b.example.com share example.com. This is not a public-suffix lookup, so a.example.co.uk and b.other.co.uk share co.uk and always use the same member. A connection without a destination name is keyed by the program's path when a rule matched it and the program is known; otherwise it goes to a random member.
The hash is taken over the members that are up, so when a member fails or recovers, many sites move to another member. load-balance spreads whole connections; it does not make one download faster.
Health checks
A health check sends an HTTP request to the check URL through the member. It succeeds when the response status is 200–299 within 3 seconds. The latency is the time of the whole request, including the connection to the proxy and its handshake.
intervalturns periodic checks on. The first round checks every member right away. After that, members are checked one at a time, spread over the interval: a group of 10 members withinterval = 300checks one member every 30 seconds. Members are never checked more often than one every 5 seconds, so a long member list takes longer thanintervalper round.urlis used byurl-testandfallbackonly.selectandload-balancegroups always check the default URL. HTTPS URLs work. Choose a URL that takes the same path as the traffic you care about: a check only proves that this URL is reachable through the member.REJECTalways fails its check.DIRECTis checked like a proxy.- Health belongs to the proxy, not to the group. A proxy in two groups has one result; the latest check, from either group, wins.
- A latency test in the app updates the same result. A failed manual test marks the proxy as failed for every
url-test,fallbackandload-balancegroup, even one withoutinterval. - Without
interval, nothing is checked periodically:fallbackstays on its first member andurl-teststays on its first member until a manual latency test gives it data. - Members of a group with a
dialer-proxyare checked without the group's entry proxy. See Proxy Chains.
Choosing a member in the app
Pick the member of a select group on the Proxy Groups page or from the tray menu. The choice applies to new connections at once.
- The choice is kept in Core's memory. It survives re-activating the profile (see below), but not a restart of Core: after a restart, the group starts again from its first member.
- The app lets you choose only in
selectgroups.url-test,fallbackandload-balancegroups choose by themselves.
What happens on reload
Re-activating the profile applies changes in place without restarting Core:
- A group that still exists, with the same name, keeps its choice if the chosen member is still in its list. Otherwise it starts again from its default.
- Health results are kept for proxies that did not change. A proxy whose settings changed starts without a result, as if never checked.
round-robinkeeps its position for groups that still exist.- Renaming a group is the same as removing it and adding a new one.
Linux eBPF: process rules pin a member
On Linux with eBPF Enhanced Mode, a process rule that targets a group picks one member the first time it matches and keeps it until proxies, groups or rules are reloaded. url-test does not switch, fallback does not fail over, load-balance does not spread, and a new select choice does not apply to those connections. Rules of other types, and Windows and macOS, are not affected. See Process Rules.
Examples
Choose by hand (fragment):
[[proxy-group]]
name = "exit"
type = "select"
proxies = ["office", "home", "DIRECT"]Fastest of several, switching only for a clear gain (fragment):
[[proxy-group]]
name = "auto"
type = "url-test"
proxies = ["office", "home"]
url = "https://www.gstatic.com/generate_204"
interval = 300
tolerance = 50Spread connections, skipping failed members (fragment):
[[proxy-group]]
name = "spread"
type = "load-balance"
proxies = ["office", "home"]
strategy = "round-robin"
interval = 300A group used by rules (fragment):
[route]
rules = [
"DOMAIN-SUFFIX,corp.example.com,work",
"FINAL,auto",
]Troubleshooting
url-testorfallbacknever switches: addinterval. Without it nothing is checked.- A working proxy is avoided: its last check failed. The check URL may be blocked on that proxy, a manual latency test may have failed, or the group has a
dialer-proxy(members are checked without it). references unknown proxy: the member is misspelled, or it is a group. Groups cannot be nested.- Choice lost after restarting the app: choices are not saved across a Core restart.
- On Linux a program never changes member: that is eBPF pinning.
See also Proxies, Proxy Chains and Rules.
