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

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

/home/superx/webapps/superx

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

Optional kann anschließend ein symbolischer Link erzeugt werden:

/var/lib/tomcat10/webapps/superx
 -> /home/superx/webapps/superx

Die Standardkonfiguration verwendet derzeit:

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

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

Benutzer und Gruppen

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.

Beispiel für die resultierenden Rechte:

Owner: superx
Group: tomcat

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

Automatische Rechtebehandlung

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 ...

Beispiel:

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

Ergebnis:

Owner: superx
Group: tomcat

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.

Beispiel:

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

Prüfung:

id superx

Beispielausgabe:

uid=1001(superx)
groups=superx,tomcat

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

Der Benutzer kann dabei:

• Dateien kopieren
• Dateien verschieben
• Verzeichnisse anlegen
• Dateirechte setzen (chmod)
• Gruppenzugehörigkeiten setzen (chgrp)

ohne root-Rechte durchführen.

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.

In diesem Fall muss das Skript entweder:

sudo ./migrate_superx_webapp.sh

oder direkt als WEBAPP_USER ausgeführt werden.

ADD_WEBAPP_USER_TO_GROUP

Optional kann das Skript den Benutzer automatisch der Zielgruppe hinzufügen.

ADD_WEBAPP_USER_TO_GROUP="true"

Beispiel:

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

Das Skript führt dann bei Bedarf aus:

usermod -aG tomcat superx

Hierfür sind root-Rechte erforderlich.

Hinweise

• WEBAPP_USER definiert den Besitzer der Ziel-Webapp.
• WEBAPP_GROUP definiert die Gruppe der Ziel-Webapp.
• 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.