Home/Docs/macOS Guide/Proxy servers (macOS)

macOS Guide

Proxy servers (macOS)

Add, edit, test and remove SOCKS5 and HTTP proxy servers in ProxyBridge for macOS. Authentication, the DNS (send hostname) option, the four-step proxy test, UDP support and running several proxies at once.

Proxy servers on macOS

A proxy server is where ProxyBridge sends the traffic that your rules select. ProxyBridge for macOS supports SOCKS5 and HTTP (CONNECT) proxies, with or without a user name and password. You can add as many as you like and let each rule use a different one.

Open the list with Proxy > Proxy Settings... (⌘,).

The Proxy Settings window with five proxies in the table

The Proxy Settings window

Part What it does
Add (top right) Add a proxy
Name column Your label for the proxy. Shows = when you left it empty
Type column SOCKS5 or HTTP
Server column host:port
Auth column A lock icon when the proxy has a user name
Test Check the proxy (see Test a proxy)
Pencil and trash icons Edit or delete the proxy
Done Close the window

A proxy is saved the moment you press Save in its window, and the running ProxyBridge extension receives the new list at once. You do not need to restart anything.

With no proxies the window says No proxy servers configured. You can still use rules with the actions DIRECT and BLOCK without any proxy.

Add a proxy

Click Add.

The Add Proxy window

Field Meaning
Name Optional label, for example Burp or Home SOCKS. It is what you pick in the rule's Action list, shown as Burp = HTTP 127.0.0.1:8080. Without a name the list shows HTTP 127.0.0.1:8080
Proxy Type SOCKS5 (the default choice) or HTTP
Proxy IP/Domain Required. An IPv4 address, an IPv6 address, a domain name, or localhost
Proxy Port Required. A number from 1 to 65535
Username, Password Optional. Leave both empty for a proxy without authentication
Let proxy resolve DNS (send hostname) On by default. See DNS handling

The Save button stays grey until the host and port are filled in and valid. The window tells you what is wrong in red:

Message Reason
Invalid proxy IP/domain The host is not an IPv4 address, an IPv6 address, a valid domain name or localhost
Port must be a valid number The port contains something other than digits
Port must be between 1 and 65535 The number is out of range

Which type to choose

Type Use it for Notes
HTTP Burp Suite, mitmproxy, Squid and similar tools that listen as an "HTTP proxy" ProxyBridge sends CONNECT host:port to the proxy and the proxy opens the tunnel. Carries TCP only
SOCKS5 Tor, ssh -D tunnels, Shadowsocks and V2Ray local ports, corporate SOCKS gateways, InterceptSuite Carries TCP, and UDP when the proxy supports UDP ASSOCIATE

If you are not sure what your tool offers, use HTTP for Burp and mitmproxy (port 8080 by default) and SOCKS5 for everything else.

Authentication

  • The user name and password are used only when both are filled in. A user name without a password (or the other way round) is treated as "no authentication".
  • HTTP proxies get a Proxy-Authorization: Basic ... header on the CONNECT request.
  • SOCKS5 proxies: with a user name and password ProxyBridge offers both "no authentication" and "user name and password" and the proxy chooses; without them it offers only "no authentication". A SOCKS5 user name and a password can each be at most 255 bytes.
  • Credentials are stored in clear text in the app's preferences and in exported profiles. See Profiles.

DNS handling

The option Let proxy resolve DNS (send hostname) decides what ProxyBridge puts in the request to the proxy:

Setting What the proxy receives
On (default) The host name the application looked up, when ProxyBridge saw that lookup (SOCKS5 "domain" address, or CONNECT name:port for HTTP)
Off Always the IP address the application connected to

Details that matter:

  • ProxyBridge learns names by watching the Mac's ordinary DNS lookups. A name is used for five minutes after the answer was seen. If there is no recent lookup for that address (the application used a hard-coded IP, or it used encrypted DNS), the proxy receives the IP even when the option is on.
  • A name is passed to the proxy only if it consists of letters, digits, ., - and _. Anything else is replaced by the IP, so a hostile DNS answer cannot inject text into a request.
  • It only works when Enable DNS is on in the Proxy menu (on by default). With it off, ProxyBridge sees no lookups and the proxy always gets the IP address. The proxy editor shows a note about this.
  • Leave it on for proxies that should see real host names: Burp Suite and mitmproxy then show example.com instead of 93.184.216.34, and CDN-hosted sites work properly.
  • Turn it off for a proxy that cannot resolve the names your Mac can (for example a proxy outside your network that does not know your internal names).
  • The Mac itself still performs the lookup. The option changes only what the proxy is told; it does not stop the lookup from happening on your Mac.

Test a proxy

Click Test next to a proxy. A window opens and runs the checks at once.

The proxy test window after all four tests passed

At the top you can change the Host and Port the test connects to through the proxy (default www.google.com and 80) and press Retest. The test is made by ProxyBridge itself, not through your rules, so it tells you whether the proxy works, whatever your rules say.

Test What it does
Test 1: Connection to the proxy server Opens a TCP connection to the proxy and shows the connect time
Test 2: Connection through the proxy server Does the SOCKS5 handshake (with authentication if set) or HTTP CONNECT, then asks for the target, then sends a small GET / and shows the first line of the answer, for example Page loaded: HTTP/1.0 200 OK
Test 3: Proxy server latency A second, fresh connection to the proxy and its connect time in ms
Test 4: SOCKS5 UDP ASSOCIATE support SOCKS5 only. Asks the proxy for a UDP relay. Tells you whether the proxy supports UDP

A run looks like this:

Proxy:    127.0.0.1:1080
Protocol: SOCKS5
Auth:     no
Target:   www.google.com:80

Test 1: Connection to the proxy server
  Connection established (2 ms)
  Test 1 passed

Test 2: Connection through the proxy server
  Connection to www.google.com:80 established through the proxy
  Page loaded: HTTP/1.0 200 OK
  Test 2 passed

Test 3: Proxy server latency
  Latency = 1 ms
  Test 3 passed

Test 4: SOCKS5 UDP ASSOCIATE support
  UDP ASSOCIATE granted; relay = 127.0.0.1:50734
  UDP is supported by this proxy

Testing finished.

What the failures mean:

Output Meaning
Could not connect to the proxy ... Testing finished: proxy is not reachable. Nothing is listening on that host and port, a firewall is in the way, or the name does not resolve. The other tests are skipped
SOCKS5 handshake or auth failed Wrong user name or password, or the proxy does not accept the authentication methods ProxyBridge offers
SOCKS5 CONNECT failed: REP=0x05 (connection refused) The proxy works but could not reach the target. The reason in brackets comes from the proxy: general failure, not allowed by ruleset, network unreachable, host unreachable, connection refused, TTL expired, command not supported, address type not supported
HTTP CONNECT failed: HTTP/1.1 407 ... The proxy wants authentication, or rejected yours. Other codes (403, 502...) are the proxy's own answer
UDP ASSOCIATE rejected: REP=0x07 (command not supported) and UDP is not supported by this proxy The proxy handles TCP only. UDP rules that use it will not work

Test 4 matters only if you plan to send UDP (QUIC, voice, games) through the proxy. A proxy that fails it is still perfectly fine for web traffic over TCP.

Edit or delete a proxy

  • Edit (pencil) opens the same window with the current values. Changes apply to new connections. Connections that are already open keep using the old settings until they end.
  • Delete (trash) asks Delete Proxy? first. If rules use that proxy, the message says how many (3 rules use this proxy and will be set to Direct). When you confirm, those rules are changed to DIRECT, so nothing silently keeps pointing at a proxy that no longer exists.

Several proxies at once

Add all of them and choose the proxy per rule in the Action list. Typical set-ups:

  • Browsers to Burp Suite (HTTP 127.0.0.1:8080) and a command-line tool to Tor (SOCKS5 127.0.0.1:9050) at the same time.
  • A corporate proxy for the company network and a personal proxy for everything else.

See Use cases.

There is no "default proxy" on macOS: a rule always names the proxy it uses. When you create a rule, the Action starts on your first proxy (or DIRECT if you have none).

A proxy on the same Mac

Tools such as Burp Suite, mitmproxy, Tor and ssh -D usually run on 127.0.0.1. That works: the ProxyBridge extension makes its own connection to the proxy, and that connection is never redirected again.

One thing to watch: if you route all programs (*) to a local proxy tool, the tool's own outgoing connections can be caught by the same rule and loop back into itself. ProxyBridge only exempts itself, not your proxy tool. Add a DIRECT rule for the proxy tool, or name the programs you want to route instead of using *. See Use cases.

Tips

  • Run Test after every change. It takes a second and shows exactly which step fails.
  • Give proxies short names. They appear in the rule Action list and in the Connections log.
  • Proxy credentials are in the clear in profile files. Use a throw-away account, or remove the password before sharing a profile.
  • Port and host are checked when you save, but ProxyBridge cannot know whether something is listening. A proxy that is down shows up as SOCKS5 connect failed or ... greeting write failed entries in the Activity Logs, and the affected connections fail (they do not fall back to direct).

Next

  • Proxy rules: decide which traffic goes through which proxy.
  • Profiles: save a set of proxies and rules, and switch between them.