In vielen Unternehmen gibt nicht der Scheduler der IDMC den Takt vor, sondern ein zentraler Scheduler wie Control-M, UC4 oder schlicht cron. Der muss einen Mapping Task oder Taskflow in der Cloud starten, auf das Ende warten und am Exit-Code erkennen, ob alles geklappt hat. Wie geht man aber vor, wenn zwischen Secure Agent und Cloud auch noch ein Proxy mit Benutzer und Passwort sitzt?

Informatica liefert dafür die runAJobCli mit dem Secure Agent aus. Mit dem IPU-Modell sind laut Informatica alle berechtigten Cloud-Dienste enthalten; in älteren Orgs mit feature-basierter Lizenz braucht ihr laut Knowledge Base das Paket RunAJobCli, das ihr im Administrator unter Licenses seht. In diesem Artikel zeige ich euch, wie man sie einrichtet, Jobs startet und die Proxy-Anmeldung zum Laufen bringt. Die Dokumentation ist an einigen Stellen dünn. Deshalb habe ich mir den Code des Werkzeugs (Version 250902) angesehen, und einige der Angaben unten stammen aus dieser Analyse und nicht aus der offiziellen Doku.

Wo die runAJobCli liegt

Die runAJobCli ist ein kleines Java-Programm. Ihr findet sie im Installationsverzeichnis des Secure Agents unter apps/runAJobCli. Aufgerufen wird sie unter Linux über cli.sh, unter Windows gibt es dasselbe als cli.bat. Meine Beispiele zeigen Linux. Beide Skripte wechseln in ihr eigenes Verzeichnis, deshalb müssen alle Konfigurationsdateien direkt daneben liegen.

Im Lieferumfang stecken nur Vorlagen mit der Endung _default. Vor dem ersten Aufruf kopiert man sie. In meinem Beispiel liegt der Secure Agent unter /opt/infaagent:

cd /opt/infaagent/apps/runAJobCli
cp restenv_default.properties restenv.properties
cp log4j2_default.properties log4j2.properties
cp set_cli_vars_default.sh set_cli_vars.sh
chmod 600 restenv.properties set_cli_vars.sh

Das chmod sorgt dafür, dass nur der Besitzer die Dateien mit den Zugangsdaten lesen kann. Legt sie deshalb als der Benutzer an, unter dem das CLI später läuft.

Fehlt restenv.properties, bricht das CLI sofort mit Exit-Code −1 ab. Fehlt log4j2.properties, gibt es nur eine Warnung.

Hinweis: Die Skripte rufen schlicht java auf. Es muss also ein Java im PATH des Benutzers liegen, unter dem der Scheduler das CLI startet. Die Doku verlangt mindestens Java 1.8. Laut Informatica-Knowledge-Base kann man cli.sh alternativ auf das JRE im Verzeichnis des Secure Agents zeigen lassen.

Konfiguration in restenv.properties

Die zentrale Datei ist restenv.properties. In meinem Beispiel sieht sie so aus:

baseUrl=https://dm-em.informaticacloud.com/ma
username=svc_scheduler
password=:2x...
orgId=
ACTIVITYMONITORWAIT=2000
TOTALWAIT=20000
RETRYCOUNT=720
PROXYHOST=proxy.firma.local
PROXYPORT=8080
use.encryption=true
use.oAuth=false

Die baseUrl ist die Login-URL eurer Region mit /ma am Ende, also etwa dm-us oder dm-em. Die übrigen Schlüssel haben folgende Bedeutung:

Schlüssel Bedeutung
username, password nativer Benutzer der IDMC (SAML-Benutzer gehen nicht); das Passwort verschlüsselt, falls use.encryption=true
orgId, use.oAuth nur für die Anmeldung per OAuth-Token (-oauthtoken)
ACTIVITYMONITORWAIT Pause in Millisekunden nach Fehlern und zwischen Login-Versuchen
TOTALWAIT Pause in Millisekunden zwischen zwei Statusabfragen
RETRYCOUNT maximale Zahl der Statusabfragen und der Wiederholungen bei HTTP-Fehlern; leer laut Code 3, die Doku nennt als Standard 6
PROXYHOST, PROXYPORT Proxy für die Verbindung zur Cloud
CONNECT_TIMEOUT_SECONDS nicht in der Vorlage: Verbindungs-Timeout, Standard 30 Sekunden

Die Optionen -u, -p und -bu auf der Kommandozeile überschreiben Benutzer, Passwort und Base-URL aus der Datei. Für den Scheduler würde ich trotzdem alles in der Datei ablegen, damit keine Zugangsdaten in den Job-Definitionen stehen.

Passwort verschlüsseln

Das IDMC-Passwort sollte nicht im Klartext in der Datei stehen. Dafür bringt das CLI das Plugin encryptText mit:

./cli.sh encryptText -t 'MeinGeheimesPasswort'

Die Ausgabe beginnt mit :2x. Diesen Text trägt man als password ein und setzt use.encryption=true. Das CLI entschlüsselt ihn beim Start mit einem Schlüssel aus der Datei key-store.txt im selben Verzeichnis.

Hinweis: Der Schlüsselspeicher ist seinerseits mit einem Passwort geschützt, das aus der Umgebungsvariable RUNAJOB_KEYSTORE_PASSWORD kommt. Ist sie leer, verwendet das CLI laut Code ein fest eingebautes Standardpasswort aus 16 Nullen. Das ist dann nur eine Verschleierung, und das CLI warnt bei jedem Lauf. Setzt die Variable deshalb in set_cli_vars.sh und verschlüsselt das Passwort erst danach:

export RUNAJOB_KEYSTORE_PASSWORD='EinLangesKeystorePasswort'

Jobs starten

Die Pflichtoption ist -t mit dem Task-Typ, etwa MTT für einen Mapping Task, DSS für einen Synchronization Task oder TASKFLOW. Einen Mapping Task startet man über seinen Namen. Liegt er nicht im Default-Ordner, gibt man mit -fp Projekt und Ordner an:

./cli.sh runAJobCli -t MTT -n mt_Kunden_Laden -fp "DWH/Staging"

Ohne -fp sucht das CLI den Namen nur im Default-Ordner. Das ist wichtig, weil Namen in der IDMC nur innerhalb eines Ordners eindeutig sind. Eine Parameterdatei übergibt man mit -pf (Dateiname) und -pd (Verzeichnis auf dem Secure Agent):

./cli.sh runAJobCli -t MTT -n mt_Kunden_Laden -fp "DWH/Staging" -pf kunden.param -pd /data/informatica/params

Taskflows startet das CLI ausschließlich über ihren eindeutigen API-Namen. Den erzeugt die IDMC beim Veröffentlichen automatisch; mit „Override API Name“ in den allgemeinen Eigenschaften des Taskflows könnt ihr einen eigenen vergeben. Der Taskflow muss veröffentlicht sein, und die Felder „Allowed Users“ und „Allowed Groups“ müssen gefüllt sein. Die Optionen -n und -fp werden bei TASKFLOW ignoriert. Optional kommen ein Parameterset (-pun) und ein Instanzname (-in) dazu:

./cli.sh runAJobCli -t TASKFLOW -un tf_DWH_Nachtlauf -pun ps_Produktion -in "Nachtlauf 2026-01-19"

Mit -w false startet das CLI den Job und kehrt sofort zurück. Standard ist -w true, dann wartet es auf das Ende. Für die Fehlersuche gibt es -d für ein ausführliches Log in logs/runAJobCli.log.

Exit-Codes und Wartezeit

Der Scheduler wertet den Exit-Code aus:

Code Bedeutung
0 erfolgreich
1 Warnung (nur bei Tasks, nicht bei Taskflows)
3 Job fehlgeschlagen
5 Start abgelehnt, Task nicht gefunden oder Taskflow angehalten (suspended)
6 Job läuft noch
−1 Konfigurationsfehler, Login gescheitert oder anderer Programmfehler

Die Doku führt zusätzlich die Codes 2 (No wait), 4 (Timeout) und 7 (Failure to start) auf. Im Code der Version 250902 werden 2 und 4 nie gesetzt: Einen Lauf ohne Warten und einen abgebrochenen Wartevorgang meldet das CLI beide mit 6.

Beim Code 6 lauert die größte Falle der runAJobCli. Ihr bekommt ihn nicht nur bei -w false, sondern auch dann, wenn das CLI das Warten aufgibt. TOTALWAIT ist nämlich nicht die Gesamtwartezeit, wie der Name vermuten lässt, sondern die Pause zwischen zwei Statusabfragen. Laut Code kommen pro Abfrage noch zehn Sekunden dazu, und RETRYCOUNT begrenzt die Zahl der Abfragen. Die maximale Wartezeit liegt damit ungefähr bei:

(RETRYCOUNT + 1) × (TOTALWAIT + 10 s)

Die Doku nennt die zehn Sekunden ebenfalls, rechnet in ihrem Beispiel aber ohne das + 1 (30 × 70 Sekunden = 35 Minuten). Mit den Werten aus der Vorlage (TOTALWAIT=5000, RETRYCOUNT leer, laut Code also 3) gibt das CLI nach rund einer Minute auf, obwohl der Job in der Cloud weiterläuft. Mit dem Standardwert 6 aus der Doku wären es knapp zwei Minuten. Für einen Nachtlauf, der bis zu sechs Stunden dauern darf, setze ich deshalb TOTALWAIT=20000 und RETRYCOUNT=720. Das ergibt eine Abfrage alle 30 Sekunden über sechs Stunden. Weil RETRYCOUNT auch die Wiederholungen bei HTTP-Fehlern steuert, versucht das CLI es dann allerdings auch bei Netzwerkproblemen entsprechend oft.

Proxy mit Benutzer und Passwort

Jetzt zum eigentlichen Anlass dieses Artikels. Den Proxy selbst tragt ihr als PROXYHOST und PROXYPORT in restenv.properties ein. Das CLI übersetzt diese Werte in die Java-Einstellungen https.proxyHost und https.proxyPort. Für Benutzer und Passwort gibt es in der Datei aber keinen Schlüssel.

Stattdessen liest das CLI die Java-Systemeigenschaften https.proxyUser und https.proxyPassword. Die übergibt man über die Variable CLI_JAVA_OPTS in set_cli_vars.sh, die cli.sh vor dem Start einliest. Mit diesen beiden Werten allein bekommt ihr in vielen Umgebungen aber weiterhin einen Fehler dieser Art:

java.io.IOException: Unable to tunnel through proxy. Proxy returns "HTTP/1.1 407 Proxy Authentication Required"

Der Grund liegt in Java selbst. Die IDMC spricht HTTPS, also baut Java über den Proxy mit CONNECT einen Tunnel auf. Seit Java 8u111 ist die Basic-Authentifizierung für genau diesen Tunnelaufbau standardmäßig abgeschaltet (Eigenschaft jdk.http.auth.tunneling.disabledSchemes=Basic in der net.properties des JDK). Das CLI benutzt die in Java eingebaute HTTP-Verbindung und hebt diese Sperre nicht auf. Der Proxy fordert die Anmeldung an, Java schickt sie nicht, und der Proxy antwortet mit 407.

Die runAJobCli schickt CONNECT an den Proxy, erhält 407, sendet mit aufgehobener Java-Sperre die Basic-Anmeldung und spricht danach durch den Tunnel mit der IDMC
Tunnelaufbau über einen Proxy mit Anmeldung.

Die Lösung ist eine dritte Systemeigenschaft, die die Sperre mit einem leeren Wert aufhebt. In set_cli_vars.sh sieht das so aus:

export RUNAJOB_KEYSTORE_PASSWORD='EinLangesKeystorePasswort'
export CLI_JAVA_OPTS='-Dhttps.proxyUser=svc_proxy -Dhttps.proxyPassword=ProxyPasswort -Djdk.http.auth.tunneling.disabledSchemes='

Beim Einrichten solltet ihr noch auf ein paar Dinge achten:

  • Anmeldedaten schickt das CLI laut Code nur, wenn PROXYHOST gesetzt ist, und nur an einen Host, dessen Name genau diesem Wert entspricht. Die Proxy-Einstellungen über -Dhttps.proxyHost in CLI_JAVA_OPTS zu setzen reicht also nicht.
  • PROXYHOST enthält nur den Hostnamen, ohne http:// und ohne Port.
  • Das Proxy-Passwort wird nicht verschlüsselt. Es steht im Klartext in set_cli_vars.sh und ist während des Laufs in der Prozessliste sichtbar. Deshalb das chmod 600 von oben, und für den Proxy nimmt man am besten einen eigenen technischen Benutzer.
  • cli.sh fügt CLI_JAVA_OPTS ohne Anführungszeichen in den java-Aufruf ein. Die Shell zerlegt den Inhalt an Leerzeichen und wertet * oder ? als Dateimuster aus. Solche Zeichen im Proxy-Passwort machen deshalb Ärger, daran ändern auch Anführungszeichen in set_cli_vars.sh nichts.

Ob der Proxy greift, seht ihr mit -d. Im Log steht dann eine Zeile Proxy settings: <host>, <port>. Fragt Java die Anmeldung für einen anderen Host an als erwartet, erscheint Skipping proxy auth. mit beiden Hostnamen.

Weitere Stolpersteine

Zum Schluss noch drei Beobachtungen aus der Code-Analyse, die im Betrieb auffallen:

  • Das CLI schreibt jede aufgerufene URL auf die Standardausgabe, unabhängig vom Log-Level. Die Ausgabe im Scheduler ist entsprechend ausführlich.
  • Auf dem Log-Level TRACE landet das entschlüsselte IDMC-Passwort in logs/runAJobCli.log. Den Level also nur kurzzeitig hochdrehen.
  • Laut Knowledge Base prüft das CLI vor dem Start, ob der Task bereits läuft. Im Code der Version 250902 greift diese Prüfung bei normalen Tasks wie MTT aber nicht. Das CLI startet ihn trotzdem ein zweites Mal. Nur bei File Ingestion Tasks (MI_TASK) hängt es sich an den laufenden Job. Den Schutz vor doppelten Starts muss also der Scheduler übernehmen.

Wie ihr seht, ist die Einrichtung eigentlich gar nicht so schwierig, wenn man die Wartezeit und die Java-Sperre für den Proxy kennt.

Quellen

Falls ihr Fragen dazu habt oder vor einer ähnlichen Aufgabe steht, schreibt mir gerne.