H5.2 - REST Service - Configuration

Basic configuration

Windows

The Windows Service runs the Java component via matchITHubService.bat, which can be found in the "service" subfolder of the matchIT Hub Service installation directory. For example:

set JAVA="C:\Program Files\Java\jdk8\bin\java.exe"
%JAVA% -jar .\matchITHubService.jar localhost:8080

The installer will configure the Java path and prompt for the host setting (see host below for more details).

As an alternative to running the Windows Service, you can run matchITHubService.bat from a command prompt. This can be useful to see debug output to the console.

Linux

The Linux package includes both 32-bit and 64-bit versions of the service in the subfolders: "service/x86" & "service/x64". These folders contain a shell script, matchITHubService.sh, for running the service. For example:

JDK=/opt/java64/jdk8/bin

${JDK}/java -Djava.library.path=./:/libstdc++ -jar ./matchITHubService.jar 192.168.40.52:8080

The default host and port that the service listens on is localhost:8080 you can override this default by specifying host and port on the command line as shown in the example above (see host below for more details).

There is also an example script for running the service as a daemon:

nohup ./matchITHubService.sh >./matchITHubService.log 2>&1 &

To stop the service send the following http delete command:

curl -X DELETE http://localhost:8080/matchITHub

Status

You can check the status of a sevice by opening this URL in a web browser: http://localhost:8080/matchITHub/status

E.g.

Advanced configuration

Advanced configuration options can be controlled via an xml configuration file. To use a configuration file, specify "-config=<filename>", e.g.

java -jar ./matchITHubService.jar -config=myconfig.xml

Here's an example configuration for the matchIT Hub Service:

<?xml version="1.0" encoding="UTF-8"?>
<config>
<service>
<host>https://localhost:8080</host>
<keystoreLocation>keystore.jks</keystoreLocation>
<keystorePassword>password</keystorePassword>

<authenticate>true</authenticate>
<credentialLocation>pass.enc</credentialLocation>
<compressionMinSize>1048576</compressionMinSize>
</service>
</config>

host

You can configure host and port either via a parameter on the command line, or via the host setting in the config file. You will probably want to change localhost to the ip address or host name of the machine if you intend to access the service across the network. You can also change the port if the default port of 8080 is already in use or otherwise unsuitable on your system.

The default protocol is http, to use https you can specify this as part of the host setting, e.g. "https://192.168.40.52:8080". If you specify https you also need to configure keystoreLocation and keystorePassword.

keystoreLocation & keystorePassword

To use https (HTTP over SSL) you need an SSL Certificate and keystore repository to store it in.

You create a keystore file and a keystore password while you generate an SSL Certificate, i.e.

keytool -genkeypair -alias "alias" -keyalg RSA -keystore keystore-location -storepass keystore-password

To create a self-signed certificate:

keytool -export -alias "alias" -rfc -keystore keystore-location > certificate-location

If you want to use a Certificate signed by a Certifying Authority, refer to Oracle's documentation for "Creating a Keystore File and Keystore Password for HTTPS Connections", and follow the procedure to submit the Certificate to the Certifying Authority to be signed.

authenticate and credentialLocation

User authentication can be optionally enabled if using the https protocol.  To enable this, the authenticate setting should be set to True.

User credentials added to the service are stored in an encrypted file.  The pathname of this file is specified with the credentialLocation setting and defaults to pass.enc.  Details about user authentication are here.

compressionMinSize

The /matchITHub/engines/<engine>/results method returns a text/plain block of records. By default the data is not compressed, specify a compressionMinSize other than 0 to cause results packets over the specified size to be compressed using gzip.