Home/Docs/Linux Guide/Proxy rules (Linux)

Linux Guide

Proxy rules (Linux)

Every field of a ProxyBridge rule on Linux: program names and paths, hosts and domains, ports, protocol, action and localhost handling. How rules are ordered and matched, what is always direct, and worked examples.

Proxy rules on Linux

A rule says: when this program connects to these hosts and ports over this protocol, do this. Rules decide which traffic is sent through a proxy, left alone, or blocked. Open them with Proxy > Proxy Rules...

The Process Rules window listing five rules with their actions

The rules window

Part What it does
+ Add Rule Create a new rule
Edit (on each row) Change the rule
Delete (on each row) Delete the rule
Enable check box Switch a rule on or off without deleting it
▲ / ▼ Move the rule higher or lower in the list (see Rule order)
Check box at the start of a row, Select All, Delete Selected Select several rules and delete them at once
Export, Import Save the selected rules to a JSON file, or load rules from one (see Export and import rules)
Columns SR (the position, which is also the priority), Name, Process, Target Hosts, Protocol, Action (Proxy: <name>, Direct or Block, plus (+localhost) when localhost is included)

A rule change applies to connections opened afterwards. Connections that are already open keep the route they started with.

A profile holds up to 4096 rules.

Add or edit a rule

Click + Add Rule (or Edit on a row) to open the rule window.

The rule window with a rule for the company network: a CIDR range and a domain

Field Meaning
Name Your label for the rule (up to 127 characters). Shown in the rule list and stored in the profile. Optional
Process Name Which programs the rule is for. Browse... picks an executable from disk and enters its file name
Target Host Which destinations: IP addresses, ranges, networks and domain names, in one multi-line box
Target Port Which destination ports
Protocol TCP, UDP or BOTH
Action One list: Direct, Block, or Proxy: for each proxy you added
Also proxy localhost traffic Active only when the action is a proxy. See Localhost traffic

A rule only matches when all of Process, Target Host, Target Port and Protocol match. If something is not valid (a bad address, a port above 65535, ...) the window stays open and tells you what is wrong.

Process names

The Process Name field holds one or more patterns. Rules always match by program name or path, never by process ID, so a rule keeps working after the program restarts.

What you type Matches
* Every program
curl A program whose file name is curl, wherever it is installed
firefox; chromium; google-chrome Any of them. Separate entries with ; (a comma works too)
fire* Wildcards: * stands for any text, ? for one character. fire*, *chrome* and python3* all work
/usr/bin/curl One exact program, by full path
/opt/myapp/* Wildcards inside a path work too: every program under that folder

How the match works:

  • Matching is case-sensitive on Linux: Firefox is not firefox.
  • Each pattern is compared with both the program's file name (curl) and its full path (/usr/bin/curl). A pattern without a / can therefore only match a file name; a pattern with a / is what you use to tell apart two programs that share a name.
  • The program is identified by the executable file it was started from, not by the name shown in ps or top, which a program can change.
  • A rule can list up to 64 patterns.

Scripts and runtimes. A Python script is the program python3.12 (or whatever interpreter runs it), a Node.js script is node, a Java program is java. A rule for myscript.py never matches. Use the interpreter's name, and look at the Connections log to see the exact name ProxyBridge sees.

Programs that start helpers. Many programs connect from a helper process with a different name. apt downloads through helper programs called http and https; a browser may use several processes with the same file name. Start with a rule for the program you know, open the Connections tab, and add the name you see there. See Troubleshooting.

Target hosts

Target Host limits the rule to certain destinations. Leave it as * for any destination. IP addresses and domain names go in the same box and can be mixed:

10.0.0.0/8; github.com; *.google.com

The box is multi-line. Write one entry per line if you like: the line breaks are only for reading, and entries are still separated by ; (or a comma). A rule can list up to 1024 entries.

Kind Example Notes
Any * Every destination
Single IPv4 192.168.1.1
IPv4 with wildcards 192.168.*.*, 10.*.*.* * replaces a whole number between the dots
IPv4 pattern with ranges 10.1-5.*.7 Each number can be a range
IPv4 range 10.10.1.1-10.10.255.255 Inclusive
IPv4 network (CIDR) 10.0.0.0/8, 192.168.1.128/25 A network and a prefix length from /0 to /32
Single IPv6 ::1, 2001:db8::1
IPv6 network (CIDR) 2001:db8::/32, fe80::/10
Domain github.com That exact name only
Domain with a wildcard *.github.com, api?.example.org * stands for any text, ? for one character

*.github.com does not match github.com itself. A domain entry matches exactly what it says. To cover a site and all its sub-domains, list both: github.com; *.github.com. (The Windows app treats *.github.com as covering both; Linux is stricter.)

Domain names are compared in lower case, and a trailing dot (github.com.) is ignored. An entry that is not valid (for example 10.0.0.0/33, or a domain with a space) is refused when you save.

Domain names need plain DNS

ProxyBridge cannot read an encrypted connection, so it learns host names by watching the application's own, ordinary DNS lookups and remembering which name belongs to which IP address. So:

  • Domain rules work only when the application uses unencrypted DNS. Browsers that use "Secure DNS" or DNS over HTTPS (Firefox, Chrome and others can) hide the lookups. Turn that off in the browser for domain rules to work, or match on IP addresses instead. systemd-resolved with DNS over TLS has the same effect.
  • The application must have looked the name up after ProxyBridge started the rule. An address the application resolved earlier has no known name (names in /etc/hosts are loaded when the engine starts).
  • Applications that take an address from a config file, or hard-code it, never look anything up. Use an IP rule.
  • IPv6 destinations have no domain matching yet (only A and CNAME answers are used). An IP rule always works.
  • If two names share one address, the name looked up most recently wins.
  • When one of your rules contains a domain, the DNS traffic (port 53) of the programs that rule covers takes one extra hop through ProxyBridge, which forwards it unchanged and reads the answers. Programs no domain rule covers are not touched.

Target ports

You type Matches
* (or empty) Every port
443 One port
80; 443; 8080 Several ports
8000-9000 A range (inclusive)
80; 443; 8000-9000 Ports and ranges together

A list can have up to 64 entries.

Protocol

Choice Matches
TCP TCP connections only (web, most APIs, databases, SSH)
UDP UDP only (DNS, QUIC/HTTP/3, games, voice)
BOTH Either

UDP only works through a SOCKS5 proxy, and not every SOCKS5 proxy supports it. An HTTP proxy cannot carry UDP: a rule that sends UDP to an HTTP proxy leaves that UDP traffic direct, and ProxyBridge writes a warning naming the rule in the Activity Logs. See UDP, QUIC and HTTP/3.

Action

Action What happens to matching traffic
Direct Left alone. It goes out normally. Useful for exceptions placed above a broader rule
Block The connection is refused. The program's connection fails at once, or its UDP datagrams are dropped
Proxy: Sent through that proxy. Every proxy you added in Proxy servers is listed by name

Until you add at least one proxy, only Direct and Block are offered. A new rule starts on the default proxy if there is one.

If a rule needs a proxy that is not there (for example you deleted the last proxy), its traffic is blocked, not sent directly. A proxy that cannot be reached closes the connection; it is never replaced by a direct connection.

Localhost traffic

Connections to your own machine (127.0.0.1, ::1, anything in 127.0.0.0/8) are normally not sent to a proxy, even when they match a proxy rule. Most proxies refuse localhost on purpose, and many programs talk to local helpers (a database, a desktop service, systemd-resolved on 127.0.0.53) that must stay local.

The check box Also proxy localhost traffic (shown when the action is a proxy) changes that for this rule only:

Check box Connections to 127.x.x.x / ::1 from the matching programs
Off (default) Go direct. All their other traffic still follows the rule
On Go through the proxy as well

Tick it when the proxy runs on this computer and you want to see the program's local traffic too, typically for security testing of a client/server pair on one machine. Do not tick it for a proxy on another computer: that machine cannot reach services on yours.

Details:

  • Block and Direct rules never touch localhost traffic.
  • DNS to a local resolver (port 53 on 127.0.0.53, for example) is never proxied, even with the check box on, so a broad rule cannot break name resolution.
  • The relay's own connections are never proxied.
  • The setting belongs to the rule, so you can proxy one program's local traffic and leave another's alone.

Rule order

Rules are checked from top to bottom, and the first match wins. Put specific rules above general ones. The SR column shows each rule's position.

1  git;ssh   any host   22;9418    Direct        <- an exception
2  firefox   any host   80;443     Proxy: Burp   <- only web traffic of Firefox
3  *         any host   any port   Block         <- everything else (see the note)

A rule that matches everything a program does (hosts *, ports *, protocol BOTH) ends the list for that program: the rules below it are never reached. Unlike the Windows app, Linux does not treat such a catch-all specially: it simply matches at its own position, so put it last.

Use ▲ and ▼ to reorder. Rules you have switched off are skipped. If no rule matches, the connection goes out directly, exactly as if ProxyBridge were not running.

Always direct

Some addresses are never proxied, so the network keeps working:

IPv4 IPv6
Loopback 127.0.0.0/8 and 0.0.0.0/8 (unless a proxy rule has Also proxy localhost traffic) Loopback ::1 (same exception)
Broadcast (255.255.255.255) Multicast (ff00::/8)
Multicast and reserved (224.0.0.0 and above) Link-local (fe80::/10)
DHCP (UDP ports 67 and 68)

These are decided before your rules are looked at, so no rule applies to them (a Proxy action becomes Direct, and a Block rule does not stop them either). The one exception is loopback traffic, which a proxy rule can include with Also proxy localhost traffic.

Export and import rules

  • Export saves the rules whose check boxes you ticked to a JSON file (proxy_rules.json is suggested). It asks you to select at least one rule first.
  • Import reads a JSON file of rules and adds them. The file format is the same as the Windows and macOS apps use for rule files, so a rule file moves between the three. Rules that fail validation are skipped and listed in the message (Imported 3 rules, 1 failed validation and were skipped: ...).

To move a whole setup (proxies and rules and settings) use a profile instead.

Examples

Goal Process Target Host Port Protocol Action
Send a browser through a proxy firefox; chromium * * TCP your proxy
Send only one site's traffic through the proxy firefox github.com; *.github.com 443 TCP your proxy
Send only the company network through the corporate proxy * 10.0.0.0/8; *.corp.example.com * BOTH corporate proxy
Keep a tool local, send everything else rule 1: curl / Direct. Rule 2: * * * BOTH your proxy
Block a program completely telemetry-agent * * BOTH Block
Block one remote service for a program myapp 203.0.113.7 * BOTH Block
See a program's local traffic in a security tool myapp * * TCP your proxy, with Also proxy localhost traffic ticked
Send a game's UDP through a SOCKS5 proxy game * * UDP a SOCKS5 proxy that supports UDP
Route every Python script python3* * * TCP your proxy

More worked scenarios are in Use cases and recipes.

Tips

  • Start with a rule for one program and check the Connections tab before you add more.
  • Name your rules. The name shows in the rule list and in the profile file, so you can tell your rules apart a month later.
  • Rules are saved in the active profile, so switching profile switches the whole rule set.
  • To stop everything for a moment without touching rules, use Proxy > Enable ProxyBridge (Settings, pausing and start at boot).
  • Long host lists and domain rules are handled by ProxyBridge's relay instead of the kernel. They work the same way, with a small cost for UDP; see How it works.