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

Aktueller Stand

Die empfohlene Zielstruktur wurde gegenüber den ersten Entwürfen angepasst.

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"

Neue Variablen

Die bisherigen Variablen:

TOMCAT_USER
SUPERX_GROUP

wurden ersetzt durch:

WEBAPP_USER
WEBAPP_GROUP

Dadurch ist das Skript nicht mehr auf bestimmte Benutzernamen festgelegt und kann flexibler eingesetzt werden.

WEBAPP_USER

Besitzer der Ziel-Webapp.

Beispiel:

WEBAPP_USER="superx"

WEBAPP_GROUP

Gruppe der Ziel-Webapp.

Beispiel:

WEBAPP_GROUP="tomcat"

Dadurch ergibt sich als Standardziel:

Owner: superx
Group: tomcat

Automatische Rechtebehandlung

SET_OWNER=auto

Dies ist die empfohlene Standardeinstellung.

SET_OWNER="auto"

Das Skript entscheidet automatisch, ob ein chown erforderlich ist.

Ausführung als root

Wird das Skript als root ausgeführt, werden Besitzer und Gruppe gesetzt:

chown -R $WEBAPP_USER:$WEBAPP_GROUP ...

Beispiel:

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

Ergebnis:

Owner: superx
Group: tomcat

Ausführung als WEBAPP_USER

Wird das Skript direkt als WEBAPP_USER ausgeführt und ist dieser Benutzer Mitglied der WEBAPP_GROUP, kann die Migration häufig vollständig ohne root-Rechte erfolgen.

Beispiel:

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

Prüfung:

id superx

Beispielausgabe:

uid=1001(superx)
groups=superx,tomcat

In diesem Fall kann der Benutzer:

• Dateien kopieren
• Dateien verschieben
• Verzeichnisse anlegen
• chmod ausführen
• Gruppenrechte setzen

ohne root-Rechte durchführen.

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.

Tomcat-Anbindung über Symlink

Empfohlen wird folgende Struktur:

/home/superx/webapps/superx

Optional kann das Skript automatisch einen Symlink erzeugen.

CREATE_TOMCAT_SYMLINK

CREATE_TOMCAT_SYMLINK="true"

TOMCAT_WEBAPPS_DIR

TOMCAT_WEBAPPS_DIR="/var/lib/tomcat10/webapps"

TOMCAT_CONTEXT_NAME

TOMCAT_CONTEXT_NAME="superx"

Ergebnis:

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

REPLACE_EXISTING_SYMLINK

Bestehende Symlinks können optional ersetzt werden.

REPLACE_EXISTING_SYMLINK="true"

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

Empfohlene Standardkonfiguration

Für neue Installationen wird derzeit folgende Konfiguration empfohlen:

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

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

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

CREATE_TOMCAT_SYMLINK="false"

Vorteile:

• SuperX bleibt unabhängig vom Tomcat-Verzeichnis.
• Git-Repositories können direkt durch den Benutzer superx gepflegt werden.
• Modulupdates können häufig ohne root durchgeführt werden.
• Die Webapp bleibt auch bei Tomcat-Upgrades unverändert.
• Die Struktur funktioniert distributionsübergreifend.

Aktualisierte Beispiele

Migration ohne root

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

SET_OWNER="auto"
SET_RIGHTS="true"

Voraussetzung:

id superx

liefert:

groups=superx,tomcat

Migration mit root

sudo ./migrate_superx_webapp.sh

Dabei werden die Zielrechte automatisch auf:

superx:tomcat

gesetzt.

Ergänzung zum Migrationsablauf

Der Ablauf lautet nun:

1. Laden von migrate_superx.conf
2. Laden der bestehenden SQL_ENV
3. Ermitteln von SUPERX_DIR, WEBAPP und DB-Verzeichnis
4. Sicherheitsprüfung auf bereits migrierte Strukturen
5. Ermitteln der Zielstruktur
6. Optional Tomcat stoppen
7. Optional Webapp kopieren
8. DB-Verzeichnis kopieren oder verschieben
9. SQL_ENV anpassen
10. Rechte setzen
11. Optional Tomcat-Symlink erzeugen
12. Optional Tomcat starten

Hinweise

• Standardziel ist /home/superx/webapps/superx.
• Die Tomcat-Anbindung kann über einen Symlink erfolgen.
• WEBAPP_USER und WEBAPP_GROUP ersetzen die früheren Variablen TOMCAT_USER und SUPERX_GROUP.
• Bei WEBAPP_USER=superx und WEBAPP_GROUP=tomcat kann die Migration häufig ohne root erfolgen.
• Root wird nur benötigt, wenn Besitzer geändert oder Systemkonfigurationen angepasst werden müssen.