Configuration and Setup

Configuring Wilma

To run Wilma, it should be configured first in wilma.conf.properties.

This configuration file must contain the following property entries (the values here are the default ones):

############################################################################
# Copyright 2013-2016 EPAM Systems
#
# This file is part of Wilma.
#
# Wilma is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Wilma is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Wilma.  If not, see .
############################################################################

# the port used by the proxy
proxy.port=9092

# internal jetty port on which web application is deployed
internal.wilma.port=1234

#the size of the request buffer used by the web application in bytes
internal.wilma.request.buffer.size=81920
#the size of the response buffer used by the web application in bytes
internal.wilma.response.buffer.size=204800

# host used to communicate with the indexing application via an activemq broker, default is localhost
jms.queue.host=

# port used to communicate with the indexing application via an activemq broker
jms.queue.port=16161

# the value of the request time out in milliseconds
proxy.request.timeout=20000

# enable/disable response volatility (changing the proxy response on-the-fly), default: disable
proxy.response.volatile=false

# maintainer is executed periodically. Time period can be given with cron expression.
log.maintainer.cron=0 0/30 * * * *

# maintainer method can be one of the following: timelimit | filelimit
log.maintainer.method=timelimit

# limit on number of files to keep
log.maintainer.file.limit=10

# files older than this value are deleted if timelimit method is switched on (can be xD days or xH hours - e.g.: 12H, 2D)
log.maintainer.time.limit=1H

# target folder of the request, response log files
log.folder=messages

# guard period of the overload safeguard in seconds. 0 means that the safeguard is inactive, otherwise the time period can be given with cron expressions (e.g.: 0/3 * * * * *).
safeguard.guardperiod=0/3 * * * * *

# when the ActiveMQ queue size exceeds this limit, the FastInfoset decompression is turned off
safeguard.responseFIdecoder.OFFlimit=1200

# when the ActiveMQ queue size drops below this limit, the FastInfoset decompression is turned on
safeguard.responseFIdecoder.ONlimit=800

# when the ActiveMQ queue size exceeds this limit, response logging is turned off completely
safeguard.responseMessageWriter.OFFlimit=1500

# when the ActiveMQ queue size  drops below this limit, response logging is turned on again
safeguard.responseMessageWriter.ONlimit=1000

# turns message logging on/off when Wilma starts
message.logging=on

# should Wilma Message ID be added to the message request headers or not
message.marking=off

# Relative folder path of the stub descriptor XML configuration files from project root.
stub.descriptors.path=

# Extension pattern of the stub descriptor XML configuration files (it could be a specific file or *.xml)
stub.descriptors.pattern=stubConfig.xml

# Relative folder path of the cached stub descriptor XML configuration files from project root.
stub.descriptors.cache.path=config/cache/stub_descriptors

# Max depth of the stub configuration dialog descriptor elements (condition-set-invoker, template-formatter-set-invoker) child's subtree. This is necessary because of recursive self referring.
stub.descriptor.max.depth=20

# Relative path of the stub template files folder from project root.
stub.template.path=config/templates

# Relative path of the stub condition checker classes folder from project root.
stub.condition.checker.path=config/condition-checkers

# Relative path of the stub template formatter classes folder from project root.
stub.template.formatter.path=config/formatters

# Relative path of the stub interceptor classes folder from project root.
stub.interceptor.path=config/interceptors

# Relative path of the jar and its classes folder from project root.
stub.jar.path=config/jar

# Relative path of the sequence handler classes folder from project root.
stub.sequence.handler.path=config/sequencehandlers

# switch between the following operation modes: proxy mode, stub mode and normal mode (valid inputs are: stub, proxy, wilma)
switch=wilma

# Interceptors - switch between using or not using Interceptors at all (config still will be loaded)
interceptor=off

# Block localhost usage - switch between forwarding messages addressed to localhost (mode: off) or denying them (mode: on)
block.localhost.usage=off

# Sequence Handling - Switch between enabling/disabling the sequence handling functionality
sequence.handling.state=off

# Defines the interval of waiting for the sequence responses (in milliseconds)
sequence.response.wait.interval=500

# the default timeout of sequences given in milliseconds
sequence.timeout=9000

# the url of readme and the text of the readme url
wilma.readme.url=http://epam.github.io/Wilma/
wilma.readme.text=Wilma Documentation

# prefix text for Wilma instance
wilma.instance.prefix=

#Relative path to admin hosts file from project root.
#The admin hosts file should contain one hostname or IP per line.
wilma.admin.hosts.file=

# sequence cleaning is executed periodically. Time period can be given with cron expression.
sequence.cleanup.cron=0 0/03 * * * *

# The maximum value of displayed messages.
message.log.UI.maxsize=500

There are two reserved ports which aren't configurable, 1099 and 2015. Pay attention to not use them.

The communication among the modules and between Wilma and Wilma Message Search goes through ActiveMQQueues. The default port is 1099 to connect to that service which monitors the LoggerQueue and ResponseQueue in Wilma. Port 2015 is used by this service in the Wilma Message Search.

The hardcoded values are in these files:

  • com.epam.wilma.safeguard.monitor.JmsQueueMonitorTask
  • com.epam.message.search.web.controller.LoadInformationController
  • /wilma-message-search-lucene/src/main/resources/conf/spring/lucene-application-context.xml

Running Wilma

After the configuration is done, you can run Wilma by entering the following command:

java [-Dlogger=DEV]
     [-Xmx4096m]
     [-Djavax.net.ssl.keyStore=jks_holding_client_certificate]
     [-Djavax.net.ssl.keyStorePassword=password_of_jks]
     [-Dcom.sun.management.jmxremote.port=jmx_port -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false]
     -jar wilma-<version>.jar wilma.conf.properties
  • The VM argument -Dlogger=DEV is optional and can be used to log detailed more information on the console.
  • The VM argument -Xmx specifies the max heap space that Wilma can use. It is recommended to set it based on the measured memory usage that is in connection to the traffic load that goes through Wilma. It is recommended to use 4G as starting point, and increase/decrease it as the actual use requires.
  • The VM argument -Djavax.net.ssl.keyStore specifies the Java Key Store file that holds the client certificates that are needed for two-way SSL. 
  • The VM argument -Djavax.net.ssl.keyStorePassword is the password of the Java Key Store in the previous argument.
  • The VM arguments -Dcom.sun.management.jmxremote.XXX are used when you would like to attach to Wilma via Java JMX Console, for monitorig purposes.

Wilma application logs are normally stored in the /log folder.

The command above requires that the properties file is in the same folder as the JAR. If you place the configuration file to a different location, you should run the JAR by specifying the full path of the configuration file.

If the tool starts successfully, you should see something similar on the console:

13:50:28 - RMI: using port:1099
13:50:29 - Timelimit method is used to maintain log files with parameters: timelimit: 1H
13:50:29 - Wilma - Service Stub and Transparent Proxy - V2.0.458
Copyright since 2013, EPAM Systems - GNU GPL-V3.0 License
Used proxy port: 9092
Wilma UI is available via URL: http://localhost:1234/index/
Application logs are stored in 'c:\wilma\log' folder.
Request-response pairs are stored in 'c:\wilma\messages' folder.

Loading Stub Configs

Details about how the Stub is configured, can be found here....

At start up Wilma checks the cache folder (see parameter: stub.descriptors.cache.path) how many file looks like *_stubConfig.json where * means >0 integer value. If there is at least one file with this name pattern, Wilma will load these files in order. If there is not any such file, then Wilma try to load the stub configuration in the following steps.

  1. Checks whether stub.descriptors.pattern contains a specific file name without any *. If it contains, then Wilma looks for this file in that folder which is given stub.descriptors.path property. 
    If the given file does not exist in that folder, Wilma will shut down with an error message.
  2. If stub.descriptors.pattern contains a *, Wilma looks for those files in the stub.descriptors.path folder which matched with the given pattern. 
    This pattern must be like *something.json, *.json ...!
    Note: "some*thing.json" is a WRONG pattern, Wilma is not able to work with such pattern!

Using Wilma

After Wilma starts, you can use it as an HTTP and HTTPS proxy that logs every request and response that goes through it.

Configuring a Java client application to use Wilma as a proxy/stub

If you want to use Wilma as a proxy for a Java client application, you must configure it to go through Wilma.

The most simple way to do this is by adding a few VM arguments to the run configuration:

-Dhttp.proxyHost=[wilma-host]
-Dhttp.proxyPort=[wilma-port]
-Dhttps.proxyHost=[wilma-host]
-Dhttps.proxyPort=[wilma-port]
-Djavax.net.ssl.trustStore=[path/to/wilma.jks]
-Djavax.net.ssl.trustStorePassword=vvilma
  • [wilma-url] is the URL of the server where Wilma is running.
  • [wilma-port] is the port that is configured in wilma.conf.properties (proxy.port, default is 9092)
  • [path/to/wilma.jks] the path to the wilma.jks file (it can be found in wilma.zip under certificate/wilma.jks)

The first 4 arguments mean that the application should use a proxy on the given host and port (both for HTTP and for HTTPS connections), the third argument specifies a Java Key Store (JKS) file that contains the certificates trusted by the client application. Depending of the HTTP/S client used by your application, other parameters might also need to be set.

Wilma uses an unsigned certificate contained by wilma.jks to be able to proxy HTTPS connections too.

The client Java application has to be configured to accept this certificate to be able to access a host that uses SSL.

Configuring "run" task of Gradle to use Wilma as a proxy/stub

If you want to use Wilma as a proxy/stub for a Java application executed via `run` task of `application` Gradle plugin, just specify the same arguments as mentioned above in `applicationDefaultJvmArgs` parameter. See example below (for http protocol only):

...
applicationDefaultJvmArgs = ["-Dhttp.proxyHost=127.0.0.1", "-Dhttp.proxyPort=9092"]
...

Using Wilma Message Search

Detailed information on how to configure and use Wilma Message Search application can be found here.

Further information

Table Of Contents

©2021, EPAM Systems.