Telematikinfrastruktur (TI) für charly VM

Die Telematikinfrastruktur (TI) ist das digitale Gesundheitsnetzwerk für Deutschland. Die charly VM ermöglicht die Anbindung an die TI über verschiedene Verbindungsmethoden.

Entscheidungshilfe: Welche Konfiguration benötige ich?

Die 5 Konfigurationstypen im Überblick

Typ	Szenario	Erkennungsmerkmal	Details
1. Konnektor in der Praxis	KoCoBox	Konnektoren der 1. Generation	→ Details
2. Optimales Netzwerk	Transparentes Praxisnetz	Konnektor kann ohne zusätzliche Routen erreicht werden	→ Details
3. VM hat VPN Client	TI-Gateway (TI 2.0), Konnektor Anbieter stellt Zugangsdaten für separaten VPN Client zur Verfügung	Visionmaxx, Teleconnect, Aquinet/Secunet HSK, CGM TI Gateway	→ Details
4. VPN Gateway	TI-Gateway (TI 2.0), TI Gateway mit VPN Box	eigene Hardware von CGM und Telekom	→ Details
5. Zweites Subnetz	TI as a Service (TIaaS)	TI Konnekt, Secunet Medical Connect, CGM Managed	→ Details

Schnellkonfiguration

Führen Sie in jedem Fall als Erstes und später zum Verifizieren der Konfiguration einen Netzwerk-Test in der VM aus:

charly-server vm test-network

1. Konnektor in der Praxis

Der Netzwerktest zeigt an, dass der Konnketor erreichbar ist, die TI Infrastruktur ist jedoch noch nicht erreichbar. Hier müssen dann nur die Routen zur Gematik gesetzt werden:

charly-server vm set-connector -ip <konnektor-ip>

→ Details

2. Optimales Netzwerk

Nach einer charly-VM Installation ist der Konnektor und die Gematik direkt erreichbar. Der Netzwerktest zeigt dann keine Fehler an und es muss nichts konfiguriert werden.

→ Details

3. VM hat VPN Client

Der Konnektor-Anbieter stellt Zugangsdaten für den VPN-Client, der in der VM eingerichtet wird, zur Verfügung. D.h. es ist ein anderer VPN Client als der, der mit dem Karten-Terminals und dem KIM Client Modul kommuniziert. Dies Zugangsdaten müssen typischerweise beim Konnektor-Anbieter angefragt werden.

charly-server vm wireguard configure <Pfad zur wg0.conf bzw. VPN_000001.conf>

VPN Verbindung herstellen:

charly-server vm wireguard connect

VPN Status prüfen:

charly-server vm wireguard status

→ Details

4. VPN Gateway

Der Konnektor-Hersteller hat eine TI Gateway Box (Hardware) oder auf einem Rechner seine VPN-Verbindung als Gateway konfiguriert. Dieses Gateway wird dann mit angegeben:

charly-server vm set-connector -ip <konnektor-ip> -via <gateway-ip>

→ Details

5. Zweites Subnetz

Der Konnektor-Hersteller teilt eine zusätzliche IP Adresse für die VM mit. Mit dieser IP Addresse kann die VM dann den Konnektor im Rechenzentrum erreichen. Die zusätzliche IP wird dann mist angegeben:

charly-server vm set-connector -ip <konnektor-ip> -additionalip <zusaetzliche-ip/subnet> -via <gateway-ip für 2. IP>

→ Details

Wie erkenne ich die aktive Konfiguration?

charly-server vm test-network

Die Ausgabe zeigt:

"Konnektor direkt erreichbar" → Fall 1 oder 2 (Lokaler Konnektor oder optimales Netzwerk)
"WireGuard aktiv" oder "OpenVPN aktiv" → Fall 3 (VPN Client)
"TI-Routen über Gateway: X.X.X.X" → Fall 4 (VPN Gateway)
"Zusätzliche IP konfiguriert: X.X.X.X" → Fall 5 (Zweite IP)

Detaillierte Konfigurationsanleitungen

Führen Sie in jedem Fall als Erstes und später zum Verifizieren der Konfiguration einen Netzwerk-Test in der VM aus:

charly-server vm test-network

1. Konnektor in der Praxis

Konnektor in der Praxis

Wann verwenden?

Konnektor ist direkt erreichbar (im gleichen Subnetz)
Physische Konnektoren wie Kokobox
TI-Routen werden automatisch vom Hauptgateway verwaltet
Netzwerk-Administrator hat Routen bereits korrekt konfiguriert

Voraussetzungen

Konnektor im Netzwerk erreichbar
Netzwerkrouting zum Konnektor möglich

Konfiguration

charly-server vm set-connector -ip <konnektor-ip>

Verifizierung

charly-server vm test-network

Erwartete Ausgabe:

Konnektor direkt erreichbar
TI-Routing vollstaendig funktional

Troubleshooting

Problem: "Konnektor nicht gefunden"

Bitte die IP Address des Konnektors auf dem Host prüfen:

ping <konnektor-ip>

2. Optimales Netzwerk

Optimales Netzwerk

Wann verwenden?

Der Systembetreuer hat das Netzwerk so konfiguriert, das der Konnektor erreichbar ist und die Routen zur TI im Router konfiguriert sind.

Voraussetzungen

Die Netzwerk-Überprüfung zeigt keine Fehler für den Konnektor und die TI an:

charly-server vm test-network

Konfiguration

Es muss nichts konfiguriert werden

3. VM hat VPN Client

VM hat VPN Client

Wann verwenden?

für ein TI-Gateway (TI 2.0)
der Konnektor Anbieter stellt Zugangsdaten für separaten VPN Client zur Verfügung
Anbieter: Visionmaxx, Teleconnect, Aquinet/Secunet HSK, CGM TI Gateway

Voraussetzungen

Es existieren Zugangsdaten für einen VPN Client, die noch nicht verwendet werden, um z.B. mit den Karten-Terminals und dem KIM Client Modul zu kommunizieren. Das ist typischerweise eine Konfigurationsdatei wg0.conf oder VPN_000001.conf

Konfiguration

charly-server vm wireguard configure <Pfad zur wg0.conf bzw. VPN_000001.conf>

Verbindung herstellen:

charly-server vm wireguard connect

Verifizierung

VPN Status prüfen

charly-server vm wireguard status

Die Ausgabe zeigt den Verbindungsstatus und weitere Informationen an

Netzwerk prüfen

charly-server vm test-network

Erwartete Ausgabe:

"WireGuard aktiv"

Troubleshooting

Problem: WireGuard-Konfiguration schlägt fehl

Existierende Routen entfernen

Wenn die WireGuard-Konfiguration fehlschlägt, liegt das oft an bereits konfigurierten TI-Routen (z.B. von einer vorherigen Fall 4 oder Fall 5 Konfiguration). Diese müssen vor der WireGuard-Einrichtung entfernt werden: → Routing-Konfiguration zurücksetzen

Problem: Verbindungsprobleme

Bei Verbindungsproblemen können die Wireguard Logs geprüft werden.

Per ssh Befehl in die VM gehen
```
charly-server vm ssh
```

Logs prüfen

# WireGuard Service Logs (systemd journal)
sudo journalctl -u charly-wireguard -f

# WireGuard Health Check Log
sudo tail -f /var/log/wireguard/health.log

4. VPN Gateway

VPN Gateway

Wann verwenden?

TI-Gateway (TI 2.0)
TI Gateway mit VPN Box
typischerweise eigene Hardware von CGM und Telekom

Voraussetzungen

Der Konnektor-Hersteller hat eine TI Gateway Box (Hardware) oder auf einem Rechner seine VPN-Verbindung als Gateway konfiguriert.

Konfiguration

Zusätzlich zur Konnektor-IP wird das VPN Gateway angegeben:

charly-server vm set-connector -ip <konnektor-ip> -via <gateway-ip>

Verifizierung

charly-server vm test-network

Erwartete Ausgabe:

TI-Routen über Gateway: X.X.X.X

Troubleshooting

Problem: "VIA Gateway nicht erreichbar"

Prüfem Sie, ob es sich tatsächlich um ein VPN Gateway handelt. Der VPN Client auf einem Rechner der Praxis ist typischerweise kein VPN Gateway. Das Windows, auf dem der VPN CLient installiert ist kann als VPN Gateway konfiguriert werden. Unter macOS ist dies nicht möglich.

Prüfen Sie ob eine Konfiguration nach Fall 3: VPN Client möglich ist. Dann sollte die bisherige Konfiguration entfernt werden: → Routing-Konfiguration zurücksetzen

5. Zweites Subnetz

Zweites Subnetz

Wann verwenden?

TI as a Service (TIaaS)
Typische Anbieter: TI Konnekt, Secunet Medical Connect, CGM Managed

Voraussetzungen

Der Konnektor-Hersteller teilt eine zusätzliche IP Adresse für die VM mit. Mit dieser IP Addresse kann die VM dann den Konnektor im Rechenzentrum erreichen.

Konfiguration

Zusätzlich zur Konnektor-IP wird die 2. IP Address und das VPN Gateway für die 2. Addresse angegeben:

charly-server vm set-connector -ip <konnektor-ip> -additionalip <zusaetzliche-ip/subnet> -via <gateway-ip für 2. IP>

Verifizierung

charly-server vm test-network

Erwartete Ausgabe:

Zusätzliche IP konfiguriert: X.X.X.X

Troubleshooting

Problem: "via parameter is mandatory when using additional-ip"

Lösung: Immer Gateway mit -Via (Windows) oder via= (Linux) angeben

Problem: "When additional_ip is configured, all routes must use the same gateway"

Lösung: Alle Routen in ti-routes.json müssen dasselbe Gateway verwenden

Problem: Gateway nicht erreichbar

Konfiguration wird trotzdem angewendet
Routen werden aktiv, sobald Gateway erreichbar ist
Mit test-network Verbindung nach Netzwerk-Etablierung prüfen

Problem: Netzwerkverbindung nach Konfiguration verloren

System hat automatisches Rollback bei Verbindungsverlust
Prüfen, dass zusätzliche IP nicht mit bestehender Konfiguration kollidiert

Konfiguration vollständig entfernen: → Routing-Konfiguration zurücksetzen

Konfiguration von komplexen TI-Routing

Wann verwenden?

Sie haben ein Skript mit mehreren "route add" Befehlen erhalten
Spezielle Netzwerk-Anforderungen mit mehreren Routen
Abweichende TI-Netzwerkbereiche vom Standard
Standard-Routing funktioniert nicht
Spezielle Routing-Tabellen vom IT-Dienstleister erhalten

Voraussetzungen

Liste der erforderlichen Routen vom IT-Dienstleister
Verständnis der Netzwerk-Topologie
Gateway-IPs für verschiedene Netzwerksegmente

Schritt-für-Schritt Einrichtung

1. Aktuelle Konfiguration herunterladen

charly-server vm get-ti-routes

Dies öffnet automatisch einen Editor mit der aktuellen Konfiguration.

2. JSON-Datei anpassen

Bearbeiten Sie die Datei basierend auf Ihren Anforderungen.

3. Konfiguration anwenden

charly-server vm set-ti-routes <pfad-zur-json-datei>

Beispiel-JSON-Konfiguration

ti-routes.json für komplexe Netzwerke:

[
  {
    "to": "10.30.0.0/15",
    "via": "192.168.1.254",
    "comment": "TI RU Network via Router"
  },
  {
    "to": "100.102.0.0/15",
    "via": "192.168.1.254",
    "comment": "TI PU Network via Router"
  },
  {
    "to": "172.16.0.0/24",
    "via": "192.168.1.254",
    "comment": "Spezielles Konnektor-Subnetz"
  },
  {
    "to": "10.200.0.0/24",
    "via": "192.168.1.254",
    "comment": "KIM-Server Netzwerk"
  },
  {
    "to": "192.168.200.0/24",
    "via": "192.168.1.254",
    "comment": "Zusaetzliche TI-Dienste"
  }
]

Verifizierung

charly-server vm test-network

Prüfen Sie speziell:

Alle konfigurierten Routen sind aktiv
Spezielle Netzwerke erreichbar

Troubleshooting

Problem: Routen werden nicht angewendet

# Von der VM aus prüfen:
charly-server vm ssh
ip route | grep -E "(10.30|100.102)"

# Netplan manuell anwenden:
sudo netplan apply

Gemeinsame Funktionen und Referenz

Routing-Konfiguration zurücksetzen

Wenn Sie eine TI-Routing-Konfiguration vollständig entfernen möchten (z.B. um zu einem anderen Fall zu wechseln):

Per ssh Befehl in die VM gehen
```
charly-server vm ssh
```

Alle TI-Routen und zusätzliche IPs löschen

sudo rm /srv/charly/config/ti-routes.json
sudo rm /etc/netplan/60-ti-routes.yaml
sudo netplan apply

Optional: Neue Konfiguration anwenden (z.B. für einen anderen Fall)

TI-Routing Grundlagen

Netzwerkbereiche

Die TI verwendet spezielle IP-Bereiche gemäß gematik-Spezifikation:

Bereich	CIDR	IP-Range	Beschreibung
RU (Referenzumgebung)	10.30.0.0/15	10.30.0.0 - 10.31.255.255	Test- und Referenzumgebung
PU (Produktionsumgebung)	100.102.0.0/15	100.102.0.0 - 100.103.255.255	Produktive TI-Dienste und offene Fachdienste

Routing-Konfiguration

Das System richtet automatisch die erforderlichen Routen ein:

Bei Konnektor-Konfiguration: Routen via Konnektor-IP
Bei OpenVPN: Routen werden vom VPN-Gateway gepusht
Bei WireGuard: Routen über AllowedIPs konfiguriert

Vereinfachte TI-Prüfung

Die VM prüft die TI-Erreichbarkeit mit einem zweistufigen Ansatz:

Primärtest: Direkter Test des TI-IDP Endpoints

https://idp.zentral.idp.splitdns.ti-dienste.de/.well-known/openid-configuration

Fallback: Nur wenn der IDP-Endpoint nicht erreichbar ist:
Suche nach PU-Routen (100.102.0.0/15)
Warnung bei Abweichung von der gematik-Spezifikation
Hinweis zur Klärung mit TI-Provider

JSON-Schema für ti-routes.json

Wichtige Felder:

to: Zielnetzwerk in CIDR-Notation (z.B. "10.30.0.0/15")
via: Gateway-IP für die Route
comment: Beschreibung der Route (optional aber empfohlen)
additional_ip: Zusätzliche IP für die VM (nur bei CGM-Szenarien)

Allgemeines Format:

[
  {
    "to": "NETZWERK/CIDR",
    "via": "GATEWAY-IP",
    "comment": "Beschreibung",
    "additional_ip": "IP/CIDR"  // Optional, nur bei CGM
  }
]

Netzwerk-Diagnose

Umfassender Netzwerktest

charly-server vm test-network

Testet automatisch:

Netzwerk-Konfiguration: IP-Adresse, Gateway, DNS
Grundlegende Konnektivität: Gateway, DNS, Internet
TI-Routing: RU/PU-Routen und TI-Endpunkte
Konnektor-Verbindungen: Erreichbarkeit konfigurierter Konnektoren
KIM-Verbindungen: POP3/SMTP-Endpoints

Anwendungsfälle

Nach Netzwerk-Änderungen: Validierung neuer Konfigurationen
Bei Verbindungsproblemen: Schnelle Fehlerdiagnose
Nach Konnektor-Konfiguration: Überprüfung der Einrichtung
Regelmäßige Überprüfung: Proaktive Wartung

Konnektortausch

Bei einem Konnektorwechsel in der Praxis:

1. Neuen Konnektor in charly einrichten

Detaillierte Anleitung in der charly-Hilfe

2. Konnektor-Konfiguration aktualisieren

charly-server vm set-connector

Oder bei speziellen Routing-Anforderungen:

charly-server vm set-connector -ip <neue_ip> -via <router_ip>

3. KIM Client Modul anpassen

Wichtig

Das KIM Client Modul muss separat auf den neuen Konnektor umgestellt werden. Dies liegt außerhalb der Verantwortung von charly-server.

4. Funktionsprüfung durchführen

Netzwerk-Test:
```
charly-server vm test-network
```
TI-Monitor prüfen: Überprüfen Sie im TI-Monitor, ob der neue Konnektor erkannt wird.
eRezept-Test: Erstellen Sie ein Test-eRezept zur Validierung.
KIM-Test: Senden Sie eine KIM-Testmail.

Verifizierung: Läuft mein System korrekt?

Schnell-Check nach der Konfiguration

# 1. Netzwerk-Test
charly-server vm test-network

# 2. TI-Monitor in charly prüfen
# Öffnen Sie charly und navigieren Sie zum TI-Monitor

# 3. Test-eRezept erstellen (optional)
# In charly ein Test-Rezept erstellen

# 4. KIM-Testmail senden (optional)
# Eine Test-KIM-Nachricht versenden

Erfolgs-Indikatoren

✅ System läuft korrekt wenn:

test-network zeigt "TI connectivity confirmed"
Konnektor wird im TI-Monitor als "erreichbar" angezeigt
eRezepte können signiert werden
KIM-Nachrichten können gesendet/empfangen werden

⚠️ Konfiguration prüfen wenn:

test-network zeigt Fehler bei TI-Routen
Konnektor im TI-Monitor als "nicht erreichbar" erscheint
Timeout-Fehler beim Signieren auftreten

Allgemeines Troubleshooting

TI-Dienste nicht erreichbar

Netzwerktest durchführen:
```
charly-server vm test-network
```
Bei fehlenden Routen:
Konnektor-Konfiguration prüfen
Bei VPN: Verbindungsstatus prüfen mit wireguard status oder openvpn status
Bei abweichenden Routen:
Prüfen ob PU-Route vom Standard (100.102.0.0/15) abweicht
Mit TI-Provider klären

Konnektor nicht erreichbar

Ping-Test:
```
ping <konnektor-ip>
```
Port-Test (LDAP):
```
telnet <konnektor-ip> 389
```
Alternative Konnektoren: Falls mehrere Konnektoren konfiguriert sind, testet die automatische Erkennung alle.

Best Practices

Sicherheit

Zugangsdaten: VPN-Passwörter sicher verwahren
Konfigurationsdateien: .ovpn und .conf Dateien vertraulich behandeln
Netzwerktrennung: TI-Traffic vom regulären Netzwerk trennen

Wartung

Regelmäßige Tests: Wöchentlicher test-network empfohlen
Backup vor Änderungen: Vor Konnektor-Wechsel Backup erstellen
Dokumentation: Netzwerk-Topologie und Routing dokumentieren

Performance

Route-Optimierung: Direkte Routen bevorzugen
VPN nur bei Bedarf: VPN nur wenn kein Konnektor direkt verfügbar
Monitoring: Verbindungslogs regelmäßig prüfen

Weiterführende Informationen

Version: 2.8.7

Datum der letzten Aktualisierung: 20.11.2025

Version: 2.8.7