10.7. Transport descriptors

This section defines the XML elements available for configuring the transport layer parameters in Fast DDS. These elements are defined within the XML tag <transports_descriptors>. The <transport_descriptors> can contain one or more <transport_descriptor> XML elements. Each <transport_descriptor> element defines a configuration for a specific type of transport protocol. Each of these <transport_descriptor> elements are uniquely identified by a transport ID with the <transport_id> XML tag. Once the user defines a valid <transports_descriptor>, i.e. defines the transport layer parameters, these can be loaded into the XML profile of the DomainParticipant using the <transport_id> XML tag. An example of how to load the <transport_descriptor> into the XML profile of the DomainParticipant is found in DomainParticipant profiles.

The following table lists all the available XML elements that can be defined within the <transport_descriptor> element for the configuration of the transport layer. A more detailed explanation of each of these elements can be found in Transport Layer.

Name

Description

Values

Default

<transport_id>

Unique name to identify each transport descriptor.

string

<type>

Type of the transport descriptor.

UDPv4

UDPv4

UDPv6

TCPv4

TCPv6

SHM

<sendBufferSize>

Size in bytes of the send socket buffer.
If the value is zero then Fast DDS will use
the system default socket size.

uint32_t

0

<receiveBufferSize>

Size in bytes of the reception socket
buffer. If the value is zero then Fast DDS
will use the system default socket size.

uint32_t

0

<maxMessageSize>

The maximum size in bytes of the transport’s
message buffer.

uint32_t

65500

<maxInitialPeersRange>

Number of channels opened with each initial
remote peer.

uint32_t

4

<netmask_filter>

Transport’s Netmask filtering
configuration.

OFF

AUTO

AUTO

ON

<interfaces>

Allows defining an Interfaces configuration.

Interfaces configuration

<interfaceWhiteList>

Allows defining an interfaces Whitelist.

Whitelist

<TTL>

Time To Live (UDP only). See
UDP Transport.

uint8_t

1

<non_blocking_send>

Whether to set the non-blocking send mode on
the socket (NOT available for SHM type). See
UDPTransportDescriptor and
TCPTransportDescriptor.

bool

false

<output_port>

Port used for output bound.
If this field isn’t defined, the output port
will be random (UDP only).

uint16_t

0

<wan_addr>

Public WAN address when using TCPv4
transports. This field is optional if the
transport doesn’t need to define a WAN
address (TCPv4 only).

IPv4 formatted
string:
XXX.XXX.XXX.XXX

<keep_alive_frequency_ms>

Frequency in milliseconds for sending RTCP
keep-alive requests (TCP only).

uint32_t

50000

<keep_alive_timeout_ms>

Time in milliseconds since the last
keep-alive request was sent to consider a
connection as broken (TCP only).

uint32_t

10000

<max_logical_port>

The maximum number of logical ports to try
during RTCP negotiations (TCP only).

uint16_t

100

<logical_port_range>

The maximum number of logical ports per
request to try during RTCP negotiations
(TCP only).

uint16_t

20

<logical_port_increment>

Increment between logical ports to try during
RTCP negotiation
(TCP only).

uint16_t

2

<listening_ports>

Local port to work as TCP acceptor for input
connections. If not set, the transport will
work as TCP client only. If set to 0, an
available port will be automatically assigned
(TCP only).

List <uint16_t>

<tls>

Allows to define TLS related parameters and
options (TCP only).

TLS Configuration

<calculate_crc>

Calculates the Cyclic Redundancy Code (CRC)
for error control (TCP only).

bool

true

<check_crc>

Check the CRC for error control (TCP
only).

bool

true

<enable_tcp_nodelay>

Socket option for disabling the Nagle
algorithm. (TCP only).

bool

false

<tcp_negotiation_timeout>

Time to wait for logical port negotiation (in ms)
(TCP only).

uint32_t

0

<segment_size>

Size (in bytes) of the shared-memory segment.
(Optional, SHM only).

uint32_t

262144

<port_queue_capacity>

Capacity (in number of messages) available to
every Listener (Optional, SHM only).

uint32_t

512

<healthy_check_timeout_ms>

Maximum time-out (in milliseconds) used when
checking whether a Listener is alive
(Optional, SHM only).

uint32_t

1000

<rtps_dump_file>

Complete path (including file) where RTPS
messages will be stored for debugging
purposes. An empty string indicates no trace
will be performed (Optional, SHM only).

string

Empty

The following XML code shows an example of transport protocol configuration using all configurable parameters. More examples of transports descriptors can be found in the Transport Layer section.

<?xml version="1.0" encoding="UTF-8" ?>
<dds xmlns="http://www.eprosima.com">
    <profiles>
        <transport_descriptors>
            <transport_descriptor>
                <transport_id>my_udpv4_transport</transport_id>
                <type>UDPv4</type>
                <sendBufferSize>8192</sendBufferSize>
                <receiveBufferSize>8192</receiveBufferSize>
                <maxMessageSize>16384</maxMessageSize>
                <maxInitialPeersRange>100</maxInitialPeersRange>
                <netmask_filter>AUTO</netmask_filter>
                <interfaces>
                    <allowlist>
                        <interface name="wlp59s0" netmask_filter="ON"/>
                    </allowlist>
                    <blocklist>
                        <interface name="127.0.0.1"/>
                        <interface name="docker0"/>
                    </blocklist>
                </interfaces>
                <interfaceWhiteList>
                    <address>192.168.1.41</address>
                    <interface>lo</interface>
                </interfaceWhiteList>
                <TTL>250</TTL>
                <non_blocking_send>false</non_blocking_send>
                <output_port>5101</output_port>
                <wan_addr>80.80.55.44</wan_addr>
                <keep_alive_frequency_ms>5000</keep_alive_frequency_ms>
                <keep_alive_timeout_ms>25000</keep_alive_timeout_ms>
                <max_logical_port>9000</max_logical_port>
                <logical_port_range>100</logical_port_range>
                <logical_port_increment>2</logical_port_increment>
                <listening_ports>
                    <port>5100</port>
                    <port>5200</port>
                </listening_ports>
                <tls><!-- TLS Section --></tls>
                <calculate_crc>false</calculate_crc>
                <check_crc>false</check_crc>
                <enable_tcp_nodelay>false</enable_tcp_nodelay>
                <segment_size>262144</segment_size>
                <port_queue_capacity>512</port_queue_capacity>
                <healthy_check_timeout_ms>1000</healthy_check_timeout_ms>
                <rtps_dump_file>rtsp_messages.log</rtps_dump_file>
            </transport_descriptor>
        </transport_descriptors>
    </profiles>
</dds>

Note

The Real-time Transport Control Protocol (RTCP) is the control protocol for communications with RTPS over TCP/IP connections.

10.7.1. TLS Configuration

Fast DDS provides mechanisms to configure the Transport Layer Security (TLS) protocol parameters through the <tls> XML element of its <transport_descriptor>. Please, refer to TLS over TCP for a detailed explanation of the entire TLS configuration in Fast DDS. More information on how to set up secure communication in Fast DDS can be found in the Security section.

Warning

For the full understanding of this section, a basic knowledge of network security in terms of SSL/TLS, Certificate Authority (CA), Public Key Infrastructure (PKI), and Diffie-Hellman is required; encryption protocols are not explained in detail.

The full list of available XML elements that can be defined within the <tls> element to configure the TLS protocol are listed in the following table:

Name

Description

Values

Default

<password>

Password of the <private_key_file> or
<rsa_private_key_file> if provided.

string

<private_key_file>

Path to the private key certificate file.

string

<rsa_private_key_file>

Path to the private key RSA certificate file.

string

<cert_chain_file>

Path to the public certificate chain file.

string

<tmp_dh_file>

Path to the Diffie-Hellman parameters file

string

<verify_file>

Path to the Certification Authority (CA) file.

string

<verify_mode>

Establishes the verification mode mask. Several
verification options can be combined in the same
<transport_descriptor>.

VERIFY_NONE

VERIFY_PEER

VERIFY_FAIL_IF_NO_PEER_CERT

VERIFY_CLIENT_ONCE

<options>

Establishes the SSL Context options mask. Several
options can be combined in the same
<transport_descriptor>.

DEFAULT_WORKAROUNDS

NO_COMPRESSION

NO_SSLV2

NO_SSLV3

NO_TLSV1

NO_TLSV1_1

NO_TLSV1_2

NO_TLSV1_3

SINGLE_DH_USE

<verify_paths>

Paths where the system will look for verification
files.

List <string>

<verify_depth>

Maximum allowed depth to verify intermediate
certificates.

uint32_t

<default_verify_path>

Specifies whether the system will look on the
default paths for the verification files.

bool

false

<handshake_role>

Role that the transport will take on handshaking.
On default, the acceptors act as SERVER and the
connectors as CLIENT.

DEFAULT

DEFAULT

SERVER

CLIENT

<server_name>

server name or host name required in case Server Name Indication (SNI) is used.

string

An example of TLS protocol parameter configuration is shown below.

<?xml version="1.0" encoding="UTF-8" ?>
<dds xmlns="http://www.eprosima.com">
    <profiles>
        <transport_descriptors>
            <transport_descriptor>
                <transport_id>Test</transport_id>
                <type>TCPv4</type>
                <tls>
                    <password>Password</password>
                    <private_key_file>Key_file.pem</private_key_file>
                    <rsa_private_key_file>RSA_file.pem</rsa_private_key_file>
                    <cert_chain_file>Chain.pem</cert_chain_file>
                    <tmp_dh_file>DH.pem</tmp_dh_file>
                    <verify_file>verify.pem</verify_file>
                    <verify_mode>
                        <verify>VERIFY_PEER</verify>
                    </verify_mode>
                    <options>
                        <option>NO_TLSV1</option>
                        <option>NO_TLSV1_1</option>
                    </options>
                    <verify_paths>
                        <verify_path>Path1</verify_path>
                        <verify_path>Path2</verify_path>
                        <verify_path>Path3</verify_path>
                    </verify_paths>
                    <verify_depth>55</verify_depth>
                    <default_verify_path>true</default_verify_path>
                    <handshake_role>SERVER</handshake_role>
                    <server_name>my_server.com</server_name>
                </tls>
            </transport_descriptor>
<!-->
    </profiles>