| pfil.9 (126468) | pfil.9 (130582) |
|---|---|
| 1.\" $NetBSD: pfil.9,v 1.22 2003/07/01 13:04:06 wiz Exp $ 2.\" 3.\" Copyright (c) 1996 Matthew R. Green 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: --- 12 unchanged lines hidden (view full) --- 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 22.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 23.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 24.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" | 1.\" $NetBSD: pfil.9,v 1.22 2003/07/01 13:04:06 wiz Exp $ 2.\" 3.\" Copyright (c) 1996 Matthew R. Green 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: --- 12 unchanged lines hidden (view full) --- 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 22.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 23.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 24.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" |
| 29.\" $FreeBSD: head/share/man/man9/pfil.9 126468 2004-03-01 22:58:07Z simon $ | 29.\" $FreeBSD: head/share/man/man9/pfil.9 130582 2004-06-16 08:33:57Z ru $ 30.\" |
| 30.Dd September 8, 2003 31.Dt PFIL 9 32.Os 33.Sh NAME 34.Nm pfil , 35.Nm pfil_head_register , 36.Nm pfil_head_unregister , 37.Nm pfil_head_get , --- 6 unchanged lines hidden (view full) --- 44.In sys/param.h 45.In sys/mbuf.h 46.In net/if.h 47.In net/pfil.h 48.Ft int 49.Fn pfil_head_register "struct pfil_head *head" 50.Ft int 51.Fn pfil_head_unregister "struct pfil_head *head" | 31.Dd September 8, 2003 32.Dt PFIL 9 33.Os 34.Sh NAME 35.Nm pfil , 36.Nm pfil_head_register , 37.Nm pfil_head_unregister , 38.Nm pfil_head_get , --- 6 unchanged lines hidden (view full) --- 45.In sys/param.h 46.In sys/mbuf.h 47.In net/if.h 48.In net/pfil.h 49.Ft int 50.Fn pfil_head_register "struct pfil_head *head" 51.Ft int 52.Fn pfil_head_unregister "struct pfil_head *head" |
| 52.Ft struct pfil_head * | 53.Ft "struct pfil_head *" |
| 53.Fn pfil_head_get "int af" "u_long dlt" | 54.Fn pfil_head_get "int af" "u_long dlt" |
| 54.Ft struct packet_filter_hook * | 55.Ft "struct packet_filter_hook *" |
| 55.Fn pfil_hook_get "int dir" "struct pfil_head *head" 56.Ft void 57.Fn pfil_add_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *" 58.Ft void 59.Fn pfil_remove_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *" 60.Ft int 61.Fn (*func) "void *arg" "struct mbuf **mp" "struct ifnet *" "int dir" 62.Ft int 63.Fn pfil_run_hooks "struct pfil_head *head" "struct mbuf **mp" "struct ifnet *" "int dir" 64.Sh DESCRIPTION 65The 66.Nm 67framework allows for a specified function to be invoked for every 68incoming or outgoing packet for a particular network I/O stream. 69These hooks may be used to implement a firewall or perform packet 70transformations. 71.Pp 72Packet filtering points are registered with 73.Fn pfil_head_register . | 56.Fn pfil_hook_get "int dir" "struct pfil_head *head" 57.Ft void 58.Fn pfil_add_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *" 59.Ft void 60.Fn pfil_remove_hook "int (*func)()" "void *arg" "int flags" "struct pfil_head *" 61.Ft int 62.Fn (*func) "void *arg" "struct mbuf **mp" "struct ifnet *" "int dir" 63.Ft int 64.Fn pfil_run_hooks "struct pfil_head *head" "struct mbuf **mp" "struct ifnet *" "int dir" 65.Sh DESCRIPTION 66The 67.Nm 68framework allows for a specified function to be invoked for every 69incoming or outgoing packet for a particular network I/O stream. 70These hooks may be used to implement a firewall or perform packet 71transformations. 72.Pp 73Packet filtering points are registered with 74.Fn pfil_head_register . |
| 74Filtering points are identified by a key (void *) and a data link type 75(int) in the 76.Em pfil_head | 75Filtering points are identified by a key 76.Pq Vt "void *" 77and a data link type 78.Pq Vt int 79in the 80.Vt pfil_head |
| 77structure. 78Packet filters use the key and data link type to look up the filtering 79point with which they register themselves. 80The key is unique to the filtering point. 81The data link type is a 82.Xr bpf 4 83DLT constant indicating what kind of header is present on the packet 84at the filtering point. --- 13 unchanged lines hidden (view full) --- 98expects. 99Filters may provide an argument to be passed to the filter when 100invoked on a packet. 101.Pp 102When a filter is invoked, the packet appears just as if it 103.Dq came off the wire . 104That is, all protocol fields are in network byte order. 105The filter is called with its specified argument, the pointer to the | 81structure. 82Packet filters use the key and data link type to look up the filtering 83point with which they register themselves. 84The key is unique to the filtering point. 85The data link type is a 86.Xr bpf 4 87DLT constant indicating what kind of header is present on the packet 88at the filtering point. --- 13 unchanged lines hidden (view full) --- 102expects. 103Filters may provide an argument to be passed to the filter when 104invoked on a packet. 105.Pp 106When a filter is invoked, the packet appears just as if it 107.Dq came off the wire . 108That is, all protocol fields are in network byte order. 109The filter is called with its specified argument, the pointer to the |
| 106pointer to the mbuf containing the packet, the pointer to the network 107interface that the packet is traversing, and the direction (PFIL_IN 108or PFIL_OUT) that the packet is traveling. 109The filter may change which mbuf the mbuf ** argument references. 110The filter returns an errno if the packet processing is to stop, or 0 | 110pointer to the 111.Vt mbuf 112containing the packet, the pointer to the network 113interface that the packet is traversing, and the direction 114.Dv ( PFIL_IN 115or 116.Dv PFIL_OUT ) 117that the packet is traveling. 118The filter may change which mbuf the 119.Vt "mbuf\ **" 120argument references. 121The filter returns an error (errno) if the packet processing is to stop, or 0 |
| 111if the processing is to continue. 112If the packet processing is to stop, it is the responsibility of the 113filter to free the packet. 114.Pp 115The 116.Nm 117interface is enabled in the kernel via the | 122if the processing is to continue. 123If the packet processing is to stop, it is the responsibility of the 124filter to free the packet. 125.Pp 126The 127.Nm 128interface is enabled in the kernel via the |
| 118.Sy PFIL_HOOKS | 129.Dv PFIL_HOOKS |
| 119option. 120.Sh RETURN VALUES 121If successful, | 130option. 131.Sh RETURN VALUES 132If successful, |
| 122.Fn pfil_head_get 123returns the pfil_head structure for the given key/dlt. 124.Fn pfil_add_hook | 133.Fn pfil_head_get 134returns the 135.Vt pfil_head 136structure for the given key/dlt. 137The 138.Fn pfil_add_hook |
| 125and 126.Fn pfil_remove_hook | 139and 140.Fn pfil_remove_hook |
| 127return 0 if successful. If called with flag PFIL_WAITOK, | 141functions 142return 0 if successful. 143If called with flag 144.Dv PFIL_WAITOK , |
| 128.Fn pfil_remove_hook 129is expected to always succeed. 130.Pp | 145.Fn pfil_remove_hook 146is expected to always succeed. 147.Pp |
| 148The |
|
| 131.Fn pfil_head_unregister | 149.Fn pfil_head_unregister |
| 150function |
|
| 132might sleep! 133.Sh HISTORY 134The 135.Nm 136interface first appeared in 137.Nx 1.3 . 138The 139.Nm 140input and output lists were originally implemented as | 151might sleep! 152.Sh HISTORY 153The 154.Nm 155interface first appeared in 156.Nx 1.3 . 157The 158.Nm 159input and output lists were originally implemented as |
| 141.Fd \*[Lt]sys/queue.h\*[Gt] | 160.In sys/queue.h |
| 142.Dv LIST 143structures; 144however this was changed in 145.Nx 1.4 146to 147.Dv TAILQ 148structures. 149This change was to allow the input and output filters to be processed in --- 11 unchanged lines hidden (view full) --- 161In 1.5K, the 162.Nm 163framework was changed to work with an arbitrary number of filtering points, 164as well as be less IP-centric. 165.Pp 166Fine-grained locking was added in 167.Fx 5.2 . 168.Sh BUGS | 161.Dv LIST 162structures; 163however this was changed in 164.Nx 1.4 165to 166.Dv TAILQ 167structures. 168This change was to allow the input and output filters to be processed in --- 11 unchanged lines hidden (view full) --- 180In 1.5K, the 181.Nm 182framework was changed to work with an arbitrary number of filtering points, 183as well as be less IP-centric. 184.Pp 185Fine-grained locking was added in 186.Fx 5.2 . 187.Sh BUGS |
| 188The |
|
| 169.Fn pfil_hook_get | 189.Fn pfil_hook_get |
| 190function |
|
| 170is only safe for internal use. 171.Pp | 191is only safe for internal use. 192.Pp |
| 172FreeBSD implements only hooks for AF_INET and AF_INET6. | 193.Fx 194implements only hooks for 195.Dv AF_INET 196and 197.Dv AF_INET6 . |
| 173Packets diverted through these hooks have data in 174host byte order contrary to the above statements. 175.Pp 176The 177.Xr bridge 4 | 198Packets diverted through these hooks have data in 199host byte order contrary to the above statements. 200.Pp 201The 202.Xr bridge 4 |
| 178diverts inbound AF_INET traffic, but contrary to the above | 203diverts inbound 204.Dv AF_INET 205traffic, but contrary to the above |
| 179statements, the data is provided in host byte order. 180.Pp | 206statements, the data is provided in host byte order. 207.Pp |
| 181When a pfil_head is being modified no traffic is diverted | 208When a 209.Vt pfil_head 210is being modified, no traffic is diverted |
| 182(to avoid deadlock). 183This means that unwanted traffic may flow for a short period 184of time. 185.Sh SEE ALSO 186.Xr bpf 4 , 187.Xr bridge 4 | 211(to avoid deadlock). 212This means that unwanted traffic may flow for a short period 213of time. 214.Sh SEE ALSO 215.Xr bpf 4 , 216.Xr bridge 4 |