Die SuperX-Datenbank läuft auf Windows- und Linux-Rechnern. Der SuperX-Client läuft im Browser. Für den Applikationsserver empfehlen wir einen UNIX- bzw. Linux-Server, da die serverseitigen Scripte als Shellscripte konfiguriert sind. Aktuelle Linux-Distributionen enthalten die benötigten Pakete für Java, Tomcat und PostgreSQL.
Das SuperX-Kernmodul beinhaltet alle zum Betrieb von SuperX unbedingt notwendigen Tabellen, Prozeduren und Abfragen; die wichtigsten Tabellen werden unten näher beschrieben.
Ab Kernmodul 6.0 liegt die Datenbankseite des Kernmoduls innerhalb der SuperX-Webanwendung. In dieser Dokumentation werden dafür folgende Umgebungsvariablen verwendet:
| Bezeichnung | Variable | Typischer Pfad | Beschreibung |
|---|---|---|---|
Tomcat-Installation | $TOMCAT_HOME | /home/superx/webserver/tomcat oder /var/lib/tomcat10 | Basisverzeichnis des installierten Tomcat |
SuperX-Webanwendung | $WEBAPP | $TOMCAT_HOME/webapps/superx | Wurzelverzeichnis der SuperX-Webanwendung |
SuperX-Datenbank- und Modulbereich | $SUPERX_DIR | $WEBAPP/WEB-INF/conf/edustore | Verzeichnis der Datenbank-, Installations- und Modulscripte |
Unterhalb von $SUPERX_DIR befinden sich insbesondere folgende Verzeichnisse:
| Pfad | Beschreibung |
|---|---|
$SUPERX_DIR/db/bin | Shellscripte und die Umgebungssteuerung SQL_ENV |
$SUPERX_DIR/db/install | Installations- und Upgrade-Scripte des Kernmoduls |
$SUPERX_DIR/db/module | Installierte SuperX-Module |
$SUPERX_DIR/db/conf | Konfigurations- und Hilfsdateien der Datenbankseite |
Unterhalb von $WEBAPP/WEB-INF befinden sich außerdem die Webanwendungsdateien, beispielsweise die Verzeichnisse classes, lib, lib_ext und reports sowie die Dateien db.properties, dbforms-config.xml und web.xml. Der Datenbankserver kann auf einem anderen Rechner liegen als der Applikationsserver. Unter Linux kann für den Betrieb ein Benutzer superx mit dem Homeverzeichnis /home/superx eingerichtet werden. Das Homeverzeichnis ist jedoch nicht automatisch mit $SUPERX_DIR identisch.
SuperX liefert eine datenbankbasierten Website zur Präsentation von Inhalten der Hochschule für die öffentliche Nutzung im Internet sowie für die interne Nutzung im Intranet. Nach einer Datenübernahme aus den operativen Systemen gilt es, eine effiziente Berichterstellung zu ermöglichen und Export- und Importschnittstellen zu bieten. Das System wird in mehreren Aufbaustufen realisiert, wichtig ist daher die Skalierbarkeit des Systems vom Prototypen bis zum Echtbetrieb.
Der Prototyp der Erstinstallation ist auf einem einzelnen System möglich:
Das zu realisierende System besteht aus drei Komponenten: der Datenbank, der Webanwendung und des Clients (3-tier-Application).
Falls die Last ansteigt, ist das System wie folgt skalierbar:
Die SuperX-Datenbank wird angebunden an ein oder mehrere operative Vorsysteme. Gleichzeitig, um die Webanwendung zu entlasten, ist es möglich, die Last auf einen zweiten Webserver auszulagern ("Load balancing"). |
|
Die Installationsschritte beziehen sich auf die Neuinstallation und das Upgrade. Für die Neuinstallation für Testzwecke gibt es eine Kurzanleitung unter Linux.
Bei der Neuinstallation können Sie einfach alle Komponenten in einen Pfad $SUPERX_DIR kopieren und von dort die unten genannten Installationsschritte durchführen. Beim Update können Sie die Patchdatei in $SUPERX_DIR entpacken; die "alten" Dateien werden ersetzt. Wenn Sie die Datenbank und den Applikationsserver auf getrennten Systemen betreiben, dann entpacken Sie am besten die Update-Datei in einem temporären Verzeichnis und kopieren dann die Ordner /db und /webserver auf die entsprechenden Rechner.
SuperX ist zwar ein sehr offenes System, aber gewisse Konventionen werden sich in Zukunft als nützlich erweisen, wenn verschiedene Hochschulen Daten und Scripte austauschen wollen. In jedem Fall empfehlen wir Ihnen immer erst dann manuelle Anpassungen, wenn die Anwendung oder das Script funktioniert – eine äußerst sinnvolle Heuristik für die Arbeit mit SuperX.
Das Kernmodul wird in drei Arbeitsschritten installiert:
Die folgende Übersicht zeigt das Vorgehen bei der SuperX-Installation, darauf folgt eine Kurzanleitung für die Installationsmaßnahmen:
Schritt | Erläuterung |
Kopieren und Vorbereiten des Kernmoduls nach $SUPERX_DIR | Bringen Sie das SuperX-Kernmodul in ein Verzeichnis auf dem Rechner, am besten auf den Applikationsserver. Kopieren Sie die Datei $SUPERX_DIR/db/bin/SQL_ENV.sam nach $SUPERX_DIR/db/bin/SQL_ENV und passen Sie die Umgebungsvariablen an. |
Installation der erforderlichen Software |
|
Start des Datenbankservers | Starten Sie den Datenbankserver und spielen Sie danach die SuperX-Datenbank des Kernmoduls ein; die Zugangsparameter müssen Sie dem SuperX-Servlet bekannt geben. |
Start des SuperX-Servlets | Gehen Sie in das Verzeichnis /webserver/tomcat/bin und starten Sie Tomcat, ggf. als Dienst |
Test des Applikationsservers | Öffnen Sie die Datei http://-Rechnername-:8080/superx/ im Browser und testen Sie zuerst die Anmeldung |
Freigabe des Webservers im Netz | Nun ist die Basisinstallation vom Kernmodul abgeschlossen, und Sie können mit der Anpassung für Ihre Einrichtung beginnen. Richten Sie User ein, und geben Sie die WWW-Adresse Ihres Webservers im Intra- oder Internet (in diesem Fall benötigen Sie auch die die Verschlüsselung) frei. |
Einspielen der Module | Füllen Sie SuperX mit den einzelnen Modulen; bisherige SuperX-Anwender können ihr bisheriges System übernehmen. |
Wir empfehlen den Einsatz von SuperX unter Linux. Für andere Betriebssysteme gelten hier und da Besonderheiten.
Wenn Sie Ubuntu nutzen, können Sie auch den Tomcat und Postgres von Ubuntu nutzen. Dabei ist aber auf einiges zu achten. Bitte schauen Sie dafür bitte unter den Kapiteln für Übertragung der Webapplikation auf einen vorhandenen Tomcat unter Ubuntu und Postgres unter Ubuntu/Debian nach.
Für Kernmodul 6.0 werden OpenJDK 17 und Tomcat 10 verwendet. Die Installation aus den Paketquellen der Distribution stellt sicher, dass Aktualisierungen über die Paketverwaltung eingespielt werden können.
Hier zum Kopieren eine Liste von Paketen für Ubuntu 24.04 Server, die für DB- und Applikationsserver benötigt werden:
apt-get update apt-get upgrade -y apt-get install -y openssh-server apt-get install -y git apt-get install -y recode apt-get install -y zip apt-get install -y openjdk-17-jdk
Wenn Sie sich dann erneut einloggen sind Sie produktiver!
Aufbauend auf den allgemeinen Ubuntu-Paketen hier eine Liste von Paketen bzw. Konfigurationen für den DB-Server:
apt-get install -y postgresql apt-get install -y postgresql-contrib apt-get install -y gettext apt-get install -y gettext libreadline8 apt-get install -y gettext ibreadline-dev apt-get install -y gettext zlib1g apt-get install -y gettext zlib1g-dev apt-get install -y gettext libxml2 apt-get install -y gettext libxml2-dev apt-get install -y gettext libxslt1.1 apt-get install -y gettext libxslt1-dev locale-gen de_DE.UTF-8 update-locale LANG=de_DE.UTF-8
Aufbauend auf den allgemeinen Ubuntu-Paketen hier eine Liste von Paketen für den Applikationsserver:
apt-get install -y tomcat10 apt-get install -y sendmail apt-get install -y s-nail apt-get install -y curl apt-get install -y mail apt-get install -y dos2unix apt-get install -y postgresql-client
Wenn Sie einen separaten Webserver mit Apache betreiben wollen hier die Pakete:
apt-get install -y apache2 apt-get install -y libapache2-mod-jk apt-get install -y socat
Bei Red Hat Enterprise Linux, AlmaLinux und vergleichbaren Distributionen unterscheiden sich Paketnamen und Dienstverwaltung von Ubuntu und Debian. Das Apache-Paket trägt dort üblicherweise den Namen httpd.
Die folgende Kurzanleitung gilt für den häufigsten Fall des Betriebs von SuperX unter Ubuntu oder Debian mit PostgreSQL als DBMS und dem Betriebssystembenutzer superx.
Voraussetzungen | PostgreSQL ist gestartet. Der Datenbankbenutzer existiert und darf Datenbanken erzeugen. OpenJDK 17 und Tomcat 10 sind installiert. Die für HTTP und AJP konfigurierten Ports dürfen nicht durch andere Dienste belegt sein. |
Entpacken | Entpacken Sie das Kernmodul in dem zukünftigen $WEBAPP Verzeichnis (z.B. /home/superx/webapps/superx) tar -xzvf kern< |
Gehen Sie in das Verzeichnis $SUPERX_DIR/db/bin (z.B. /home/superx/webapps/superx/WEB-INF/conf/edustore/db/bin) cd $SUPERX_DIR/db/bin Kopieren Sie SQL_ENV.sam nach SQL_ENV cp SQL_ENV.sam SQL_ENV Passen Sie $SUPERX_DIR, $WEBAPP, $JAVA_HOME, $DATABASE, $SX_CLIENT, $LANG und $MAILPROG an. Starten Sie das Script mit . SQL_ENV und fügen Sie den Aufruf am Ende der Datei ~/.bashrc ein: . $SUPERX_DIR/db/bin/SQL_ENV |
Einspielen der Datenbank | Gehen Sie in das Install-Verzeichnis cd $SUPERX_DIR/db/install Starten Sie das Script kernmodul_erzeugen.x Bei Fehlern kommt eine Meldung, Protokolle stehen in create.log Damit ist die db-Seite eingerichtet. |
Steuerungsdatei für das Servlet: db.properties | Nun gehen Sie in das Verzeichnis cd $WEBAPP/WEB-INF Kopieren Sie db-postgres.properties nach db.properties: cp db-postgres.properties db.properties Starten Sie den PropAdmin mit propadmin.x Passen Sie hier den Servernamen, Datenbanknamen, Usernamen und Passwort an, und drücken Sie "Verbindung testen". Danach speichern Sie die Datei. |
Start von Tomcat | Nun wechseln Sie in das Verzeichnis cd $TOMCAT_HOME/bin Und starten tomcat mit startup.sh (Stop übrigens mit "shutdown.sh".) |
Und los geht’s... | Nach erfolgreichem Start rufen Sie im Browser auf: http://localhost:8080/superx/ Dort können Sie die Anwendung aufrufen und die Anmeldung testen. Ändern Sie ein gegebenenfalls noch vorhandenes Initialpasswort unmittelbar nach der Installation. |
Feineinstellung | Melden Sie sich in der Anwendung an und gehen Sie im Menü auf "Tabelle suchen", klicken einfach "Abschicken" und öffnen Sie die Tabelle hochschulinfo; dort sollten Sie Ihre Hochschule auswählen und "Speichern" anklicken, damit Ihre Hochschulnummer gespeichert wird. |
Zunächst muss aber der Datenbankserver eingerichtet werden. Derzeit laufen die Installationsscripte und auch alle Modulscripte nur unter UNIX /Linux.
Unterstütztes Datenbanksystem ist PostgreSQL. Technische Mindestversion ist PostgreSQL 12. Für Neuinstallationen wird PostgreSQL 16 oder neuer empfohlen.
SuperX wird mit UTF-8 betrieben. Prüfen Sie vor der Installation, ob die Betriebssystem-Locale auf UTF-8 eingestellt ist.
Die auf Ihrem System installierte Codierung erfahren Sie mit dem Befehl
echo $LANG
Je nach UNIX-System lautet die UTF-8-Locale beispielsweise de_DE.utf8 oder de_DE.UTF-8. Die verfügbaren deutschen Locales können Sie anzeigen mit:
locale -a | grep de
Mit dem SuperX-Kernmodul werden außerdem Scripte ausgeliefert, mit denen Dateien bei der Migration eines Altsystems von ISO nach UTF-8 konvertiert werden können. Weitere Hinweise finden Sie unter Codierung in ISO und UTF-8.
Unter Ubuntu und Debian können Sie die deutsche UTF-8-Locale mit folgenden Befehlen bereitstellen:
Tragen Sie dieselbe Locale in der SQL_ENV ein. Falls zusätzlich LC_ALL gesetzt ist, muss auch diese Variable auf eine UTF-8-Locale zeigen. Für die einmalige Migration älterer ISO-Dateien kann das Programm recode benötigt werden. Die zugehörigen Konvertierungsscripte sind unter Codierung in ISO und UTF-8 beschrieben.
Legen Sie einen User superx am einfachsten mit dem home-Verzeichnis /home/superx an.
Das Homeverzeichnis /home/superx dient als mögliches Basisverzeichnis der Installation. $SUPERX_DIR bezeichnet ab Kernmodul 6.0 dagegen den Bereich $WEBAPP/WEB-INF/conf/edustore innerhalb der SuperX-Webanwendung.
Es muss auf Betriebssystemebene sichergestellt werden, dass das Dateisystem Textdateien in der passenden Locale anlegt sind. Bei modernen UNIXen ist die Umgebungsvariable $LANG standardmäßig auf "UTF-8" gesetzt.
Setzen Sie die richtige Locale z.B. mit
LANG=de_DE.utf8; export LANG
Entpacken Sie das Kernmodul entsprechend der ausgelieferten Verzeichnisstruktur. Die Datenbankseite befindet sich anschließend unter $WEBAPP/WEB-INF/conf/edustore/db.
Machen Sie eine Kopie der Datei Date $SUPERX_DIR/db/bin/SQL_ENV.sam und nennen Sie sie einfach SQL_ENV. In dieser Datei werden viele allgemeine Konfigurationen der Umgebung vorgenommen. Prüfen Sie, ob die in der SQL_ENV angegebene Locale (LANG=de_DE...) existiert.
Geben Sie der Datei ggf. Ausführungsrechte mit chmod +x SQL_ENV.
Installieren Sie PostgreSQL über die Paketverwaltung der verwendeten Linux-Distribution. Dadurch können Sicherheits- und Wartungsaktualisierungen regulär eingespielt werden. Technische Mindestversion für SuperX ist PostgreSQL 12; für Neuinstallationen wird PostgreSQL 16 oder neuer empfohlen.
Unter Ubuntu oder Debian installieren Sie Server, Zusatzmodule und Client beispielsweise mit:
Eine manuelle Kompilierung von PostgreSQL aus dem Quellcode wird in dieser Dokumentation nicht mehr beschrieben.
Das PostgreSQL-Modul pgcrypto wird für kryptografische Funktionen verwendet und ist im Paket postgresql-contrib enthalten. Aktivieren Sie die Erweiterung in der SuperX-Datenbank:
SSL wird in postgresql.conf aktiviert und der Zugriff in pg_hba.conf gesteuert. Zertifikat und privater Schlüssel müssen für den PostgreSQL-Dienst lesbar sein; der private Schlüssel darf nur für den Eigentümer zugänglich sein. Verwenden Sie für ausschließlich verschlüsselte Verbindungen in pg_hba.conf die Direktive hostssl.
Für psql kann der SSL-Zugriff mit der Umgebungsvariable PGSSLMODE getestet werden:
Die JDBC-Verbindung wird in db.properties entsprechend für SSL konfiguriert. Mit DOQUERY "select * from xdummy" kann der Zugriff anschließend getestet werden.
Wenn der Datenbankserver auf einem anderen Rechner betrieben wird, genügt auf dem Applikationsserver das Clientpaket:
Für einen Datenbankserver installieren Sie zusätzlich Server und Zusatzmodule:
Die versionsbezogene Konfiguration liegt beispielsweise für PostgreSQL 16 unter /etc/postgresql/16/main. Starten, stoppen und laden Sie den Dienst mit systemctl:
Vorhandene Cluster und deren Ports zeigt folgender Befehl:
Prüfen Sie, ob der PostgreSQL-Dienst läuft und die Datenbanken UTF-8 verwenden:
Legen Sie den Datenbankbenutzer für SuperX mit den tatsächlich benötigten Rechten an. Der Benutzer der Webanwendung sollte aus Sicherheitsgründen kein PostgreSQL-Superuser sein.
Installieren Sie PostgreSQL unter Red Hat Enterprise Linux, AlmaLinux, SUSE Linux Enterprise Server und vergleichbaren Distributionen aus den jeweiligen Paketquellen. Paketnamen, Konfigurationspfade und Dienstnamen können abweichen. Verwenden Sie eine unterstützte PostgreSQL-Version, eine UTF-8-Locale und die Dienstverwaltung der jeweiligen Distribution.
Wichtige Parameter wie shared_buffers, effective_cache_size, work_mem und max_connections werden in postgresql.conf an die verfügbare Hardware und die Zahl paralleler Verbindungen angepasst. Verwenden Sie als Ausgangspunkt die Vorgaben der installierten PostgreSQL-Version und kontrollieren Sie die tatsächliche Auslastung. Führen Sie VACUUM und ANALYZE nicht über veraltete eigene Wartungsroutinen aus, wenn Autovacuum ordnungsgemäß konfiguriert ist.
Falls Sie für Testzwecke z.B. einen User "alex" anlegen wollen, der alle Tabellen einer DB lesen kann, geht dies mit Postgres so:
Zunächst müssen Sie in der pg_hba.conf sicherstellen, dass Passwort-Anmeldung über IP4 möglich ist:
# TYPE DATABASE USER ADDRESS METHOD host all all -IP-Nummernkreis- md5
Dann starten Sie Postgres neu oder führen einen RELOAD aus, z.B. unter Linux:
/etc/init.d/postgresql reload
Dann gehen Sie als Superuser auf den DB-Server, und führen Sie in der Ziel-Datenbank folgende SQLs aus:
CREATE USER alex WITH NOSUPERUSER PASSWORD 'password'; GRANT USAGE ON SCHEMA public TO alex; GRANT SELECT ON ALL TABLES IN SCHEMA public TO alex; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO alex;
Der letzte Befehl sorgt dafür, dass auch neue Tabellen Berechtigung erhalten.
Wenn Sie das Passwort später ändern wollen schreiben Sie
alter USER alex WITH PASSWORD 'anfang12';
Für die Installation haben wir unten eine Kurzanleitung vorbereitet. Das Kernmodul der Datenbank liegt exportiert vor und kann in das DBMS übernommen werden. Die nachfolgenden Installationschritte gehen davon aus, daß Sie keinen speziellen DBSpace für SuperX vorgesehen haben.
Das Installationsscript für die Datenbank befindet sich im Verzeichnis
$SUPERX_DIR/db/install/kernmodul_erzeugen.x -ggf. mit Name des DBSpace-
Das Script läuft nur, wenn die Parameter in der Datei $SUPERX_DIR/db/bin/SQL_ENV stimmen. Bei erfolgreichem Ablauf kommt eine Erfolgmeldung, im Falle eines Fehlers wird die Fehler-Logdatei create.log angezeigt. Wenn ein Fehler auftritt, müssen sie die Datenbank vor einem erneuten Ablauf des Scriptes droppen.
Danach können Sie mit psql superx (unter Postgres) testen, ob die Datenbank verfügbar ist.
Schließlich sollten Sie die Tabelle hochschulinfo anpassen und die Daten Ihrer Hochschule dort eingeben, insbesondere die Hochschulnummer (apnr-Wert in cifx mit key=36).
Vor dem Start der Update-Scripte sollte immer eine Sicherung der Datenbank erfolgen. Für Backups ist es notwendig, die Datenbank regelmäßig zu exportieren. Beide Datenbanken bieten entsprechende Werkzeuge.Es bietet sich an, einen cronjob einzurichten, der zuerst das Backup vornimmt, und dann die einzelnen Module nacheinander aktualisiert.
Ein Beispiel-Eintrag der crontab des users superx liegt in $SUPERX_DIR/db/module/crontab.sam. Ein Beispiel-Update-Script liegt in $SUPERX_DIR/db/module/update.x.sam . Der Eintrag in der crontab, der das Script werktags um 18:00 Uhr startet, sähe dann wie folgt aus:
# Täglicher SuperX-Update um 18 Uhr # 00 18 * * 1-5 /home/superx/webserver/tomcat/webapps/superx/WEB-INF/conf/edustore/db/module/update.x >/home/superx/webserver/tomcat/webapps/superx/WEB-INF/conf/edustore/db/module/update.log 2>&1
Ein Beispielinhalt für das Script update.x ist Teil des Kernmoduls: update.x
Ein Beispielscript, das die Datenbank sichert, liegt in $SUPERX_DIR/db/install/dump_it.x. Es erzeugt den Dump im Verzeichnis $SUPERX_DIR/db/install, prüft die erfolgreiche Sicherung und verschickt ggf. eine Fehler-Mail. Wenn Sie das Script in einem Cronjob betreiben wollen, müssen Sie als ersten Parameter $SUPERX_DIR übergeben.
Die Rücksicherung einer Datenbank ist mit dem Script $SUPERX_DIR/db/install/restore_it.x möglich.
Postgres lässt sich auch im laufenden Betrieb sichern.
pg_dump -f superx.sql superx
Noch kompakter ist der Dump als Binärfile mit dem Parameter --format=c:
pg_dump -f $DBNAME.sql --format=c $DBNAME
Sie können den Dump mit dem Parameter "--inserts" versehen, dies vergrößert den Dump beträchtlich. Dies ist eine sehr vorsichtige Einstellung, aber der Dump ist dadurch maximal kompatibel zu verschiedenen Postgres-Versionen, außerdem tauchen keine Probleme mit Umbrüchen in langen Textfeldern auf.
Wenn Ihnen die resultierenden Dumps zu groß sind, können Sie in einem eigenen Dump auf die Inserts verzichten (s.o.).
Wenn Sie die Verfügbarkeit des Datenbankservers getestet haben, dann müssen die Datenbankparameter in die Datei
$WEBAPP/WEB-INF/db.properties
übertragen werden, damit das Servlet eine Verbindung zur Datenbank herstellen kann. Die Musterdatei db-postgres.properties ist im Kernmodul enthalten und wird nach db.properties kopiert. Verwenden Sie für den Datenbankzugriff ein individuelles Passwort.
Zur Erstellung und ggfs. Änderung dieser Datei gibt es ein Tool:
propadmin.x
Das Shellscript liest aus der Umgebungsvariable $DB_PROPERTIES (oder über den ersten Parameter) den Speicherort der db.properties ein; in der Regel muss das die obige Position sein, damit das Servlet die Datei findet. Ausnahmen gibt es nur, wenn SuperX über den jdbc-Client auf eine andere Datenbank zugreifen soll.
Füllen Sie die Felder entsprechend des folgenden Beispiels (Postgres):
Hinweis für Postgres: Wenn Sie Postgres auf einem anderen Port als dem voreingestellten 5432 betreiben, müssen Sie im jdbc-Treiber als Connection-URL den Port wie folgt angeben:
connectionURL=jdbc:postgresql://localhost:-Portnumer-/superx
Durch Anklicken von OK wird die Datei db.properties (bzw. der Pfad zum Inhalt der Umgebungsvariable DB_PROPERTIES) erstellt, wobei das Passwort verschlüsselt wird. Vorher sollten Sie mit "Verbindung Testen" prüfen, ob eine Datenbankverbindung hergestellt werden kann. Wenn dies nicht klappt, sollten die Fehlermeldungen weiterhelfen.
Wenn Sie einen UNIX / LINUX-Server für Tomcat betreiben wollen, dann ist es möglich, daß Sie unter Linux keine graphische Java-Umgebung starten können. In diesem Fall müssen Sie das Kernmodul auf einem Rechner mit installiertem Java und graphischer Umgebung kopieren, das Programm dort aus der Konsole starten und die Parameter ändern (wichtig: der Rechner muss die gleiche Zeichenkodierung haben, also UTF-8). Danach kopieren sie die Datei db.properties mit scp / WinSCP auf den UNIX-Rechner. Alternativ können Sie die Parameter mit dem vi bearbeiten. Wenn der Propadmin ohne graphische Umgebung gestartet wird, kann lediglich das Passwort eingegeben werden.
Wenn Sie Tomcat auf einem anderen Rechner als dem Datenbankserver betreiben, müssen Sie die Startdateien propadmin.bat bzw. propadmin.x im Verzeichnis
$WEBAPP/WEB-INF
benutzen (in diesem Falle ist das Verzeichnis $SUPERX_DIR/db nicht notwendig.)
Die folgenden Anleitungen gehen davon aus, dass Sie als Installationspfade für den Applikationsserver C:\superx\webserver (unter win32) und /home/superx/webserver (unter UNIX / LINUX) gewählt haben. Sie können natürlich auch andere Pfade wählen, müssen dann aber die Pfade in dieser Dokumentation entsprechend umsetzen. Fehlende oder falsche Pfade bzw. Umgebungsvariablen sind in Java- und Datenbankprojekten eine wichtige Fehlerquelle (z.B. unter LINUX die Groß- / Kleinschreibung).
Für Kernmodul 6.0 wird OpenJDK 17 als Referenzversion verwendet. Unter Ubuntu 24.04 und Debian installieren Sie das JDK aus der Paketverwaltung:
Die für SuperX benötigten Java-Optionen werden zentral unter Die Umgebungssteuerung SQL_ENV dokumentiert.
Die Servlet-Engine ermöglicht dem Applikationsserver das SuperX-Servlet auszuführen. Anders als andere Scriptsprachen (z.B. asp, PHP, Perl) für Webserver ist der Java-Code als Bytecode kompiliert; die Servlets werden normalerweise also nicht auf dem Webserver entwickelt und getestet, sondern auf einem eigenen Entwicklungsrechner.
Unsere Referenz für Servlet-Engines ist Tomcat. Kernmodul 6.0 benötigt Tomcat 10. Tomcat 8 und Tomcat 9 werden dafür nicht mehr unterstützt.
Installieren Sie Tomcat möglichst aus der jeweiligen Linux-Distribution, damit Sicherheitsaktualisierungen über die Paketverwaltung eingespielt werden können. Alternativ kann eine aktuelle Tomcat-10-Distribution direkt vom Hersteller verwendet werden.
Sie können Tomcat auch direkt vom Hersteller herunterladen.
Die Installation von Tomcat für SuperX wird auf einer eigenen Website beschrieben. Die weitere Konfiguration ist im Folgenden beschrieben.
Editieren Sie zunächst die Konfigurationsdatei:
$TOMCAT_HOME/conf/server.xml
Hier werden die Ports und Anbindungen der Tomcat-Installation angepasst. Häufig wird der HTTP-Connector auf Port 8080 und die Apache-Anbindung über AJP auf Port 8009 betrieben. Der Shutdown-Port ergibt sich aus dem port-Attribut des Server-Elements und kann bei aktuellen Installationen mit port="-1" deaktiviert sein.
Wichtig beim Betrieb des Tomcat mit UTF-8-Codierung: Der jew. Connector muss das weitere Attribut URIEncoding="UTF-8" aufführen. Wenn z.B. der Connector 8080 genutzt wird, sieht das so aus:
Dies ist wichtig für den Ajax-Client.
Nach einer Änderung müssen Sie Tomcat neu starten.
Wenn Sie mod_jk nutzen, müssen der AJP-Connector in server.xml und der zugehörige Worker in workers.properties zusammenpassen. Bei Apache und Tomcat auf demselben Server sollte der Connector nur an eine Loopback-Adresse gebunden werden. Das folgende Beispiel verwendet IPv4:
In workers.properties müssen worker.host, worker.port und das Secret dieselben Werte verwenden. Bei einer Änderung an server.xml ist Tomcat neu zu starten. Nach einer Änderung an workers.properties muss zunächst die Apache-Konfiguration geprüft und anschließend Apache neu geladen oder neu gestartet werden.
Weitere Details siehe Tomcat-Leitfaden.
Die Datenbankverbindung für DBFORMS wird in der Datei $WEBAPP/WEB-INF/dbforms-config.xml definiert. Für Kernmodul 6.0 muss die Datei folgende Definition enthalten:
Nach einer Änderung muss Tomcat neu gestartet werden.
In der Datei $TOMCAT_HOME/conf/web.xml sie u.a. die serverweite "Welcome-Page" bzw. deren Reihenfolge., welche wiederum Dateien anzeigen, wenn der Anwender ein Verzeichnis ohne Dateinamen aufruft, z.B. http://servername/superx/:
Wenn Sie z.B. die Reihenfolge so ändern, dass zuerst die Datei index.jsp angezeigt wird (sofern sie existiert), dann können Sie eigene "Homepages" definieren, die nicht von der SuperX-Distribution (z.B. bei Updates) überschrieben würden. Außerdem ist dies eine sinnvolle Sicherheitsmassnahme, weil so keine Directory Listings angezeigt werden.
Änderungen in der Datei web.xml in der Webanwendung ( -Webanwendung-/WEB-INF/web.xml) überschreiben die Einträge in der serverweiten web.xml.
Weitere Konfigurationsmöglichkeiten (Server Side Includes etc). sind in dieser Datei dokumentiert.
Vergleiche auch den unten folgenden Abschnitt zur Einrichtung der SuperX-Servlets unter Tomcat.
In der Tomcat Auslieferung gibt es Beispiel-Webanwendungen, bitte löschen Sie diese.
Die Datei $WEBAPP/WEB-INF/web.xml enthält die Konfiguration der Webanwendung, z.B. maximale Zeilenanzahl bei Berichten. Diese Datei wird initial ausgeliefert, bei Upgrades des Kernmoduls aber nicht automatisch überschrieben. Im Zweifelsfall stellen Sie die Auslieferungsdatei wieder her, es Muster dafür befindet sich in der Datei $WEBAPP/WEB-INF/web.xml.superxonly.
Eine Änderung in der web.xml macht einen Tomcat-Neustart erforderlich. Achten Sie auf eine wohlgeformte XML-Notation. Wenn die Datei nicht wohlgeformt ist, kann die Webanwendung nicht gestartet werden. Verwenden Sie im Zweifelsfall die mit Kernmodul 6.0 ausgelieferte Datei web.xml.superxonly als Grundlage und übernehmen Sie anschließend nur die benötigten lokalen Anpassungen.
Für SuperX-Standalone-Betrieb (also unabhängig von HisInOne) ist ab Kernmodul 5.0 der context-Parameter zentral
Anpassen der Datei db.properties mit den Datenbank-Zugangsdaten (siehe oben Anpassen der Datenbankparameter für das SuperX-Servlet) ist Voraussetzungen dafür, dass der Applikationsserver auf die Datenbank zugreifen kann.
In der web.xml werden im SuperXManager Servlet einige wichtige Konfigurationen vorgenommen. Zentrales Servlet ist der SuperXManager, für den ein Eintrag benötigt wird.
Im folgenden werden einige Parameter beschrieben:
Default für Response Compression ist true, dann braucht der init-param auch nicht angegeben zu werden. Die RTWH Aachen nutzt allerdings einen ReverseProxy der mit der gzip-Kompression nicht klar kam, in diesem Fall kann man durch setzen des ResponseCompression-Initparams mit param-value=false die Kompression ausschalten.
Der field1Cache kann Inhalte von Auswahllisten der Feldart 1 zwischenspeichern.
Wenn ein entsprechender init-param beim SuperXManager definiert ist, lädt sich der webserver beim Start Inhalte für die angegeben Felder der Feldart 1 (aus felderinfo), in denen es keine dynamischen Tags gibt (wie z.B. < Als Param-value muss eine where-Bedingung für einen select auf die Tabelle felderinfo angegeben werden. Sie können das Beispiel tid>10000 belassen oder bei Bedarf bestimmte Felder auslassen, z.B. Der Cache wird aktualisiert, wenn im SuperXManager-Servlet auf den Button “Server-Cache aktualisieren” geklickt wird oder der Webserver neu gestartet wird. Außerdem wird er jeden Morgen einmal automatisch aktualisiert. Felder die sich zusätzlich zu den nächtlichen Updates dynamisch ändern, sollten ausgeschlossen werden, damit sie immer aktuell aus der Datenbank geholt werden. Ein weiterer Parameter für die gesamte Webapplikation, der aber nur im XML-Frontend ausgewertet wird, lautet Der CSV-Export von Masken verwendet standardmäßig UTF-8. Eine abweichende Codierung sollte nur für ausdrücklich benötigte Altschnittstellen konfiguriert werden. Nach einer Änderung an der web.xml müssen Sie Tomcat neu starten. Sie können auch durch spezielle Fehlerseiten die normale Fehlerausgabe des SuperX-Servlets sperren. Fügen Sie an das Ende der web.xml vor dem End-Tag "" z.B. folgende Elemente ein ... Die ist die Voreinstellung bei Neuinstallation von SuperX, ältere Installationen müssen dies ggf. nachholen. Sie können auf verschiedene Fehler-Codes sowie Exception-Types eigene Fehlerseiten definieren. Details dazu finden Sie in der Dokumentation Ihres Applikationsservers. Vor dem Start müssen die Umgebungsvariablen der Datei $SUPERX_DIR/db/bin/SQL_ENV geladen werden. Das Terminal-Fenster zeigt den Port an, auf dem Tomcat läuft, z.B. 8080; um die Engine zu testen, kann man einen Webbrowser (zur Not auch lynx) starten und die Seite http://localhost:8080/... aufrufen. Beendet wird Tomcat mit dem Befehl: shutdown.bat für MS-DOS bzw. shutdown.sh für UNIX. Wenn Sie die SuperX-Webapplikation auf einem vorhandenen Tomcat installieren wollen, folgen Sie dem Leitfaden auf der Seite http://www.superx-projekt.de/doku/kern_modul/tomcat/f_TomcatausLinuxDistributionen.htm Es ist möglich, die Authentifizierung von Usern über eine LDAP-Datenbank laufen zu lassen. Die User müssen aber auf jeden Fall in SuperX auch existieren und entsprechende Gruppenzugehörigkeiten und Rechteeinstellungen haben (Tabellen userinfo, groupinfo, user_group_bez, user_masken_bez,group_masken_bez,user_sachgeb_bez,group_sachgeb_bez, user_sichten etc). Falls Sie ein eigenes Zertifikat für die Verschlüsselung Ihres LDAP-Servers einsetzen, muss dies importiert werden in die Java Runtime. Danach müssen Sie das Zertifikat auch der JVM bekannt machen, die Tomcat startet. Ergänzen Sie die zentral unter Die Umgebungssteuerung SQL_ENV dokumentierten Java-Optionen um folgenden installationsspezifischen Parameter: also z.B. Kopieren Sie die Datei superx/WEB-INF/superx_standalone_ldap.properties.sam nach superx_standalone_ldap.properties und bearbeiten Sie diese – wenn SuperX beim Serverstart diese Datei findet, wird eine neue SuperX-interne LDAP-Passwortkontrolle aktiviert. Sie finden auch in der catalina.out einen Hinweis „Passwortkontrolle via LDAP wird aktiviert“. Die Passwortkontrolle erfolgt über die SuperX-interne LDAP-Anbindung. In der sam-Datei ist eine Verbindung zu einem öffentlichen LDAP-Testserver vorkonfiguriert. Dort gibt es einen User „einstein“ mit Passwort „password. Wenn Sie in SuperX einen User „einstein“ anlegen und ein anderes Passwort wie „albert“, können Sie sich nach einer Aktivierung von LDAP mit „einstein“ und „password“ anmelden. Optional können Sie bei Bedarf zusätzlich einen komplexeren Searchfilter definieren,z.B. Wenn für einen Testbenutzer oder durch andere Gegebenheiten für einen Benutzer keine LDAP Kennzung zur Verfügung steht, kann ab Kernmodul 5.2 für die index.jsp der Parameter login=superx angegeben werden. Als Beispiel: Damit wird dann für die verwendete Kennung das Passwort aus der userinfo von SuperX geprüft. Es ist möglich, die Authentifizierung der Benutzer über ein Shibboleth Single Sign-On (SSO) durchzuführen. In diesem Fall erfolgt der eigentliche Login über das Shibboleth-System, während SuperX weiterhin für die Verwaltung der Benutzerrechte zuständig ist. Auch bei Verwendung von Shibboleth müssen die Benutzer in SuperX vorhanden sein. Die Rechteverwaltung erfolgt weiterhin innerhalb von SuperX. Nach erfolgreicher Anmeldung über Shibboleth wird die Benutzerkennung an SuperX übergeben. SuperX verwendet diese Kennung, um den entsprechenden Benutzer zu identifizieren und automatisch anzumelden. Wichtig dabei ist: Die Benutzerkennung muss in SuperX exakt so benannt sein wie die vom Shibboleth-System übergebene Kennung. Nur wenn die Kennung übereinstimmt, kann SuperX den Benutzer korrekt zuordnen. Beim Einsatz von Shibboleth reicht der normale Logout innerhalb von SuperX nicht aus, da zusätzlich die Session des Shibboleth Service Providers beendet werden muss. Dazu wird ein spezieller Logout-Link verwendet: https://< Dieser Link beendet die Shibboleth-Session und leitet anschließend auf eine definierte Seite weiter. Damit der Logout korrekt funktioniert, muss das entsprechende Template in die Datei kopiert werden. Beim Logout-Link ( Die Servlet-Engine Tomcat verfügt zwar über einen kleinen "eingebauten" Webserver, doch für den Echtbetrieb sollte man aus Performance-Gründen einen der marktgängigen Webserver nutzen (z.B. Apache, IIS), der auch Verschlüsselung bietet. Für den Echtbetrieb empfehlen wird die Installation eines Apache, meist ist dieser in der Linux-Distribution bereits integriert. Der Apache läßt sich sehr gut mit dem Tomcat verbinden . Weitere Details siehe unser Tomcat-Leitfaden. An mehreren Stellen können Sie mit SSL Verschlüsselung in Berührung kommen: Im folgenden eine Anleitung zum Erzeugen und Bereitstellen von Zertifikaten. Auf dem Rechner, der verschlüsseln soll, muss das Paket Openssl installiert sein. Ist dies der Fall, kann man als User root ein Zertifikat erzeugen. Wir führen alle Schritte als user root durch, und gehen z.B. davon aus, dass wir uns im Verzeichnis /root befinden. Zunächst muss ein Zertifikat erzeugt werden: Sie die jeweiligen Angaben (Land, Organisation etc.). Beim "Common Name" muss der DNS-Servername des Servers angegeben werden. Ein Challenge Passwort ist erst einmal nicht notwendig. Der private Schlüssel ist nicht geschützt, sonst müßten Sie den bei der Nutzung (z.B. Apache Start) manuell eintippen. Der private Schlüssel liegt in /root/mydomain.key Der öffentliche Schlüssel hat das RSA Format. In Java Runtimes und im Browser wird ggf. nur ein X.509 Zeirtifikat erlaubt. Dazu müssen Sie das öffentliche Zertifikat zuerst in das entsprechende DER-Format konvertieren: Es wird die Datei /root/capub.crt erzeugt. Alternatives Vorgehen unter Ubuntu mit Ziel Zertifikat für Postgres: Eine passphrase ist nicht hilfreich, wenn Server automatisch neu gebootet werden können soll. So kann man eine Entfernen: https://knowledge.digicert.com/solution/SO5292.html Sie können ein neues Zertifikat erstellen und direkt einen Request für eine Zertifizierungsstelle erzeugen. Der Schlüssel sollte mind. 2048 bit haben. Das geht mit dem Befehl: Es wird ein Request in die Datei ./mein_request.csr geschrieben. Letzteren übergeben Sie an die Zertifizierungsstelle. Achten Sie dabei darauf, dass die Angabe bei "Common Name" exakt dem Domainnamen entspricht. Wie uopenssl req -new -nodes -newkey rsa:2048 -keyout mydomain.key -out mein_request.csrnd in welchem Format Sie die Anfrage an die von Ihnen ausgewählte Zertifizierungsstelle senden müssen, erfahren Sie von der entsprechenden Zertifizierungsstelle. Wenn Client Programme wie z.B. Java auf einen SSL verschlüsselten Server zugreifen, der über ein selbst signiertes Zertifikat verfügt, dann muss man das Zertifikat in den TrustStore von Java bzw. Tomcat importieren. Es gibt einen systemweiten Truststore , wenn Sie das systemweiten TrustStore von Java verwenden, liegt dies in $JAVA_HOME/jre/lib/security/cacerts. Dann würde der Befehl lauten: Ggf. müssen Sie hier das Passwort des keystore eingeben (Standard wenn nicht verändert: changeit) . Danach kommt die Sicherheitsabfrage Wenn Sie für Tomcat einen speziellen Truststore definieren, z.B. durch den Tomcat Start Parameter dann müssen Sie den Zielpfad für den Import entsprechend anpassen: Achtung: Wenn Sie eine eigene Datei als keystore nutzen wollen, gibt es in manchen Tomcat/Java Konstellationen Probleme, z.B. bei Tomcat 7.0.22 und jdk1.7.0_51. Verwenden Sie in diesem Falle besser den Default ($JAVA_HOME/jre/lib/security/cacerts ). Falls Sie das Zertifikat des Ziel-Servers nicht zur Hand haben, können Sie es auch direkt herunterladen. Gehen Sie im Browser auf die entsprechende URL und klicken Sie vor der URL auf das Schlüsselsymbol. Dort gehen Sie auf "Zertifikat anzeigen" -> Details. Je nach Browser/Version heißen die Menüpunkte unterscheidlich. Bei der Detailansicht des Zertifikats gibt es einen "Exportieren" Button. Hier ein Beispiel für Firefox: Die Zieldatei bekommt eine Endung "*.crt". Alternativ geht auch die Linux Kommandozeile: Falls Das Zertifikat in x509 format benötigt wird, bitte folgenden Befehl verwenden: Danach können Sie das Zertifikat importieren mit Der Befehl keytool ist recht flexibel, man kann damit auch Zertifikate anschauen (-list) oder löschen (-delete). Details liefert die Ausgabe von keytool -help. Zum Mailversand von Logmails installieren Sie ein UNIX Mailprogramm. Unter Ubuntu Linux ist dies z.B. s-nail, das ein Binary namens "s-nail" bereitstellt: Standardmäßig sucht s-nail den SMTP Server auf localhost, typischerweise muss ein externer Mailserver angebunden werden. Dazu legen sie im Homeverzeichnis des Benutzers eine Datei ".mailrc" an. Der Inhalt z.B. Hinweis: es gibt auch andere Mailclients wie mutt oder mailx, wir haben s-nail gewählt weil die Syntax der obigen .mailrc-Datei und z.B. bzgl. den Anfügens von Attachments (z.B. für Logdateien) nach dem klassischen "mailx" orientiert ist. Letzteres wird nicht mehr weiterentwickelt. Sie können den Mailversand dann testen z.B. mit Sie können auch Mailverteiler einrichten, mit dem Befehl alias: Sie können den Alias als Adressaten verwenden, z.B. mit An einigen Hochschulen gibt es ein Testsystem in dem Entwicklungen getestet werden und ein Produktivsystem in dem die stabilen Entwicklungen dann übertragen werden. Die Schwierigkeit bestand bisher, beide Systeme auf einen vergleichbaren Stand zu halten, damit das Testsystem auch einem reellen Test widerspiegelt. Außerdem gab es keine einfache Möglichkeit größere Änderungen vom Testsystem ins Produktivsystem zu übertragen. Um diese Möglichkeit zu erhalten gibt nun wie in allen anderen Modulen auch im Kernmodul eine Hauptladeroutine mit unload- und update-Funktion. Über die Bordmittel der Laderoutinen (Unload / Copy / Upload) können also Konfigurationen übertragen werden. Details zu den Laderoutinen jeweils für Im Kontext der Säulenübertragung in HISinOne kann neben der Copy-Funktion auch SVN / Git genutzt werden, Sie müssen dazu nur die Dateien aus dem SVN-Ignore /GIT-Ignore entfernen, auf dem Entwicklungssystem committen und auf der Zielsäule updaten. Über die Entladeparameter können Sie steuern, welche Daten übertragen werden sollen. Hier gibt es default-Werte, die Sie in der KERN_ENV selber anpassen können. Falls Sie keine angaben dazu in der KERN_ENV machen, werden die default-Werte verwendet. UNLOAD_USERRIGHTS Hier handelt es sich um die Benutzerrechte aus dem Kernmodul. Es werden also die Benutzer, Gruppen, Sichtenrechte... übertragen. Spezielle Rechte wie die Kameralen Rechte des FIN Moduls sind hier nicht mit inbegriffen. UNLOAD_FIN_USER_KAM Hierbei handelt es sich nur im die Kamerale Rechte des FIN Moduls. UNLOAD_KONSTANTEN Hierbei handelt es sich um die Konstanten. UNLOAD_UNLOAD_PARAMS Hierbei handelt es sich um die Entladeparameter. UNLOAD_REPOSITORY Hierbei handelt es sich um die Repository Variablen UNLOAD_HOCHSCHULINFO Hierbei handelt es sich um die Tabelle Hochschulinfo mit Informationen wie Name, Anschrift... der Hochschule. UNLOAD_THEMENBAUM Hierbei handelt es sich um die Menüstruktur des Informationssystems. UNLOAD_MASKEN Hierbei handelt es sich um alle Berichte. UNLOAD_STYLESHEETS Hierbei handelt es sich um die Styles der Breichte. Achtung: Es werden nur die Datenbankeinträge übertragen keine Dateien aus dem Dateisystem. Die Stylesheets müssen daher extra kopiert werden. UNLOAD_MAKROS Hier werdne die Makros übertragen. UNLOAD_CAPTIONS Hierbei handelt es sich um die Beschreibungen von Feldern, Erläuterungstexten ... UNLOAD_SICHTEN Heirbei handelt es sich um die Sichten UNLOAD_MAN_CATALOGUE Hierbei handelt es sich um den Zahlenkatalog des MAN Moduls. UNLOAD_MAN_ZAHL_WERT Hierbei handelt es sich um eigene Werte der Hochschule für das MAN Modul. UNLOAD_KENN_ZAHL_WERT Hierbei handelt es sich um eigene Werte der Hochschule für das KENN Modul. Wie üblich muss in der SQL_ENV die DB Verbindung eingerichtet werden und auch die Entladeparameter. Über die Scripte kern_unload.x werden dann die Tabellen aus dem jeweils anderen SuperX entladen und per kern_update.x in das verwendete SuperX eingespielt. Ein Upgrade einer bestehenden SuperX-Installation muss vorbereitet werden, da lokale Konfigurationen und hochschulspezifische Anpassungen nicht durch ein Komplettpaket überschrieben werden dürfen. Sichern Sie vor dem Upgrade die PostgreSQL-Datenbank, die Rollen und das Dateisystem der bestehenden Installation. Laden Sie das zur vorhandenen Installation passende Upgrade- bzw. Patch-Paket von download.superx-projekt.de herunter. Informationen zu den Änderungen befinden sich auf der Downloadseite und in der mitgelieferten Readme-Datei. Kernmodul 6.0 verwendet PostgreSQL, UTF-8 und die Webapp-Verzeichnisstruktur. Patches werden mit dem Script $SUPERX_DIR/db/bin/patch_apply.x direkt aus dem Patchverzeichnis eingespielt:tid > 10000 and name not in ('Haushaltsjahr','Semester').
Start des Tomcat
Die Umgebungsvariable JAVA_HOME muss korrekt gesetzt sein
Die Übertragung der Web Application
LDAP Anbindung
Zertifikat einspielen
-Djavax.net.ssl.trustStore=<
-Djavax.net.ssl.trustStore=/usr/local/tomcat/conf/cacerts
Anpassen der superx_ldap.properties
# SuperX LDAP Konfiguration für Passwortkontrolle
#Falls SuperX standalone betrieben wird, können hier LDAP Parameter hinterlegt werden
# Beispielparameter verwenden
# https://www.forumsys.com/tutorials/integration-how-to/ldap/online-ldap-test-server/
# Beispieluser auf diesem System einstein Passwort=password
# Wenn Sie in Superx einen User mit Kennung einstein anlegen, können Sie die Anmeldung via LDAP # testen
LdapUrl=ldap://ldap.forumsys.com:389
#
#Base Definition für die LDAP Suche, kann ggfs. um Gruppen erweitert werden, wie
# ou=superx_user,dc=example,dc=com
LdapBase=dc=example,dc=com
#
#Falls für den LDAP Zugriff ein ServiceUser (mit eigenem Passwort) benötigt wird, kann dies hier angegeben werden
#LdapServiceUserDN=cn=read-only-admin,dc=example,dc=com
#LdapServiceUserPassword=password
#
# Identifiying Attribute mit dem ein User mittels seiner Kennung gefunden wird (z.B. uid)
# z.B. bei Suchstring uid={0} einfach nur uid
LdapIdentifyingAttribute=uid
LdapSearchFilter=(&(uid=${0})(status=aktiv))
Trotz LDAP lokalen Login aktivieren
.../superx/index.jsp?login=superx
Shibboleth Anbindung
Voraussetzungen
Benutzerkennung
Logout
Einbindung in das SuperX-Template
pageComponents_html_final.xs
href) wird dort die oben genannte Shibboleth-Logout-URL eingetragen.Integration von Tomcat mit dem Apache
Umgang mit SSL Verschlüsselung
Erzeugen eines SSL Zertifikats
openssl req -new -nodes -newkey rsa:2048 -keyout mydomain.key -out mydomain.csr
openssl x509 -in mydomain.key -out capub.crt -outform DER
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365
openssl rsa -in [file1.key] -out [file2.key]
Erzeugen eines Zertifikat-Request für eine Zertifizierungsstelle
openssl req -new -nodes -newkey rsa:2048 -keyout mydomain.key -out mein_request.csr
Importieren des Zertifikats in Java
sudo keytool -import -alias myssl -file /root/capub.crt -keystore $JAVA_HOME/jre/lib/security/cacerts
Diesem Zertifikat vertrauen? [Nein]: Ja
Zertifikat wurde zu Keystore hinzugefügt.
-Djavax.net.ssl.trustStore=/usr/local/tomcat/conf/cacerts
sudo keytool -import -alias myssl -file /root/capub.crt -keystore /usr/local/tomcat/conf/cacerts
In der HISinOne-BI kann der TrustStore in der globalen Konfiguration im Parameter KEYSTORE=... gesetzt werden. Das Vorgehen wäre hier analog.
openssl s_client -connect meinserver.de:443 -servername meinserver.de:443 < /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' < /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' >
openssl x509 -in <(openssl s_client -connect ads.hs-karlsruhe.de:636 -prexit 2<(openssl s_client -connect ads.hs-karlsruhe.de:636 -prexit 2>
$JAVA_HOME/bin/keytool -importcert -alias myssl -keystore $JAVA_HOME/jre/lib/security/cacerts -trustcacerts -file ./my-ca.crt
Mailversand
apt-get install -y s-nail
set smtp="smtp://smtp.meinmailserver.de:587"
set from="superx@localhost"
set smtp-auth=login
set smtp-auth-user="meinemailkennung"
set smtp-auth-password=meinpasswort
echo test | s-nail -s Testbetreff supervisor@meinmailserver.de
alias sxadmin supervisor1@meinmailserver.de supervisor2@meinmailserver.de
echo test | s-nail -s Testbetreff sxadmin
Test- und Produktivsystem synchronisieren
webapps/superx/WEB-INF/conf/edustore/db/install/rohdaten/unl/*.unl
Entladeparameter
Ausführung
Upgrade einer bestehenden SuperX-Installation
Patch einspielen
Je nach Patch kann anschließend ein Tomcat-Neustart erforderlich sein. Beachten Sie dazu die Hinweise der jeweiligen Patch-Dokumentation. Weitere Hinweise finden Sie unter Patch einspielen.
Beenden Sie Tomcat und erstellen Sie eine Sicherung der Datenbank:
Entpacken Sie das passende Upgrade-Paket und führen Sie anschließend die Upgrade-Scripte aus:
Das erneute Laden der SQL_ENV nach kern_env_upgrade.x ist erforderlich, damit die aktualisierte Umgebung für kern_upgrade.x verwendet wird. Starten Sie Tomcat nach Abschluss des Upgrades neu.
Kernmodul 6.0 benötigt Tomcat 10 und wird mit OpenJDK 17 betrieben. Die folgenden Schritte ergänzen das Standardvorgehen insbesondere für Ubuntu und Debian.
Beenden Sie vor dem Umbau Tomcat und gegebenenfalls Apache. Sichern Sie die PostgreSQL-Datenbanken und Rollen sowie die bestehende SuperX-Installation. Prüfen Sie vor dem späteren Entfernen einer alten PostgreSQL-Version, ob die Datenbanken vollständig in den neuen PostgreSQL-Cluster übernommen wurden.
Unter Ubuntu 24.04 und Debian können Java 17 und Tomcat 10 aus der Paketverwaltung installiert werden:
Legen Sie bei Bedarf das Tomcat-Homeverzeichnis und die von Kettle verwendeten Dateien an und vergeben Sie die erforderlichen Rechte für den Tomcat-Benutzer.
Die vollständigen JAVA_OPTS und CATALINA_OPTS werden ausschließlich unter Die Umgebungssteuerung SQL_ENV gepflegt. Übernehmen Sie die dort dokumentierte Konfiguration je nach Installation in die SQL_ENV, nach /etc/default/tomcat10 oder in die Startkonfiguration des eigenen Tomcat.
Ab Kernmodul 6.0 befindet sich die Datenbankseite unter $WEBAPP/WEB-INF/conf/edustore. Für die Migration einer bestehenden Installation wird empfohlen, das im Projekt BI Maintenance bereitgestellte Migrationsskript zu verwenden. Das Script übernimmt die Umstellung auf die Webapp-Struktur kontrolliert und sollte bevorzugt eingesetzt werden, wenn BI Maintenance vorhanden ist.
Alternativ kann das bisherige db-Verzeichnis bei beendetem Tomcat manuell verschoben werden. Die Variablen müssen zuvor auf die vorhandene Installation gesetzt werden:
Setzen Sie anschließend die zentralen Variablen:
Prüfen Sie danach Cronjobs, Modul-Update-Scripte, systemd-Dienste, .bashrc, .profile und eigene Shellscripte auf alte Pfade wie /home/superx/db oder Verweise auf Tomcat 9. Die SQL_ENV liegt in der neuen Struktur unter $SUPERX_DIR/db/bin/SQL_ENV.
Bei einem Distributionsupgrade kann PostgreSQL 16 zusätzlich zu einem älteren PostgreSQL-Cluster installiert werden. Prüfen Sie die vorhandenen Cluster und Ports:
Ein parallel angelegter Cluster kann zunächst Port 5433 verwenden. Passen Sie entweder den Port des neuen Clusters kontrolliert an oder übernehmen Sie den tatsächlichen Port in db.properties und den JDBC-Verbindungsangaben. Entfernen Sie die alte PostgreSQL-Version erst nach erfolgreicher Migration und vollständigem Anwendungstest.
Tomcat 10 verwendet die Jakarta-Servlet-API. Der JDBC_CLASSPATH muss deshalb die Jakarta-Bibliothek enthalten:
Ein veralteter Classpath mit servlet-api.jar kann bei Kernmodul-Scripten zu folgender Fehlermeldung führen:
Laden Sie nach einer Änderung die SQL_ENV erneut.
Verwenden Sie die zu Kernmodul 6.0 gehörende web.xml.superxonly als Grundlage und übernehmen Sie anschließend die erforderlichen lokalen Anpassungen. Die Datei $WEBAPP/WEB-INF/dbforms-config.xml muss den Spring Connection Provider verwenden:
Nach Änderungen an web.xml oder dbforms-config.xml ist ein Tomcat-Neustart erforderlich.
Der Tomcat-Prozess benötigt Leserechte auf die SuperX-Webanwendung und Ausführungsrechte auf allen übergeordneten Verzeichnissen. Prüfen Sie die vollständige Verzeichniskette beispielsweise mit:
Dateien müssen für den Tomcat-Benutzer oder die Tomcat-Gruppe lesbar sein. Verzeichnisse, in die Tomcat schreibt, benötigen zusätzlich Schreibrechte. Vergeben Sie keine pauschalen Rechte mit chmod -R 777.
Wenn Apache über mod_jk mit Tomcat verbunden ist, müssen server.xml und workers.properties aufeinander abgestimmt sein:
Bei Apache und Tomcat auf demselben Server sollte der AJP-Connector nur an 127.0.0.1 oder ::1 gebunden werden. Eine Bindung an 0.0.0.0 ist nur erforderlich, wenn ein externer Apache zugreifen muss und der Zugriff entsprechend abgesichert ist.
Bei Load-Balancer-Installationen muss das Attribut jvmRoute im Engine-Element zur Route beziehungsweise zum Namen des zugehörigen Workers passen:
Nach Änderungen an server.xml starten Sie Tomcat neu. Nach Änderungen an workers.properties prüfen Sie zunächst die Apache-Konfiguration und laden Apache anschließend neu:
Falls Apache deaktiviert wurde, muss der Dienst vor dem Anwendungstest wieder aktiviert und gestartet werden.
Prüfen Sie eigene Login-Seiten, Portlets und angepasste Anmeldeformulare darauf, ob noch der veraltete Parameter alt_redirect_url verwendet wird. Entfernen Sie einen vorhandenen Eintrag beim Upgrade auf Kernmodul 6.0:
Aktivieren und starten Sie Tomcat 10 nach Abschluss der Anpassungen:
Prüfen Sie anschließend die direkte Tomcat-Verbindung und, sofern vorhanden, den Zugriff über Apache beziehungsweise den Load Balancer.
Es gibt verschiedene Szenarien zur Migration von SuperX, hierzu werden Empfehlungen gegeben.
Unter Postgres bietet es sich an, von Postgres ISO-Codierung zu Postgres-UTF-8 Codierung zu wechseln. Für die Umsetzung der Zeichencodierung von Dateien gibt es in Postgres eingebaute Unterstützung: Wenn ein Text-Dump einer ISO-Datenbank erzeugt wird, dann steht im Kopf der Datei die Encodierung. Wenn man diese Datei mit psql in eine UTF-8-DB füttert, wird automatisch von ISO nach UTF-8 konvertiert. Für die Umcodierung der Datenbank hat sich also folgendes Vorgehen bewährt:
Exportieren Sie die ISO-Datenbank mit pg_dump im Format "plain text". Es wird eine sql-Datei erzeugt, im folgenden Beispiel für die Datenbank mit dem Namen "$DBNAME":
pg_dump -f $DBNAME.sql $DBNAME
Falls Sie direkt beim Dump eine zip-Datei erzeugen wollen, nutzen Sie folgendes Script:
vpg_dump $DBNAME | gzip >$DBNAME.sql.gz 2>dump.err
Wechseln Sie dann in eine Postgres-Installation, die UTF-8 unterstützt, und erzeugen Sie die Datenbank neu:
createdb --encoding=UTF-8 $DBNAME
Dann importieren die Datenbank mit:
psql $DBNAME < $DBNAME.sql
Danach müssen Sie alle Dateien unterhalb von $SUPERX_DIR von ISO nach UTF-8 konvertieren. Bitte fertigen Sie zunächst eine Sicherung des Dateisystems unterhalb von $SUPERX_DIR an.
Zum Konvertieren stehen die Shellscripte des SuperX-Kernmoduls zur Verfügung:
cd $SUPERX_DIR sx_list_isofiles.x . >iso.txt sx_recode_isofiles.x iso.txt
Am Ende müssen Sie noch in der Datei $SUPERX_DIR/db/bin/SQL_ENV die Variable LANG auf die UTF-8-Codierung setzen. Führen Sie dazu
locale -a | grep de
aus, um die verfügbaren Codierungen zu ermitteln, und setzen Sie dann den entsprechenden Wert, z.B.:
LANG=de_DE.utf8 export LANG
Übernehmen Sie anschließend die zentral dokumentierten Java-Optionen aus Die Umgebungssteuerung SQL_ENV. Darin muss -Dfile.encoding=UTF-8 enthalten sein.
Danach laden Sie einmal die Datei SQL_ENV neu:
. $SUPERX_DIR/db/bin/SQL_ENV
Danach müssen Sie in der Datei $TOMCAT_HOME/conf/server.xml den Parameter URIEncoding="UTF-8" ergänzen, z.B.
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" URIEncoding="UTF-8" />
Starten Sie dann noch Tomcat neu. Damit die die Migration nach UTF-8 beendet.
In HISinOne / Edustore ist folgendes fest vorgegeben:
Vor einer Migration zu HISinOne / Edustore müssen Sie also o.g. zuerst erledigen. Eine Anleitung finden Sie oben.
Sie können nach der Migration der Datenbank die Konnektoren auf BI-Technik umstellen oder die SuperX-Shellscripte weiterhin nutzen. Die Datenbankseite liegt in der Webapp-Struktur unter $WEBAPP/WEB-INF/conf/edustore/db. Setzen Sie $SUPERX_DIR daher auf $WEBAPP/WEB-INF/conf/edustore und passen Sie Ihre SQL_ENV entsprechend an.
Die Technik der BI-Konnektoren ist identisch mit der von SuperX, allerdings lassen sich BI Konnektoren auch in der Komponentenverwaltung von HISinOne ausführen. Wenn Sie die Komponentenverwaltung nutzen wollen müssen Sie die Umgebung der bisherigen SuperX-Shellscripte des jew. Moduls (z.B. $SOS_LOAD_PFAD/SOS_ENV und die darin referenzierte DB_PROPERTIES) nach HISinOne (die Datei .../webapps/qissserver/WEB-INF/conf/databases_< Das analoge Beispiel in $SOS_LOAD_PFAD/db-sos_pg.properties: Sie übertragen also die Connection Angaben in die databases.xml und starten den Tomcat neu. Weitere Infos: https://wiki.his.de/mediawiki/index.php/Komponentenverwaltung_der_HISinOne-BI https://wiki.his.de/mediawiki/index.php/Komponenten_Update-HISinOne-BI#Skriptgesteuerter_Update Mit Kernmodul 6.0 wird die Verzeichnisstruktur von SuperX unterhalb von webapps/superx verlagert. Details siehe Migrationsleitfaden. Wenn Sie den Tomcat benutzen, welcher mit SuperX ausgeliefert wird, wird dieser nicht automatisch vom System geupgradet. Dies muss manuell gemacht werden. Bei kleineren Versionssprüngen wird es sehr wahrscheinlich keine Probleme geben. Bei dem Upgrade auf eine neue Tomcat Version ist aber Vorsicht geboten. Dieser Leitfaden zur Aktualisierung des Tomcats ist ein Vorschlag von uns, wie Sie den Tomcat aktualisieren können. Bitte sichern Sie zuvor das Dateisystem von SuperX und die Datenbank um bei eventuellen Problemen das System auf den funktionierenden Stand wieder zurück bringen zu können. Bitte laden Sie sich hier: http://tomcat.apache.org/ die Version des Tomcats herunter, welche Sie verwenden möchten. Beenden Sie Tomcat und sichern Sie $TOMCAT_HOME einschließlich der Konfiguration und der Webanwendung. Installieren beziehungsweise entpacken Sie die neue Tomcat-Version in ein separates Verzeichnis. Übernehmen Sie aus der alten Installation nur die weiterhin benötigten Konfigurationen und prüfen Sie diese gegen die Standardkonfiguration der neuen Version. Binden Sie anschließend die vorhandene Webanwendung unter $WEBAPP ein, starten Sie Tomcat und testen Sie die Anwendung zuerst direkt und danach gegebenenfalls über Apache oder den Load Balancer.
driverName=org.postgresql.Driver
connectionName=superx
connectionURL=jdbc\:postgresql\://localhost:5432/sospos
logLevelSQL=FINEST
connectionPassword=sx_des\#-1\#108\#-75\#72\#-110\#-117\#-34\#-94\#116\#120\#-97\#-28\#-54\#-55\#11\#8
Hinweis: Wenn Sie Vorsysteme mit einem anderen Datenbanksystem als PostgreSQL nutzen, beispielsweise MACH unter SQL Server, müssen Sie auch den JDBC-Treiber der Anwendung vom Rohdatenpfad nach $WEBAPP/WEB-INF/lib kopieren und Tomcat neu starten.
Migration Webapp-Verzeichnisstruktur
Tomcat aktualisieren
