/monitor-analytics web application

This installation step is only necessary if interaction data is to be collected within map.apps on the client side.

To install the webapp of service.monitor deploy the given WAR file from monitor-analytics.war to the Servlet Container that shall be used.

To change the default configuration values,

  1. copy the file \monitor-analytics\WEB-INF\classes\custom-application.properties to [data.directory.location]/application.properties,

  2. change the necessary values and

  3. restart the Servlet Container or reload the context.

Configuration

Logstash - Send interation data

If the Logstash service is installed on a different host than localhost, configure it in the application.properties and connect it to the Logstash service.

application.properties
analytics.gelf.server=myserver.domain.de
analytics.gelf.port=12201

It is also possible to change the port, on which outgoing log messages are send. If you change the port in the application.properties file, change the listening port in the Logstash configuration at /resources/analytics/elasticsearch/logstash/pipelines/ct-analytics/logstash-analytics-100-input.conf to open the port to receive messages.

After any configuration changes, restart the related component.

Restrict log endpoint access

It may be desired to restrict access to the /usage/log endpoint for persisting data. This can be done by setting up a list of allowed host names. Those host names will be tested against the HTTP Header value Referer. The referrer value typically contains the url of the web page sending the request.

default-application.properties
analytics.usagelog.referers=*

The default setting allows for sending /usage/log requests from anywhere.

Example

With the following setting, the restrictions below apply.

application.properties
analytics.usagelog.referers=mydomain.com,https://www.myotherdomain.eu

The endpoint allows requests from pages that have, for example, the following HTTP header values:

  • http://mydomain.com/application/index.html

  • https://mydomain.com/webapp/somePage.jsp

  • https://www.myotherdomain.eu/client.aspx

The endpoint would not allow or store requests with such referrer values:

  • http://www.myotherdomain.eu/client.aspx because the setting explicitly points to https protocol.

  • http://www.conterra.de/some-page.html because the URL is not listed in the property.

Elasticsearch - Query collected data

Changes to the application.properties are necessary, for example, if Elasticsearch runs on another host than http://localhost:9200. In this case, the service URL has to be configured to connect the webapp with Elasticsearch. Also, if Elastic requires username and password for access, credentials can be configured here.

application.properties
analytics.elasticsearch.service.url=http://myserver:9200/analytics-*/_search
analytics.elasticsearch.service.user=<user>
analytics.elasticsearch.service.pwd=<password>

service.monitor Usage Log webapp provides a security layer to secure queries against the Elasticsearch indices. To protect the loggend data against unwanted access, it is HIGHLY RECOMMENDED to change the properties.

  • security.user.admin.name

  • security.user.admin.pw

Use a hash algorithm to encrypt it by setting the property security.user.pwenc to one of MD5, SHA-1, SHA-256, SHA-384 or SHA-512.

Note, that security.user.admin.pw then stores the encrypted password, e.g

security.user.pwenc=SHA-256
security.user.admin.pw=b18474123c790f30c300b6bb9ee146a4959b6bcd5eef20244b925d69ea996690

Access to data

There are several levels of security available when it comes to protection of the collected data. It is not recommend making the search index publicly accessible. Access should be restricted to authorized persons only.

Therefore, the product allows configuring three different modes of authentication:

NONE

Access to collected data is completely unrestricted.

INTEGRATED

Access to collected data is granted for authorized users only.

Authentication happens via http/BASIC auth. There is one single user available.

Its credentials are configurable via application.properties:

security.mode=INTEGRATED
security.user.admin.name=
security.user.admin.pw=
ONLY_AUTHN

Access to collected data is granted for authorized users only.

Authentication happens via security.manager and its SSO Domain Cookie support. This allows for a seamless SSO Experience. Necessary configuration properties are available via application.properties, please refer to your security.manager or map.apps configuration:

security.mode=ONLY_AUTHN
security.sso.cookie.name=ct_SSO
security.sso.cookie.domain=
security.sso.cookie.bindToIP=false

# security.manager service locations
security.administration.url=http://<host>/administration
security.was.service.url=$\{security.administration.url\}/WAS
security.sso.service.url=$\{security.administration.url\}/resources/ssosessions
security.sso.token.service.url=$\{security.administration.url\}/token/ssosession


# Key Store Properties
security.keystore.location=<some path>
security.keystore.passwd=changeit
security.keystore.key.alias=ct-security
security.keystore.key.passwd=changeit
Access is granted, if authenticated user owns the role mon_Redakteur. The name of the role can be defined in application.properties via servicemonitor.admin.role.

Overview of all default values

See \monitor-analytics\WEB-INF\classes\default-application.properties for an overview of the default values of the used properties.

The default value for [data.directory.location] is $\{user.home\}/.monitor.

In case the Tomcat server is operated as a windows service this folder corresponds to the user that executes the Tomcat service. If no such user is configured the Tomcat server runs under the system user’s account (not recommended!). In this case the .monitor folder is to be found under path C:\Windows\System32\config\systemprofile\.monitor.

If a custom folder should be used to store Analytics data, define this path in \monitor-analytics\WEB-INF\classes\custom-application.properties inside the webapp on the Tomcat.
Linux

When installing service.monitor on Linux systems, you have to change the following parameter in configuration file \monitor-analytics\WEB-INF\classes\custom-application.properties:

data.directory.location=$\{user.home\}/.monitor

to e.g.

data.directory.location=/opt/data/.monitor