[GitHub/mt8127/android_kernel_alcatel_ttab.git] / Documentation / networking / filter.txt

filter.txt: Linux Socket Filtering
Written by: Jay Schulist <jschlst@samba.org>

Introduction
============

	Linux Socket Filtering is derived from the Berkeley
Packet Filter. There are some distinct differences between
the BSD and Linux Kernel Filtering.

Linux Socket Filtering (LSF) allows a user-space program to
attach a filter onto any socket and allow or disallow certain
types of data to come through the socket. LSF follows exactly
the same filter code structure as the BSD Berkeley Packet Filter
(BPF), so referring to the BSD bpf.4 manpage is very helpful in
creating filters.

LSF is much simpler than BPF. One does not have to worry about
devices or anything like that. You simply create your filter
code, send it to the kernel via the SO_ATTACH_FILTER option and
if your filter code passes the kernel check on it, you then
immediately begin filtering data on that socket.

You can also detach filters from your socket via the
SO_DETACH_FILTER option. This will probably not be used much
since when you close a socket that has a filter on it the
filter is automagically removed. The other less common case
may be adding a different filter on the same socket where you had another
filter that is still running: the kernel takes care of removing
the old one and placing your new one in its place, assuming your
filter has passed the checks, otherwise if it fails the old filter
will remain on that socket.

SO_LOCK_FILTER option allows to lock the filter attached to a
socket. Once set, a filter cannot be removed or changed. This allows
one process to setup a socket, attach a filter, lock it then drop
privileges and be assured that the filter will be kept until the
socket is closed.

Examples
========

Ioctls-
setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_FILTER, &Filter, sizeof(Filter));
setsockopt(sockfd, SOL_SOCKET, SO_DETACH_FILTER, &value, sizeof(value));
setsockopt(sockfd, SOL_SOCKET, SO_LOCK_FILTER, &value, sizeof(value));

See the BSD bpf.4 manpage and the BSD Packet Filter paper written by
Steven McCanne and Van Jacobson of Lawrence Berkeley Laboratory.
Commit	Line	Data
1da177e4 LT	1	filter.txt: Linux Socket Filtering
	2	Written by: Jay Schulist <jschlst@samba.org>
	3
	4	Introduction
	5	============
	6
	7	Linux Socket Filtering is derived from the Berkeley
	8	Packet Filter. There are some distinct differences between
	9	the BSD and Linux Kernel Filtering.
	10
	11	Linux Socket Filtering (LSF) allows a user-space program to
	12	attach a filter onto any socket and allow or disallow certain
	13	types of data to come through the socket. LSF follows exactly
	14	the same filter code structure as the BSD Berkeley Packet Filter
	15	(BPF), so referring to the BSD bpf.4 manpage is very helpful in
	16	creating filters.
	17
	18	LSF is much simpler than BPF. One does not have to worry about
	19	devices or anything like that. You simply create your filter
d59577b6	20	code, send it to the kernel via the SO_ATTACH_FILTER option and
1da177e4 LT	21	if your filter code passes the kernel check on it, you then
	22	immediately begin filtering data on that socket.
	23
	24	You can also detach filters from your socket via the
d59577b6	25	SO_DETACH_FILTER option. This will probably not be used much
1da177e4 LT	26	since when you close a socket that has a filter on it the
	27	filter is automagically removed. The other less common case
	28	may be adding a different filter on the same socket where you had another
	29	filter that is still running: the kernel takes care of removing
	30	the old one and placing your new one in its place, assuming your
	31	filter has passed the checks, otherwise if it fails the old filter
	32	will remain on that socket.
	33
d59577b6 VB	34	SO_LOCK_FILTER option allows to lock the filter attached to a
	35	socket. Once set, a filter cannot be removed or changed. This allows
	36	one process to setup a socket, attach a filter, lock it then drop
	37	privileges and be assured that the filter will be kept until the
	38	socket is closed.
	39
1da177e4 LT	40	Examples
	41	========
	42
	43	Ioctls-
	44	setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_FILTER, &Filter, sizeof(Filter));
	45	setsockopt(sockfd, SOL_SOCKET, SO_DETACH_FILTER, &value, sizeof(value));
d59577b6	46	setsockopt(sockfd, SOL_SOCKET, SO_LOCK_FILTER, &value, sizeof(value));
1da177e4 LT	47
	48	See the BSD bpf.4 manpage and the BSD Packet Filter paper written by
	49	Steven McCanne and Van Jacobson of Lawrence Berkeley Laboratory.