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:

in BI_ENV kopiert/umbenannt werden:

cp BI_ENV.sam BI_ENV

an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
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:

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

  ComponentAdminCLI -e <modul>

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

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:

Beispieldatei kopieren:

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

Pfade zur BI_ENV und zum Update-Skript anpassen.
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.

Dies kann insbesondere bei großen Installationen sinnvoll sein, um unnötigen zusätzlichen Speicherbedarf zu vermeiden.

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

Laden der migrate_superx.conf
Laden der bestehenden SQL_ENV
Ermitteln von SUPERX_DIR, WEBAPP und DB-Verzeichnis
Sicherheitsprüfungen
Optionales Stoppen des Tomcat-Dienstes
Kopieren der Webapp
Kopieren oder Verschieben des DB-Verzeichnisses
Anpassen der SQL_ENV
Setzen von Besitzern, Gruppen und Rechten
Optionales Erzeugen des Tomcat-Symlinks
Optionales Starten des Tomcat-Dienstes

Empfohlene Standardkonfiguration

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

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

MIGRATION_MODE="full"
DB_TRANSFER_MODE="copy"

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.

Kernmodul Regelbetrieb

BI Maintenance

Ziel und Überblick

Installation aus dem git Repository

Umgebungsvariablen in der BI_ENV

BI_ENV.sam – Template und lokale BI_ENV

Bedeutung der Variablen

Java-Konfiguration

Pfade zur SuperX-BI-Installation

Modulsteuerung

Logging

Mailversand

Steuerung der Log-Anhänge

Optionale Prüfung der Modul-Logs

Module Updates

modules_update.sh – Hauptskript

modules_update_cron.sh – Wrapper für Cron

Module Upgrades

modules_upgrade.sh – Hauptskript

Modulverwaltung

Modulkürzel

Migration auf die Webapp-Struktur

Zielstruktur

Tomcat-Anbindung

Wichtige Variablen

TARGET_WEBAPP

WEBAPP_USER

WEBAPP_GROUP

MIGRATION_MODE

Migration des DB-Verzeichnisses

DB_TRANSFER_MODE=copy

DB_TRANSFER_MODE=move

Automatische Anpassung der SQL_ENV

Benutzer und Gruppen

WEBAPP_USER

WEBAPP_GROUP

Automatische Rechtebehandlung

SET_OWNER=auto

Ausführung als root

Ausführung als WEBAPP_USER

Ausführung als anderer Benutzer

ADD_WEBAPP_USER_TO_GROUP

Tomcat-Symlink

CREATE_TOMCAT_SYMLINK

TOMCAT_WEBAPPS_DIR

TOMCAT_CONTEXT_NAME

REPLACE_EXISTING_SYMLINK

Sicherheitsprüfungen

FORCE_ALREADY_MIGRATED

Typischer Ablauf

Empfohlene Standardkonfiguration

Hinweise