/monitor-analytics Webapplikation

Dieser Installationsschritt ist nur nötig, wenn auf Client-Seite Interaktionsdaten innerhalb von map.apps gesammelt werden sollen.

Für die Installation der Usagelog Webapp des service.monitor deployen Sie die ausgelieferte WAR-Datei monitor-analytics.war im gewünschten Servlet Container.

Anpassung der Konfiguration

Für Änderungen an der Standardkonfiguration müssen Sie die entsprechend Konfigurationsdateien anpassen. Folgende Konfigurationsdateien werden von service.monitor verarbeitet:

  • WEB-INF/classes/default-application.properties (NICHT EDITIEREN)
    In dieser Datei befinden sich alle Konfigurationsoptionen von map.apps mit ihren Standardwerten.

  • WEB-INF/classes/custom-application.properties
    Wenn eine Änderung des Arbeitsverzeichnisses (data.directory.location) oder Konfigurationsverzeichnisses (config.directory.location) nötig ist, muss die Änderung in dieser Datei erfolgen. Alle weiteren Anpassungen erfolgen in folgender Datei:

  • [config.directory.location]/application.properties
    Nehmen Sie Änderungen an der Konfiguration durch das Bearbeiten dieser Datei vor.
    Das Konfigurationsverzeichnis (config.directory.location) von map.apps ist in der Standardinstallation das Verzeichnis ${user.home}/.monitor. Die Datei wird nicht automatisch erstellt, daher kann als Vorlage die Datei WEB-INF/classes/config-templates/application.properties dienen. Belassen Sie nur die Einstellungen in der Datei, die geändert wurden oder solche, die auf Werte aus den secrets.properties verweisen.

  • [config.directory.location]/secrets.properties
    Legen Sie sensible Daten wie Passwörter oder API-Schlüssel in dieser Datei ab und verweisen Sie, wie im Beispiel beschrieben, auf diese in den application.properties.

Das Format der Konfigurationsdateien muss dem Java Properties Dateiformat entsprechen.

Starten Sie nach den Änderungen den Servlet Container neu oder aktualisieren Sie den Kontext.

Umgebungsvariablen

Sie können die Werte aller Konfigurationsparameter auch mit Umgebungsvariablen setzen. Diese überschreiben immer die Werte, aus den Konfigurationsdateien. Das ist hilfreich, wenn {product-name} zum Beispiel in einem Docker-Container betrieben wird.

Sie müssen die Namen der Konfigurationsparameter aus den Konfigurationsdateien für die Verwendung als Umgebungsvariablen anpassen: Ersetzen Sie alle Buchstaben des Namen durch Großbuchstaben sowie den Punkt . durch den Unterstrich _.

Beispiel: security.oauth.provider wird zu SECURITY_OAUTH_PROVIDER. Dieses Muster gilt für alle Konfigurationsparameter.

Konfiguration von Passwörtern bzw. Geheimnissen

Sensible Daten wie Passwörter oder API-Schlüssel, sollten in der Datei secrets.properties in der Form secretKey=value gespeichert werden. Im Gegensatz zu früheren Softwareversionen werden keine Standard-Passwörter mehr vorgegeben. Alle benötigten Passwörter müssen bei der Installation selbst gesetzt werden. Die Passwortkodierung ist standardmäßig auf SHA-512 festgelegt und kann über die Property security.user.pwenc angepasst werden. Definieren Sie hier beispielsweise das Passwort für den Administrationszugang wie folgt:

secrets.properties
# Passwort für Administrationszugang
secret.admin.pw=mySecretValue

Den Eintrag referenzieren Sie dann in der application.properties Datei:

application.properties
# Referenz auf Eintrag in secrets.properties
security.user.admin.pw=${secret.admin.pw}

Durch die separate Speicherung der Geheimnisse in der Datei secrets.properties wird verhindert, dass man mit dem Wissen über die Konfiguration der Anwendung gleichzeitig Kenntnis über konfigurierte Geheimnisse erhält.

Sichern Sie die Datei secrets.properties durch die Vergabe passender Zugriffsberechtigungen ab und verschlüsseln diese bei Bedarf mit den Mitteln des Betriebssystems.

In dynamischen Deployment Szenarien, wie beispielsweise dem Betrieb in einem Docker-Container, kann die Datei secrets.properties auch generiert oder extern verwaltet werden.

Konfiguration

Elastic Ingest Pipeline

Die /monitor-analytics Webapplikation nutzt per default die Elastic Ingest Pipeline, um die clientseitigen Interaktionsdaten von map.apps zu verarbeiten und an Elasticsearch weiterzuleiten. Die folgende application.properties Konfiguration definiert die Verbindung zu Elasticsearch:

application.properties
analytics.elastic.url=https://elasticsearch.example.com
analytics.elastic.username=elastic
analytics.elastic.password=${secret.monitoring.elastic.password}

Logging Interface Zugriff

Sie können den Zugriff auf den Endpunkt /usage/log zum Schreiben vom Logdaten einschränken. Definieren Sie hierfür Hostnamen, für die das Schreiben explizit erlaubt werden kann. Die Hostnamen werden gegen den HTTP Header Wert Referer geprüft. Referrer-Werte enthalten normalerweise die URL der Webseite, die die aktuelle Anfrage sendet.

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

Der Standardwert erlaubt das Senden und Speichern von Information über /usage/log von überall her.

Beispiel

Bei folgender Einstellung gelten die unten stehenden Einschränkungen.

application.properties
analytics.usagelog.referers=example.com,https://www.example.net

Der Endpunkt erlaubt Anfragen von Seiten, die z.B. folgende HTTP-Header-Werte vorweisen:

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

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

  • https://www.example.net/client.aspx

Nicht erlauben oder speichern würde der Endpunkt Anfragen mit solchen Referrer-Werten:

  • http://www.example.net/client.aspx, weil der Wert explizit das HTTPS-Protokoll definiert.

  • http://www.example.org/some-page.html, weil der Wert überhaupt nicht in der Liste auftaucht.

Übersicht aller Standardwerte

Die Datei \monitor-analytics\WEB-INF\classes\default-application.properties bietet eine Übersicht aller Standardwerte der genutzten Eigenschaften.

Der Standardwert für [data.directory.location] ist $\{user.home\}/.monitor.

Wird der Tomcat Server als Windows-Service ausgeführt, so entspricht dieser Ordner dem ausführenden Benutzer des Dienstes. Wenn kein Nutzer konfiguriert ist, wird der Tomcat Server durch den System-Benutzer Account ausgeführt (nicht empfohlen!). In diesem Fall können Sie das .monitor Verzeichnis unter dem Pfad C:\Windows\System32\config\systemprofile\.monitor finden.

Falls Sie ein spezielles Verzeichnis für die Speicherung der service.monitor Daten nutzen wollen, so passen Sie den Pfad in \monitor-analytics\WEB-INF\classes\custom-application.properties der Webapp des Tomcats an.
Linux

Bei der Installation von service.monitor unter Linux Systemen müssen Sie den folgenden Parameter in der Konfigurationsdatei \monitor-analytics\WEB-INF\classes\custom-application.properties anpassen:

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

zu beispielsweise:

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