diff --git a/code/XMLTester.xml b/code/XMLTester.xml index 0dbe986bb..5d86b59aa 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -1004,6 +1004,19 @@ <--> +PARTICIPANT-NETMASK-FILTER<--> + + + + true + ON + + +<--> + TRANSPORT-NETMASK-FILTER<--> <--> diff --git a/docs/fastdds/transport/interfaces.rst b/docs/fastdds/transport/interfaces.rst index c6c65d4d7..fcfddb2c4 100644 --- a/docs/fastdds/transport/interfaces.rst +++ b/docs/fastdds/transport/interfaces.rst @@ -2,6 +2,11 @@ .. 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 @@ -19,10 +24,10 @@ 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 waste of resources of extreme value in limited bandwidth scenarios, as messages could be sent -from an interface to an unreachable destination given a concrete network architecture. -In this situation, a user may enable the netmask filtering feature, which would prevent this behaviour by only sending -data from a network interface to remote locators within the same subnetwork. +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: @@ -42,39 +47,50 @@ This configuration option can be set at participant, transport and interface lev - 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 transport descriptor -where it is included, and in the case of a transport descriptor would be the participant where it is registered. +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. -Note however that 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 +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. 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/transport level +and :ref:`endpoints ` when enabling the netmask filtering feature at participant or transport level without defining an allowlist. 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 (at externality greater than `0`) is defined for a :ref:`participant ` or -:ref:`endpoint `. +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 both via C++ API or XML configuration. -In the case of participants, the netmask filter configuration is set in C++ as follows: +Netmask filtering can be enabled 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-4 + :dedent: 8 -.. literalinclude:: /../code/DDSCodeTester.cpp - :language: c++ - :start-after: //CONF-NETMASK-FILTER - :end-before: //!-- - :lines: 3-4 - :dedent: 8 + .. tab:: XML -See :ref:`RTPS` for an example on how to configure netmask filtering for a participant through an XML profile. + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: PARTICIPANT-NETMASK-FILTER + :end-before: <--> + :lines: 2-3,5- + :append: For socket (UDP/TCP) transport descriptors: @@ -183,8 +199,3 @@ For example: :lines: 2-3,5- :append: - -.. 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`. diff --git a/docs/fastdds/transport/whitelist.rst b/docs/fastdds/transport/whitelist.rst index 1a2b25aab..282cf34d0 100644 --- a/docs/fastdds/transport/whitelist.rst +++ b/docs/fastdds/transport/whitelist.rst @@ -5,7 +5,7 @@ .. warning:: Interface whitelist will be deprecated in future versions of Fast DDS. - The use of the new :ref:`interfaces allowlist ` is encouraged. + The use of the new :ref:`interfaces allowlist ` is recommended. .. _whitelist-interfaces: