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 Pkt-Prio Queue Thread-Prio Tests
58 [ 1] recv OK N/A N/A N/A 3 iface[2],eth vlan type[0x0800],size max[200]
59 [ 2] recv OK N/A N/A N/A 3 iface[3],eth vlan type[0x0800],size min[100]
60 [ 3] recv OK N/A N/A N/A 1 iface[1]
61 [ 4] recv OK N/A N/A N/A 2 iface[2],eth vlan type[0x0806]
62 [ 5] recv OK N/A N/A N/A 2 iface[3],eth vlan type[0x0806]
63 [ 6] recv DROP N/A N/A N/A 0
64 [ 7] IPv4 recv OK N/A N/A N/A 1 ip src block[192.0.2.2,198.51.100.2]
65 [ 8] IPv6 recv OK N/A N/A N/A 1 ip src block[2001:db8::2,2001:db8::100:2]
66
67The above sample application network packet filter rules can be interpreted
68like this:
69
70* Rule 1: Allow IPv4 (Ethernet type 0x0800) packets with max size 200 bytes
71 to network interface 2 which is the first VLAN interface.
72
73* Rule 2: Allow IPv4 packets with min size 100 bytes to network interface 3
74 which is the second VLAN interface.
75
76* Rule 3: Allow all incoming traffic to Ethernet interface 1
77
78* Rule 4: Allow ARP packets (Ethernet type 0x0806) to VLAN interface 2
79
80* Rule 5: Allow ARP packets (Ethernet type 0x0806) to VLAN interface 3
81
82* Rule 6: Drop all other packets. This also means that IPv6 packets are
83 dropped.
84
85* Rule 7: Drop IPv4 packets where the source address is either ``192.0.2.2`` or ``198.51.100.2``.
86
87* Rule 8: Drop IPv6 packets where the source address is either ``2001:db8::2`` or ``2001:db8::100:2``.
88
89If you enable network packet priority option :kconfig:option:`CONFIG_NET_SAMPLE_USE_PACKET_PRIORITIES`
90then the sample will install extra rules for setting up the priorities.
91
92 uart:~$ net filter
93 Rule Type Verdict Pkt-Prio Queue Thread-Prio Tests
94 [ 1] recv CONTINUE 1 0 1 1 iface[1]
95 [ 2] recv CONTINUE 7 2 SKIP 2 iface[1],eth type[0x88f7]
96 [ 3] recv CONTINUE 2 0 1 2 iface[1],eth type[0x8100]
97 [ 4] recv CONTINUE 1 0 1 2 iface[2],eth vlan type[0x0806]
98 [ 5] recv CONTINUE 1 0 1 2 iface[3],eth vlan type[0x0806]
99 [ 6] recv OK N/A N/A N/A 3 iface[2],eth vlan type[0x0800],size max[200]
100 [ 7] recv OK N/A N/A N/A 3 iface[3],eth vlan type[0x0800],size min[100]
101 [ 8] recv OK N/A N/A N/A 1 iface[1]
102 [ 9] recv OK N/A N/A N/A 2 iface[2],eth vlan type[0x0806]
103 [10] recv OK N/A N/A N/A 2 iface[3],eth vlan type[0x0806]
104 [11] recv DROP N/A N/A N/A 0
105 [12] IPv4 recv OK N/A N/A N/A 1 ip src block[192.0.2.2,198.51.100.2]
106 [13] IPv6 recv OK N/A N/A N/A 1 ip src block[2001:db8::2,2001:db8::100:2]
107
108The above sample application network packet filter rules can be interpreted
109like this:
110
111* Rules 1 - 5: Add rules to set network packet priority to certain type packets.
112
113* Rule 6 - 13: These are the same as in previous rule list.
114
115The network statistics can be used to see that the packets are dropped.
116Use ``net stats`` command to monitor statistics.
117
118You can verify the rules from network shell:
119
120.. code-block:: console
121
122 uart:~$ net ping 2001:db8:100::2 -c 2
123 PING 2001:db8:100::2
124 Ping timeout
125 uart:~$ net stats 2
126 Interface 0x8089c6c (Virtual) [2]
127 ==================================
128 IPv6 recv 0 sent 3 drop 0 forwarded 0
129 IPv6 ND recv 0 sent 7 drop 1
130 IPv6 MLD recv 0 sent 0 drop 0
131 ICMP recv 0 sent 3 drop 0
132 ...
133 Filter drop rx 10 tx 0
134 Bytes received 320
135 Bytes sent 660
136 Processing err 10
137
138 uart:~$ net ping 198.51.100.2 -c 1
139 PING 198.51.100.2
140 28 bytes from 198.51.100.2 to 198.51.100.1: icmp_seq=1 ttl=64 time=100 ms
141
142 uart:~$ net ping 198.51.100.2 -c 1 -s 201
143 PING 198.51.100.2
144 Ping timeout
145
146 uart:~$ net ping 203.0.113.2 -c 1
147 PING 203.0.113.2
148 Ping timeout
149
150 uart:~$ net ping 203.0.113.2 -c 1 -s 101
151 PING 203.0.113.2
152 125 bytes from 203.0.113.2 to 203.0.113.1: icmp_seq=1 ttl=64 time=20 ms
153
