Kernmodul Regelbetrieb

BI Maintenance

Ziel und Überblick

Die hier bereitgestellten Skripte ermöglichen es, in der BI-Umgebung von HISinOne und in Zukunft auch von SuperX (aktuell können die Scripte in SuperX leider noch nicht verwendet werden) Modul-Updates und -Upgrades zuverlässig über die Shell auszuführen – automatisiert per Cronjob oder manuell. Sie orientieren sich bewusst am bisherigen Vorgehen aus SuperX, wurden jedoch erweitert:

• Ausführung der BI-Modul-Updates/-Upgrades über Java (ComponentAdminCLI).
• Vollständige Protokollierung in Logdateien.
• Optional: Protokollierung der Läufe in der Tabelle update_prot.
• Automatischer Mailversand über ein konfigurierbares Mailprogramm.
• Optional: Erkennen interner Fehler im Batch-Job (auch wenn Java Exitcode 0 liefert).
• Möglichkeit, Logdateien automatisch an Mails anzuhängen (erfolgreiche und fehlerhafte Module).

Installation aus dem git Repository

Führen Sie folgenden Shell-Befehl aus:

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git

Die weitere Konfiguration wird im Folgenden beschrieben. Alle Einstellungen erfolgen zentral in der Datei BI_ENV, die als Template BI_ENV.sam ausgeliefert wird.

Umgebungsvariablen in der BI_ENV

BI_ENV.sam – Template und lokale BI_ENV

Die Datei BI_ENV.sam wird als Muster ausgeliefert.

Sie muss vor Ort:

1. in BI_ENV kopiert/umbenannt werden:

cp BI_ENV.sam BI_ENV

1. an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
2. mit restriktiven Rechten versehen werden:

chmod 600 BI_ENV

Skripte binden diese Datei später mit

. /pfad/zu/BI_ENV

ein.

---

Bedeutung der Variablen

Im Folgenden die wichtigsten Variablen, die angepasst werden müssen.

Java-Konfiguration

JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export JAVA_HOME

JRE_HOME=$JAVA_HOME
export JRE_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH

Diese Variablen stellen sicher, dass die BI-Jobs mit dem vorgesehenen Java (empfohlen: Java 17) ausgeführt werden.

Java-Optionen:

JAVA_OPTS="-Xmx1520M -Djava.awt.headless=true ... --add-opens ..."
export JAVA_OPTS

Pfade zur SuperX-BI-Installation

WEBAPP=/var/lib/tomcat10/webapps/superx
export WEBAPP

SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export SUPERX_DIR

Diese Pfade müssen an lokale Tomcat-Installation und SuperX-Verzeichnisstruktur angepasst werden.

Modulsteuerung

Für die Update- und Upgrade-Skripte werden die zu bearbeitenden Module festgelegt:

export BI_UPDATE_MODULES="sos kenn zul"
export BI_UPGRADE_MODULES="kenn"

Hinweis: Die Modulkürzel müssen klein geschrieben sein (z. B. sos, kenn, zul) und mit Leerzeichen getrennt aufgelistet werden.

Logging

LOGPFAD=$WEBAPP/WEB-INF/logs
export LOGPFAD

Im Logpfad werden u. a. folgende Dateien erzeugt:

• bi_update.log – Sammellog des Updates
• bi_upgrade.log – Sammellog des Upgrades
• <modul>_update.log
• <modul>_upgrade.log

Java-Batch-Jobs erzeugen ergänzende Logs in:

$WEBAPP/WEB-INF/logs/jobs

Mailversand

Folgende Variablen steuern Empfänger und Format der Benachrichtigungen:

export ERRORMAIL="admin@hs.de"
export LOGMAIL="$ERRORMAIL"
#export LOGMAIL="admin@hs.de kollege@hs.de"   # mehrere Empfänger möglich

• ERRORMAIL – Empfänger für Fehlermails
• LOGMAIL – Empfänger für Erfolgs- und Statusmails

Mehrere Adressen werden per Leerzeichen getrennt.

Mailprogramm:

export MAILPROG="s-nail --account=test1 -S ttycharset=utf-8 -S sendcharset=utf-8"

Betreffzeilen:

export MAIL_BETREFF_UPDATE="BI Job Update"
export MAIL_BETREFF_UPGRADE="BI Job Upgrade"
export MAIL_BETREFF_SUFFIX_ERFOLGREICH=" - Erfolgreich"
export MAIL_BETREFF_SUFFIX_FEHLER=" - Fehler"

So könnten die Mails aussehen.

Steuerung der Log-Anhänge

# error  = Logs nur bei Fehlern anhängen
# always = Logs immer anhängen (Erfolg + Fehler)
export MAIL_ATTACH_LOGS_MODE="error"

Optionale Prüfung der Modul-Logs

# true  = zusätzlich Modul-Log auf interne Fehler prüfen
# false = nur Exitcode des Java-Calls verwenden
export CHECK_JOBLOG_FOR_ERRORS="true"

Gerade bei dem Java Aufruf von ComponentAdminCLI empfehlenswert, da dieser aktuell noch trotz status: FAILED oft Exitcode 0 liefert.

---

Module Updates

modules_update.sh – Hauptskript

Dieses Skript führt alle Module aus BI_UPDATE_MODULES nacheinander aus.

Ablauf:

1. Startcheck: Sind WEBAPP, LOGPFAD und BI_UPDATE_MODULES gesetzt?
2. Falls verfügbar: DB-Protokollierung via DOQUERY.
3. Für jedes Modul:
   1. Logdatei anlegen
   2. Start in update_prot protokollieren (update_id = -10000)
   3. Java-Update starten:

  ComponentAdminCLI -e <modul>

1. 1. Optional: Modul-Logdatei nach internen Fehlern durchsuchen
   2. Erfolg:
      1. Modul-Log in SUCCESS_LOG_FILES
      2. DB-Update (update_id = -10000)
   3. Fehler:
      1. Modul-Log in ERROR_LOG_FILES
      2. DB-Update (update_id = -10001)
   4. Zuletzt: Java-Joblogs aus $WEBAPP/WEB-INF/logs/jobs ermitteln

1. Nach Abschluss aller Module:
   1. Erfolgs- oder Fehlermail versenden
   2. Anhänge abhängig von MAIL_ATTACH_LOGS_MODE

modules_update_cron.sh – Wrapper für Cron

Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript.

Vorgehen:

1. Beispieldatei kopieren:

cp modules_update_cron.sh.sam modules_update_cron.sh
chmod +x modules_update_cron.sh

1. Pfade zur BI_ENV und zum Update-Skript anpassen.
2. Cronjob eintragen, z. B. werktags um 18 Uhr:

0 18 * * 1-5 /pfad/zu/modules_update_cron.sh

Inhaltlich:

• Laden der BI_ENV
• Start des Skripts modules_update.sh

---

Module Upgrades

modules_upgrade.sh – Hauptskript

Das Upgrade-Skript entspricht dem Update-Skript, unterscheidet sich aber in folgenden Punkten:

• Es wird **manuell** ausgeführt – kein Cronjob vorgesehen.
• Es verwendet BI_UPGRADE_MODULES.
• Das eigentliche Upgrade erfolgt über:

 ComponentAdminCLI -u <modul>

• Nach Abschluss des Upgrades erfolgt ein Mailversand analog zum Update-Skript.

Aufruf:

cd /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update
./modules_upgrade.sh

Vorher muss zu Beginn des Skripts der Pfad zur BI_ENV eingetragen sein:

. /pfad/zur/BI_ENV

---

Modulverwaltung

Modulkürzel

Die folgenden Modulkürzel sind in einer typischen BI-Installation relevant:

 kuerzel |                         name                          
---------+-------------------------------------------------------
 astat   | Amtliche Statistik                                
 bau     | Gebäude, Räume, Flächen                           
 cob     | Kostenrechnung                                    
 erfolg  | Studienverlauf                                    
 fin     | Finanzrechnung                                    
 gang    | Studiengänge                                      
 ivs     | Inventar                                          
 kenn    | Kennzahlen                                        
 kern    | Administration                                    
 lm      | Leistungsmonitoring                               
 man     | Management                                        
 prom    | Promovierende                                     
 res     | Forschung                                         
 sos     | Studierende, Prüfungen                            
 sva     | Personal, Stellen                                 
 zul     | Bewerbung, Zulassung

Die aktiven Module der eigenen Installation können mit folgendem SQL abgefragt werden:

SELECT V.his_system AS kuerzel,
       S.name
  FROM db_version V
  JOIN systeminfo S
    ON S.tid = V.systeminfo_id
 ORDER BY 1;

Migration auf die Webapp-Struktur

Das bereitgestellte Migrationsskript ermöglicht die Umstellung einer bestehenden SuperX-Installation auf die empfohlene Webapp-Struktur.

Dabei können sowohl klassische Installationen mit separatem DB-Verzeichnis als auch bestehende Webapp-Installationen migriert werden. Die Migration kann je nach Anwendungsfall vollständig oder ausschließlich für das DB-Verzeichnis durchgeführt werden. Hier eine Anleitung "in short", wenn Sie bisher das "klasssische" Layout genutzt haben (also Unix Benutzer "superx", Installation in "/home/superx").

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git
#Script ausführen und neues ENV laden:
cd BI_Maintenance/webapps_migration
./migrate_superx_webapp.sh

Das Skript liest die bestehende Installation anhand der vorhandenen SQL_ENV-Datei ein und erzeugt daraus die gewünschte Zielstruktur. Details können in der Konfigurationsdatei

migrate_superx.conf

konfiguriert, siehe folgende Dokumentation.

Zielstruktur

Die Webapp wird standardmäßig nicht direkt im Tomcat-Webapp-Verzeichnis abgelegt, sondern unter:

/home/superx/webapps/superx

Dadurch bleibt die Installation unabhängig von der verwendeten Tomcat-Distribution und kann einfacher per Git, rsync oder Modulupdate gepflegt werden.

Die zugehörige DB-Struktur befindet sich anschließend unter:

/home/superx/webapps/superx/WEB-INF/conf/edustore/db

Tomcat-Anbindung

Für den Zugriff des Tomcat-Servers auf die Webapp gibt es grundsätzlich zwei Möglichkeiten:

• Verwendung eines symbolischen Links vom Tomcat-Webapp-Verzeichnis auf die eigentliche Webapp.
• Anpassung der Tomcat-Konfiguration (z. B. appBase oder Context-Konfiguration).

Empfohlen wird die Verwendung eines symbolischen Links.

Beispiel:

/srv/tomcat/webapps/superx
 -> /home/superx/webapps/superx

Wichtige Variablen

Die wichtigsten Einstellungen erfolgen in der Datei:

migrate_superx.conf

TARGET_WEBAPP

Definiert das Zielverzeichnis der Webapp.

Beispiel:

TARGET_WEBAPP="/home/superx/webapps/superx"

WEBAPP_USER

Definiert den Besitzer der Ziel-Webapp.

Beispiel:

WEBAPP_USER="superx"

WEBAPP_GROUP

Definiert die Gruppe der Ziel-Webapp.

Beispiel:

WEBAPP_GROUP="tomcat"

Ergebnis:

Owner: superx
Group: tomcat

MIGRATION_MODE

Steuert die Art der Migration.

Vollständige Migration:

MIGRATION_MODE="full"

Nur Migration des DB-Verzeichnisses:

MIGRATION_MODE="db_only"

Migration des DB-Verzeichnisses

Das DB-Verzeichnis kann entweder kopiert oder verschoben werden.

DB_TRANSFER_MODE=copy

Das bestehende DB-Verzeichnis bleibt erhalten.

DB_TRANSFER_MODE="copy"

Intern wird hierfür rsync verwendet.

DB_TRANSFER_MODE=move

Das DB-Verzeichnis wird verschoben.

DB_TRANSFER_MODE="move"

Intern wird hierfür mv verwendet. Ist das Zielverzeichnis bereits vorhanden und ALLOW_EXISTING_TARGET_DB="true" gesetzt, wird das vorhandene Ziel-DB-Verzeichnis vor dem Verschieben vollständig ersetzt. Damit verbleiben keine alten Dateien im Ziel.

Dies ist der empfohlene Standard für die Migration klassischer SuperX-Installationen und vermeidet unnötigen zusätzlichen Speicherbedarf.

Automatische Anpassung der SQL_ENV

Nach der Migration kann die SQL_ENV-Datei automatisch angepasst werden.

Dabei werden insbesondere folgende Variablen aktualisiert:

SUPERX_DIR
WEBAPP

Zusätzlich wird sichergestellt, dass folgende Einstellung vorhanden ist:

umask 002

Vor der Änderung wird automatisch eine Sicherungskopie der SQL_ENV-Datei angelegt.

Benutzer und Gruppen

Die folgenden Variablen steuern, welchem Benutzer und welcher Gruppe die Ziel-Webapp nach der Migration zugeordnet wird.

WEBAPP_USER

Definiert den Besitzer der Ziel-Webapp.

Beispiel:

WEBAPP_USER="superx"

Alle Dateien und Verzeichnisse der Ziel-Webapp werden diesem Benutzer zugeordnet, sofern die Rechteverwaltung aktiviert ist.

WEBAPP_GROUP

Definiert die Gruppe der Ziel-Webapp.

Beispiel:

WEBAPP_GROUP="tomcat"

Die Gruppe wird für alle Dateien und Verzeichnisse der Ziel-Webapp verwendet.

Durch das gesetzte setgid-Bit auf den Verzeichnissen erben neu angelegte Dateien und Unterverzeichnisse automatisch diese Gruppe.

Automatische Rechtebehandlung

Die Migration kann sowohl als root als auch – unter bestimmten Voraussetzungen – direkt als Anwendungsbenutzer ausgeführt werden.

SET_OWNER=auto

Dies ist die empfohlene Standardeinstellung.

SET_OWNER="auto"

Das Skript entscheidet abhängig vom aktuellen Benutzer automatisch, ob ein Besitzerwechsel erforderlich ist.

Ausführung als root

Wird das Skript als root ausgeführt, werden Besitzer und Gruppe der Ziel-Webapp auf die konfigurierten Werte gesetzt.

chown -R $WEBAPP_USER:$WEBAPP_GROUP ...

Zusätzlich wird auch das übergeordnete Verzeichnis der Webapp (z. B. /home/superx/webapps) auf die gleichen Besitz- und Gruppenrechte gesetzt.

Ausführung als WEBAPP_USER

Wird das Skript direkt als der konfigurierte WEBAPP_USER ausgeführt und ist dieser Benutzer Mitglied der konfigurierten WEBAPP_GROUP, wird kein chown ausgeführt.

Stattdessen verwendet das Skript bei Bedarf ein chgrp, um die Gruppenzugehörigkeit der Dateien anzupassen.

In diesem Fall kann die Migration häufig vollständig ohne root-Rechte durchgeführt werden.

Ausführung als anderer Benutzer

Wird das Skript weder als root noch als WEBAPP_USER mit passender Gruppenmitgliedschaft ausgeführt, bricht das Skript mit einer entsprechenden Fehlermeldung ab.

ADD_WEBAPP_USER_TO_GROUP

Optional kann das Skript die Gruppenmitgliedschaft des Zielbenutzers automatisch anpassen.

ADD_WEBAPP_USER_TO_GROUP="true"

Hierfür sind root-Rechte erforderlich.

Tomcat-Symlink

Optional kann das Skript den Symlink für den Tomcat automatisch erzeugen.

CREATE_TOMCAT_SYMLINK

CREATE_TOMCAT_SYMLINK="true"

TOMCAT_WEBAPPS_DIR

TOMCAT_WEBAPPS_DIR="/srv/tomcat/webapps"

TOMCAT_CONTEXT_NAME

TOMCAT_CONTEXT_NAME="superx"

REPLACE_EXISTING_SYMLINK

Bestehende Symlinks können bei Bedarf automatisch ersetzt werden.

REPLACE_EXISTING_SYMLINK="true"

Normale Dateien oder Verzeichnisse werden dabei niemals automatisch gelöscht.

Sicherheitsprüfungen

Vor Beginn der Migration werden verschiedene Sicherheitsprüfungen durchgeführt.

Unter anderem wird geprüft:

• Existiert die SQL_ENV-Datei?
• Existiert der konfigurierte Benutzer?
• Existiert die konfigurierte Gruppe?
• Sind Quell- und Zielverzeichnis identisch?
• Würde eine Verzeichnisverschachtelung entstehen?
• Befindet sich SUPERX_DIR bereits innerhalb von WEBAPP?

Wird erkannt, dass die Installation bereits der neuen Struktur entspricht, bricht das Skript standardmäßig ab.

FORCE_ALREADY_MIGRATED

In Ausnahmefällen kann diese Prüfung übersteuert werden.

FORCE_ALREADY_MIGRATED="true"

Dies sollte nur verwendet werden, wenn die Auswirkungen bekannt sind.

Typischer Ablauf

1. Laden der migrate_superx.conf
2. Laden der bestehenden SQL_ENV
3. Ermitteln von SUPERX_DIR, WEBAPP und DB-Verzeichnis
4. Sicherheitsprüfungen
5. Optionales Stoppen des Tomcat-Dienstes
6. Kopieren der Webapp
7. Kopieren oder Verschieben des DB-Verzeichnisses
8. Anpassen der SQL_ENV
9. Setzen von Besitzern, Gruppen und Rechten
10. Optionales Erzeugen des Tomcat-Symlinks
11. Optionales Starten des Tomcat-Dienstes

Empfohlene Standardkonfiguration

TARGET_WEBAPP="/home/superx/webapps/superx"

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

MIGRATION_MODE="db_only"
DB_TRANSFER_MODE="move"

SET_OWNER="auto"
SET_RIGHTS="true"
SET_CHMOD="true"

CREATE_TOMCAT_SYMLINK="true"

Hinweise

• Standardziel ist /home/superx/webapps/superx.
• Die Tomcat-Anbindung kann über einen Symlink erfolgen.
• Bei WEBAPP_USER=superx und WEBAPP_GROUP=tomcat kann die Migration häufig ohne root erfolgen, sofern der Benutzer Mitglied der Gruppe tomcat ist.
• Root wird nur benötigt, wenn Besitzer geändert, Benutzer oder Gruppen angepasst oder Systemkonfigurationen verändert werden müssen.