From 3d08cd331c1adcf0d917392f7e527b3f00511748 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:22 +0200 Subject: Merging upstream version 6.8. Signed-off-by: Daniel Baumann --- man/man7/raw.7 | 281 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 281 insertions(+) create mode 100644 man/man7/raw.7 (limited to 'man/man7/raw.7') diff --git a/man/man7/raw.7 b/man/man7/raw.7 new file mode 100644 index 0000000..44b1aff --- /dev/null +++ b/man/man7/raw.7 @@ -0,0 +1,281 @@ +'\" t +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $ +.\" +.TH raw 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +raw \- Linux IPv4 raw sockets +.SH SYNOPSIS +.nf +.B #include +.B #include +.BI "raw_socket = socket(AF_INET, SOCK_RAW, int " protocol ); +.fi +.SH DESCRIPTION +Raw sockets allow new IPv4 protocols to be implemented in user space. +A raw socket receives or sends the raw datagram not +including link level headers. +.P +The IPv4 layer generates an IP header when sending a packet unless the +.B IP_HDRINCL +socket option is enabled on the socket. +When it is enabled, the packet must contain an IP header. +For receiving, the IP header is always included in the packet. +.P +In order to create a raw socket, a process must have the +.B CAP_NET_RAW +capability in the user namespace that governs its network namespace. +.P +All packets or errors matching the +.I protocol +number specified +for the raw socket are passed to this socket. +For a list of the allowed protocols, +see the IANA list of assigned protocol numbers at +.UR http://www.iana.org/assignments/protocol\-numbers/ +.UE +and +.BR getprotobyname (3). +.P +A protocol of +.B IPPROTO_RAW +implies enabled +.B IP_HDRINCL +and is able to send any IP protocol that is specified in the passed +header. +Receiving of all IP protocols via +.B IPPROTO_RAW +is not possible using raw sockets. +.RS +.TS +tab(:) allbox; +c s +l l. +IP Header fields modified on sending by \fBIP_HDRINCL\fP +IP Checksum:Always filled in +Source Address:Filled in when zero +Packet ID:Filled in when zero +Total Length:Always filled in +.TE +.RE +.P +If +.B IP_HDRINCL +is specified and the IP header has a nonzero destination address, then +the destination address of the socket is used to route the packet. +When +.B MSG_DONTROUTE +is specified, the destination address should refer to a local interface, +otherwise a routing table lookup is done anyway but gatewayed routes +are ignored. +.P +If +.B IP_HDRINCL +isn't set, then IP header options can be set on raw sockets with +.BR setsockopt (2); +see +.BR ip (7) +for more information. +.P +Starting with Linux 2.2, all IP header fields and options can be set using +IP socket options. +This means raw sockets are usually needed only for new +protocols or protocols with no user interface (like ICMP). +.P +When a packet is received, it is passed to any raw sockets which have +been bound to its protocol before it is passed to other protocol handlers +(e.g., kernel protocol modules). +.SS Address format +For sending and receiving datagrams +.RB ( sendto (2), +.BR recvfrom (2), +and similar), +raw sockets use the standard +.I sockaddr_in +address structure defined in +.BR ip (7). +The +.I sin_port +field could be used to specify the IP protocol number, +but it is ignored for sending in Linux 2.2 and later, and should be always +set to 0 (see BUGS). +For incoming packets, +.I sin_port +.\" commit f59fc7f30b710d45aadf715460b3e60dbe9d3418 +is set to zero. +.SS Socket options +Raw socket options can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2) +by passing the +.B IPPROTO_RAW +.\" Or SOL_RAW on Linux +family flag. +.TP +.B ICMP_FILTER +Enable a special filter for raw sockets bound to the +.B IPPROTO_ICMP +protocol. +The value has a bit set for each ICMP message type which +should be filtered out. +The default is to filter no ICMP messages. +.P +In addition, all +.BR ip (7) +.B IPPROTO_IP +socket options valid for datagram sockets are supported. +.SS Error handling +Errors originating from the network are passed to the user only when the +socket is connected or the +.B IP_RECVERR +flag is enabled. +For connected sockets, only +.B EMSGSIZE +and +.B EPROTO +are passed for compatibility. +With +.BR IP_RECVERR , +all network errors are saved in the error queue. +.SH ERRORS +.TP +.B EACCES +User tried to send to a broadcast address without having the +broadcast flag set on the socket. +.TP +.B EFAULT +An invalid memory address was supplied. +.TP +.B EINVAL +Invalid argument. +.TP +.B EMSGSIZE +Packet too big. +Either Path MTU Discovery is enabled (the +.B IP_MTU_DISCOVER +socket flag) or the packet size exceeds the maximum allowed IPv4 +packet size of 64\ kB. +.TP +.B EOPNOTSUPP +Invalid flag has been passed to a socket call (like +.BR MSG_OOB ). +.TP +.B EPERM +The user doesn't have permission to open raw sockets. +Only processes with an effective user ID of 0 or the +.B CAP_NET_RAW +attribute may do that. +.TP +.B EPROTO +An ICMP error has arrived reporting a parameter problem. +.SH VERSIONS +.B IP_RECVERR +and +.B ICMP_FILTER +are new in Linux 2.2. +They are Linux extensions and should not be used in portable programs. +.P +Linux 2.0 enabled some bug-to-bug compatibility with BSD in the +raw socket code when the +.B SO_BSDCOMPAT +socket option was set; since Linux 2.2, +this option no longer has that effect. +.SH NOTES +By default, raw sockets do path MTU (Maximum Transmission Unit) discovery. +This means the kernel +will keep track of the MTU to a specific target IP address and return +.B EMSGSIZE +when a raw packet write exceeds it. +When this happens, the application should decrease the packet size. +Path MTU discovery can be also turned off using the +.B IP_MTU_DISCOVER +socket option or the +.I /proc/sys/net/ipv4/ip_no_pmtu_disc +file, see +.BR ip (7) +for details. +When turned off, raw sockets will fragment outgoing packets +that exceed the interface MTU. +However, disabling it is not recommended +for performance and reliability reasons. +.P +A raw socket can be bound to a specific local address using the +.BR bind (2) +call. +If it isn't bound, all packets with the specified IP protocol are received. +In addition, a raw socket can be bound to a specific network device using +.BR SO_BINDTODEVICE ; +see +.BR socket (7). +.P +An +.B IPPROTO_RAW +socket is send only. +If you really want to receive all IP packets, use a +.BR packet (7) +socket with the +.B ETH_P_IP +protocol. +Note that packet sockets don't reassemble IP fragments, +unlike raw sockets. +.P +If you want to receive all ICMP packets for a datagram socket, +it is often better to use +.B IP_RECVERR +on that particular socket; see +.BR ip (7). +.P +Raw sockets may tap all IP protocols in Linux, even +protocols like ICMP or TCP which have a protocol module in the kernel. +In this case, the packets are passed to both the kernel module and the raw +socket(s). +This should not be relied upon in portable programs, many other BSD +socket implementation have limitations here. +.P +Linux never changes headers passed from the user (except for filling +in some zeroed fields as described for +.BR IP_HDRINCL ). +This differs from many other implementations of raw sockets. +.P +Raw sockets are generally rather unportable and should be avoided in +programs intended to be portable. +.P +Sending on raw sockets should take the IP protocol from +.IR sin_port ; +this ability was lost in Linux 2.2. +The workaround is to use +.BR IP_HDRINCL . +.SH BUGS +Transparent proxy extensions are not described. +.P +When the +.B IP_HDRINCL +option is set, datagrams will not be fragmented and are limited to +the interface MTU. +.P +Setting the IP protocol for sending in +.I sin_port +got lost in Linux 2.2. +The protocol that the socket was bound to or that +was specified in the initial +.BR socket (2) +call is always used. +.\" .SH AUTHORS +.\" This man page was written by Andi Kleen. +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2), +.BR capabilities (7), +.BR ip (7), +.BR socket (7) +.P +.B RFC\ 1191 +for path MTU discovery. +.B RFC\ 791 +and the +.I +header file for the IP protocol. -- cgit v1.2.3