====== REX3D einrichten ======
====== REX3D mit OpenFOAM einrichten ======

REX3D verwendet in Kombination mit unserem OpenFOAM-Solver eine gekapselte Linux-Umgebung. Nach der einmaligen Einrichtung des Zugriffs sind keine weiteren Konfigurationen erforderlich. Die benötigten Container werden von REX automatisch bereitgestellt und eingerichtet nachdem Sie die //REX3D Abhängigkeiten// heruntergeladen und installiert haben. Die Anleitung hierfür finden Sie hier: [[rex3d:rex3dkonfiguration]].

Für die Verwendung des OpenFOAM-Solvers stehen zwei Varianten zur Verfügung:

  * lokaler Betrieb eines Linux-Containers in einer WSL-Umgebung
  * Remotezugriff auf ein Linux-System

Die Einrichtung beider Varianten wird in den folgenden Abschnitten beschrieben.

===== Verwendung auf einem lokalen PC mit WSL =====
Möchten Sie REX3D mit OpenFOAM lokal verwenden müssen Sie WSL installieren und eine lokale virtuelle Maschine verwenden.

==== WSL auf dem Client-PC installieren ====

Öffnen Sie die Windows Powershell mit Adminstrationsberechtigungen und geben Sie folgendes ein:
<code powershell>
wsl --install
</code>

Anschließend muss das System neugestartet werden.

==== REX3D-Optionen anpassen ====

Öffnen Sie anschließend in PSI / REX über das Hauptmenü den Eintrag Optionen > REX3D

Setzen Sie den Haken bei 'Lokale Maschine nutzen' und tragen Sie als Verbindungsname: **podman-machine-default** ein.
Durch das Klicken auf den Button 'Anwenden und testen' wird die WSL VM eingerichtet und vorbereitet. In den nächsten Schritten müssen Sie noch RAM, CPU Kerne und Festplattenkapazität der VM festlegen.
{{ :rex3d:rex19_openfoam_lokal_de.png?nolink |}}

===== Verwendung eines Remote-Servers =====

Mit dem Podman-Remote-Client kann ein Windows-PC auf ein Podman-Backend auf einem Linux-Server zugreifen. Das Podman-Backend stellt die für REX3D beziehungsweise PSI benötigte OpenFOAM-Umgebung bereit.

Für REX3D beziehungsweise PSI verhält sich die entfernte Podman-Installation weitgehend wie eine lokale Podman-Installation.

==== Voraussetzungen ====

Die Verbindung basiert auf einem Client-Server-Modell.

Folgende Komponenten werden benötigt:

  * Linux-Server oder Linux-VM
  * laufender SSH-Dienst auf dem Server
  * Podman auf dem Server
  * Windows-PC mit einer REX- beziehungsweise PSI-Version
  * OpenSSH-Client auf dem Windows-PC
  * Podman-Client auf dem Windows-PC

Diese Anleitung basiert auf Ubuntu 24.04 oder einer vergleichbaren Ubuntu-Version mit ''systemd''. Podman ist über die offiziellen Ubuntu-Paketquellen verfügbar.

In den folgenden Befehlen werden Platzhalter verwendet. Ersetzen Sie diese durch die Werte Ihrer Umgebung:

  * %%<SERVER>%%: Hostname oder IP-Adresse des Servers
  * %%<ADMIN>%%: administrativer Benutzer auf dem Server
  * %%<e3d_usr>%%: unprivilegierter Benutzer für Podman und OpenFOAM
  * %%<ssh_podman_e3d_usr>%%: Dateiname des SSH-Schlüssels
  * %%<UID>%%: numerische Benutzer-ID des Benutzers %%<e3d_usr>%%

==== 1. Podman auf dem Server installieren ====

=== 1.1 Am Server anmelden ===

Öffnen Sie auf dem Windows-PC PowerShell und stellen Sie eine SSH-Verbindung zum Server her:

<code powershell>
ssh.exe <ADMIN>@<SERVER>
</code>

=== 1.2 Benötigte Pakete installieren ===

Aktualisieren Sie zunächst die Paketinformationen:

<code bash>
sudo apt-get update
</code>

Installieren Sie anschließend die benötigten Pakete:

<code bash>
sudo apt-get install podman
</code>

Prüfen Sie die Installation:

<code bash>
podman --version
</code>

==== 2. Podman-Benutzer einrichten ====

=== 2.1 Benutzer ohne lokale Passwortanmeldung anlegen ===

Legen Sie als Administrator einen separaten Benutzer für Podman und OpenFOAM an:

<code bash>
sudo adduser \
  --disabled-password \
  --comment "" \
  <e3d_usr>
</code>

Der Benutzer erhält kein lokales Passwort. Die Anmeldung erfolgt später ausschließlich über einen SSH-Schlüssel.

=== 2.2 Dateisystem des Home-Verzeichnisses prüfen ===

Prüfen Sie, auf welchem Dateisystem sich das Home-Verzeichnis des Benutzers befindet:

<code bash>
findmnt -T /home/<e3d_usr>
</code>

Für den Container-Storage eignen sich lokale Dateisysteme wie ''ext4'', ''xfs'' oder ''btrfs''.

Befindet sich das Home-Verzeichnis auf einem NFS-Dateisystem, richten Sie für den Podman-Storage einen lokalen Speicherpfad ein. NFS ist für Rootless-Container-Storage in der Regel nicht geeignet.

=== 2.3 Benutzerspezifische systemd-Dienste dauerhaft aktivieren ===

Damit benutzerspezifische systemd-Dienste auch ohne aktive SSH-Sitzung ausgeführt werden können, aktivieren Sie die Linger-Funktion für den Benutzer:

<code bash>
sudo loginctl enable-linger <e3d_usr>
</code>

Prüfen Sie anschließend den Status:

<code bash>
loginctl show-user <e3d_usr> -p Linger
</code>

Erwartete Ausgabe:

<code text>
Linger=yes
</code>

==== 3. SSH-Schlüssel auf dem Windows-PC einrichten ====

Auf dem Windows-PC muss der OpenSSH-Client installiert sein.

=== 3.1 OpenSSH-Installation prüfen ===

Öffnen Sie PowerShell und prüfen Sie, ob die benötigten Programme verfügbar sind:

<code powershell>
Get-Command ssh.exe
Get-Command ssh-keygen.exe
Get-Command scp.exe

ssh.exe -V </code>

OpenSSH für Windows stellt unter anderem die Programme ''ssh'', ''scp'' und ''ssh-keygen'' bereit.

=== 3.2 SSH-Schlüssel erzeugen ===

Legen Sie zunächst den Pfad für den neuen SSH-Schlüssel fest:

<code powershell>
$KeyPath = "$env:USERPROFILE\.ssh\<ssh_podman_e3d_usr>"
</code>

Erstellen Sie das Verzeichnis ''.ssh'', falls es noch nicht vorhanden ist:

<code powershell>
New-Item `
    -ItemType Directory `
    -Force `
    -Path "$env:USERPROFILE\.ssh" |
    Out-Null
</code>

Prüfen Sie, ob unter dem gewählten Namen bereits Schlüsseldateien vorhanden sind:

<code powershell>
Test-Path $KeyPath
Test-Path "$KeyPath.pub"
</code>

Beide Befehle sollten folgende Ausgabe liefern:

<code text>
False
</code>

**Hinweis:** Sind unter dem angegebenen Pfad bereits Dateien vorhanden, prüfen Sie vor dem nächsten Schritt, ob diese Schlüssel noch benötigt werden. Vorhandene Schlüssel dürfen nicht unbeabsichtigt überschrieben werden.

Erzeugen Sie anschließend einen neuen SSH-Schlüssel:

<code powershell>
ssh-keygen.exe `
    -t ed25519 `
    -a 100 `
    -f $KeyPath `
    -C "<e3d_usr>@<SERVER>"
</code>

Dabei werden zwei Dateien erzeugt:

<code text>
<ssh_podman_e3d_usr>       Privater Schlüssel
<ssh_podman_e3d_usr>.pub   Öffentlicher Schlüssel
</code>

**Wichtig:** Der private Schlüssel darf den Windows-PC, auf dem REX3D beziehungsweise PSI installiert ist, nicht verlassen.

=== 3.3 Öffentlichen Schlüssel auf den Server übertragen ===

Kopieren Sie den öffentlichen Schlüssel zunächst in das temporäre Verzeichnis des Servers:

<code powershell>
scp.exe `
    "$KeyPath.pub" `
    "<ADMIN>@<SERVER>:/tmp/<e3d_usr>.pub"
</code>

Melden Sie sich anschließend als Administrator auf dem Server an:

<code powershell>
ssh.exe <ADMIN>@<SERVER>
</code>

=== 3.4 Öffentlichen Schlüssel für den Podman-Benutzer installieren ===

Erstellen Sie zunächst das SSH-Verzeichnis des Podman-Benutzers:

<code bash>
sudo install \
  -d \
  -m 700 \
  -o <e3d_usr> \
  -g <e3d_usr> \
  /home/<e3d_usr>/.ssh
</code>

Installieren Sie anschließend den öffentlichen Schlüssel als ''authorized_keys'':

<code bash>
sudo install \
  -m 600 \
  -o <e3d_usr> \
  -g <e3d_usr> \
  /tmp/<e3d_usr>.pub \
  /home/<e3d_usr>/.ssh/authorized_keys
</code>

Löschen Sie danach die temporäre Datei:

<code bash>
sudo rm -f /tmp/<e3d_usr>.pub
</code>

Prüfen Sie abschließend die Berechtigungen:

<code bash>
sudo ls -ld /home/<e3d_usr>/.ssh
sudo ls -l /home/<e3d_usr>/.ssh/authorized_keys
</code>

=== 3.5 SSH-Anmeldung als Podman-Benutzer testen ===

Stellen Sie auf dem Windows-PC eine SSH-Verbindung mit dem neu erzeugten Schlüssel her:

<code powershell>
ssh.exe `
    -i "$env:USERPROFILE\.ssh\<ssh_podman_e3d_usr>" `
    <e3d_usr>@<SERVER>
</code>

Prüfen Sie nach der Anmeldung Benutzer, Gruppen und Arbeitsverzeichnis:

<code bash>
whoami
id
pwd
</code>

Unter anderem werden folgende Werte erwartet:

<code text>
<e3d_usr>
/home/<e3d_usr>
</code>

Die Ausgabe von ''id'' muss die Benutzer- und Gruppeninformationen des Benutzers %%<e3d_usr>%% anzeigen.

Optional können Sie die SSH-Verbindung direkt vom Windows-PC aus testen:

<code powershell>
ssh.exe `
    -i "$env:USERPROFILE\.ssh\<ssh_podman_e3d_usr>" `
    <e3d_usr>@<SERVER> `
    "whoami; podman --version"
</code>

==== 4. Podman-Socket auf dem Server aktivieren ====

=== 4.1 Podman als unprivilegierter Benutzer testen ===

Melden Sie sich als %%<e3d_usr>%% auf dem Server an und führen Sie folgenden Befehl aus:

<code bash>
podman info
</code>

**Wichtig:** Der Befehl muss ohne ''sudo'' ausgeführt werden.

=== 4.2 Podman-Socket aktivieren ===

Aktivieren Sie als Benutzer %%<e3d_usr>%% den Podman-Socket:

<code bash>
systemctl --user enable --now podman.socket
</code>

Prüfen Sie anschließend den Status:

<code bash>
systemctl --user status podman.socket --no-pager
</code>

=== 4.3 Socket-Pfad ermitteln ===

Prüfen Sie den Pfad des Podman-Sockets:

<code bash>
echo "$XDG_RUNTIME_DIR/podman/podman.sock"
ls -l "$XDG_RUNTIME_DIR/podman/podman.sock"
</code>

Der Rootless-Podman-Socket befindet sich standardmäßig unter:

<code text>
/run/user/<UID>/podman/podman.sock
</code>

Ermitteln Sie die numerische UID des Benutzers mit folgendem Befehl:

<code bash>
id -u
</code>

Notieren Sie die ausgegebene UID. Sie wird später für die Einrichtung der Podman-Remote-Verbindung benötigt.

Podman verwendet für den API-Socket die systemd-Socket-Aktivierung. In Verbindung mit ''loginctl enable-linger'' bleibt der Socket auch ohne aktive SSH-Sitzung verfügbar.

==== 5. Podman-Remote-Verbindung auf dem Windows-PC einrichten ====

Auf dem Windows-PC muss ein Podman-Client installiert sein.

=== 5.1 Podman-Verbindung hinzufügen ===

Öffnen Sie PowerShell und legen Sie eine neue Podman-Verbindung an:

<code powershell>
podman.exe system connection add `
    remote-vm-ktp `
    --identity "$env:USERPROFILE\.ssh\<ssh_podman_e3d_usr>" `
    "ssh://<e3d_usr>@<SERVER>/run/user/<UID>/podman/podman.sock"
</code>


=== 5.2 Podman-Verbindung anzeigen ===

Zeigen Sie die konfigurierten Verbindungen an:

<code powershell>
podman.exe system connection list
</code>

Die Verbindung ''remote-vm-ktp'' sollte in der Liste erscheinen.

=== 5.3 Podman-Verbindung testen ===

Testen Sie die Verbindung:

<code powershell>
podman.exe `
    --connection remote-vm-ktp `
    info
</code>

Der Befehl sollte Informationen zur Podman-Installation auf dem Linux-Server anzeigen.



Der Container wird auf dem Linux-Server ausgeführt. Auf dem Windows-PC wird lediglich der Podman-Remote-Client verwendet.

==== 6. Podman-Verbindung in REX3D konfigurieren ====

Öffnen Sie die REX3D-Optionen und tragen Sie dort den Namen der zuvor angelegten Podman-Verbindung ein.

Bei Verwendung der Befehle aus dieser Anleitung lautet der Verbindungsname:

<code text>
remote-vm-ktp
</code>

**Entfernen** Sie den Haken bei 'Lokale Maschine nutzen'

{{ :rex3d:rex19_openfoam_remote_de.png?nolink |}}
Die verfügbaren Podman-Verbindungen können jederzeit mit folgendem Befehl über die Powershell angezeigt werden:

<code powershell>
podman.exe system connection list
</code>

Nach erfolgreicher Konfiguration kann REX3D die OpenFOAM-Container über die eingerichtete Podman-Remote-Verbindung auf dem Linux-Server verwenden.

==== Sicherheitshinweise ====

Der Podman-API-Socket ermöglicht die vollständige Verwaltung aller Container, Images, Volumes und Pods des Benutzers %%<e3d_usr>%%.

**Wichtig:** Veröffentlichen Sie den Podman-Socket nicht über einen ungeschützten TCP-Port. Verwenden Sie stattdessen den in dieser Anleitung beschriebenen Zugriff über SSH auf den benutzereigenen Unix-Socket.

Für den Benutzer %%<e3d_usr>%% gelten folgende Empfehlungen:

  * Der Benutzer sollte **keine** ''sudo''-Rechte besitzen.
  * Der Benutzer sollte **kein** Mitglied privilegierter Gruppen sein.
  * Der Benutzer sollte **ausschließlich** auf die benötigten Dateien und Verzeichnisse zugreifen können.
  * Der Benutzer sollte **ausschließlich** für REX3D, PSI und die zugehörigen OpenFOAM-Container verwendet werden.
  * Für den Benutzer sollte ein eigener SSH-Schlüssel verwendet werden.
  * Dem Benutzer dürfen **keine** privaten Schlüssel anderer Benutzer zur Verfügung gestellt werden.


===Weitere Themen===
  * [[rex3d:rex3dpreprocessing|]]
  * [[rex3d:rex3dpostprocessing|]]

  * [[rex3d:rex3dkonfiguration|]]
  * [[rex3d:openfoamremote|]]