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 MAC address
■   Destination MAC address
■   VLAN ID
■   Inner-VLAN
■   Layer 2 ethernet type
■   Source IPv4 address
■   Destination IPv4 address
■   Internet protocol
■   IP version number
■   IP fragmentation bits
■   Time to Live (TTL) value
■   DiffServ Code Point bits
■   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.
■   You can delete the PCAP configuration after the packets are captured.
■   The PCAP configuration profile in the device is deleted:
■   after device backup and restore
■   after device reboot and upgrade

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.
■   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.
■   For the receive (Rx) or transmit (Tx) direction of traffic, a maximum of 64 filter rules can be configured. However, if you want to configure filter rules for both directions of traffic, a maximum of 32 filter rules can be configured.
■   The qualifiers 'vlan' and 'inner-vlan' are not supported when the pcap is configured on the tool or hybrid port in the 'tx' direction.
■   If the packet size is more than 1000 bytes, then all the incoming packets on the port might not be captured.
■   For the GigaVUE-HC1P, GigaVUE-TA25, and GigaVUE-TA25E platforms, captured packets will contain a duplicate VLAN header.

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

         dscp <af11 | af12 | af13 | af21 | af22 | af23 | af31 | af32 | af33 | af41 | af42 | af43 | ef>

         ethertype <2-byte-hex>

         inner-vlan <vlan>

         ipdst <IP address> <netmask>

         ipfrag <no-frag | all-frag | all-frag-no-first | first-frag | first-or-no-frag>

         ipsrc <IP address> <netmask>

         ipver <4 | 6>

         macdst <MAC address> <MAC netmask>

         macsrc <MAC address> <MAC 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>

         ttl <ttl>
         vlan <vlan>

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

 

Note:  If a PCAP configuration is deleted, the channel ports configured in the PCAP will go down.

packet-limit <1-40000>

Specifies the number of packets to capture. The valid range is from 1 to 20000 for GigaVUE-HC2 and 1 to 40000 for other platforms. Use the packet limit to specify that the packet capture will stop after the specified number of packets have been captured.

The default value is 20000 for GigaVUE-HC2 and 40000 for other platforms.

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

dscp <af11 | af12 | af13 | af21 | af22 | af23 | af31 | af32 | af33 | af41 | af42 | af43 | ef>

   ethertype <2-byte-hex>

   inner-vlan <vlan>

   ipdst <IP address> <netmask>

   ipfrag <no-frag | all-frag | all-frag-no-first | first-frag | first-or-no-frag>

    ipsrc <IP address> <netmask>

    ipver <4 | 6>

    macdst <MAC address> <MAC netmask>

    macsrc <MAC address> <MAC 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>

    ttl <ttl>
    vlan <vlan>

Specifies the rules on which to filter traffic as follows:

● dscp—Specifies the decimal DSCP value. You can select any value within the four Assured Forwarding (af) class ranges or ef for Expedited Forwarding (the highest priority in the DSCP model). The valid DSCP values by Assured Forwarding Class are as follows:
o Class 1—11, 12, 13
o Class 2—21, 22, 23
o Class 3—31, 32, 33
o Class 4—41, 42, 43
o Expedited Forwarding—ef
● ethertype—Specifies the layer 2 ethernet type value.
● inner-vlan—Specifies the VLAN ID value as a number between 1 and 4094.
● ipdst—Specifies the destination IPv4 address and IP mask or a wildcard with an IP mask.
● ipfrag—Specifies any of the IP fragments listed below.
o no-frag—Matches unfragmented packets.
o all-frag—Matches any fragment.
o all-frag-no-first—Matches all fragments except the first fragment in a packet.
o first-frag—Matches the first fragment of a packet.
o first-or-no-frag—Matches unfragmented packets or the first fragment of a packet
● ipsrc—Specifies the source IPv4 address and IP mask or a wildcard with an IP mask.
● ipver—Specifies the IP version for traffic, either IPv4 or IPv6.
● macdst—Specifies the destination MAC address and MAC netmask.
● macsrc—Specifies the source MAC address and MAC netmask.
● 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.
● ttl—Specifies the Time to Live (TTL—IPv4) or Hop Limit (IPv6) value in an IP packet, as a number between 0 and 255.
● vlan—Specifies the VLAN ID value as a number between 1 and 16777215.

You can configure multiple filter rules to the same PCAP.

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