Konfiguration¶
In diesem Kapitel erfährst du, wie du den Assistant Server korrekt konfigurierst. Wie bei allen unseren Produkten basiert die Konfiguration auf unserem zentralen Konfigurationssystem. Die Grundlagen zur Struktur, zum Speicherort und zur Funktionsweise von Konfigurationsdateien findest du im Kapitel Konfigurationssystem.
Der Assistant Server benötigt neben der Hauptkonfiguration im Application Modul in der Regel auch folgende zusätzliche Konfigurationsbausteine:
ein
SSLModul für verschlüsselte Verbindungen,ein
LogModul für die Protokollierung wichtiger Ereignisse,optional ein
StatisticSystemModul, falls du unser Statistic System für die Analyse von Benutzeraktionen nutzen möchtest.
Details zur Einrichtung dieser Module findest du in den entsprechenden Kapiteln: Eigene SSL Zertifikate verwenden, Log-System und in der separaten Dokumentation zum Statistik-System.
Grundlegende Struktur¶
Das folgende Beispiel zeigt dir die typische Grundstruktur einer Serverkonfiguration für das Assistant System:
1<?xml version="1.0" encoding="UTF-8" ?>
2<Configuration
3 version="1"
4 xmlns="http://educateit.ch/software/BlueStone/Configuration/1">
5
6 <Module name="Application">
7 <!-- Hauptkonfiguration des Assistant Servers -->
8 </Module>
9
10 <Module name="SSL">
11 <!-- SSL-Profile -->
12 </Module>
13
14 <Module name="StatisticSystem">
15 <!-- Optionale Konfiguration des Statistik-Systems -->
16 </Module>
17
18 <Module name="Log">
19 <!-- Konfiguration des Log-Systems -->
20 </Module>
21
22 <!-- Einbindung zusätzlicher Konfigurationen für Erweiterungen -->
23 <SearchDirectory>conf</SearchDirectory>
24 <IncludeFile>Erweiterung1.conf_b.xml</IncludeFile>
25 <IncludeFile>Erweiterung2.conf_b.xml</IncludeFile>
26 <!-- ... -->
27
28</Configuration>
Das Modul Application bildet immer das Herzstück der Serverkonfiguration. Hier definierst du alle zentralen Einstellungen für den Betrieb des Assistant Servers.
Das optionale SSL Modul ermöglicht dir die Konfiguration von Schlüsseln und Zertifikaten für sichere Verbindungen zwischen Client und Server.
Wenn du das Statistik-System einsetzen möchtest, erfolgt dessen Konfiguration im StatisticSystem Modul. Die zu erfassenden Benutzeraktionen sind bereits im Assistenten selbst vordefiniert.
Das Log Modul dient zur Einrichtung des Log Systems. Weitere Details dazu findest du im Kapitel Log-System.
Wie im Beispiel gezeigt, kannst du die Konfiguration durch Erweiterungsmodule flexibel ergänzen. Lege dazu mit SearchDirectory ein Verzeichnis fest, in dem Erweiterungskonfigurationen gesucht werden, und füge mit IncludeFile die gewünschten Dateien ein. Ausführliche Informationen dazu findest du im Kapitel Konfigurationssystem.
Wichtig
Der Server aktiviert nur solche Erweiterungen, die über ein Konfigurationsmodul verfügen. Falls eine Erweiterung keine eigenen Konfigurationswerte benötigt oder du bewusst die Standardwerte verwenden möchtest, kannst du ein leeres Konfigurationsmodul anlegen, um sie trotzdem zu aktivieren.
Das Konfigurationsschema¶
Module
Application
Must be a valid host address.
Must not be empty.
List
Complex list definition
Must not be empty.
Must not be empty.
Must not be empty.
Der Wert serverInterface¶
Mit diesem optionalen Parameter kannst du den Server an eine bestimmte Netzwerkschnittstelle binden. Gib dazu die IP-Adresse der gewünschten Schnittstelle an. Lässt du diesen Parameter weg, wird der Server an alle verfügbaren Netzwerkinterfaces gebunden.
Im folgenden Beispiel wird der Assistant Server explizit an die Schnittstelle mit der IP-Adresse 10.130.47.12 gebunden. Dadurch ist er nur über diese Adresse erreichbar.
1<Module name="Application">
2 <Value name="serverInterface">10.130.47.12</Value>
3 <Value name="serverPort">9632</Value>
4 <Value name="sslProfile">assistant</Value>
5 <List name="secrets">
6 <ListEntry>
7 <Value name="label">Raptor Server</Value>
8 <Value name="key">(...)</Value>
9 <Value name="secret">(...)</Value>
10 <Value name="authorizedNetworks">10.130.47.0/24</Value>
11 </ListEntry>
12 </List>
13</Module>
Der Wert serverPort¶
Mit diesem Parameter kannst du den Port ändern, auf dem der Server eingehende Verbindungen akzeptiert. Wenn du diesen Wert nicht angibst, wird standardmäßig der Port 17644 verwendet.
Falls du den Port änderst, stelle sicher, dass alle Clients entsprechend auf den gleichen Port konfiguriert sind.
Im folgenden Beispiel ist der Assistant Server so konfiguriert, dass er Verbindungen auf Port 9632 entgegennimmt.
1<Module name="Application">
2 <Value name="serverInterface">10.130.47.12</Value>
3 <Value name="serverPort">9632</Value>
4 <Value name="sslProfile">assistant</Value>
5 <List name="secrets">
6 <ListEntry>
7 <Value name="label">Raptor Server</Value>
8 <Value name="key">(...)</Value>
9 <Value name="secret">(...)</Value>
10 <Value name="authorizedNetworks">10.130.47.0/24</Value>
11 </ListEntry>
12 </List>
13</Module>
Der Wert sslProfile¶
Mit SslProfile bestimmst du die SSL-Konfiguration für deine Verbindung. Stelle sicher, dass der Name, den du hier einfügst, in der Liste profiles im SSL Konfigurationsmodul vorhanden ist. In Kapitel Eigene SSL Zertifikate verwenden erfährst du mehr darüber, wie du das SSL-Profil richtig einrichtest.
Du hast auch die Möglichkeit, diesen Wert auf legacy zu setzen. Das ist besonders hilfreich, wenn du eine Migration durchführen oder ältere Installationen unterstützen möchtest. In diesem Fall verwendet das System die integrierten Zertifikate, die mit älteren Versionen des Raptor Systems kompatibel sind.
Warnung
Wir empfehlen allerdings ausdrücklich, immer eigene Zertifikate und Schlüssel zu verwenden. Diese sollten den korrekten Servernamen enthalten und von einer internen Zertifizierungsstelle deines Unternehmens ausgestellt werden. Mit dieser Methode stellst du sicher, dass deine Verbindung sicher und authentifiziert ist.
1<Module name="Application">
2 <Value name="sslProfile">assistant</Value>
3 <List name="secrets">
4 <ListEntry>
5 <Value name="label">Raptor Server</Value>
6 <Value name="key">(...)</Value>
7 <Value name="secret">(...)</Value>
8 <Value name="authorizedNetworks">10.130.47.0/24</Value>
9 </ListEntry>
10 </List>
11</Module>
Die Liste secrets¶
Die Liste secrets definiert, wer auf das Assistant System zugreifen kann. Dazu generierst du mit dem EducateIT Secret Generator Schlüsselpaare, die für den Zugriff auf das System erforderlich sind. Siehe dazu Das Secret System.
Der Client ist die Software, die auf die Daten zugreifen möchte – in diesem Fall der Assistant Client. Der Server ist der Assistant Server.
Für jede Anwendergruppe, die auf den Assistant Server zugreift, solltest du ein eigenes Schlüsselpaar erstellen. Zusätzlich empfiehlt es sich, das Secret auf der Client-Seite zu kodieren, da es wie ein Passwort behandelt werden sollte. Schütze es daher entsprechend. Weitere Informationen dazu findest du in Kodieren von Passwörtern.
Neben dem Schlüsselpaar kannst du den Zugriff auch über eine Netzwerkliste einschränken. Wenn du beispielsweise weißt, dass sich ein Client immer aus dem Netzwerk 10.0.0.0/24 mit dem Server verbindet, kannst du diese Einschränkung mit dem Wert authorizedNetworks konfigurieren. Wir empfehlen, solche Einschränkungen nach Möglichkeit zu definieren.
Das folgende Beispiel zeigt eine secrets-Liste. Die Platzhalter (...) bei den Werten key und secret müssen durch die tatsächlichen Schlüssel ersetzt werden.
1<Module name="Application">
2 (...)
3 <List name="secrets">
4 <ListEntry>
5 <Value name="label">Raptor Server</Value>
6 <Value name="key">(...)</Value>
7 <Value name="secret">(...)</Value>
8 <Value name="authorizedNetworks">10.0.0.0/16 127.0.0.1/24</Value>
9 </ListEntry>
10 <ListEntry>
11 <Value name="label">Client</Value>
12 <Value name="key">(...)</Value>
13 <Value name="secret">(...)</Value>
14 </ListEntry>
15 <ListEntry>
16 <Value name="label">HttpApiAccess</Value>
17 <Value name="key">(...)</Value>
18 <Value name="secret">(...)</Value>
19 </ListEntry>
20 </List>
21</Module>
Der Wert label¶
Mit dem Wert label gibst du einem Eintrag einen Namen. Dieser taucht in den Logdateien auf, so dass du Fehlermeldungen oder Zugriffe einem Eintrag zuordnen kannst. Funktional hat dieser Wert keine Bedeutung.
Siehe dazu auch Kapitel Das Secret System.
1<Module name="Application">
2 (...)
3 <List name="secrets">
4 <ListEntry>
5 <Value name="label">Raptor Server</Value>
6 <Value name="key">(...)</Value>
7 <Value name="secret">(...)</Value>
8 <Value name="authorizedNetworks">10.0.0.0/16 127.0.0.1/24</Value>
9 </ListEntry>
10 (...)
11 </List>
12</Module>
Der Wert key¶
Der Wert key ist ein Teil des Schlüsselpaars, welches du mit dem EducateIT Secret Generator erstellst. Dieser Wert bildet der Schlüssel, welcher einen Zugang eindeutig identifiziert. Der Wert ist vergleichbar mit einem Benutzernamen.
Siehe dazu auch Kapitel Das Secret System.
1<Module name="Application">
2 (...)
3 <List name="secrets">
4 <ListEntry>
5 <Value name="label">Raptor Server</Value>
6 <Value name="key">(...)</Value>
7 <Value name="secret">(...)</Value>
8 <Value name="authorizedNetworks">10.0.0.0/16 127.0.0.1/24</Value>
9 </ListEntry>
10 (...)
11 </List>
12</Module>
Der Wert secret¶
Der Wert secret ist der zweite Teil des Schlüsselpaars, welches du mit dem EducateIT Secret Generator erstellst. Dieser Wert ist eine Prüfsumme („Hash“) des eigentlichen Werts welches du im Client konfigurierst. Es ist nicht ohne weiteres möglich von dem Server Secret auf das Client Secret zu schliessen. Trotzdem solltest du den Zugriff auf die Konfiguration so gut wie möglich limitieren.
Siehe dazu auch Kapitel Das Secret System.
1<Module name="Application">
2 (...)
3 <List name="secrets">
4 <ListEntry>
5 <Value name="label">Raptor Server</Value>
6 <Value name="key">(...)</Value>
7 <Value name="secret">(...)</Value>
8 <Value name="authorizedNetworks">10.0.0.0/16 127.0.0.1/24</Value>
9 </ListEntry>
10 (...)
11 </List>
12</Module>
Der Wert numberOfThreads¶
Mit diesem optionalen Wert kannst du die Anzahl der Threads steuern, die für die Verarbeitung aller Anfragen genutzt werden. Der Wert muss zwischen 8 und 64 liegen, der Standardwert ist 64. In den meisten Fällen kannst du diese Einstellung ignorieren.
Falls das Assistenzsystem in einer stark ausgelasteten Umgebung auf einer leistungsfähigen Maschine läuft, empfiehlt es sich, vier Threads pro CPU-Kern zu nutzen. Auf einem 6-Kern-Prozessor wären das beispielsweise 24 Threads.
1<Module name="Application">
2 (...)
3 <Value name="numberOfThreads">16</Value>
4 (...)
5</Module>
Der Wert rollbackEnabled¶
Mit diesem Konfigurationswert kannst du das Rollback für einzelne Aktionen aktivieren. Dieser optionale Wert ist eine durch Leerzeichen getrennte Liste von Aktionskennungen. Für jede Aktion in dieser Liste wird das Rollback aktiviert.
Wenn du den speziellen Wert All angibst, wird das Rollback für alle unterstützten Aktionen aktiviert. Dies ist die Standardeinstellung.
Das Rollback ist nur für Aktionen verfügbar, die diese Funktion unterstützen. Falls du eine Aktionskennung für eine Aktion angibst, die kein Rollback unterstützt, wird dieser Eintrag ignoriert.
Lies die Dokumentation der einzelnen Plug-ins, um zu erfahren, welche Aktionen Rollback unterstützen.
1<Module name="Application">
2 (...)
3 <Value name="rollbackEnabled">
4 CleanUpProfile
5 </Value>
6 (...)
7</Module>
