Home/Docs/Linux Guide/Command line (Linux)

Linux Guide

Command line (Linux)

Run ProxyBridge on Linux without a window: the ProxyBridge command, its options, verbosity levels, output, error messages, update check, and how to use it from systemd, scripts and CI.

Command line

ProxyBridge is the same engine as the window, without the window. It loads a profile, applies its proxies and rules, prints what it is doing and runs until you press Ctrl+C. Use it on servers, over SSH, in scripts, in CI and as a boot service.

The profile can be built in the window (Profile > Export Profile...), written by hand, or taken from a colleague. The .pbprofile format is the same one the Windows and macOS apps use.

sudo ProxyBridge --profile work

Options

Option What it does
--profile <path or name> The profile to run. Either a path to a .pbprofile file (anything containing a /: ~/lab.pbprofile, ./team.pbprofile) or the name of a profile saved by the window (work, Pentest lab, with or without .pbprofile)
--verbose <0-3> How much to print. See Verbosity. Default 0
--version Print the version and exit
-h, -?, --help Print the help and exit
--update Check for a newer version and print where to download it. Needs no root
--daemon Run as the ProxyBridge service: owns the engine and the profiles and serves the window. This is what proxybridge.service runs; you rarely start it yourself. Needs root. It cannot be combined with --profile
--socket <path> With --daemon: the control socket (default /run/proxybridge/ctl.sock)
--print-unit <path> Print the systemd unit that runs <path> --daemon (the installer uses it). Needs no root

To run a profile you only need --profile. A name is looked up in /etc/proxybridge/profiles; a path is used as it is. A bare file name such as lab.pbprofile is treated as a name, so for a file in the current folder write ./lab.pbprofile. Credentials are never accepted on the command line, so they cannot appear in ps or in your shell history; they live in the profile file.

Root is required

The engine loads eBPF programs and reads /proc, which needs root, so ProxyBridge --profile must run with sudo or as root. (The window does not need root: it uses the service.) Without it you get:

ERROR: ProxyBridge requires root privileges!
Please run this application with sudo or as root.

Kernel 5.11 or newer with BTF and cgroup v2 is also required. See Install on Linux for how to check.

A first run

$ sudo ProxyBridge --profile nexus-lab --verbose 2
Loading profile: /etc/proxybridge/profiles/nexus-lab.pbprofile
...banner...
Proxies: 1
  [1] nexus socks5://127.0.0.1:1080
DNS via Proxy: Enabled
Rules: 3
  [1] curl:*:80;443:TCP -> PROXY
  [2] python3:*:*:UDP -> PROXY
  [3] telemetry-agent:*:*:BOTH -> BLOCK

ProxyBridge started. Press Ctrl+C to stop...

[CONN] curl (PID:22117) -> 93.184.216.34:80 via SOCKS5 127.0.0.1:1080
[CONN] python3 (PID:22140) -> 8.8.8.8:53 via SOCKS5 127.0.0.1:1080 (UDP)
^C
ProxyBridge stopped.

What each part means:

Line Meaning
Loading profile: ... The file that was found
Proxies: N and the numbered list Each proxy as type://host:port, with (auth) if it has a login and (dns:local) if DNS via proxy is off for it
DNS via Proxy: Enabled or Disabled The profile's DnsViaProxy value: whether DNS (port 53) follows your rules
Rules: N and the numbered list Only the enabled rules, in the profile's order, as process:hosts:ports:protocol -> ACTION. (+localhost) marks a rule that also proxies localhost traffic
ProxyBridge started The engine is running. Rules are active from this moment
ProxyBridge stopped. After Ctrl+C or SIGTERM the hooks are removed and everything goes direct again

Verbosity

The default (0) prints the lines above and nothing else, which keeps a boot service's journal short. Raise it to see decisions and problems:

Level Prints
0 Nothing after the start-up lines
1 Messages from the engine, prefixed [LOG]: the same text as the window's Activity Logs tab
2 One [CONN] line per decision, like the window's Connections tab
3 Both

A connection line:

[CONN] firefox (PID:21408) -> 104.18.32.47:443 via HTTP 127.0.0.1:8080
[CONN] chromium (PID:20977) -> 142.250.74.14:443 via SOCKS5 proxy.corp.example.com:1080 (UDP)
[CONN] git (PID:22301) -> 140.82.112.3:22 via DIRECT
[CONN] telemetry-agent (PID:1984) -> 198.51.100.23:443 via BLOCK

Meaning: process, process ID, destination, the route taken (DIRECT, BLOCK or the proxy), and (UDP) for UDP. Unlike the window, these lines carry the IP address only, not the looked-up name. Which lines appear follows the profile's Log Every Connection setting. The profile's log filters and traffic-logging switch belong to the window; the command line is controlled by --verbose.

Redirect the output to keep a record, for example sudo ProxyBridge --profile work --verbose 3 | tee proxybridge.log.

Profile errors

The profile is checked completely before anything is loaded into the kernel. A problem stops the program with exit status 1 and changes nothing.

Message Cause and fix
ERROR: No profile specified. --profile is missing. Add it
ERROR: Invalid profile '...' The name cannot be turned into a profile file name (for example it is empty)
ERROR: ... right after Loading profile: The file could not be read or is not valid: missing, unreadable, too large (the limit is 4 MiB), not JSON, a bad number, text with control characters, a rule that names a proxy that is not in the file. The message says which
ERROR: Profile contains no enabled rules. Every rule is switched off, or there are none. Enable at least one rule
ERROR: A rule uses a proxy but the profile has no proxy server. A rule's action is Proxy but the profile has no proxies
ERROR: Proxy 'name' (host:port): ... The engine rejected that proxy (for example an unusable host name or port)
ERROR: Rule N (process:hosts:ports): ... The engine rejected that rule, with the reason: for example a bad address range, a bad port, or an empty list. N is the rule's position in the file
ERROR: Failed to start ProxyBridge (run with --verbose 1 for details) The engine could not start: usually the kernel, cgroup or permission problem. Run with --verbose 1. See Troubleshooting
ERROR: Unknown option '...' and Use --help for usage information A typo in an option
ERROR: Verbose level must be 0-3 --verbose got a value outside the range

Disabled rules ("IsEnabled": false) are skipped silently, which makes it easy to keep optional rules in a profile and switch them with a text editor.

A warning is printed, but the run continues, when the profile holds proxy passwords and other users can read the file:

WARNING: /home/alice/lab.pbprofile holds proxy credentials but other users can read it (chmod 600 recommended)

Fix it with chmod 600 lab.pbprofile.

Checking for updates

$ ProxyBridge --update
Current version: 4.0.0-Beta
Latest version:  4.0.1
A newer version is available.
Release notes:   https://github.com/InterceptSuite/ProxyBridge/releases/tag/...
Download:        https://github.com/InterceptSuite/ProxyBridge/releases/download/...

This only reads the project's update feed and prints the result. Nothing is downloaded or installed, and only HTTPS links are shown. It exits with 0 when it could read the feed (whether or not a newer version exists) and 1 when the feed could not be fetched or has no Linux entry. It works without root, so it can run from a cron job or a login script.

Stopping

Press Ctrl+C, or send SIGTERM (sudo kill <pid>, systemctl stop). The program removes the kernel hooks and exits with ProxyBridge stopped. If it is killed with SIGKILL or crashes, the kernel drops the hooks anyway and traffic goes direct.

The command line and the service

Two ways to run ProxyBridge without a window:

  • ProxyBridge --profile <name> (this page): one profile, in the foreground, until Ctrl+C. Nothing is installed. Good for scripts, CI and quick tests.
  • The ProxyBridge service (proxybridge.service, which the installer sets up): runs in the background, holds all your profiles, and is what the window controls. With Start at Boot on (window: Settings), it applies the active profile when the machine starts and keeps routing with no window and no login. See Settings and Install on Linux.

Don't run both at the same time: they would manage the same rules. If the service is routing, stop it first (sudo systemctl stop proxybridge) before ProxyBridge --profile.

To install the service by hand (without setup.sh):

sudo ProxyBridge --print-unit /usr/local/bin/ProxyBridge | sudo tee /etc/systemd/system/proxybridge.service
sudo groupadd --system proxybridge          # who may use it besides root
sudo systemctl daemon-reload
sudo systemctl enable --now proxybridge

The profile it runs at boot is chosen in the window (the active profile) and stored in /etc/proxybridge/settings.json; to run a profile at boot without ever opening the window, copy it into /etc/proxybridge/profiles/ and set "ActiveProfileName" and "StartAtBoot": true there. A .pbprofile run directly with --profile is independent of all this.

Using it in scripts and CI

  • Run for the duration of a test, then stop:

    sudo ProxyBridge --profile ./ci.pbprofile --verbose 2 > proxybridge.log 2>&1 &
    PB=$!
    sleep 2                               # wait for "ProxyBridge started"
    ./run-tests.sh
    sudo kill "$PB"
    wait "$PB" 2>/dev/null
    

    Instead of sleeping, wait for the line ProxyBridge started to appear in the log.

  • Exit status. 0 after a clean stop, 1 for every error listed above. A script can tell whether the engine came up by checking that the process is still alive after the start-up lines.

  • Containers. ProxyBridge uses the host kernel and root. Run it on the host; see Troubleshooting for what applies to programs inside containers.

  • CI runners. Any runner with a recent kernel (see the requirements) and sudo works: install the release, then sudo ProxyBridge --profile ./ci.pbprofile.

  • Several runs. Don't start two copies with different profiles at the same time; stop one first.

The command line and the window

Window (ProxyBridgeGUI) Command line (ProxyBridge)
Edit proxies, rules and filters Yes Edit the .pbprofile file
Live log and byte counters Yes --verbose output
Runs without a display No Yes
Starts at boot Via Start at Boot (the service) --profile does not; use the service
Test a proxy Yes Use curl through the proxy
Several profiles Switch from the menu One per run
Needs root No (the service does) Yes

Both use the same profile files, so a good workflow is: build and test the profile in the window, export it, run it with the command line on the server.