1.\" $OpenBSD: bpf_mtap.9,v 1.8 2016/05/10 23:51:50 dlg 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: May 10 2016 $ 18.Dt BPF_MTAP 9 19.Os 20.Sh NAME 21.Nm bpf_filter , 22.Nm bpf_mfilter , 23.Nm bpf_validate , 24.Nm bpf_tap , 25.Nm bpf_mtap , 26.Nm bpf_mtap_hdr , 27.Nm bpf_mtap_af , 28.Nm bpf_mtap_ether 29.Nd BPF kernel API 30.Sh SYNOPSIS 31.In net/bpf.h 32.Ft u_int 33.Fo bpf_filter 34.Fa "const struct bpf_insn *pc" 35.Fa "const u_char *pkt" 36.Fa "u_int wirelen" 37.Fa "u_int pktlen" 38.Fc 39.Ft u_int 40.Fo bpf_mfilter 41.Fa "const struct bpf_insn *pc" 42.Fa "const struct mbuf *m" 43.Fa "u_int wirelen" 44.Fc 45.Ft int 46.Fn bpf_validate "struct bpf_insn *pc" "int len" 47.Ft int 48.Fn bpf_tap "caddr_t bpf" "u_char *pkt" "u_int pktlen" "u_int direction" 49.Ft int 50.Fn bpf_mtap "caddr_t bpf" "const struct mbuf *m" "u_int direction" 51.Ft int 52.Fo bpf_mtap_hdr 53.Fa "caddr_t bpf" 54.Fa "caddr_t hdr" 55.Fa "u_int hdrlen" 56.Fa "const struct mbuf *m" 57.Fa "u_int direction" 58.Fa "void (*cpfn)(const void *, void *, size_t)" 59.Fc 60.Ft int 61.Fo bpf_mtap_af 62.Fa "caddr_t bpf" 63.Fa "u_int32_t af" 64.Fa "const struct mbuf *m" 65.Fa "u_int direction" 66.Fc 67.Ft int 68.Fn bpf_mtap_ether "caddr_t bpf" "const struct mbuf *m" "u_int direction" 69.Sh DESCRIPTION 70The BPF kernel API provides functions for evaluating BPF instructions 71against packets, and incoming linkage from device drivers. 72A packet is parsed by the filters associated with each interface 73and, if accepted, stashed into the corresponding buffer. 74.Pp 75.Fn bpf_filter 76executes the BPF program referenced by 77.Fa pc 78against the packet buffer starting at 79.Fa pkt 80of 81.Fa pktlen 82bytes in length. 83.Fa wirelen 84is the length of the original packet on the wire. 85.Pp 86.Fn bpf_mfilter 87executes the BPF program referenced by 88.Fa pc 89against the packet in the mbuf 90.Fa m . 91.Fa wirelen 92is the length of the original packet on the wire. 93.Pp 94.Fn bpf_validate 95tests if the BPF program referenced by 96.Fa pc 97is valid. 98.Fa len 99specifies the number of instructions in 100.Fa pc . 101.Pp 102.Fn bfp_tap 103runs the filters on the BPF interface referenced by 104.Fa bpf 105in the direction 106.Fa direction 107against the packet in the 108.Fa pkt 109buffer. 110.Pp 111.Fn bfp_mtap 112runs the filters on the BPF interface referenced by 113.Fa bpf 114in the direction 115.Fa direction 116against the packet in mbuf chain 117.Fa m . 118.Pp 119.Fn bfp_mtap_hdr 120runs the filters on the BPF interface referenced by 121.Fa bpf 122in the direction 123.Fa direction 124against the packet in mbuf chain 125.Fa m . 126The header referenced by 127.Fa hdr 128will be prefixed to the packet during filter evaluation. 129A custom packet copy function may be provided via 130.Fa cpfn . 131If 132.Fa cpfn 133is 134.Dv NULL 135an internal function for copying mbuf payloads will be used. 136.Pp 137.Fn bpf_mtap_af 138runs the filters on the BPF interface referenced by 139.Fa bpf 140in the direction 141.Fa direction 142against the packet in mbuf chain 143.Fa m . 144The address family specified by 145.Fa af 146will be prepended to the packet before matching occurs. 147.Pp 148.Fn bpf_mtap_ether 149runs the filters on the BPF interface referenced by 150.Fa bpf 151in the direction 152.Fa direction 153against an Ethernet packet in the mbuf 154.Fa m . 155If the mbuf is flagged with 156.Dv M_VLANTAG 157an Ethernet VLAN header is constructed using 158m->m_pkthdr.ether_vtag 159and 160m->m_pkthdr.pf.prio 161before matching occurs. 162.Sh CONTEXT 163.Fn bpf_filter , 164.Fn bpf_mfilter , 165and 166.Fn bpf_validate 167can be called from process context, or from an interrupt context. 168.Pp 169.Fn bpf_mtap , 170.Fn bpf_tap , 171.Fn bpf_mtap , 172.Fn bpf_mtap_hdr , 173.Fn bpf_mtap_af , 174and 175.Fn bpf_mtap_ether 176can be called from process context, or from an interrupt context at or below 177.Dv IPL_NET . 178.Sh RETURN VALUES 179.Fn bpf_filter , 180and 181.Fn bpf_mfilter 182return -1 (cast to an unsigned integer) if the filter program is 183.Dv NULL , 184or the result of the filter program. 185Filter programs should return the maximum number of bytes of the 186packet to capture, or 0 if the packet does not match the filter 187program. 188.Pp 189.Fn bpf_validate 190returns a non-zero value if the BPF program is valid, 191otherwise 0. 192.Pp 193.Fn bpf_tap , 194.Fn bpf_mtap , 195.Fn bpf_mtap_hdr , 196.Fn bpf_mtap_af , 197and 198.Fn bpf_mtap_ether 199return 1 if the packet matched a filter that indicates the packet 200should be dropped, otherwise 0. 201.Sh SEE ALSO 202.Xr mbuf 9 , 203.Xr spl 9 204