Administrator-Dokumentation

Zielgruppe dieses Abschnitts sind System- und Anwendungsadministratoren.

IGUASU Installationsverzeichnis

Verzeichnis "bin"

Alle notwendigen Skripte zum Starten und Stoppen von IGUASU und zur Installation als Windows und Linux befinden sich in diesem Verzeichnis.

Verzeichnis "data"

Alle Daten und Repositories die während der Ausführung von IGUASU zur Laufzeit erzeugt werden, werden hier abgelegt. Um den Speicherort anzupassen, müssen Sie die Dateien ui/conf/iguasu-ui.properties und in nifi/conf/nifi.properties anpassen.

Verzeichnis "ui"

Enthält die IGUASU UI Installation

Verzeichnis "nifi"

Enthält die NiFi Installation

Datei	Parameter
iguasu-ui.properties	ui.data-directory
nifi.properties	nifi.flow.configuration.file nifi.flow.configuration.archive.dir nifi.templates.directory nifi.database.directory nifi.flowfile.repository.directory nifi.content.repository.directory.default nifi.provenance.repository.directory.default

Datei

Parameter

iguasu-ui.properties

ui.data-directory

nifi.properties

nifi.flow.configuration.file
nifi.flow.configuration.archive.dir
nifi.templates.directory
nifi.database.directory
nifi.flowfile.repository.directory
nifi.content.repository.directory.default
nifi.provenance.repository.directory.default

Konfiguration

Allgemeines

Bedingungen

IGUASU setzt eine vorhandene Java Runtime in Version 17 voraus.
Diese muss über die Umgebungsvariable JAVA_HOME verfügbar gemacht werden.

Falls JAVA_HOME nicht systemweit verfügbar gemacht werden kann, oder mehrere unterschiedliche Runtimes auf dem System installiert sind, so kann JAVA_HOME explizit für IGUASU in der Datei ./bin/iguasu-env.sh konfiguriert werden.

Wichtige Befehle

Installation/Deinstallation des systemd Services
```
./bin/iguasu.sh install|uninstall
```
Starten von IGUASU im Vordergrund (Logausgabe erfolgt in Konsole, beendet wird mit ctrl/strg + c)
```
./bin/iguasu.sh run
```
Starten/Stoppen von IGUASU im Hintergrund
```
./bin/iguasu.sh start|stop
```

Konfiguration NiFi

Linux System-Konfiguration

Zur Vorbereitung des Systems lesen Sie in der NiFi Dokumentation den Abschnitt Best Practices.

Die hier in den Best Practices verlinkten Einstellungen können die Performance von IGUASU stark beeinflussen bzw. bei zu geringen Werten zu Problemen führen!

Sizing

NiFi ist grundsätzlich dafür designt alle verfügbaren Ressourcen des Knotens zu verwenden. Processors, RAM, Netzwerk und Festplatte.

Das größte Bottleneck ist typischerweise Disk I/O. Tritt das auf, ist es sinnvoll jedem Repository (Content, FlowFile, Provenance) eine dedizierte Platte zuzuordnen. Ein Repository (z.B. Content) kann auch selbst noch über mehrere Platten bzw. Verzeichnisse verteilt werden. SSDs sind besser als Festplatten.

NiFi kann FlowFiles jeder Größe verarbeiten und hält diese dabei nicht komplett im Speicher. Somit reichen typischerweise 8 GB bis 16 GB Java Heap aus. Es ist aber zu bedenken, dass einzelne Processors auch mehr Speicher benötigen können und z.B. auch ein komplettes XML als DOM in den Speicher laden können, wenn sie so implementiert sind (die typischen Record basierten Processors tun dies aber nicht).

Empfehlungen:

At least 4 cores per NiFi node (more is better and 8 cores usually provides the best starting point for the most common use cases)
At least 6 disks per NiFi node to ensure dedicated disks for repositories
At least 4GB of RAM for the NiFi heap

Content Archiving

Der Content der FlowFiles wird normalerweise aus dem Content Repository gelöscht, sobald ein FlowFile NiFi verläßt - also z.b. der Flow an einem Processor endet. Es gibt aber das Content Archiving, welches sich konfigurieren lässt.

Die Archivierung dient dazu, dass man über die Provenance der FlowFiles (also den Verlauf, den sie durch die Flows genommen haben) auch jeweils den Content an den Processors einsehen kann. Ebenso kann hierüber an der jeweiligen Stelle ein "Replay" mit den Daten erfolgen. Die Properties, um dies zu steuern sind:

nifi.content.repository.archive.max.retention.period=12 hours
nifi.content.repository.archive.max.usage.percentage=50%
nifi.content.repository.archive.enabled=true

Wird die Archivierung so eingeschaltet, werden "content claims" (der Content in NiFi-Stücken) im Content Repository jeweils in archive Unterordner verschoben und nicht gelöscht. Da hier nur ein move stattfindet, sollte das sehr schnell sein und keine Last erzeugen.

Die retention.period und die usage.percentage geben an, wann die Daten dann letztendlich gelöscht werden sollen. Beides sind weiche Kriterien - wenn ein Checkpoint erkennt, dass sie überschritten sind, werden die ältesten Dateien gelöscht, bis das Kriterium erfüllt ist.

Es ist sehr wichtig, dass entweder genug Platz auf der Festplatte ist, so dass die nifi.content.repository.archive.max.usage.percentage (hier 50 %), nicht ständig eintritt oder nifi.content.repository.archive.enabled auf false geschaltet wird. Ist die Archivierung aktiviert, es gibt aber grundsätzlich weniger freien Plattenplatz als hier als Grenze eingestellt ist, wird das System sehr langsam und potenziell instabil.

Konfiguration IGUASU UI

IGUASU UI kann über die Datei iguasu-ui.properties im Verzeichnis iguasu-x.x.x/ui/conf konfiguriert werden.

Im Folgenden werden die wichtigsten Parameter erklärt:

Webserver Konfiguration

Parameter	Bedeutung
server.port	der Port auf dem die Oberfläche von IGUASU UI läuft
server.ssl.key-store	Der Ort an dem der Java Keystore liegt. Dieser wird benötigt, falls Sie die Oberfläche über HTTPS aufrufen möchten.
server.ssl.key-store-password	Das Passwort für den Keystore
server.ssl.key-alias	Der Alias für das SSL Zertifikat
server.ssl.key-password	Das Passwort für das SSL Zertifikat

Parameter

Bedeutung

server.port

der Port auf dem die Oberfläche von IGUASU UI läuft

server.ssl.key-store

Der Ort an dem der Java Keystore liegt. Dieser wird benötigt, falls Sie die Oberfläche über HTTPS aufrufen möchten.

server.ssl.key-store-password

Das Passwort für den Keystore

server.ssl.key-alias

Der Alias für das SSL Zertifikat

server.ssl.key-password

Das Passwort für das SSL Zertifikat

Logging

Parameter	Bedeutung
logging.file.name	Der Ort an dem IGUASU UI die Log Dateien speichert
logging.level.*	Verschiedene Logging Filter. Default ist INFO. Um Debugginginformationen zu erhalten, stellen Sie das Level auf DEBUG

Parameter

Bedeutung

logging.file.name

Der Ort an dem IGUASU UI die Log Dateien speichert

logging.level.*

Verschiedene Logging Filter. Default ist INFO. Um Debugginginformationen zu erhalten, stellen Sie das Level auf DEBUG

OpenID Connect Konfiguration

registration-id und provider-id können frei gewählt werden, müssen allerdings eindeutig sein
Ein Beispiel finden Sie unter (OIDC LINK).

Parameter	Bedeutung
spring.security.oauth2.client.registration.<registration-id>.client-name	Name des OIDC Provider, z.B. Virtimo Keycloak
spring.security.oauth2.client.registration.<registration-id>.client-id	die ClientId unter der IGUASU im Provider registriert ist
spring.security.oauth2.client.registration.<registration-id>.client-secret	das Client Secret
spring.security.oauth2.client.provider.<provider-id>.user-name-attribute	das Mapping für den Benutzernamen, z.B. username oder email
spring.security.oauth2.client.provider.<provider-id>.issuer-uri	die Url unter der IGUASU nach der OpenID Provider Konfiguration sucht

Parameter

Bedeutung

spring.security.oauth2.client.registration.<registration-id>.client-name

Name des OIDC Provider, z.B. Virtimo Keycloak

spring.security.oauth2.client.registration.<registration-id>.client-id

die ClientId unter der IGUASU im Provider registriert ist

spring.security.oauth2.client.registration.<registration-id>.client-secret

das Client Secret

spring.security.oauth2.client.provider.<provider-id>.user-name-attribute

das Mapping für den Benutzernamen, z.B. username oder email

spring.security.oauth2.client.provider.<provider-id>.issuer-uri

die Url unter der IGUASU nach der OpenID Provider Konfiguration sucht

IGUASU UI

Parameter	Bedeutung
ui.security-enabled	aktiviert die Absicherung der Webanwendung und erfordert die Konfiguration des OpenID Connect Providers
ui.production-mode	aktiviert den Production Mode Weitere Informationen finden Sie unter Production Mode vs Development Mode
ui.allow-test-in-production-mode	aktiviert Testläufe von Processors im Production Mode Weitere Informationen finden Sie unter Production Mode vs Development Mode
ui.data-directory	der Ort an dem IGUASU UI Laufzeitdaten ablegt
ui.nifi.directory	der Ort an dem IGUASU UI nach der lokalen NiFi Installation sucht
ui.nifi.url	die URL unter der NiFi läuft
ui.nifi.security.keystore	der Keystore in dem das Zertifikat zur Kommunikation mit NiFi abgelegt ist
ui.nifi.security.keystorePassword	das Keystore Passwort
ui.nifi.security.keyAlias	der Alias des Zertifikates
ui.nifi.security.keyPassword	das Zertifikatspasswort
ui.nifi.security.truststore	der Truststore in dem das Zertifikat zur Kommunikation mit NiFi abgelegt ist
ui.nifi.security.truststorePassword	das Zertifikatspasswort

Parameter

Bedeutung

ui.security-enabled

aktiviert die Absicherung der Webanwendung und erfordert die Konfiguration des OpenID Connect Providers

ui.production-mode

aktiviert den Production Mode
Weitere Informationen finden Sie unter Production Mode vs Development Mode

ui.allow-test-in-production-mode

aktiviert Testläufe von Processors im Production Mode
Weitere Informationen finden Sie unter Production Mode vs Development Mode

ui.data-directory

der Ort an dem IGUASU UI Laufzeitdaten ablegt

ui.nifi.directory

der Ort an dem IGUASU UI nach der lokalen NiFi Installation sucht

ui.nifi.url

die URL unter der NiFi läuft

ui.nifi.security.keystore

der Keystore in dem das Zertifikat zur Kommunikation mit NiFi abgelegt ist

ui.nifi.security.keystorePassword

das Keystore Passwort

ui.nifi.security.keyAlias

der Alias des Zertifikates

ui.nifi.security.keyPassword

das Zertifikatspasswort

ui.nifi.security.truststore

der Truststore in dem das Zertifikat zur Kommunikation mit NiFi abgelegt ist

ui.nifi.security.truststorePassword

das Zertifikatspasswort

Production Mode vs Development Mode

Wenn der Production Mode aktiviert ist, dann gibt es eine Reihe von Änderungen in der Verwendung von Flow:

Der Aufruf von IGUASU im Browser muss über HTTPS erfolgen. Andernfalls startet das IGUASU UI nicht. Im Log wird folgende Fehlermeldung ausgegeben:

If you run the application with productionmode=true you need to configure authentication and tls for IGUASU
Please follow the Admin Guide or check the README about how to secure IGUASU.

Ändern/Löschen von Connections erfordert ein explizites Stoppen der Ziele/Quellen der Connection
Beim Wechsel zwischen Entities wird nicht automatisch gespeichert, sondern Sie werden zum Speichern oder Verwerfen der Änderungen aufgefordert.
allow-test-in-production-mode:
wenn aktiviert, dann wird vor einem Testlauf eines Processors eine Warnung ausgegeben,
wenn deaktiviert, dann können keine Testläufe von Processors gestartet werden

Teamwork

Teamwork kann über die Datei ui/conf/iguasu-ui.properties konfiguriert werden:

Parameter	Value
ui.teamwork.diagram	true \| false true, wenn die Benutzer am Diagram angezeigt werden sollen
ui.teamwork.header	true \| false true, wenn die Benutzer in der globalen Toolbar angezeigt werden sollen
ui.teamwork.pictures	true \| false Gibt an, die Profil-Bilder der Nutzer geladen und angezeigt werden sollen, wenn es über OIDC das Benuter-Attribut 'picture' gibt.
ui.teamwork.users.not	user1@example.com, user2@example.com Durch Komma getrennte Liste von Benutzern, welche ausgeblendet werden sollen. Alle anderen werden angezeigt. Leer, wenn nicht konfiguriert.
ui.teamwork.users.only	user1@example.com, user2@example.com Durch Komma getrennte Liste von Benutzern, angezeigt werden sollen. Alle anderen werden nicht angezeigt. Leer, wenn nicht konfiguriert.

Parameter

Value

ui.teamwork.diagram

true | false
true, wenn die Benutzer am Diagram angezeigt werden sollen

ui.teamwork.header

true | false
true, wenn die Benutzer in der globalen Toolbar angezeigt werden sollen

ui.teamwork.pictures

true | false
Gibt an, die Profil-Bilder der Nutzer geladen und angezeigt werden sollen, wenn es über OIDC das Benuter-Attribut 'picture' gibt.

ui.teamwork.users.not

user1@example.com, user2@example.com
Durch Komma getrennte Liste von Benutzern, welche ausgeblendet werden sollen.
Alle anderen werden angezeigt.
Leer, wenn nicht konfiguriert.

ui.teamwork.users.only

user1@example.com, user2@example.com
Durch Komma getrennte Liste von Benutzern, angezeigt werden sollen.
Alle anderen werden nicht angezeigt.
Leer, wenn nicht konfiguriert.

Um die Profilbilder bei der Nutzung mit Keycloak zu aktivieren, muss in Keycloak das Attribut 'picture' über einen Mapper gesetzt werden. Für die Anbindung über Google Account heißt das:

Hinzufügen eines picture Attributes unter Realm settings/User Profile
Hinzufügen eines Mappers mit Namen picture unter Identity Providers/Google/Mappers
ID, Name und Social Profile JSON Field Path auf picture setzen; Sync mode override im Zweifelsfall auf Force setzen; der Mapper type ist ein Attribute Importer

Sicherheit

Einrichtung Single User Authentication

Wenn kein OIDC Provider konfiguriert wird, startet NiFi im Single User Modus. Der Benutzername und das Passwort werden beim ersten Start automatisch generiert und können in der Logdatei nifi-app.log eingesehen werden.

Um den Benutzernamen und das Passwort zu verändern, geben Sie vor dem Start von IGUASU folgen Befehl ein:

./nifi/bin/nifi.sh set-single-user-credentials <username> <password>

Einrichtung OpenId Connect

Bitte beachten Sie: Nach der erfolgreichen Einrichtung von OpenId Connect ist es notwendig, dass die erste Anmeldung am System mit einem Administrator Account erfolgen muss. Das System wird mit diesem Account eine automatische Konfiguration durchführen und so die Ersteinrichtung abschließen.

Für die Einrichtung von OpenId Connect wird ein Identity Provider benötigt. Dafür kann Keycloak oder auch ein anderer Identity Provider wie Google OAuth 2.0 eingesetzt werden.

Einrichtung Google

Legen Sie ein neues Projekt unter https://console.developers.google.com/ an, oder wählen Sie ein bereits vorhandenes Projekt aus.
Wählen sie unter OAuth-Zustimmungsbildschirm Intern
Nach der Erstellung des Zustimmungsbildschirmes muss dieser konfiguriert werden. Vergeben Sie einen Namen für die Anwendung, wählen Sie eine Support E-Mail-Adresse aus und tragen Sie die autorisierten Domains ein.
Navigieren Sie anschließend zum Punkt Anmeldedaten, klicken Sie auf Anmeldedaten erstellen und wählen OAuth-Client-ID aus.
Wählen Sie Webanwendung aus, vergeben Sie einen Namen und geben Sie als autorisierte Weiterleitungs-URL die URL Adresse des IGUASU UI Servers und des NiFi Servers in folgendem Format an:
- (https://)<url-iguasu-ui>/login/oauth2/code/google
- (https://)<url-nifi>/nifi-api/access/oidc/callback
Anschließend erscheint ein Popup Fenster mit der Client ID und dem Client Secret.

Diese Informationen werden für die spätere Konfiguration von NiFi und dem IGUASU UI benötigt.

Einrichtung Keycloak

Erzeugen Sie einen neuen Realm und wählen Sie diesen aus.
IGUASU verwendet Gruppen, um die Berechtigungen von Benutzern zu verwalten. Legen Sie flow_admin und flow_dev an.
Legen Sie einen Servicebenutzer für IGUASU an, damit Benutzer und Rollen in Keycloak abgefragt werden können. Dieser Benutzer muss in den "Role Mappings" unter "Client Roles: realm-management" die Role view_users erhalten. Der Name und das Passwort werden später im IGUASU Toolkit unter NiFi Keycloak service account abgefragt.
Für den ersten Start benötigt IGUASU einen Administrator Account der in die der Gruppe "flow_admin" hinzugefügt werden muss. Der Benutzername wird später im IGUASU Toolkit unter NiFi initial user identity bzw. NiFi initial admin identity abgefragt.
Keycloak enthält in der Standardkonfiguration einen Client namens "admin-cli". Diesem muss die Rolle view_users hinzugefügt werden. IGUASU verwendet diesen Client um Rollen und Benutzer von Keycloak abfragen zu können.
Legen Sie einen neuen Client mit dem Client an.
1. Client Protocol auf openid-connect setzen.
2. Access Type auf confidential setzen.
3. Valid Redirect URIs für IGUASU UI und NiFi hinzufügen.
  
  https://iguasu.example.com:iguasu-ui-port/* und https://iguasu.exmple.com:nifi-port/*

Nachdem Sie die Änderungen gespeichert haben, können Sie sich im Reiter Installation die Keycloak Konfiguration im JSON Format ansehen.Wichtige Informationen sind: realm (der Realm Name), resource (die Client ID), secret (das Client Secret), auth-server-url (die Keycloak URL).

IGUASU Toolkit ausführen

Für die Ausführung sollte sich das IGUASU Toolkit im IGUASU Verzeichnis befinden.

IGUASU Verzeichnis Struktur

iguasu-x.x.x
├── bin
├── iguasu-toolkit-x.x.x
├── ui
└── nifi

Starten Sie das IGUASU Toolkit, indem Sie im Verzeichnis iguasu-toolkit-x.x.x/bin die Datei run.sh (Linux/Mac) / run.bat (Windows) ausführen.

Nach der Ausführung sollten die verfügbaren Befehle, wie im Screenshot dargestellt, aufgelistet werden. Um die Konfiguration mit Keycloak als OIDC Provider zu starten, geben Sie folgenden Befehl ein:

IGUASU-TOOLKIT>secure -p keycloak

Für alle anderen Identity Provider verwenden Sie:

IGUASU-TOOLKIT>secure

oder

IGUASU-TOOLKIT>secure -p other

Folgende Parameter werden nun im IGUASU-Toolkit abgefragt:

IGUASU server domain name - der Domain Name des IGUASU Servers.
IGUASU server host name - der Host Name des IGUASU Servers.
Common OIDC URL - die URL des Keycloak Servers
Common OIDC Realm - der Keycloak Realm Name.
Common OIDC Client ID - die Client ID.
Common OIDC Client Secret - das Client Secret
Common OIDC Username mapping email/preferred_username - Mapping der Benutzer in IGUASU anhand von E-Mail/Benutzername
NiFi HTTPS port - Port des Nifi Services
NiFi truststore password - Truststore Passwort. Leere Eingabe generiert automatisch einen neuen Truststore mit einem zufälligen Passwort.

Für eine abgesicherte Kommunikation zwischen dem IGUASU UI und NiFi werden Trust- und Keystores verwendet. Das IGUASU Toolkit kann automatisch die notwendigen Schlüssel samt den Trust- und Keystores generieren. In den eckigen Klammern wird das Zufallspasswort angezeigt welcher für den Trust- /Keystore generiert wird, falls kein eigenes verwendet wird.

NiFi keystore password - Keystore Passwort. Leere Eingabe generiert automatisch einen neuen Keystore mit einem zufälligen Passwort.
NiFi Keycloak service account username - Benutzername des IGUASU Service Accounts
NiFi Keycloak service account password - Passwort des IGUASU Service Accounts
NiFi initial user identity - Benutzername des IGUASU Administrator Accounts
NiFi initial admin identity - Benutzername des IGUASU Administrator Accounts

Es ist zu beachten, dass der Username entsprechend der bereits abgefragten Einstellungen des Mappings "email/preferred_username" erzeugt wird. Also falls beispielsweise die "email" ausgewählt wurde, muss hier die E-Mail des Users eingetragen werden.

IGUASU UI keystore password (minimum 6 characters) - Keystore Passwort für IGUASU UI. Leere Eingabe generiert automatisch einen neuen Keystore mit einem zufälligen Passwort.
IGUASU UI truststore password (minimum 6 characters) - Truststore Passwort für IGUASU UI. Leere Eingabe generiert automatisch einen neuen Truststore mit einem zufälligen Passwort.
IGUASU UI secret key password (minimum 6 characters) - Secret Key für IGUASU UI. Leere Eingabe generiert automatisch einen neuen zufälligen Secret Key.
Do you want to enable HTTPS for IGUASU UI? - Stellt IGUASU UI auf die verwendung von TLS um.
IGUASU UI Port - Port des IGUASU UI Services

Backup

Wichtige zu sichernde Verzeichnisse sind:

iguasu-x.x.x/nifi/conf/
iguasu-x.x.x/ui/conf/
iguasu-x.x.x/data/nifi/conf/

Wenn es notwendig sein sollte, dass Laufzeitdaten nach einer Wiederherstellung vorhanden sein müssen, dann wird zusätzlich noch folgendes Verzeichnis benötigt:

iguasu-x.x.x/data/nifi/work/

dieses Verzeichnis kann unter Umständen erheblichen Plattenplatz belegen

Migration

Deinstallation des alten systemd IGUASU Services (stoppt auch eine möglicherweise laufende IGUASU Instanz).
```
 ./bin/iguasu.sh uninstall
```
Kopieren der Konfiguration und der Daten in die neue Installation
1. Für eine komplette Kopie werden folgende Verzeichnisse benötigt:
  ./nifi/conf/ ./ui/conf/ ./data/
2. Für eine minmale Migration ohne Verlaufsdaten müssen die beiden Dateien
  ./nifi/conf/flow.json.gz ./nifi/conf/flow.xml.gz
  in die neue Installation kopiert werden.
  
  Falls in
  ./data/keystores und ./data/driver
  Dateiein vorhanden sind, sollten diese ebenfalls kopiert werden.
  
  Wichtig ist hierbei, dass folgende Properties aus der Datei ./nifi/conf/nifi.properties ebenfalls übernommen werden.
  nifi.sensitive.props.key= nifi.sensitive.props.key.protected= nifi.sensitive.props.algorithm= nifi.sensitive.props.additional.keys=
  Je nach Authentifizierungskonfiguration müssen die Schritte im Abschnitt Sicherheit erneut ausgeführt werden.
Eventuelle Anpassungen aus
```
 ./bin/iguasu-env.sh
```
sollten ebenfalls übernommen werden
Installation des neuen systemd IGUASU Services (die neue IGUASU Instanz wird dabei automatisch gestartet).
```
 ./bin/iguasu.sh install
```

Unter Umständen kann es sinnvoll sein, die Konfiguration von einer vorhandenen iguasu-x.x.x/nifi/conf/nifi.properties und iguasu-x.x.x/ui/conf/iguasu.properties Datei in die neuen Konfigurationsdateien von Hand zu übernehmen. Um sich einen schnellen Überblick über die geänderten Zeilen zu verschaffen, kann folgender Befehl verwendet werden:

diff -a --suppress-common-lines -y <file1> <file2>