Skip to content

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.

toml
[[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 = 300

The 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 ​

typePicks
selectthe member you chose in the app; the first member until you choose
url-testthe healthy member with the lowest measured latency
fallbackthe first member, in list order, that has not failed its last check
load-balancea 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 ​

KeyRequiredDefaultValue
nameyes—unique among proxies and groups; not DIRECT or REJECT; no comma, no ::
typeyes—select, url-test, fallback or load-balance
proxiesyes—non-empty array of member names, see Members
urlnohttp://www.gstatic.com/generate_204health-check URL; used by url-test and fallback only
intervalnononeseconds between checks, a positive integer. Without it, no periodic checks run
toleranceno0milliseconds, not negative; url-test only
strategynoconsistent-hashingconsistent-hashing or round-robin; load-balance only
dialer-proxynononea proxy every member connects through, see Proxy Chains
iconnononeicon 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]], or DIRECT, or REJECT.
  • Groups cannot contain groups. A group name in proxies is rejected with Proxy 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-proxy may contain proxies only, no DIRECT or REJECT.
  • Member order matters for select (the default member) and fallback (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.
  • tolerance avoids flapping: the group keeps its current member while that member's latency is at most tolerance ms above the fastest. With tolerance = 0 it 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.

strategyPicks
consistent-hashing (default)a member from a hash of the destination, so the same site keeps the same member
round-robinthe 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.

  • interval turns 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 with interval = 300 checks one member every 30 seconds. Members are never checked more often than one every 5 seconds, so a long member list takes longer than interval per round.
  • url is used by url-test and fallback only. select and load-balance groups 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.
  • REJECT always fails its check. DIRECT is 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, fallback and load-balance group, even one without interval.
  • Without interval, nothing is checked periodically: fallback stays on its first member and url-test stays on its first member until a manual latency test gives it data.
  • Members of a group with a dialer-proxy are 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 select groups. url-test, fallback and load-balance groups 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-robin keeps 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):

toml
[[proxy-group]]
name = "exit"
type = "select"
proxies = ["office", "home", "DIRECT"]

Fastest of several, switching only for a clear gain (fragment):

toml
[[proxy-group]]
name = "auto"
type = "url-test"
proxies = ["office", "home"]
url = "https://www.gstatic.com/generate_204"
interval = 300
tolerance = 50

Spread connections, skipping failed members (fragment):

toml
[[proxy-group]]
name = "spread"
type = "load-balance"
proxies = ["office", "home"]
strategy = "round-robin"
interval = 300

A group used by rules (fragment):

toml
[route]
rules = [
  "DOMAIN-SUFFIX,corp.example.com,work",
  "FINAL,auto",
]

Troubleshooting ​

  1. url-test or fallback never switches: add interval. Without it nothing is checked.
  2. 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).
  3. references unknown proxy: the member is misspelled, or it is a group. Groups cannot be nested.
  4. Choice lost after restarting the app: choices are not saved across a Core restart.
  5. On Linux a program never changes member: that is eBPF pinning.

See also Proxies, Proxy Chains and Rules.