Performing a packet trace on a Citrix ADC VPX appliance

A Citrix ADC appliance provides a NITRO API object called nstrace to get a dump of the packets that are received and sent out by the appliance. The API stores the packets in trace files. You can use these files to debug problems in the flow of packets in the Citrix ADC appliance. The trace files must be viewed with the Wireshark application.

Some salient aspects of the nstrace NITRO API object are:

• Can be configured to trace packets selectively by using classic expressions and default expressions.
• Can capture the trace in multiple formats: ns trace format (.cap) and TCP dump format (.pcap).

Before you begin

Before performing a packet trace on a Citrix ADC VPX appliance, note the following points:

• Make sure that you have deployed a Citrix ADC VPX appliance and the appliance is UP and running in your setup. For more information, see Deploy a Citrix ADC VPX instance.

• Make sure that you have a basic understanding of the nstrace feature of a Citrix ADC appliance. For more information, see:
  • How to record a packet trace on Citrix ADC.

• Make sure that you have a basic understanding of the Citrix ADC NITRO REST APIs. For more information, see Citrix ADC NITRO API reference.

• nstrace NITRO API is not available in the Java, C#, and Python SDKs.

Best practices

On a Citrix ADC appliance handling high volume of traffic per second, capturing traffic is a very resource intensive process. The impact to resources is mainly in terms of the CPU and the disk space. Disk space impact can be reduced by using filtering expressions. However, the impact on the CPU remains and sometimes causes a slight increase as the appliance now needs to process packets according to the filter before capturing them.

The best practices about packet tracing are:

• The duration for which the trace is run must be as limited as possible when you still ensure the packets of interest are captured.
• Schedule the tracing activity to happen at a time when the number of users (and hence the traffic) is greatly reduced, such as during off hours.

Steps for performing a packet trace

Performing a packet trace on a Citrix ADC VPX appliance consists of the following steps:

1. Start recording a packet trace
2. Retrieve the current state information of the packet trace recording
3. Stop recording a packet trace

Start recording a packet trace

To start recording a packet trace, you use the nstrace NITRO API object with action as start.

Packet traces are recorded in files in the /var/nstrace/<date-timestamp> directory of the appliance. The packet trace file name is of the form nstrace<id>.cap, where id is always 1 for a standalone appliance. In other words, packet trace file with the same name nstrace1.cap is always generated for a standalone appliance.

For more information about the nstrace object and its properties, see Citrix NITRO API reference for nstrace.

Request components

Curl request

curl -X POST -H "Content-Type: application/json" -u nsroot:examplepassword http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nstrace?action=start  -d '{"nstrace":{"size":<value>, "mode":<value>, ... }}'
<!--NeedCopy-->

Example

curl -X POST -H "Content-Type: application/json" -u nsroot:examplepassword http://192.0.0.33/nitro/v1/config/nstrace?action=start  -d '{"nstrace":{"size":0}}'
<!--NeedCopy-->

Retrieve the current state information of the packet trace recording

To retrieve the current state information of the packet trace recording, you use the nstrace NITRO API object along with HTTP method as GET.

The Citrix ADC appliance responds with the following information:

• state. This attribute shows the current state information of the packet trace recording. Possible values: RUNNING, STOPPED
• Other attributes settings that are used in the current packet trace recording in running state. If the packet trace recording is not running(state shown as STOPPED), default settings are shown for the attributes.

For more information about the nstrace object and its properties, see Citrix NITRO API reference for nstrace.

Request components

Curl request

curl -X GET -H "Content-Type: application/json" -u nsroot:examplepassword http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nstrace
<!--NeedCopy-->

Examples

Stop recording a packet trace

To stop recording a packet trace, you use the nstrace NITRO API object with action as stop.

For more information about the nstrace object and its properties, see Citrix NITRO API reference for nstrace.

Request components

Curl request

curl -X POST -H "Content-Type: application/json" -u nsroot:examplepassword http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nstrace?action=stop  -d '{"nstrace":{}}'
<!--NeedCopy-->

Example

curl -X POST -H "Content-Type: application/json" -u nsroot:examplepassword    -d '{"nstrace":{}}'
<!--NeedCopy-->