From 7f39aaa3d8633e9f05d2570c756e5e1fcac9b017 Mon Sep 17 00:00:00 2001 From: Thomas Lenz Date: Mon, 20 Dec 2021 08:16:01 +0100 Subject: switch from log4j to logback --- id/server/doc/handbook/install/install.html | 144 ++++++++++++++-------------- 1 file changed, 71 insertions(+), 73 deletions(-) (limited to 'id/server/doc') diff --git a/id/server/doc/handbook/install/install.html b/id/server/doc/handbook/install/install.html index bcd802b75..4f9214cbd 100644 --- a/id/server/doc/handbook/install/install.html +++ b/id/server/doc/handbook/install/install.html @@ -7,7 +7,7 @@ - +
@@ -16,65 +16,65 @@
-

Installation

+

Installation

Inhalt

-
    -
  1. -

    MOA-ID-Auth und MOA-ID-Configuration

    -
      -
    1. Basisinstallation -
        -
      1. Einführung
        2. -
      2. Installation -
          -
        1. Vorbereitung
          2. -
        2. Konfiguration von Apache Tomcat -
            -
          1. Konfiguration des HTTP Connectors
            2. -
          2. Konfiguration des HTTPS Connectors
            3. -
          -
          3. +
            +
          1. +

            MOA-ID-Auth und MOA-ID-Configuration

            +
              +
            1. Basisinstallation +
                +
              1. Einführung
                2. +
              2. Installation +
                  +
                1. Vorbereitung
                  2. +
                2. Konfiguration von Apache Tomcat +
                    +
                  1. Konfiguration des HTTP Connectors
                    2. +
                  2. Konfiguration des HTTPS Connectors
                    3. +
                  +
                3. Einsatz des Moduls MOA-ID-Auth in Tomcat
                  4. -
                4. Einsatz des Moduls MOA-ID-Configuration in Tomcat
                  5. -
                5. Starten und Stoppen von Tomcat -
                    -
                  1. Unter Windows
                    2. -
                  2. Unter Unix
                    3. -
                  3. Prüfen des erfolgreichen Starts
                    4. -
                  -
                  6. -
                6. Änderung der Konfiguration im laufenden Betrieb
                  7. -
                -
                3. -
              3. Logging -
                  -
                1. Format der Log-Meldungen
                  2. -
                2. Wichtige Log-Meldungen
                  3. -
                -
                4. -
              -
              2. -
            2. Erweiterungsmöglichkeiten
                -
              1. Vorgeschalteter Webserver
                  -
                1. Microsoft Internet Information Server (MS IIS)
                    -
                  1. Konfiguration von mod_jk im MS IIS
                    2. -
                  2. Konfiguration von Tomcat
                    3. -
                  3. Konfiguration von SSL
                    4. -
                  -
                  2. -
                2. Apache
                    -
                  1. Konfiguration von mod_jk im Apache
                    2. -
                  2. Konfiguration von Tomcat
                    3. -
                  3. Konfiguration von SSL mit mod_SSL
                    4. -
                  -
                  3. +
                3. Einsatz des Moduls MOA-ID-Configuration in Tomcat
                  4. +
                4. Starten und Stoppen von Tomcat +
                    +
                  1. Unter Windows
                    2. +
                  2. Unter Unix
                    3. +
                  3. Prüfen des erfolgreichen Starts
                    4. +
                  +
                  5. +
                5. Änderung der Konfiguration im laufenden Betrieb
                  6. +
                +
                2. +
              2. Logging +
                  +
                1. Format der Log-Meldungen
                  2. +
                2. Wichtige Log-Meldungen
                  3. +
                +
                3. +
              +
              3. +
            3. Erweiterungsmöglichkeiten
                +
              1. Vorgeschalteter Webserver
                  +
                1. Microsoft Internet Information Server (MS IIS)
                    +
                  1. Konfiguration von mod_jk im MS IIS
                    2. +
                  2. Konfiguration von Tomcat
                    3. +
                  3. Konfiguration von SSL
                    4. +
                  +
                  2. +
                2. Apache
                    +
                  1. Konfiguration von mod_jk im Apache
                    2. +
                  2. Konfiguration von Tomcat
                    3. +
                  3. Konfiguration von SSL mit mod_SSL
                    4. +
                  +
              4. -
            +
        -
          +
          1. Referenzierte Software

          1 Übersicht

          @@ -95,7 +95,7 @@
        1. Java SE Update SE 7 (neuestes Update) bzw. Java SE 8 (neuestes Update)
        2. Apache Tomcat 7 (neuestes Update) bzw. Apache Tomcat 8 (neuestes Update)
          3. -

          In diesem Betriebs-Szenario wird das MOA-ID-Auth Webservice und das MOA-ID Konfigurationstool in Tomcat zum Einsatz gebracht. Beide Module können sowohl in derselben Tomcat-Instanz, als auch in separaten Tomcat-Instanzen betrieben werden. Für den Fall des separaten Betriebs muss die Installation auf beiden Tomcat-Instanzen ausgeführt werden. In beiden Fällen fungiert der Tomcat gleichzeitig als HTTP- und HTTPS-Endpunkt für beide Module. Beide Protokolle werden direkt in Tomcat konfiguriert, wobei MOA-ID-Auth und MOA-ID-Configuration Log4j als Logging Toolkit verwenden.

          +

          In diesem Betriebs-Szenario wird das MOA-ID-Auth Webservice und das MOA-ID Konfigurationstool in Tomcat zum Einsatz gebracht. Beide Module können sowohl in derselben Tomcat-Instanz, als auch in separaten Tomcat-Instanzen betrieben werden. Für den Fall des separaten Betriebs muss die Installation auf beiden Tomcat-Instanzen ausgeführt werden. In beiden Fällen fungiert der Tomcat gleichzeitig als HTTP- und HTTPS-Endpunkt für beide Module. Beide Protokolle werden direkt in Tomcat konfiguriert, wobei MOA-ID-Auth und MOA-ID-Configuration LogBack als Logging Toolkit verwenden.

          2.1.2 Installation

          2.1.2.1 Vorbereitung

          Die folgenden Schritte dienen der Vorbereitung der Installation.

          @@ -108,9 +108,9 @@
          Entpacken Sie die Datei moa-id-auth-3.0.0.zip in ein beliebiges Verzeichnis. Dieses Verzeichnis wird im weiteren Verlauf als $MOA_ID_AUTH_INST bezeichnet.
          Installation der Kryptographiebibliotheken von SIC/IAIK
          -

          Kopieren Sie alle Dateien aus dem Verzeichnis $MOA_ID_AUTH_INST/ext in das Verzeichnis $JAVA_HOME/jre/lib/ext. Zusätzlich müssen Sie die Rechtedateien Ihrer Java SE austauschen. Laden Sie dazu die passenden Unlimited Strength - - +

          Kopieren Sie alle Dateien aus dem Verzeichnis $MOA_ID_AUTH_INST/ext in das Verzeichnis $JAVA_HOME/jre/lib/ext. Zusätzlich müssen Sie die Rechtedateien Ihrer Java SE austauschen. Laden Sie dazu die passenden Unlimited Strength + + Jurisdiction Policy Files von der Java SE Downloadseite und achten Sie darauf die für ihre verwendete Java SE Installation richtige Version zu nehmen. Anschließend folgen Sie der darin enthaltenen Installationsanweisung.

          Installation einer Datenbank
          @@ -142,8 +142,7 @@
        3. moa.id.configuration: Pfad und Name der Basiskonfigurationsdatei für MOA-ID-Auth. Eine beispielhafte Konfigurationsdatei finden Sie hier. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der Java Virtual Machine interpretiert.
        4. moa.spss.server.configuration: Pfad und Name der zentralen Konfigurationsdatei für MOA SP/SS. Eine beispielhafte Konfigurationsdatei finden Sie hier. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter WEB-INF/conf enthaltene Default-Konfiguration herangezogen.
        5. eu.stork.samlengine.config.location: Pfad auf den Ordner mit den zentralen Konfigurationsdateien für STORK. Die Beispielkonfiguration für das Modul MOA-ID-Auth enthält bereits den Ordner für die STORK Konfiguration.
          6. -
        6. log4j.configuration: URL der Log4j Konfigurationsdatei. Eine beispielhafte Log4j-Konfiguration finden Sie hier. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter WEB-INF/classes enthaltene Default-Konfiguration herangezogen.
          7. -
        7. -Dlogback.configurationFile: URL der LogBack Konfigurationsdatei. Eine beispielhafte LobBack-Konfiguration finden Sie hier. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter WEB-INF/classes enthaltene Default-Konfiguration herangezogen. Überdies besteht die Möglichkeit eine bestehende Log44 Konfigurationsdatei in der LogBack Format zu überführen (http://logback.qos.ch/translator/).
          8. +
        8. -Dlogback.configurationFile: URL der LogBack Konfigurationsdatei. Eine beispielhafte LobBack-Konfiguration finden Sie hier. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter WEB-INF/classes enthaltene Default-Konfiguration herangezogen. Überdies besteht die Möglichkeit eine bestehende Log44 Konfigurationsdatei in der LogBack Format zu überführen (http://logback.qos.ch/translator/).
        9. javax.net.ssl.trustStore: Pfad und Dateiname des Truststores für vertrauenswürdige SSL Zertifikate. Die SSL Serverzertifikate der Server von denen mittels https Dateien bezogen werden müssen im Truststore abgelegt werden. Ein relativer Pfad werden relativ zum Startverzeichnis der Java Virtual Machine interpretiert.
        10. javax.net.ssl.trustStorePassword: Passwort für den Truststore (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll).
        11. javax.net.ssl.trustStoreType: Truststore-Typ (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll). Je nach verwendetem Keystore-Typ muss jks (Java Key Store) oder pkcs12 (PKCS#12-Datei) angegeben werden.
          12. @@ -161,8 +160,7 @@
          • moa.id.webconfig: Pfad und Name der Basiskonfigurationsdatei für MOA-ID-Configuration. Eine beispielhafte Konfigurationsdatei finden Sie hier. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der Java Virtual Machine interpretiert.
          • user.properties: Pfad und Name der Basiskonfigurationsdatei für das Usermanagement der Konfigurationsoberfläche. Eine beispielhafte Konfigurationsdatei finden Sie hier. Wird ein relativer Pfad angegeben, wird dieser relativ zum Startverzeichnis der Java Virtual Machine interpretiert.
            • -
          • log4j.configuration: URL der Log4j Konfigurationsdatei. Eine beispielhafte Log4j-Konfiguration finden Sie hier. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter WEB-INF/classes enthaltene Default-Konfiguration herangezogen.
            • -
          • logback.configurationFile: URL der LogBack Konfigurationsdatei. Eine beispielhafte LobBack-Konfiguration finden Sie hier. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter WEB-INF/classes enthaltene Default-Konfiguration herangezogen. Überdies besteht die Möglichkeit eine bestehende Log44 Konfigurationsdatei in der LogBack Format zu überführen (http://logback.qos.ch/translator/).
            • +
          • logback.configurationFile: URL der LogBack Konfigurationsdatei. Eine beispielhafte LobBack-Konfiguration finden Sie hier. Wird eine relative URL angegeben, wird diese als File-URL relativ zum Startverzeichnis der Java Virtual Machine interpretiert. Ist diese System Property nicht gesetzt, wird automatisch eine im Webarchiv unter WEB-INF/classes enthaltene Default-Konfiguration herangezogen. Überdies besteht die Möglichkeit eine bestehende Log44 Konfigurationsdatei in der LogBack Format zu überführen (http://logback.qos.ch/translator/).
          • javax.net.ssl.trustStore: Pfad und Dateiname des Truststores für vertrauenswürdige SSL Zertifikate Die SSL Serverzertifikate der Server von denen mittels https Dateien bezogen werden müssen im Truststore abgelegt werden. Ein relativer Pfad werden relativ zum Startverzeichnis der Java Virtual Machine interpretiert.
          • javax.net.ssl.trustStorePassword: Passwort für den Truststore (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll).
          • javax.net.ssl.trustStoreType: Truststore-Typ (optional; nur, wenn SSL Client-Authentisierung durchgeführt werden soll). Je nach verwendetem Keystore-Typ muss jks (Java Key Store) oder pkcs12 (PKCS#12-Datei) angegeben werden.
            • @@ -186,7 +184,7 @@ gestartet werden. Das Stoppen von Tomcat erfolgt analog mit

            Ein erfolgreicher Start des MOA-ID-Auth Modules ist an folgender Log-Meldung ersichtlich:

-
32131 [localhost-startStop-1] INFO moa.id.auth  - MOA ID Authentisierung wurde erfolgreich gestartet 
+
32131 [localhost-startStop-1] INFO moa.id.auth  - MOA ID Authentisierung wurde erfolgreich gestartet
 32131 [localhost-startStop-1] INFO moa.id.auth  - Dispatcher Servlet initialization finished.

 
Analog bei MOA-ID-Configuration

 
INFO | 21 10:16:22 | localhost-startStop-1 | Loading config module: MOAIDConfigurationModul

@@ -202,7 +200,7 @@ https://<host>:<port>/moa-id-auth/
 https://<host>:<port>/egiz-configuration-webapp/

Die Verfügbarkeit des Services können Sie einfach überprüfen, indem Sie die Endpunkte mit einem Web-Browser aufgerufen; dies sollte nach erfolgreichem Start zur Anzeige einer Informationsseite führen.

2.1.3 Logging
-

Beide Module verwenden Log4j für die Ausgabe von Log-Meldungen am Bildschirm bzw. in Log-Dateien. Log4j bietet zahlreiche Konfigurationsmöglichkeiten, die ausführlich im Log4j Handbuch beschrieben sind. Unter anderem gibt es die Möglichkeit, folgende Einstellungen vorzunehmen: +

Beide Module verwenden LobBack für die Ausgabe von Log-Meldungen am Bildschirm bzw. in Log-Dateien. LogBack bietet zahlreiche Konfigurationsmöglichkeiten, die ausführlich im LogBack Handbuch beschrieben sind. Unter anderem gibt es die Möglichkeit, folgende Einstellungen vorzunehmen:

-

Eine für beide Module passende Konfigurationsdatei für Log4j finden Sie hier. Wird diese Datei als Logging-Konfiguration verwendet, so werden alle Log-Meldungen sowohl in die Konsole, als auch in die Dateien moa-id-auth.log und moa-id-configuration.log geschrieben.

+

Wird diese Datei als Logging-Konfiguration verwendet, so werden alle Log-Meldungen sowohl in die Konsole, als auch in die Dateien moa-id-auth.log und moa-id-configuration.log geschrieben.

2.1.3.1 Format der Log-Meldungen
-

Anhand einer konkreten Log-Meldung wird das Format der MOA SP/SS Log-Meldungen erläutert:

+

Anhand einer konkreten Log-Meldung wird das Format der MOA-ID-Meldungen erläutert: 

- INFO | 2017-09-18 10:29:22,904 | SID-7947921060553739539 | TID-4708232418268334030 | https://sso.demosp.at/handysignatur 
+ INFO | 2017-09-18 10:29:22,904 | SID-7947921060553739539 | TID-4708232418268334030 | https://sso.demosp.at/handysignatur
       | ajp-nio-28109-exec-7 | No SSO Session cookie found

Der Wert INFO besagt, dass die Log-Meldung im Log-Level INFO entstanden ist. Folgende Log-Levels existieren:

@@ -259,19 +257,19 @@ https://<host>:<port>/egiz-configuration-webapp/

Der nächste Wert 01 21:25:26,540 gibt den Zeitpunkt an, zu dem die Log-Meldung generiert wurde (in diesem Fall den 1. Tag im aktuellen Monat, sowie die genaue Uhrzeit).

-

Der Wert SID-7947921060553739539 bezeichnet die SessionID, welche diesem Request zugeordnet wurde. Eine SessionID ist innerhalb einer SSO auch über mehrere Authentifizierungsrequests eindeutig. Das Loggen der SessionID kann mittels %X{sessionId} in der log4j Konfiguration gesetzt werden

-

Der Wert TID-4708232418268334030 bezeichnet die TransactionsID, welche diesem Request zugeordnet wurde. Eine TransactionsID ist innerhalb eines Authentifizierungsrequests eindeutig. Das Loggen der TransactionsID kann mittels %X{transactionId} in der log4j Konfiguration gesetzt werden

-

Der Wert https://sso.demosp.at/handysignatur bezeichnet die Online Applikation (eindeutiger Identifier dieses Service Providers) für welchen dieser Authentifizierungsrequest durchgeführt wird. Das Loggen des OA Identifiers kann mittels %X{oaId} in der log4j Konfiguration gesetzt werden

+

Der Wert SID-7947921060553739539 bezeichnet die SessionID, welche diesem Request zugeordnet wurde. Eine SessionID ist innerhalb einer SSO auch über mehrere Authentifizierungsrequests eindeutig. Das Loggen der SessionID kann mittels %X{sessionId} in der LogBack Konfiguration gesetzt werden

+

Der Wert TID-4708232418268334030 bezeichnet die TransactionsID, welche diesem Request zugeordnet wurde. Eine TransactionsID ist innerhalb eines Authentifizierungsrequests eindeutig. Das Loggen der TransactionsID kann mittels %X{transactionId} in der LogBack Konfiguration gesetzt werden

+

Der Wert https://sso.demosp.at/handysignatur bezeichnet die Online Applikation (eindeutiger Identifier dieses Service Providers) für welchen dieser Authentifizierungsrequest durchgeführt wird. Das Loggen des OA Identifiers kann mittels %X{oaId} in der LogBack Konfiguration gesetzt werden

Der Wert ajp-nio-28109-exec-7 bezeichnet den Thread, von dem die Anfrage bearbeitet wird.

Der Rest der Zeile einer Log-Meldung ist der eigentliche Text, mit dem das System bestimmte Informationen anzeigt. Im Fehlerfall ist häufig ein Java Stack-Trace angefügt, der eine genauere Ursachen-Forschung ermöglicht.

2.1.3.2 Wichtige Log-Meldungen

Neben den im Abschnitt 2.1.2.4.3 beschriebenen Log-Meldungen, die anzeigen, ob das Service ordnungsgemäß gestartet wurde, geben nachfolgenden Log-Meldungen Aufschluss über die Abarbeitung von Anfragen.

Die Entgegennahme einer Anfrage wird angezeigt durch: - + 

125690 [ajp-bio-129.27.142.119-38609-exec-1] INFO moa.id.auth  - REQUEST: /moa-id-auth/dispatcher
 125690 [ajp-bio-129.27.142.119-38609-exec-1] INFO moa.id.auth  - QUERY  : mod=id_pvp2x&action=Post&
-

Ein Fehler beim Abarbeiten der Anfrage wird angezeigt durch: +

Ein Fehler beim Abarbeiten der Anfrage wird angezeigt durch: 

2435298 [ajp-bio-129.27.142.119-38609-exec-10] ERROR moa.id.auth  - Failed to generate a valid protocol request!

In diesem Fall gibt der mitgeloggte Stacktrace Auskunft über die Art des Fehlers.

@@ -318,7 +316,7 @@ https://<host>:<port>/egiz-configuration-webapp/ Java Standard Edition (Software Development Kit bzw. Java Runtime Environment) - Log4J + LogBack Logging Framework -- cgit v1.2.3