The core parameters of MigratoryData KE are described below.

LicenseKey

   
Description A string representing the license key
Default value No default value
Required parameter Required

The license key consists of a sequence of numbers and letters. The license keys are issued by MigratoryData either for evaluation, development, or production usage of MigratoryData KE. To obtain a license key, please contact MigratoryData at support@migratorydata.com.

Memory

   
Description Specify the maximum memory to be used by MigratoryData KE
Default value No default value
Required parameter Required

The memory size defined by this parameter can be expressed in bytes. Also, it can be expressed in gigabytes, megabytes, and kilobytes by using the following postfixes: GB for gigabytes, MB for megabytes, or KB for kilobytes.

For example, to allocate 512 megabytes for MigratoryData KE, configure the parameter Memory as follows:

Memory = 512 MB

In a production environment is is recommended to use at least 8 GB or more depending on the load of data on the server and how much simultaneous clients will be connected.

Listen

   
Description A comma separated list of addresses to listen for client connections
Default value No default value
Required parameter Optional

The format of each address of the list defined by this parameter is either IP Address:Port or DNS Name:Port.

For example, to listen for clients on the port 80 of the address 192.168.1.1, use 192.168.1.1:80. Likewise, to listen for clients on the port 8800 of the address push.example.com, use push.example.com:8800. IPv6 addresses must be enclosed in square brackets as follows [2001:db8::a00:20ff:fea7:ccea]:80.

If you specify an address without a port, the default port 80 will be used.

By specifying an IP address, MigratoryData KE will bind only to that IP address. The wildcard address (*) will enable MigratoryData KE to bind to all available IP addresses of the machine.

If MigratoryData KE is installed on a machine that has a firewall enabled, then you will need to allow in the firewall rules the access to the addresses and ports configured by this parameter.

ListenEncrypted

   
Description A list of addresses to listen for encrypted client connections
Default value No default value
Required parameter Optional

The same conventions applies as for the Listen parameter, except the fact that if you specify an address without a port, the default port 443 will be used.

In a production deployment, it is recommend to use encrypted client connections. In addition to the fact that data will be securely delivered to clients, there is another advantage. Some security solutions consider HTTP streaming as a non-standard HTTP access and may block streaming to the client having installed such a security solution. By deploying MigratoryData KE with encrypted client connections, the security solutions cannot inspect the content of the HTTP messages so that streaming cannot be blocked.

KeyStore

   
Description A Java KeyStore (JKS) file with security certificates
Default value No default value
Required parameter Required if at least one of the following is true:
- ListenEncrypted is configured
- MonitorJMX.Encryption is configured on true
- MonitorHTTP.Encryption is configured on true

The keystore file must be configured using absolute paths. For example:

   
KeyStore = /some/path/mykeystore.jks For Linux/Unix
KeyStore = C:/some/path/mykeystore.jks For Windows

The keystore must contain a SSL certificate for each address used in the configuration of the following parameters:

   
ListenEncrypted
MonitorJMX.Listen provided that MonitorJMX.Encryption is set on true
MonitorHTTP.Listen provided that MonitorHTTP.Encryption is set on true

How to add a certificate to the keystore

Suppose the following DNS address push.example.com resolves to the IP address 192.168.1.1, and vice-versa, the IP address 192.168.1.1 resolves to the DNS address push.example.com.

If an address appears in the configuration of any of the parameters used to define encrypted connections, then the keystore file must contain an SSL certificate for that address. If the address is specified by its DNS name, say push.example.com, then its certificate entry in the keystore must have as alias the string push.example.com. If the address is specified by its IP address, say 192.168.1.1, then its certificate entry in the keystore must have as alias the string 192.168.1.1.

To create a certificate for an address in the keystore, there are two possibilities: either use a self-signed certificate for that address or use a certificate signed by a Certificate Authority (CA).

Self-signed certificates can be used for development. In a production environment always use certificates signed by a Certificate Authority.

In the next two subsections we assume that the keystore file is named mykeystore.jks and the address for which a certificate should be added in the keystore is specified either by DNS name as push.example.com or by IP address as 192.168.1.1.

Adding a self-signed certificate to the keystore

Run one of following depending on how the address was specified in the configuration file:

   
Certificate for DNS name keytool -genkeypair \
-dname "CN=push.example.com" \
-alias push.example.com \
-keyalg RSA -validity 3600 \
-keystore mykeystore.jks
Certificate for IP address keytool -genkeypair \
-dname "CN=192.168.1.1" \
-alias 192.168.1.1 \
-keyalg RSA -validity 3600 \
-keystore mykeystore.jks
Certificate for JMX monitoring       keytool -genkeypair \
-dname "CN=jmx" \
-alias jmx \
-keyalg RSA -validity 3600 \
-keystore mykeystore.jks

You will be asked to set a password for the keystore if the file mykeystore.jks does not exist, or to enter the keystore password if the keystore file already exists and contains other certificate entries. This password must be used to configure the parameter KeyStorePassword.

Adding a CA-signed certificate to the keystore

Suppose you obtained the following signed certificate file push.example.com.crt from a Certificate Authority for the domain push.example.com and suppose push.example.com.key is the file containing its corresponding private key.

In order to add this CA-signed certificate to the keystore, follow these steps:

  1. If the Certificate Authority provided you an intermediate certificate in addition to the signed certificate push.example.com.crt, then you will have to chain your signed certificate with the intermediary certificate. If you have not received an intermediary certificate, then just skip this step.

    To chain your signed certificate push.example.com.crt with the intermediary certificate, you should first append to your signed certificate the intermediary certificate, say intermediary.crt. Then append the certificate signing request that you sent to the CA authority, say push.example.com.csr. On Linux, use the command:

    cat intermediary.crt push.example.com.csr >> push.example.com.crt
    

    On Windows, use the command:

    type intermediary.crt push.example.com.csr >> push.example.com.crt
    
  2. Convert the CA-signed certificate to the pkcs#12 as follows:

    openssl pkcs12 -export \
    -in push.example.com.crt \
    -inkey push.example.com.key \
    -out push.example.com.pkcs12
    

    This will produce the file push.example.com.pkcs12. The password for the this new file must be the same like that used for the keystore.

  3. Add the pkcs#12 certificate obtained in the previous step to the keystore as follows:

    keytool -importkeystore \
    -srckeystore push.example.com.pkcs12 \
    -srcstoretype PKCS12 \
    -deststoretype JKS \
    -destkeystore mykeystore.jks
    

    This will insert a new entry to the keystore file mykeystore.jks with the default alias 1.

  4. Rename the default certificate alias 1 of the keystore by entering one of following commands depending on how you specified the address in the configuration file:

   
Certificate for DNS name keytool -v -keystore mykeystore.jks \
-changealias -alias 1 -destalias push.example.com
Certificate for IP address keytool -v -keystore mykeystore.jks \
-changealias -alias 1 -destalias 192.168.1.1
Certificate for JMX monitoring       keytool -v -keystore mykeystore.jks \
-changealias -alias 1 -destalias jmx

KeyStorePassword

   
Description The password to access the keystore
Default value No default value
Required parameter       Required if the parameter KeyStore is configured

Configure this parameter with the password defined when you created the keystore file. The keystore file is created when adding the first certificate entry to it as explained in the description of the KeyStore parameter.

Monitor

   
Description A list of monitoring options
Default value No default value
Required parameter       Optional

The currently available monitoring options are JMX, HTTP, and Prometheus. Use comma separated values to configure multiple monitoring options. For example, to configure JMX and Prometheus, use the following configuration:

Monitor = JMX, Prometheus
Prometheus monitoring is usually combined with Grafana dashboarding. Please check out the article Monitoring MigratoryData with Prometheus and Grafana for more information.

MonitorUsername

   
Description Monitoring user name
Default value admin
Required parameter       Required if at least one of the following is true:
- MonitorJMX.Authentication is configured on true
- MonitorHTTP.Authentication is configured on true
- MonitorPrometheus.Authentication is configured on true

MonitorPassword

   
Description Monitoring password
Default value pass
Required parameter       Required if at least one of the following is true:
- MonitorJMX.Authentication is configured on true
- MonitorHTTP.Authentication is configured on true
- MonitorPrometheus.Authentication is configured on true

MonitorJMX.Listen

   
Description Address to listen for JMX monitoring clients
Default value No default value
Required parameter Optional

The format of the address used by this parameter is the same like the format of the Listen parameter.

In order to access the JMX monitoring from a remote machine, please check your firewall settings so that the network traffic from the remote machine is allowed to the address configured by this parameter.

The jconsole utility that is freely available with OpenJDK can be used for JMX monitoring. Also, there are many commercial tools for JMX that provide enhanced functionality like dashboards and database persistence that can be used.

The `jconsole` utility has a known issue when connecting remotely to a JMX service running on Linux. To avoid this issue, execute the following command on the Linux machine where MigratoryData KE runs:
hostname -i

The command above should return the address used in the configuration of the parameter MonitorJMX.Listen. If it reports a local address like 127.0.0.1, then jconsole would not be able to connect remotely to the JMX monitoring service of MigratoryData KE. To fix this issue, edit /etc/hosts so that hostname resolves to the address used by MonitorJMX.Listen.

To access the JMX service of MigratoryData KE running on AWS EC2, please also refer to the note of the section MIGRATORYDATA_JAVA_EXTRA_OPTS.

MonitorJMX.Authentication

   
Description Specify whether or not to use authentication for JMX monitoring
Default value No default value
Required parameter Optional

This parameter can have two values: true or false. If set on true, then, in order to access the JMX monitoring, you should use the monitoring user name specified with the MonitorUsername parameter and the monitoring password specified with the MonitorPassword parameter.

MonitorJMX.Encryption

   
Description Specify whether or not to use encryption for JMX monitoring
Default value No default value
Required parameter Optional

This parameter can have two values: true or false. If set on true, then a JMX client will connect to the JMX monitoring through a SSL/TLS encrypted connection. The use of an encrypted connection is especially recommended for JMX remote monitoring from an insecure network, including Internet.

If this parameter is set on true, then the address used by the parameter MonitorJMX.Listen must have a certificate entry in the keystore file defined by the parameter KeyStore. The certificate entry of the keystore must be created with the alias jmx as explained in the description of the KeyStore parameter.

Secure JMX monitoring over insecure networks

In this subsection it is assumed that the JMX client is jconsole. For other JMX clients you can also use the steps below, but you may have to adapt the configuration to suit your specific JMX client.

Supposing the file name of the keystore defined by the KeyStore parameter is mykeystore.jks, and supposing the keystore mykeystore.jks includes an certificate entry for the address used in the configuration of the parameter MonitorJMX.Listen having as alias jmx. Then, use the following steps to establish a secure JMX connection:

  1. Create a truststore for the JMX client. The truststore is a special keystore that can verify the trusted SSL certificates. The trustsore will be used by the JMX client. Supposing that the file name used for the truststore is mytruststore.jks, run the following two commands to create the truststore:

    keytool -export \
    -alias jmx \
    -keystore mykeystore.jks \
    -rfc -file temp.cer
    
    keytool -import \
    -alias jmx \
    -file temp.cer \
    -keystore mytruststore.jks
    

    For the first command, use the password of the keystore as defined by the KeyStorePassword parameter. For the second command, use a new password, say mytruststore-password.

  2. Generate a new keystore for the JMX client having a certificate entry with the alias jmx as follows:

    keytool -genkeypair \
    -alias jmx \
    -keyalg RSA \
    -validity 3600 \
    -keystore clientkeystore.jks
    

    where clientkeystore.jsk is the name of the new keystore. For this command, use a new password, say clientkeystore-password.

  3. To securely connect to the JMX monitoring service of MigratoryData KE, execute the following command:

    jconsole \
    -J-Djavax.net.ssl.keyStore=clientkeystore.jks \
    -J-Djavax.net.ssl.keyStorePassword=clientkeystore-password \
    -J-Djavax.net.ssl.trustStore=mystruststore.jks \
    -J-Djavax.net.ssl.trustStorePassword=mytruststore-password
    

MonitorHTTP.Listen

   
Description Address to listen for HTTP monitoring clients
Default value No default value
Required parameter Optional

The format of the address used by this parameter is the same like the format of the Listen parameter.

In order to access the HTTP monitoring from a remote machine, please check your firewall settings so that the network traffic from the remote machine is allowed to the address configured by this parameter.

Accessing the HTTP Monitoring Service

Supposing you have the following monitoring related configuration:

Monitor = HTTP
MonitorUsername = admin
MonitorPassword = pass
MonitorHTTP.Listen = push.example.com:4000
MonitorHTTP.Authentication = true
MonitorHTTP.Encryption = false

Then you can access the HTTP monitoring using the following URL:

http://push.example.com:4000/stats?username=admin&password=pass

Opening the URL above will produce an output with the following format:

<fieldname1>:<value1> <fieldname2>:<value2> ... <fieldnameN>:<valueN>

where each field correspond to one of the following stats:

  • Average
  • Standard Deviation
  • Maximum

applied to one of the following metrics:

  • The number of connected clients
  • The number of connections per second
  • The number of disconnections per second
  • The number of incoming messages per second received from publishers
  • The number of outgoing messages per second sent to clients
  • The number of incoming bytes per second received from publishers
  • The number of outgoing bytes per second sent to clients

for one of the following period of time:

  • Current
  • Since startup
  • Last minute, last 5 minutes, and last 15 minutes
  • Last hour, last 5 hours, and last 15 hours
  • Last day, last 5 days, and last 15 days
  • Last month, last 5 months, and last 15 months

XML and JSON Output Format

You can also retrieve data in XML and JSON format. Append a view parameter to the URL above with the value xml or json. For example, to retrieve the monitoring data in XML format use:

http://push.example.com:4000/stats?username=admin&password=pass&view=xml

Filters

You can filter the monitoring data by indicator and/or stats and/or period of time. To do so, add to the URL above one or more of the GET parameters listed in filters table below.

For example, to retrieve the maximum number of concurrent clients in the last 15 minutes, use:

http://push.example.com:4000/stats?username=admin&password=pass&indicator=ConnectedSessions&statistic=MAX&period=Last.15.Minute

Another example. To retrieve the average for all indicators for all available periods of time, use:

http://push.example.com:4000/stats?username=admin&password=pass&statistic=AVG
Parameter Possible Value Description
indicator ConnectedSessions Number of connected clients
InBytesPerSecond Number of incoming bytes/second
InPublishMessagesPerSecond Number of incoming messages/second
OutBytesPerSecond Number of outgoing bytes/second
OutPublishMessagesPerSecond Number of outgoing messages/second
SessionConnectionsPerSecond Number of connections/second
SessionDisconnectionsPerSecond Number of disconnections/second
statistic AVG Average
STDEV Standard Deviation
MAX Maximum
period Current Current
Last.1.Minute Last 1 minute
Last.5.Minute Last 5 minutes
Last.15.Minute Last 15 minutes
Last.1.Hour Last 1 hour
Last.5.Hour Last 5 hours
Last.15.Hour Last 15 hours
Last.1.Day Last 1 day
Last.5.Day Last 5 days
Last.15.Day Last 15 days
Last.1.Month Last 1 month
Last.5.Month Last 5 months
Last.15.Month Last 15 months
SinceStartup Since startup

Secure HTTP monitoring over insecure networks

To securely monitor MigratoryData KE over an insecure network such as Internet, configure

MonitorHTTP.Encryption = true

See the description of the MonitorHTTP.Encryption parameter for more details, then access the HTTP monitoring service using over https as follows:

https://push.example.com:4000/stats?username=user&password=pass

MonitorHTTP.Authentication

   
Description Specify whether or not to use authentication for HTTP monitoring
Default value No default value
Required parameter Optional

This parameter can have two values: true or false. If set on true then, in order to access the HTTP monitoring, you should use the monitoring user name specified with the MonitorUsername parameter and the monitoring password specified with the MonitorPassword parameter.

MonitorHTTP.Encryption

   
Description Specify whether or not to use encryption for HTTP monitoring
Default value No default value
Required parameter Optional

This parameter can have two values: true or false. If set on true, then an HTTP client will connect to the HTTP monitoring through a SSL/TLS encrypted connection. The use of an encrypted connection is especially recommended for HTTP remote monitoring from an insecure network, including Internet.

If this parameter is set on true, then the address used by the parameter MonitorHTTP.Listen must have a certificate entry in the keystore file defined by the parameter KeyStore.

MonitorPrometheus.Listen

   
Description Address to listen for Prometheus monitoring clients
Default value No default value
Required parameter Optional

The format of the address used by this parameter is the same like the format of the Listen parameter.

In order to access the Prometheus monitoring from a remote machine, please check your firewall settings so that the network traffic from the remote machine is allowed to the address configured by this parameter.

MonitorPrometheus.Authentication

   
Description Specify whether or not to use authentication for Prometheus monitoring
Default value No default value
Required parameter Optional

This parameter can have two values: true or false. If set on true, then, in order to access the Prometheus monitoring, you should use the monitoring user name specified with the MonitorUsername parameter and the monitoring password specified with the MonitorPassword parameter.

MonitorPrometheus.Encryption

   
Description Specify whether or not to use encryption for Prometheus monitoring
Default value No default value
Required parameter Optional

This parameter can have two values: true or false. If set on true, then a Prometheus client will connect to the Prometheus monitoring through a SSL/TLS encrypted connection. The use of an encrypted connection is especially recommended for Prometheus remote monitoring from an insecure network, including Internet.

If this parameter is set on true, then the address used by the parameter MonitorPrometheus.Listen must have a certificate entry in the keystore file defined by the parameter KeyStore. The certificate entry of the keystore must be created with the alias prometheus as explained in the description of the KeyStore parameter.

LogFolder

   
Description The folder where the logs will be written
Default value logs
Required parameter Optional

If not configured, MigratoryData KE will use the default folder logs relative to the directory path used to start MigratoryData Server.

The log folder can be configured using absolute paths as follows:

   
LogFolder = /some/path/mylogs For Linux/Unix
LogFolder = C:/some/path/mylogs For Windows

LogLevel

   
Description The verbosity level of the logs
Default value INFO
Required parameter Optional

The following levels are available:

  • TRACE (most verbose)
  • DEBUG
  • INFO (recommended for production use)
  • WARN
  • ERROR (least verbose)

LogRotateLimit

   
Description The maximum size of a log file
Default value 10 MB
Required parameter Optional

The value of this parameter can be expressed in gigabytes, megabytes, and kilobytes by using the following postfixes: GB for gigabytes, MB for megabytes, or KB for kilobytes.

If the log file reaches the size provided by this parameter, then MigratoryData KE will automatically create a new log file. The previous log files are preserved on disk up to the number of log files defined by the LogRotateFileCount parameter.

LogRotateTime

   
Description The period of time at which a new log file will be created
Default value No default value
Required parameter Optional

The value of this parameter can be expressed in expressed in minutes (m), hours (h), days (D), weeks (W), months (M), or years (Y).

For example, in order to record the logs in a separate file every day use:

LogRotateTime = 1 D

To record the logs in separate file every 4 hours use:

LogRotateTime = 4 h

The previous log files are preserved on disk up to the number of log files defined by the LogRotateFileCount parameter.

This parameter takes precedence over the parameter LogRotateLimit. Therefore, if this parameter is configured, then the parameter LogRotateLimit is ignored.

LogRotateFileCount

   
Description Limit the number of historical log files created by log rotation
Default value 100
Required parameter Optional

If the number of log files produced by log rotation defined by the parameters LogRotateTime or LogRotateLimit reaches the value of this parameter, then the oldest log file is removed whenever a new log file is created such that the total number of logs files will not exceed the value of this parameter.

DocumentRoot

   
Description Set the folder from which MigratoryData KE will serve files
Default value html
Required parameter Optional

This parameter is optional. If not supplied, the default folder html relative to the directory path used to start the MigratoryData KE is used.

MigratoryData KE has a limited capability to serve files. This feature is only offered to facilitate the development process. MigratoryData KE is designed exclusively for real-time messaging.

Thus, for any production deployment, this parameter should be disabled, and a regular web server such as Nginx or Apache should be used for serving files such as web pages and images.

Entitlement

   
Description Specify the entitlement type
Default value Basic
Required parameter Optional

To define which users of your application have access to which subjects, you can define one of the following Entitlement types:

  • None allows any client to subscribe to and publish on any subject.
  • Basic allows any client to subscribe to any subject. However, publication is allowed only from the clients which authenticate with the token defined by the parameter EntitlementAllowToken.
  • Custom allows you to define your own entitlement rules. You can use the MigratoryData Extension SDK for Authorizaion to build an extension plugin for MigratoryData KE to allow or deny certain users to subscribe to or publish on certain subjects.

EntitlementAllowToken

   
Description Specify an entitlement token
Default value No default value
Required parameter Required if Entitlement is set on Basic

This parameter applies only if you configure the Entitlement parameter as Basic. See the semantics of this entitlement token in the definition of the entitlement type Basic in the description of the parameter Entitlement.