1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
.\" $OpenBSD: bpf_mtap.9,v 1.7 2016/04/08 06:40:07 jmc Exp $
.\"
.\" Copyright (c) 2016 David Gwynne <dlg@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: April 8 2016 $
.Dt BPF_MTAP 9
.Os
.Sh NAME
.Nm bpf_filter ,
.Nm bpf_mfilter ,
.Nm bpf_validate ,
.Nm bpf_tap ,
.Nm bpf_mtap ,
.Nm bpf_mtap_hdr ,
.Nm bpf_mtap_af ,
.Nm bpf_mtap_ether
.Nd BPF kernel API
.Sh SYNOPSIS
.In net/bpf.h
.Ft u_int
.Fo bpf_filter
.Fa "const struct bpf_insn *pc"
.Fa "const u_char *pkt"
.Fa "u_int wirelen"
.Fa "u_int pktlen"
.Fc
.Ft u_int
.Fo bpf_mfilter
.Fa "const struct bpf_insn *pc"
.Fa "const struct mbuf *m"
.Fa "u_int wirelen"
.Fc
.Ft int
.Fn bpf_validate "struct bpf_insn *pc" "int len"
.Ft int
.Fn bpf_tap "caddr_t bpf" "u_char *pkt" "u_int pktlen" "u_int direction"
.Ft int
.Fn bpf_mtap "caddr_t bpf" "struct mbuf *m" "u_int direction"
.Ft int
.Fo bpf_mtap_hdr
.Fa "caddr_t bpf"
.Fa "caddr_t hdr"
.Fa "u_int hdrlen"
.Fa "struct mbuf *m"
.Fa "u_int direction"
.Fa "void (*cpfn)(const void *, void *, size_t)"
.Fc
.Ft int
.Fn bpf_mtap_af "caddr_t bpf" "u_int32_t af" "struct mbuf *m" "u_int direction"
.Ft int
.Fn bpf_mtap_ether "caddr_t bpf" "struct mbuf *m" "u_int direction"
.Sh DESCRIPTION
The BPF kernel API provides functions for evaluating BPF instructions
against packets, and incoming linkage from device drivers.
A packet is parsed by the filters associated with each interface
and, if accepted, stashed into the corresponding buffer.
.Pp
.Fn bpf_filter
executes the BPF program referenced by
.Fa pc
against the packet buffer starting at
.Fa pkt
of
.Fa pktlen
bytes in length.
.Fa wirelen
is the length of the original packet on the wire.
.Pp
.Fn bpf_mfilter
executes the BPF program referenced by
.Fa pc
against the packet in the mbuf
.Fa m .
.Fa wirelen
is the length of the original packet on the wire.
.Pp
.Fn bpf_validate
tests if the BPF program referenced by
.Fa pc
is valid.
.Fa len
specifies the number of instructions in
.Fa pc .
.Pp
.Fn bfp_tap
runs the filters on the BPF interface referenced by
.Fa bpf
in the direction
.Fa direction
against the packet in the
.Fa pkt
buffer.
.Pp
.Fn bfp_mtap
runs the filters on the BPF interface referenced by
.Fa bpf
in the direction
.Fa direction
against the packet in mbuf chain
.Fa m .
.Pp
.Fn bfp_mtap_hdr
runs the filters on the BPF interface referenced by
.Fa bpf
in the direction
.Fa direction
against the packet in mbuf chain
.Fa m .
The header referenced by
.Fa hdr
will be prefixed to the packet during filter evaluation.
A custom packet copy function may be provided via
.Fa cpfn .
If
.Fa cpfn
is
.Dv NULL
an internal function for copying mbuf payloads will be used.
.Pp
.Fn bpf_mtap_af
runs the filters on the BPF interface referenced by
.Fa bpf
in the direction
.Fa direction
against the packet in mbuf chain
.Fa m .
The address family specified by
.Fa af
will be prepended to the packet before matching occurs.
.Pp
.Fn bpf_mtap_ether
runs the filters on the BPF interface referenced by
.Fa bpf
in the direction
.Fa direction
against an Ethernet packet in the mbuf
.Fa m .
If the mbuf is flagged with
.Dv M_VLANTAG
an Ethernet VLAN header is constructed using
m->m_pkthdr.ether_vtag
and
m->m_pkthdr.pf.prio
before matching occurs.
.Sh CONTEXT
.Fn bpf_filter ,
.Fn bpf_mfilter ,
and
.Fn bpf_validate
can be called from process context, or from an interrupt context.
.Pp
.Fn bpf_mtap ,
.Fn bpf_tap ,
.Fn bpf_mtap ,
.Fn bpf_mtap_hdr ,
.Fn bpf_mtap_af ,
and
.Fn bpf_mtap_ether
can be called from process context, or from an interrupt context at or below
.Dv IPL_NET .
.Sh RETURN VALUES
.Fn bpf_filter ,
and
.Fn bpf_mfilter
return -1 (cast to an unsigned integer) if the filter program is
.Dv NULL ,
or the result of the filter program.
Filter programs should return the maximum number of bytes of the
packet to capture, or 0 if the packet does not match the filter
program.
.Pp
.Fn bpf_validate
returns a non-zero value if the BPF program is valid,
otherwise 0.
.Pp
.Fn bpf_tap ,
.Fn bpf_mtap ,
.Fn bpf_mtap_hdr ,
.Fn bpf_mtap_af ,
and
.Fn bpf_mtap_ether
return 1 if the packet matched a filter that indicates the packet
should be dropped, otherwise 0.
.Sh SEE ALSO
.Xr mbuf 9 ,
.Xr spl 9
|
