RTI Connext Modern C++ API  Version 6.1.2

Save network traffic into a capture file for further analysis. More...

Classes

class  rti::util::network_capture::ContentKindMask
 <<extension>> Mask indicating the types of contents to remove from RTPS frames before saving them to the capture file. More...
 
class  rti::util::network_capture::TrafficKindMask
 <<extension>> Mask indicating the traffic direction to capture. More...
 
class  rti::util::network_capture::NetworkCaptureParams
 <<extension>> Input parameters for starting Network Capture. More...
 

Functions

bool rti::util::network_capture::enable ()
 Enable Network Capture. More...
 
bool rti::util::network_capture::disable ()
 Disable Network Capture. More...
 
bool rti::util::network_capture::set_default_params (const NetworkCaptureParams &params)
 Set the default Network Capture parameters. More...
 
bool rti::util::network_capture::start (const std::string &filename)
 Start Network Capture. More...
 
bool rti::util::network_capture::start (dds::domain::DomainParticipant participant, const std::string &filename)
 Start Network Capture for a participant. More...
 
bool rti::util::network_capture::start (const std::string &filename, const NetworkCaptureParams &params)
 Start Network Capture with parameters. More...
 
bool rti::util::network_capture::start (dds::domain::DomainParticipant participant, const std::string &filename, const NetworkCaptureParams &params)
 Start Network Capture with parameters for a participant. More...
 
bool rti::util::network_capture::stop ()
 Stop Network Capture. More...
 
bool rti::util::network_capture::stop (dds::domain::DomainParticipant participant)
 Stop Network Capture. More...
 
bool rti::util::network_capture::pause ()
 Pause Network Capture. More...
 
bool rti::util::network_capture::pause (dds::domain::DomainParticipant participant)
 Pause Network Capture. More...
 
bool rti::util::network_capture::resume ()
 Resume Network Capture. More...
 
bool rti::util::network_capture::resume (dds::domain::DomainParticipant participant)
 Resume Network Capture. More...
 

Detailed Description

Save network traffic into a capture file for further analysis.

RTI Connext allows you to capture the network traffic that one or more DomainParticipants send or receive. This feature can be used to analyze and debug communication problems between your DDS applications. When network capture is enabled, each DomainParticipant will generate a pcap-based file that can then be opened by a packet analyzer like Wireshark, provided the right dissectors are installed.

To some extent, network capture can be used as an alternative to existing pcap-based network capture software (such as Wireshark). This will be the case when you are only interested in analyzing the traffic a DomainParticipant sends/receives. In this scenario, network capture will actually have some advantages over using more general pcap-based network capture applications: RTI's network capture includes additional information such as security-related data; it also removes information that is not needed, such as user data, when you want to reduce the capture size. That said, RTI's network capture is not a replacement for other pcap-based network capture applications: it only captures the traffic exchanged by the DomainParticipants, but it does not capture any other traffic exchanged through the system network interfaces.

To capture network traffic network_capture::enable() must be invoked before creating any DomainParticipant. Similarly, network_capture::disable() must be called after deleting all participants. In between these calls, you may start, stop, pause or resume capturing traffic for one or all participants.

Capturing Shared Memory Traffic

Every RTPS frame in network capture has a source and a destination associated with it. In the case of shared memory traffic, a process identifier and a port determine the source and destination endpoints.

Access to the process identifier (PID) of the source for inbound traffic requires changes in the shared memory segments. These changes would break shared memory compatibility with previous versions of RTI Connext. For this reason, by default, network capture will not populate the value of the source PID for inbound shared memory traffic.

If interoperability with previous versions of RTI Connext is not necessary, you can generate capture files containing the source PID for inbound traffic. To do so, configure the value of the 'dds.transport.minimum_compatibility_version' property to 6.1.0. (See rti::core::policy::Property).

<domain_participant_qos>
<property>
<value>
<element>
<name>dds.transport.minimum_compatibility_version</name>
<value>6.1.0</value>
<propagate>false</propagate>
</element>
</value>
</property>
</domain_participant_qos>

This property is never propagated, so it must be consistently configured throughout the whole system.

Note: Changing the value of this property affects the type of shared memory segments that RTI Connext uses. For that reason, you may see the following warning, resulting from leftover shared memory segments:

[0xC733A001,0xB248F671,0xAEC4A0C1:0x000001C1{D=200}|CREATE DP|ENABLE] NDDS_Transport_Shmem_is_segment_compatible:incompatible shared memory protocol detected. Current version 4.0 not compatible with 2.0.

The leftover shared memory segments can be removed using the ipcrm command. See https://community.rti.com/kb/what-are-possible-solutions-common-shared-memory-issues for more information.

Function Documentation

◆ enable()

bool rti::util::network_capture::enable ( )

Enable Network Capture.

This method must be called before any other Network Capture method. It must also be called before creating the participants for which we want to capture traffic.

Use this method only for debugging purposes, since it may introduce a significant performance impact.

Returns
true if success. Otherwise, false
MT Safety:
UNSAFE. It is not safe to call this method while another thread may be simultaneously calling another Network Caputre related method, including this one.
See also
network_capture::disable()
Note
This is a standalone function in the namespace rti::util::network_capture

Referenced by dds::core::policy::Presentation::access_scope(), rti::queuing::QueueConsumerParams::enable_availability(), rti::queuing::QueueRequesterParams::enable_availability(), rti::queuing::QueueReplierParams::enable_availability(), rti::queuing::QueueProducerParams::enable_sample_replication(), rti::queuing::QueueRequesterParams::enable_sample_replication(), rti::queuing::QueueReplierParams::enable_sample_replication(), rti::queuing::QueueProducerParams::enable_wait_for_ack(), rti::queuing::QueueRequesterParams::enable_wait_for_ack(), rti::queuing::QueueReplierParams::enable_wait_for_ack(), and rti::core::policy::TopicQueryDispatch::TopicQueryDispatch().

◆ disable()

bool rti::util::network_capture::disable ( )

Disable Network Capture.

This method must be the last Network Capture method to be called. It must also be called after deleting the participants for which we captured traffic. Disabling Network Capture without stopping it first is not ok!

Returns
true if success. Otherwise, false
MT Safety:
UNSAFE. It is not safe to call this method while another thread may be simultaneously calling another Network Capture related method, including this one.
See also
network_capture::enable()
Note
This is a standalone function in the namespace rti::util::network_capture

◆ set_default_params()

bool rti::util::network_capture::set_default_params ( const NetworkCaptureParams params)

Set the default Network Capture parameters.

The default parameters are used when Network Capture is started without parameters, i.e., network_capture::start().

Precondition
This method requires first enabling Network Capture. See network_capture::enable().
Parameters
params<<in>>. Configuration parameters that we want to set as defaults.
Returns
true if success. Otherwise, false
See also
network_capture::start()
network_capture::start(dds::domain::DomainParticipant, const std::string &)
Note
This is a standalone function in the namespace rti::util::network_capture

◆ start() [1/4]

bool rti::util::network_capture::start ( const std::string &  filename)

Start Network Capture.

Precondition
This method requires first enabling Network Capture. See network_capture::enable().
Parameters
filename<<in>>. The name of the output capture file will be based on this input parameter.

In particular, the name for the capture file is the concatenation of the filename input parameter, the "_GUID-" string followed by the decimal representation of bytes 8-11 of the DomainParticipant's GUID, and the file extension (".pcap").

Returns
true if success. Otherwise, false
See also
network_capture::stop()
network_capture::start(dds::domain::DomainParticipant, const std::string &)
Note
This is a standalone function in the namespace rti::util::network_capture

◆ start() [2/4]

bool rti::util::network_capture::start ( dds::domain::DomainParticipant  participant,
const std::string &  filename 
)

Start Network Capture for a participant.

Precondition
This method requires first enabling Network Capture. See network_capture::enable().
Parameters
participant<<in>>. DomainParticipant for which we want to capture traffic.
filename<<in>>. The name of the output capture file will be based on this input parameter.

In particular, the name for the capture file is the concatenation of the filename input parameter, and the file extension (".pcap").

Returns
true if success. Otherwise, false
See also
network_capture::stop()
network_capture::start(dds::domain::DomainParticipant, const std::string &, const NetworkCaptureParams &)
network_capture::enable()
Note
This is a standalone function in the namespace rti::util::network_capture

◆ start() [3/4]

bool rti::util::network_capture::start ( const std::string &  filename,
const NetworkCaptureParams params 
)

Start Network Capture with parameters.

Precondition
This method requires first enabling Network Capture. See network_capture::enable().

Perfoms the same function as network_capture::start() except that it uses the provided parameters, instead of the default ones.

Parameters
filename<<in>>. The name of the output capture file will be based on this input parameter.

In particular, the name for the capture file is the concatenation of the filename input parameter, the "_GUID-" string followed by the decimal representation of bytes 8-11 of the DomainParticipant's GUID, and the file extension (".pcap").

Parameters
params<<in>>. Configuration parameters for the capture.
Returns
true if success. Otherwise, false
See also
network_capture::stop()
network_capture::start(dds::domain::DomainParticipant, const std::string &, const NetworkCaptureParams &)
Note
This is a standalone function in the namespace rti::util::network_capture

◆ start() [4/4]

bool rti::util::network_capture::start ( dds::domain::DomainParticipant  participant,
const std::string &  filename,
const NetworkCaptureParams params 
)

Start Network Capture with parameters for a participant.

Precondition
This method requires enabling first Network Capture. See network_capture::enable().
Parameters
participant<<in>>. DomainParticipant for which we want to capture traffic.
filename<<in>>. The name of the output capture file will be based on this input parameter.

In particular, the name for the capture file is the concatenation of the filename input parameter, and the file extension (".pcap").

Parameters
params<<in>>. Parameters for configuring the capture.
Returns
true if success. Otherwise, false
See also
network_capture::stop()
network_capture::start(dds::domain::DomainParticipant, const std::string &)
Note
This is a standalone function in the namespace rti::util::network_capture

◆ stop() [1/2]

bool rti::util::network_capture::stop ( )

Stop Network Capture.

Precondition
This method requires enabling first Network Capture. See network_capture::enable().

This method can (and must) be called after network_capture::start(), not network_capture::start(dds::domain::DomainParticipant, const std::string &). That is, if we start capturing traffic globally (for all DomainParticipants), we must stop capturing traffic also globally. It is not possible to start capturing traffic for a participant but stop it globally.

It is possible to start capturing globally and then stop capturing for a participant, as long as we eventually stop capturing traffic globally.

We must stop capturing for a participant before deleting it.

Returns
true if success. Otherwise, false
See also
network_capture::start()
network_capture::stop()
Note
This is a standalone function in the namespace rti::util::network_capture

◆ stop() [2/2]

bool rti::util::network_capture::stop ( dds::domain::DomainParticipant  participant)

Stop Network Capture.

Precondition
This method requires first enabling Network Capture. See network_capture::enable().
Parameters
participant<<in>>. DomainParticipant for which we want to stop capturing traffic.
Returns
true if success. Otherwise, false
See also
network_capture::start(dds::domain::DomainParticipant, const std::string &)
network_capture::stop()
Note
This is a standalone function in the namespace rti::util::network_capture

◆ pause() [1/2]

bool rti::util::network_capture::pause ( )

Pause Network Capture.

Precondition
This method requires first enabling Network Capture. See network_capture::enable().
Returns
true if success. Otherwise, false
See also
network_capture::resume()
network_capture::pause()
Note
This is a standalone function in the namespace rti::util::network_capture

◆ pause() [2/2]

bool rti::util::network_capture::pause ( dds::domain::DomainParticipant  participant)

Pause Network Capture.

Precondition
This method requires first enabling Network Capture. See network_capture::enable().
Parameters
participant<<in>>. DomainParticipant for which we want to pause capturing traffic.
Returns
true if success. Otherwise, false
See also
network_capture::resume()
network_capture::pause()
Note
This is a standalone function in the namespace rti::util::network_capture

◆ resume() [1/2]

bool rti::util::network_capture::resume ( )

Resume Network Capture.

Precondition
This method requires first enabling Network Capture. See network_capture::enable().
Returns
true if success. Otherwise, false
See also
network_capture::pause()
network_capture::resume()
Note
This is a standalone function in the namespace rti::util::network_capture

◆ resume() [2/2]

bool rti::util::network_capture::resume ( dds::domain::DomainParticipant  participant)

Resume Network Capture.

Precondition
This method requires first enabling Network Capture. See network_capture::enable().
Parameters
participant<<in>>. DomainParticipant for which we want to resume capturing traffic.
Returns
true if success. Otherwise, false
See also
network_capture::pause()
network_capture::resume()
Note
This is a standalone function in the namespace rti::util::network_capture