Konfigurierbare TURN-Server

Sie können die von einem OpenTok-Client verwendeten TURN-Server konfigurieren.

Diese Funktion ist verfügbar als Add-on-Feature.

Dieses Thema umfasst die folgenden Abschnitte:

Übersicht

Sie können die TURN-Server-Nutzung für jeden Client in der Sitzung auf folgende Weise anpassen:

  • Sie können eine Liste mit Ihren eigenen TURN-Servern hinzufügen, die der Client verwenden soll.

  • Sie können festlegen, ob der Client ausschließlich Ihre TURN-Server nutzen soll oder ob er diese zusätzlich zu den OpenTok-TURN-Servern nutzen soll

Das Hinzufügen eigener TURN-Server kann Nutzern helfen, in restriktiven Netzwerkumgebungen eine Verbindung herzustellen, in denen OpenTok-TURN-Server möglicherweise blockiert sind.

Wenn Sie sich dafür entscheiden, die OpenTok-TURN-Server zu überschreiben und ausschließlich Ihre eigenen TURN-Server zu verwenden, können Sie sicherstellen, dass die Medienströme Ihr Netzwerk zu keinem Zeitpunkt verlassen.

Sie können für jeden Client, der eine Verbindung zur Sitzung herstellt, eigene TURN-Server hinzufügen – entweder mithilfe von OpenTok.js (für Web-Clients), dem OpenTok-iOS-SDK oder dem OpenTok-Android-SDK. Die API für benutzerdefinierte TURN-Server wurde in Version 2.13.0 dieser Client SDKs hinzugefügt.

Außerdem gibt es eine IP-Proxy Add-on-Funktion, mit der Sie Sie Ihren eigenen Proxyserver verwenden können, um die Nicht-Medien Datenverkehr – wie beispielsweise Video API-Aufrufe, WebSocket-Verbindungen und Protokollverkehr.

OpenTok.js

Die options Parameter des OT.initSession() Die Methode umfasst eine iceConfig Eigenschaft. Diese Eigenschaft umfasst die folgenden Eigenschaften:

  • includeServers (String) - Setzen Sie dies auf 'custom' und der Client verwendet nur die benutzerdefinierten TURN-Server, die Sie in der customServers Array. Setzen Sie dies auf 'all' (der Standard) und der Client verwendet sowohl die von Ihnen bereitgestellten benutzerdefinierten TURN-Server als auch die OpenTok-TURN-Server.

  • transportPolicy (String) - Setzen Sie dies auf 'all' (die Standardeinstellung) und der Client verwendet alle ICE-Transporttypen (z. B. Host, srflx und TURN), um die Medienkonnektivität herzustellen. Setzen Sie dies auf 'relay' die Konnektivität immer über TURN zu erzwingen und alle anderen ICE-Kandidaten zu ignorieren Kandidaten.

  • customServers (Array) - Setzen Sie dies auf ein Array von Objekten, die Ihre benutzerdefinierten TURN-Server definieren. Jedes Objekt entspricht einem benutzerdefinierten TURN-Server, und es enthält die folgenden Eigenschaften:

    • urls (String oder Array von Strings) - Ein String oder ein Array von Strings, wobei jeder String eine vom TURN-Server unterstützte URL ist (und dies darf nur eine URL sein).

    • username (String) - Der Benutzername für den in diesem Objekt definierten TURN-Server.

    • credential (String) - Der Credential-String für den in diesem Objekt definierten TURN-Server Objekt definiert ist.

Anmerkung: Damit der Client nur die von Ihnen angegebenen TURN-Server verwendet (und nicht die die OpenTok-TURN-Server): Setzen Sie die includeServers Eigenschaft zu 'custom'setzen Sie die transportPolicy Eigenschaft zu 'relay'und setzen die customServers Eigenschaft, um Ihre TURN-Server.

Um benutzerdefinierte TURN-Anmeldedaten dynamisch zu aktualisieren, verwenden Sie die Session.setIceConfig() Methode.

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

const session = OT.initSession(projectId, sessionId, {
  iceConfig: {
    includeServers: 'custom',
    transportPolicy: 'relay',
    customServers: [
      {
        urls: [
          'turn:123.124.125.126:3478?transport=udp',
          'turn:123.124.125.126:3478?transport=tcp'
        ],
        username: 'webrtc',
        credential: 'foO0Bar1'
      },
      {
          urls: [
            'turns:turntls.example.com:3478?transport=tcp'
          ],
          username: 'webrtc',
          credential: 'foO0Bar2',
      },
    ],
  },
});

OpenTok Android SDK

Die Session.Builder Klasse enthält zwei Methoden zur Konfiguration der TURN-Server-Nutzung für den Client:

  • Session.Builder.setCustomIceServers() — Rufen Sie diese Methode auf, um eine Liste benutzerdefinierter TURN- Server für den Client hinzuzufügen.

  • Session.Builder.setIceRouting() — Rufen Sie diese Methode auf, um die ICE-Einschränkungsoptionen für den Client hinzuzufügen.

Zusätzlich zu den beiden neuen Methoden definieren zwei neue Enums die Optionen des TURN-Servers:

  • IncludeServers — Bietet Optionen für die ausschließliche Nutzung der benutzerdefinierten Server oder für die Nutzung sowohl der OpenTok-Server als auch der benutzerdefinierten Server.

  • TransportPolicy — Beschreibt die zu verwendende Routing-Methode.

Anmerkung: Damit der Client ausschließlich die von Ihnen angegebenen TURN-Server verwendet (und nicht die OpenTok-TURN-Server), rufen Sie die folgenden Methoden des `Session.Builder`-Objekts auf, mit dem Sie das `Session`-Objekt erstellen:

  • setCustomIceServers() — Übergeben Sie eine Liste von IceServer-Objekten (die Ihren benutzerdefinierten TURN-Servern entsprechen) als serverList Parameter, und einreichen IncludeServers.TURN als die config Parameter.

  • setIceRouting() — Weitergeben TransportPolicy.Relay.

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

List<IceServer> serverList = new IceServer(
  'turn:123.124.125.126:3478?transport=udp', // TURN server URL
  'webrtc', // Username
  'foO0Bar1' // Credential
);
mSession = new Session.Builder(this, apiKey, sessionId)
  .setCustomIceServers(serverList, IncludeServers.Custom)
  .setIceRouting(TransportPolicy.TURN)
  .build();
mSession.setSessionListener(this);
mSession.connect(token);

OpenTok iOS-SDK

Wenn Sie ein OTSession-Objekt initialisieren, setzen Sie die OTSessionSettings.iceConfig Eigenschaft, um eine benutzerdefinierte TURN-Server-Konfiguration für den Client zu definieren. Die Klasse OTSessionICEConfig definiert die OTSessionSettings.iceConfig Eigentum.

Anmerkung: Damit der Client ausschließlich die von Ihnen angegebenen TURN-Server verwendet (und nicht die OpenTok-TURN-Server), rufen Sie die [OTSessionSettings addICEServerWithURL:] Methode des des OTSessionSettings-Objekts, das Sie zur Erstellung des OTSession-Objekts verwenden. Setzen Sie dann die die folgenden Eigenschaften des OTSessionSettings-Objekts:

  • includeServers — Setzen Sie diesen Wert auf „OTSessionICEIncludeServersCustom“.

  • transportPolicy — Setzen Sie diesen Wert auf „OTSessionICETransportRelay“.

Sie können die OTSessionICEConfig.filterOutLanCandidates Eigenschaft, um zu verhindern, dass Clients im selben lokalen Netzwerk in weitergeleiteten Sitzungen abonniert werden, was dazu führt, dass die App den Benutzer unter iOS 14+ um Erlaubnis bittet. Beachten Sie, dass diese Funktion nicht benötigen das konfigurierbare TURN-Zusatzmodul. Für mehr Informationen, siehe dieses Thema.

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

OTSessionICEConfig *myICEServerConfiguration = [[OTSessionICEConfig alloc] init];
myICEServerConfiguration.includeServers = OTSessionICEIncludeServersCustom;
myICEServerConfiguration.transportPolicy = OTSessionICETransportRelay;

NSError *error = nil;
[myICEServerConfiguration addICEServerWithURL:@"turn:123.124.125.126:3478?transport=udp"
                                     userName:@"webrtc"
                                   credential:@"foO0Bar1"
                                        error:&error];

OTSessionSettings *settings = [[OTSessionSettings alloc] init];
settings.iceConfig = myICEServerConfiguration;

_session = [[OTSession alloc] initWithApiKey:kApiKey
                                   sessionId:kSessionId
                                    delegate:self
                                    settings:settings];

OpenTok Windows SDK

Verwenden Sie die IceConfig-Klasse, um die benutzerdefinierte ICE-Konfiguration die vom Client verwendet werden soll.

Die IceConfig() Konstruktormethode enthält die folgenden Parameter:

  • customIceServers -- Setzen Sie dies auf Eine Liste von IceServer-Objekten, die benutzerdefinierte TURN-Server, die vom Client verwendet werden sollen. Für jeden IceServer setzen Sie die URL, den Benutzernamen und den Credential-String für den benutzerdefinierten TURN-Server

  • transportPolicy -- Setzen Sie dies auf einen Wert in der ICETransport enum:

    • All -- Der Client verwendet alle ICE-Kandidatentypen (wie Host, srflx und Relay) um die Medienkonnektivität herzustellen.

    • Relayed -- Der Client erzwingt die Konnektivität immer über TURN und ignoriert alle anderen ICE-Kandidaten.

  • includeServers -- Setzen Sie dies auf einen Wert in der IncludeServers enum:

    • All -- Der Client nutzt zusätzlich zu den von Ihnen bereitgestellten benutzerdefinierten TURN-Servern auch die TURN-Server von OpenTok.

    • Custom -- Der Client wird nur die von Ihnen bereitgestellten TURN-Server verwenden.

Die Klasse Session.Builder enthält eine IceConfig Eigenschaft. Setzen Sie diese beim Erstellen des Session-Objekts auf ein IceConfig-Objekt.

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

List<IceServer> iceServers = new List<IceServer>() {
  new IceServer(
    "turn:123.124.125.126:3478?transport=udp", "webrtc", "fo0Bar1"
  )
};
IceConfig iceConfig = new IceConfig(
  iceServers,
  ICETransport.Relayed,
  ICEIncludeServers.Custom
);
session = new Session.Builder(context, apiKey, sessionId){
  IceConfig = iceConfig
}.Build();

OpenTok macOS SDK

Der Typ otc_custom_ice_config definiert eine Struktur, die die folgenden Mitglieder enthält:

  • num_ice_servers -- Die Anzahl der ICE-Server

  • ice_url -- Ein Array von Strings, die Ihre ICE-Server-URLs angeben.

  • ice_user -- Ein Array von Strings, die Benutzernamen für die TURN-Server angeben.

  • ice_credential -- Ein Array von Zeichenketten, die Anmeldeinformationen für die TURN-Server angeben.

Rufen Sie die otc_session_settings_set_custom_ice_config() Funktion und geben Sie die otc_custom_ice_config Instanz:

otc_session_settings_set_custom_ice_config(session_settings,
                                           &ice_config);

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

// Provide the ICE configuration here.
struct otc_custom_ice_config ice_config;
ice_config.num_ice_servers = 1;
ice_config.ice_url = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_url[0] = strdup("turn:123.124.125.126:3478?transport=udp");
ice_config.ice_user = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_user[0] = strdup("webrtc");
ice_config.ice_credential = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_credential[0] = strdup("foO0Bar1");
ice_config.force_turn = OTC_TRUE;
ice_config.use_custom_turn_only = OTC_FALSE;

otc_session_settings *session_settings = otc_session_settings_new();
if (session_settings != NULL) {
  otc_session_settings_set_custom_ice_config(session_settings,
                                             &ice_config);
}

otc_session *session = NULL;

session = otc_session_new_with_settings(API_KEY,
                                        SESSION_ID,
                                        &session_callbacks,
                                        session_settings);

if (session == NULL) {
  printf("Could not create OpenTok session successfully");
  return EXIT_FAILURE;
}

otc_session_connect(session, TOKEN);

OpenTok Linux-SDK

Der Typ otc_custom_ice_config definiert eine Struktur, die die folgenden Mitglieder enthält:

  • num_ice_servers -- Die Anzahl der ICE-Server

  • ice_url -- Ein Array von Strings, die Ihre ICE-Server-URLs angeben.

  • ice_user -- Ein Array von Strings, die Benutzernamen für die TURN-Server angeben.

  • ice_credential -- Ein Array von Zeichenketten, die Anmeldeinformationen für die TURN-Server angeben.

Rufen Sie die otc_session_settings_set_custom_ice_config() Funktion und geben Sie die otc_custom_ice_config Instanz:

otc_session_settings_set_custom_ice_config(session_settings,
                                           &ice_config);

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

// Provide the ICE configuration here.
struct otc_custom_ice_config ice_config;
ice_config.num_ice_servers = 1;
ice_config.ice_url = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_url[0] = strdup("turn:123.124.125.126:3478?transport=udp");
ice_config.ice_user = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_user[0] = strdup("webrtc");
ice_config.ice_credential = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_credential[0] = strdup("foO0Bar1");
ice_config.force_turn = OTC_TRUE;
ice_config.use_custom_turn_only = OTC_FALSE;

otc_session_settings *session_settings = otc_session_settings_new();
if (session_settings != NULL) {
  otc_session_settings_set_custom_ice_config(session_settings,
                                             &ice_config);
}

otc_session *session = NULL;

session = otc_session_new_with_settings(API_KEY,
                                        SESSION_ID,
                                        &session_callbacks,
                                        session_settings);

if (session == NULL) {
  printf("Could not create OpenTok session successfully");
  return EXIT_FAILURE;
}

otc_session_connect(session, TOKEN);

OpenTok React Native SDK

Die options Stütze des OTSession Komponente umfasst eine iceConfig Eigenschaft. Dieses Objekt umfasst die folgenden Eigenschaften:

  • includeServers (String) - Setzen Sie dies auf 'custom' und der Client verwendet nur die benutzerdefinierten TURN-Server, die Sie in der customServers Array. Setzen Sie dies auf 'all' (der Standard) und der Client verwendet sowohl die von Ihnen bereitgestellten benutzerdefinierten TURN-Server als auch die OpenTok-TURN-Server.

  • transportPolicy (String) - Setzen Sie dies auf 'all' (die Standardeinstellung) und der Client verwendet alle ICE-Transporttypen (z. B. Host, srflx und TURN), um die Medienkonnektivität herzustellen. Setzen Sie dies auf 'relay' die Konnektivität immer über TURN zu erzwingen und alle anderen ICE-Kandidaten zu ignorieren Kandidaten.

  • customServers (Array) - Setzen Sie dies auf ein Array von Objekten, die Ihre benutzerdefinierten TURN-Server definieren. Jedes Objekt entspricht einem benutzerdefinierten TURN-Server, und es enthält die folgenden Eigenschaften:

    • urls (String oder Array von Strings) - Ein String oder ein Array von Strings, wobei jeder String eine vom TURN-Server unterstützte URL ist (und dies darf nur eine URL sein).

    • username (String) - Der Benutzername für den in diesem Objekt definierten TURN-Server.

    • credential (String) - Der Credential-String für den in diesem Objekt definierten TURN-Server Objekt definiert ist.

Anmerkung: Damit der Client nur die von Ihnen angegebenen TURN-Server verwendet (und nicht die die OpenTok-TURN-Server): Setzen Sie die includeServers Eigenschaft zu 'custom'setzen Sie die transportPolicy Eigenschaft zu 'relay'und setzen die customServers Eigenschaft, um Ihre TURN-Server.

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

<OTSession
  apiKey="your-api-key"
  sessionId="your-session-id"
  token="your-session-token"
  options={{
    iceConfig:{
      transportPolicy: 'all',
      includeServers: 'all',
      customServers: [
        {
        urls: [
          'turn:123.124.125.126:3478?transport=udp',
          'turn:123.124.125.126:3478?transport=tcp'
        ],
        username: 'webrtc',
        credential: 'foO0Bar1'
        },
      ],
    }
  }}
>
  <OTPublisher style={{ width: 600, height: 400 }}/>
  <OTSubscriber style={{ width: 600, height: 400 }} />
</OTSession>

Bekanntes Problem

Wenn Sie einen Client so einstellen, dass er immer die TURN-Server in einer weitergeleitete Sitzungkann er nicht seine eigenen Streams zu abonnieren (Streams, die er veröffentlicht).

FAQs

Löst die konfigurierbare TURN-API das Problem des HTTP-Verkehrs?

Nein. Konfigurierbares TURN zerstreut die Bedenken der Kunden bezüglich der Verbindung zu vertrauenswürdigen Endpunkten für nur für Medienverkehr.

Für den HTTP-Verkehr müssen die Kunden eine der folgenden Möglichkeiten nutzen:

  • OpenTok-Domainnamen auf die Whitelist setzen:

    • *.opentok.com
    • *.tokbox.com

  • Whitelist IP-Adressblöcke, die für die Vonage Video API bereitgestellt werden.

  • Verwenden Sie die Web-Proxy-Einstellungen auf den Clients, um den gesamten Vonage-HTTPS-Verkehr durch Ihre eigenen Ziele zu leiten. Siehe den Abschnitt Proxy-Anforderungen hier.

Wie wird der Medienpfad zwischen den verfügbaren TURN-Zielen ausgewählt. Wird dabei die Round-Trip-Latenz berücksichtigt, oder wird sie von der Reihenfolge beeinflusst, in der wir die Ziele auflisten, oder erfolgt sie zufällig?

Die Reihenfolge der TURN-Server wird nicht anhand der angegebenen Liste garantiert. Stattdessen wählt die ICE-Implementierung, wenn die Medien die ICE-Implementierung aus, welcher Kandidat/Server die beste Konnektivität aufweist und erfolgreich zuerst verhandelt.

Wenn die URL des TURN-Servers auf mehrere IP-Adressen verweist, wie wird dann der spezifische TURN-Server für die Sitzung ausgewählt? Ist dies zufällig?

Die meisten Implementierungen, einschließlich der in Chrome und Firefox verwendeten, nehmen die erste IP, die von der DNS-Abfrage zurückgegeben wird. Dies führt in der Regel zu einer zufälligen Auswahl in der Runde.

Wenn sowohl TCP- als auch UDP-TURN-Server bereitgestellt werden und erreichbar sind, ist es dann möglich, UDP-Ziele zu priorisieren und nur bei Bedarf auf TCP zurückzugreifen?

UDP-Relay-Kandidaten werden gegenüber TCP-Relay-Kandidaten bevorzugt, da diese Kandidaten eine eine niedrigere lokale Typpräferenz und damit eine niedrigere Priorität haben. Siehe RFC 8445 für Details. Die Reihenfolge der übergebenen ICE-Server spielt dabei keine Rolle.

Kann ein einzelner Client verschiedene Medienpfade für verschiedene Streams verwenden?

Ja, das ist das erwartete Verhalten, da OpenTok jeden einzelnen Medienstrom separat behandelt.

Wie viel Kontrolle hat die konfigurierbare TURN-API über die Auswahl des Medienpfads?

Die Auswahl des Medienpfads wird von ICE (Interactive Connectivity Establishment) innerhalb von WebRTC gehandhabt, und wir haben keine Möglichkeit, dieses Verhalten zu ändern. Die konfigurierbare TURN-API hilft nur bei der Änderung der Liste von ICE-Servern, die der Client WebRTC zur Verfügung stellt, und beeinflusst den Auswahlprozess nicht.

Ist eine direkte Verbindung zum OpenTok Media Server über UDP immer vorzuziehen?

Ja, eine direkte Verbindung zum OpenTok-Medienserver wird grundsätzlich bevorzugt. Es wird auf TURN umgeschaltet, wenn die Verbindung zum OpenTok-Medienserver fehlschlägt oder wenn die Option „Force TURN“ in der konfigurierbaren TURN-API verwendet wird.

Kann ich mehrere TURN-Server desselben Typs zum Lastausgleich verwenden?

Dies wird nicht empfohlen, da der Client dann einen zufälligen Server auswählt, der sich während der Dauer der Verbindung ändern kann.

Wie kann ich die Last meines TURN-Servers ausbalancieren?

Bitte kontaktieren Sie uns für weitere Informationen.

Kann der TURN-Server Medien entschlüsseln?

Nein, der TURN-Server hat keinen Zugriff auf die SRTP-Schlüssel, die mit DTLS-SRTP ausgetauscht werden und nur den Endpunkten der Verbindung zur Verfügung stehen.

Was passiert, wenn ein TURN-Server während einer Sitzung abstürzt und wie man ihn wiederherstellen kann

Wenn ein TURN-Server abstürzt, während er benutzt wird, führt dies dazu, dass die Verbindung des Clients getrennt wird. Der Client versucht dann, die Verbindung mit einem ICE-Neustart wiederherzustellen.

Wie kann ich einen TURN-Server testen?

Sie können Ihren TURN-Server entweder mithilfe der Video API Spielwiese, das Trickle Ice Testseite oder das coturn turnutils_uclient.