Runscope Gateway Agent

The Runscope Gateway Agent runs within your infrastructure and captures HTTP and HTTPS API requests made to private or internal APIs. The captured request data is available in the API Traffic Inspector just as if the requests had been made through our cloud-based global traffic gateways. The agent is particularly useful if you're looking to debug API traffic in the following situations:

  • Troubleshooting API calls made to private or internal APIs that reside behind a firewall.
  • Creating Gateway URLs for services running on localhost.
  • Accessing APIs that require a fixed client IP address (IP whitelisting).

Use of the Gateway Agent requires a trial or paid subscription.



How it Works

The agent works by creating a locally-hosted instance of the Runscope Gateway with your own hostname and TLS certificate. Instead of using our cloud-based Runscope Gateways (hosted on *.runscope.net), requests will use the configured hostname for your agent instead.


How Runscope Gateway Agent works


Inspecting traffic with the gateway agent uses a hybrid on-premises approach. The agent runs on a host within your infrastructure, but traffic data is stored in the Runscope cloud to make searching and collaboration easier. Traffic collected with the agent is available in the Traffic Inspector along with all other traffic made in the same bucket.

All communication from the agent to the Runscope cloud is made securely over outbound requests to the Runscope API via HTTPS on port 443. See Firewall Considerations for more information.

Downloading the Agent

Select an operating system to download the gateway agent:

 

DNS & SSL Certificate Prerequisites

Before running the agent, you'll need to have a valid wildcard DNS entry (e.g. *.example.com) for the domain you want to use while running the agent. The hostname must be visible to all potential clients that wish to have their traffic captured. The DNS entry should point to the IP address for the host the agent is running on.

To capture HTTPS traffic through your agent you'll need to create a PEM-encoded, wildcard SSL certificate and key file that trusted by the client(s) making API calls through the agent.

Firewall Considerations

By default the agent will listen on ports 8000 (plain HTTP) and/or 8443 (SSL/TLS). Be sure the configure the host running the agent to allow connections on those ports on the network interface(s) you want to listen on. If the traffic is entirely on-premises, be sure to keep any external traffic restrictions in place.

Configuring and Running the Agent

After downloading the agent, extract the executable from the .zip file and run it from your command line:

Linux and OS X

$ ./runscope-gateway

Windows

C:\> runscope-gateway.exe

You will be prompted to sign in to your Runscope account and select a team. Once authenticated, you can save a configuration file to be used for subsequent runs of the agent (without having to sign in). To launch the agent with a specific configuration file, use the -f command line option. This is the recommended way to start the agent.

To generate a new configuration file, launch the agent without any command line options specified and enter your desired settings:

  • hostname - The DNS entry for the host the gateway is listening on.
  • network interface - The host's network interface to listen on.
  • HTTP port - The port to listen for incoming HTTP connections on (optional).
  • HTTPS port - The port to listen for incoming HTTPS connections on (optional).
  • SSL certificate - The path to a PEM-encoded SSL certificate file (required if using HTTPS).
  • SSL key - The path to a PEM-encoded SSL key file (required if using HTTPS).

Once you've finished configuring the agent you can chose to save your input as a configuration file.


Command Line Option Reference

You can specify options on the command line to override those used in the configuration file.

-f, --config-file Start the agent with the configuration contained within the specified configuration file.


Need help running or configuring the Runscope Gateway Agent in your infrastructure? Contact Support.