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

Ziel

Mit dem Skript migrate_superx_webapp.sh kann eine bestehende SuperX-Installation automatisch auf die neue Verzeichnisstruktur migriert werden.

Dabei werden die Dateien nicht verschoben, sondern kopiert. Die bestehende Installation bleibt dadurch unverändert erhalten und kann bei Bedarf weiterhin verwendet werden.

Die Migration dient insbesondere dazu, die bisher getrennten Verzeichnisse:

/home/superx/db
/home/superx/webserver/tomcat/webapps/superx

in einer gemeinsamen Struktur innerhalb der Tomcat-Webapp zusammenzuführen.

Neue Verzeichnisstruktur

Nach der Migration befindet sich die komplette SuperX-Installation innerhalb der Webapp:

<WEBAPP>
├── WEB-INF
│   ├── conf
│   │   └── edustore
│   │       └── db
│   └── ...
└── ...

Beispiel:

/var/lib/tomcat10/webapps/superx
└── WEB-INF
    └── conf
        └── edustore
            └── db

Die Variablen in der SQL_ENV werden dabei automatisch angepasst:

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

SUPERX_DIR=/var/lib/tomcat10/webapps/superx/WEB-INF/conf/edustore

Zusätzlich wird die Umask auf:

umask 002

gesetzt, damit Dateien und Verzeichnisse künftig gruppenweit bearbeitet werden können.

Installation

Das Migrationsskript wird zusammen mit einer Konfigurationsdatei ausgeliefert:

migrate_superx.conf
migrate_superx_webapp.sh

Beide Dateien müssen sich im selben Verzeichnis befinden.

Das Skript liest die Konfiguration automatisch aus der Datei:

migrate_superx.conf

im aktuellen Skriptverzeichnis ein.

Konfiguration

Vorhandene SQL_ENV

Pfad zur bestehenden Installation:

SQL_ENV=/home/superx/db/bin/SQL_ENV

Über diese Datei werden die bisherigen Werte von SUPERX_DIR und WEBAPP ermittelt.

Ziel-Webapp

Zielverzeichnis der neuen Installation:

TARGET_WEBAPP=/var/lib/tomcat10/webapps/superx

Die interne Struktur unterhalb dieses Verzeichnisses wird automatisch erzeugt.

Benutzer und Gruppen

TOMCAT_USER=tomcat
SUPERX_GROUP=superx

Alternativ:

TOMCAT_USER=superx
SUPERX_GROUP=superx

Automatische Rechtebehandlung

Die Variable

SET_OWNER=auto

steuert, ob und wie Besitzer und Gruppen der migrierten Dateien gesetzt werden.

SET_OWNER=auto (empfohlen)

Dies ist die empfohlene Standardeinstellung.

Das Skript entscheidet automatisch, ob ein chown erforderlich ist:

Wird das Skript als root ausgeführt, werden Besitzer und Gruppe gemäß den Variablen TOMCAT_USER und SUPERX_GROUP gesetzt.
Wird das Skript als derselbe Benutzer ausgeführt, der auch als TOMCAT_USER konfiguriert wurde und ist dieser Benutzer Mitglied der angegebenen Gruppe, wird auf das chown automatisch verzichtet.
Ist eine Änderung des Besitzers erforderlich, das Skript läuft jedoch nicht als root, wird die Ausführung mit einer entsprechenden Fehlermeldung abgebrochen.

Dadurch können Testmigrationen ohne Root-Rechte durchgeführt werden, während Produktivmigrationen weiterhin die korrekten Besitzer und Gruppen setzen.

SET_OWNER=true

SET_OWNER=true

Der Besitzer wird immer auf den konfigurierten Benutzer und die konfigurierte Gruppe gesetzt:

chown -R $TOMCAT_USER:$SUPERX_GROUP ...

Für diese Einstellung werden in der Regel Root-Rechte benötigt.

SET_OWNER=false

SET_OWNER=false

Es wird kein chown ausgeführt.

Die vorhandenen Besitzer- und Gruppeninformationen bleiben unverändert erhalten.

Diese Einstellung eignet sich insbesondere für Testumgebungen oder Spezialfälle, in denen die Rechteverwaltung bereits anderweitig erfolgt.

Sicherheitsprüfung bereits migrierter Installationen

Um versehentliche Mehrfachmigrationen zu vermeiden, prüft das Skript standardmäßig, ob die Quellinstallation bereits die neue Webapp-Struktur verwendet.

Folgende Konstellationen werden erkannt:

SUPERX_DIR=/home/superx/webserver/tomcat/webapps/superx/WEB-INF/conf/edustore
WEBAPP=/home/superx/webserver/tomcat/webapps/superx

In diesem Fall liegt SUPERX_DIR bereits innerhalb von WEBAPP und die Installation sieht bereits wie eine migrierte Webapp-Struktur aus.

Zusätzlich wird geprüft, ob bereits folgendes Verzeichnis vorhanden ist:

WEB-INF/conf/edustore/db

Wird eine solche Struktur erkannt, bricht das Skript standardmäßig mit einer entsprechenden Fehlermeldung ab.

FORCE_ALREADY_MIGRATED

Für Sonderfälle kann diese Sicherheitsprüfung bewusst übersteuert werden:

FORCE_ALREADY_MIGRATED=true

Dann wird die Migration trotz erkannter Webapp-Struktur fortgesetzt.

Diese Option sollte nur verwendet werden, wenn die Auswirkungen bekannt sind. Andernfalls besteht die Gefahr, dass bereits migrierte Strukturen erneut kopiert oder Verzeichnisstrukturen ungewollt verschachtelt werden.

Standardwert:

FORCE_ALREADY_MIGRATED=false

Beispiele

Produktivsystem:

TOMCAT_USER=tomcat
SUPERX_GROUP=superx
SET_OWNER=auto
FORCE_ALREADY_MIGRATED=false

Testsystem:

TOMCAT_USER=superx
SUPERX_GROUP=superx
SET_OWNER=auto
FORCE_ALREADY_MIGRATED=false

Wird das Skript in diesem Beispiel als Benutzer superx ausgeführt, sind keine Root-Rechte erforderlich.

Ablauf der Migration

Laden der Konfiguration aus migrate_superx.conf
Laden der bestehenden SQL_ENV
Ermitteln der bisherigen Verzeichnisse
Anlegen der Zielstruktur
Kopieren der Webapp mittels rsync
Kopieren des DB-Verzeichnisses nach WEB-INF/conf/edustore/db
Backup der neuen SQL_ENV
Anpassung von WEBAPP, SUPERX_DIR und umask
Optionales Setzen von Rechten
Optionale Tomcat-Integration

Dry-Run

Vor einer Produktivmigration empfiehlt sich ein Testlauf:

DRY_RUN=true

Anschließend:

./migrate_superx_webapp.sh

Es werden alle geplanten Aktionen angezeigt, jedoch keine Änderungen durchgeführt.

Produktivmigration

sudo ./migrate_superx_webapp.sh

Nach Abschluss sollte die neue SQL_ENV geprüft werden:

. <WEBAPP>/WEB-INF/conf/edustore/db/bin/SQL_ENV

echo $SUPERX_DIR
echo $WEBAPP

Hinweise

Die ursprüngliche Installation bleibt erhalten, da ausschließlich kopiert wird.
Für die eigentliche Migration wird rsync benötigt.
Das Skript kann mehrfach ausgeführt werden.
Die interne Zielstruktur ist fest definiert und unabhängig vom gewählten Webapp-Pfad.
Für Produktivmigrationen wird die Ausführung als root empfohlen.
Testmigrationen können je nach Konfiguration auch ohne Root-Rechte durchgeführt werden.

Kernmodul Regelbetrieb