diff --git a/docs/devguide/internet_enabled_rtps.rst b/docs/devguide/internet_enabled_rtps.rst index abd0f75c1ab..7bfcbb1b8c3 100644 --- a/docs/devguide/internet_enabled_rtps.rst +++ b/docs/devguide/internet_enabled_rtps.rst @@ -16,11 +16,11 @@ Overview .. Sect<15.1> -Like any specification, standard, or system, RTPS was designed with certain assumptions. +Like any specification, standard, or system, :ref:`RTPS ` was designed with certain assumptions. Two of these assumptions severely limit the ability to use RTPS in modern network environments. -First, RTPS, or more specifically, SPDP uses multicast for discovery. +First, RTPS, or more specifically, :ref:`SPDP ` uses multicast for discovery. Multicast is not supported on the public Internet which precludes the use of RTPS for Internet of Things (IoT) applications and Industrial Internet of Things (IIoT) applications. -Second, SPDP and SEDP advertise locators (IP and port pairs) for endpoints (DDS readers and writer). +Second, SPDP and :ref:`SEDP ` advertise locators (IP and port pairs) for endpoints (DDS readers and writer). If the participant is behind a firewall that performs network address translation, then the locators advertised by the participant are useless to participants on the public side of the firewall. This section describes different tools and techniques for getting around these limitations. @@ -119,7 +119,8 @@ As an example: Each participant should use a single RtpsRelay instance due to the way NAT bindings work. Most firewalls will only forward packets received from the destination address that was originally used to create the NAT binding. -That is, if participant A is interacting with relay A and participant B is interacting with relay B, then a message from A to B must go from A to relay A, to relay B, and finally to B. Relay A cannot send directly to B since that packet will not be accepted by the firewall. +That is, if participant A is interacting with relay A and participant B is interacting with relay B, then a message from A to B must go from A to relay A, to relay B, and finally to B. +Relay A cannot send directly to B since that packet will not be accepted by the firewall. .. _internet_enabled_rtps--usage: @@ -129,6 +130,8 @@ Usage .. Sect<15.2.2> +.. program:: RtpsRelay + The RtpsRelay itself is an OpenDDS application. The source code is located in :ghfile:`tools/rtpsrelay`. Security must be enabled to build the RtpsRelay. @@ -141,7 +144,7 @@ The webserver has the following endpoints: * ``/config`` Responds with configured content and content type. - See -MetaDiscovery options below. + See :option:`-MetaDiscoveryContentPath` and :option:`-MetaDiscoveryContent` below. Potential client participants can download the necessary configuration from this endpoint. * ``/healthcheck`` @@ -155,15 +158,15 @@ The command-line options for the RtpsRelay: This option is mandatory and is a unique id associated with all topics published by the relay. -.. option:: -HorizontalAddres
+.. option:: -HorizontalAddress
Determines the base network address used for receiving RTPS message from other relays. - By default, the relay listens on the first IP network and uses port 11444 for SPDP messages, 11445 for SEDP messages, and 11446 for data messages. + By default, the relay listens on the first IP network and uses port ``11444`` for :ref:`SPDP ` messages, ``11445`` for :ref:`SEDP ` messages, and ``11446`` for data messages. .. option:: -VerticalAddress
Determines the base network address used for receiving RTPS messages from the participants. - By default, the relay listens on 0.0.0.0:4444 for SPDP messages, 0.0.0.0:4445 for SEDP messages, and 0.0.0.0.4446 for data messages. + By default, the relay listens on ``0.0.0.0:4444`` for :ref:`SPDP ` messages, ``0.0.0.0:4445`` for :ref:`SEDP ` messages, and ``0.0.0.0.4446`` for data messages. .. option:: -RelayDomain @@ -240,6 +243,10 @@ The command-line options for the RtpsRelay: Enable/disable logging of activity events. +.. option:: -LogHttp 0|1 + + Enable/disable logging of the HTTP server. + .. option:: -LogRelayStatistics .. option:: -LogHandlerStatistics @@ -268,6 +275,17 @@ The command-line options for the RtpsRelay: If :cfg:prop:`thread monitoring is enabled `, the RtpsRelay will not accept new client participants if the CPU utilization of any thread is above this limit, default .95. +.. option:: -AdmissionControlQueueSize + + The max number of new client participants that are allowed to perform discovery. + If the admission control queue is full, then new client participants are not admitted. + Default is 0 (disabled). + +.. option:: -AdmissionControlQueueDuration + + New client participants in the :option:`admission control queue <-AdmissionControlQueueSize>` that are taking longer than this many seconds to perform discovery are kicked out of the queue. + Default is 0. + .. option:: -PublishRelayStatus Setting this to a positive integer causes the relay to publish its status at that interval. @@ -284,7 +302,7 @@ The command-line options for the RtpsRelay: The HTTP content type to report for the meta discovery config endpoint, default is ``application/json``. -.. option:: -MetaDiscoveryContentPath +.. option:: -MetaDiscoveryContentPath .. option:: -MetaDiscoveryContent @@ -343,7 +361,7 @@ Second, the hosts generate and exchange candidates (which includes the public IP A candidate is an IP and port that responds to STUN messages and sends datagrams. Third, the hosts send STUN binding requests to the candidates in an attempt to generate the necessary NAT bindings and establish connectivity. -For OpenDDS, ICE can be used to potentially establish connectivity between SPDP endpoints, SEDP endpoints, and ordinary RTPS endpoints. +For OpenDDS, ICE can be used to potentially establish connectivity between :ref:`SPDP ` endpoints, :ref:`SEDP ` endpoints, and ordinary RTPS endpoints. SPDP is used as the side channel for SEDP and SEDP is used as the side channel for the ordinary RTPS endpoints. To this, we added two parameters to the RTPS protocol for sending general ICE information and ICE candidates and added the ability to execute the ICE protocol and process STUN messages to the RTPS transports. diff --git a/docs/devguide/introduction.rst b/docs/devguide/introduction.rst index 891719a745a..3c49c00bb71 100644 --- a/docs/devguide/introduction.rst +++ b/docs/devguide/introduction.rst @@ -70,7 +70,7 @@ Real-time Publish-Subscribe (RTPS) The full name of this specification is the *Real-time Publish-Subscribe Protocol DDS Interoperability Wire Protocol* (DDSI-RTPS), but can also be just called RTPS. This specification describes the requirements for interoperability between DDS implementations. -See :ref:`rtps-disc` for more information. +See :ref:`rtps-disc` and :ref:`rtps-udp-transport` for more information. The version OpenDDS uses is :omgspec:`rtps`. Although the document number is v2.3, it specifies protocol version 2.4. diff --git a/docs/devguide/run_time_configuration.rst b/docs/devguide/run_time_configuration.rst index aab20e624f1..9cd7469aa96 100644 --- a/docs/devguide/run_time_configuration.rst +++ b/docs/devguide/run_time_configuration.rst @@ -1026,21 +1026,24 @@ Configuring for RTPS Discovery .. Sect<7.3.3> +.. default-cfg-sec:: rtps_discovery + This section describes the configuration properties for :ref:`rtps-disc`. -The RTPS specification gives the following simple description that forms the basis for the discovery approach used by OpenDDS and the two different protocols used to accomplish the discovery operations. -The excerpt from the :omgspec:`rtps:8.5.1` is as follows: - The RTPS specification splits up the discovery protocol into two independent protocols: +To configure RTPS discovery, it's helpful to understand that it is composed of 2 distinct protocols: - 1. Participant Discovery Protocol +.. _spdp: - 2. Endpoint Discovery Protocol +*Simple Participant Discovery Protocol* (SPDP) + This protocol is how RTPS participants :prop:`discover each other ` and let each other know :prop:`they're still available `. + They also use it to exchange basic information about each other such as the domain id and addresses to use to communicate. + More about SPDP can be found in :omgspec:`rtps:8.5.3 The Simple Participant Discovery Protocol`. - A Participant Discovery Protocol (PDP) specifies how Participants discover each other in the network. - Once two Participants have discovered each other, they exchange information on the Endpoints they contain using an Endpoint Discovery Protocol (EDP). - Apart from this causality relationship, both protocols can be considered independent. +.. _sedp: -The configuration options discussed in this section allow a user to specify property values to change the behavior of the *Simple Participant Discovery Protocol* (SPDP) and/or the *Simple Endpoint Discovery Protocol* (SEDP) default settings. +*Simple Endpoint Discovery Protocol* (SEDP) + This protocol is how RTPS participants exchange information about their :term:`DataReader`\s and :term:`DataWriter`\s, including their :ref:`qos`. + More about SEDP can be found in :omgspec:`rtps:8.5.4 The Simple Endpoint Discovery Protocol`. RTPS discovery can be configured for a single domain or for multiple domains as was done in :ref:`run_time_configuration--configuring-for-multiple-dcpsinforepo-instances`. @@ -1064,7 +1067,7 @@ The following example uses the ``[common]`` section to point to an instance of a ResendPeriod=5 The instance ``[rtps_discovery/TheRTPSConfig]`` is now the location where properties that vary the default RTPS settings get specified. -In our example the :prop:`ResendPeriod=5 <[rtps_discovery]ResendPeriod>` entry sets the number of seconds between periodic announcements of available data readers / data writers and to detect the presence of other data readers / data writers on the network. +In our example the :prop:`ResendPeriod=5 ` entry sets the number of seconds between periodic announcements of available data readers / data writers and to detect the presence of other data readers / data writers on the network. This would override the default of 30 seconds. If your OpenDDS deployment uses multiple domains, the following configuration approach combines the use of the :sec:`domain` section title with :sec:`rtps_discovery` to allow a user to specify particular settings by domain. @@ -1103,22 +1106,22 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: ResendPeriod= :default: ``30`` - The number of seconds that a process waits between the announcement of participants (see :omgspec:`rtps:8.5.3`). + The number of seconds that a process waits between the :ref:`SPDP participants announcements `. .. prop:: MinResendDelay= :default: ``100`` - The minimum time in milliseconds between participant announcements. + The minimum time in milliseconds between :ref:`SPDP participants announcements `. .. prop:: QuickResendRatio= :default: ``0.1`` - Tuning parameter that configures local SPDP resends as a fraction of the resend period. + Tuning parameter that configures local :ref:`SPDP participants announcement ` resends as a fraction of the resend period. .. prop:: LeaseDuration= :default: ``300`` (5 minutes) - Sent as part of the participant announcement. + Sent as part of the :ref:`SPDP participants announcement `. It tells the peer participants that if they don't hear from this participant for the specified duration, then this participant can be considered "not alive". .. prop:: LeaseExtension= @@ -1200,21 +1203,21 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: SedpMaxMessageSize= :default: ``65466`` (maximum worst-case UDP payload size) - Set the maximum SEDP message size. + Set the maximum :ref:`SEDP ` message size. See :prop:`[transport@rtps_udp]max_message_size`. .. prop:: SedpMulticast= :default: ``1`` - Determines whether Multicast is used for the SEDP traffic. + Determines whether Multicast is used for the :ref:`SEDP ` traffic. When set to ``1``, Multicast is used. When set to ``0``, Unicast is used. .. prop:: SedpMulticastAddress=[:] :default: :prop:`InteropMulticastOverride` - The multicast group to use for SEDP multicast traffic. + The multicast group to use for :ref:`SEDP ` multicast traffic. If ```` is ``0`` or not specified, it is calculated as described in :ref:`config-ports-used-by-sedp-multicast`. .. prop:: Ipv6SedpMulticastAddress=[:] @@ -1225,7 +1228,7 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: SedpLocalAddress=:[] :default: :prop:`[common]DCPSDefaultAddress` - Configure the transport instance created and used by SEDP to bind to the specified local address and port. + Configure the transport instance created and used by :ref:`SEDP ` to bind to the specified local address and port. In order to leave the port unspecified, it can be omitted from the setting but the trailing ``:`` must be present. If ```` is ``0`` or not specified, it is calculated as described in :ref:`config-ports-used-by-sedp-unicast`. @@ -1237,7 +1240,7 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: SpdpMulticastAddress=[:] :default: :prop:`InteropMulticastOverride` - The multicast group to use for SPDP multicast traffic. + The multicast group to use for :ref:`SPDP ` multicast traffic. If ```` is ``0`` or not specified, it is calculated as described in :ref:`config-ports-used-by-spdp-multicast`. .. prop:: Ipv6SpdpMulticastAddress=[:] @@ -1248,7 +1251,7 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: SpdpLocalAddress=[:] :default: :prop:`[common]DCPSDefaultAddress` - Address of a local interface, which will be used by SPDP to bind to that specific interface. + Address of a local interface, which will be used by :ref:`SPDP ` to bind to that specific interface. If ```` is ``0`` or not specified, it is calculated as described in :ref:`config-ports-used-by-spdp-unicast`. .. prop:: Ipv6SpdpLocalAddress=[:] @@ -1258,51 +1261,51 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: SedpAdvertisedLocalAddress=:[] - Sets the address advertised by SEDP. + Sets the address advertised by :ref:`SEDP `. Typically used when the participant is behind a firewall or NAT. In order to leave the port unspecified, it can be omitted from the setting but the trailing ``:`` must be present. .. prop:: SedpSendDelay= :default: ``10`` - Time in milliseconds for a built-in SEDP Writer to wait before sending data. + Time in milliseconds for a built-in :ref:`SEDP ` Writer to wait before sending data. .. prop:: SedpHeartbeatPeriod= :default: ``200`` - Time in milliseconds for a built-in SEDP Writer to announce the availability of data. + Time in milliseconds for a built-in :ref:`SEDP ` Writer to announce the availability of data. .. prop:: SedpNakResponseDelay= :default: ``100`` - Time in milliseconds for a built-in SEDP Writer to delay the response to a negative acknowledgment. + Time in milliseconds for a built-in :ref:`SEDP ` Writer to delay the response to a negative acknowledgment. .. prop:: SpdpSendAddrs=:[,:]... - A list (comma or whitespace separated) of ``:`` pairs used as destinations for SPDP content. + A list (comma or whitespace separated) of ``:`` pairs used as destinations for :ref:`SPDP ` content. This can be a combination of Unicast and Multicast addresses. .. prop:: MaxSpdpSequenceMsgResetChecks= :default: ``3`` - Remove a discovered participant after this number of SPDP messages with earlier sequence numbers. + Remove a discovered participant after this number of :ref:`SPDP ` messages with earlier sequence numbers. .. prop:: PeriodicDirectedSpdp= :default: ``0`` (disabled) - A boolean value that determines whether directed SPDP messages are sent to all participants once every resend period. + A boolean value that determines whether directed :ref:`SPDP ` messages are sent to all participants once every resend period. This setting should be enabled for participants that cannot use multicast to send SPDP announcements, e.g., an RtpsRelay. .. prop:: UndirectedSpdp= :default: ``1`` (enabled) - A boolean value that determines whether undirected SPDP messages are sent. + A boolean value that determines whether undirected :ref:`SPDP ` messages are sent. This setting should be disabled for participants that cannot use multicast to send SPDP announcements, e.g., an RtpsRelay. .. prop:: InteropMulticastOverride= :default: ``239.255.0.1`` - A network address specifying the multicast group to be used for SPDP and SEDP. + A network address specifying the multicast group to be used for :ref:`SPDP ` and :ref:`SEDP `. The default is defined by the RTPS specification. This property can be used, for example, to specify use of a routed group address to provide a larger discovery scope. It can be modified by :prop:`[Customization]InteropMulticastOverride`. @@ -1333,16 +1336,16 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: SpdpRtpsRelayAddress=: - Specifies the address of the :ref:`RtpsRelay ` for SPDP messages. + Specifies the address of the :ref:`RtpsRelay ` for :ref:`SPDP ` messages. .. prop:: SpdpRtpsRelaySendPeriod= :default: ``30`` seconds - Specifies the interval between SPDP announcements sent to the :ref:`RtpsRelay `. + Specifies the interval between :ref:`SPDP ` announcements sent to the :ref:`RtpsRelay `. .. prop:: SedpRtpsRelayAddress=host:port - Specifies the address of the :ref:`RtpsRelay ` for SEDP messages. + Specifies the address of the :ref:`RtpsRelay ` for :ref:`SEDP ` messages. .. prop:: RtpsRelayOnly= :default: ``0`` (disabled) @@ -1357,16 +1360,16 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: SpdpStunServerAddress=: - Specifies the address of the STUN server to use for SPDP when using :ref:`ICE `. + Specifies the address of the STUN server to use for :ref:`SPDP ` when using :ref:`ICE `. .. prop:: SedpStunServerAddress=: - Specifies the address of the STUN server to use for SEDP when using :ref:`ICE `. + Specifies the address of the STUN server to use for :ref:`SEDP ` when using :ref:`ICE `. .. prop:: UseIce= :default: ``0`` (disabled) - Enable or disable :ref:`ICE ` for both SPDP and SEDP. + Enable or disable :ref:`ICE ` for both :ref:`SPDP ` and :ref:`SEDP `. .. prop:: MaxAuthTime= :default: ``300`` seconds (5 minutes) @@ -1416,7 +1419,7 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: SedpResponsiveMode= :default: ``0`` (disabled) - Causes the built-in SEDP endpoints to send additional messages which may reduce latency. + Causes the built-in :ref:`SEDP ` endpoints to send additional messages which may reduce latency. .. prop:: SedpPassiveConnectDuration= :default: ``60000`` milliseconds (1 minute) @@ -1426,14 +1429,14 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: SendBufferSize= :default: ``0`` (system default value is used, ``65466`` typical) - Socket send buffer size for both SPDP and SEDP. + Socket send buffer size for both :ref:`SPDP ` and :ref:`SEDP `. See :prop:`[transport@rtps_udp]send_buffer_size`. .. prop:: RecvBufferSize= :default: ``0`` (system default value is used, ``65466`` typical) - Socket receive buffer size for both SPDP and SEDP. + Socket receive buffer size for both :ref:`SPDP ` and :ref:`SEDP `. See :prop:`[transport@rtps_udp]rcv_buffer_size`. @@ -1446,17 +1449,17 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: SedpReceivePreallocatedMessageBlocks= :default: ``0`` (use :prop:`[transport]receive_preallocated_message_blocks`'s default) - Configure the :prop:`[transport]receive_preallocated_message_blocks` attribute of SEDP's transport. + Configure the :prop:`[transport]receive_preallocated_message_blocks` attribute of :ref:`SEDP `'s transport. .. prop:: SedpReceivePreallocatedDataBlocks= :default: ``0`` (use :prop:`[transport]receive_preallocated_data_blocks`'s default) - Configure the :prop:`[transport]receive_preallocated_data_blocks` attribute of SEDP's transport. + Configure the :prop:`[transport]receive_preallocated_data_blocks` attribute of :ref:`SEDP `'s transport. .. prop:: CheckSourceIp= :default: ``1`` (enabled) - Incoming participant announcements (SPDP) are checked to verify that their source IP address matches one of: + Incoming :ref:`SPDP participant announcements ` are checked to verify that their source IP address matches one of: - An entry in the metatraffic locator list - The configured :ref:`RtpsRelay ` (if any) @@ -1467,7 +1470,7 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem .. prop:: SpdpUserTag= :default: ``0`` (disabled) - Add the OpenDDS-specific UserTag RTPS submessage to the start of SPDP messages. + Add the OpenDDS-specific UserTag RTPS submessage to the start of :ref:`SPDP ` messages. If ```` is 0 (the default), the submessage is not added. Otherwise this submessage's contents is the 4-byte unsigned integer ````. @@ -1476,7 +1479,11 @@ Those properties, along with options specific to OpenDDS's RTPS discovery implem Ports Used by RTPS Discovery ---------------------------- -See :omgspec:`rtps:9.6.1 Default Locators` for the related RTPS spec definitions. +.. seealso:: + + :omgspec:`rtps:9.6.1 Default Locators` for the RTPS spec definitions. + + :ref:`config-ports-used-by-rtps-udp` .. _config-ports-used-by-spdp: @@ -1488,23 +1495,23 @@ Simple Participant Discovery Protocol (SPDP) SPDP Multicast """""""""""""" -The SPDP multicast port will be one of the following: +The :ref:`SPDP ` multicast port will be one of the following: -- Port from :prop:`SpdpMulticastAddress <[rtps_discovery]SpdpMulticastAddress>` if set -- :prop:`PB <[rtps_discovery]PB>` + :prop:`DG <[rtps_discovery]DG>` × *domainId* + :prop:`D0 <[rtps_discovery]D0>` +- Port from :prop:`SpdpMulticastAddress` if set +- :prop:`PB` + :prop:`DG` × *domainId* + :prop:`D0` .. _config-ports-used-by-spdp-unicast: SPDP Unicast """""""""""" -The SPDP unicast port will be one of the following: +The :ref:`SPDP ` unicast port will be one of the following: -- Port from :prop:`SpdpLocalAddress <[rtps_discovery]SpdpLocalAddress>` if set -- A system-provided port if :val:`SpdpPortMode=system <[rtps_discovery]SpdpPortMode=system>` -- :prop:`PB <[rtps_discovery]PB>` + :prop:`DG <[rtps_discovery]DG>` × *domainId* + :prop:`D1 <[rtps_discovery]D1>` + :prop:`PG <[rtps_discovery]PG>` × *participantId* if :val:`SpdpPortMode=probe <[rtps_discovery]SpdpPortMode=probe>` is set (default) +- Port from :prop:`SpdpLocalAddress` if set +- A system-provided port if :val:`SpdpPortMode=system` +- :prop:`PB` + :prop:`DG` × *domainId* + :prop:`D1` + :prop:`PG` × *participantId* if :val:`SpdpPortMode=probe` is set (default) - - If the port can not be opened, then the *participantId* is incremented until a port can be opened. + - *participantId* starts at 0 and if the port can not be opened, then the *participantId* is incremented until a port can be opened. - If no valid UDP port can be opened, then an error will be logged. .. _config-ports-used-by-sedp: @@ -1514,32 +1521,32 @@ Simple Endpoint Discovery Protocol (SEDP) .. note:: - :prop:`DX <[rtps_discovery]DX>` and :prop:`DY <[rtps_discovery]DY>` are OpenDDS-specific. + :prop:`DX` and :prop:`DY` are OpenDDS-specific. .. _config-ports-used-by-sedp-multicast: SEDP Multicast """""""""""""" -If :prop:`SedpMulticast=1 <[rtps_discovery]SedpMulticast>`, the SEDP multicast port will be one of the following: +If :prop:`SedpMulticast=1 `, the :ref:`SEDP ` multicast port will be one of the following: -- Port from :prop:`SedpMulticastAddress <[rtps_discovery]SedpMulticastAddress>` if set (the same as SPDP) -- :prop:`PB <[rtps_discovery]PB>` + :prop:`DG <[rtps_discovery]DG>` × *domainId* + :prop:`DX <[rtps_discovery]DX>` +- Port from :prop:`SedpMulticastAddress` if set +- :prop:`PB` + :prop:`DG` × *domainId* + :prop:`DX` .. _config-ports-used-by-sedp-unicast: SEDP Unicast """""""""""" -The SEDP unicast port will be one of the following: +The :ref:`SEDP ` unicast port will be one of the following: -- Port from :prop:`SedpLocalAddress <[rtps_discovery]SedpLocalAddress>` if set -- :prop:`PB <[rtps_discovery]PB>` + :prop:`DG <[rtps_discovery]DG>` × *domainId* + :prop:`DY <[rtps_discovery]DY>` + :prop:`PG <[rtps_discovery]PG>` × *participantId* if :val:`SedpPortMode=probe <[rtps_discovery]SedpPortMode=probe>` is set +- Port from :prop:`SedpLocalAddress` if set +- :prop:`PB` + :prop:`DG` × *domainId* + :prop:`DY` + :prop:`PG` × *participantId* if :val:`SedpPortMode=probe` is set - - If the port can not be opened, then the *participantId* is incremented until a port can be opened. + - *participantId* starts at 0 and if the port can not be opened, then the *participantId* is incremented until a port can be opened. - If no valid UDP port can be opened, then an error will be logged. -- A system-provided port if :val:`SedpPortMode=system <[rtps_discovery]SedpPortMode=system>` (default) +- A system-provided port if :val:`SedpPortMode=system` (default) .. _run_time_configuration--additional-ddsi-rtps-discovery-features: @@ -1552,6 +1559,8 @@ Additional RTPS Discovery Features The RTPS discovery implementation creates and manages a transport instance -- specifically an object of class ``RtpsUdpInst``. In order for applications to access this object and :ref:`enable advanced features `, the ``RtpsDiscovery`` class provides the method ``sedp_transport_inst(domainId, participant)``. +.. default-cfg-sec:: + .. _static-disc-config: .. _run_time_configuration--configuring-for-static-discovery: @@ -2670,6 +2679,8 @@ RTPS UDP Transport Configuration Properties .. Sect<7.4.5.5> +.. default-cfg-sec:: transport@rtps_udp + This section describes the configuration properties for the :ref:`rtps-udp-transport`. To provide an RTPS variant of the single configuration example from :ref:`run_time_configuration--single-transport-configuration`, the configuration file below simply introduces the ``myrtps`` transport and sets :val:`[transport]transport_type=rtps_udp`. @@ -2881,20 +2892,24 @@ Some implementation notes related to using the ``rtps_udp`` transport protocol a .. _config-ports-used-by-rtps-udp: -Ports used by RTPS/UDP +Ports Used by RTPS/UDP ^^^^^^^^^^^^^^^^^^^^^^ -See :omgspec:`rtps:9.6.1 Default Locators` for the related RTPS spec definitions. +.. seealso:: + + :omgspec:`rtps:9.6.1 Default Locators` for the RTPS spec definitions. + + :ref:`config-ports-used-by-rtps-disc` .. _config-ports-used-by-rtps-udp-multicast: Multicast """"""""" -If :prop:`use_multicast=1 <[transport@rtps_udp]use_multicast>` the RTPS/UDP multicast port will be one of the following: +If :prop:`use_multicast=1 ` the RTPS/UDP multicast port will be one of the following: -- Port from :prop:`multicast_group_address <[transport@rtps_udp]multicast_group_address>` and :prop:`ipv6_multicast_group_address <[transport@rtps_udp]ipv6_multicast_group_address>` if set -- :prop:`PB <[transport@rtps_udp]PB>` + :prop:`DG <[transport@rtps_udp]DG>` × *domainId* + :prop:`D2 <[transport@rtps_udp]D2>` +- Port from :prop:`multicast_group_address` and :prop:`ipv6_multicast_group_address` if set +- :prop:`PB` + :prop:`DG` × *domainId* + :prop:`D2` .. _config-ports-used-by-rtps-udp-unicast: @@ -2903,13 +2918,15 @@ Unicast The RTPS/UDP unicast port will be one of the following: -- Port from :prop:`local_address <[transport@rtps_udp]local_address>` and :prop:`ipv6_local_address <[transport@rtps_udp]ipv6_local_address>` if set -- :prop:`PB <[transport@rtps_udp]PB>` + :prop:`DG <[transport@rtps_udp]DG>` × *domainId* + :prop:`D3 <[transport@rtps_udp]D3>` + :prop:`PG <[transport@rtps_udp]PG>` × *participantId* if :val:`PortMode=prob <[transport@rtps_udp]PortMode=probe>` +- Port from :prop:`local_address` and :prop:`ipv6_local_address` if set +- :prop:`PB` + :prop:`DG` × *domainId* + :prop:`D3` + :prop:`PG` × *participantId* if :val:`PortMode=probe` - - If the port can not be opened, then the *participantId* is incremented until a port can be opened. + - *participantId* starts at 0 and if the port can not be opened, then the *participantId* is incremented until a port can be opened. - If no valid UDP port can be opened, then an error will be logged. -- A system-provided port if :val:`PortMode=system <[transport@rtps_udp]PortMode=system>` (default) +- A system-provided port if :val:`PortMode=system` (default) + +.. default-cfg-sec:: .. _run_time_configuration--additional-rtps-udp-features: diff --git a/docs/devguide/safety_profile.rst b/docs/devguide/safety_profile.rst index eb1598b738e..ae357023578 100644 --- a/docs/devguide/safety_profile.rst +++ b/docs/devguide/safety_profile.rst @@ -57,7 +57,7 @@ It is possible that enabling any of these compliance profiles in a Safety Profil To build OpenDDS Safety Profile, pass the command line argument ``--safety-profile`` to the configure script along with any other arguments needed for your platform or configuration. When safety profile is enabled in the configure script, the four compliance profiles listed above default to disabled. -See :ref:`install` for more information about the configure script. +See :ref:`building` for more information about the configure script. .. _safety_profile--safety-profile-configurations-of-ace: diff --git a/docs/internal/docs.rst b/docs/internal/docs.rst index 4e767927d26..418d50bf6b8 100644 --- a/docs/internal/docs.rst +++ b/docs/internal/docs.rst @@ -485,6 +485,11 @@ For :doc:`/devguide/run_time_configuration` there's a custom configuration Sphin Do not include arguments if it has arguments in the directive. The possible formats are ```` and ``@``. +.. rst:directive:: .. default-cfg-sec:: [[@]] + + This sets the default :rst:dir:`cfg:sec` to use in the roles when outside of a section. + If this is not used or has been used with no argument, then the default will be ``common``. + .. rst:directive:: .. cfg:prop:: = Use to document a configuration property that can contain :rst:dir:`cfg:val` and most other RST content. @@ -517,7 +522,7 @@ For :doc:`/devguide/run_time_configuration` there's a custom configuration Sphin - ```` Inside of a :rst:dir:`cfg:sec`, it refers to a property in that section. - Outside of a :rst:dir:`cfg:sec`, the property is assumed to be ``common``. + Outside of a :rst:dir:`cfg:sec`, the property is assumed to be in :rst:dir:`default-cfg-sec`. - ``[]`` - ``[@]`` @@ -541,7 +546,7 @@ For :doc:`/devguide/run_time_configuration` there's a custom configuration Sphin - ``=`` Inside of a :rst:dir:`cfg:sec`, it refers to a value of a property in that section. - Outside of a :rst:dir:`cfg:sec`, the property is assumed to be ``common``. + Outside of a :rst:dir:`cfg:sec`, the property is assumed to be in :rst:dir:`default-cfg-sec`. - ``[]=`` - ``[@]=`` @@ -564,7 +569,7 @@ This is a example made up for the following INI file: Outside their sections, references to properties and values must be complete: :cfg:val:`[server]os=linux`, :cfg:prop:`[server@linux]distro` - Otherwise the ``common`` section will be assumed. + Otherwise the default section will be assumed. .. cfg:sec:: server/ @@ -588,11 +593,23 @@ This is a example made up for the following INI file: .. cfg:prop:: distro= :default: ``Ubuntu`` + .. default-cfg-sec:: server + + ``default-cfg-sec=server``: :cfg:prop:`os`. + + .. default-cfg-sec:: server@linux + + ``default-cfg-sec=server@linux``: :cfg:prop:`distro`. + + .. default-cfg-sec:: + + ``default-cfg-sec=``: :cfg:prop:`[server@linux]distro`. + Turns into: Outside their sections, references to properties and values must be complete: :cfg:val:`[server]os=linux`, :cfg:prop:`[server@linux]distro` - Otherwise the ``common`` section will be assumed. + Otherwise the default section will be assumed. .. cfg:sec:: server/ :no-contents-entry: @@ -628,7 +645,19 @@ Turns into: :no-contents-entry: :no-index-entry: -.. _docs-news: + .. default-cfg-sec:: server + + ``default-cfg-sec=server``: :cfg:prop:`os`. + + .. default-cfg-sec:: server@linux + + ``default-cfg-sec=server@linux``: :cfg:prop:`distro`. + + .. default-cfg-sec:: + + ``default-cfg-sec=``: :cfg:prop:`[server@linux]distro`. + + .. _docs-news: **** News diff --git a/docs/internal/release.rst b/docs/internal/release.rst index da6bc5f88ee..d41e45e5497 100644 --- a/docs/internal/release.rst +++ b/docs/internal/release.rst @@ -358,7 +358,7 @@ Update News on Master .. note:: - This should only be done for the :ref:`latest release ` that's also a `:ref:`micro release `. + This should only be done for the :ref:`latest release ` that's also a :ref:`micro release `. The news on the master branch has to be updated to account for the micro release. Updating the news consists of: diff --git a/docs/news.d/devguide-misc-fixes.rst b/docs/news.d/devguide-misc-fixes.rst new file mode 100644 index 00000000000..82ae40d608c --- /dev/null +++ b/docs/news.d/devguide-misc-fixes.rst @@ -0,0 +1,6 @@ +.. news-prs: 4699 + +.. news-start-section: Documentation +- Documented :option:`RtpsRelay -LogHttp`, :option:`RtpsRelay -AdmissionControlQueueSize`, and :option:`RtpsRelay -AdmissionControlQueueDuration`. +- Documented :ref:`SPDP ` and :ref:`SEDP `. +.. news-end-section diff --git a/docs/sphinx_extensions/config_domain.py b/docs/sphinx_extensions/config_domain.py index 997772c6500..8d984b016d5 100644 --- a/docs/sphinx_extensions/config_domain.py +++ b/docs/sphinx_extensions/config_domain.py @@ -17,6 +17,7 @@ from sphinx.application import Sphinx from sphinx.util import logging from sphinx.util.nodes import nested_parse_with_titles +from sphinx.util.docutils import SphinxDirective from sphinx.roles import XRefRole from custom_domain import CustomDomain, CustomDomainObject, ContextWrapper @@ -27,6 +28,10 @@ class ConfigDomain(CustomDomain): label = 'config' logger = logging.getLogger(__name__) + @classmethod + def ctx(cls, env): + return ContextWrapper(env, cls.name) + def parse(what, regex, string, node, *ret): m = re.fullmatch(regex, string) @@ -106,6 +111,31 @@ def create_signode(self, ctx, name, signode, sec_name, sec_disc, arguments): signode += addnodes.desc_annotation(text, text) +class DefaultCfgSecDirective(SphinxDirective): + has_content = True + name = 'default-cfg-sec' + + def run(self): + ctx = ConfigDomain.ctx(self.env) + + count = len(self.content) + if count == 0: + del ctx.misc[self.name] + elif count == 1: + sec = self.content[0].strip() + parse_section_name(sec, self) + ctx.misc[self.name] = sec + else: + e = ValueError(f'Can not pass more than one line to default-sec') + ConfigDomain.logger.warning(e, location=self.get_location()) + raise e + return [] + + @classmethod + def get_default_section(cls, ctx): + return ctx.misc.get(cls.name, 'common') + + # cfg:prop ==================================================================== prop_name_re = id_re + r'(?:\.' + id_re + r')*' @@ -146,10 +176,25 @@ def key_canonicalize(sec_name, sec_args, prop_name): return sec + '_' + name_canonicalize(prop_name) +def rescope(ctx, sec, sec_name, prop_name=None): + scope = ctx.get_all_names() + if scope: + # We're somewhere inside a sec + scope = scope + [None] * (2 - len(scope)) + if scope[0] == sec: + sec_name = None + if scope[1] == prop_name: + prop_name = None + elif sec == DefaultCfgSecDirective.get_default_section(ctx): + sec_name = None + + return sec_name, prop_name + + class ConfigPropRefRole(XRefRole): def process_link(self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool, title: str, target: str) -> tuple[str, str]: - ctx = ContextWrapper(env, 'cfg') + ctx = ConfigDomain.ctx(env) target = target.strip() # Normalize target for the current scope @@ -159,8 +204,9 @@ def process_link(self, env: BuildEnvironment, refnode: Element, # [sec]prop anywhere pass elif scope_kind == 0 and sec is None: - # Assume prop outside section should be in [common] - target = f'[common]{target}' + # prop outside a section + default_section = DefaultCfgSecDirective.get_default_section(ctx) + target = f'[{default_section}]{target}' elif scope_kind >= 1: # prop anywhere in a section prefix = ctx.get_full_name(0) @@ -172,11 +218,7 @@ def process_link(self, env: BuildEnvironment, refnode: Element, if not has_explicit_title: # Reparse target and hide parts of title that are in the current scope sec, sec_name, sec_disc, prop_name = parse_prop_name(target, self) - scope = ctx.get_all_names() - scope = scope + [None] * (2 - len(scope)) - if scope[0] == sec: - sec_name = None - + sec_name, _ = rescope(ctx, sec, sec_name) title = prop_text(sec_name, sec_disc, prop_name) return title, target @@ -270,7 +312,7 @@ def value_text(sec_name, sec_disc, prop_name, val_name): class ConfigValueRefRole(XRefRole): def process_link(self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool, title: str, target: str) -> tuple[str, str]: - ctx = ContextWrapper(env, 'cfg') + ctx = ConfigDomain.ctx(env) target = target.strip() # Normalize target for the current scope @@ -280,8 +322,9 @@ def process_link(self, env: BuildEnvironment, refnode: Element, # [sec]prop=val anywhere pass elif scope_kind == 0 and sec is None: - # prop=val outside section - target = f'[common]{target}' + # prop outside a section + default_section = DefaultCfgSecDirective.get_default_section(ctx) + target = f'[{default_section}]{target}' elif scope_kind >= 1 and prop is not None: # prop=val anywhere in a section target = ctx.get_full_name(0) + target @@ -295,13 +338,7 @@ def process_link(self, env: BuildEnvironment, refnode: Element, if not has_explicit_title: # Reparse target and hide parts of title that are in the current scope sec, sec_name, sec_disc, prop, prop_name, val_name = parse_value_name(target, self) - scope = ctx.get_all_names() - scope = scope + [None] * (3 - len(scope)) - if scope[0] == sec: - sec_name = None - if scope[1] == prop_name: - prop_name = None - + sec_name, prop_name = rescope(ctx, sec, sec_name, prop_name) title = value_text(sec_name, sec_disc, prop_name, val_name) return title, target @@ -344,6 +381,7 @@ def create_signode(self, ctx, name, signode, brackets): def setup(app: Sphinx) -> dict[str, Any]: app.add_domain(ConfigDomain) + app.add_directive(DefaultCfgSecDirective.name, DefaultCfgSecDirective) return { 'version': '0.1', diff --git a/docs/sphinx_extensions/custom_domain.py b/docs/sphinx_extensions/custom_domain.py index ea924e54953..8876a1fef14 100644 --- a/docs/sphinx_extensions/custom_domain.py +++ b/docs/sphinx_extensions/custom_domain.py @@ -22,6 +22,7 @@ def __init__(self, env, domain): self.ctx = env.ref_context.setdefault(f'{domain}-context', dict( stack=[], needs_push=True, + misc={}, )) def needs_push(self): @@ -74,6 +75,10 @@ def get_full_name(self, index=-1): def get_index_text(self, index=-1): return self.get(index, 'index_text') + @property + def misc(self): + return self.ctx['misc'] + class CustomDomainObject(ObjectDescription[str]): option_spec: OptionSpec = {