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