1xdpdump(a8)simple tcpdump like tool for capturing packets at the XDP laxydeprdump(8)
2
3
4

NAME

6       xdpdump  -  a simple tcpdump like tool for capturing packets at the XDP
7       layer
8

SYNOPSIS

10       xdpdump is a simple XDP packet capture tool that tries to behave  simi‐
11       lar  to  tcpdump,  however, it has no packet filter or decode capabili‐
12       ties.
13
14
15       This can be used for debugging XDP programs that are already loaded  on
16       an  interface.   Packets can be dumped/inspected before on entry to XDP
17       program, or after at exit from an XDP program.   Furthermore,  at  exit
18       the XDP action is also captured.  This means that even packets that are
19       dropped at the XDP layer can be captured via this tool.
20
21
22       xdpdump works by attaching a bpf trace program to the XDP entry  and/or
23       exit function which stores the raw packet in a perf trace buffer. If no
24       XDP program is loaded this approach can not be used and the  tool  will
25       use a libpcap live-capture to be backward compatible.
26
27
28   Running xdpdump
29       The syntax for running xdpdump is:
30
31              Usage: xdpdump [options]
32
33               XDPDump tool to dump network traffic
34
35              Options:
36                   --rx-capture <mode>    Capture point for the rx direction (valid values: entry,exit)
37               -D, --list-interfaces      Print the list of available interfaces
38               -i, --interface <ifname>   Name of interface to capture on
39                   --perf-wakeup <events>  Wake up xdpdump every <events> packets
40               -p, --program-names <prog>  Specific program to attach to
41               -s, --snapshot-length <snaplen>  Minimum bytes of packet to capture
42                   --use-pcap             Use legacy pcap format for XDP traces
43               -w, --write <file>         Write raw packets to pcap file
44               -x, --hex                  Print the full packet in hex
45               -v, --verbose              Enable verbose logging (-vv: more verbose)
46                   --version              Display version information
47               -h, --help                 Show this help
48
49

The options explained

51       The  xdpdump tool tries to mimic the basic tcpdump options, but just in
52       case below each of the available options is explained:
53
54
55   --rx-capture <mode>
56       Specify where the ingress packet gets captured. Either at the entry  of
57       the  XDP  program and/or exit of the XDP program. Valid options are en‐
58       try, exit, or both entry,exit. The packet at exit can  be  modified  by
59       the  XDP  program.  If  you are interested to see both the original and
60       modified packet, use the entry,exit option. With this, each  packet  is
61       captured twice. The default value for this is entry.
62
63   -D, --list-interfaces
64       Display a list of available interfaces and any XDP program loaded
65
66   --load-xdp-mode
67       Specifies  which loader mode to use with the --load-xdp-program option.
68       The valid values are ‘native’, which is the default in-driver XDP mode,
69       ‘skb’,  which causes the so-called skb mode (also known as generic XDP)
70       to be used, ‘hw’ which causes the program to be offloaded to the  hard‐
71       ware,  or ‘unspecified’ which leaves it up to the kernel to pick a mode
72       (which it will do by picking native mode if the driver supports it,  or
73       generic mode otherwise). Note that using ‘unspecified’ can make it dif‐
74       ficult to predict what mode a program will end up being loaded in.  For
75       this reason, the default is ‘native’.
76
77   --load-xdp-program
78       If  no XDP program is loaded on the interface, by default, xdpdump will
79       fallback to libpcap's live capture mode to capture the packets.  Alter‐
80       natively,  with this option, you can ask xdpdump to load an XDP program
81       to capture the packets directly.
82
83   -i, --interface <ifname>
84       Listen on interface ifname. Note that if no XDP program  is  loaded  on
85       the  interface  it  will use libpcap's live capture mode to capture the
86       packets.
87
88   --perf-wakeup <events>
89       Let the Kernel wake up xdpdump once for every <events> being posted  in
90       the  perf  ring buffer. The higher the number the less the impact is on
91       the actual XDP program. The default value  is  0,  which  automatically
92       calculates the value based on the available CPUs/buffers. Use -v to see
93       the actual used value.
94
95   -p, --program-names [<prog>|all]
96       This option allows you to capture packets for a specific,  set  of,  or
97       all  XDP  programs  loaded on the interface. You can either specify the
98       actual program names or program IDs separated by commas.  In  the  case
99       where multiple programs are attached with the same name, you should use
100       the program ID. Use the -D option to see the loaded programs and  their
101       IDs.
102
103
104
105       In  addition,  the  Linux API does not provide the full name of the at‐
106       tached eBPF entry function if it's longer than 15  characters.  xdpdump
107       will  try to guess the correct function name from the available BTF de‐
108       bug information. However, if multiple functions  exist  with  the  same
109       leading  name, it can not pick the correct one. It will dump the avail‐
110       able functions, and you can choose the correct one, and supply it  with
111       this  option.  If you have programs with duplicate long names, you also
112       need to specify the program ID with the full name. This can be done  by
113       adding the id to the name with the @<id> suffix.
114
115   -P, --promiscuous-mode
116       This option puts the interface into promiscuous mode.
117
118   -s, --snapshot-length <snaplen>
119       Capture snaplen bytes of a packet rather than the default 262144 bytes.
120
121   --use-pcap
122       Use  legacy  pcap  format  for  XDP traces. By default, it will use the
123       PcapNG format so that it can store various metadata.
124
125   -w, --write <file>
126       Write the raw packets to a pcap file  rather  than  printing  them  out
127       hexadecimal. Standard output is used if file is -.
128
129   -x, --hex
130       When  dumping packets on the console also print the full packet content
131       in hex.
132
133   -v, --verbose
134       Enable debug logging. Specify twice for even more verbosity.
135
136   --version
137       Display xpdump version information and exit.
138
139   -h, --help
140       Display a summary of the available options
141
142

Examples

144       The below will load the xdp-filter program on eth0, but it does not  do
145       any actual filtering:
146
147              # xdp-filter load --mode skb eth0
148              #
149              # xdpdump -D
150              Interface        Prio  Program name      Mode     ID   Tag               Chain actions
151              --------------------------------------------------------------------------------------
152              lo                     <No XDP program loaded!>
153              eth0                   xdp_dispatcher    skb      10651 d51e469e988d81da
154               =>              10     xdpfilt_alw_all           10669 0b394f43ab24501c  XDP_PASS
155
156
157       Now we can try xdpdump:
158
159              # xdpdump -i eth0 -x
160              listening on eth0, ingress XDP program ID 10651 func xdp_dispatcher, capture mode entry, capture size 262144 bytes
161              1584373839.460733895: xdp_dispatcher()@entry: packet size 102 bytes, captured 102 bytes on if_index 2, rx queue 0, id 1
162                0x0000:  52 54 00 db 44 b6 52 54 00 34 38 da 08 00 45 48  RT..D.RT.48...EH
163                0x0010:  00 58 d7 dd 40 00 40 06 ec c3 c0 a8 7a 01 c0 a8  .X..@.@.....z...
164                0x0020:  7a 64 9c de 00 16 0d d5 c6 bc 46 c9 bb 11 80 18  zd........F.....
165                0x0030:  01 f5 7b b4 00 00 01 01 08 0a 77 0a 8c b8 40 12  ..{.......w...@.
166                0x0040:  cc a6 00 00 00 10 54 ce 6e 20 c3 e7 da 6c 08 42  ......T.n ...l.B
167                0x0050:  d6 d9 ee 42 42 f0 82 c9 4f 12 ed 7b 19 ab 22 0d  ...BB...O..{..".
168                0x0060:  09 29 a9 ee df 89                                .)....
169
170              1584373839.462340808: xdp_dispatcher()@entry: packet size 66 bytes, captured 66 bytes on if_index 2, rx queue 0, id 2
171                0x0000:  52 54 00 db 44 b6 52 54 00 34 38 da 08 00 45 48  RT..D.RT.48...EH
172                0x0010:  00 34 d7 de 40 00 40 06 ec e6 c0 a8 7a 01 c0 a8  .4..@.@.....z...
173                0x0020:  7a 64 9c de 00 16 0d d5 c6 e0 46 c9 bc 85 80 10  zd........F.....
174                0x0030:  01 f5 74 0c 00 00 01 01 08 0a 77 0a 8c ba 40 12  ..t.......w...@.
175                0x0040:  d2 34                                            .4
176              ^C
177              2 packets captured
178              0 packets dropped by perf ring
179
180
181       Below  are two more examples redirecting the capture file to tcpdump or
182       tshark:
183
184              # xdpdump -i eth0 -w - | tcpdump -r - -n
185              listening on eth0, ingress XDP program ID 10651 func xdp_dispatcher, capture mode entry, capture size 262144 bytes
186              reading from file -, link-type EN10MB (Ethernet)
187              15:55:09.075887 IP 192.168.122.1.40928 > 192.168.122.100.ssh: Flags [P.], seq 3857553815:3857553851, ack 3306438882, win 501, options [nop,nop,TS val 1997449167 ecr 1075234328], length 36
188              15:55:09.077756 IP 192.168.122.1.40928 > 192.168.122.100.ssh: Flags [.], ack 37, win 501, options [nop,nop,TS val 1997449169 ecr 1075244363], length 0
189              15:55:09.750230 IP 192.168.122.1.40928 > 192.168.122.100.ssh: Flags [P.], seq 36:72, ack 37, win 501, options [nop,nop,TS val 1997449842 ecr 1075244363], length 36
190
191              # xdpdump -i eth0 -w - | tshark -r - -n
192              listening on eth0, ingress XDP program ID 10651 func xdp_dispatcher, capture mode entry, capture size 262144 bytes
193                  1   0.000000 192.168.122.1 → 192.168.122.100 SSH 102 Client: Encrypted packet (len=36)
194                  2   0.000646 192.168.122.1 → 192.168.122.100 TCP 66 40158 → 22 [ACK] Seq=37 Ack=37 Win=1467 Len=0 TSval=1997621571 TSecr=1075416765
195                  3  12.218164 192.168.122.1 → 192.168.122.100 SSH 102 Client: Encrypted packet (len=36)
196
197
198       One final example capturing specific XDP programs loaded on the  inter‐
199       face:
200
201              # xdpdump -D
202              Interface        Prio  Program name      Mode     ID   Tag               Chain actions
203              --------------------------------------------------------------------------------------
204              lo                     <No XDP program loaded!>
205              eth0                   xdp_dispatcher    skb      10558 d51e469e988d81da
206               =>              5      xdp_test_prog_w           10576 b5a46c6e9935298c  XDP_PASS
207               =>              10     xdp_pass                  10582 3b185187f1855c4c  XDP_PASS
208               =>              10     xdp_pass                  10587 3b185187f1855c4c  XDP_PASS
209
210
211       We  would  like  to see the packets on the xdp_dispatcher() and the 2nd
212       xdp_pass() program:
213
214              # xdpdump -i eth0 --rx-capture=entry,exit -p xdp_dispatcher,xdp_pass@10587
215                or
216              # xdpdump -i eth0 --rx-capture=entry,exit -p 10558,10587
217              listening on eth0, ingress XDP program ID 10558 func xdp_dispatcher, ID 10587 func xdp_pass, capture mode entry/exit, capture size 262144 bytes
218              1607694215.501287259: xdp_dispatcher()@entry: packet size 102 bytes on if_index 2, rx queue 0, id 1
219              1607694215.501371504: xdp_pass()@entry: packet size 102 bytes on if_index 2, rx queue 0, id 1
220              1607694215.501383099: xdp_pass()@exit[PASS]: packet size 102 bytes on if_index 2, rx queue 0, id 1
221              1607694215.501394709: xdp_dispatcher()@exit[PASS]: packet size 102 bytes on if_index 2, rx queue 0, id 1
222              ^C
223              4 packets captured
224              0 packets dropped by perf ring
225
226

BUGS

228       Please report any bugs on  Github:  https://github.com/xdp-project/xdp-
229       tools/issues
230
231

AUTHOR

233       xdpdump was written by Eelco Chaudron
234
235
236
237V1.4.1                         OCTOBER 20, 2023                     xdpdump(8)
Impressum