Network Capture

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

Data Structures
struct	NDDS_Utility_NetworkCaptureParams_t
	Input parameters for starting network capture. 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...

Functions
DDS_Boolean	NDDS_Utility_enable_network_capture (void)
	Enable Network Capture. More...
DDS_Boolean	NDDS_Utility_disable_network_capture (void)
	Disable Network Capture. More...
DDS_Boolean	NDDS_Utility_set_default_network_capture_params (const NDDS_Utility_NetworkCaptureParams_t *params)
	Set the default Network Capture parameters. More...
DDS_Boolean	NDDS_Utility_start_network_capture (const char *filename)
	Start capturing traffic for all DomainParticipants, with the default parameters. More...
DDS_Boolean	NDDS_Utility_start_network_capture_for_participant (DDS_DomainParticipant *participant, const char *filename)
	Start capturing traffic for a DomainParticipant, with the default parameters. More...
DDS_Boolean	NDDS_Utility_start_network_capture_w_params (const char *filename, const NDDS_Utility_NetworkCaptureParams_t *params)
	Start capturing traffic for all DomainParticipants, with the provided parameters. More...
DDS_Boolean	NDDS_Utility_start_network_capture_w_params_for_participant (DDS_DomainParticipant *participant, const char *filename, const NDDS_Utility_NetworkCaptureParams_t *params)
	Start capturing traffic for a DomainParticipant, with the provided parameters. More...
DDS_Boolean	NDDS_Utility_stop_network_capture (void)
	Stop capturing traffic for all participants. More...
DDS_Boolean	NDDS_Utility_stop_network_capture_for_participant (DDS_DomainParticipant *participant)
	Stop capturing traffic for a DomainParticipant. More...
DDS_Boolean	NDDS_Utility_pause_network_capture (void)
	Pause capturing traffic for all DomainParticipants. More...
DDS_Boolean	NDDS_Utility_pause_network_capture_for_participant (DDS_DomainParticipant *participant)
	Pause capturing traffic for a DomainParticipant. More...
DDS_Boolean	NDDS_Utility_resume_network_capture (void)
	Resume capturing traffic for all DomainParticipants. More...
DDS_Boolean	NDDS_Utility_resume_network_capture_for_participant (DDS_DomainParticipant *participant)
	Resume capturing traffic for a DomainParticipant. 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 NDDS_Utility_enable_network_capture must be invoked before creating any DomainParticipant. Similarly, NDDS_Utility_disable_network_capture 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{Domain=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_IN).

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.

Function Documentation

NDDS_Utility_enable_network_capture()

DDS_Boolean NDDS_Utility_enable_network_capture

(

void

)

Enable Network Capture.

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

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

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

MT Safety:

UNSAFE. It is not safe to call this function while another thread may be simultaneously calling another Network Caputre related function, including this one.

MT Safety:

UNSAFE. In VxWorks, it is unsafe to call this function while another thread may be simulatenously calling DDS_DomainParticipantFactory_get_instance, DDS_DomainParticipantFactory_finalize_instance, DDS_TypeCodeFactory_get_instance, DDS_TypeCodeFactory_finalize_instance, NDDS_Utility_enable_network_capture, or NDDS_Utility_disable_network_capture.

See also

NDDS_Utility_disable_network_capture

NDDS_Utility_disable_network_capture()

DDS_Boolean NDDS_Utility_disable_network_capture

(

void

)

Disable Network Capture.

This function must be the last Network Capture function 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

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

MT Safety:

UNSAFE. It is not safe to call this function while another thread may be simultaneously calling another Network Capture related function, including this one.

MT Safety:

UNSAFE. In VxWorks, it is unsafe to call this function while another thread may be simulatenously calling DDS_DomainParticipantFactory_get_instance, DDS_DomainParticipantFactory_finalize_instance, DDS_TypeCodeFactory_get_instance, DDS_TypeCodeFactory_finalize_instance, NDDS_Utility_enable_network_capture, or NDDS_Utility_disable_network_capture.

See also

NDDS_Utility_enable_network_capture

NDDS_Utility_set_default_network_capture_params()

DDS_Boolean NDDS_Utility_set_default_network_capture_params

(

const NDDS_Utility_NetworkCaptureParams_t *

params

)

Set the default Network Capture parameters.

The default parameters are used when Network Capture is started without parameters, i.e., NDDS_Utility_start_network_capture.

Precondition

This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.

Parameters

params

<<in>>. Configuration parameters that we want to set as defaults.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_start_network_capture

NDDS_Utility_start_network_capture_for_participant

NDDS_Utility_start_network_capture()

DDS_Boolean NDDS_Utility_start_network_capture

(

const char *

filename

)

Start capturing traffic for all DomainParticipants, with the default parameters.

Precondition

This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.

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

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_stop_network_capture

NDDS_Utility_start_network_capture_for_participant

NDDS_Utility_start_network_capture_for_participant()

DDS_Boolean NDDS_Utility_start_network_capture_for_participant	(	DDS_DomainParticipant *	participant,
		const char *	filename
	)

Start capturing traffic for a DomainParticipant, with the default parameters.

Precondition

This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.

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

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_stop_network_capture_for_participant

NDDS_Utility_start_network_capture_w_params_for_participant

NDDS_Utility_enable_network_capture

NDDS_Utility_start_network_capture_w_params()

DDS_Boolean NDDS_Utility_start_network_capture_w_params	(	const char *	filename,
		const NDDS_Utility_NetworkCaptureParams_t *	params
	)

Start capturing traffic for all DomainParticipants, with the provided parameters.

Precondition

This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.

Perfoms the same function as NDDS_Utility_start_network_capture 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

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_stop_network_capture

NDDS_Utility_start_network_capture_w_params_for_participant

NDDS_Utility_start_network_capture_w_params_for_participant()

DDS_Boolean NDDS_Utility_start_network_capture_w_params_for_participant	(	DDS_DomainParticipant *	participant,
		const char *	filename,
		const NDDS_Utility_NetworkCaptureParams_t *	params
	)

Start capturing traffic for a DomainParticipant, with the provided parameters.

Precondition

This function requires enabling first Network Capture. See NDDS_Utility_enable_network_capture.

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

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_stop_network_capture_for_participant

NDDS_Utility_start_network_capture_for_participant

NDDS_Utility_stop_network_capture()

DDS_Boolean NDDS_Utility_stop_network_capture

(

void

)

Stop capturing traffic for all participants.

Precondition

This function requires enabling first Network Capture. See NDDS_Utility_enable_network_capture.

This function can (and must) be called after NDDS_Utility_start_network_capture, not NDDS_Utility_start_network_capture_for_participant. 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

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_start_network_capture

NDDS_Utility_stop_network_capture_for_participant

NDDS_Utility_stop_network_capture_for_participant()

DDS_Boolean NDDS_Utility_stop_network_capture_for_participant

(

DDS_DomainParticipant *

participant

)

Stop capturing traffic for a DomainParticipant.

Precondition

This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.

Parameters

participant

<<in>>. DomainParticipant for which we want to stop capturing traffic.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_start_network_capture_for_participant

NDDS_Utility_stop_network_capture

NDDS_Utility_pause_network_capture()

DDS_Boolean NDDS_Utility_pause_network_capture

(

void

)

Pause capturing traffic for all DomainParticipants.

Precondition

This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_resume_network_capture

NDDS_Utility_pause_network_capture_for_participant

NDDS_Utility_pause_network_capture_for_participant()

DDS_Boolean NDDS_Utility_pause_network_capture_for_participant

(

DDS_DomainParticipant *

participant

)

Pause capturing traffic for a DomainParticipant.

Precondition

This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.

Parameters

participant

<<in>>. DomainParticipant for which we want to pause capturing traffic.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_resume_network_capture_for_participant

NDDS_Utility_pause_network_capture

NDDS_Utility_resume_network_capture()

DDS_Boolean NDDS_Utility_resume_network_capture

(

void

)

Resume capturing traffic for all DomainParticipants.

Precondition

This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_pause_network_capture

NDDS_Utility_resume_network_capture_for_participant

NDDS_Utility_resume_network_capture_for_participant()

DDS_Boolean NDDS_Utility_resume_network_capture_for_participant

(

DDS_DomainParticipant *

participant

)

Resume capturing traffic for a DomainParticipant.

Precondition

This function requires first enabling Network Capture. See NDDS_Utility_enable_network_capture.

Parameters

participant

<<in>>. DomainParticipant for which we want to resume capturing traffic.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_pause_network_capture_for_participant

NDDS_Utility_resume_network_capture

Variable Documentation

NDDS_UTILITY_NETWORK_CAPTURE_PARAMETERS_DEFAULT

const NDDS_Utility_NetworkCaptureParams_t NDDS_UTILITY_NETWORK_CAPTURE_PARAMETERS_DEFAULT

extern

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 function:

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.