Installation

Diese Seite beschreibt die Installation eines beliebigen IFAS-Services/IFAS-Jobs und ist für jede Art von IFAS-Service (Dokumentenserver, MuSchG-Service, Asbest-Service, SBA-Report-Service, ...) gültig.
Auf den Unterseiten der Services befinden sich eventuell weitere Konfigurationsschritte, welche für den jeweiligen Service erforderlich sind.

Inhalt

  1. Tomcat Konfiguration
  2. Installation mehrerer IFAS-Services/Jobs innerhalb eines Tomcats
  3. Anmelden mit der IFAS-Benutzerkennung
  4. Konfiguration MS-SQL-Server
  5. Logging
  6. Fehlerbericht der letzten 24 Stunden
  7. DB-Sperren für IFAS-Jobs
  8. E-Mail Versand
  9. Netzwerkfreigaben
  10. Update der Services/Jobs oder der Java-Version

Tomcat Konfiguration

Installation mehrerer IFAS-Services/Jobs innerhalb eines Tomcats

Es können mehrere IFAS-Services/Jobs problemlos innerhalb eines Tomcats laufen. Standardmäßig teilen sich die Programme die Konfigurationsdatei standard.cnf. Beim Start sucht jeder Service/Job aber eine standard.cnf unter einem individuellen Namen. Falls unter diesem Namen keine Datei gefunden wurde, wird nach dem Standard-Namen "standard.cnf" gesucht. So ist es möglich einen Service mit Parametern zu starten, die nur für diesen einen Dienst gelten (z.B. eine andere Datenbank-Verbindung).
Dies sind die genauen Namen für die einzelnen standard.cnf-Dateien:

Service/Jobname Name der standard.cnf
Asbest Service asbestservice-standard.cnf
Dokumentenserver ids-standard.cnf
Formularserver formserver-standard.cnf
Entgelt Service (Heimarbeit) entgeltservice-standard.cnf
MuSchG Service muschgservice-standard.cnf
IFAS Plus Service ifasplusservice-standard.cnf
SBA Report Service sbareportservice-standard.cnf
SprengG Service sprengservice-standard.cnf
IFAS Jobs ifasjob-standard.cnf
IFAS NiSV Service nisvservice-standard.cnf
Heimaufsicht Service heimaufsichtservice-standard.cnf
Arbeitszeit Service azserviceservice-standard.cnf

Anmelden mit der IFAS-Benutzerkennung

Bei allen IFAS-Services ist standardmäßig eine HTTP-Basis-Authentifizierung aktiviert.
Wenn aus den IFAS-Modulen heraus einer dieser Services aufgerufen wird (Zugriff auf ein Schreiben im VIS, Erstellung einer Systembewertung), geschieht diese Authentifizierung im Hintergrund und damit transparent für den Anwender. Wird dagegen auf den Service direkt im Browser zugegriffen, müssen Benutzer/Passwort direkt eingegeben werden.
Falls die Anmeldung über die Windows Domäne (Active Directory) erfolgt, ist das Passwort vom Anwender in der IFAS Benutzerverwaltung evtl. nicht bekannt bzw. keines gesetzt. Für diesen Fall sollten dann Kennwörter für die Benutzer vergeben werden.

Die Anmeldung lässt sich über die cnf-Variable SERVICE_ANMELDUNG in der standard.cnf deaktivieren, hierzu muss folgender Eintrag in die vom IFAS Plus Service/Dokumentenserver genutzten Datei standard.cnf eingefügt werden:
SERVICE_ANMELDUNG=0
Die früher genutzte Variante mit der Datei application.yml wird nicht mehr unterstützt, sollte diese Datei noch existieren, sollte diese gelöscht werden.

Konfiguration MS-SQL-Server

SSL-Verbindung

Bei neueren eingesetzten MS-SQL-Server-Treibern ist eine SSL-Verbindung zur DB verpflichtend. Ist das Zertifikat auf dem Tomcat nicht bekannt, kann es zu folgender Fehlermeldung kommen: 
javax.servlet.ServletException: DB connection failure: Datenbankverbindung 'Heimaufsicht' nicht vorhanden.
Error NdatJdbc Db-Connect: Der Treiber konnte keine sichere Verbindung mit SQL-Server Über die SSL-(Secure Sockets Layer)-Verschlüsselung herstellen.
Fehler: 'PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target'.
ClientConnectionId:4d419d34-5faa-4c90-b2e5-8c0107372baa
Als Fehlerbehebung funktioniert derzeit leider nur folgender Workaround: In der Datei ndat.dft wird die Überprüfung des Host-Zertifikats durch Hinzufügen der URL mit den Parametern "encrypt=true;trustServerCertificate=true;" abgeschaltet, z.B.: 
[IFAS]
DATABASE_DRIVER=com.microsoft.sqlserver.jdbc.SQLServerDriver
DATABASE_CONNECT=jdbc:sqlserver://rechnername;databaseName=IFAS;integratedSecurity=false;encrypt=true;trustServerCertificate=true;
...
weitere Angaben
....

Integrierte Authentifizierung des SQL-Servers nutzen (Active-Directory)

Zum Herstellen einer DB-Verbindung vom Tomcat zum DB-Server kann der Windows-Benutzer, unter dem der Tomcat ausgeführt wird, genutzt werden. Der DATABASE_CONNECT-Eintrag in der ndat.dft muss die Verwendung der Authentifizierung über das Active-Directory über integratedSecurity=true; aktivieren:

DATABASE_CONNECT=jdbc:sqlserver://localhost:1434;databaseName=IFAS;integratedSecurity=true;

Auf der Downloadseite des jeweiligen Service sind die zum in der war-Datei ausgelieferten Microsoft SQL JDBC Treiber gehörigen DLL-Dateien zum Download zu finden.

Damit der tomcat die DLL laden kann muss sie in einem der Verzeichnisse liegen, die vom tomcat nach DLLs durchsucht werden. Die Liste der zu durchsuchenden Verzeichnisse kann beim Start des tomcat über die Systemeigenschaft java.library.path festgelegt werden.

Per Default ist java.library.path auf den Wert der Windows Umgebungsvariable PATH gesetzt. Zusätzlich wird das bin Verzeichnis der Java Umgebung durchsucht, die zum Start des tomcat verwendet wird.

Es wird empfohlen die DLL in das Verzeichnis C:\Kisters\ifas\bin\jar\jdbcdrivers zu kopieren und dieses Verzeichnis in java.library.path anzugeben.

Wird der tomcat als Dienst ausgeführt, ist die Konfiguration über die Oberfläche von tomcat9w.exe zu konfigurieren. Auf dem Reiter Java ist unter Java Options -Djava.library.path=C:\Kisters\ifas\bin\jar\jdbcdrivers zu ergänzen.

Konfiguration von java.library.path im tomcat Service

Alternativ kann die DLL in das bin Verzeichnis der Java Installation kopiert werden, die zum ausführen des tomcat verwendet wird. Bei einer Aktualisierung der Java Version ist dieser Schritt dann zu wiederholen.

Logging

Um in einem Fehlerfall, oder bei anderen unerwarteten Ereignissen, eine genaue Fehleranalyse durchführen zu können, gibt es 2 unterschiedliche Mechanismen zum Logging: Das Schreiben in eine Datei im Tomcat und das Loggen in die Datenbanktabelle ifas_log.
Das Loggen in eine Datei muss konfiguriert werden, das Loggen in die DB geschieht standardmäßig bei schwer wiegenden Fehlern.

Logging in Datei

Es ist ratsam, das Logging innerhalb des Tomcats zu konfigurieren. Gerade im Testbetrieb sollte ein niedriger log-Level eingestellt werden.
Die beiden folgenden Werte müssen in der standard.cnf gesetzt werden, um das Logging in eine Datei innerhalb des Tomcats zu aktivieren und können als Standardwerte für jeden Service genutzt werden:
LOG4J=$CATALINA_BASE\logs\service-log4j.log
LOG4JCLASSES=de.kisters.ifas=Info,de.kisters.ifas.rest=Debug,de.kisters.ifas.services=Debug
Diese Werte sorgen für das Erzeugen einer log-Datei service-log4j.log innerhalb des logs-Verzeichnis des Tomcats. Eine ausführliche Erläuterung der cnf-Parameter in der Datei standard.cnf befindet sich hier.

Logging in DB-Tabelle ifas_log

Standardmäßig werden schwere Fehler immer auch in die Tabelle ifas_log geschrieben. Dieses Verhalten kann abgeschaltet werden (nicht empfohlen) oder aber auch erhöht werden, so dass alle log-Meldungen in die DB geschrieben werden. Dies ist vor allem für den Fall praktisch, wenn der Zugriff auf das Dateisystems des Tomcats nicht ohne weiteres möglich ist (z.B. wenn sich der Tomcat innerhalb eines Rechenzentrums befindet und der Zugriff auf die log-Dateien nur über Dritte möglich ist).
Das Logging kann systemweit über die cnf-Variablen LOG4JDATABSECLASSES und LOG4JDATABASELEVEL gesetzt werden, oder aber auch in der standard.cnf eines Tomcats: 
LOG4JDATABASELEVEL=DEBUG
LOG4JCLASSES=de.kisters.ifas.rest,de.kisters.ifas.services
Hohe Log-Level (DEBUG, INFO) führen hier zu einer erheblichen DB-Belastung und deutlichen Perfomance-Einbußen, und sollten daher nur im Testbetrieb aktiviert werden. Der Log-Level TRACE wird unabhängig der Konfiguration nie in die DB geloggt.

Fehlerbericht der letzten 24 Stunden

Um einen besseren Überblick, gerade bei mehreren Diensten zu behalten ist es ratsam, den Fehlerbericht der letzten 24 Stunden zu aktivieren. Eine Anleitung befindet sich hier.

Fehlerbericht der letzten 24 Stunden

DB-Sperren für IFAS-Jobs

Jeder IFAS-Job trägt sich zum Start seiner Ausführung in die Benutzerverwaltung ein und zum Ende der Ausführung auch wieder aus. So sind über die Benutzerverwaltung die einzelnen Jobs im Karteireiter "Monitor" sichtbar:

Übersicht Benutzerverwaltung

Durch diese Einträge sperrt ein Job die DB, eine erneute Ausführung des gleichen Jobs (nicht aber eines anderes Jobs, siehe Bildschirmfoto: hier werden 2 verschiedene Jobs zur gleichen Zeit ausgeführt) wird verhindert.
Somit wird vermieden, dass ein IFAS-Job, falls er aus Versehen in verschiedene Tomcats auf die gleiche DB zugreift, parallel ausgeführt wird. Dies kann zu schwer zu entdeckenden Fehlern führen und wird somit dadurch verhindert.

In seltenen Fällen kann es passieren, dass ein Job nicht bis zum Ende durchläuft (z.B. Absturz des Tomcats, Abreissen der DB-Verbindung während der Ausführung) und dadurch nach Ende des Jobs der Eintrag in der DB nicht mehr entfernt wird. Im Fehlerbericht der letzten 24 Stunden findet sich dann dort ein Eintrag (oder auch direkt in der Tabelle ifas_log):

Fehlerbericht der letzten 24 Stunden

In den log-Dateien findet sich hierzu auch ein entsprechender Eintrag zum Abbruch des Jobs: 
20 Dez. 2023 15:02:00 ERROR de.kisters.ifas.jobs.dmstransfer.common.AIfasJob.isJobInDb(AIfasJob.java:123): Job Fabasoft-Job ist bereits in Tabelle bwlmx eingetragen, Job wird abgebrochen
Sollte dies der Fall sein und man sich sicher ist, dass der Job nicht auf verschiedenen Rechnern/Tomcats ausgeführt wird, kann der Eintrag in der Benutzerverwaltung gelöscht werden:

Jobeintrag in der Benutzerverwaltung löschen

E-Mail Versand

In einigen Services kann ein (optionaler) E-Mail-Versand eingerichetet werden. Falls eine Benutzeranmeldung am SMTP-Mailserver nötig ist ist diese über die Passwortverwaltung im Admin-Modul zu konfigurieren: Im Feld "Konto" ist der Anmeldename, im Feld "Passwort" ist das Paßwort zu hinterlegen. Falls die Absenderemailadresse nicht der gleiche Name wie der Anmeldename ist, so ist diese im Feld "Kennung" einzutragen:

Beispieleinträge für E-Mail-Versand

Außerdem müssen folgende cnf-Variablen in der genutzten standard.cnf Datei getätigt werden:

Bedeutung
EMAIL_HOST Domain oder IP-Adresse des E-Mailservers
EMAIL_PORT Portnummer des E-Mailservers
EMAIL_ENABLE_TLS (optional) Hiermit kann die TLS-Transportverschlüsselung an oder abgeschaltet werden. Standardmäßig ist diese angeschaltet:
0: TLS-Transportverschlüsselung aus
1: TLS-Transportverschlüsselung an (Standardwert)

Fehlersuche

Im Fehlerfall kann eine genaue Ausgabe in einer Datei $texte/mail.log protokolliert werden. Hierzu muss Log4J aktiviert sein und der Wert LOG4JCLASSES muss um den folgenden Zusatz ergänzt werden:de.kisters.tools.mail=DEBUG Wurde das Debugging erfolgreich eingestellt wird in jedem Fall eine Datei mail.log iom Verzeichnis $texte erstellt. Diese Datei wird auch im Erfolgsfall geschrieben und enthält sämtliche Informationen der Mail, d.h. diese Funktion sollte nur zur Fehlersuche aktiv sein.

Beispielausgabe:
DEBUG: Jakarta Mail version 1.6.7
DEBUG: successfully loaded resource: /META-INF/javamail.default.providers
DEBUG: Tables of loaded providers
DEBUG: Providers Listed By Class Name: {com.sun.mail.smtp.SMTPTransport=javax.mail.Provider[TRANSPORT,smtp,com.sun.mail.smtp.SMTPTransport,Oracle], com.sun.mail.imap.IMAPSSLStore=javax.mail.Provider[STORE,imaps,com.sun.mail.imap.IMAPSSLStore,Oracle], com.sun.mail.pop3.POP3Store=javax.mail.Provider[STORE,pop3,com.sun.mail.pop3.POP3Store,Oracle], com.sun.mail.smtp.SMTPSSLTransport=javax.mail.Provider[TRANSPORT,smtps,com.sun.mail.smtp.SMTPSSLTransport,Oracle], com.sun.mail.imap.IMAPStore=javax.mail.Provider[STORE,imap,com.sun.mail.imap.IMAPStore,Oracle], com.sun.mail.pop3.POP3SSLStore=javax.mail.Provider[STORE,pop3s,com.sun.mail.pop3.POP3SSLStore,Oracle]}
DEBUG: Providers Listed By Protocol: {imap=javax.mail.Provider[STORE,imap,com.sun.mail.imap.IMAPStore,Oracle], smtp=javax.mail.Provider[TRANSPORT,smtp,com.sun.mail.smtp.SMTPTransport,Oracle], pop3=javax.mail.Provider[STORE,pop3,com.sun.mail.pop3.POP3Store,Oracle], imaps=javax.mail.Provider[STORE,imaps,com.sun.mail.imap.IMAPSSLStore,Oracle], smtps=javax.mail.Provider[TRANSPORT,smtps,com.sun.mail.smtp.SMTPSSLTransport,Oracle], pop3s=javax.mail.Provider[STORE,pop3s,com.sun.mail.pop3.POP3SSLStore,Oracle]}
DEBUG: successfully loaded resource: /META-INF/javamail.default.address.map
DEBUG: getProvider() returning javax.mail.Provider[TRANSPORT,smtp,com.sun.mail.smtp.SMTPTransport,Oracle]
DEBUG SMTP: need username and password for authentication
DEBUG SMTP: protocolConnect returning false, host=testsystem, user=Jörg Possin, password=
DEBUG SMTP: useEhlo true, useAuth true
DEBUG SMTP: trying to connect to host "testsystem", port 25, isSSL false
220 mail1.kisters.de ESMTP Tue, 12 Dec 2023 20:08:36 +0100
DEBUG SMTP: connected to host testsystem", port: 25
EHLO 
250-testsystem Hello computer [*.*.*.*], pleased to meet you
250-ETRN
250-AUTH LOGIN PLAIN
250-8BITMIME
250-ENHANCEDSTATUSCODES
250-PIPELINING
250-CHUNKING
250-STARTTLS
250 SIZE
...

Netzwerkfreigaben

Einige der IFAS-Services/Jobs benötigen Zugriff auf das komplette IFAS-Ablageverzeichnis, das über die Konfigurationsvariable IFAS_TEXTE konfiguriert ist. Der Zugriff wird z.B. von allen DMS-Jobs/Services benötigt. Zum Übertragen/Anzeigen der Schreiben oder vom Formularserver zur Erstellung von Schreiben aus Dateianhängen. Daher muss folgendes sichergestellt werden: Laufen die Services/Jobs unter einem Linux-System, muss zusätzlich noch die Konfigurationsvariable IFAS_TEXTE_REPLACEMENT gesetzt werden.

Update der Services/Jobs oder der Java-Version

Update/Wechsel der Java Version

Über den Tomcat Service Konfigurationsdialog:
Die neue Java-Version muss hierzu bereits zuvor in ein Verzeichnis kopiert worden sein. Unter Windows empfiehlt es sich, die auch für die IFAS-Module bereit gestellte Java Laufzeitumgebung zu nutzen.