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

. /home/superx/git/BI_Maintenance/env/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=/home/superx/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 die automatische Ausführung

Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript. Dieses kann sowohl über einen klassischen Cronjob als auch über einen systemd-Service gestartet werden.

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, zum Update-Skript und zur Logdatei anpassen.

Inhaltlich:

• Laden der BI_ENV
• Start des Skripts modules_update.sh
• Umleitung der Ausgabe in die konfigurierte Logdatei

Ausführung über Cron

Für die regelmäßige Ausführung kann beispielsweise ein Cronjob eingerichtet werden, der das Update werktags um 18 Uhr startet:

0 18 * * 1-5 /home/superx/git/BI_Maintenance/update/modules_update_cron.sh

Der Cronjob sollte unter dem Benutzer ausgeführt werden, unter dem auch die BI-Installation betrieben wird, üblicherweise superx.

Ausführung über systemd

Alternativ zum klassischen Cronjob kann die Laderoutine über einen systemd-Service und einen systemd-Timer ausgeführt werden.

Im Verzeichnis

update/systemd/

werden hierfür die beiden Beispieldateien

superx_update.service
superx_update.timer

bereitgestellt.

Der Service führt das Wrapper-Skript modules_update_cron.sh unter dem Benutzer superx aus.

Beispiel superx_update.service:

[Unit]
Description=SuperX BI Laderoutine

[Service]
Type=oneshot
User=superx
Group=superx
WorkingDirectory=/home/superx
ExecStart=/bin/bash /home/superx/git/BI_Maintenance/update/modules_update_cron.sh

Die Pfade sowie Benutzer und Gruppe müssen bei Bedarf an die lokale Installation angepasst werden.

Durch den expliziten Aufruf über /bin/bash können insbesondere auf Systemen mit SELinux Probleme bei der direkten Ausführung von Skripten aus Benutzerverzeichnissen vermieden werden.

Der zugehörige Timer legt fest, wann der Service gestartet wird.

Beispiel superx_update.timer:

[Unit]
Description=Timer für SuperX BI Laderoutine

[Timer]
OnCalendar=Mon..Fri *-*-* 18:00:00
Unit=superx_update.service

# Optional:
# Verpassten Lauf nach Server-Neustart nachholen:
# Persistent=true

[Install]
WantedBy=timers.target

Im Beispiel wird die Laderoutine montags bis freitags jeweils um 18 Uhr ausgeführt. Der Zeitplan kann über OnCalendar an die lokalen Anforderungen angepasst werden.

Die beiden Dateien werden nach /etc/systemd/system kopiert:

cp systemd/superx_update.service /etc/systemd/system/
cp systemd/superx_update.timer /etc/systemd/system/

Anschließend wird die systemd-Konfiguration neu eingelesen und der Timer aktiviert:

systemctl daemon-reload
systemctl enable --now superx_update.timer

Der Status des Timers und die nächste geplante Ausführung können anschließend geprüft werden:

systemctl status superx_update.timer
systemctl list-timers --all | grep superx

Der Service kann unabhängig vom Timer auch manuell gestartet und geprüft werden:

systemctl start superx_update.service
systemctl status superx_update.service

Der superx_update.service selbst muss nicht mit systemctl enable aktiviert werden. Er wird bei Bedarf durch den Timer gestartet.

Optional kann im Timer

Persistent=true

gesetzt werden. In diesem Fall holt systemd einen verpassten Lauf nach, beispielsweise wenn der Server zum geplanten Ausführungszeitpunkt ausgeschaltet war. Ob dieses Verhalten gewünscht ist, sollte für die jeweilige Installation entschieden werden.

---

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 /home/superx/git/BI_Maintenance/upgrade
./modules_upgrade.sh

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

. /home/superx/git/BI_Maintenance/env/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.