From bb5eedfae95a83bff5237007495bafdc57674997 Mon Sep 17 00:00:00 2001 From: Juan Navarro Date: Thu, 30 Apr 2020 17:46:06 +0200 Subject: [PATCH] Rework all references and texts about STUN/TURN/ICE/NAT Users seem to keep falling into the same pitfalls with regards to (lack of) configuring STUN or TURN in their browsers and/or KMS installations. This change brings a better structure of the documentation sections, to remove duplicated explanations and provide a better "flow" to guide users when they start reading from the Install instructions. Definition of NAT, ICE, STUN, TURN has been moved from the FAQ to their appropriate entries in the Glossary. FAQ now has centralized information about a) installing Coturn, b) testing Coturn (or any other STUN/TURN server), and c) configuring STUN/TURN into Kurento Media Server. KMS config is explained in both static mode (with .conf file), and dynamic mode (using the API methods from the Server Application). Fixes https://github.com/Kurento/bugtracker/issues/461 --- source/features/events.rst | 4 +- source/features/nat_traversal.rst | 10 +- source/glossary.rst | 22 ++-- source/knowledge/browser.rst | 2 +- source/knowledge/nat.rst | 8 +- source/user/faq.rst | 208 +++++++++++++++++++----------- source/user/features.rst | 2 +- source/user/installation.rst | 87 +++---------- source/user/troubleshooting.rst | 51 ++++---- 9 files changed, 196 insertions(+), 198 deletions(-) diff --git a/source/features/events.rst b/source/features/events.rst index bcd70979..fcb68f6b 100644 --- a/source/features/events.rst +++ b/source/features/events.rst @@ -209,7 +209,7 @@ This graph shows the possible state changes (`source `__. +:term:`ICE` is the standard method used by :term:`WebRTC` to solve the issue of :term:`NAT Traversal`. Kurento supports ICE by means of a 3rd-party library: `libnice, The GLib ICE implementation `__. Refer to the :ref:`logging documentation ` if you need to enable the debug logging for this library. @@ -26,11 +26,11 @@ KMS is able to automatically infer what is the public IP and port of any remote **TCP-Based Media Transport in the Session Description Protocol** (SDP) (`IETF RFC 4145 `__) defines an SDP extension which adds TCP connections and procedures, such as how a passive machine would wait for connections from a remote active machine and be able to obtain connection information from the active one, upon reception of an initial connection. -Early Drafts of RFC 4145 (up to `Draft 05 `__) also contemplated the usage of this same concept of "Connection-Oriented Media Transport in SDP" with UDP connections, as a way of aiding NAT traversal. This is what has been used as a basis for the implementation of automatic port discovery in KMS. +Early Drafts of RFC 4145 (up to `Draft 05 `__) also contemplated the usage of this same concept of "Connection-Oriented Media Transport in SDP" with UDP connections, as a way of aiding :term:`NAT Traversal`. This is what has been used as a basis for the implementation of automatic port discovery in KMS. It works as follows: -1. The machine behind a NAT router acts as the active peer. It sends an SDP Offer to the other machine, the passive peer. +1. The machine behind a :term:`NAT` router acts as the active peer. It sends an SDP Offer to the other machine, the passive peer. A. Sending an SDP Offer from behind a NAT means that the IP and port specified in the SDP message are actually just the private IP and port of that machine, instead of the public ones. The passive peer won't be able to use these to communicate back to the active peer. Due to this, the SDP Offer states the port ``9`` (*Discard port*) instead of whatever port the active machine will be using. B. The SDP Offer includes the media-level attribute ``a=direction:active``, so the passive peer is able to acknowledge that the Connection-Oriented Media Transport is being used for that media, and it writes ``a=direction:passive`` in its SDP Answer. @@ -60,7 +60,7 @@ This is how to enable the Connection-Oriented Media Transport mode: Example ------- -This is a minimal example of an :term:`SDP Offer/Answer` negotiation that a machine would perform with KMS from behind a NAT router. The highlighted lines are those relevant to NAT Traversal: +This is a minimal example of an :term:`SDP Offer/Answer` negotiation that a machine would perform with KMS from behind a :term:`NAT` router. The highlighted lines are those relevant to NAT Traversal: .. code-block:: text :caption: SDP Offer diff --git a/source/glossary.rst b/source/glossary.rst index 6469e416..fb632cf1 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -68,7 +68,9 @@ This is a glossary of terms that often appear in discussion about multimedia tra Hypertext Transfer Protocol -- HTTP/1.1 ICE - Interactive Connectivity Establishment (ICE) is a technique used to achieve :term:`NAT Traversal`. ICE makes use of the :term:`STUN` protocol and its extension, :term:`TURN`. ICE can be used by any aplication that makes use of the SDP Offer/Answer model.. + *Interactive Connectivity Establishment* (ICE) is a protocol used for :term:`NAT Traversal`. It defines a technique that allows communication between two endpoints when one is inside a NAT and the other is outside of it. The net effect of the ICE process is that the NAT will be left with all needed ports open for communication, and both endpoints will have complete information about the IP address and ports where the other endpoint can be contacted. + + ICE doesn't work standalone: it uses a couple of helper protocols called :term:`STUN` and :term:`TURN`. .. seealso:: @@ -161,7 +163,9 @@ This is a glossary of terms that often appear in discussion about multimedia tra NAT Network Address Translation - Network address translation (NAT) is the technique of modifying network address information in Internet Protocol (IP) datagram packet headers while they are in transit across a traffic routing device for the purpose of remapping one IP address space into another. + *Network Address Translation* (NAT) is a mechanism that hides from the public access the private IP addresses of machines inside a network. The NAT mechanism is typically found in all types of network devices, ranging from home routers to full-fledged corporate firewalls. In all cases the effect is the same: machines inside the NAT cannot be freely accessed from outside. + + NAT introduces a lot of problems for WebRTC communications: machines inside the network will be able to send data to the outside, but they won't be able to receive data from remote participants that are outside the network. In order to allow for this, NAT devices typically allow to configure **NAT bindings** to let data come in from the outside part of the network; creating these NAT bindings is what is called :term:`NAT Traversal`, also commonly referred as "opening ports". .. seealso:: @@ -173,9 +177,8 @@ This is a glossary of terms that often appear in discussion about multimedia tra `How Network Address Translation Works `__ (`archive `__) A comprehensive description of NAT and its mechanics. - NAT-T NAT Traversal - NAT traversal (sometimes abbreviated as NAT-T) is a general term for techniques that establish and maintain Internet protocol connections traversing network address translation (NAT) gateways, which break end-to-end connectivity. Intercepting and modifying traffic can only be performed transparently in the absence of secure encryption and authentication. + NAT Traversal is a general term for techniques that establish and maintain Internet protocol connections traversing network address translation (:term:`NAT`) gateways, which break end-to-end connectivity. Intercepting and modifying traffic can only be performed transparently in the absence of secure encryption and authentication. .. seealso:: @@ -380,8 +383,7 @@ This is a glossary of terms that often appear in discussion about multimedia tra Secure Socket Layer. See :term:`TLS`. STUN - STUN stands for **Session Traversal Utilities for NAT**. It is a standard protocol (`IETF RFC 5389 `__) used by :term:`NAT` traversal algorithms to assist hosts in the discovery of their public network information. - If the routers between peers use full cone, address-restricted, or port-restricted NAT, then a direct link can be discovered with STUN alone. If either one of the routers use symmetric NAT, then a link can be discovered with STUN packets only if the other router does not use symmetric or port-restricted NAT. In this later case, the only alternative left is to discover a relayed path through the use of :term:`TURN`. + *Session Traversal Utilities for NAT* (STUN) is a protocol that complements :term:`ICE` in the task of solving the :term:`NAT Traversal` issue. It can be used by any endpoints to determine the IP address and port allocated to it by a :term:`NAT`. It can also be used to check connectivity between two endpoints, and as a keep-alive protocol to maintain NAT bindings. STUN works with many existing types of NAT, and does not require any special behavior from them. Trickle ICE Extension to the :term:`ICE` protocol that allows ICE agents to send and receive candidates incrementally rather than exchanging complete lists. With such incremental provisioning, ICE agents can begin connectivity checks while they are still gathering candidates and considerably shorten the time necessary for ICE processing to complete. @@ -402,9 +404,11 @@ This is a glossary of terms that often appear in discussion about multimedia tra The Transport Layer Security (TLS) Protocol Version 1.2. TURN - TURN stands for **Traversal Using Relays around NAT**. Like :term:`STUN`, it is a network protocol (`IETF RFC 5766 `__) used to assist in the discovery of paths between peers on the Internet. - It differs from STUN in that it uses a public intermediary relay to act as a proxy for packets between peers. It is used when no other option is available since it consumes server resources and has an increased latency. - The only time when TURN is necessary is when one of the peers is behind a symmetric NAT and the other peer is behind either a symmetric NAT or a port-restricted NAT. + *Traversal Using Relays around NAT* (TURN) is an extension of :term:`STUN`, used where the :term:`NAT` security policies are too strict and the needed NAT bindings cannot be successfully created to achieve :term:`NAT Traversal`. In these situations, it is necessary for the host to use the services of a TURN server that acts as a communication relay. + + .. note:: + + **You don't need to set a STUN server up if you have already configured a TURN relay**, because TURN is just an extension of STUN. VP8 VP8 is a video compression format created by On2 Technologies as a successor to VP7. Its patents rights are owned by Google, who made an irrevocable patent promise on its patents for implementing it and released a specification under the `Creative Commons Attribution 3.0 license `__. diff --git a/source/knowledge/browser.rst b/source/knowledge/browser.rst index d28a03ca..282cfbbd 100644 --- a/source/knowledge/browser.rst +++ b/source/knowledge/browser.rst @@ -89,7 +89,7 @@ With command line arguments: -MOZ_LOG=timestamp,rotate:200,nsHttp:5,cache2:5,nsSocketTransport:5,nsHostResolver:5 \ -MOZ_LOG_FILE=/tmp/firefox.log -Log ICE candidates / STUN / TURN: +Log :term:`ICE` candidates / :term:`STUN` / :term:`TURN`: .. code-block:: bash diff --git a/source/knowledge/nat.rst b/source/knowledge/nat.rst index 9a752237..3f5fd611 100644 --- a/source/knowledge/nat.rst +++ b/source/knowledge/nat.rst @@ -44,7 +44,7 @@ Visualization: Inbound NAT connection ---------------------- -A NAT maintains **inbound** rules which are used to translate IP tuples between the NAT's *external* and *internal* sides. Usually, the *external* side of the NAT is facing the public internet (*WAN*), while the *internal* side of the NAT is facing the local network (*LAN*). These inbound rules have the form of a *hash table* (or *map*); for each given key, there is a resulting value: +A :term:`NAT` maintains **inbound** rules which are used to translate IP tuples between the NAT's *external* and *internal* sides. Usually, the *external* side of the NAT is facing the public internet (*WAN*), while the *internal* side of the NAT is facing the local network (*LAN*). These inbound rules have the form of a *hash table* (or *map*); for each given key, there is a resulting value: - The key of the table is an IP quadruplet, formed by a NAT's external IP tuple and a remote machine's IP tuple. - The value of the table is a NAT's internal IP tuple. @@ -159,7 +159,7 @@ Symmetric NAT This type of NAT behaves in the same way of a Port-Restricted Cone NAT, with an important difference: for each outbound connection to a different remote IP tuple (i.e. to a different remote machine), the NAT assigns a **new random source port** on the external side. This means that two consecutive connections from the same local port to two different remote machines will have two different external source ports, even if the internal source IP tuple is the same for both of them. -This is also the only case where the ICE connectivity protocol will find `Peer Reflexive candidates `__ which differ from the Server Reflexive ones, due to the differing ports between the connection to the STUN server and the direct connection between peers. +This is also the only case where the ICE connectivity protocol will find `Peer Reflexive candidates `__ which differ from the Server Reflexive ones, due to the differing ports between the connection to the :term:`STUN` server and the direct connection between peers. Visualization: @@ -198,9 +198,9 @@ The NAT mechanism is implemented in a vast majority of home and corporate router To connect with a local machine which is behind any type of NAT, it's first required that the local machine performs an outbound connection to the remote one. This way, a dynamic rule will be created for the destination IP tuple, allowing the remote machine to connect back. -In order to tell one machine when it has to perform an outbound connection to another one, and the destination IP tuple it must use, the typical solution is to use a helper service such as STUN. This is usually managed by a third machine, a server sitting on a public internet address. It retrieves the external IP and port of each peer, and gives that information to the other peers that want to communicate. +In order to tell one machine when it has to perform an outbound connection to another one, and the destination IP tuple it must use, the typical solution is to use a helper service such as :term:`STUN`. This is usually managed by a third machine, a server sitting on a public internet address. It retrieves the external IP and port of each peer, and gives that information to the other peers that want to communicate. -STUN/TURN requirement: +:term:`STUN` / :term:`TURN` requirements: - Symmetric to Symmetric: *TURN*. - Symmetric to Port-Restricted Cone: *TURN*. diff --git a/source/user/faq.rst b/source/user/faq.rst index 21cd028b..df57a995 100644 --- a/source/user/faq.rst +++ b/source/user/faq.rst @@ -7,57 +7,49 @@ Frequently Asked Questions About NAT, ICE, STUN, TURN ========================== -What is NAT? ------------- +These are very important concepts that developers must understand well to work with WebRTC. Here is a collection of all Kurento material talking about these acronyms: -*Network Address Translation* (:term:`NAT`) is a mechanism that hides from the public access the private IP addresses of machines inside a network. This NAT mechanism is typically found in all types of network devices, ranging from home routers to full-fledged corporate firewalls. In all cases the effect is the same: machines inside the NAT cannot be freely accessed from outside. +* Glossary: -The effects of a NAT is very negative for WebRTC communications: machines inside the network will be able to send data to the outside, but they won't be able to receive data from remote endpoints that are sitting outside the network. In order to allow for this need, NAT devices typically allow to configure **NAT bindings** to let data come in from the outside part of the network; creating these NAT bindings is what is called :term:`NAT traversal`, also commonly referred as "opening ports". + - :term:`What is NAT `? + - :term:`What is NAT Traversal `? + - :term:`What is ICE `? + - :term:`What is STUN `? + - :term:`What is TURN `? +* Installing and configuring a STUN/TURN server: + - :ref:`faq-coturn-install` + - :ref:`faq-stun-test` + - :ref:`faq-stun-configure` -What is ICE? ------------- - -*Interactive Connectivity Establishment* (:term:`ICE`) is a protocol used for :term:`NAT traversal`. It defines a technique that allows communication between two endpoints when one is inside a NAT and the other is outside of it. The net effect of the ICE process is that the NAT will be left with all needed ports open for communication, and both endpoints will have complete information about the IP address and ports where the other endpoint can be contacted. - -ICE doesn't work standalone: it needs to use a helper protocol called STUN. - - - -What are STUN and TURN? ------------------------ - -*Session Traversal Utilities for NAT* (:term:`STUN`) is a protocol that complements :term:`ICE` in the task of solving the :term:`NAT traversal` issue. It can be used by any endpoints to determine the IP address and port allocated to it by a NAT. It can also be used to check connectivity between two endpoints, and as a keep-alive protocol to maintain NAT bindings. STUN works with many existing NATs, and does not require any special behavior from them. - -*Traversal Using Relays around NAT* (:term:`TURN`) is an extension of STUN, used where the NAT security policies are too strict and the needed NAT bindings cannot be successfully created. In these situations, it is necessary for the host to use the services of an intermediate node that acts as a communication relay. - -.. note:: - - **Every TURN server supports STUN**, because TURN is just an extension of STUN, to provide for a network relay. This means that *you don't need to set a STUN server up if you have already configured a TURN server*. +* Troubleshooting :ref:`troubleshooting-webrtc` +* Advanced knowledge: :doc:`/knowledge/nat` -.. _faq-stun: +.. _faq-stun-needed: -When is STUN needed? --------------------- +When are STUN and TURN needed? +------------------------------ -:term:`STUN` (and possibly :term:`TURN`) is needed **for every endpoint behind a NAT**. All peers that try to connect from behind a :term:`NAT` will need to "*open*" their own NAT ports, a process that is known as :term:`NAT traversal`. This is achieved by using a STUN/TURN server that is deployed *outside of the NAT*. +:term:`STUN` (and possibly :term:`TURN`) is needed **for every WebRTC participant behind a NAT**. All peers that try to connect from behind a :term:`NAT` will need to "*open*" their own ports, a process that is known as :term:`NAT Traversal`. This is achieved by using a STUN server that is deployed **outside of the NAT**. -The STUN/TURN server is configured to use a range of UDP & TCP ports. All those ports should also be opened to all traffic, in the server's network configuration or security group. +The STUN server is configured to use a range of UDP & TCP ports. All those ports should also be opened to all traffic, in the server's network configuration or security group. -If you are installing Kurento in a NAT environment (e.g. if your server is behind a NAT firewall), you also need to configure an external STUN or TURN server in */etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini*. Similarly, all browser clients that are behind a NAT need to configure the STUN and/or TURN server details with the ``iceServers`` field of the `RTCPeerConnection constructor `__. +If you are installing Kurento in a NAT environment (e.g. if your server is behind a NAT firewall), you also need to configure an external STUN server, in */etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini*. Similarly, all browser clients that are behind a NAT need to configure the STUN server details with the ``iceServers`` field of the `RTCPeerConnection constructor `__. **Example:** -The typical installation scenario for Kurento Media Server is to have a strict separation between Application Server and client. KMS and Application Server are running in a cloud machine **without any NAT** or port restriction on incoming connections, while a browser client runs from any (possibly restricted) network that forbids incoming connections on any port that hasn't been "opened" in advance (i.e., a NAT). The client may communicate with the Application Server for signaling purposes, but at the end of the day the bulk of the audio/video communication is done between the WebRTC engines of the browser and KMS. +Kurento Media Server and its Application Server are running in a cloud machine **without any NAT** or port restriction on incoming connections, while a browser client runs from a possibly restricted :term:`NAT` network that forbids incoming connections on any port that hasn't been "opened" in advance + +The browser client may communicate with the Application Server for signaling purposes, but at the end of the day the bulk of the audio/video communication is done between the WebRTC engines of the browser and KMS. .. figure:: /images/faq-stun-1.png :align: center :alt: NAT client without STUN -In scenarios such as this one, the client is able to send data to KMS because its NAT will allow outgoing packets. However, KMS will *not* be able to send data to the client, because the client's NAT is closed for incoming packets. This is solved by configuring the client to use a STUN server; this server will be used by the client's browser to open the appropriate ports in the NAT. After this operation, the client is now able to receive audio/video streams from KMS: +In scenarios like this, the client is able to send data to KMS because its NAT will allow outgoing packets. However, KMS will *not* be able to send data to the client, because the client's NAT is closed for incoming packets. This is solved by configuring the client to use a STUN server; this server will be used by the client's browser to open the appropriate ports in the NAT. After this operation, the client is now able to receive audio/video streams from KMS: .. figure:: /images/faq-stun-2.png :align: center @@ -65,7 +57,7 @@ In scenarios such as this one, the client is able to send data to KMS because it This procedure is done by the :term:`ICE` implementation of the client's browser. -Note that you *can* also deploy KMS behind a NAT firewall, as long as KMS itself is also configured to use a STUN/TURN server. +Note that you *can* also deploy KMS behind a NAT firewall, as long as KMS itself is also configured to use a STUN server. Further reading: @@ -74,10 +66,12 @@ Further reading: +.. _faq-coturn-install: + How to install Coturn? ---------------------- -Coturn is a :term:`STUN` server and (optionally) a :term:`TURN` relay, supporting all features required for the :term:`ICE` protocol and allowing to establish WebRTC connections from behind a :term:`NAT`. +Coturn is a :term:`STUN` server and :term:`TURN` relay, supporting all features required for the :term:`ICE` protocol and allowing to establish WebRTC connections from behind a :term:`NAT`. Coturn can be installed directly from the Ubuntu package repositories: @@ -86,9 +80,9 @@ Coturn can be installed directly from the Ubuntu package repositories: sudo apt-get update && sudo apt-get install --no-install-recommends --yes \ coturn -Then, follow these steps: +To configure it for WebRTC, follow these steps: -1. Edit */etc/turnserver.conf* and configure the server according to your needs. +1. Edit */etc/turnserver.conf*. This example configuration is a good first step; it will work for using Coturn with Kurento Media Server for WebRTC streams. However, you may want to change it according to your needs: @@ -130,11 +124,13 @@ Then, follow these steps: # Disable log file rollover and use log file name as-is. simple-log - - The *external-ip* is necessary in cloud providers which use internal NATs, such as **Amazon EC2** (**AWS**). Write in ```` your server's **public** IP address, like ``198.51.100.1``. It must be an IP address, **not a domain name**. + Notes: + + - The *external-ip* is necessary in cloud providers which use internal NATs, such as **Amazon EC2** (AWS). Write your server's **public** IP address, like ``198.51.100.1``, in the ```` parameter. **It must be an IP address, not a domain name**. - The options *fingerprint*, *lt-cred-mech*, and *realm* are needed for WebRTC. - - The *user* parameter is the most basic form of authorization to use the TURN relay capabilities. Write your desired user name and password in the fields ```` and ````. + - The *user* parameter is the most basic form of authorization to use the :term:`TURN` relay capabilities. Write your desired user name and password in the fields ```` and ````. - Other parameters can be tuned as needed. For more information, check the Coturn help pages: @@ -150,80 +146,138 @@ Then, follow these steps: so the server starts automatically as a system service daemon. -3. Configure Kurento Media Server and point it to where the STUN/TURN server is listening for connections. Edit the file */etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini* and set either the STUN or the TURN parameters: +3. Follow with the next sections to test that Coturn is working, and then set it up as your STUN/TURN server in Kurento Media Server. + + + +.. _faq-stun-test: + +How to test my STUN/TURN server? +-------------------------------- + +To test if your :term:`STUN`/:term:`TURN` server is functioning properly, open the `Trickle ICE test page `__. In that page, follow these steps: + +1. Remove any server that might be filled in already by default. + +2. Fill in your STUN/TURN server details. + + - To only test STUN server (TURN relay will not be tested): + + .. code-block:: text + + stun:: + + - To test both STUN server and TURN relay: + + .. code-block:: text + + turn:: + + ... and also fill in the *TURN username* and *TURN password*. + +3. Click on *Add Server*. You should have only **one entry** in the list, with your server details. + +4. Click on *Gather candidates*. **Verify** that you get candidates of type ``srflx`` if you are testing STUN. Likewise, you should get candidates of type ``srflx`` *and* type ``relay`` if you are testing TURN. + + If you are missing any of the expected candidate types, *your STUN/TURN server is not working well* and WebRTC will fail. Check your server configuration, and your cloud provider's network settings. + + + +.. _faq-stun-configure: + +How to configure STUN/TURN? +--------------------------- + +To configure a :term:`STUN` server or :term:`TURN` relay with Kurento Media Server, you may use either of two methods: + +A. Write the parameters into the file */etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini*. Do this if your settings are static and you know them beforehand. + + To only use STUN server (TURN relay will not be used): .. code-block:: text - stunServerAddress= - stunServerPort= + stunServerAddress= + stunServerPort= + + ```` should be the public IP address of the STUN server. **It must be an IP address, not a domain name**. For example: .. code-block:: text - turnURL=:@: + stunServerAddress=198.51.100.1 + stunServerPort=3478 - If you only configure the STUN parameters in KMS, then the TURN relay capability of Coturn won't be used. Of course, if you instead configure the whole TURN URL, then KMS will be able to use the Coturn server as a TURN relay when it needs to. + To use both STUN server and TURN relay: - .. note:: + .. code-block:: text - **Every TURN server supports STUN**, because TURN is just an extension of STUN, to provide for a network relay. This means that *you don't need to set a STUN server up if you have already configured a TURN server*. + turnURL=:@: - The following ports should be open in the firewall or your cloud machine's *Security Groups*: + ```` should be the public IP address of the TURN relay. **It must be an IP address, not a domain name**. For example: - - **** (Default: 3478) UDP & TCP. - - **49152-65535** UDP & TCP: As per :rfc:`5766`, these are the ports that the TURN server will use to exchange media. These ports can be changed using Coturn's ``min-port`` and ``max-port`` parameters. + .. code-block:: text - .. note:: + turnURL=myuser:mypassword@198.51.100.1:3478 - The STUN/TURN ports that are configured in Coturn **must match those configured in Kurento Media Server**. This can be done in the file */etc/kurento/modules/kurento/BaseRtpEndpoint.conf.ini*, so it is possible to restrict the port range used by KMS to have a reduced set of open ports in your server. +B. Use the API methods to set the parameters dynamically. Do this if your STUN server details are not known beforehand, or if your TURN credentials are generated on runtime: -4. (Re)Start both Coturn and Kurento servers: + To only use STUN server (TURN relay will not be used): - .. code-block:: bash + .. code-block:: text - sudo service coturn restart - sudo service kurento-media-server restart + setStunServerAddress(""); + setStunServerPort(); -5. Check that your STUN/TURN server is working, by using the `Trickle ICE test page `__: + Kurento Client API docs: `Java `__, `JavaScript `__. - - If you configured Coturn to act just as a STUN server, use an URI with this format: ``stun::``. - - If you left the default settings, then Coturn will act as both STUN and TURN server. Use an URI like this: ``turn::``, and also write the ```` and ````. - - Finally, click on "*Gather candidates*" and check that you get candidates of type "**srflx**" (STUN) and "**relay**" (TURN). + To use both STUN server and TURN relay: + .. code-block:: text + setTurnUrl(":@:"); -Readings about NAT, ICE, STUN, TURN ------------------------------------ + Kurento Client API docs: `Java `__, `JavaScript `__. -Here is a collection of all Kurento material talking about these topics: +.. note:: -* Frequently Asked Questions: :ref:`faq-nat-ice-stun-turn` -* Glossary: :term:`ICE`; :term:`STUN`; :term:`TURN`; :term:`NAT traversal` -* Installing and configuring Kurento: :ref:`installation-stun-turn` -* Troubleshooting network issues: :ref:`troubleshooting-webrtc-connection` -* Advanced knowledge: :doc:`/knowledge/nat` + **You don't need to set a STUN server up if you have already configured a TURN relay**, because TURN is just an extension of STUN. + +The following ports should be open in the firewall or your cloud machine's *Security Groups*: + +- **** (Default: 3478) UDP & TCP. +- **49152-65535** UDP & TCP: As per :rfc:`5766`, these are the ports that the TURN relay will use to exchange media. These ports can be changed using Coturn's ``min-port`` and ``max-port`` parameters. + +.. note:: + + **Port ranges must match between Coturn and Kurento Media Server**. Check the files */etc/turnserver.conf* and */etc/kurento/modules/kurento/BaseRtpEndpoint.conf.ini*, to verify that both will be using the same set of ports. + +When you are done, (re)start both Coturn and Kurento servers: + +.. code-block:: bash + + sudo service coturn restart + sudo service kurento-media-server restart -How To ... -========== +How many Media Pipelines do I need for my Application? +====================================================== -Know how many Media Pipelines do I need for my Application? ------------------------------------------------------------ +A Pipeline is a top-level container that handles every resource that should be able to achieve any kind of interaction with each other. Media Elements can only communicate when they are part of the same Pipeline. Different Pipelines in the server are independent, so they do not share audio, video, data or events. -Media Elements can only communicate with each other when they are part of the same pipeline. Different MediaPipelines in the server are independent do not share audio, video, data or events. +99% times, this translates to using 1 Pipeline object for each "room"-like videoconference. It doesn't matter if there is 1 single presenter and N viewers ("one-to-many"), or if there are N participants Skype-style ("many-to-many"), all of them are managed by the same Pipeline. So, most actual real-world applications would only ever create 1 Pipeline, because that's good enough for most needs. -A good heuristic is that you will need one pipeline per each set of communicating partners in a channel, and one Endpoint in this pipeline per audio/video streams reaching a partner. +A good heuristic is that you will need one Pipeline per each set of communicating partners in a channel, and one Endpoint in this Pipeline per audio/video streams exchanged with a participant. -Know how many Endpoints do I need? ----------------------------------- +How many Endpoints do I need? +============================= -Your application will need to create an Endpoint for each media stream flowing to (or from) the pipeline. As we said in the previous answer, each set of communicating partners in a channel will be in the same Media Pipeline, and each of them will use one or more Endpoints. They could use more than one if they are recording or reproducing several streams. +Your application will need to create at least one Endpoint for each media stream flowing to (or from) each participant. You might actually need more, if the streams are to be recorded or if streams are being duplicated for other purposes. -Know to what client a given WebRtcEndPoint belongs or where is it coming from? ------------------------------------------------------------------------------- +Which participant corresponds to which Endpoint? +================================================ -Kurento API currently offers no way to get application attributes stored in a Media Element. However, the application developer can maintain a hashmap or equivalent data structure mapping the ``WebRtcEndpoint`` internal Id (which is a string) to whatever application information is desired. +The Kurento API offers no way to get application-level semantic attributes stored in a Media Element. However, the application developer can maintain a HashMap or equivalent data structure, storing the Endpoint identifiers (which are plain strings) to whatever application information is desired, such as the names of the participants. diff --git a/source/user/features.rst b/source/user/features.rst index 703e6949..085e1eb7 100644 --- a/source/user/features.rst +++ b/source/user/features.rst @@ -64,7 +64,7 @@ RTP Streaming Besides WebRTC connections, Kurento Media Server is able to manage standard RTP streams, allowing to connect an instance of KMS to a wide variety of devices. -There are two topics to note when dealing with RTP connections: the automatic congestion control algorithms that KMS implements (see :ref:`features-remb`), and the NAT traversal capabilities (see :doc:`/features/nat_traversal`). +There are two topics to note when dealing with RTP connections: the automatic congestion control algorithms that KMS implements (see :ref:`features-remb`), and the :term:`NAT Traversal` capabilities (see :doc:`/features/nat_traversal`). diff --git a/source/user/installation.rst b/source/user/installation.rst index 8f077bff..b5d73e70 100644 --- a/source/user/installation.rst +++ b/source/user/installation.rst @@ -8,7 +8,9 @@ Installation Guide * :ref:`Using the Kurento Docker images `. Docker allows to run Kurento in any host machine, so for example it's possible to run KMS on top of a Fedora or CentOS system. In theory it could even be possible to run under Windows, but so far that possibility hasn't been explored by the Kurento team, so you would be at your own risk. -* :ref:`Setting up a local installation ` with ``apt-get install``. This method allows to have total control of the installation process. Besides installing KMS, a common need is also :ref:`installing a STUN/TURN server `, especially if KMS or any of its clients are located behind a :ref:`Symmetric NAT ` or firewall. +* :ref:`Setting up a local installation ` with ``apt-get install``. This method allows to have total control of the installation process. + +Besides installing KMS, a common need is also :ref:`installing a STUN/TURN server `, especially if KMS or any of its clients are located behind a :term:`NAT` router or firewall. If you want to try nightly builds of KMS, then head to the section :doc:`/user/installation_dev`. @@ -45,13 +47,13 @@ Follow these steps to use it: 4.4. **SSHLocation**: For security reasons you may need to restrict SSH traffic to allow connections only from specific locations. For example, from your home or office. - 4.5. **TurnUser**: User name for the TURN server. + 4.5. **TurnUser**: User name for the TURN relay. - 4.6. **TurnPassword**: Password required to use the TURN server. + 4.6. **TurnPassword**: Password required to use the TURN relay. .. note:: - The template file includes *Coturn* as a :term:`TURN` server. The default user/password for this server is ``kurento``/``kurento``. You can optionally change the username, but **make sure to change the default password**. + The template file includes *Coturn* as a :term:`STUN` server and :term:`TURN` relay. The default user/password for this server is ``kurento``/``kurento``. You can optionally change the username, but **make sure to change the default password**. 5. Finish the Stack creation process. Wait until the status of the newly created Stack reads *CREATE_COMPLETE*. @@ -186,77 +188,20 @@ B. **Uninstall the old Kurento version**, before installing the new one. .. _installation-stun-turn: -STUN and TURN servers -===================== - -If Kurento Media Server, its Application Server, or any of the clients are located behind a :term:`NAT`, you need to use a :term:`STUN` or a :term:`TURN` server in order to achieve :term:`NAT traversal`. You can read more about this topic here: :doc:`/knowledge/nat`. - -In most cases, STUN is effective in addressing the NAT issue with most consumer network devices (routers). However, it doesn't work for many corporate networks, so a TURN server becomes necessary. - -.. note:: - - **Every TURN server supports STUN**, because TURN is just an extension of STUN, to provide for a network relay. This means that *you don't need to set a STUN server up if you have already configured a TURN server*. - -The STUN/TURN server is configured to use a range of UDP & TCP ports. All those ports should also be opened to all traffic, in the server's network configuration or security group. - -For more information about why and when STUN/TURN is needed, check out the FAQ: :ref:`faq-stun`. - - - -STUN server ------------ - -To configure a STUN server in KMS, uncomment the following lines in the WebRtcEndpoint configuration file, located at */etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini*: - -.. code-block:: bash - - stunServerAddress= - stunServerPort= - -The parameter ``StunServerIp`` should be the public IP address of the STUN server. It must be an IP address, **not a domain name**. For example: - -.. code-block:: bash - - stunServerAddress=198.51.100.1 - stunServerPort=3478 - -.. note:: - - Be careful since inline comments (with ``;``) are not allowed for parameters in the configuration files. Thus, the following line **is not correct**: - - .. code-block:: text - - stunServerAddress=198.51.100.1 ; My STUN server - - ... and must be changed to something like this: - - .. code-block:: text - - ; My STUN server - stunServerAddress=198.51.100.1 - -STUN is a very lightweight protocol and maintaining a STUN server is very cheap. For this reason, it should be easy to find some public STUN servers that are made available free of charge, if you don't want to maintain your own. - - - -TURN server ------------ - -To configure a TURN server in KMS, uncomment the following lines in the WebRtcEndpoint configuration file, located at */etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini*: - -.. code-block:: bash - - turnURL=:@: +STUN/TURN server install +======================== -The parameter ``TurnServerIp`` should be the public IP address of the TURN server. It must be an IP address, **not a domain name**. For example: +Working with WebRTC *requires* developers to know and have a good understanding about everything related to NAT, ICE, STUN, and TURN. If you don't know about these, you should start reading here: :ref:`faq-nat-ice-stun-turn`. -.. code-block:: bash +Kurento Media Server, just like any WebRTC endpoint, will work fine on its own, for *localhost* connections. You only need to install KMS if all you need are local network connections. - turnURL=myuser:mypassword@198.51.100.1:3478 +However, sooner or later you will want to make your application work in a cloud environment, and allow KMS to connect with remote clients. The problem is, remote clients will probably want to connect from behind a :term:`NAT` router, so your application needs to perform :term:`NAT Traversal` in the client's router. This can be done by setting up a :term:`STUN` server or a :term:`TURN` relay, and configuring it **in both KMS and the client browser**. -TURN servers are used to relay audio/video traffic between peers, and for this reason they are expensive to run. It is rare to find public ones that work free of charge while offering good performance, so we recommend that you deploy and maintain your own private TURN server. +These links contain the information needed to finish configuring your Kurento Media Server with a STUN/TURN server: -`Coturn`_ is an open source implementation of a STUN+TURN server. In the :ref:`STUN FAQ ` section you'll find instructions to install and configure it. +- :ref:`faq-coturn-install` +- :ref:`faq-stun-test` +- :ref:`faq-stun-configure` @@ -298,7 +243,7 @@ You should get a response similar to this one: HTTP/1.1 500 Internal Server Error Server: WebSocket++/0.7.0 -Ignore the error line: it is an expected error, because ``curl`` does not talk the Kurento protocol. We just checked that the ``WebSocket++`` server is actually up, and listening for connections. If you wanted, you could automate this check with a script similar to `healthchecker.sh`_, the one we use in `Kurento Docker images`_. +Ignore the error line: it is an expected error, because *curl* does not talk the Kurento protocol. We just checked that the *WebSocket* server is actually up, and listening for connections. If you wanted, you could automate this check with a script similar to `healthchecker.sh`_, the one we use in `Kurento Docker images`_. diff --git a/source/user/troubleshooting.rst b/source/user/troubleshooting.rst index 598639b6..421800b9 100644 --- a/source/user/troubleshooting.rst +++ b/source/user/troubleshooting.rst @@ -208,7 +208,7 @@ If the machine is disconnected during the actual installation of this package, t Missing audio or video streams ------------------------------ -If the Kurento Tutorials are showing an spinner, or your application is missing media streams, that's a strong indication that the network topology requires using either a STUN or TURN server, to traverse through the NAT firewall of intermediate routers. Check the section about :ref:`installing a STUN/TURN server `. +If the Kurento Tutorials are showing an spinner, or your application is missing media streams, that's a strong indication that the network topology requires using either a :term:`STUN` server or a :term:`TURN` relay, to traverse through the :term:`NAT` firewall of intermediate routers. Check the section about :ref:`installing a STUN/TURN server `. @@ -391,34 +391,20 @@ The solution is to ensure that both peers are able to find a match in their supp -Network issues -============== +.. _troubleshooting-webrtc: -Have a look at these articles about troubleshooting WebRTC: - -* `Troubleshooting WebRTC Connection Issues `__ (`archive `__). -* `Common (beginner) mistakes in WebRTC `__ (`archive `__). - - - -.. _troubleshooting-webrtc-connection: - -WebRTC connection is not established ------------------------------------- +WebRTC failures +=============== There is a multitude of possible reasons for a failed WebRTC connection, so you can start by following this checklist: -* You probably need to deploy an external STUN/TURN server such as Coturn, to make WebRTC connections possible. Read more about all this in the FAQ: :ref:`faq-stun`. - -* Check that your STUN/TURN server is working, by using the `Trickle ICE test page `__: +* Deploy a :term:`STUN`/:term:`TURN` server (such as Coturn), to make remote WebRTC connections possible: :ref:`faq-coturn-install`. - - If you just have a STUN server, use an URI with this format: ``stun::``. - - If you have a full-featured TURN server, use an URI like this: ``turn::``, and also write the ```` and ````. - - Finally, click on "*Gather candidates*" and check that you get candidates of type "**srflx**" (STUN) and "**relay**" (TURN). +* Test if your :term:`STUN`/:term:`TURN` server is working correctly: :ref:`faq-stun-test`. -* Configure your STUN/TURN server in Kurento Media Server, as explained here: :ref:`installation-stun-turn`. +* Configure your :term:`STUN`/:term:`TURN` server in Kurento Media Server: :ref:`faq-stun-configure`. -* Check the debug logs of your STUN/TURN server. Maybe the server is failing and some useful error messages are being printed in there. +* Check the debug logs of your :term:`STUN`/:term:`TURN` server. Maybe the server is failing and some useful error messages are being printed in there. * Check the debug logs of Kurento Media Server. Look for messages that confirm a correct configuration: @@ -438,6 +424,12 @@ There is a multitude of possible reasons for a failed WebRTC connection, so you * If WebRTC seems to disconnect exactly after some amount of time, every single time, **watch out for proxy timeouts**. Sometimes you have to extend the timeout for the site that is being hit with the problem. +* Have a look at these articles about troubleshooting WebRTC: + + - `Troubleshooting WebRTC Connection Issues `__ (`archive `__). + + - `Common (beginner) mistakes in WebRTC `__ (`archive `__). + ICE connection problems @@ -447,18 +439,18 @@ If your application receives an :ref:`events-icecomponentstatechange` event with Here are some tips to keep in mind: -* Check that you have correctly configured a :term:`STUN` and/or :term:`TURN` server both in Kurento Media Server (file *WebRtcEndpoint.conf.ini*), and in the client browsers (through the `RTCPeerConnection's iceServers setting `__). +* Check that you have correctly configured a :term:`STUN` server or :term:`TURN` relay, both in Kurento Media Server (file *WebRtcEndpoint.conf.ini*), and in the client browsers (through the `RTCPeerConnection's iceServers setting `__). -* Check that the TURN credentials are correct, by using the `Trickle ICE test page `__ and configuring there your STUNTURN server. For more details, see the section above: :ref:`troubleshooting-webrtc-connection`. +* Check that the :term:`TURN` credentials are correct, by using the `Trickle ICE test page `__ to test your STUN/TURN server, as explained here: :ref:`faq-stun-test`. * It is always a good idea to work out the **correlation between ICE failures on KMS with ICE failures on the client browser**. The combined logs of both sides might shed some light into what caused the disconnection. -* Inspect all :ref:`events-newcandidatepairselected` events emitted by Kurento. A lot of ICE candidates are tested for connectivity during the WebRTC session establishment, but only the actual working ones are reported with the *NewCandidatePairSelected* event. A **careful examination of all selected local and remote candidates** might reveal useful information about the kind of connectivity issues that clients might be having. +* Analyze all :ref:`events-newcandidatepairselected` events emitted by Kurento. A lot of ICE candidates are tested for connectivity during the WebRTC session establishment, but only the actual working ones are reported with the *NewCandidatePairSelected* event. A **careful examination of all selected local and remote candidates** might reveal useful information about the kind of connectivity issues that clients might be having. - For example, maybe you see that most or all of the selected local or remote candidates are of ``typ relay``, i.e. using a TURN server as a proxy for the audio/video streams. This would mean two things: + For example, maybe you see that most or all of the selected local or remote candidates are of ``typ relay``, i.e. using a :term:`TURN` relay as a proxy for the audio/video streams. This would mean two things: - 1. That the TURN server will be under high server load, possibly saturating the machine's resources. - 2. That **direct peer-to-peer WebRTC connections are not being established**, giving you a good starting point to investigate why this is happening. Usually, when you see usage of the TURN relay, this is caused by overzealous hardware or software firewalls, or the presence of Symmetric NAT modem/routers somewhere in the network path. + 1. That the :term:`TURN` relay will be under high server load, possibly saturating the machine's resources. + 2. That **direct peer-to-peer WebRTC connections are not being established**, giving you a good starting point to investigate why this is happening. Usually, when you see usage of the :term:`TURN` relay, this is caused by overzealous hardware or software firewalls, or the presence of Symmetric :term:`NAT` modem/routers somewhere in the network path. * If you see messages about ICE connection tests failing due to **timeout on trying pairs**, make sure that all required UDP ports for media content are open on the sever; otherwise, not only the ICE process will fail, but also the video or audio streams themselves won't be able to reach each WebRTC peer. @@ -513,6 +505,9 @@ To disable mDNS, open this URL: ``chrome://flags/#enable-webrtc-hide-local-ips-w +Other network issues +==================== + Multicast fails in Docker -------------------------