summaryrefslogtreecommitdiffstats
path: root/docs/gettingstarted
diff options
context:
space:
mode:
authorDave Barach <dave@barachs.net>2019-09-13 17:47:50 -0400
committerDamjan Marion <dmarion@me.com>2019-09-25 22:19:59 +0000
commit1b696ac9b334aa9305925e4759c6c6f6b47c3328 (patch)
tree6cbc009453d33c1a7d54b5aca1a4d347bbcf0a8a /docs/gettingstarted
parent2abe699d10450553148307bb614979902f2bf4b3 (diff)
misc: classifier-based packet trace filter
See .../src/vnet/classify/trace_classify.h for the business end of the scheme. It would be best to hash pkts, prefetch buckets, and do the primary table lookups two at a time. The inline as given works, but perf tuning will be required. "At least it works..." Add "classify filter" debug cli, for example: classify filter mask l3 ip4 src dst \ match l3 ip4 dst 192.168.2.10 src 192.168.1.10 Add "pcap rx | tx trace ... filter" to use the current classify filter chain Patch includes sphinx documentation and doxygen tags. Next step: device-driver integration Type: feature Signed-off-by: Dave Barach <dave@barachs.net> Change-Id: I05b1358a769f61e6d32470e0c87058f640486b26 (cherry picked from commit 9137e5400699bed9f7c0095187839a8b38273100)
Diffstat (limited to 'docs/gettingstarted')
-rw-r--r--docs/gettingstarted/developers/vnet.md108
1 files changed, 108 insertions, 0 deletions
diff --git a/docs/gettingstarted/developers/vnet.md b/docs/gettingstarted/developers/vnet.md
index 79d539676b9..b8f878c2cd7 100644
--- a/docs/gettingstarted/developers/vnet.md
+++ b/docs/gettingstarted/developers/vnet.md
@@ -469,3 +469,111 @@ metadata changes, header checksum changes, and so forth.
This should be of significant value when developing new vpp graph
nodes. If new code mispositions b->current_data, it will be completely
obvious from looking at the dispatch trace in wireshark.
+
+## pcap rx and tx tracing
+
+vpp also supports rx and tx packet capture in pcap format, through the
+"pcap rx trace" and "pcap tx trace" debug CLI commands
+
+This command is used to start or stop a packet capture, or show
+the status of packet capture. Note that both "pcap rx trace" and
+"pcap tx trace" are implemented. The command syntax is identical,
+simply substitute rx for tx as needed.
+
+These commands have the following optional parameters:
+
+on|off- Used to start or stop a packet capture.
+
+- <b>max _nnnn_</b> - file size, number of packet captures. Once
+ <nnnn> packets have been received, the trace buffer buffer is flushed
+ to the indicated file. Defaults to 1000. Can only be updated if packet
+ capture is off.
+
+- <b>intfc _interface_ | _any_</b> - Used to specify a given interface,
+ or use '<em>any</em>' to run packet capture on all interfaces.
+ '<em>any</em>' is the default if not provided. Settings from a previous
+ packet capture are preserved, so '<em>any</em>' can be used to reset
+ the interface setting.
+
+- <b>file _filename_</b> - Used to specify the output filename. The
+ file will be placed in the '<em>/tmp</em>' directory. If _filename_
+ already exists, file will be overwritten. If no filename is
+ provided, '<em>/tmp/rx.pcap or tx.pcap</em>' will be used, depending
+ on capture direction. Can only be updated when pcap capture is off.
+
+- <b>status</b> - Displays the current status and configured
+ attributes associated with a packet capture. If packet capture is in
+ progress, '<em>status</em>' also will return the number of packets
+ currently in the buffer. Any additional attributes entered on
+ command line with a '<em>status</em>' request will be ignored.
+
+- <b>filter</b> - Capture packets which match the current packet
+ trace filter set. See next section. Configure the capture filter
+ first.
+
+## packet trace capture filtering
+
+The "classify filter" debug CLI command constructs an arbitrary set of
+ packet classifier tables for use with "pcap rx | tx trace," and
+ (eventually) with the vpp packet tracer
+
+Packets which match a rule in the classifier table chain will be
+traced. The tables are automatically ordered so that matches in the
+most specific table are tried first.
+
+It's reasonably likely that folks will configure a single table with
+one or two matches. As a result, we configure 8 hash buckets and 128K
+of match rule space by default. One can override the defaults by
+specifiying "buckets <nnn>" and "memory-size <xxx>" as desired.
+
+To build up complex filter chains, repeatedly issue the classify
+filter debug CLI command. Each command must specify the desired mask
+and match values. If a classifier table with a suitable mask already
+exists, the CLI command adds a match rule to the existing table. If
+not, the CLI command add a new table and the indicated mask rule
+
+### Configure a simple classify filter
+
+```
+ classify filter mask l3 ip4 src match l3 ip4 src 192.168.1.11"
+ pcap rx trace on max 100 filter
+```
+
+### Configure another fairly simple filter
+
+```
+ classify filter mask l3 ip4 src dst match l3 ip4 src 192.168.1.10 dst 192.168.2.10
+ pcap tx trace on max 100 filter
+```
+
+### Clear all current classifier filters
+
+```
+ classify filter del
+```
+
+### To inspect the classifier tables
+
+```
+ show classify table [verbose]
+```
+
+The verbose form displays all of the match rules, with hit-counters.
+
+### Terse description of the "mask <xxx>" syntax:
+
+```
+ l2 src dst proto tag1 tag2 ignore-tag1 ignore-tag2 cos1 cos2 dot1q dot1ad
+ l3 ip4 <ip4-mask> ip6 <ip6-mask>
+ <ip4-mask> version hdr_length src[/width] dst[/width]
+ tos length fragment_id ttl protocol checksum
+ <ip6-mask> version traffic-class flow-label src dst proto
+ payload_length hop_limit protocol
+ l4 tcp <tcp-mask> udp <udp_mask> src_port dst_port
+ <tcp-mask> src dst # ports
+ <udp-mask> src_port dst_port
+```
+
+To construct **matches**, add the values to match after the indicated
+keywords in the mask syntax. For example: "... mask l3 ip4 src" ->
+"... match l3 ip4 src 192.168.1.11"