netscaler.adc.nstrace module – Configuration for nstrace operations resource.

Note

This module is part of the netscaler.adc collection (version 2.6.2).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install netscaler.adc.

To use it in a playbook, specify: netscaler.adc.nstrace.

New in netscaler.adc 2.0.0

Synopsis

  • Configuration for nstrace operations resource.

Parameters

Parameter

Comments

api_path

string

Base NITRO API path.

Define only in case of an ADM service proxy call

Default: "nitro/v1/config"

capdroppkt

string

Captures Dropped Packets if set to ENABLED.

Choices:

  • "ENABLED"

  • "DISABLED"

capsslkeys

string

Capture SSL Master keys. Master keys will not be captured on FIPS machine.

Warning: The captured keys can be used to decrypt information that may be confidential. The captured key files have to be stored in a secure environment

Choices:

  • "ENABLED"

  • "DISABLED"

doruntimecleanup

string

Enable or disable runtime temp file cleanup

Choices:

  • "ENABLED"

  • "DISABLED"

fileid

string

ID for the trace file name for uniqueness. Should be used only with -name option.

filename

string

Name of the trace file.

filesize

float

File size, in MB, treshold for rollover. If free disk space is less than 2GB at the time of rollover, trace will stop

filter

string

Filter expression for nstrace. Maximum length of filter is 255 and it can be of following format:

<expression> [<relop> <expression>]

<relop> = ( && | || )

<expression> =:

CONNECTION.<qualifier>.<qualifier-method>.(<qualifier-value>)

<qualifier> = SRCIP

<qualifier-method> = [ EQ | NE ]

<qualifier-value> = A valid IPv4 address.

example = CONNECTION.SRCIP.EQ(127.0.0.1)

<qualifier> = DSTIP

<qualifier-method> = [ EQ | NE ]

<qualifier-value> = A valid IPv4 address.

example = CONNECTION.DSTIP.EQ(127.0.0.1)

<qualifier> = IP

<qualifier-method> = [ EQ | NE ]

<qualifier-value> = A valid IPv4 address.

example = CONNECTION.IP.EQ(127.0.0.1)

<qualifier> = SRCIPv6

<qualifier-method> = [ EQ | NE ]

<qualifier-value> = A valid IPv6 address.

example = CONNECTION.SRCIPv6.EQ(2001:db8:0:0:1::1)

<qualifier> = DSTIPv6

<qualifier-method> = [ EQ | NE ]

<qualifier-value> = A valid IPv6 address.

example = CONNECTION.DSTIPv6.EQ(2001:db8:0:0:1::1)

<qualifier> = IPv6

<qualifier-method> = [ EQ | NE ]

<qualifier-value> = A valid IPv6 address.

example = CONNECTION.IPv6.EQ(2001:db8:0:0:1::1)

<qualifier> = SRCPORT

<qualifier-method> = [ EQ | NE | GT | GE | LT | LE

BETWEEN ]

<qualifier-value> = A valid port number.

example = CONNECTION.SRCPORT.EQ(80)

<qualifier> = DSTPORT

<qualifier-method> = [ EQ | NE | GT | GE | LT | LE

BETWEEN ]

<qualifier-value> = A valid port number.

example = CONNECTION.DSTPORT.EQ(80)

<qualifier> = PORT

<qualifier-method> = [ EQ | NE | GT | GE | LT | LE

BETWEEN ]

<qualifier-value> = A valid port number.

example = CONNECTION.PORT.EQ(80)

<qualifier> = VLANID

<qualifier-method> = [ EQ | NE | GT | GE | LT | LE

BETWEEN ]

<qualifier-value> = A valid VLAN ID.

example = CONNECTION.VLANID.EQ(0)

<qualifier> = CONNID

<qualifier-method> = [ EQ | NE | GT | GE | LT | LE

BETWEEN ]

<qualifier-value> = A valid PCB dev number.

example = CONNECTION.CONNID.EQ(0)

<qualifier> = PPEID

<qualifier-method> = [ EQ | NE | GT | GE | LT | LE

BETWEEN ]

<qualifier-value> = A valid core ID.

example = CONNECTION.PPEID.EQ(0)

<qualifier> = SVCNAME

<qualifier-method> = [ EQ | NE | CONTAINS | STARTSWITH

ENDSWITH ]

<qualifier-value> = A valid text string.

example = CONNECTION.SVCNAME.EQ(“name”)

<qualifier> = LB_VSERVER.NAME

<qualifier-method> = [ EQ | NE | CONTAINS | STARTSWITH

ENDSWITH ]

<qualifier-value> = LB vserver name.

example = CONNECTION.LB_VSERVER.NAME.EQ(“name”)

<qualifier> = CS_VSERVER.NAME

<qualifier-method> = [ EQ | NE | CONTAINS | STARTSWITH

ENDSWITH ]

<qualifier-value> = CS vserver name.

example = CONNECTION.CS_VSERVER.NAME.EQ(“name”)

<qualifier> = INTF

<qualifier-method> = [ EQ | NE ]

<qualifier-value> = A valid interface id in the

form of x/y.

example = CONNECTION.INTF.EQ(“x/y”)

<qualifier> = SERVICE_TYPE

<qualifier-method> = [ EQ | NE ]

<qualifier-value> = ( SVC_HTTP | FTP | TCP | UDP | SSL |

SSL_BRIDGE | SSL_TCP | NNTP | RPCSVR | RPCSVRS |

RPCCLNT | SVC_DNS | ADNS | SNMP | RTSP | DHCPRA | ANY|

MONITOR | MONITOR_UDP | MONITOR_PING | SIP_UDP |

SVC_MYSQL | SVC_MSSQL | FIX | SSL_FIX | PKTSTEER |

SVC_AAA | SERVICE_UNKNOWN )

example = CONNECTION.SERVICE_TYPE.EQ(ANY)

<qualifier> = TRAFFIC_DOMAIN_ID

<qualifier-method> = [ EQ | NE | GT | GE | LT | LE

BETWEEN ]

<qualifier-value> = A valid traffic domain ID.

example = CONNECTION.TRAFFIC_DOMAIN_ID.EQ(0)

eg: start nstrace -filter “CONNECTION.SRCIP.EQ(127.0.0.1) || (CONNECTION.SVCNAME.NE(“s1”) && CONNECTION.SRCPORT.EQ(80))”

The filter expression should be given in double quotes.

common use cases:

Trace capturing full sized traffic from/to ip 10.102.44.111, excluding loopback traffic

start nstrace -size 0 -filter “CONNECTION.IP.NE(127.0.0.1) && CONNECTION.IP.EQ(10.102.44.111)”

Trace capturing all traffic to (terminating at) port 80 or 443

start nstrace -size 0 -filter “CONNECTION.DSTPORT.EQ(443) || CONNECTION.DSTPORT.EQ(80)”

Trace capturing all backend traffic specific to service service1 along with corresponding client side traffic

start nstrace -size 0 -filter “CONNECTION.SVCNAME.EQ(“service1”)” -link ENABLED

Trace capturing all traffic through Citrix ADC interface 1/1

start nstrace -filter “CONNECTION.INTF.EQ(“1/1”)”

Trace capturing all traffic specific through vlan 2

start nstrace -filter “CONNECTION.VLANID.EQ(2)”

Trace capturing all frontend (client side) traffic specific to lb vserver vserver1 along with corresponding server side traffic

start nstrace -size 0 -filter “CONNECTION.LB_VSERVER.NAME.EQ(“vserver1”)” -link ENABLED

inmemorytrace

string

Logs packets in appliance’s memory and dumps the trace file on stopping the nstrace operation

Choices:

  • "ENABLED"

  • "DISABLED"

string

Includes filtered connection’s peer traffic.

Choices:

  • "ENABLED"

  • "DISABLED"

managed_netscaler_instance_id

string

added in netscaler.adc 2.6.0

The ID of the managed NetScaler instance to which NetScaler Console

has to configure as a proxy server.

Define only in case of an ADM service proxy call

managed_netscaler_instance_ip

string

added in netscaler.adc 2.6.0

The IP of the managed NetScaler instance to which NetScaler Console

has to configure as a proxy server.

Define only in case of an ADM service proxy call

managed_netscaler_instance_name

string

added in netscaler.adc 2.6.0

The name of the managed NetScaler instance to which NetScaler Console

has to configure as a proxy server.

Define only in case of an ADM service proxy call

managed_netscaler_instance_password

string

added in netscaler.adc 2.6.0

The password of the managed NetScaler instance.

Define only in case of an ADM service proxy call

In Settings > Administration > System Configurations > Basic Settings,

if you select Prompt Credentials for Instance Login,

ensure to configure username and password of a managed instance.

managed_netscaler_instance_username

string

added in netscaler.adc 2.6.0

The username of the managed NetScaler instance.

Define only in case of an ADM service proxy call

In Settings > Administration > System Configurations > Basic Settings,

if you select Prompt Credentials for Instance Login,

ensure to configure username and password of a managed instance.

merge

string

Specify how traces across PE’s are merged

Choices:

  • "ONSTOP"

  • "ONTHEFLY"

  • "NOMERGE"

mode

list / elements=string

Capturing mode for trace. Mode can be any of the following values or combination of these values:

RX Received packets before NIC pipelining (Filter does not work when RX capturing mode is ON)

NEW_RX Received packets after NIC pipelining

TX Transmitted packets

TXB Packets buffered for transmission

IPV6 Translated IPv6 packets

C2C Capture C2C message

NS_FR_TX TX/TXB packets are not captured in flow receiver.

MPTCP MPTCP master flow

HTTP_QUIC HTTP-over-QUIC stream data and stream events

Default mode: NEW_RX TXB

Choices:

  • "TX"

  • "TXB"

  • "RX"

  • "IPV6"

  • "NEW_RX"

  • "C2C"

  • "NS_FR_TX"

  • "APPFW"

  • "MPTCP"

  • "PolicyBased"

  • "HTTP_QUIC"

netscaler_console_as_proxy_server

boolean

added in netscaler.adc 2.6.0

The IP address of the NetScaler ADC appliance acting as a proxy server.

Define only in case of an ADM service proxy call

Choices:

  • false ← (default)

  • true

nf

float

Number of files to be generated in cycle.

nitro_auth_token

string

The authentication token provided by a login operation.

nitro_pass

string

The password with which to authenticate to the NetScaler ADC node.

nitro_protocol

string

Which protocol to use when accessing the nitro API objects.

Choices:

  • "http"

  • "https" ← (default)

nitro_user

string

The username with which to authenticate to the NetScaler ADC node.

nodeid

float

Unique number that identifies the cluster node.

nodes

list / elements=integer

Nodes on which tracing is started.

nsip

string / required

The ip address of the NetScaler ADC appliance where the nitro API calls will be made.

The port can be specified with the colon (:). E.g. 192.168.1.1:555.

pernic

string

Use separate trace files for each interface. Works only with cap format.

Choices:

  • "ENABLED"

  • "DISABLED"

save_config

boolean

If true the module will save the configuration on the NetScaler ADC node if it makes any changes.

The module will not save the configuration on the NetScaler ADC node if it made no changes.

Choices:

  • false ← (default)

  • true

size

float

Size of the captured data. Set 0 for full packet trace.

skiplocalssh

string

skip local SSH packets

Choices:

  • "ENABLED"

  • "DISABLED"

skiprpc

string

skip RPC packets

Choices:

  • "ENABLED"

  • "DISABLED"

state

string

The state of the resource being configured by the module on the NetScaler ADC node.

Default: "present"

time

float

Time per file (sec).

tracebuffers

float

Number of 16KB trace buffers

traceformat

string

Format in which trace will be generated

Choices:

  • "NSCAP"

  • "PCAP"

validate_certs

boolean

If false, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.

Choices:

  • false

  • true ← (default)

Notes

Note

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

changed

boolean

Indicates if any change is made by the module

Returned: always

Sample: true

diff

dictionary

Dictionary of before and after changes

Returned: always

Sample: {"after": {"key2": "pqr"}, "before": {"key1": "xyz"}, "prepared": "changes done"}

diff_list

list / elements=string

List of differences between the actual configured object and the configuration specified in the module

Returned: when changed

Sample: ["Attribute `key1` differs. Desired: (<class 'str'>) XYZ. Existing: (<class 'str'>) PQR"]

failed

boolean

Indicates if the module failed or not

Returned: always

Sample: false

loglines

list / elements=string

list of logged messages by the module

Returned: always

Sample: ["message 1", "message 2"]

Authors

  • Sumanth Lingappa (@sumanth-lingappa)

  • Shiva Shankar Vaddepally (@shivashankar-vaddepally)