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 Kurento/bugtracker#461

source/features/events.rst

@@ -209,7 +209,7 @@ This graph shows the possible state changes (`source <https://cgit.freedesktop.o
 
 .. note::
 
-   The states *Ready* and *Failed* indicate that the ICE transport has completed gathering and is currently idle. However, since events such as adding a new interface or a new TURN server will cause the state to go back, *Ready* and *Failed* are **not** terminal states.
+   The states *Ready* and *Failed* indicate that the ICE transport has completed gathering and is currently idle. However, since events such as adding a new interface or a new :term:`STUN`/:term:`TURN` server will cause the state to go back, *Ready* and *Failed* are **not** terminal states.
 
 
 
@@ -300,7 +300,7 @@ When a *WebRtcEndpoint* instance has been created, and all event handlers have b
 
 5. ``AddIceCandidate``
 
-   Repeated multiple times; the remote peer will continue sending its own gathered candidates, of any type: ``host``, ``srflx`` (*STUN*), ``relay`` (*TURN*).
+   Repeated multiple times; the remote peer will continue sending its own gathered candidates, of any type: ``host``, ``srflx`` (:term:`STUN`), ``relay`` (:term:`TURN`).
 
 6. ``IceCandidateFound``
 

source/features/nat_traversal.rst

@@ -2,7 +2,7 @@
 NAT Traversal
 =============
 
-:term:`NAT Traversal`, also known as *Hole Punching*, is the procedure of opening an inbound port in the NAT tables of the routers which implement this technology (which are the vast majority of home and corporate routers).
+:term:`NAT Traversal`, also known as *Hole Punching*, is the procedure of opening an inbound port in the :term:`NAT` tables of the routers which implement this technology (which are the vast majority of home and corporate routers).
 
 There are different types of NAT, depending on how they behave: **Full Cone**, **Address-Restricted Cone**, **Port-Restricted Cone**, and **Symmetric**. For a comprehensive explanation of NAT and the different types that exist, please read our Knowledge Base document: :doc:`/knowledge/nat`.
 
@@ -11,7 +11,7 @@ There are different types of NAT, depending on how they behave: **Full Cone**, *
 WebRTC with ICE
 ===============
 
-:term:`ICE` is the standard method used by :term:`WebRTC` to solve the issue of NAT Traversal. Kurento supports ICE by means of a 3rd-party library: `libnice, The GLib ICE implementation <https://nice.freedesktop.org>`__.
+: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 <https://nice.freedesktop.org>`__.
 
 Refer to the :ref:`logging documentation <logging-libnice>` 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 <https://tools.ietf.org/html/rfc4145>`__) 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 <https://tools.ietf.org/html/draft-ietf-mmusic-sdp-comedia-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 <https://tools.ietf.org/html/draft-ietf-mmusic-sdp-comedia-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

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 <https://computer.howstuffworks.com/nat.htm>`__ (`archive <https://web.archive.org/web/20200213082726/https://computer.howstuffworks.com/nat.htm>`__)
               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 <https://tools.ietf.org/html/rfc5389>`__) 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 <https://tools.ietf.org/html/rfc5766>`__) 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 <https://creativecommons.org/licenses/by/3.0/>`__.

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
 

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 <https://tools.ietf.org/html/rfc5245#section-7.1.3.2.1>`__ 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 <https://tools.ietf.org/html/rfc5245#section-7.1.3.2.1>`__ 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*.