Linux Guide
Proxy servers (Linux)
Add, edit, test and remove SOCKS5 and HTTP proxy servers in ProxyBridge for Linux. Authentication, the default proxy, DNS via proxy, the proxy test with its five steps, and running several proxies at once.
Proxy servers on Linux
A proxy server is where ProxyBridge sends the traffic of the applications your rules select. Add the proxy once here, then pick it in any number of rules.
Open the list with Proxy > Proxy Settings...

The list shows each proxy's Name, Type, Host:Port, whether it needs a login (Auth) and which one is the Default. The buttons under the list are Add, Edit, Delete and Set Default. Below them is the proxy test (see Test a proxy).
Proxies belong to the active profile. Switching profile switches the list.
Add a proxy
- Click Add to open the Add Proxy window.
- Fill in the fields:

| Field | What to enter |
|---|---|
| Name | A label you will recognise in the rule list, for example Burp Suite or Corporate SOCKS5. It must be unique inside the profile. The first proxy you add is pre-filled with default |
| Type | SOCKS5 (the default choice) or HTTP. See the table below |
| Host | An IP address (127.0.0.1, 192.168.1.100) or a host name (proxy.example.com, localhost). A host name is looked up when it is needed, with a 5 second limit and a cache, so a slow DNS server cannot stall your traffic |
| Port | The proxy's port, from 1 to 65535, for example 1080 (common for SOCKS5) or 8080 / 3128 (common for HTTP) |
| Username, Password | Only if the proxy requires a login. Leave both empty otherwise. The password is hidden while you type |
| DNS via proxy (the proxy resolves host names) | Ticked by default. See DNS handling |
- Click Save. The proxy appears in the list and in the Action drop-down of the rule editor.
If something is wrong, the window stays open and tells you why, in red at the bottom: Name cannot be empty., A proxy with this name already exists., Host (IP/Domain) cannot be empty. or Port must be a number between 1 and 65535.
Which type to choose
| SOCKS5 | HTTP | |
|---|---|---|
| Carries TCP | Yes | Yes (uses the CONNECT method) |
| Carries UDP | Only if the proxy supports UDP ASSOCIATE | No |
| Authentication | Username and password (RFC 1929) | Basic authentication |
| Typical use | General purpose, non-HTTP protocols, UDP | Web tools such as Burp Suite, ZAP, mitmproxy, corporate web proxies |
If you are unsure, use SOCKS5. Use HTTP when the proxy only offers an HTTP listener (a typical Burp Suite listener is an HTTP proxy).
Your password is stored in the profile file under
/etc/proxybridge/profiles/. The folder is readable by root only (mode0700, files0600), and ProxyBridge never takes credentials from the command line, so they cannot show up inpsor your shell history. Remove the password before you share an exported profile.
The default proxy
One proxy in the list is marked Default (the first one you add, until you change it). Select another row and click Set Default to move the mark.
The default proxy is used in three places:
- a new rule starts with it selected in its Action drop-down;
- a rule in an imported profile that does not name a proxy (
ProxyConfigId0) uses it; - a rule whose proxy you delete falls back to it.
You can ignore the default completely by always choosing a proxy by name in each rule.
DNS handling
The DNS via proxy option controls what ProxyBridge sends to the proxy as the destination:
| Setting | What the proxy receives | Use it when |
|---|---|---|
| Ticked (default) | The host name the application looked up, when ProxyBridge knows it (a SOCKS5 "domain" address, or CONNECT host:port for an HTTP proxy) |
The proxy is remote and should do the lookup (corporate networks, split DNS), or you want the proxy's log and your security tool to show host names instead of IP addresses |
| Unticked | The IP address the application already resolved | The proxy should only see addresses, or it cannot resolve the names you use |
ProxyBridge learns host names by watching the application's own, ordinary DNS answers. If the application used encrypted DNS (DNS over HTTPS or TLS), no name is learned and the IP address is sent either way. UDP datagrams always carry the IP address.
The option is per proxy, like in the Windows and macOS apps, so one profile can have a proxy that resolves names and another that only gets addresses. Host names are checked before they are put into a request, so a hostile DNS answer cannot inject anything into what the proxy receives.
Which DNS queries follow your rules is a separate question. DNS (port 53) is handled like any other traffic: it follows your rules, so a rule for a program that matches port 53 sends that program's DNS through the proxy too. A profile can switch this off with
"DnsViaProxy": false; see Profiles.
Test a proxy
Select a proxy in the list, check the Target and Port (they start as google.com and 80) and click Start Test. The report appears below. The test connects directly from ProxyBridge to the proxy; it does not go through your rules.
A test report looks like this:
Proxy: nexus (SOCKS5 127.0.0.1:1080), no credentials
Target: example.com:80
[1/5] Connecting to the proxy ...
OK: connected to 127.0.0.1 in 1 ms
[2/5] Opening a tunnel to the target ...
OK: SOCKS5 tunnel established in 58 ms
[3/5] Loading a page through the tunnel ...
OK: HTTP/1.1 200 OK (first byte after 18 ms)
[4/5] Measuring tunnel set-up time (3 tunnels) ...
OK: min/avg/max = 4/7/11 ms
[5/5] UDP support ...
OK: UDP ASSOCIATE accepted, the proxy relays UDP at 127.0.0.1:56512
Result: PASSED
| Step | What it checks |
|---|---|
| 1. Connecting to the proxy | Can ProxyBridge reach the proxy's address and port, and how long it took |
| 2. Opening a tunnel to the target | Does the proxy accept the login (if any) and open a tunnel to the target |
| 3. Loading a page through the tunnel | Only when the target port is 80: sends a small web request and reports the first line of the answer. Other ports skip this step |
| 4. Measuring tunnel set-up time | Opens three more tunnels and reports the fastest, average and slowest time |
| 5. UDP support | (SOCKS5 only) Asks the proxy for a UDP association. HTTP proxies report that they cannot carry UDP |
Steps 1 and 2 decide the result. If either fails the report ends with Result: FAILED. A problem in step 3, 4 or 5 is only a WARNING: the proxy works, but the page did not load, it was slow, or it cannot do UDP. That matters if you plan UDP rules: see UDP, QUIC and HTTP/3.
Common failures, with the wording ProxyBridge uses:
| Message | Usually means |
|---|---|
Cannot reach proxy: connect to 127.0.0.1:1080 failed: Connection refused |
Nothing is listening there: the proxy is not running, or the host or port is wrong |
Cannot reach proxy: cannot resolve '...' |
The proxy's host name does not resolve |
SOCKS5 authentication failed (wrong username or password) |
The login is wrong |
SOCKS5 proxy rejected all auth methods (credentials required or not accepted) |
The proxy wants a login and none is set |
HTTP proxy authentication required (407): check username/password |
HTTP proxy, wrong or missing login |
connection refused by target |
The proxy works, but could not reach the target you typed |
Edit or delete a proxy
- Edit opens the same window for the selected proxy (double-clicking a row does the same). Changes apply to every rule that uses it, at once. Renaming a proxy updates the rules that use it and the default mark.
- Delete asks first. Rules that used the proxy are not removed: they fall back to the default proxy. If you delete the last proxy, a rule that wanted a proxy has none to use and its traffic is blocked, not sent directly, so nothing leaks around a missing proxy.
Several proxies at once
A profile can hold up to 255 proxy servers (SOCKS5 and HTTP can be mixed). Each rule chooses its own proxy in its Action drop-down, so different applications can use different proxies at the same time, with no change in the applications.
Examples:
firefoxthrough a Burp Suite HTTP listener andcurlthrough Tor (SOCKS5)- A local proxy for latency-sensitive tools and a remote proxy for everything else
- One proxy per test environment, with the rules for each in a separate profile
Proxy connections are handled by a pool of workers, so a proxy that accepts connections and then never answers cannot hold up traffic that uses another proxy.
A proxy on the same machine
Proxies on the same computer (127.0.0.1) are fine: Burp Suite, mitmproxy, Tor, ssh -D, InterceptSuite. Two things are handled for you:
- No loops. A program that listens on a configured proxy address (for example Burp or
ssh -D) is exempted automatically, so a rule for*cannot send the proxy's own connections back into the proxy. The exemption follows the process, not the program name, and is refreshed every two seconds. - Localhost stays local. The connection from your application to
127.0.0.1is not proxied unless you tick Also proxy localhost traffic on the rule. See Proxy rules.
Start the proxy before you enable rules that use it. While its port is free, any program on the machine could open that port, and ProxyBridge would treat that program as the proxy. This is only a concern on machines shared with other users; see How it works.
Tips
- A proxy is only used by a rule whose Action names it. Adding a proxy on its own changes nothing.
- If the proxy lives on another machine, make sure its listener accepts connections from this computer (the proxy's bind address and firewall).
- SSH SOCKS proxies (
ssh -D) and Tor carry TCP only. For UDP you need a SOCKS5 proxy that supports UDP ASSOCIATE, for example Nexus Proxy. - Pointing ProxyBridge at a security tool is covered in Use with security tools.
