diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2016-03-01 09:40:22 +0100 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2016-03-01 11:01:27 +0100 |
| commit | 096da11042da14c532af6720cae67fc0b2b74497 (patch) | |
| tree | ef80931648fbbbfb15c8178e6a4efc25c33b65ac /man7/socket.7 | |
| parent | 6e9336599c1485f4421d504ca4653854f71a8838 (diff) | |
| download | man-pages-096da11042da14c532af6720cae67fc0b2b74497.tar.gz | |
socket.7: Minor tweaks to Craig's patch
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Diffstat (limited to 'man7/socket.7')
| -rw-r--r-- | man7/socket.7 | 125 |
1 files changed, 68 insertions, 57 deletions
diff --git a/man7/socket.7 b/man7/socket.7 index 60f7be13c2..a8a96df0b9 100644 --- a/man7/socket.7 +++ b/man7/socket.7 @@ -301,21 +301,25 @@ The value 0 indicates that this is not a listening socket, the value 1 indicates that this is a listening socket. This socket option is read-only. .TP -.BR SO_ATTACH_FILTER " and " SO_ATTACH_BPF -Attach a classic or extended BPF program (respectively) to the socket -for use as a filter of incoming packets. A packet will be dropped if -the filter program returns zero. If the filter program returns a -non-zero value which is less than the packet's data length, the packet -will be truncated to the length returned. If the value returned by -the filter is greater than or equal to the packet's data length, the -packet is allowed to proceed unmodified. +.BR SO_ATTACH_FILTER " (since Linux 2.2), " SO_ATTACH_BPF " (since Linux 3.19)" +Attach a classic BPF +.RB ( SO_ATTACH_FILTER ) +or an extended BPF +.RB ( SO_ATTACH_BPF ) +program to the socket for use as a filter of incoming packets. +A packet will be dropped if the filter program returns zero. +If the filter program returns a +non-zero value which is less than the packet's data length, +the packet will be truncated to the length returned. +If the value returned by the filter is greater than or equal to the +packet's data length, the packet is allowed to proceed unmodified. The argument for .BR SO_ATTACH_FILTER is a .I sock_fprog -structure in -.B <linux/filter.h>. +structure, defined in +.IR <linux/filter.h> : .sp .in +4n .nf @@ -332,31 +336,33 @@ is a file descriptor returned by the .BR bpf (2) system call and must refer to a program of type .BR BPF_PROG_TYPE_SOCKET_FILTER. -These options may be set multiple times for a given socket, each time -replacing the previous filter program. The classic and extended -versions may be called on the same socket, but the previous filter -will always be replaced such that a socket never has more than one -filter defined. -.BR SO_ATTACH_FILTER -is available since Linux 2.2. -.BR SO_ATTACH_BPF -is available since Linux 3.19. Both classic and extended BPF are -explained in the kernel source file +These options may be set multiple times for a given socket, +each time replacing the previous filter program. +The classic and extended versions may be called on the same socket, +but the previous filter will always be replaced such that a socket +never has more than one filter defined. + +Both classic and extended BPF are explained in the kernel source file .I Documentation/networking/filter.txt .TP -.BR SO_ATTACH_REUSEPORT_CBPF ", " SO_ATTACH_REUSEPORT_EBPF " (since Linux 4.5)" +.BR SO_ATTACH_REUSEPORT_CBPF ", " SO_ATTACH_REUSEPORT_EBPF For use with the .BR SO_REUSEPORT -option, these options allow the user to set a classic or extended -BPF program (respectively) which defines how packets are assigned to +option, these options allow the user to set a classic BPF +.RB ( SO_ATTACH_REUSEPORT_CBPF ) +or an extended BPF +.RB ( SO_ATTACH_REUSEPORT_EBPF ) +program which defines how packets are assigned to the sockets in the reuseport group (that is, all sockets which have .BR SO_REUSEPORT -set and are using the same local address to receive packets). The BPF -program must return an index between 0 and N-1 representing the socket -which should receive the packet (where N is the number of sockets in -the group). If the BPF program returns an invalid index, socket -selection will fall back to the plain +set and are using the same local address to receive packets). + +The BPF program must return an index between 0 and N\-1 representing +the socket which should receive the packet +(where N is the number of sockets in the group). +If the BPF program returns an invalid index, +socket selection will fall back to the plain .BR SO_REUSEPORT mechanism. @@ -365,25 +371,26 @@ Sockets are numbered in the order in which they are added to the group .BR bind (2) calls for UDP sockets or the order of .BR listen (2) -calls for TCP sockets). New sockets added to a reuseport group will -inherit the BPF program. When a socket is removed from a reuseport -group (via -.BR close (2)) +calls for TCP sockets). +New sockets added to a reuseport group will inherit the BPF program. +When a socket is removed from a reuseport group (via +.BR close (2)), the last socket in the group will be moved into the closed socket's position. -These options may be set repeatedly at any time on any single socket -in the group to replace the current BPF program used by all sockets in -the group. +These options may be set repeatedly at any time on any socket in the group +to replace the current BPF program used by all sockets in the group. + .BR SO_ATTACH_REUSEPORT_CBPF -takes the same socket argument type as +takes the same argument type as .BR SO_ATTACH_FILTER and .BR SO_ATTACH_REUSEPORT_EBPF -takes the same socket argument type as +takes the same argument type as .BR SO_ATTACH_BPF. -UDP support for this feature is available since Linux 4.5. -TCP support for this feature is available since Linux 4.6. + +UDP support for this feature is available since Linux 4.5; +TCP support is available since Linux 4.6. .TP .B SO_BINDTODEVICE Bind this socket to a particular device like \(lqeth0\(rq, @@ -442,17 +449,14 @@ Only allowed for processes with the .B CAP_NET_ADMIN capability or an effective user ID of 0. .TP -.BR SO_DETACH_FILTER " and " SO_DETACH_BPF -These options may be used to remove the BPF program attached to the -socket with either +.BR SO_DETACH_FILTER " (since Linux 2.2), " SO_DETACH_BPF " (since Linux 3.19)" +These two options, which are synonyms, +may be used to remove the classic or extended BPF +program attached to a socket with either .BR SO_ATTACH_FILTER or -.BR SO_ATTACH_BPF. +.BR SO_ATTACH_BPF . The option value is ignored. -.BR SO_DETACH_FILTER -is available since Linux 2.2. -.BR SO_DETACH_BPF -is available since Linux 3.19. .TP .BR SO_DOMAIN " (since Linux 2.6.32)" Retrieves the socket domain as an integer, returning a value such as @@ -510,23 +514,30 @@ When the socket is closed as part of it always lingers in the background. .TP .B SO_LOCK_FILTER +.\" commit d59577b6ffd313d0ab3be39cb1ab47e29bdc9182 When set, this option will prevent an unprivileged process from -changing the filters associated with the socket. These filters -include any set using the socket options +changing the filters associated with the socket. +These filters include any set using the socket options .BR SO_ATTACH_FILTER, .BR SO_ATTACH_BPF, .BR SO_ATTACH_REUSEPORT_CBPF -or -.BR SO_ATTACH_REUSEPORT_EPBF. -The typical use case is for a privileged process to setup a socket with +and +.BR SO_ATTACH_REUSEPORT_EPBF . + +The typical use case is for a privileged process to set up a socket with restrictive filters, set -.BR SO_LOCK_FILTER +.BR SO_LOCK_FILTER , and then either drop its privileges or pass the socket file descriptor -to an unprivileged process. Attempts to change a filter by an -unprivileged process while +to an unprivileged process. + +Once the +.BR SO_LOCK_FILTER +option has been enabled, +attempts by an unprivileged process to change or remove the filter +attached to a socket, or to disable the .BR SO_LOCK_FILTER -is set will result in an error with value -.BR EPERM. +option will fail with the error +.BR EPERM . .TP .BR SO_MARK " (since Linux 2.6.25)" .\" commit 4a19ec5800fc3bb64e2d87c4d9fdd9e636086fe0 |