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