1.\" $OpenBSD: bpf_mtap.9,v 1.18 2023/04/12 09:55:22 jsg Exp $ 2.\" 3.\" Copyright (c) 2016 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: April 12 2023 $ 18.Dt BPF_MTAP 9 19.Os 20.Sh NAME 21.Nm bpfattach , 22.Nm bpfdetach , 23.Nm bpfsattach , 24.Nm bpfsdetach , 25.Nm bpf_filter , 26.Nm bpf_mfilter , 27.Nm bpf_validate , 28.Nm bpf_mtap , 29.Nm bpf_mtap_hdr , 30.Nm bpf_mtap_af , 31.Nm bpf_mtap_ether , 32.Nm bpf_tap_hdr 33.Nd BPF kernel API 34.Sh SYNOPSIS 35.In net/bpf.h 36.Ft void 37.Fo bpfattach 38.Fa "caddr_t *bpfp" 39.Fa "struct ifnet *ifp" 40.Fa "u_int dlt" 41.Fa "u_int hdrlen" 42.Fc 43.Ft void 44.Fn bpfdetach "struct ifnet *ifp" 45.Ft void * 46.Fn bpfsattach "caddr_t *bpfp" "const char *name" "u_int dlt" "u_int hdrlen" 47.Ft void 48.Fn bpfsdetach "void *bpfif" 49.Ft u_int 50.Fo bpf_filter 51.Fa "const struct bpf_insn *pc" 52.Fa "const u_char *pkt" 53.Fa "u_int wirelen" 54.Fa "u_int pktlen" 55.Fc 56.Ft u_int 57.Fo bpf_mfilter 58.Fa "const struct bpf_insn *pc" 59.Fa "const struct mbuf *m" 60.Fa "u_int wirelen" 61.Fc 62.Ft int 63.Fn bpf_validate "struct bpf_insn *pc" "int len" 64.Ft int 65.Fn bpf_mtap "caddr_t bpf" "const struct mbuf *m" "u_int direction" 66.Ft int 67.Fo bpf_mtap_hdr 68.Fa "caddr_t bpf" 69.Fa "const void *hdr" 70.Fa "u_int hdrlen" 71.Fa "const struct mbuf *m" 72.Fa "u_int direction" 73.Fc 74.Ft int 75.Fo bpf_mtap_af 76.Fa "caddr_t bpf" 77.Fa "u_int32_t af" 78.Fa "const struct mbuf *m" 79.Fa "u_int direction" 80.Fc 81.Ft int 82.Fn bpf_mtap_ether "caddr_t bpf" "const struct mbuf *m" "u_int direction" 83.Ft int 84.Fo bpf_tap_hdr 85.Fa "caddr_t bpf" 86.Fa "const void *hdr" 87.Fa "u_int hdrlen" 88.Fa "const void *buf" 89.Fa "u_int buflen" 90.Fa "u_int direction" 91.Fc 92.Sh DESCRIPTION 93The BPF kernel API provides functions for evaluating BPF instructions 94against packets, and incoming linkage from device drivers. 95A packet is parsed by the filters associated with each interface 96and, if accepted, stashed into the corresponding buffer. 97.Pp 98.Fn bpfattach 99allocates and configures a BPF interface for use with the network interface 100.Fa ifp . 101.Fa bpfp 102is the location of BPF interface pointer that the network interface passes to 103the filter functions. 104The BPF interface pointer will be clear until a filter is registered and 105packets can be filtered on it. 106The 107.Fa dlt 108argument identifies the data link-layer type that the network 109interface provides for this BPF interface. 110.Fn bpfattach 111may be called multiple times against the same network interface to 112provide different data link-layer types for filtering. 113.Fa hdrlen 114indicates the length of the link header for the data link-layer type. 115.Pp 116.Fn bpfdetach 117removes and frees all the BPF interfaces that were configured for 118the network interface 119.Fa ifp . 120.Pp 121.Fn bpfsattach 122allocates and configures a BPF interface for use by the subsystem 123identified by 124.Fa name . 125The 126.Fa bpfp , 127.Fa dlt , 128.Fa hdrlen 129arguments work like those in 130.Fn bpfattach . 131.Pp 132.Fn bpfsdetach 133removes and frees the BPF interface referenced by 134.Fa bpfif . 135.Pp 136.Fn bpf_filter 137executes the BPF program referenced by 138.Fa pc 139against the packet buffer starting at 140.Fa pkt 141of 142.Fa pktlen 143bytes in length. 144.Fa wirelen 145is the length of the original packet on the wire. 146.Pp 147.Fn bpf_mfilter 148executes the BPF program referenced by 149.Fa pc 150against the packet in the mbuf 151.Fa m . 152.Fa wirelen 153is the length of the original packet on the wire. 154.Pp 155.Fn bpf_validate 156tests if the BPF program referenced by 157.Fa pc 158is valid. 159.Fa len 160specifies the number of instructions in 161.Fa pc . 162.Pp 163.Fn bpf_tap 164runs the filters on the BPF interface referenced by 165.Fa bpf 166in the direction 167.Fa direction 168against the packet in the 169.Fa pkt 170buffer. 171.Pp 172.Fn bpf_mtap 173runs the filters on the BPF interface referenced by 174.Fa bpf 175in the direction 176.Fa direction 177against the packet in mbuf chain 178.Fa m . 179.Pp 180.Fn bpf_mtap_hdr 181runs the filters on the BPF interface referenced by 182.Fa bpf 183in the direction 184.Fa direction 185against the packet in mbuf chain 186.Fa m . 187The header referenced by 188.Fa hdr 189will be prefixed to the packet during filter evaluation. 190.Pp 191.Fn bpf_mtap_af 192runs the filters on the BPF interface referenced by 193.Fa bpf 194in the direction 195.Fa direction 196against the packet in mbuf chain 197.Fa m . 198The address family specified by 199.Fa af 200will be prepended to the packet before matching occurs. 201.Pp 202.Fn bpf_mtap_ether 203runs the filters on the BPF interface referenced by 204.Fa bpf 205in the direction 206.Fa direction 207against an Ethernet packet in the mbuf 208.Fa m . 209If the mbuf is flagged with 210.Dv M_VLANTAG , 211an Ethernet VLAN header is constructed using 212m->m_pkthdr.ether_vtag 213and 214m->m_pkthdr.pf.prio 215before matching occurs. 216.Pp 217.Fn bpf_tap_hdr 218runs the filters on the BPF interface referenced by 219.Fa bpf 220in the direction 221.Fa direction 222against the buffer 223.Fa buf 224of length 225.Fa buflen . 226The header 227.Fa hdr 228of length 229.Fa hdrlen 230will be prefixed to the buffer for filter evaluation. 231.Sh CONTEXT 232.Fn bpfattach , 233.Fn bpfdetach , 234.Fn bpfsattach , 235and 236.Fn bpfsdetach 237can be called from process context. 238.Pp 239.Fn bpf_filter , 240.Fn bpf_mfilter , 241and 242.Fn bpf_validate 243can be called from process context, or from an interrupt context. 244.Pp 245.Fn bpf_mtap , 246.Fn bpf_mtap_hdr , 247.Fn bpf_mtap_af , 248.Fn bpf_mtap_ether , 249and 250.Fn bpf_tap_hdr 251can be called from process context, or from an interrupt context at or below 252.Dv IPL_NET . 253.Sh RETURN VALUES 254.Fn bpfsattach 255returns a reference to the BPF interface it allocates. 256.Pp 257.Fn bpf_filter 258and 259.Fn bpf_mfilter 260return -1 (cast to an unsigned integer) if the filter program is 261.Dv NULL , 262or the result of the filter program. 263Filter programs should return the maximum number of bytes of the 264packet to capture, or 0 if the packet does not match the filter 265program. 266.Pp 267.Fn bpf_validate 268returns a non-zero value if the BPF program is valid, 269otherwise 0. 270.Pp 271.Fn bpf_mtap , 272.Fn bpf_mtap_hdr , 273.Fn bpf_mtap_af , 274.Fn bpf_mtap_ether , 275and 276.Fn bpf_tap_hdr 277return 1 if the packet or buffer matched a filter that indicates it 278should be dropped, otherwise 0. 279.Sh SEE ALSO 280.Xr mbuf 9 , 281.Xr spl 9 282