Updateanleitung Version 4.47 auf Version 4.49 für Linux

WICHTIGER HINWEIS

Mit der Version 4.49.0 gibt es eine neue Update-Anleitung. Bitte folgen Sie den neuen Update-Schritten.

Update-Reihenfolge

Das Einspielen der Versionen 4.3.0, 4.7.6, 4.11.1, 4.44.1 und 4.49.0 ist zwingend erforderlich und darf nicht übersprungen werden.
Bevor Sie das Update auf die aktuelle Version vornehmen. Jede Version muss einmal komplett erfolgreich starten und Sie müssen sich einmal an der FTAPI Weboberfläche einloggen, bevor Sie die nächste Version einspielen.

Wenn Ihr FTAPI System derzeit noch auf einer Version < 4.44.1 ist, dann führen Sie bitte zunächst ein Update auf Version 4.44.1 durch.
-> Zur Installationsdatei & Update-Anleitung.

Sollten Sie die FTAPI-Server-Komponenten oder eine Updateanleitung für vorherige Versionen zum Download benötigen, nutzen Sie hierfür bitte das Support-Formular: https://www.ftapi.com/supportanfrage/

Vorbereitung zur Einspielung des Updates

Um sicherzustellen, dass Ihr lokal installierter Dienst Zugriff auf den externen Dienst cdn.ftapi.com hat, führen Sie bitte folgende Schritte durch:

Überprüfen Sie zunächst mit nslookup cdn.ftapi.com oder dig cdn.ftapi.com die korrekte DNS-Auflösung der Adresse.
Stellen Sie dann sicher, dass Ihre Firewall ausgehende Verbindungen auf den Port 443 (HTTPS) zulässt.
Überprüfen Sie gegebenenfalls die Konfiguration eines eventuell verwendeten Proxy-Servers.
Führen Sie abschließend einen Test durch, um die erfolgreiche Verbindung zu bestätigen.

Der Zugriff auf cdn.ftapi.com wird unter anderem benötigt, um die sicherheitsrelevante Benachrichtigung zu veralteten Outlook Add-In-Versionen bereitzustellen.

Die Update-Schritte

Stoppen Sie den FTAPI Server und erstellen Sie ein komplettes Backup des Systems.
Sichern Sie nun bitte die Datei Installationsverzeichnis /ftapi-server/tomcat/conf/server.xml
Bitte prüfen und merken Sie sich, mit welchem Nutzer der FTAPI Dienst aktuell läuft. Dies ist von der Distribution und dem gewählten init-System abhängig. Wenn Sie keinen vom Standard abweichenden Nutzer angegeben haben, können Sie diesen Schritt überspringen.
Bitte de-installieren Sie den FTAPI Dienst mittels
1. Linux mit init.d: dem Befehl rm /etc/init.d/ftapi
  1. Linux mit SystemD:
    systemctl stop ftapi
    systemctl disable ftapi
    rm /usr/lib/systemd/system/ftapi.service # and symlinks that might be related
    systemctl daemon-reload
    systemctl reset-failed
Verschieben oder benennen Sie nun den gesamten Ordner <Installationsverzeichnis>/ftapi-server z. B. in ftapi-server-old. WICHTIG: der Ordner .ftapi/ darf nicht gelöscht oder verschoben werden.
Kopieren Sie nun aus dem Downloadpaket die Ordner ftapi-server und additional-lib
ins Installationsverzeichnis
Legen Sie eine Sicherung ihrer Konfigurationsdateien an. Diese Sicherung sollte folgende Ordner enthalten:
1. .ftapi/config
2. .ftapi/certificate (falls vorhanden)
3. .ftapi/saml (falls vorhanden)
Falls Sie HTTPS im FTAPI-Server verwenden: Migrieren Sie die alte KeyStore-Konfiguration aus der Tomcat-Konfiguration.
1. Benennen Sie die Datei secutransfer.yml aus dem Verzeichnis .ftapi/config/ in secutransfer.yml.old um
2. Kopieren Sie die Vorlage aus dem Downloadpaket (.ftapi/config/secutransfer.yml.template) in das Verzeichnis .ftapi/config/ , benennen Sie die Datei in secutransfer.yml um.
3. Extrahieren Sie die folgenden Werte aus ftapi-server-old/tomcat/conf/server.xml
  den Connector finden Sie unter <Connector [...] keystoreFile="../../domain.pfx" keystorePass="secret" />
  Der Befehl cat ftapi-server-old/tomcat/conf/server.xml |grep key gibt Ihnen die benötigen Werte aus.
  1. Übernehmen Sie die Werte von keystoreFile und keystorePass
  2. Wandeln Sie den Pfad keystoreFile in einen absoluten Pfad um, z.B. /home/<user>/ftapi/.ftapi/certificate/domain.pfx
Passen Sie die Werte in der secutransfer.yml an, achten Sie bitte stets auf korrekte Einrückungen, z.B.

server:
  port: 443
  ssl:
    key-store: /home/<user>/ftapi/.ftapi/certificate/domain.pfx
    key-store-password: password
    enabled: true

10. Migrieren Sie die alte Datenbank-Konfiguration

a. Extrahieren Sie die folgenden Werte aus ../.ftapi/config/properties.xml

<config-definition>
    <group name="config.group.database" hidden="true">
        <property name="ftapi.jdbc.url" value="jdbc:mysql://database:3306/ftapi?useUnicode=yes&amp;characterEncoding=UTF-8&amp;useJDBCCompliantTimezoneShift=true&amp;useLegacyDatetimeCode=false&amp;serverTimezone=UTC&amp;driver=com.mysql.cj.jdbc.Driver" />
        <property name="ftapi.jdbc.driver" value="net.bull.javamelody.JdbcDriver" />
        <property name="ftapi.jdbc.password" value="secret" type="password"/>
        <property name="ftapi.jdbc.username" value="user" />
        <property name="ftapi.hibernate.dialect" value="com.ftapi.server.dao.hibernate.FTAPIMySQL8Dialect" />
    </group>
</config-definition>

b. Folgende Werte (siehe value=".." aus properties.xml) zu secutransfer.yml hinzufügen, z.B.:

ftapi:
  hostingType: onprem
  jdbc:
    url: jdbc:mysql://database:3306/ftapi?useUnicode=yes&characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC&driver=com.mysql.cj.jdbc.Driver
    driver: net.bull.javamelody.JdbcDriver
    username: user
    password: secret
    hibernate:
      dialect: com.ftapi.server.dao.hibernate.FTAPIMySQL8Dialect

10. Lösen Sie die mysql-connector-j*.jar-Abhängigkeit auf:

Laden Sie den MySQL-Connector über https://dev.mysql.com/downloads/connector/j/ herunter (Plattform unabhängig)
Entpacken Sie die *.jar-Datei in das Verzeichnis /ftapi/additional-lib/

11. Unter Linux haben wir uns auf ftap.sh verlassen, um Tomcat über catalina.sh zu starten. Jetzt liefern wir einen SystemD-Dienst, um das Java-Binary direkt aufzurufen. Um zu migrieren, müssen Sie die folgenden Schritte durchführen.

12. Erstellen Sie einen neuen Benutzer mit dem Namen secutransfer und stellen Sie sicher, dass dieser Benutzer in <BASE_DIR> und allen seinen Unterverzeichnissen lesen und schreiben kann.

sudo adduser secutransfer
sudo chown -R secutransfer:secutransfer <BASE_DIR>

13. Machen Sie alle Binärdateien in <BASE_DIR>/ftapi-server/jre/linux/bin/java ausführbar

Beispiel: sudo chmod +x <BASE_DIR>/ftapi-server/jre/linux/bin/java

14. Erstellen Sie einen SymLink zu unserer Dienstdefinition

sudo ln -s <BASE_DIR>/ftapi-server/ftapi.service /etc/systemd/system/ftapi.service

15. Laden Sie den SystemD-Daemon neu und starten Sie den FTAPI-Dienst

sudo systemctl daemon-reload
sudo systemctl start ftapi.service

Troubleshooting

Versuchen Sie zunächst immer, die Server-URL aufzurufen. Es sollte die Anmeldeseite angezeigt werden.
Wenn dies nicht funktioniert, überprüfen Sie bitte die Logdateien auf Fehler.
Secutransfer speichert alle Logs in folgendem Verzeichnis: <BASE_DIR>/.ftapi/logs

Verwenden Sie systemctl, um den aktuellen Status des Dienstes zu erhalten. Führen Sie systemctl status ftapi.service aus. Dies gibt Ihnen Auskunft darüber, ob der Dienst gerade läuft oder nicht, und gibt einen Einblick in die aktuellen Logs des Dienstes.

Wenn die SecuTransfer-Protokolle keine Informationen enthalten oder Sie ein anderes Werkzeug zum Lesen der SecuTransfer-Protokolle bevorzugen, können Sie journalctl verwenden, um die Protokolle anzuzeigen.

Die Protokolle ausdrucken journalctl -u ftapi.service
Verfolgen der aktuellen Logs journalctl -f -u ftapi.service
Protokolle für einen bestimmten Zeitraum journalctl --since „2025-04-11 15:00:00“ --until „2025-04-11 16:00:00“ -u ftapi.service

Outlook Add-in

Sollten Sie das Outlook Add-in nutzen, empfiehlt FTAPI die aktuellste Version 4.8.6 des Add-ins zu verwenden: zum Download-Bereich

Insbesondere bei der Nutzung von Single-Sign-On und "Passwort Speichern" für das Add-in, können Komplikationen mit älteren Versionen des Add-ins auftreten.

Weboberfläche

Falls die FTAPI Weboberfläche nach dem erstmaligen Start nach der Durchführung des Updates einen Fehler ausgibt, durchsuchen sie das aktuelle ftapi-stderr.log (zu finden unter ftapi/ftapi-server/tomcat/logs) nach folgendem Fehler:

META-INF/config/db/db-changelog-pre-all-versions.xml::1.0.0-pre-all-mysql-primary-key-dbchangelog::jdietrich was: 8:aac6a5dc3e82735ef2fecbeaff535dfc but is now: 8:222b93d12a3606a2f8e40bfa69ef063f

Falls dieser Fehler im Log auftauchen sollte, führen Sie in der FTAPI MySQL Datenbank die folgende Query aus und starten sie anschließend den FTAPI Dienst neu:

UPDATE DATABASECHANGELOG SET MD5SUM='8:222b93d12a3606a2f8e40bfa69ef063f' WHERE ID='1.0.0-pre-all-mysql-primary-key-dbchangelog';

Eröffnen Sie alternativ ein Ticket bei unserem Support, dieser wird Sie bei der Durchführung unterstützen.