diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index 32894cbdf..13eef2ecc 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -34,6 +34,9 @@ #include #include #include +#include +#include +#include #include #include #include @@ -4909,6 +4912,85 @@ void dds_transport_examples () //!-- } + { + using namespace eprosima::fastdds::rtps; + //CONF-NETMASK-FILTER + DomainParticipantQos qos; + + // 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 + + // Create a descriptor for the new transport. + auto udp_transport = std::make_shared(); + + // 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 + + // Configure netmask filtering at interface level + udp_transport->interface_allowlist.emplace_back("wlp59s0", NetmaskFilterKind::ON); + + // 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; + //!-- + } + + { + using namespace eprosima::fastdds::rtps; + //CONF-INTERFACES-ALLOWLIST + DomainParticipantQos qos; + + // Create a descriptor for the new transport. + auto udp_transport = std::make_shared(); + + // 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; + //!-- + } + + { + using namespace eprosima::fastdds::rtps; + //CONF-INTERFACES-BLOCKLIST + DomainParticipantQos qos; + + // Create a descriptor for the new transport. + auto udp_transport = std::make_shared(); + + // 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; + //!-- + } + { //CONF-DISABLE-MULTICAST DomainParticipantQos qos; diff --git a/code/XMLTester.xml b/code/XMLTester.xml index 6a58318b9..73b857ecd 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -1004,6 +1004,99 @@ <--> +PARTICIPANT-NETMASK-FILTER<--> + + + + true + ON + + +<--> + +TRANSPORT-NETMASK-FILTER<--> + + + + CustomTcpTransportNetmaskFilter + TCPv4 + ON + + + + + + false + + CustomTcpTransportNetmaskFilter + + true + + +<--> + +INTERFACES-ALLOWLIST<--> + + + + CustomTcpTransportAllowlist + TCPv4 + + + + + + + + + + + + false + + CustomTcpTransportAllowlist + + + +<--> + +INTERFACES-BLOCKLIST<--> + + + + CustomTcpTransportBlocklist + TCPv4 + + + + + + + + + + + + false + + CustomTcpTransportBlocklist + + + +<--> + CONF-TRANSPORT_METAMULTICASTLOCATOR<--> @@ -3803,9 +3899,19 @@ 8192 16384 100 + AUTO + + + + + + + + +
192.168.1.41
-
127.0.0.1
+ lo 250 false diff --git a/code/XMLTesterExample.xml b/code/XMLTesterExample.xml index 873147025..4e5f873c9 100644 --- a/code/XMLTesterExample.xml +++ b/code/XMLTesterExample.xml @@ -10,9 +10,19 @@ 8192 16384 100 + AUTO + + + + + + + + +
192.168.1.41
-
127.0.0.1
+ lo 80.80.55.44 5000 @@ -212,6 +222,7 @@ true 8192 8192 + AUTO diff --git a/docs/03-exports/aliases-api.include b/docs/03-exports/aliases-api.include index 19eb546be..6999c6d18 100644 --- a/docs/03-exports/aliases-api.include +++ b/docs/03-exports/aliases-api.include @@ -612,6 +612,15 @@ .. |SocketTransportDescriptor::interfaceWhiteList-api| replace:: :cpp:var:`interfaceWhiteList` .. |SocketTransportDescriptor::TTL-api| replace:: :cpp:var:`TTL` +.. |NetmaskFilterKind-api| replace:: :cpp:enum:`NetmaskFilterKind` +.. |NetmaskFilterKind::ON-api| replace:: :cpp:enumerator:`ON` +.. |NetmaskFilterKind::OFF-api| replace:: :cpp:enumerator:`OFF` +.. |NetmaskFilterKind::AUTO-api| replace:: :cpp:enumerator:`AUTO` +.. |SocketTransportDescriptor::netmask_filter-api| replace:: :cpp:var:`netmask_filter` +.. |SocketTransportDescriptor::interface_allowlist-api| replace:: :cpp:var:`allowlist` +.. |SocketTransportDescriptor::interface_blocklist-api| replace:: :cpp:var:`blocklist` + + .. |UDPTransportDescriptor::m_output_udp_socket-api| replace:: :cpp:var:`m_output_udp_socket` .. |UDPTransportDescriptor::non_blocking_send-api| replace:: :cpp:var:`non_blocking_send` .. |UDPv4TransportDescriptor-api| replace:: :cpp:struct:`UDPv4TransportDescriptor` diff --git a/docs/fastdds/api_reference/spelling_wordlist.txt b/docs/fastdds/api_reference/spelling_wordlist.txt index 4821e7391..13464258e 100644 --- a/docs/fastdds/api_reference/spelling_wordlist.txt +++ b/docs/fastdds/api_reference/spelling_wordlist.txt @@ -3,11 +3,13 @@ ACKs addReaderLocator addReaderProxy addWriterProxy +allowlist assignability autodispose autoenable autopurge behaviour +blocklist booleans bytesPerPeriod cacheChange @@ -93,6 +95,7 @@ mutexes myFilterFactory nackResponseDelay nackSupressionDuration +netmask NonConstEnabler NoOpDomainParticipantListener nullptr @@ -150,6 +153,7 @@ Struct Subclassed subclasses subentities +subnetwork SubscriberListener SubscriptionMatchedStatus synchronism diff --git a/docs/fastdds/transport/interfaces.rst b/docs/fastdds/transport/interfaces.rst new file mode 100644 index 000000000..251a587d5 --- /dev/null +++ b/docs/fastdds/transport/interfaces.rst @@ -0,0 +1,203 @@ +.. include:: ../../03-exports/aliases.include +.. include:: ../../03-exports/aliases-api.include +.. include:: ../../03-exports/roles.include + +.. warning:: + + The configuration options described in this section apply to network interfaces. + Therefore, it is only available on :ref:`transport_tcp_tcp` and :ref:`transport_udp_udp`. + +.. _ifaces_config: + +Interfaces configuration +======================== + +By default, *Fast DDS* makes use of all active network interfaces found in the system to communicate (note: applies to +:ref:`transport_udp_udp` and :ref:`transport_tcp_tcp`). +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. + +.. _netmask_filtering: + +Netmask filtering +----------------- + +The standard behaviour in *Fast-DDS* is to attempt data transmission to any remote locator for which a compatible +transport (based on :ref:`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: + +.. _netmask_filter_values: + +.. list-table:: + :header-rows: 1 + :align: left + + * - Value + - Description + * - |NetmaskFilterKind::ON-api| + - Enable netmask filtering. + * - |NetmaskFilterKind::OFF-api| + - Disable netmask filtering. + * - |NetmaskFilterKind::AUTO-api| + - Use container's netmask filter configuration. + +An |NetmaskFilterKind::AUTO-api| netmask filter configuration means that its effective value will be given by that of +its "container", which in the case of an :ref:`allowlist ` entry would be the +:ref:`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 |NetmaskFilterKind::OFF-api| if it is |NetmaskFilterKind::ON-api| for the participant where this transport +is registered. +Likewise, the netmask filter configuration for an allowlist entry cannot be |NetmaskFilterKind::ON-api| if it is +|NetmaskFilterKind::OFF-api| 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 :ref:`Matching algorithm `) both in :ref:`participants ` + and :ref:`endpoints ` when enabling the netmask filtering feature at participant or transport level + without defining an :ref:`allowlist ` or :ref:`blocklist `. + +Additional considerations need to be taken into account when using netmask filtering in combination with +:ref:`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 :ref:`participant ` +or :ref:`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: + +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :start-after: //CONF-NETMASK-FILTER + :end-before: //!-- + :lines: 3-5 + :dedent: 8 + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: PARTICIPANT-NETMASK-FILTER + :end-before: <--> + :lines: 2-3,5- + :append: + +For socket (UDP/TCP) transport descriptors: + +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :start-after: //CONF-NETMASK-FILTER + :end-before: //!-- + :lines: 7-12 + :dedent: 8 + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: TRANSPORT-NETMASK-FILTER + :end-before: <--> + :lines: 2-3,5- + :append: + +See :ref:`Allowlist ` to learn how to configure netmask filtering for specific network devices. + + +.. _interfaces_allowlist: + +Allowlist +--------- + +Using *Fast DDS*, it is possible to limit the network interfaces used by :ref:`transport_tcp_tcp` +and :ref:`transport_udp_udp`. +This is achieved by adding the interfaces to the |SocketTransportDescriptor::interface_allowlist-api| field in the +:ref:`transport_tcp_transportDescriptor` or :ref:`transport_udp_transportDescriptor`. +Thus, the communication interfaces used by the |DomainParticipants| whose |TransportDescriptorInterface-api| defines an +|SocketTransportDescriptor::interface_allowlist-api| 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 |SocketTransportDescriptor::interface_allowlist-api| can be specified both by IP address +or interface name. +Additionally, each entry added to the allowlist may specify a :ref:`netmask filter ` +configuration value (|NetmaskFilterKind::AUTO-api| by default). + +For example: + +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :start-after: //CONF-INTERFACES-ALLOWLIST + :end-before: //!-- + :dedent: 8 + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: INTERFACES-ALLOWLIST + :end-before: <--> + :lines: 2-3,5- + :append: + +.. 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. + + +.. _interfaces_blocklist: + +Blocklist +--------- + +Apart from defining a list of :ref:`allowed interfaces `, it is also possible to define a list of +interfaces that should be blocked. +This is accomplished through the |SocketTransportDescriptor::interface_blocklist-api| field present in the +:ref:`transport_tcp_transportDescriptor` or :ref:`transport_udp_transportDescriptor`. + +.. note:: + This list takes precedence over the allowlist, so if a network interface is in both lists, it will be blocked. + +The interfaces in |SocketTransportDescriptor::interface_blocklist-api| can be specified both by IP address +or interface name. + +For example: + +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :start-after: //CONF-INTERFACES-BLOCKLIST + :end-before: //!-- + :dedent: 8 + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: INTERFACES-BLOCKLIST + :end-before: <--> + :lines: 2-3,5- + :append: + diff --git a/docs/fastdds/transport/tcp/tcp.rst b/docs/fastdds/transport/tcp/tcp.rst index 432fdec9d..b92b889eb 100644 --- a/docs/fastdds/transport/tcp/tcp.rst +++ b/docs/fastdds/transport/tcp/tcp.rst @@ -1,5 +1,6 @@ .. include:: ../../../03-exports/aliases.include .. include:: ../../../03-exports/aliases-api.include +.. include:: ../../../03-exports/roles.include .. _transport_tcp_tcp: @@ -40,6 +41,9 @@ However, they share many of their features, and most of the |TransportDescriptor The following table describes the common data members for both TCPv4 and TCPv6. +.. |netmask_filtering| replace:: :ref:`netmask_filtering` +.. |interfaces_allowlist| replace:: :ref:`interfaces_allowlist` +.. |interfaces_blocklist| replace:: :ref:`interfaces_blocklist` .. |InterfaceWhitelist| replace:: :ref:`whitelist-interfaces` .. |TLSconfig| replace:: :ref:`transport_tcp_tls` @@ -59,6 +63,21 @@ The following table describes the common data members for both TCPv4 and TCPv6. - ``uint32_t`` - 0 - Size of the receiving buffer of the socket (octets). + * - |SocketTransportDescriptor::netmask_filter-api| + - |NetmaskFilterKind-api| + - |NetmaskFilterKind::AUTO-api| + - See |netmask_filtering|. + * - |SocketTransportDescriptor::interface_allowlist-api| + - ``vector>`` + - Empty vector + - List of allowed interfaces with |br| + netmask filter configuration. |br| + See |interfaces_allowlist|. + * - |SocketTransportDescriptor::interface_blocklist-api| + - ``vector`` + - Empty vector + - List of blocked interfaces. + See |interfaces_blocklist|. * - |SocketTransportDescriptor::interfaceWhiteList-api| - ``vector`` - Empty vector diff --git a/docs/fastdds/transport/transport.rst b/docs/fastdds/transport/transport.rst index 7b8b6d362..01c131231 100644 --- a/docs/fastdds/transport/transport.rst +++ b/docs/fastdds/transport/transport.rst @@ -58,5 +58,6 @@ The figure below shows a comparison between the different transports available i /fastdds/transport/listening_locators.rst /fastdds/transport/announced_locators.rst /fastdds/transport/whitelist.rst + /fastdds/transport/interfaces.rst /fastdds/transport/disabling_multicast.rst diff --git a/docs/fastdds/transport/transport_api.rst b/docs/fastdds/transport/transport_api.rst index cb8e81521..d272aafbc 100644 --- a/docs/fastdds/transport/transport_api.rst +++ b/docs/fastdds/transport/transport_api.rst @@ -104,6 +104,8 @@ Data members The TransportInterface defines the following data members: +.. _transport_transportApi_kind: + +-------------------------+------------------+-----------------------------------------------------------------------+ | Member | Data type | Description | +=========================+==================+=======================================================================+ diff --git a/docs/fastdds/transport/udp/udp.rst b/docs/fastdds/transport/udp/udp.rst index c6fe47979..f56d3af05 100644 --- a/docs/fastdds/transport/udp/udp.rst +++ b/docs/fastdds/transport/udp/udp.rst @@ -1,5 +1,6 @@ .. include:: ../../../03-exports/aliases.include .. include:: ../../../03-exports/aliases-api.include +.. include:: ../../../03-exports/roles.include .. _transport_udp_udp: @@ -27,6 +28,9 @@ However, all their |TransportDescriptorInterface-api| data members are common. The following table describes the common data members for both UDPv4 and UDPv6. +.. |netmask_filtering| replace:: :ref:`netmask_filtering` +.. |interfaces_allowlist| replace:: :ref:`interfaces_allowlist` +.. |interfaces_blocklist| replace:: :ref:`interfaces_blocklist` .. |InterfaceWhitelist| replace:: :ref:`whitelist-interfaces` .. list-table:: @@ -45,6 +49,21 @@ The following table describes the common data members for both UDPv4 and UDPv6. - ``uint32_t`` - 0 - Size of the receiving buffer of the socket (octets). + * - |SocketTransportDescriptor::netmask_filter-api| + - |NetmaskFilterKind-api| + - |NetmaskFilterKind::AUTO-api| + - See |netmask_filtering|. + * - |SocketTransportDescriptor::interface_allowlist-api| + - ``vector>`` + - Empty vector + - List of allowed interfaces with |br| + netmask filter configuration. |br| + See |interfaces_allowlist|. + * - |SocketTransportDescriptor::interface_blocklist-api| + - ``vector`` + - Empty vector + - List of blocked interfaces. + See |interfaces_blocklist|. * - |SocketTransportDescriptor::interfaceWhiteList-api| - ``vector`` - Empty vector diff --git a/docs/fastdds/transport/whitelist.rst b/docs/fastdds/transport/whitelist.rst index 206db5432..282cf34d0 100644 --- a/docs/fastdds/transport/whitelist.rst +++ b/docs/fastdds/transport/whitelist.rst @@ -2,6 +2,11 @@ .. include:: ../../03-exports/aliases-api.include .. include:: ../../03-exports/roles.include +.. warning:: + + Interface whitelist will be deprecated in future versions of Fast DDS. + The use of the new :ref:`interfaces allowlist ` is recommended. + .. _whitelist-interfaces: Interface Whitelist diff --git a/docs/fastdds/xml_configuration/domainparticipant.rst b/docs/fastdds/xml_configuration/domainparticipant.rst index a34791ab1..1e2a74042 100644 --- a/docs/fastdds/xml_configuration/domainparticipant.rst +++ b/docs/fastdds/xml_configuration/domainparticipant.rst @@ -123,6 +123,12 @@ These elements allow the user to define the DomainParticipant configuration. socket size. - ``uint32_t`` - 0 + * - ```` + - Participant's netmask |br| + filtering configuration. |br| + See the :ref:`netmask_filtering` section. + - |NetmaskFilterKind-api| + - |NetmaskFilterKind::AUTO-api| * - ```` - |WireProtocolConfigQos::builtin-api| public data member of the |br| |WireProtocolConfigQos-api| class. |br| @@ -211,7 +217,7 @@ These elements allow the user to define the DomainParticipant configuration. :language: xml :start-after: XML-PARTICIPANT<--> :end-before: <--> - :lines: 2-4, 6-126, 128-129 + :lines: 2-4, 6-128, 130-131 .. note:: diff --git a/docs/fastdds/xml_configuration/transports.rst b/docs/fastdds/xml_configuration/transports.rst index 3982222d4..1706aa859 100644 --- a/docs/fastdds/xml_configuration/transports.rst +++ b/docs/fastdds/xml_configuration/transports.rst @@ -53,6 +53,14 @@ A more detailed explanation of each of these elements can be found in :ref:`comm | ```` | Number of channels opened with each initial |br| | ``uint32_t`` | 4 | | | remote peer. | | | +-------------------------------+----------------------------------------------------+----------------------+----------+ +| ```` | Transport's :ref:`netmask_filtering` |br| | OFF | AUTO | +| | configuration. +----------------------+ | +| | | AUTO | | +| | +----------------------+ | +| | | ON | | ++-------------------------------+----------------------------------------------------+----------------------+----------+ +| ```` | Allows defining an :ref:`ifaces_config`. | :ref:`ifaces_config` | | ++-------------------------------+----------------------------------------------------+----------------------+----------+ | ```` | Allows defining an interfaces |whitelist|. | |whitelist| | | +-------------------------------+----------------------------------------------------+----------------------+----------+ | ```` | *Time To Live* (**UDP only**). See |br| | ``uint8_t`` | 1 | @@ -137,7 +145,7 @@ More examples of transports descriptors can be found in the :ref:`comm-transport :language: xml :start-after: :end-before: <--> - :lines: 2-4, 6-40, 42-43 + :lines: 2-4, 6-50, 52-53 .. _rtcpdefinition: