pcap

Required Command-Line Mode = Admin

Use the pcap command to configure packet capture, which lets you capture packets at an ingress port, an egress port, or both and the captured packets are stored in a PCAP file.

To configure packet capture, define filters to capture specific traffic based on rules. The following criteria can be specified in the rules:

■   Source IPv4 address
■   Destination IPv4 address
■   Internet protocol
■   Layer 4 destination port number
■   Layer 4 source port number
■   TCP flags

Packet capture is supported on GigaVUE‑HC1, GigaVUE‑HC1-Plus, GigaVUE‑HC2, GigaVUE‑HC3, and GigaVUE TA Series nodes. It is supported on both standalone nodes and clusters.

The port type used for packet capture can be tool, network, hybrid, inline tool, or inline network. They must be physical ports.

Refer to the following notes for packet capture:

■   The criteria listed above can be defined in any combination.
■   The source and destination can only be IPv4 addresses.
■   The source and destination can be specified as an IP address or a wildcard with an IP mask.
■   The Layer 4 source and destination ports can be specified as a port number only. A range of ports is not supported.
■   The TCP flags are control bits, such as SYN, FIN, ACK, URG, specified as 1 byte hex values.
■   The number of ports on which packets can be simultaneously captured is 4.
■   The number of filters that can be configured on a node is 64.
■   The same filter can be specified on multiple ports.
■   The same port can have multiple filters configured on it.
■   When multiple filters are configured, the traffic matching each filter is stored in a separate PCAP file.
■   It is recommended that you configure a maximum of four PCAP sessions at a time. If you configure more than four PCAP sessions, the time taken to capture the packets in the PCAP file increases. For GigaVUE-TA400 devices, you can only configure one PCAP session at a time.
■   If you configure multiple PCAP sessions with different rules on an ingress port, only one PCAP session will be chosen for that port.
■   Use the show files pcap command to display the PCAP file.
■   The PCAP file can be exported from the GigaVUE node to an external location using the file pcap upload command.

Refer to the following limitations of packet capture:

■   IPv6 addresses are not supported.
■   Configuration in any node's port in a cluster is supported only on leader nodes. Adding and removing the captured pcap files have to performed on the individual nodes through GigaVUE-OS CLI.
■   The port type of stack is not supported on the capture port or the channel port.
■   GigaSMART engine ports are not supported.
■   Inline network groups are not supported. Specify up to 4 individual ports for packet capturing.
■   Packet capture filters cannot be saved or restored.
■   Q-in-Q packets cannot be captured in the egress port.
■   Bursty traffic1 (size > 6 MB per second)2 cannot be captured in the PCAP file.
■   The pcap command does not capture packets on IP interface (network or tool).
■   The pcap feature will not function for GigaVUE‑TA400 nodes configured with multiple pcap filters in the same port. However, it will work when a single pcap filter is configured in the port.
■   In GigaVUE-HC2 GigaSMART module , the pcap files will be captured as per the configuration, but the packet hit count cannot be retrieved.

The pcap command has the following syntax:

pcap   alias <alias>
      channel-port <port ID>
      packet-limit <1-20000>
      port <port ID> <tx | rx | both>
      filter

         ipdst <IP address> <netmask>

         ipsrc <IP address> <netmask>

         portdst <0-65535>

         portsrc <0-65535>

         protocol <ipv6-hop | icmp-ipv4 | igmp | ipv4ov4 | tcp | udp | ipv6 | rsvp | gre | icmp-ipv6>

         tcpctl <1-byte-hex>

The following table describes the arguments for the pcap command:

Argument

Description

alias <alias>

Specifies the name of the packet capture filter.

For example:

(config) # pcap alias issl_ack

channel-port <port ID>

Specifies the channel port identifier for the packet capture filter, in the format <bid/sid/pid>. The channel port can be a network, tool, or hybrid port.

The channel port is any unused port. Unused means that it does not have any map configuration. In addition, the channel port must be on the same node as the capture port. Finally, the channel port must be administratively enabled and must remain enabled while a packet capture filter is configured.

You must specify one channel port for each tx or both direction. A channel port is not needed for rx.

For example:

(config pcap alias issl_ack) # channel-port 1/1/x2

(config) # port 1/1/x2 params admin enable

packet-limit <1-20000>

Specifies the number of packets to capture. The valid range is from 1 to 20000. Use the packet limit to specify that the packet capture will stop after the specified number of packets have been captured.

The default is 0, which means everything is captured. This is not recommended due to disk limitations.

For example:

(config pcap alias issl_ack) # packet-limit 100

If you do not specify a packet limit, delete the packet capture filter to stop capturing. For example:

(config) # no pcap alias issl_ack

port <port ID> <tx | rx | both>

Specifies the port identifier for the packet capture filter, in the format <bid/sid/pid>, and the direction as follows:

● tx—Specifies the transmitting end (egress).
● rx—Specifies the receiving end (ingress).
● both—Specifies both the transmitting and the receiving ends (egress and ingress).

This port may also be referred to as the capture port or the filter port.

The port type can be tool, network, hybrid, inline tool, or inline network. They must be physical ports.

Examples:

(config pcap alias issl_ack) # port 1/1/x1 tx

filter

   ipdst <IP address> <netmask>

    ipsrc <IP address> <netmask>

    portdst <0-65535>

    portsrc <0-65535>

    protocol <ipv6-hop | icmp-ipv4 | igmp | ipv4ov4 | tcp | udp | ipv6 | rsvp | gre | icmp-ipv6>

    tcpctl <1-byte-hex>

Specifies the rules on which to filter traffic as follows:

● ipdst—Specifies the destination IPv4 address and IP mask or a wildcard with an IP mask.
● ipsrc—Specifies the source IPv4 address and IP mask or a wildcard with an IP mask.
● portdst—Specifies the Layer 4 destination port number, from 0 to 65535. A range of ports is not supported.
● portsrc—Specifies the Layer 4 source port number, from 0 to 65535. A range of ports is not supported.
● protocol—Specifies the Internet protocol. The valid protocols and their hex value are as follows:
o ipv6-hop (0x0)
o icmp-ipv4 (0x1)
o igmp (0x2)
o ipv4ov4 (0x4)
o tcp (0x6)
o udp (0x11)
o ipv6 (0x29)
o rsvp (0x2E)
o gre (0x2F)
o icmp-ipv6 (0x3A)
o A custom-defined value can also be defined in 1 byte hex.
● tcpctl—Specifies TCP control bits, such as SYN, FIN, ACK, URG, as 1 byte hex values. Rules using the tcpctl parameter must also specify the protocol as tcp.

Only one filter is allowed per packet capture filter. To configure multiple rules on the same port, configure multiple filter parameters as part of the same filter.

For example:

(config pcap alias issl_ack ) # filter ipsrc 10.10.1.16 /24 portsrc 2152 protocol udp

Related Commands

The following table summarizes other commands related to the pcap command:

Task

Command

Displays all packet capture filters.

# show pcap

Displays a specified packet capture filter.

# show pcap alias issl_ack

Displays PCAP files.

show files pcap

Sends a PCAP file to a remote host. Refer to file.

(config) # file pcap upload pcap_p1_2018_05_08_17_28.pcap scp://myNode@10.115.0.100/tftpboot/myName/.

Stops a specified packet capture and deletes it.

(config) # no pcap alias issl_ack