Proxy Support

The forwarder can be pointed at an HTTP proxy, authenticated or not, and on Windows and Linux that is an explicit setting you control. Set it during installation if you know the proxy in advance, or afterwards on a host that is already installed. Whichever way you set it, the proxy string takes one form:

http://[username:password@]<ip_address_or_hostname>:<port>

Two examples:

A proxy the forwarder routes through is a different question from a proxy that decrypts and re-signs traffic on the way past. Both can be true at once, and the second one breaks a forwarder that is otherwise configured correctly. That case has its own section at the end of this page, and it is the one to read if traffic is reaching the proxy and Stairwell is still receiving nothing.

How do I set a proxy on Windows at install time?

Pass HTTPSPROXY to the installer. It applies from the forwarder's first run, so there is no window in which the host tries to reach Stairwell directly.

.\StairwellForwarderBundle-1.7.9.1.exe TOKEN="TOKENHERE" ENVIRONMENT_ID="ENVIRONMENTIDHERE" HTTPSPROXY="http://127.0.0.1:8081" /quiet /norestart /log C:\stairwell.log

The installer filename above is the current bundled package. Take the exact name from Windows v1.7.9, because it carries the build number and changes with every release.

How do I set a proxy on a Windows host that is already installed?

Add a HttpsProxy string value to the forwarder's registry key, then restart the service. The key depends on the forwarder version, because the product was renamed partway through its history and older forwarders still read the old location.

The value to add:

To remove a proxy, delete the HttpsProxy value from the same key and restart the service again. Deleting the value is not the same as setting it to an empty string, and an empty string is not a documented way to disable it.

The forwarder reads this at startup, so the restart is not optional. Windows Forwarder Troubleshooting has the service names to stop and start.

How do I set a proxy on Linux?

Set proxyURL in /etc/stairwell/config.json, then restart the service.

{
  "logger": { "loglevel": "info" },
  "asset": {
    "EnvId": "YOUR_ENVIRONMENT_ID",
    "Token": "YOUR_TOKEN"
  },
  "proxyURL": "http://proxy.example.com:8080"
}

sudo systemctl restart stairwell

The file is JSON, so a stray comma stops the forwarder starting at all rather than starting without a proxy. If the service does not come back, Linux Forwarder Troubleshooting covers where the startup error goes.

What if the proxy inspects TLS?

Add Stairwell's hostnames to the proxy's decryption bypass list. Pointing the forwarder at the proxy does not solve this on its own, and no endpoint-side setting will.

A device that terminates TLS, reads the plaintext, and re-signs it with your organization's own certificate authority presents a certificate the forwarder will not accept. Browsers on the same machine accept it, because the internal authority is trusted locally, so the network looks healthy to everyone who works on it. The forwarder verifies that it is talking to Stairwell rather than to something in the middle, declines, and keeps quiet about it.

Bypass all four:

• *.app.stairwell.com
• *.api.stairwell.com
• downloads.stairwell.com
• storage.googleapis.com

Those are the same hostnames the proxy needs to allow at all, so allowlist and bypass list can be set in one pass.

Confirm the result rather than assuming it: swell verify connectivity on the affected machine reports possible MITM proxy while inspection is still in the path, and clean rows once it is not. Pre-Deployment Check covers that command and how to read its output.

One related failure to know about, because it survives a correct bypass list: a proxy that passes ordinary HTTPS and interferes with HTTP/2 leaves the gRPC endpoints unreachable while everything else looks fine. In the connectivity check that shows up as a gRPC row failing on its own.

What should I read next?

• Pre-Deployment Check, to prove the path works before you deploy behind a proxy at scale.
• What to Check First, if the proxy is configured and data still is not arriving.
• Forwarder Downloads, for the current installers and their exact filenames.