search close

Reverse Proxy Mode

access_time Updated Jun 20, 2021

The Agent can be configured to run as a reverse proxy allowing it to interact directly with requests and responses without the need for a module. Running the Agent in reverse proxy mode is ideal when a module for your web service does not yet exist or you do not want to modify your web service configuration - for example, while testing the product. In this mode, the agent sits inline as a service in front of your web service.

In reverse proxy mode, the Agent will start one or more listeners and proxy all traffic received on the listener(s) to the configured upstream server. Both HTTP, HTTPS (TLS) listeners can be enabled. Note that configuring the Agent in reverse proxy mode will disable the RPC listener and the Agent will not function with any modules.

Reverse Proxy Listener Configuration

The reverse proxy now supports an arbitrary number of listeners (before only 1 each of HTTP and TLS). Each listener is now configured in a revproxy-listener block. Each block is defined by a unique name in the format [revproxy-listener.NAME]. Each block has its own set of directives for that listener. Multiple blocks are supported, but all blocks MUST be at the end of the configuration file after all other global options.

For example, to configure a simple HTTP (no encryption) listener, update the agent.conf file (default: /etc/sigsci/agent.conf) to include the following configuration block as shown below that creates an HTTP reverse proxy listener named example1:

listener = ""
upstreams = ""

The listener option is the address the Agent will listen on in the form of a URL, and the upstreams option defines the upstream host(s) that the Agent will proxy requests to. The upstream hosts are a comma separate list of URLs. The scheme of the URLs specify the protocol that will be used for listening and proxying to the upstreams.

Note: If your load balancer is configured for sticky session load balancing, you will need to create a separate listener for every upstream host.

To configure a TLS encrypted listener, use the https scheme for the listener option and configure the tls-key and tls-cert options to point to files containing the key and cert. The upstreams scheme determines the protocol used to proxy to the upstream hosts.

Encrypt traffic to Upstream

listener = ""
upstreams = ","
tls-cert = "/etc/sigsci/server-cert.pem"
tls-key = "/etc/sigsci/server-key.pem"

Terminating TLS at the Agent

This option is similar to the above with the only difference being the scheme used in the upstreams.

listener = ""
upstreams = ","
tls-cert = "/etc/sigsci/server-cert.pem"
tls-key = "/etc/sigsci/server-key.pem"

Note: In both options, the cert and key files can be the same file provided you concatenate both key and cert into one file.

After you have completed the desired configuration, reload the “sigsci-agent” configuration for the changes to take effect. On most systems this can be done by sending a SIGHUP signal to the agent process ID (e.g., kill -HUP 12345 where 12345 is the PID) or just restarting the agent.

The [revproxy-listener.NAME] configuration and its available options are documented on the agent configuration page.

Alternative configuration without a configuration file

If you are not using a configuration file, then you cannot use the new block format above and you must instead use an alternative format. This format can be used with a single --revproxy-listener command line option or via a single SIGSCI_REVPROXY_LISTENER environment variable.

Generic format for the alternative revproxy-listener value

listener1:{opt=val,...}; listener2:{...}; ...

Some example from above are repeated here in the alternative format.

Simple HTTP listener


Simple HTTPS listener


Multiple listeners can be specified in a single option by separating each listener definition with a semicolon (;).

Multiple listeners

SIGSCI_REVPROXY_LISTENER="example1:{...}; example2:{...}"

Side Effects and Limitations

HTTP header names are normalized

The agent in reverse proxy mode will normalize all header names by capitalizing the first letter in each word. For example, example-header becomes Example-Header.

HTTP header order may not be maintained

Due to technical limitation, the agent in reverse proxy mode does not allow for tracking and maintaining the order of headers. The order of headers may change when sent to the upstream server. For example:

GET /test HTTP/1.1
X-Example-Header: example
X-Test-Header: test
X-Other-Header: other
Accept: */*

This request may arrive at the upstream server as:

GET /test HTTP/1.1
Accept: */*
X-Test-Header: test
X-Other-Header: other
X-Example-Header: example

Added headers

By default, the following headers are added to the upstream request:

  • X-Forwarded-For
  • X-Forwarded-Host
  • X-Forwarded-Proto
  • X-Forwarded-Server

In agent v3.7+, each listener can be configured with minimal-header-rewriting = true and these additional headers will not be added/modified. These headers will still be passed through if they exist in the request. Additionally, configuring a listener to not trust the proxy headers with trust-proxy-headers = false will strip these headers before sending to the upstream.

Additionally, the following Signal Sciences headers will be added regardless of the above configurations:

  • X-Sigsci-Agentresponse
  • X-Sigsci-Tags (only if there were tags added)

HTTP/1.0 to upstream is upgraded to HTTP/1.1

Any HTTP/1.0 requests processed by the agent in reverse proxy mode will be upgraded to HTTP/1.1 when sent to the upstream. This means:

  • HTTP keepalives are enabled by default
  • HTTP/1.1 version is used in the request line
  • The HTTP Host header is added
  • The Accept-Encoding: gzip header is added

HTTP/0.9 is not supported

Go (which the agent is written in) does not support HTTP versions prior to HTTP/1.0. Any requests in the HTTP/0.9 format will result in a 400 Bad Request error response. This may affect some simple monitoring from older monitors and load balancers.

For example, GET / is a request in HTTP/0.9 format and would result in a 400 error.
By contrast, GET / HTTP/1.0 is in the supported HTTP/1.0 format, which specifies the HTTP version.

Failing open

When the agent is running in reverse proxy mode, requests that have failed open are not sent to the Signal Sciences cloud backend and therefore won’t be visible on the requests page of the console.

Next Steps

Explore other installation options: