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: -
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:
- Start recording a packet trace
- Retrieve the current state information of the packet trace recording
- 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
Request field | Value |
---|---|
HTTP Method | POST |
URL | http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nstrace?action=start |
Request Headers | Content-Type: application/json |
Request Payload |
{"nstrace":{"size":<value>, "mode":<value>, ... }} Example: {"nstrace":{"size":0}}
|
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>, ... }}'
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}}'
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
Request field | Value |
---|---|
HTTP Method | GET |
URL | http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nstrace |
Request Headers | Content-Type: application/json |
Curl request
curl -X GET -H "Content-Type: application/json" -u nsroot:examplepassword http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nstrace
Examples
Example description | Curl request | Response payload |
---|---|---|
Retrieve the current state information and other attribute settings of the packet trace recording in a Citrix ADC appliance, which has Citrix ADC IP address (NSIP) of 192.0.0.33. | curl -X GET -H "Content-Type: application/json" -u nsroot:examplepassword http://192.0.0.33/nitro/v1/config/nstrace |
{ “errorcode”: 0, “message”: “Done”, “severity”: “NONE”, “nstrace”: { “state”: “RUNNING”, “scope”: “LOCAL”, “tracelocation”: “/var/nstrace/18Feb2021_20_08_25/…”, “nf”: “24”, “time”: “3600”, “size”: “0”, “mode”: [ “TXB”, “NEW_RX” ], “traceformat”: “NSCAP”, “pernic”: “DISABLED”, “filename”: “18Feb2021_20_08_25”, “link”: “DISABLED”, “merge”: “ONSTOP”, “doruntimecleanup”: “ENABLED”, “tracebuffers”: “5000”, “skiprpc”: “DISABLED”, “skiplocalssh”: “DISABLED”, “capsslkeys”: “DISABLED”, “capdroppkt”: “DISABLED”, “inmemorytrace”: “DISABLED” } } |
Retrieve only the current state information of the packet trace recording in a Citrix ADC appliance, which has Citrix ADC IP address (NSIP) of 192.0.0.33. | curl -X GET -H "Content-Type: application/json" -u nsroot:examplepassword http://192.0.0.33/nitro/v1/config/nstrace |
{ “errorcode”: 0, “message”: “Done”, “severity”: “NONE”, “nstrace”: { “state”: “RUNNING” } } |
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
Request field | Value |
---|---|
HTTP Method | POST |
URL | http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nstrace?action=stop |
Request Headers | Content-Type: application/json |
Request Payload | {"nstrace":{}} |
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":{}}'
Example
curl -X POST -H "Content-Type: application/json" -u nsroot:examplepassword -d '{"nstrace":{}}'