1.. zephyr:code-sample:: net-capture
2 :name: Network packet capture
3 :relevant-api: net_capture
4
5 Capture network packets and send them to a remote host via IPIP tunnel.
6
7Overview
8********
9
10This application will setup the device so that net-shell can be used
11to enable network packet capture.
12
13The captured packets are sent to
14remote host via IPIP tunnel. The tunnel can be configured to be in the
15same connection as what we are capturing packets or it can be a separate
16bearer. For example if you are capturing network traffic for interface 1,
17then the remote host where the captured packets are sent can also be reached
18via interface 1 or via some other network interface if the device has
19multiple network interfaces connected.
20
21Requirements
22************
23
24- :ref:`networking_with_host`
25
26Building and Running
27********************
28
29Build the sample application like this:
30
31.. zephyr-app-commands::
32 :zephyr-app: samples/net/capture
33 :board: <board to use>
34 :conf: <config file to use>
35 :goals: build
36 :compact:
37
38
39Network Configuration
40*********************
41
42The ``net-tools`` project contains ``net-setup.sh`` script that can be used to setup
43the tunneling.
44
45In terminal #1, type:
46
47.. code-block:: console
48
49 ./net-setup.sh -c zeth-tunnel.conf
50
51The script will create following network interfaces:
52
53.. code-block:: console
54
55 zeth: flags=4099<UP,BROADCAST,MULTICAST> mtu 1500
56 inet 192.0.2.2 netmask 255.255.255.255 broadcast 0.0.0.0
57 inet6 2001:db8::2 prefixlen 128 scopeid 0x0<global>
58 ether 00:00:5e:00:53:ff txqueuelen 1000 (Ethernet)
59 RX packets 0 bytes 0 (0.0 B)
60 RX errors 0 dropped 0 overruns 0 frame 0
61 TX packets 0 bytes 0 (0.0 B)
62 TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
63
64 zeth-ip6ip: flags=209<UP,POINTOPOINT,RUNNING,NOARP> mtu 1480
65 inet6 2001:db8:200::2 prefixlen 64 scopeid 0x0<global>
66 inet6 fe80::c000:202 prefixlen 64 scopeid 0x20<link>
67 sit txqueuelen 1000 (IPv6-in-IPv4)
68 RX packets 0 bytes 0 (0.0 B)
69 RX errors 0 dropped 0 overruns 0 frame 0
70 TX packets 0 bytes 0 (0.0 B)
71 TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
72
73 zeth-ip6ip6: flags=209<UP,POINTOPOINT,RUNNING,NOARP> mtu 1452
74 inet6 fe80::486c:eeff:fead:5d11 prefixlen 64 scopeid 0x20<link>
75 inet6 2001:db8:100::2 prefixlen 64 scopeid 0x0<global>
76 unspec 20-01-0D-B8-00-00-00-00-00-00-00-00-00-00-00-00 txqueuelen 1000 (UNSPEC)
77 RX packets 0 bytes 0 (0.0 B)
78 RX errors 0 dropped 0 overruns 0 frame 0
79 TX packets 0 bytes 0 (0.0 B)
80 TX errors 8 dropped 8 overruns 0 carrier 8 collisions 0
81
82 zeth-ipip: flags=209<UP,POINTOPOINT,RUNNING,NOARP> mtu 1480
83 inet 198.51.100.2 netmask 255.255.255.0 destination 198.51.100.2
84 inet6 fe80::5efe:c000:202 prefixlen 64 scopeid 0x20<link>
85 tunnel txqueuelen 1000 (IPIP Tunnel)
86 RX packets 0 bytes 0 (0.0 B)
87 RX errors 0 dropped 0 overruns 0 frame 0
88 TX packets 0 bytes 0 (0.0 B)
89 TX errors 7 dropped 0 overruns 0 carrier 0 collisions 0
90
91 zeth-ipip6: flags=209<UP,POINTOPOINT,RUNNING,NOARP> mtu 1452
92 inet 203.0.113.2 netmask 255.255.255.0 destination 203.0.113.2
93 inet6 fe80::387b:a6ff:fe56:6cac prefixlen 64 scopeid 0x20<link>
94 unspec 20-01-0D-B8-00-00-00-00-00-00-00-00-00-00-00-00 txqueuelen 1000 (UNSPEC)
95 RX packets 0 bytes 0 (0.0 B)
96 RX errors 0 dropped 0 overruns 0 frame 0
97 TX packets 0 bytes 0 (0.0 B)
98 TX errors 7 dropped 7 overruns 0 carrier 0 collisions 0
99
100The ``zeth`` is the outer tunnel interface, all the packets go via it.
101The other interfaces receive packets depending on the configuration you have
102in the Zephyr side.
103
104Network Capture Configuration
105=============================
106
107In Zephyr console, type:
108
109.. code-block:: console
110
111 uart:~$ net iface
112
113 Interface 0x807df74 (Virtual) [1]
114 =================================
115 Interface is down.
116
117 Interface 0x807e040 (Ethernet) [2]
118 ==================================
119 Link addr : 02:00:5E:00:53:3B
120 MTU : 1452
121 Flags : AUTO_START,IPv4,IPv6
122 Ethernet capabilities supported:
123 IPv6 unicast addresses (max 4):
124 fe80::5eff:fe00:533b autoconf preferred infinite
125 2001:db8::1 manual preferred infinite
126 IPv6 multicast addresses (max 4):
127 ff02::1
128 ff02::1:ff00:533b
129 ff02::1:ff00:1
130 IPv6 prefixes (max 2):
131 <none>
132 IPv6 hop limit : 64
133 IPv6 base reachable time : 30000
134 IPv6 reachable time : 43300
135 IPv6 retransmit timer : 0
136 IPv4 unicast addresses (max 2):
137 192.0.2.1 manual preferred infinite
138 IPv4 multicast addresses (max 1):
139 <none>
140 IPv4 gateway : 0.0.0.0
141 IPv4 netmask : 255.255.255.0
142
143Next the monitoring is setup so that captured packets are sent as a payload
144in IPv6/UDP packets.
145
146.. code-block:: console
147
148 uart:~$ net capture setup 192.0.2.2 2001:db8:200::1 2001:db8:200::2
149 Capture setup done, next enable it by "net capture enable <idx>"
150
151The ``net capture`` command will show current configuration. As we have not
152yet enabled capturing, the interface is not yet set.
153
154.. code-block:: console
155
156 uart:~$ net capture
157 Network packet capture disabled
158 Capture Tunnel
159 Device iface iface Local Peer
160 NET_CAPTURE0 - 1 [2001:db8:200::1]:4242 [2001:db8:200::2]:4242
161
162Next enable network packet capturing for interface 2.
163
164.. code-block:: console
165
166 uart:~$ net capture enable 2
167
168The tunneling interface will be UP and the captured packets will be sent to
169peer host.
170
171.. code-block:: console
172
173 uart:~$ net iface 1
174
175 Interface 0x807df74 (Virtual) [1]
176 =================================
177 Name : IPv4 tunnel
178 Attached : 2 (Ethernet / 0x807e040)
179 Link addr : 8E:F9:94:6D:B9:E6
180 MTU : 1452
181 Flags : POINTOPOINT,NO_AUTO_START,IPv6
182 IPv6 unicast addresses (max 4):
183 fe80::aee6:fbff:fe50:28c0 autoconf preferred infinite
184 2001:db8:200::1 manual preferred infinite
185 IPv6 multicast addresses (max 4):
186 <none>
187 IPv6 prefixes (max 2):
188 <none>
189 IPv6 hop limit : 64
190 IPv6 base reachable time : 30000
191 IPv6 reachable time : 22624
192 IPv6 retransmit timer : 0
193 IPv4 not enabled for this interface.
194
195If you now do this:
196
197.. code-block:: console
198
199 uart:~$ net ping -c 1 192.0.2.2
200
201You should see a ICMPv4 message sent to ``192.0.2.2`` and also the captured
202packet will be sent to ``192.0.2.2`` in tunnel to ``2001:db8:200::2``
203address. The UDP port is by default ``4242`` but that can be changed when
204setting the tunnel endpoint address.
205
206The actual captured network packets received at the end of the tunnel will look
207like this:
208
209.. code-block:: console
210
211 No. Time Source Destination Protocol Length Info
212 34 106.078538049 192.0.2.1 192.0.2.2 ICMP 94 Echo (ping) request id=0xdc36, seq=0/0, ttl=64 (reply in 35)
213
214 Frame 34: 94 bytes on wire (752 bits), 94 bytes captured (752 bits) on interface zeth-ip6ip, id 0
215 Raw packet data
216 Internet Protocol Version 6, Src: 2001:db8:200::1, Dst: 2001:db8:200::2
217 User Datagram Protocol, Src Port: 4242, Dst Port: 4242
218 Ethernet II, Src: 02:00:5e:00:53:3b (02:00:5e:00:53:3b), Dst: ICANNIAN_00:53:ff (00:00:5e:00:53:ff)
219 Internet Protocol Version 4, Src: 192.0.2.1, Dst: 192.0.2.2
220 Internet Control Message Protocol
221
222 No. Time Source Destination Protocol Length Info
223 35 106.098850599 192.0.2.2 192.0.2.1 ICMP 94 Echo (ping) reply id=0xdc36, seq=0/0, ttl=64 (request in 34)
224
225 Frame 35: 94 bytes on wire (752 bits), 94 bytes captured (752 bits) on interface zeth-ip6ip, id 0
226 Raw packet data
227 Internet Protocol Version 6, Src: 2001:db8:200::1, Dst: 2001:db8:200::2
228 User Datagram Protocol, Src Port: 4242, Dst Port: 4242
229 Ethernet II, Src: ICANNIAN_00:53:ff (00:00:5e:00:53:ff), Dst: 02:00:5e:00:53:3b (02:00:5e:00:53:3b)
230 Internet Protocol Version 4, Src: 192.0.2.2, Dst: 192.0.2.1
231 Internet Control Message Protocol
232
