README.rst
1.. zephyr:code-sample:: net-pkt-filter
2 :name: Network packet filter
3 :relevant-api: net_pkt_filter
4
5 Install network packet filter hooks.
6
7Overview
8********
9
10This sample shows how to set network packet filters from a user application.
11
12The source code for this sample application can be found at:
13:zephyr_file:`samples/net/pkt_filter`.
14
15Requirements
16************
17
18- :ref:`networking_with_host`
19
20Building and Running
21********************
22
23A good way to run this sample application is with QEMU or native_sim board
24as described in :ref:`networking_with_host`.
25
26For demo purposes, the VLAN support needs to be enabled in host side like this.
27Execute these commands in a terminal window:
28
29.. code-block:: console
30
31 $ cd tools/net-tools
32 $ ./net-setup.sh -c zeth-vlan.conf
33
34Then follow these steps to build the network packet filter sample application for
35either ``qemu_x86`` or ``native_sim`` boards:
36
37.. zephyr-app-commands::
38 :zephyr-app: samples/net/pkt_filter
39 :board: <board to use>
40 :conf: "prj.conf overlay-vlan.conf"
41 :goals: build
42 :compact:
43
44In this example, we enable VLAN support with these settings:
45
46The VLAN overlay configuration file :zephyr_file:`samples/net/pkt_filter/overlay-vlan.conf`
47creates two virtual LAN networks with these settings:
48
49- VLAN tag 100: IPv4 198.51.100.1 and IPv6 2001:db8:100::1
50- VLAN tag 200: IPv4 203.0.113.1 and IPv6 2001:db8:200::1
51
52In network shell, you can monitor the network packet filters:
53
54.. code-block:: console
55
56 uart:~$ net filter
57 Rule Type Verdict Tests
58 [ 1] recv OK 3 eth vlan type[0x0800],size max[200],iface[2]
59 [ 2] recv OK 3 eth vlan type[0x0800],size min[100],iface[3]
60 [ 3] recv OK 1 iface[1]
61 [ 4] recv OK 2 eth vlan type[0x0806],iface[2]
62 [ 5] recv OK 2 eth vlan type[0x0806],iface[3]
63 [ 6] recv DROP 0
64
65The above sample application network packet filter rules can be interpreted
66like this:
67
68* Rule 1: Allow IPv4 (Ethernet type 0x0800) packets with max size 200 bytes
69 to network interface 2 which is the first VLAN interface.
70
71* Rule 2: Allow IPv4 packets with min size 100 bytes to network interface 3
72 which is the second VLAN interface.
73
74* Rule 3: Allow all incoming traffic to Ethernet interface 1
75
76* Rule 4: Allow ARP packets (Ethernet type 0x0806) to VLAN interface 2
77
78* Rule 5: Allow ARP packets (Ethernet type 0x0806) to VLAN interface 3
79
80* Rule 6: Drop all other packets. This also means that IPv6 packets are
81 dropped.
82
83The network statistics can be used to see that the packets are dropped.
84Use ``net stats`` command to monitor statistics.
85
86You can verify the rules from network shell:
87
88.. code-block:: console
89
90 uart:~$ net ping 2001:db8:100::2 -c 2
91 PING 2001:db8:100::2
92 Ping timeout
93 uart:~$ net stats 2
94 Interface 0x8089c6c (Virtual) [2]
95 ==================================
96 IPv6 recv 0 sent 3 drop 0 forwarded 0
97 IPv6 ND recv 0 sent 7 drop 1
98 IPv6 MLD recv 0 sent 0 drop 0
99 ICMP recv 0 sent 3 drop 0
100 ...
101 Filter drop rx 10 tx 0
102 Bytes received 320
103 Bytes sent 660
104 Processing err 10
105
106 uart:~$ net ping 198.51.100.2 -c 1
107 PING 198.51.100.2
108 28 bytes from 198.51.100.2 to 198.51.100.1: icmp_seq=1 ttl=64 time=100 ms
109
110 uart:~$ net ping 198.51.100.2 -c 1 -s 201
111 PING 198.51.100.2
112 Ping timeout
113
114 uart:~$ net ping 203.0.113.2 -c 1
115 PING 203.0.113.2
116 Ping timeout
117
118 uart:~$ net ping 203.0.113.2 -c 1 -s 101
119 PING 203.0.113.2
120 125 bytes from 203.0.113.2 to 203.0.113.1: icmp_seq=1 ttl=64 time=20 ms
121