Warning

The configuration options described in this section apply to network interfaces. Therefore, it is only available on TCP Transport and UDP Transport.

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
ON	Enable netmask filtering.
OFF	Disable netmask filtering.
AUTO	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:

C++XML

// 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

For socket (UDP/TCP) transport descriptors:

C++XML

// 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

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:

C++XML

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;

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:

C++XML

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;