Network Capture

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

Classes
struct	NDDS_Utility_NetworkCaptureParams_t
	Input parameters for starting network capture. More...
class	NDDSUtilityNetworkCapture
	Network Capture APIs. More...

Macros
#define	NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_DEFAULT
	Default mask for NDDS_Utility_NetworkCaptureContentKind: do not remove any content. More...
#define	NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_NONE
	The RTPS frames in the capture file will be saved as they are. More...
#define	NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_ALL
	The RTPS frames in the capture file will not include user data (either plain or encrypted). More...
#define	NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_DEFAULT
	Default mask for NDDS_Utility_NetworkCaptureTrafficKindMask. More...
#define	NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_NONE
	Do not capture any traffic. More...
#define	NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_ALL
	Capture all traffic (both inbound and outbound). More...

Typedefs
typedef DDS_Long	NDDS_Utility_NetworkCaptureContentKindMask
	Mask that indicates a combination of content types. More...
typedef DDS_Long	NDDS_Utility_NetworkCaptureTrafficKindMask
	Mask that indicates the traffic direction to capture. More...
typedef struct NDDS_Utility_NetworkCaptureParams_t	NDDS_Utility_NetworkCaptureParams_t
	Input parameters for starting network capture. More...

Enumerations
enum	NDDS_Utility_NetworkCaptureContentKind {   NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_USER_SERIALIZED_DATA,   NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_ENCRYPTED_DATA }
	Bitmap used to specify a content type, i.e., a part of the RTPS frame. More...
enum	NDDS_Utility_NetworkCaptureTrafficKind {   NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_OUT,   NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_IN }
	Bitmap used to specify whether we want to capture inbound or outbound traffic. More...

Variables
const NDDS_Utility_NetworkCaptureParams_t	NDDS_UTILITY_NETWORK_CAPTURE_PARAMETERS_DEFAULT
	Default parameters used in 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 NDDSUtilityNetworkCapture::enable must be invoked before creating any DomainParticipant. Similarly, NDDSUtilityNetworkCapture::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 DDS_PropertyQosPolicy).

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

Macro Definition Documentation

NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_DEFAULT

#define NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_DEFAULT

Default mask for NDDS_Utility_NetworkCaptureContentKind: do not remove any content.

It is equivalent to NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_NONE.

[default] Do not remove any content.

NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_NONE

#define NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_NONE

The RTPS frames in the capture file will be saved as they are.

NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_ALL

#define NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_MASK_ALL

The RTPS frames in the capture file will not include user data (either plain or encrypted).

Its value is the result of setting the bits for removing user data and removing encrypted data: (NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_USER_SERIALIZED_DATA) | NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_ENCRYPTED_DATA)

NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_DEFAULT

#define NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_DEFAULT

Default mask for NDDS_Utility_NetworkCaptureTrafficKindMask.

It is equivalent to NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_ALL.

[default] Capture all traffic: inbound and outbound.

NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_NONE

#define NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_NONE

Do not capture any traffic.

NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_ALL

#define NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_MASK_ALL

Capture all traffic (both inbound and outbound).

The value is equal to setting both the input and output bits of the mask: (NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_OUT | NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_OUT).

Typedef Documentation

NDDS_Utility_NetworkCaptureContentKindMask

typedef DDS_Long NDDS_Utility_NetworkCaptureContentKindMask

Mask that indicates a combination of content types.

The masks are based on a combination (or only one) of the NDDS_Utility_NetworkCaptureContentKind bitmaps.

See also

NDDS_Utility_NetworkCaptureContentKind

NDDS_Utility_NetworkCaptureTrafficKindMask

typedef DDS_Long NDDS_Utility_NetworkCaptureTrafficKindMask

Mask that indicates the traffic direction to capture.

The masks are based on a combination (or only one) of the NDDS_Utility_NetworkCaptureTrafficKind bitmaps.

See also

NDDS_Utility_NetworkCaptureTrafficKind

NDDS_Utility_NetworkCaptureParams_t

typedef struct NDDS_Utility_NetworkCaptureParams_t NDDS_Utility_NetworkCaptureParams_t

Input parameters for starting network capture.

Enumeration Type Documentation

NDDS_Utility_NetworkCaptureContentKind

enum NDDS_Utility_NetworkCaptureContentKind

Bitmap used to specify a content type, i.e., a part of the RTPS frame.

Several values can be combined. Read NDDS_Utility_NetworkCaptureContentKindMask for typical combinations.

Enumerator
NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_USER_SERIALIZED_DATA	The serialized data coming from a user.
NDDS_UTILITY_NETWORK_CAPTURE_CONTENT_ENCRYPTED_DATA	The encrypted user data.

NDDS_Utility_NetworkCaptureTrafficKind

enum NDDS_Utility_NetworkCaptureTrafficKind

Bitmap used to specify whether we want to capture inbound or outbound traffic.

Several values can be combined. Read NDDS_Utility_NetworkCaptureTrafficKindMask for typical combinations.

Enumerator
NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_OUT	Do not capture outbound traffic.
NDDS_UTILITY_NETWORK_CAPTURE_TRAFFIC_IN	Do not capture inbound traffic.

Variable Documentation

NDDS_UTILITY_NETWORK_CAPTURE_PARAMETERS_DEFAULT

const NDDS_Utility_NetworkCaptureParams_t NDDS_UTILITY_NETWORK_CAPTURE_PARAMETERS_DEFAULT

Default parameters used in Network Capture.

The default parameters can be used as initilizers to ensure that new objects do not have uninitialized contents.

Initialization of a NDDS_Utility_NetworkCaptureParams_t type can be done either by assigning to the default parameters:

struct NDDS_Utility_NetworkCaptureParams_t params = NDDS_UTILITY_NETWORK_CAPTURE_PARAMETERS_DEFAULT;                 

Or equivalently, by using its initializer method:

struct NDDS_Utility_NetworkCaptureParams_t params;
 NDDS_Utility_NetworkCaptureParams_t_initialize(&params);                 

In either case, do not forget to finalize the parameters when you don't need them any more:

NDDS_Utility_NetworkCaptureParams_t_finalize(&params);                 

The values that are used by default for the parameters can be found in the description of each of the members in NDDS_Utility_NetworkCaptureParams_t.