Code autogenerated from Kurento/doc-kurento@44f3b7e

source/project/relnotes/v6_16_0.rst

@@ -22,6 +22,19 @@ Of course, if you cannot guarantee that UDP will work in your network, then **yo
 
 Thanks to `@prlanzarin <https://github.com/prlanzarin>`__ (Paulo Lanzarin) for `Kurento/kms-elements#26 <https://github.com/Kurento/kms-elements/pull/26>`__ (*Add niceAgentIceTcp configuration option and API methods for it*).
 
+**Local install**
+
+* Set value ``iceTcp`` to 1 (ON) or 0 (OFF) in ``/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini``.
+
+**Docker**
+
+* Set environment variable ``KMS_ICE_TCP`` to 1 (ON) or 0 (OFF).
+
+**Client API**
+
+* Java: `setIceTcp <../../_static/client-javadoc/org/kurento/client/WebRtcEndpoint.html#setIceTcp-boolean->`__.
+* JavaScript: `setIceTcp <../../_static/client-jsdoc/module-elements.WebRtcEndpoint.html#setIceTcp>`__.
+
 
 
 Packet loss correction in Recorder

source/user/configuration.rst

@@ -39,7 +39,7 @@ The :ref:`Kurento Docker <installation-docker>` images also accept some environm
 
 
 
-Debug logging
+Debug Logging
 =============
 
 KMS uses the environment variable ``GST_DEBUG`` to define the debug level of all underlying modules. Check :doc:`/features/logging` for more information about this and other environment variables.
@@ -62,29 +62,9 @@ Set this variable to change the verbosity level of the log messages generated by
 
 
 
-.. _configuration-bitrate:
-
-WebRTC bitrate
-==============
-
-The default **VideoSendBandwidth** range of the WebRtcEndpoint is a VERY conservative one, and leads to a low maximum video quality. Most applications will probably want to increase this to higher values such as 2000 kbps (2 mbps): `Java <../_static/client-javadoc/org/kurento/client/BaseRtpEndpoint.html#setMaxVideoSendBandwidth-int->`__, `JavaScript <../_static/client-jsdoc/module-core_abstracts.BaseRtpEndpoint.html#setMaxVideoSendBandwidth>`__.
-
-Besides that, you have several ways to override the default settings for variable bitrate and network bandwidth detection:
-
-* Methods in `BaseRtpEndpoint <../_static/client-javadoc/org/kurento/client/BaseRtpEndpoint.html>`__:
-
-  - *setMinVideoRecvBandwidth()* / *setMaxVideoRecvBandwidth()*
-  - *setMinVideoSendBandwidth()* / *setMaxVideoSendBandwidth()*
-
-* Methods in `MediaElement <../_static/client-javadoc/org/kurento/client/MediaElement.html>`__:
+.. _configuration-stun-turn:
 
-  - *setMinOutputBitrate()* / *setMaxOutputBitrate()*
-
-    This setting is also configurable in ``/etc/kurento/modules/kurento/MediaElement.conf.ini``.
-
-
-
-STUN/TURN server
+STUN/TURN Server
 ================
 
 Read :ref:`faq-stun-needed` to learn about when you might need to use these, and :ref:`installation-stun-turn` for guidance on how to install your own STUN/TURN server.
@@ -104,7 +84,7 @@ Read :ref:`faq-stun-needed` to learn about when you might need to use these, and
 
 
 
-Network interface
+Network Interface
 =================
 
 To specify the network interface name(s) that KMS should use to communicate from the environment where it is running (either a physical machine, a virtual machine, a Docker container, etc.)
@@ -124,8 +104,30 @@ To specify the network interface name(s) that KMS should use to communicate from
 
 
 
-RTP port
-========
+.. _configuration-bitrate:
+
+WebRTC Bitrate
+==============
+
+The default **VideoSendBandwidth** range of the WebRtcEndpoint is a VERY conservative one, and leads to a low maximum video quality. Most applications will probably want to increase this to higher values such as 2000 kbps (2 mbps): `Java <../_static/client-javadoc/org/kurento/client/BaseRtpEndpoint.html#setMaxVideoSendBandwidth-int->`__, `JavaScript <../_static/client-jsdoc/module-core_abstracts.BaseRtpEndpoint.html#setMaxVideoSendBandwidth>`__.
+
+Besides that, you have several ways to override the default settings for variable bitrate and network bandwidth detection:
+
+* Methods in `BaseRtpEndpoint <../_static/client-javadoc/org/kurento/client/BaseRtpEndpoint.html>`__:
+
+  - *setMinVideoRecvBandwidth()* / *setMaxVideoRecvBandwidth()*
+  - *setMinVideoSendBandwidth()* / *setMaxVideoSendBandwidth()*
+
+* Methods in `MediaElement <../_static/client-javadoc/org/kurento/client/MediaElement.html>`__:
+
+  - *setMinOutputBitrate()* / *setMaxOutputBitrate()*
+
+    This setting is also configurable in ``/etc/kurento/modules/kurento/MediaElement.conf.ini``.
+
+
+
+RTP Ports
+=========
 
 You can configure the minimum and maximum ports that Kurento Media Server will open (bind to) in order to receive RTP packets from remote peers. This affects the operation of both RtpEndpoint and WebRtcEndpoint.
 
@@ -139,14 +141,38 @@ You can configure the minimum and maximum ports that Kurento Media Server will o
 
 
 
-Advanced settings
+Advanced Settings
 =================
 
 These settings are only provided for advanced users who know what they are doing and why they need them. For most cases, it's better to leave these settings on their default values.
 
 
 
-External IP address
+ICE-TCP
+-------
+
+`ICE-TCP <https://tools.ietf.org/html/rfc6544>`__ is what allows WebRTC endpoints to exchange ICE candidates that use the TCP protocol; in other words, the feature of using TCP instead of UDP for WebRTC communications.
+
+If you have a well known scenario and you are 100% sure that UDP will work, then disabling TCP provides slightly faster times when establishing WebRTC sessions. I.e., with ICE-TCP disabled, the time between joining a call and actually seeing the video will be shorter.
+
+Of course, if you cannot guarantee that UDP will work in your network, then **you should leave this setting enabled**, which is the default. Otherwise, UDP might fail and there would be no TCP fallback for WebRTC to work.
+
+**Local install**
+
+* Set value ``iceTcp`` to 1 (ON) or 0 (OFF) in ``/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini``.
+
+**Docker**
+
+* Set environment variable ``KMS_ICE_TCP`` to 1 (ON) or 0 (OFF).
+
+**Client API**
+
+* Java: `setIceTcp <../../_static/client-javadoc/org/kurento/client/WebRtcEndpoint.html#setIceTcp-boolean->`__.
+* JavaScript: `setIceTcp <../../_static/client-jsdoc/module-elements.WebRtcEndpoint.html#setIceTcp>`__.
+
+
+
+External IP Address
 -------------------
 
 When this feature is used, all of the Kurento IPv4 and/or IPv6 ICE candidates are mangled to contain the given address. This can speed up WebRTC connection establishment in scenarios where the external or public IP is already well known, also having the benefit that STUN won't be needed *for the media server*.

source/user/faq.rst

@@ -22,11 +22,10 @@ These are very important concepts that developers must understand well to work w
   - :term:`What is TURN <TURN>`?
   - :ref:`faq-turn-works`
 
-* Installing and configuring a STUN/TURN server:
+* Installing a STUN/TURN server (Coturn):
 
   - :ref:`faq-coturn-install`
   - :ref:`faq-stun-test`
-  - :ref:`faq-stun-configure`
 
 * Troubleshooting :ref:`troubleshooting-webrtc`
 * Advanced knowledge: :doc:`/knowledge/nat`
@@ -106,7 +105,7 @@ Coturn can be installed directly from the Ubuntu package repositories:
 
 To configure it for WebRTC, follow these steps:
 
-1. Edit ``/etc/turnserver.conf``.
+#. Edit ``/etc/turnserver.conf``.
 
    This example configuration is a good baseline; it contains the minimum setup required for using Coturn with Kurento Media Server for WebRTC:
 
@@ -150,13 +149,7 @@ To configure it for WebRTC, follow these steps:
 
    .. note::
 
-      * 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 field *<CoturnIp>*. **It must be an IP address, not a domain name**.
-
-      * This example uses the "*long-term credential*" mechanism of Coturn with a static password, which is good enough for showcasing the setup. You write the desired user name and password in the fields *<TurnUser>* and *<TurnPassword>*, and provide them to KMS as static parameters.
-
-        However, for real-world scenarios you might want to use dynamic passwords. Coturn can be integrated with external sources, such as PostgreSQL (`psql-userdb <https://github.com/coturn/coturn/blob/ae2ee1f4e4f4f4119425e3d890a7f6ca44b57d0b/examples/etc/turnserver.conf#L299>`__), MySQL (`mysql-userdb <https://github.com/coturn/coturn/blob/ae2ee1f4e4f4f4119425e3d890a7f6ca44b57d0b/examples/etc/turnserver.conf#L313>`__), MongoDB (`mongo-userdb <https://github.com/coturn/coturn/blob/ae2ee1f4e4f4f4119425e3d890a7f6ca44b57d0b/examples/etc/turnserver.conf#L331>`__), or Redis (`redis-userdb <https://github.com/coturn/coturn/blob/ae2ee1f4e4f4f4119425e3d890a7f6ca44b57d0b/examples/etc/turnserver.conf#L339>`__). You would handle this from your :doc:`Application Server </user/writing_applications>`, and then use the Kurento API to dynamically provide each individual WebRtcEndpoint with the correct parameters.
-
-        Read :ref:`faq-stun-configure` for info about static and dynamic parameter configuration.
+      * The *external-ip* is necessary in cloud providers that use internal NATs, such as **Amazon EC2** (AWS). Write your server's **public** IP address in the field *<CoturnIp>*. **It must be an IP address, not a domain name**.
 
       * Comment out (or delete) all the TURN parameters if you only want Coturn acting as a STUN server.
 
@@ -166,15 +159,37 @@ To configure it for WebRTC, follow these steps:
         - Fully commented configuration file: https://github.com/coturn/coturn/blob/master/examples/etc/turnserver.conf
         - Additional docs on configuration: https://github.com/coturn/coturn/wiki/CoturnConfig
 
-2. Edit the file ``/etc/default/coturn`` and set
+   .. warning::
+
+      This example configures TURN authentication with the "*long-term credential*" method, where you write a static username and password in the fields *<TurnUser>* and *<TurnPassword>*.
+
+      While that is good enough for showcasing the Coturn setup here, for real-world scenarios you might want to use dynamically-generated passwords. This is more secure, because each individual participant can be provided with an exclusive one-time username and password.
+
+      Coturn can be integrated with external sources, such as PostgreSQL (`psql-userdb <https://github.com/coturn/coturn/blob/4.5.2/examples/etc/turnserver.conf#L299>`__), MySQL (`mysql-userdb <https://github.com/coturn/coturn/blob/4.5.2/examples/etc/turnserver.conf#L313>`__), MongoDB (`mongo-userdb <https://github.com/coturn/coturn/blob/4.5.2/examples/etc/turnserver.conf#L331>`__), or Redis (`redis-userdb <https://github.com/coturn/coturn/blob/4.5.2/examples/etc/turnserver.conf#L339>`__), and it even provides a `REST API <https://tools.ietf.org/html/draft-uberti-behave-turn-rest-00>`__ for time-limited credentials (`use-auth-secret <https://github.com/coturn/coturn/blob/4.5.2/examples/etc/turnserver.conf#L236>`__). You can handle any of these methods from your :doc:`Application Server </user/writing_applications>`, then use the Kurento API to dynamically provide each individual WebRtcEndpoint with the correct parameters.
+
+#. Edit the file ``/etc/default/coturn`` and set
 
    .. code-block:: shell
 
       TURNSERVER_ENABLED=1
 
    so the server starts automatically as a system service daemon.
 
-3. Follow with the next sections to test that Coturn is working, and then set it up as your STUN/TURN server in both Kurento Media Server and the WebRTC clients.
+#. The following ports should be open in your firewall / NAT / cloud provider's *Security Group*:
+
+   * **listening-port** (default: 3478) UDP & TCP. You can skip opening one of the protocols if you disable either UDP or TCP in Coturn (for example, with ``no-tcp``).
+
+   * All the range from **min-port** to **max-port** (default: 49152 to 65535). As per :rfc:`8656`, this is the port range that Coturn will use by default for TURN relay. Again, you can disable either of TCP or UDP (for example, with ``no-tcp-relay``).
+
+   .. note::
+
+      **Port ranges do NOT need to match between Coturn and Kurento Media Server**.
+
+      If you happen to deploy both Coturn and KMS in the same machine, we recommend that their port ranges do not overlap.
+
+#. Configure the STUN or TURN parameters in both Kurento Media Server and all WebRTC clients (like web browsers). Check :ref:`STUN/TURN Server Configuration <configuration-stun-turn>` for ways to configure KMS with these parameters.
+
+#. Check that your Coturn server is working. For that, follow the steps given in the next section.
 
 
 
@@ -211,85 +226,6 @@ To test if your :term:`STUN`/:term:`TURN` server is functioning properly, open t
 
 
 
-.. _faq-stun-configure:
-
-How to configure STUN/TURN in Kurento?
---------------------------------------
-
-To configure a :term:`STUN` server or :term:`TURN` relay with Kurento Media Server, you may use either of two methods:
-
-* **Static config**. If the STUN or TURN parameters are well know and will not change over time, write them into the file ``/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini``.
-
-  To only use STUN server (TURN relay will not be used):
-
-  .. code-block:: text
-
-     stunServerAddress=<StunServerIp>
-     stunServerPort=<StunServerPort>
-
-  *<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:: text
-
-     stunServerAddress=198.51.100.1
-     stunServerPort=3478
-
-  To use both STUN server and TURN relay:
-
-  .. code-block:: text
-
-     turnURL=<TurnUser>:<TurnPassword>@<TurnServerIp>:<TurnServerPort>
-
-  *<TurnServerIp>* should be the public IP address of the TURN relay. **It must be an IP address, not a domain name**. For example:
-
-  .. code-block:: text
-
-     turnURL=myuser:mypassword@198.51.100.1:3478
-
-* **Dynamic config**. If the STUN or TURN parameters are not known beforehand (for example, if your TURN credentials are dynamically generated during run-time), use the Kurento API methods to set them.
-
-  To only use STUN server (TURN relay will not be used):
-
-  .. code-block:: text
-
-     webRtcEndpoint.setStunServerAddress("<StunServerIp>");
-     webRtcEndpoint.setStunServerPort(<StunServerPort>);
-
-  To use both STUN server and TURN relay:
-
-  .. code-block:: text
-
-     webRtcEndpoint.setTurnUrl("<TurnUser>:<TurnPassword>@<TurnServerIp>:<TurnServerPort>");
-
-  Client API:
-
-  * Java: `setStunServerAddress <../_static/client-javadoc/org/kurento/client/WebRtcEndpoint.html#setStunServerAddress-java.lang.String->`__, `setStunServerPort <../_static/client-javadoc/org/kurento/client/WebRtcEndpoint.html#setStunServerPort-int->`__, `setTurnUrl <../_static/client-javadoc/org/kurento/client/WebRtcEndpoint.html#setTurnUrl-java.lang.String->`__.
-  * JavaScript: `setStunServerAddress <../_static/client-jsdoc/module-elements.WebRtcEndpoint.html#setStunServerAddress>`__, `setStunServerPort <../_static/client-jsdoc/module-elements.WebRtcEndpoint.html#setStunServerPort>`__, `setTurnUrl <../_static/client-jsdoc/module-elements.WebRtcEndpoint.html#setTurnUrl>`__.
-
-.. note::
-
-   **You don't need to configure both STUN and TURN**, because TURN already includes STUN functionality.
-
-The following ports should be open in the firewall or your cloud provider *Security Group*:
-
-- **<CoturnPort>** (Default: 3478) UDP & TCP, unless you disable either UDP or TCP in Coturn (for example, with ``no-tcp``).
-- **49152 to 65535** UDP & TCP: As per :rfc:`8656`, this port range will be used by a TURN relay to exchange media by default. These ports can be changed using Coturn's ``min-port`` and ``max-port`` settings. Again, you can disable using either TCP or UDP for the relay port range (for example, with ``no-tcp-relay``).
-
-.. note::
-
-   **Port ranges do NOT need to match between Coturn and Kurento Media Server**.
-
-   If you happen to deploy both Coturn and KMS in the same machine, we recommend that their port ranges do not overlap.
-
-When you are done, (re)start both Coturn and Kurento servers:
-
-.. code-block:: shell
-
-   sudo service coturn restart
-   sudo service kurento-media-server restart
-
-
-
 .. _faq-docker:
 
 About using Kurento with Docker
@@ -419,8 +355,8 @@ The Kurento API offers no way to get application-level semantic attributes store
 
 
 
-How to retrieve known objects from the Media Server?
-----------------------------------------------------
+How to get existing objects from the Media Server?
+--------------------------------------------------
 
 The usual workflow for an Application Server is to connect with the Media Server, and use RPC methods to *create* new MediaPipelines and Endpoints inside it. However, if you want to connect your Application Server with objects that *already exist* in the Media Server (as opposed to creating new ones), you can achieve it by querying by their ID. This is done with the "*describe*" method of the JSON-RPC API, as described in :doc:`/features/kurento_protocol`.
 

source/user/installation.rst

@@ -270,9 +270,9 @@ Kurento Media Server, just like any WebRTC endpoint, will work fine on its own,
 
 These links contain the information needed to finish configuring your Kurento Media Server with a STUN/TURN server:
 
+- :doc:`/user/configuration`
 - :ref:`faq-coturn-install`
 - :ref:`faq-stun-test`
-- :ref:`faq-stun-configure`
 
 
 

source/user/troubleshooting.rst

@@ -573,7 +573,7 @@ There is a multitude of possible reasons for a failed WebRTC connection, so you
 
 * Test if your :term:`STUN`/:term:`TURN` server is working correctly: :ref:`faq-stun-test`.
 
-* Configure your :term:`STUN`/:term:`TURN` server in Kurento Media Server: :ref:`faq-stun-configure`.
+* Configure your :term:`STUN`/:term:`TURN` server in Kurento Media Server: :ref:`configuration-stun-turn`.
 
 * 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.