Install Ekko Proxy, a simple service virtualization utility that can be used to monitor, record or playback web service messages.
Virtualizing critical APIs can drastically help reduce dependencies and delays during the delivery pipeline.


Ekko Proxy is packaged as a 'fat' jar and only requires Java 8 or later to run on your local machine or server.


Ekko Proxy can be downloaded from here and from github.


Once downloaded Ekko Proxy can be run from the command line:

 $ java -jar ekkoproxy-1.3.1.jar

Application settings

The following application startup settings can be overridden on the command line and more than one can be specified at a time. E.g. setting a different server port can be done like this:

$ java -jar ekkoproxy-1.3.1.jar --server.port=8081
Setting Description
server.port Sets server port to access the application on. Defaults to 4040. Sets the output directory for any recorded messages. If set, users will not be able to specify it in the Ekko Proxy UI. Can be a relative or full path. If it does not exist then it will be created. E.g.\\foo\\ekkoproxy or Sets the maximum number of messages (i.e. in memory history), per proxy, that can be viewed at anyone time. Defaults to 100.

Note without a license this setting is ignored and a more limited number of messages are displayed.
ekkoproxy.http.connection.timeout Sets the time (in milliseconds) to establish the connection with the remote host. Defaults to 0.

Note a timeout value of zero is interpreted as the platform default which is usually anything from 20 seconds to minute depending on the operating system. Also you cannot specify a connection timeout that increases the platform default; you can only use it to decrease it from the platform default.
ekkoproxy.http.socket.timeout Sets the time (in milliseconds) waiting for data – after establishing the connection; maximum time of inactivity between two data packets. A timeout value of zero is interpreted as an 'infinite' timeout. Defaults to 0.
ekkoproxy.threadpool.corePoolSize The core pool size is the minimum number of threads always kept alive for request handling. Defaults to -1. Zero and negative values have special meaning as per below:
0 = means a pool size equal to the number of available processors.
-1 = means a pool size equal to the number of available processors * 2.
-2 = means a pool size equal to the number of available processors * 3.
-3 = means a pool size equal to the number of available processors + 1.
-4 = means a pool size equal to the number of available processors + 2.
-5 = means available processors +3 and -6 would be +4 and so forth.
ekkoproxy.threadpool.maxPoolSize The maximum number of active threads in the pool at anyone time. Defaults to 200.
Zero and negative values work in the same way as the corePoolSize setting.
ekkoproxy.threadpool.keepAliveTime The number of milliseconds the pool will keep idle/extra threads (above the core pool size) alive for. Defaults to 60000 (1 minute).
ekkoproxy.threadpool.queueSize The maximum queue size for incoming requests when all possible request processing threads are in use. Any requests received when the queue is full will be refused. A value of zero means the queue is unbounded and requests would effectively never be rejected and you could run out of resources if requests keep coming in at a higher rate than they can be processed. Defaults to 100.
ekkoproxy.threadpool.prestartCoreThreads Starts all core threads, causing them to be idly wait for work. Defaults to false.
server.tomcat.max-threads The size of the thread pool of the embedded Tomcat web server. Defaults to 200.

Note this is usually more than enough however if forwarding is being used extensively then it may be necessary to increase this number.

Start proxies on startup

On start up of the application you can specify one or more proxies that you want to setup and start straightway.

The only prerequisite for this is that a settings file e.g. EkkoProxySettings_3099.json for each proxy exists already in the same working directory as the Ekko Proxy application itself. The settings file for a proxy is created automatically once a proxy has been created via the Ekko Proxy UI or Command line interface.

 $ java -jar ekkoproxy-1.3.1.jar --proxy=3099 --proxy=1080

Configuring SSL

If you need to have the Ekko Proxy running on a secure connection then you can configure the following SSL properties when starting it.

Setting Description
server.ssl.key-store-type The format used for the keystore. Would normally be PKCS12 but it could also be set to JKS in case it is a JKS file.
server.ssl.key-store The full or relative path to the keystore containing the certificate.
server.ssl.key-store-password Password used to access the certificate / key store.
server.ssl.key-alias The alias that identifies the key in the key store.

Command line interface

Besides the web interface (see Accessing), Ekko Proxy can also be controlled on the command line using curl or similar to send commands.

Starting a proxy

Starting a proxy that's already has a settings file e.g. EkkoProxySettings_1080.json can be done like this:

 $ curl -i http://localhost:4040/cli/proxies/1080/start

If you want to create and start a proxy (i.e. it does not already have a saved settings file) then you can do:

 $ curl -i -X POST http://localhost:4040/cli/proxies \
-H "Content-Type: application/json" \
-d @- << 'EOF'
  "listenerPort" : 1080,
  "targetPort" : 80,
  "targetHost" : "",
  "mode" : "playback",
  "outputDir" : "./recordings",
  "outputFormat" : "XML",
  "outputSubFolderExpressions" : [ "local-name(//Envelope/Body/*[1])", "(//UserID/text()|//Author/text())[last()]" ],
  "excludeExpressions" : [ "//Header/TraceId", "//Header/SessionId", "//ServiceRequest/userAgent" ],
  "expressionFormat" : "XPATH",
  "includeHeadersInHash" : false,
  "useRequestUriInOutputPath" : true,
  "targetHttps" : false,
  "sslCertificatePath" : "",
  "sslCertificatePassword" : "",
  "delays" : null,
  "description" : ""

Stopping a proxy

Stopping a running proxy is done as per below:

 $ curl -i http://localhost:4040/cli/proxies/1080/stop

Removing a proxy

The following command can be used to remove a proxy (it doesn't matter if it's stopped or started):

 $ curl -i http://localhost:4040/cli/proxies/1080/remove


Once the application has started the Ekko Proxy management page can be accessed in a browser on either localhost:<server.port>, if running locally or <hostname>:<server.port>, if running on a server. E.g.


Putting the above url in a browser like Chrome (recommended browser) or Firefox will load the Ekko Proxy application as per below screenshot:

ekkoproxy management screen

Usage scenarios

Ekko Proxy can be used in many different scenarios during the software development and testing cycles of an application. A couple of 'before and after' scenarios are shown below.

Classic client server scenario where the client application is directed at Ekko Proxy and Ekko Proxy is pointed to the target server / host:

Ekko Proxy install scenario one

Another scenario could be where you have a single page web application connecting to a middle tear using REST (JSON) and the middle tear connecting through to backend systems using SOAP (XML) or REST. In this scenario you could configure Ekko Proxy on two ports to intercept and possibly playback messages between the different layers:

Ekko Proxy install scenario two

Even if you have a mix of REST, SOAP etc. backend services you can simply setup multiple proxies on different ports to handle them.


Once an Ekko Proxy is running on a port then you can configure your application to go through the proxy by repointing the application service endpoints to <hostname>:<port> of where Ekko Proxy instance resides e.g. localhost:3080.

There can be situations where the port, that an Ekko Proxy is created on, cannot be exposed outside of that machine be it due to firewalls or cloud restrictions etc. In those cases requests can be 'forwarded' to the Ekko proxy/proxies using a special forward/<port> path as in the example endpoints below:


Note using this feature will consume threads from the main Tomcat thread pool rather than the individual Ekko Proxy thread pools.

< Go Back