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 4 Konfigurationstypen im Überblick

Typ	Szenario	Erkennungsmerkmal	Details
1. Konnektor über Default Gateway	Konnektor im Praxisnetz erreichbar	Konnektor kann von beliebigen Rechnern im Praxisnetz erreicht werden	→ Details
2. VM hat VPN Client	TI-Gateway mit separatem VPN-Zugang	Eigene VPN-Zugangsdaten für die VM	→ Details
3. VPN Gateway	TI-Gateway mit Hardware-Box	Separates Gateway-Gerät im Netzwerk	→ Details
4. Zweites Subnetz	TI as a Service (TIaaS)	Zusätzliche IP-Adresse für die VM	→ Details

Fall 1 ist die Standard-Konfiguration

Als Software-Anbieter setzen wir voraus, dass das Netzwerk korrekt konfiguriert ist und der Konnektor über das Default Gateway erreichbar ist. Die Fälle 2-4 sind Workarounds für Situationen, in denen diese Voraussetzung nicht erfüllt ist. Wenn Sie sich unsicher sind, prüfen Sie zuerst, ob Ihr Systemadministrator oder TI-Anbieter das Netzwerk so konfigurieren kann, dass Fall 1 möglich wird.

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 über Default Gateway

Netzwerktest in der VM ausführen: Führen Sie charly-server vm test-network aus, um zu prüfen, ob die TI bereits erreichbar ist:

TI bereits erreichbar: Keine Konfiguration nötig. Dies ist der Idealfall - Ihr Netzwerkadministrator hat die Routen bereits korrekt eingerichtet.
Nur Konnektor erreichbar, TI nicht: Routen müssen gesetzt werden:

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

Optionale Vorprüfung (vor VM-Installation): Falls Sie noch keine VM installiert haben, können Sie vom Arbeitsplatz aus prüfen, ob der Konnektor erreichbar ist. Da ICMP (Ping) oft deaktiviert ist, testen Sie stattdessen den LDAP-Port:

Windows (PowerShell)

Test-NetConnection -ComputerName <konnektor-ip> -Port 636

macOS (Terminal)

nc -zv <konnektor-ip> 636

→ Details

2. 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. Diese 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

3. 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

4. Zweites Subnetz

Der Konnektor-Hersteller teilt eine zusätzliche IP Adresse für die VM mit. Mit dieser IP Adresse kann die VM dann den Konnektor im Rechenzentrum erreichen. Die zusätzliche IP wird dann mit 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 (Konnektor über Default Gateway)
"WireGuard aktiv" oder "OpenVPN aktiv" → Fall 2 (VPN Client)
"TI-Routen über Gateway: X.X.X.X" → Fall 3 (VPN Gateway)
"Zusätzliche IP konfiguriert: X.X.X.X" → Fall 4 (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 über Default Gateway

Konnektor über Default Gateway

Wann verwenden?

Konnektor ist im Praxisnetz erreichbar
Konnektor kann von beliebigen Rechnern im Praxisnetz erreicht werden
Physische Konnektoren (z.B. KoCoBox) oder TI-Gateways mit korrektem Netzwerk-Routing
TI-Routen werden vom Hauptgateway (Router) verwaltet

Empfohlen: Netzwerk korrekt konfigurieren lassen

Dies ist die Standard-Konfiguration. Wenn Ihr Netzwerk korrekt eingerichtet ist, sollte der Konnektor automatisch über das Default Gateway erreichbar sein. Falls das nicht der Fall ist, fragen Sie Ihren Systemadministrator oder TI-Anbieter, ob das Netzwerk entsprechend konfiguriert werden kann. Siehe auch: FAQ: Netzwerk für TI konfigurieren

Voraussetzungen

VM-Netzwerktest: Führen Sie charly-server vm test-network aus - dies ist die schnellste und zuverlässigste Methode.
Optionale Vorprüfung (vor VM-Installation): Falls Sie noch keine VM installiert haben, können Sie vom Arbeitsplatz aus prüfen, ob der Konnektor erreichbar ist. Da ICMP (Ping) oft deaktiviert ist, testen Sie stattdessen den LDAP-Port (636):

Windows (PowerShell)

Test-NetConnection -ComputerName <konnektor-ip> -Port 636

macOS (Terminal)

nc -zv <konnektor-ip> 636

Konfiguration

Wenn TI bereits erreichbar: Keine Konfiguration erforderlich. Der Netzwerktest zeigt "TI connectivity confirmed".

Wenn nur Konnektor erreichbar, TI nicht: Routen müssen gesetzt werden:

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

Verifizierung

charly-server vm test-network

Erwartete Ausgabe:

Konnektor direkt erreichbar
TI-Routing vollständig funktional

Troubleshooting

Problem: "Konnektor nicht gefunden"

Prüfen Sie die Konnektor-Erreichbarkeit vom Arbeitsplatz aus:

Windows (PowerShell)

Test-NetConnection -ComputerName <konnektor-ip> -Port 636

macOS (Terminal)

nc -zv <konnektor-ip> 636

Problem: Konnektor vom Arbeitsplatz nicht erreichbar

Prüfen Sie die IP-Adresse des Konnektors
Stellen Sie sicher, dass der Konnektor eingeschaltet ist
Kontaktieren Sie Ihren Systemadministrator oder TI-Anbieter

Problem: TI nicht erreichbar trotz Konnektor-Verbindung

Mögliche Ursachen:

Routen im Router nicht konfiguriert → Fragen Sie Ihren Systemadministrator
Konnektor hat keine TI-Verbindung → Prüfen Sie die Konnektor-Status-Anzeige
Falls das Netzwerk nicht angepasst werden kann, prüfen Sie Fall 2 (VPN Client) oder Fall 3 (VPN Gateway)

2. VM hat VPN Client

VM hat VPN Client

Wann verwenden?

TI-Gateway (TI 2.0)
Der Konnektor-Anbieter stellt Zugangsdaten für separaten VPN Client zur Verfügung
Sie haben eine VPN-Konfigurationsdatei erhalten (z.B. wg0.conf oder VPN_000001.conf)

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 3 oder Fall 4 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

3. VPN Gateway

VPN Gateway

Wann verwenden?

TI-Gateway (TI 2.0)
TI Gateway mit VPN Box (Hardware)
Separates Gateway-Gerät im Netzwerk, das die TI-Verbindung bereitstellt

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üfen 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 2: VPN Client möglich ist. Dann sollte die bisherige Konfiguration entfernt werden: → Routing-Konfiguration zurücksetzen

4. Zweites Subnetz

Zweites Subnetz

Wann verwenden?

TI as a Service (TIaaS)
Zusätzliche IP-Adresse für die VM erforderlich

Voraussetzungen

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

Konfiguration

Zusätzlich zur Konnektor-IP wird die 2. IP Adresse und das VPN Gateway für die 2. Adresse 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

FAQ: Netzwerk für TI konfigurieren

Dieser Abschnitt richtet sich an Systemadministratoren und TI-Anbieter, die das Praxisnetzwerk so konfigurieren möchten, dass der Konnektor über das Default Gateway erreichbar ist (Fall 1).

Warum ist Fall 1 die beste Lösung?

Wenn der Konnektor über das Default Gateway erreichbar ist:

Keine zusätzliche Software-Konfiguration in der VM erforderlich
Einfachste und zuverlässigste Lösung
Keine separaten VPN-Zugangsdaten nötig
Alle Geräte im Netzwerk können die TI-Dienste nutzen

Was muss konfiguriert werden?

Statische Routen im Router, die TI-Traffic an das VPN-Gateway (den Rechner oder die Hardware-Box mit der TI-Verbindung) weiterleiten.

Benötigte Informationen:

IP-Adresse des VPN-Gateways (der Rechner oder die Box mit der TI-VPN-Verbindung)
TI-Netzwerkbereich für die Produktionsumgebung: 100.102.0.0/15
IP-Adresse des Konnektors (falls dieser in einem separaten Subnetz liegt)

Router-spezifische Anleitungen

Hinweis

Diese Beispiele dienen nur zur Orientierung. Die genaue Konfiguration hängt von Ihrer Netzwerkumgebung ab. Wenden Sie sich bei Fragen an Ihren TI-Anbieter oder Netzwerkadministrator.

FritzBox

Dokumentation: AVM: Statische Routen einrichten

Navigieren Sie zu: Heimnetz → Netzwerk → Netzwerkeinstellungen → Statische Routentabelle

Für die TI-Produktionsumgebung:

Netzwerk: 100.102.0.0
Subnetzmaske: 255.254.0.0
Gateway: IP-Adresse Ihres VPN-Gateways

Falls der Konnektor in einem separaten Subnetz liegt, fügen Sie eine weitere Route hinzu.

Lancom

Dokumentation: Lancom: Statische Routen

Navigieren Sie zu: Setup → IP-Router → Routing-Tabelle

Für die TI-Produktionsumgebung:

Routentyp: Netzwerkroute
IP-Adresse: 100.102.0.0
IP-Netzmaske: 255.254.0.0
Router: IP-Adresse Ihres VPN-Gateways

Falls der Konnektor in einem separaten Subnetz liegt, fügen Sie eine weitere Route hinzu.

Ubiquiti / UniFi

Dokumentation: Ubiquiti: Static Routes

Navigieren Sie zu: Settings → Routing → Static Routes → Create New Route

Für die TI-Produktionsumgebung:

Name: z.B. "TI-PU"
Destination Network: 100.102.0.0/15
Next Hop: IP-Adresse Ihres VPN-Gateways

Falls der Konnektor in einem separaten Subnetz liegt, fügen Sie eine weitere Route hinzu.

Konfiguration von komplexen TI-Routing

Achtung: Gefahr des Verbindungsverlusts

Mit falschen Routing-Einstellungen können Sie die VM vollständig unerreichbar machen. Stellen Sie sicher, dass Sie ein Backup haben und die Netzwerk-Topologie verstehen, bevor Sie manuelle Routing-Änderungen vornehmen. Im Zweifelsfall wenden Sie sich an Ihren Systemadministrator.

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": "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"
  }
]

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 "(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
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. "100.102.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 TIaaS-Szenarien)

Allgemeines Format:

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

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: 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

Port-Test (LDAP):

Windows (PowerShell)

Test-NetConnection -ComputerName <konnektor-ip> -Port 636

macOS (Terminal)

nc -zv <konnektor-ip> 636

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.9.2

Datum der letzten Aktualisierung: 13.01.2026

Version: 2.9.2