6.11. Interfaces configuration
By default, Fast DDS makes use of all active network interfaces found in the system to communicate (note: applies to UDP Transport and TCP Transport). However, it is possible for a user to indicate a specific set of network interfaces to be used by the library, and/or configure some of them in a specific manner.
6.11.1. Netmask filtering
The standard behaviour in Fast-DDS is to attempt data transmission to any remote locator for which a compatible transport (based on kind) is registered. This may result in a non-optimum resource utilization, as messages could be sent from an interface to an unreachable destination given a particular network architecture. In this situation, a user may decide to enable the netmask filtering feature, which would prevent this behavior by only sending data from a network interface to remote locators within the same subnetwork.
This configuration option can be set at participant, transport and interface levels, and its possible values are:
Value |
Description |
---|---|
|
Enable netmask filtering. |
|
Disable netmask filtering. |
|
Use container’s netmask filter configuration. |
An AUTO
netmask filter configuration means that its effective value will be given by that of
its “container”, which in the case of an allowlist entry would be the
transport descriptor where it is included, and in the case of a transport descriptor
would be the participant where it is registered.
However not all configurations are valid; this is, for example, a transport’s netmask filter configuration cannot
be OFF
if it is ON
for the participant where this transport
is registered.
Likewise, the netmask filter configuration for an allowlist entry cannot be ON
if it is
OFF
for the transport descriptor where this allowlist is defined.
Note
Due to implementation details, it is required to set ignore_non_matching_locators to true (see Matching algorithm) both in participants and endpoints when enabling the netmask filtering feature at participant or transport level without defining an allowlist or blocklist.
Additional considerations need to be taken into account when using netmask filtering in combination with external locators. In particular, it is not possible to enable netmask filtering in all entries of an allowlist when a set of local external locators (with an externality greater than 0) is defined for a participant or endpoint. The reason for this is that a matching remote external locator would then (most likely) be effectively ignored, as no network interface would be able to reach it according to its network mask.
Netmask filtering can be enabled at participant level both via C++ API or XML configuration:
// Configure netmask filtering at participant level
qos.transport().netmask_filter = NetmaskFilterKind::AUTO;
qos.wire_protocol().ignore_non_matching_locators = true; // Required if not defining an allowlist or blocklist
<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
<participant profile_name="CustomTcpParticipantNetmaskFilterParticipant">
<rtps>
<ignore_non_matching_locators>true</ignore_non_matching_locators>
<netmask_filter>ON</netmask_filter>
</rtps>
</participant>
</profiles>
For socket (UDP/TCP) transport descriptors:
// Create a descriptor for the new transport.
auto udp_transport = std::make_shared<UDPv4TransportDescriptor>();
// Configure netmask filtering at transport level
udp_transport->netmask_filter = NetmaskFilterKind::AUTO;
qos.wire_protocol().ignore_non_matching_locators = true; // Required if not defining an allowlist or blocklist
<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
<transport_descriptors>
<transport_descriptor>
<transport_id>CustomTcpTransportNetmaskFilter</transport_id>
<type>TCPv4</type>
<netmask_filter>ON</netmask_filter>
</transport_descriptor>
</transport_descriptors>
<participant profile_name="CustomTcpTransportNetmaskFilterParticipant">
<rtps>
<useBuiltinTransports>false</useBuiltinTransports>
<userTransports>
<transport_id>CustomTcpTransportNetmaskFilter</transport_id>
</userTransports>
<ignore_non_matching_locators>true</ignore_non_matching_locators>
</rtps>
</participant>
</profiles>
See Allowlist to learn how to configure netmask filtering for specific network devices.
6.11.2. Allowlist
Using Fast DDS, it is possible to limit the network interfaces used by TCP Transport
and UDP Transport.
This is achieved by adding the interfaces to the allowlist
field in the
TCPTransportDescriptor or UDPTransportDescriptor.
Thus, the communication interfaces used by the DomainParticipants whose TransportDescriptorInterface
defines an
allowlist
is limited to the interfaces defined in that list, therefore
avoiding the use of the rest of the network interfaces available in the system.
The interfaces in allowlist
can be specified both by IP address
or interface name.
Additionally, each entry added to the allowlist may specify a netmask filter
configuration value (AUTO
by default).
For example:
DomainParticipantQos qos;
// Create a descriptor for the new transport.
auto udp_transport = std::make_shared<UDPv4TransportDescriptor>();
// Add allowed interface by device name
udp_transport->interface_allowlist.emplace_back("eth0", NetmaskFilterKind::OFF);
// Add allowed interface by IP address (using default netmask filter AUTO)
udp_transport->interface_allowlist.emplace_back("127.0.0.1");
// Add allowed interface with explicit AllowedNetworkInterface construction
AllowedNetworkInterface another_allowed_interface("docker0", NetmaskFilterKind::OFF);
udp_transport->interface_allowlist.emplace_back(another_allowed_interface);
// Link the Transport Layer to the Participant.
qos.transport().user_transports.push_back(udp_transport);
// Avoid using the builtin transports
qos.transport().use_builtin_transports = false;
<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
<transport_descriptors>
<transport_descriptor>
<transport_id>CustomTcpTransportAllowlist</transport_id>
<type>TCPv4</type>
<interfaces>
<allowlist>
<interface name="wlp59s0" netmask_filter="ON"/>
<interface name="192.168.1.10" netmask_filter="OFF"/>
</allowlist>
</interfaces>
</transport_descriptor>
</transport_descriptors>
<participant profile_name="CustomTcpTransportAllowlistParticipant">
<rtps>
<useBuiltinTransports>false</useBuiltinTransports>
<userTransports>
<transport_id>CustomTcpTransportAllowlist</transport_id>
</userTransports>
</rtps>
</participant>
</profiles>
Important
If none of the values in the transport descriptor’s allowlist match the interfaces on the host, then all the interfaces in the allowlist are filtered out and therefore no communication will be established through that transport.
6.11.3. Blocklist
Apart from defining a list of allowed interfaces, it is also possible to define a list of
interfaces that should be blocked.
This is accomplished through the blocklist
field present in the
TCPTransportDescriptor or UDPTransportDescriptor.
Note
This list takes precedence over the allowlist, so if a network interface is in both lists, it will be blocked.
The interfaces in blocklist
can be specified both by IP address
or interface name.
For example:
DomainParticipantQos qos;
// Create a descriptor for the new transport.
auto udp_transport = std::make_shared<UDPv4TransportDescriptor>();
// Add blocked interface by device name
udp_transport->interface_blocklist.emplace_back("docker0");
// Add blocked interface by IP address
udp_transport->interface_blocklist.emplace_back("127.0.0.1");
// Add blocked interface with explicit BlockedNetworkInterface construction
BlockedNetworkInterface another_blocked_interface("eth0");
udp_transport->interface_blocklist.emplace_back(another_blocked_interface);
// Link the Transport Layer to the Participant.
qos.transport().user_transports.push_back(udp_transport);
// Avoid using the builtin transports
qos.transport().use_builtin_transports = false;
<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
<transport_descriptors>
<transport_descriptor>
<transport_id>CustomTcpTransportBlocklist</transport_id>
<type>TCPv4</type>
<interfaces>
<blocklist>
<interface name="127.0.0.1"/>
<interface name="docker0"/>
</blocklist>
</interfaces>
</transport_descriptor>
</transport_descriptors>
<participant profile_name="CustomTcpTransportBlocklistParticipant">
<rtps>
<useBuiltinTransports>false</useBuiltinTransports>
<userTransports>
<transport_id>CustomTcpTransportBlocklist</transport_id>
</userTransports>
</rtps>
</participant>
</profiles>