Proxy. Dokumentation. Automic Software GmbH

Transkript

1 Proxy Dokumentation Automic Software GmbH

2 ii Copyright Copyright Die Marke Automic und das Automic-Logo sind Warenzeichen der Automic Software GmbH (Automic). Die Nutzung sämtlicher Warenzeichen bedarf der ausdrücklichen schriftlichen Genehmigung und unterliegt den Lizenzbedingungen. Die Software/das Computerprogramm sind geschütztes Eigentum der Firma Automic. Zugang und Nutzung vorbehaltlich der geprüften schriftlichen Lizenzbedingungen. Die Software/das Computerprogramm ist weiters durch internationale Verträge sowie nationale und internationale Gesetze urheberrechtlich geschützt. Unbefugter Zugang bzw. Nutzung werden zivilund strafrechtlich verfolgt. Unbefugtes Kopieren und andere Formen der auszugsweisen oder vollständigen Reproduktion, Dekompilierung, Nachbau, Änderung oder die Entwicklung von aus der Software abgeleiteten Produkten sind strengstens verboten. Die Nichtbeachtung wird strafrechtlich verfolgt. Alle Angaben ohne Gewähr. Änderungen, Irrtümer, Satz- und Druckfehler vorbehalten. Nachdruck auch in Auszügen ist untersagt. Copyright Automic Software GmbH. Alle Rechte vorbehalten.

3 Proxy Dokumentation iii Inhaltsverzeichnis 1 Proxy Allgemeines Load-Balancing Load-Balancing nicht aktiv Load-Balancing aktiv Terminologie 3 2 Installation Ausgelieferte Dateien Ablauf 5 3 Konfiguration des Client-Proxys Struktur Beispiel 13

4 1 Kapitel 1 Proxy 1 Proxy Bei Proxy handelt es sich um ein zusätzliches Dienstprogramm, welches ausschließlich in Kombination mit dem Produkt Automation Engine (AE)verwendet werden kann. Proxy wird als ein eigenes Produkt ausgeliefert. 1.1 Allgemeines Proxy kann sowohl in Zusammenhang mit aktuellen als auch älteren Versionen (6.00, 8.00,...) der Automation Engine verwendet werden. Zur Serverkomponente der Automation Engine (ab Version 9 als "AutomationEngine" bezeichnet) verbinden sich verschiedene Komponenten, wie Agenten, Dialoge (UserInterface) und APIs (CallAPI, JavAPI). Für jede Komponente wird dabei eine eigene Verbindung zu den Kommunikationsprozessen (CPs) der Serverkomponente aufgebaut. Beim Einsatz einer Firewall muss jede dieser Verbindungen explizit erlaubt werden, was einen hohen Konfigurationsaufwand bedeutet. Die Anwendung Proxy ermöglicht es, die CP-Verbindungen der AE-Komponenten (Agenten, Dialoge...) zu einer Verbindung zusammenzufassen und dabei die Richtung des Verbindungsaufbaus umzukehren. Dafür ist für sowohl auf der Komponenten- als auch der Server- Seite eine Instanz von Proxy erforderlich. Beim Client-Proxy handelt es sich um jene Instanz von Proxy, die auf Seite der CPs läuft. Als Server-Proxy wird die Instanz bezeichnet, die auf Seite der AE-Komponenten (Agenten...) betrieben wird. Für jeden Client-Proxy ist auch ein Server-Proxy erforderlich. Client- und Server-Proxy werden als Paar betrieben, das bedeutet, ein Server-Proxy erlaubt die Verbindung genau eines Client- Proxys. Somit sind nur die Verbindungen von Proxy einmalig in der Firewall zu konfigurieren. Neue Komponenten (beispielsweise Agenten), die sich zur Serverkomponente verbinden sollen, sind anschließend nur einem entsprechenden Server-Proxy zuzuordnen. Tip: Betreiben Sie zumindest 2 Proxy-Pärchen parallel für die selben AE-Komponenten und koppeln Sie diese miteinander (INI-Datei des Client-Proxys: Sektion [OTHER_SP_LIST]). So erhöhen Sie die Zuverlässigkeit, falls ein Proxy-Pärchen ausfällt. Info: Der Server-Proxy benötigt keine INI-Datei, da er die für ihn relevanten Einstellungen vom Client-Proxy über die Service-Verbindung mitgeteilt bekommt. Der Server- als auch den Client- Proxy wird durch die INI-Datei auf Client-Proxy-Seite konfiguriert.

5 Proxy Dokumentation Load-Balancing Der Client-Proxy ist in der Lage, die Auswahl eines Kommunikationsprozesses abhängig von der Last der Kommunikationsprozesse eines AE- Systems durchzuführen (= Load-Balancing). Ist Load- Balancing aktiv, so sucht der Client-Proxy nach anderen Kommunikationsprozessen des selben AE-Systems und verbindet sich automatisch zu jenem, der am wenigsten Verbindungen besitzt. Load-Balancing auf Kommunikationsprozesss-Seite kann in der INI-Datei (Parameter: cpselection=) des Client-Proxys aktiviert bzw. deaktiviert werden. Ist Load-Balancing nicht aktiv, so verbindet sich der Client-Proxy zu einem bestimmten CP Load-Balancing nicht aktiv In folgendem Beispiel-System ist Load-Balaning deaktiviert. Client-Proxy 1 und 2 sind nur mit einem CP verbunden. Diese Einstellung ist bei der Verwendung von UserInterfaces und CallAPIs erforderlich Load-Balancing aktiv In folgendem Beispiel, ist Load-Balancing aktiv. Die Client-Proxys wählen beim Verbindungsaufbau den CP abhängig von der Last unter allen verfügbaren CPs aus (ab AutomationEngine Version 9 ServicePack 3 werden nur CPs innerhalb der gleichen netarea berücksichtigt). Client-Proxy 1 leitet Verbindungen der Agenten 1 und 2 vom Server-Proxy 1 zu CP1 und CP2 weiter, Client-Proxy 2 die Verbindungen von Agent 3 und UserInterface 1 zu CP3 und CP4. Load Balancing darf nur aktiviert werden, wenn ausschließlich Agenten zu den Proxys verbunden werden.

6 3 Kapitel 1 Proxy 1.3 Terminologie Begriff Proxy Client-Proxy Server-Proxy Serverkomponente Kommunikationsprozess (CP) Arbeitsprozess (WP) Erklärung Ein Produkt der Firma Automic Software Gmbh, das der Zusammenfassung und Umleitung von CP-Verbindungen dient. Instanz von Proxy, welche auf der Seite der Kommunikationsprozesse läuft. Nimmt Verbindung zum Server-Proxy auf und leitet dessen Verbindungen zu einem CP weiter. Instanz von Proxy, die auf der Seite der AE- Komponenten läuft, die sich mit einem CP verbinden. Routet die Verbindungen von Agenten, APIs, Dialogen usw. zum Client-Proxy um. Kernkomponente der Automation Engine. Besteht aus mehreren Kommunikationsprozessen (CPs) und Arbeitsprozessen (WPs). Wird in Version 9 und 10 als Automation Engine bezeichnet. In Vorversionen war der Name "UC4 Server" in Verwendung. Teil der Serverkomponente, zu der sich AE- Komponenten (wie Agenten) verbinden. Teil der Serverkomponente, welcher die Verarbeitung übernimmt.

7 Proxy Dokumentation 4 Begriff Routing-Port Load-Balancing Erklärung Port des Server-Proxys, zu welchem sich AE- Komponenten wie Agenten und UserInterfaces verbinden. Der Client-Proxy führt eine lastabhängige Auswahl der CPs durch. Dieses Verhalten kann in der INI-Datei aktiviert bzw. deaktiviert werden.

8 5 Kapitel 2 Installation 2 Installation Die Installation von Proxy wird in folgenden Schritten durchgeführt. Die Installationsanleitung gilt für Windows und UNIX. 2.1 Ausgelieferte Dateien Datei proxy.jar proxy.ini 2.2 Ablauf 1. Java-Runtime Beschreibung Proxy Anwendung INI-Datei für die Konfiguration der Client- Instanz von Proxy Für den Einsatz von Proxy ist Oracle Java 1.7 (oder höher) erforderlich. Die Version der Java-VM kann mit folgendem Kommando überprüft werden: java -version Sind mehrere JREs oder SDKs installiert, achten Sie auf die richtige Reihenfolge der Java- Verzeichnisse in der Umgebungsvariable %PATH% (Windows) bzw. $PATH (UNIX). Es wird immer die erste Java-VM verwendet. Sie können die aktuelle Java-Version von herunterladen. 2. Proxy installieren Für den Betrieb sind 2 Instanzen von Proxy erforderlich: Der Client-Proxy und der Server-Proxy. Dieser Installationsschritt ist daher sowohl auf dem Rechner durchzuführen, auf welchem Client- Proxy laufen soll, als auch auf jenem auf dem der Server-Proxy betrieben werden soll. Legen Sie ein eigenes Verzeichnis für den Proxy an. Zum Beispiel (Windows): "C:\Automic\Proxy\bin" Kopieren Sie die ausgelieferten Dateien in dieses Verzeichnis. Die INI-Datei muss dabei nur in das Verzeichnis des Client-Proxys kopiert werden. Für den Server-Proxy ist keine INI-Datei erforderlich. 3. SSL Zertifikat erstellen Für die Verbindungen zwischen Client- und Server-Proxy ist SSL-Verschlüsselung zu verwenden, wofür ein Zertifikat zu erstellen ist. Verbindungen zwischen Client- und Server-Proxy werden nur dann akzeptiert, wenn beide dasselbe Zertifikat besitzen.

9 Proxy Dokumentation 6 Beachten Sie, dass SSL-Authentifizierung für die Verbindungen zwischen Client- und Server- Proxy zwingend erforderlich ist. Die Verschlüsselung kann nicht deaktiviert werden. Um ein selbst signiertes Zertifikat zu erstellen, verwenden Sie das Java Keytool, welches sich im bin-ordner innerhalb des Java-Programmverzeichnisses befindet. Zum Beispiel: C:\Program Files\Java\jre7\bin\keytool.exe Folgender Befehl erstellt die Datei keystore.jks, die ein Zertifikat speichert, welches 365 Tage gültig ist. Die Keystore-Datei ist durch das Passwort "passwd" geschützt. keytool -genkey -keyalg RSA -alias selfsigned -keystore keystore.jks - storepass passwd -validity 365 -keysize 2048 Anschließend sind die Rückfragen über das Unternehmen entsprechend zu beantworten und mit ENTER zu bestätigen. Beispiel: What is your first and last name? [Unknown]: What is the name of your organizational unit? [Unknown]: Development What is the name of your organization? [Unknown]: Automic What is the name of your City or Locality? [Unknown]: Wien What is the name of your State or Province? [Unknown]: Wien What is the two-letter country code for this unit? [Unknown]: AT Is CN= OU=Development, O=Automic, L=Wien, ST=Wien, C=AT correct? [no]: yes Enter key password for <selfsigned> (RETURN if same as keystore password): 4. Client-Proxy konfigurieren Passen Sie die INI-Datei des Client-Proxys entsprechend an. 5. Server-Proxy starten Starten Sie die Proxy Instanz, welche auf der Seite von Agenten, APIs, usw. läuft (= Server-Proxy), mit folgenden Kommandozeilenparametern: serviceport= Port des Server-Proxys zu dem sich der Client-Proxy verbindet. Wird der Parameter nicht angegeben, so wird automatisch der Standardport 4321 verwendet. keystore= Pfad und Name der KeyStore-Datei

10 7 Kapitel 2 Installation keystorepwd= Passwort der Keystore-Datei Beispiel: java -cp proxy.jar com.uc4.proxy.server -keystore=keystore.jks - keystorepwd=passwd -serviceport= Client-Proxy starten Die Proxy-Instanz auf der Seite der CPs (= Client-Proxy) ist ohne die Angabe von Kommandozeilenparametern zu starten. Beispiel: java -jar proxy.jar Der Client-Proxy erstellt gleich nach Start eine Log-Datei und stellt sicher, ob eine Verbindung zu einem Kommunikationsprozess hergestellt werden kann. Erst wenn die Verbindung zum CP erfolgreich war, verbindet sich der Client-Proxy zum Server-Proxy. Verwenden Sie den Automic ServiceManager, um den Client-Proxy und den Server-Proxy als Dienst zu starten.

11 Proxy Dokumentation 8 3 Konfiguration des Client-Proxys Aufbau und mögliche Einstellungen der Datei proxy.ini von Proxy. Pflicht-Parameter sind rot hervorgehoben. Die Konfigurationsdatei proxy.ini ist nur für den Client-Proxy erforderlich. Der Client-Proxy verbindet sich zum Server-Proxy (dessen Port via Kommandozeile übergeben wird), wodurch dieser die benö tigten Einstellungen erhält. Diese initiale Verbindung wird Service-Verbindung genannt, über die sich Client- und Server-Proxy signalisieren. 3.1 Struktur Sektion/Parameter [GLOBAL] cpselection= Beschreibung Load-Balancing Erlaubte Werte: "Y", "1", "y" oder "N", "0", "n" (Standardwert) Wird diese Einstellung auf den Wert "Y" (oder auch : "y", "1") gesetzt, so führt der Proxy ein Load-Balancing durch. Dies bedeutet, dass Proxy automatisch jenen Kommunikationsprozess auswählt, der am wenigsten Verbindungen besitzt. Ist Load-Balancing aktiv, so muss die Einstellung cpname= auf einen Wert gesetzt werden, der pro Proxy-Instanz eindeutig ist. Die Sektion [CP_LIST] wird automatisch durch die Proxy- Anwendung erweitert, wenn zusätzliche Kommunikationsprozesse gefunden werden. Wird die Einstellung auf "N" (oder auch "n", "0") gesetzt, so wird Load-Balancing deaktiviert. Somit wird keine lastabhängige CP- Auswahl durchgeführt und der Client-Proxy verbindet sich zu jenem Kommunikationsprozess, der in der Sektion [CP_LIST] definiert wurde. Bei cpselection=n muss in der Sektion [CP_LIST] genau ein CP-Eintrag definiert sein, zu welchem sich der Client-Proxy verbindet. cpselection=y darf nur verwendet werden, wenn sich ausschließlich Agenten zum Proxy verbinden sollen! UserInterfaces, CallAPIs und Java-APIs erfordern die Einstellung "N" (oder "n", "0").

12 9 Kapitel 3 Konfiguration des Client-Proxys Sektion/Parameter cpname= Beschreibung Name eines Proxy-Paars, der innerhalb einer netarea (ab AE- Version 9 Service-Pack 3) bzw. im gesamten AE-System (Version 6, 8 oder Version 9 Service-Pack 1 bis 2) eindeutig ist. Diese Einstellung muss und darf nur gesetzt werden, wenn der Parameter cpselection auf "Y" (oder "y", "1") gesetzt wurde. Der Name darf maximal 32 Zeichen umfassen. serverproxy= routingport= Adresse des Server-Proxys, zu dem sich der Client-Proxy verbinden soll. Zulässiges Format: <IP-Adresse bzw Hostname>:<Port> Nummer des Routing-Ports des Server-Proxys Standardwert: 2217 checkmemoryconsumption= Der Server-Proxy überwacht den Routing-Port auf eingehende Verbindungen von AE-Komponenten (Agenten, UserInterfaces...). Zeitintervall in Sekunden zwischen den Speicher-Prüfungen. Bei jeder Prüfung wird der aktuelle Java-Speicherverbrauch berechnet und in die Log-Datei geschrieben. Wenn der Speicherverbrauch 90% übersteigt, akzeptiert der Server-Proxy keine weiteren Verbindungen, bis der Verbrauch wieder unter 80% fällt. language= logging= serverlogging= logcount= Standardwert: 30 Sekunden Sprache der Log-Datei-Einträge Erlaubte Werte: "D" (Deutsch), "E" (Englisch, Standardwert) oder "F" (Französisch) Pfad und Name der Log-Datei des Client-Proxys Die Zeichen ## können dabei als Platzhalter für die aufsteigende Nummerierung der Log-Dateien verwendet werden. Die Nummer "00" repräsentiert dabei die aktuellste Log-Datei. Es werden maximal soviele Log-Dateien behalten, wie mit der Einstellung logcount= festgelegt sind. Pfad und Name der Log-Datei des Server-Proxys Erfolgt keine Angabe, so wird die Log-Datei des Client-Proxys verwendet (siehe Beschreibung von logging=). Für serverlogging= können ebenfalls die Platzhalter ## verwendet werden. Anzahl der zu speichernden Log-Dateien Standardwert: 1

13 Proxy Dokumentation 10 Sektion/Parameter LogMaxDays= LogMaxSize= [TCP/IP] cpresponsetime= connect= keepalivetime= tcp_nodelay= sokeepalive= sendbuffersize= Beschreibung Anzahl der Tage, nach welcher die Log-Datei automatisch gewechselt werden soll. Standardwert: 1 Maximale Größe der Log-Datei. Ist diese Größe erreicht, so wird eine neue Log-Datei erstellt. Standardwert: KB Maximale Zeitdauer in Sekunden,die gewartet wird, ob ein CP auf einen Verbindungsversuch reagiert. Sendet der CP innerhalb dieser Zeit kein Paket, wird angenommen, dass dieser nicht erreichbar ist. Ist kein CP erreichbar, akzeptiert der Proxy keine neuen Verbindungen mehr. Standardwert: 10 Sekunden Zeitdauer in Sekunden, die nach einem nicht erfolgreichen Verbindungsversuch zum CP oder Server-Proxy gewartet wird. Wenn die Verbindung nicht hergestellt werden kann, erfolgt der nächste Versuch nach dieser Zeitdauer. Standardwert: 60 Sekunden Zeitintervall in Sekunden, in welchem Pakete zwischen Serverund Client-Proxy zur Aufrechterhaltung der Service-Verbindung gesendet werden. Standardwert: 60 Sekunden Ist diese Option auf "N" (oder "n", "0") gesetzt, so wird der Nagle- Algorithmus für Proxy-Verbindungen verwendet, sofern dies vom Betriebssystem unterstützt wird. Erlaubte Werte: "Y", "1", "y" (Standardwert) oder "N", "0", "n" Wird diese Einstellung auf "Y" (oder "y", "1") gesetzt, so wird das Senden von KeepAlive-Paketen für die TCP/IP Sockets der Proxys aktiviert, sofern dies vom Betriebssystem unterstützt wird. Betrifft alle Verbindungen. Erlaubte Werte: "Y", "1", "y" (Standardwert) oder "N", "0", "n" Größe des TCP/IP Zwischenspeichers für zu sendende Nachrichten in Byte. Beim Wert "0" wird der Standard-Wert der Systemumgebung verwendet. Standardwert: 8192 Bytes

14 11 Kapitel 3 Konfiguration des Client-Proxys Sektion/Parameter receivebuffersize= Beschreibung Größe des TCP/IP Zwischenspeichers für zu empfangende Nachrichten in Byte. Beim Wert "0" wird der Standard-Wert der Systemumgebung verwendet. connectdelayms= maxconnectioncount= Standardwert: 8192 Bytes Zeitdauer in Millisekunden, die zwischen dem Aufbau von mehreren gleichzeitigen Verbindungen zum CP gewartet werden soll. Standardwert: 10 Millisekunden Maximale Anzahl der Verbindungen, die der Proxy akzeptiert. Bei Erreichen dieser Anzahl, werden zusätzliche Verbindungen erst akzeptiert, wenn Verbindungen wieder abgebaut werden. tracelevel= Standardwert: 1000 Aktivieren von zusätzlichen Debug-Ausgaben in die Log-Datei. Es wird keine separate Trace-Datei erstellt! Mögliche Werte: "0" (Standardwert) = Keine zusätzlichen Ausgaben "1" = Beim Senden oder Empfangen eines Pakets wird Quelle, Ziel und Größe protokolliert "2" = Beim Senden oder Empfangen wird der Hex-Dump des Paket-Inhalts protokolliert. "3" = Beim Modifizieren der Socket-Optionen wird der betreffende Socket, Option (z.b.: sokeepalive=) und Wert protokolliert. "4" = Findet eine SSL Aktion statt, so wird diese Aktion, der resultierende Status und die verbrauchten / erzeugten Bytes protokolliert. [SSL] keystore= keystorepwd= Pfad zur KeyStore-Datei, welche ein Zertifikat enthält, das vom Java-Keytool erzeugt wurde. Durch diesen Parameter werden die Verbindungen zwischen Server-Proxy und Client-Proxy SLL-verschlüsselt und authentifiziert. Client- und Server-Proxy benötigen die selbe KeyStore-Datei. Passwort der KeyStore-Datei Das Passwort wird beim Erzeugen der Keystore-Datei festgelegt.

15 Proxy Dokumentation 12 Sektion/Parameter [OTHER_SP_LIST] Beschreibung Adresse aller Server-Proxys, zwischen denen die Agenten (bzw. UserInterfaces oder CallAPIs) zwecks Load-Balancing und Failover auswählen dürfen. Gültiges Format: spx = <Server-Name bzw. IP-Adresse>:<Routing-Port> Beispiel: [CP_LIST] sp1 = HOST01:8809 sp2 = HOST02:8810 Liste der Kommunikationsprozesse (CPs) der Serverkomponente zu welchen sich der Client-Proxy verbinden soll. Gültiges Format: cpx = <Server-Name bzw. IP-Adresse>:<Port> Beispiel: c1 = HOST01:2217 Ist der Parameter cpselection= deaktiviert (Wert "N", "n" oder "0"), so darf die CP-Liste nur einen Eintrag aufweisen.

16 13 Kapitel 3 Konfiguration des Client-Proxys 3.2 Beispiel [GLOBAL] cpselection=1 cpname=proxy_01 serverproxy=hostsp01:4321 routingport=2217 checkmemoryconsumption=10 language=(d,e) logging=../temp/proxy_log_##.txt serverlogging=../temp/sproxy_log_##.txt logcount=10 logmaxdays=1 logmaxsize=9000k [TCP/IP] cpresponsetime=10 connect=60 keepalivetime=60 tcp_nodelay=1 sokeepalive=1 sendbuffersize=8192 receivebuffersize=8192 connectdelayms=10 maxconnectioncount=10000 tracelevel=0 [SSL] keystore=keystore.jks keystorepwd=passwd [OTHER_SP_LIST] sp1=hostsp02:2217 sp2=hostsp03:2217 [CP_LIST] cp1=hostsrv01:2216 cp2= :2217 cp3= :2218