TCP is a connection oriented transport, so the :ref:`dds_layer_domainParticipant` must establish a TCP connection to the remote peer before sending data messages. Therefore, one of the communicating DomainParticipants (the one acting as server) must open a TCP port listening for incoming connections, and the other one (the one acting as client) must connect to this port.
Note
The server and client concepts are independent from the DDS concepts of :ref:`dds_layer_publisher`, :ref:`dds_layer_subscriber`, :ref:`dds_layer_publisher_dataWriter`, and :ref:`dds_layer_subscriber_dataReader`. Also, these concepts are independent from the eProsima Discovery Server servers and clients (:ref:`discovery_server`). Any of them can act as a TCP Server or TCP Client when establishing the connection, and the DDS communication will work over this connection.
Warning
This documentation assumes the reader has basic knowledge of TCP/IP concepts, since terms like Time To Live (TTL), Cyclic Redundancy Check (CRC), Transport Layer Security (TLS), socket buffers, and port numbering are not explained in detail. However, it is possible to configure a basic TCP transport on Fast DDS without this knowledge.
eProsima Fast DDS implements TCP transport for both TCPv4 and TCPv6. Each of these transports is independent from the other, and has its own |TransportDescriptorInterface-api|. However, they share many of their features, and most of the |TransportDescriptorInterface-api| data members are common.
The following table describes the common data members for both TCPv4 and TCPv6.
Member | Data type | Default | Description |
---|---|---|---|
|SocketTransportDescriptor::sendBufferSize-api| | uint32_t |
0 | Size of the sending buffer of the socket (octets). |
|SocketTransportDescriptor::receiveBufferSize-api| | uint32_t |
0 | Size of the receiving buffer of the socket (octets). |
|SocketTransportDescriptor::interfaceWhiteList-api| | vector<string> |
Empty vector | List of allowed interfaces See |InterfaceWhitelist|. |
|SocketTransportDescriptor::TTL-api| | uint8_t |
1 | Time to live, in number of hops. |
|TCPTransportDescriptor::listening_ports-api| | vector<uint16_t> |
Empty vector | List of ports to listen as server. If a port is set to 0, an available port will be automatically assigned. |
|TCPTransportDescriptor::keep_alive_frequency_ms-api| | uint32_t |
5000 | Frequency of RTCP keep alive requests (in ms). |
|TCPTransportDescriptor::keep_alive_timeout_ms-api| | uint32_t |
15000 | Time since sending the last keep alive request to consider a connection as broken (in ms). |
|TCPTransportDescriptor::max_logical_port-api| | uint16_t |
100 | Maximum number of logical ports to try during RTCP negotiation. |
|TCPTransportDescriptor::logical_port_range-api| | uint16_t |
20 | Maximum number of logical ports per request to try during RTCP negotiation. |
|TCPTransportDescriptor::logical_port_increment-api| | uint16_t |
2 | Increment between logical ports to try during RTCP negotiation. |
|TCPTransportDescriptor::enable_tcp_nodelay-api| | bool |
false |
Enables the TCP_NODELAY socket option. |
|TCPTransportDescriptor::calculate_crc-api| | bool |
true |
True to calculate and send CRC on message headers. |
|TCPTransportDescriptor::check_crc-api| | bool |
true |
True to check the CRC of incoming message headers. |
|TCPTransportDescriptor::apply_security-api| | bool |
false |
True to use TLS. See |TLSconfig|. |
|TCPTransportDescriptor::tls_config-api| | |TCPTransportDescriptor::TLSConfig-api| | Configuration for TLS. See |TLSconfig|. |
Note
If |TCPTransportDescriptor::listening_ports-api| is left empty, the participant will not be able to receive incoming connections but will be able to connect to other participants that have configured their listening ports.
The following table describes the data members that are exclusive for |TCPv4TransportDescriptor-api|.
Member | Data type | Default | Description |
---|---|---|---|
|TCPv4TransportDescriptor::wan_addr-api| | octet[4] |
[0, 0, 0, 0] | Configuration for WAN. See |WANconfig|. |
Note
The |TransportInterface::kind-api| value for a |TCPv4TransportDescriptor-api| is given by the value |LOCATOR_KIND_TCPv4-api|.
|TCPv6TransportDescriptor-api| has no additional data members from the common ones described in :ref:`transport_tcp_transportDescriptor`.
Note
The |TransportInterface::kind-api| value for a |TCPv6TransportDescriptor-api| is given by the value |LOCATOR_KIND_TCPv6-api|.
There are several ways of enabling TCP transport in eprosima Fast DDS. According to the facet of each scenario, one method might suit better than the others.
The first option is to modify the builtin transports that are responsible of the creation of the DomainParticipant
transports. The existing configuration that enables TCP transports is LARGE_DATA
.
This option instantiates a UDPv4, a TCPv4 and a SHM transport, respectively. UDP protocol will be used for multicast
announcements during the participant discovery phase (see :ref:`disc_phases`) while the participant liveliness and
the application data delivery occurs over TCP or SHM. This configuration enables auto discovery and does not
require to manually set up each participant IP and listening port. Hence, avoiding the typical Server-Client
configuration.
Builtin Transports can be configured using the FASTDDS_BUILTIN_TRANSPORTS
environment variable (see
:ref:`env_vars_builtin_transports`), XML profiles (see :ref:`RTPS`) or via code.
.. tabs:: .. tab:: Environment Variable .. code-block:: bash export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA .. tab:: XML .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: <!-->LARGE_DATA_BUILTIN_TRANSPORTS<--> :end-before: <!--><--> :lines: 2-4, 6-13, 15-16 .. tab:: C++ .. literalinclude:: /../code/DDSCodeTester.cpp :language: c++ :start-after: //CONF-TCP-TRANSPORT-BUILTIN-TRANSPORT :end-before: //!-- :dedent: 8
Note
Note that LARGE_DATA
configuration of the builtin transports will also create a SHM transport along the UDP
and TCP transports. Shared Memory will be used whenever it is possible. Manual configuration will be required
if a TCP communication is required when SHM is feasible. (See :ref:`use-case-tcp-multicast`).
To set up a Server-Client configuration you need to create an instance of :ref:`transport_tcp_v4transportDescriptor` (for TCPv4) or :ref:`transport_tcp_v6transportDescriptor` (for TCPv6), and add it to the user transport list of the DomainParticipant.
Depending on the TCP transport descriptor settings and network locators defined, the DomainParticipant can act as a TCP Server or TCP Client.
TCP Server: If you provide |TCPTransportDescriptor::listening_ports-api| on the descriptor, the DomainParticipant will act as TCP server, listening for incoming remote connections on the given ports. The examples below show this procedure in both C++ code and XML file.
.. tabs:: .. tab:: C++ .. literalinclude:: /../code/DDSCodeTester.cpp :language: c++ :start-after: //CONF-TCP-TRANSPORT-SETTING-SERVER :end-before: //!-- :dedent: 8 .. tab:: XML .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: <!-->CONF-TCP-TRANSPORT-SETTING-SERVER :end-before: <!--><--> :lines: 2-3,5- :append: </profiles>
TCP Client: If you provide |BuiltinAttributes::initialPeersList-api| to the DomainParticipant, it will act as TCP client, trying to connect to the remote servers at the given addresses and ports. The examples below show this procedure in both C++ code and XML file. See :ref:`Simple Initial Peers` for more information about their configuration.
.. tabs:: .. tab:: C++ .. literalinclude:: /../code/DDSCodeTester.cpp :language: c++ :start-after: //CONF-TCP-TRANSPORT-SETTING-CLIENT :end-before: //!-- :dedent: 8 .. tab:: XML .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: <!-->CONF-TCP-TRANSPORT-SETTING-CLIENT :end-before: <!--><--> :lines: 2-3,5- :append: </profiles>
Note
Manually setting unicast locators is optional. If not setting them or setting them with a logical
port of 0
, the client's initial peer shouldn't set its logical port (or set it to 0
). Otherwise,
initial peer's logical port must match server's unicast logical port.
:ref:`transport_tcp_example` shows how to use and configure a TCP transport.
Fast DDS is able to connect through the Internet or other WAN networks when configured properly. To achieve this kind of scenarios, the involved network devices such as routers and firewalls must add the rules to allow the communication.
For example, imagine we have the scenario represented on the following figure:
- A DomainParticipant acts as a TCP server listening on port
5100
and is connected to the WAN through a router with public IP80.80.99.45
. - Another DomainParticipant acts as a TCP client and has configured the server's IP address and port in its :ref:`Simple Initial Peers` list.
By using set_WAN_address(wan_ip)
, the WAN IP address is set on the participant's locators that
are communicated during the discovery phase.
Like in the LAN case, manually setting unicast locators is optional. However, in this case, there are some considerations to take into account when setting its IP addresses:
- Setting the WAN IP address using the
setWAN()
method in unicast locators is ineffective because it gets overridden by theset_WAN_address()
call. - For assigning IP addresses to unicast locators, use only the
setIPv4()
orsetIPv6()
methods, which are LAN IP setters. There are some configurations which allow using these setters with a WAN IP address.
Depending on whether the server has manually set its metatraffic unicast locators and default unicast locators, the client needs to adjust its initial peer list accordingly:
- If the server's unicast locators are configured with the LAN IP address:
- The initial peer can be set up with only the server's WAN IP using the LAN IP setter.
- Alternatively, it can be configured with both the server's LAN and WAN IP addresses using the LAN setter for the LAN IP and the WAN setter for the WAN IP.
- If the server's unicast locators are configured with the WAN IP address:
- The initial peer must be set up with only the server's WAN IP using the LAN setter.
- Alternatively, it can be configured with the WAN IP address using both the LAN and WAN setters.
- If the server has not set any unicast locators:
- The initial peer can be configured with only the server's WAN IP using the LAN setter.
- Alternatively, it can be configured with both the server's LAN and WAN IP addresses using the LAN setter for the LAN IP and the WAN setter for the WAN IP.
Note
Manually setting unicast locators is optional. If not setting them or setting them with a logical
port of 0
, the client's initial peer shouldn't set its logical port (or set it to 0
). Otherwise,
initial peer's logical port must match server's unicast logical port.
On the server side, the router must be configured to forward to the TCP server
all traffic incoming to port 5100
. Typically, a NAT routing of port 5100
to our
machine is enough. Any existing firewall should be configured as well.
In addition, to allow incoming connections through a WAN, the :ref:`transport_tcp_v4transportDescriptor` must indicate its public IP address in the |TCPv4TransportDescriptor::wan_addr-api| data member. The following examples show how to configure the DomainParticipant both in C++ and XML.
.. tabs:: .. tab:: C++ .. literalinclude:: /../code/DDSCodeTester.cpp :language: c++ :start-after: //CONF-TCP-TRANSPORT-SETTING-WAN-SERVER :end-before: //!-- :dedent: 8 .. tab:: XML .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: <!-->CONF-TCP-TRANSPORT-SETTING-WAN-SERVER :end-before: <!--><--> :lines: 2-3,5- :append: </profiles>
On the client side, the DomainParticipant must be configured with the public IP address and |TCPTransportDescriptor::listening_ports-api| of the TCP server as :ref:`Simple Initial Peers`.
.. tabs:: .. tab:: C++ .. literalinclude:: /../code/DDSCodeTester.cpp :language: c++ :start-after: //CONF-TCP-TRANSPORT-SETTING-WAN-CLIENT :end-before: //!-- :dedent: 8 .. tab:: XML .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: <!-->CONF-TCP-TRANSPORT-SETTING-WAN-CLIENT :end-before: <!--><--> :lines: 2-3,5- :append: </profiles>
A TCP version of helloworld example can be found in the HelloWorldExampleTCP folder. It shows a publisher and a subscriber that communicate through TCP. The publisher is configured as TCP server while the Subscriber is acting as TCP client.