diff options
Diffstat (limited to '')
| -rw-r--r-- | man7/raw.7 | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/man7/raw.7 b/man7/raw.7 new file mode 100644 index 0000000..ab43dd4 --- /dev/null +++ b/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 <ak@muc.de>. +.\" +.\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $ +.\" +.TH raw 7 2023-07-15 "Linux man-pages 6.05.01" +.SH NAME +raw \- Linux IPv4 raw sockets +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.B #include <netinet/in.h> +.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. +.PP +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. +.PP +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. +.PP +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). +.PP +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 +.PP +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. +.PP +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. +.PP +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). +.PP +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. +.PP +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. +.PP +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. +.PP +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). +.PP +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. +.PP +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). +.PP +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. +.PP +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. +.PP +Raw sockets are generally rather unportable and should be avoided in +programs intended to be portable. +.PP +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. +.PP +When the +.B IP_HDRINCL +option is set, datagrams will not be fragmented and are limited to +the interface MTU. +.PP +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) +.PP +.B RFC\ 1191 +for path MTU discovery. +.B RFC\ 791 +and the +.I <linux/ip.h> +header file for the IP protocol. |