Linux Guide
Settings, pausing and start at boot (Linux)
Every menu in ProxyBridge for Linux: pause and resume, start and stop the engine, the ProxyBridge service, Start at Boot, text size, update checks, Documentation and About.
Settings, pausing and start at boot
The menu bar has the same four menus as the Windows app: Proxy, Profile, Settings and Help.
The menus at a glance
| Menu | Items |
|---|---|
| Proxy | Enable ProxyBridge, Start Engine, Stop Engine, Proxy Settings..., Proxy Rules..., Log Filters..., Exit |
| Profile | New, Duplicate, Rename, Delete, Import, Export, Switch Profile (see Profiles) |
| Settings | Enable Traffic Logging, Start at Boot (systemd service), Auto-clear Logs, Log Every Connection, Check for Updates on Startup, Zoom In, Zoom Out, Reset Zoom |
| Help | Documentation, Check for Updates..., About |
Settings that are saved in the profile (traffic logging, auto-clear, log every connection, zoom) are explained in Connections and logs. The rest of this page covers the other items.
Pausing ProxyBridge
Proxy > Enable ProxyBridge is the main switch. It is ticked when ProxyBridge starts.
- Untick it and new connections are no longer redirected: every application talks to the network directly, as if ProxyBridge was not installed. The Activity Logs tab says
ProxyBridge paused: new connections are not redirected. - Tick it again and your rules apply to new connections once more.
Connections that are already open keep the route they were given when they started. The switch is not saved in the profile, so ProxyBridge always starts enabled.
Use it when you want to compare behaviour with and without the proxy, or to do something quickly without proxy rules getting in the way, without touching your rules.
Start Engine and Stop Engine
The engine is the part that loads the eBPF programs and the relay. It starts when you open the window. Proxy > Stop Engine removes everything ProxyBridge put into the kernel and stops the relay. Nothing is redirected any more and the status bar shows Engine: Stopped. Start Engine brings it back with the active profile's proxies and rules.
Stopping the engine is different from pausing: pausing keeps the engine loaded and only stops redirecting; stopping unloads it completely. Both leave your applications working normally.
If ProxyBridge exits or crashes, traffic simply goes direct. The kernel programs are attached with a link that disappears with the program, so there is no state where your connections are redirected to a relay that no longer exists. See How it works.
Proxy > Exit (or closing the window, or Ctrl+C in the terminal that started it) closes the window. Whether routing stops with it depends on Start at Boot: off (the default), the engine is stopped and everything goes direct; on, the service keeps routing.
The service
The window is only a control panel. The engine runs in proxybridge.service, which the installer sets up as a root service. That is why the window needs no sudo.
- The window and the service talk through
/run/proxybridge/ctl.sock. If the service restarts (an update, a crash), the status bar saysLost the connection to the ProxyBridge service. Trying to reconnect..., the window reconnects by itself within a few seconds and sends its configuration again, and the Activity Logs sayconnected to the ProxyBridge service again. - Only root and members of the group
proxybridgemay use it. See Install on Linux. - What the service did before the window connected (for example loading your profile at boot) appears in the Activity Logs when the window opens.
- A window started with
sudoon a system without the service runs the engine inside itself, as older versions did.
Useful commands:
systemctl status proxybridge # is it running?
journalctl -u proxybridge -f # follow its output
sudo systemctl restart proxybridge # restart it (open windows reconnect)
sudo systemctl stop proxybridge # stop the service: routing ends, everything goes direct
The service is installed with these settings (the path is where you installed ProxyBridge):
[Unit]
Description=ProxyBridge
Documentation=https://proxybridge.interceptsuite.com/docs/linux-settings/
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
ExecStart="/usr/local/bin/ProxyBridge" --daemon
Restart=on-failure
RestartSec=5
RuntimeDirectory=proxybridge
RuntimeDirectoryMode=0755
LimitNOFILE=1048576
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=/etc/proxybridge
ProtectHome=yes
PrivateTmp=yes
ProtectKernelModules=yes
ProtectKernelLogs=yes
ProtectKernelTunables=yes
ProtectControlGroups=yes
ProtectClock=yes
ProtectHostname=yes
PrivateDevices=yes
RestrictSUIDSGID=yes
LockPersonality=yes
RestrictRealtime=yes
RestrictNamespaces=yes
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
SystemCallArchitectures=native
MemoryDenyWriteExecute=yes
UMask=0077
MemoryMax=1G
TasksMax=512
CapabilityBoundingSet=CAP_BPF CAP_PERFMON CAP_NET_ADMIN CAP_SYS_ADMIN CAP_SYS_RESOURCE CAP_SYS_PTRACE CAP_DAC_READ_SEARCH
[Install]
WantedBy=multi-user.target
It runs as root because loading eBPF needs it, and is limited to what the engine needs: only the capabilities listed (no changing owners, killing processes, setuid, loading modules, raw I/O, mounting or setting the clock), no new privileges, nothing writable but /etc/proxybridge, no access to home folders or devices, only unix and internet sockets, no new namespaces, no writable-and-executable memory, its own private /tmp, and at most 1 GB of memory. If it dies, systemd restarts it after 5 seconds. See How it works.
Start at Boot
Settings > Start at Boot (systemd service) decides what the service does when nobody has the window open:
| Start at Boot | When the machine starts | When you close the window |
|---|---|---|
| On | The service applies your active profile and starts routing, before anyone logs in | Routing continues |
| Off (default) | The service starts but stays idle | Routing stops: the engine is stopped and everything goes direct, as with a program you close |
Switch it on for a server or a test machine that must keep routing, with or without a window. Leave it off for a desktop where you only want ProxyBridge active while you are using it.
Things worth knowing:
- It follows the active profile. The service runs the profile that was active when you last used the window, so switching profile in the window changes what the next boot starts.
- The setting belongs to the service, not to a profile (it is stored in
/etc/proxybridge/settings.jsonasStartAtBoot). - Closing the window never stops the service itself, only the engine inside it, and only when Start at Boot is off.
- The service itself always starts at boot (the installer enabled it); with Start at Boot off it simply waits. It uses almost no resources while idle.
- A profile that cannot be loaded does not stop the service. It stays up, says why in
journalctl -u proxybridgeand in the Activity Logs, and waits for a window. - If the engine cannot start (a kernel without BTF, for example) the service says so and keeps running; the window shows
Failed to start the ProxyBridge enginewith the reason in the Activity Logs.
Without the service (a window started with sudo), Start at Boot installs and enables an equivalent unit for you and removes it when you switch it off.
Text size (zoom)
Settings > Zoom In (Ctrl + +), Zoom Out (Ctrl + -) and Reset Zoom (Ctrl + 0) change the text size of the whole application, including the dialogs, in steps of 10 percent, between 60 and 300 percent. It is saved in the profile.
Updates
Help > Check for Updates... asks the project's update feed whether a newer Linux version exists and tells you the result:
You are using the latest version (x.y.z).Version x.y.z is available (current x.y.z). Open the download page in your browser?with Open in Browser and Close.- An error message if the feed could not be reached.
Settings > Check for Updates on Startup (on by default) does the same quietly when the window opens: you only see a message when a newer version exists. That message also offers Don't Check at Startup, which unticks the item. The setting belongs to the app, not to a profile.
ProxyBridge never downloads or installs anything by itself. The download page opens in your browser, and only addresses on the project's own sites are accepted (the browser is started by the root-run window, so nothing else is ever handed to it). To update, install the new version.
Documentation and About
- Help > Documentation opens these pages in your browser.
- Help > About shows the version, the kernel requirement, the author and the licence (MIT).
What the Linux app does not have
The Windows app has a few items that make no sense on Linux and are left out on purpose:
| Windows | On Linux |
|---|---|
| Language | English only |
| Close to tray, tray icon | There is no tray. ProxyBridge keeps running in the background through the service: turn on Start at Boot and closing the window leaves routing on |
| Start with Windows | Start at Boot: the service applies your profile when the machine starts |
