Zum Inhalt

Troubleshooting

Zugang zur FreeSwitch-Konsole

# fs_cli im Container
docker exec voicebot-fs fs_cli -H 127.0.0.1 -P 8021 -p voicebot2024

Passwort nicht aendern

Das ESL-Passwort voicebot2024 wird auch von der Platform API für die ESL-Verbindung genutzt. Eine Änderung muss an beiden Stellen gleichzeitig erfolgen.

Diagnose-Befehle

Gateway-Status pruefen

# Alle Gateways anzeigen
sofia status

# Erwartete Ausgabe:
# external-ipv4    sip:mod_sofia@46.4.96.105:5060  RUNNING (0)
# internal         sip:mod_sofia@[::]:5060          RUNNING (0)

# Gateway-Details eines Profils
sofia status profile internal

# Registrierte Extensions
sofia status profile internal reg
Status Bedeutung
REGED Gateway ist registriert (1&1)
NOREG Kein Register nötig (Plusnet) — kein Fehler!
FAIL_WAIT Registrierung fehlgeschlagen, wartet auf Retry
TRYING Registrierung läuft

SIP-Trace

# SIP-Trace einschalten (KURZZEITIG!)
sofia global siptrace on

# SIP-Trace ausschalten
sofia global siptrace off

SIP-Trace nur kurzzeitig

SIP-Trace erzeugt enorme Datenmengen im Log. Nur für gezielte Fehlersuche einschalten und sofort danach wieder deaktivieren. Bei Vergessen kann die Festplatte volllaufen.

Audio-Debug

# Audio-Debug fuer einen aktiven Call
uuid_debug_media <call-uuid> both on

# Aktive Calls anzeigen
show calls
show channels

Log-Analyse

# FreeSwitch-Logs im Container
docker logs voicebot-fs --tail 100 -f

# Platform API Logs (SIP-Modul)
docker logs xynap-platform-api --tail 100 -f | grep -i sip

# LiveKit-Logs
docker logs livekit --tail 100 -f
docker logs livekit-sip --tail 100 -f
docker logs livekit-agent --tail 100 -f

Haeufige Probleme

1&1: 503 Service Unavailable

Symptom: Gateway zeigt FAIL_WAIT, Registrierung schlägt mit 503 fehl.

Ursache: 1&1 blockiert Hetzner-IPv4-Adressen.

Lösung:

  1. Sicherstellen, dass der Trunk dem Profil internal zugeordnet ist (Dual-Stack mit IPv6)
  2. ext-sip-ip und ext-rtp-ip im internal-Profil müssen auf 2a01:4f8:140:829d::2 stehen
  3. Outbound-Proxy muss IPv6 sein: [2001:8d8:104:100:212:227:124:129]
# Pruefen, ob IPv6 korrekt konfiguriert ist
sofia status profile internal
# ext-sip-ip muss 2a01:4f8:140:829d::2 zeigen

1&1: 401 Unauthorized (trotz korrekter Credentials)

Symptom: Registrierung schlägt fehl, obwohl Benutzername und Passwort stimmen.

Ursache: Falscher Realm konfiguriert.

Lösung: Der Realm muss sip.1und1.de sein, nicht 1und1.de.

Plusnet: 408 Request Timeout

Symptom: Ausgehende Calls zu Plusnet brechen mit Timeout ab.

Ursache: DNS Round-Robin — INVITE und ACK landen bei verschiedenen Servern.

Lösung: Outbound-Proxy 92.197.176.16 muss gesetzt sein.

Eingehende Anrufe kommen nicht an (CallsIN = 0)

Symptom: Gateway zeigt REGED oder NOREG (Status OK), aber keine eingehenden Calls.

Checkliste:

  1. UFW prüfen: Sind die Provider-IPs für Port 5060/udp freigeschaltet? 

    sudo ufw status | grep 5060

  2. IPv6-Firewall prüfen (für 1&1): 

    sudo ufw status | grep 2001:8d8

  3. FreeSwitch ACL prüfen: Ist die Provider-IP in der ACL sip-gateways eingetragen?

  4. SIP-Trace aktivieren und schauen, ob INVITEs überhaupt ankommen

Kein Audio (One-Way oder beidseitig)

Symptom: Call wird aufgebaut, aber kein Audio hörbar.

Ursache: Falsche ext-rtp-ip im Sofia-Profil.

Checkliste:

  1. ext-rtp-ip prüfen: Muss zur IP-Version des Providers passen
  2. Plusnet (IPv4): ext-rtp-ip = 46.4.96.105

  3. 1&1 (IPv6): ext-rtp-ip = 2a01:4f8:140:829d::2

  4. RTP-Ports offen? 

    sudo ufw status | grep -E "10000|16384"

  5. Audio-Debug aktivieren: 

    # In fs_cli:
uuid_debug_media <uuid> both on
    Falls keine RTP-Pakete sichtbar → Firewall-Problem. Falls RTP-Pakete ankommen aber kein Audio → Codec-Mismatch.

WebRTC: Kein Verbindungsaufbau

Symptom: WebRTC-Softphone verbindet sich nicht oder REGISTER schlägt fehl.

Checkliste:

  1. WSS-Port 7443 erreichbar? 

    openssl s_client -connect sip.xynap.tech:7443

  2. TLS-Zertifikat gültig? WebRTC erfordert ein gültiges TLS-Zertifikat.

  3. JsSIP Race Condition: WebSocket muss vollständig verbunden sein, bevor REGISTER gesendet wird. Browser-Konsole auf Fehler prüfen.

  4. ICE Timeout: Falls ICE-Gathering fehlschlägt, liegt es meist an restriktiven Client-Firewalls.

Platform API: xml-curl liefert leere Antwort

Symptom: FreeSwitch kann keine Extensions/Gateways laden. Neue Trunks erscheinen nicht.

Checkliste:

  1. API erreichbar? 

    curl -s http://127.0.0.1:8001/api/v1/sip/live-status

  2. API-Logs prüfen: 

    docker logs xynap-platform-api --tail 50 | grep xml-curl

  3. ESL-Verbindung aktiv? Die Platform API zeigt im Log, ob die ESL-Verbindung steht.

  4. Manueller xml-curl Test: 

    curl -X POST http://127.0.0.1:8001/api/v1/sip/xml-curl \
  -d "section=directory&domain=sip.xynap.tech"

LiveKit Agent antwortet nicht

Symptom: Call wird an *99 / LiveKit weitergeleitet, aber kein Agent nimmt teil.

Checkliste:

  1. Agent-Container läuft? 

    docker ps | grep livekit-agent

  2. Agent-Logs: 

    docker logs livekit-agent --tail 50

  3. SIP-Bridge-Logs: 

    docker logs livekit-sip --tail 50

  4. LiveKit-Room erstellt? Prüfen, ob der SIP-Call einen Room anlegt: 

    docker logs livekit --tail 50 | grep room

Neustart-Reihenfolge

Bei einem vollständigen Neustart des Telefonie-Stacks diese Reihenfolge einhalten:

# 1. Platform API (muss zuerst laufen fuer xml-curl)
sudo docker compose -f /etc/xynap/stack/docker-compose.yml restart xynap-platform-api

# 2. Warten bis API antwortet
sleep 10
curl -s http://127.0.0.1:8001/api/v1/health

# 3. FreeSwitch
sudo docker compose -f /usr/local/xynap/voicebot/docker-compose.yml restart voicebot-fs

# 4. LiveKit Stack
sudo docker compose -f /usr/local/xynap/voicebot/docker-compose.yml restart livekit livekit-sip livekit-agent

Reihenfolge beachten

FreeSwitch benötigt die Platform API beim Start für Gateway-Discovery. Startet FreeSwitch vor der API, werden keine Gateways geladen. In diesem Fall hilft ein sofia profile internal restart und sofia profile external-ipv4 restart in der fs_cli.

Quick-Reference: fs_cli Befehle

Befehl Beschreibung
sofia status Alle Profile und Gateways anzeigen
sofia status profile internal reg Registrierte Clients
sofia profile internal restart Internal-Profil neu laden
sofia profile external-ipv4 restart External-Profil neu laden
sofia global siptrace on/off SIP-Trace ein-/ausschalten
show calls Aktive Calls
show channels Aktive Kanäle
uuid_debug_media <uuid> both on Audio-Debug für einen Call
reloadxml XML-Konfiguration neu laden
reload mod_xml_curl xml-curl Modul neu laden
originate sofia/internal/1000@sip.xynap.tech &echo Test-Call an Extension 1000