| '\" t |
| .\" Don't change the first line, it tells man that we need tbl. |
| .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. |
| .\" Permission is granted to distribute possibly modified copies |
| .\" of this page provided the header is included verbatim, |
| .\" and in case of nontrivial modification author and date |
| .\" of the modification is added to the header. |
| .\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $ |
| .TH RAW 7 2012-05-10 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| raw \- Linux IPv4 raw sockets |
| .SH SYNOPSIS |
| .B #include <sys/socket.h> |
| .br |
| .B #include <netinet/in.h> |
| .br |
| .BI "raw_socket = socket(AF_INET, SOCK_RAW, int " protocol ); |
| .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. |
| |
| 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. |
| |
| Only processes with an effective user ID of 0 or the |
| .B CAP_NET_RAW |
| capability are allowed to open raw sockets. |
| |
| 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 RFC\ 1700 assigned numbers and |
| .BR getprotobyname (3). |
| |
| 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 |
| .sp |
| .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. |
| |
| 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. |
| |
| In Linux 2.2, all IP header fields and options can be set using |
| IP socket options. |
| This means raw sockets are usually only needed for new |
| protocols or protocols with no user interface (like ICMP). |
| |
| 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 |
| 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 should be always |
| set to 0 (see BUGS). |
| For incoming packets, |
| .I sin_port |
| is set to the protocol of the packet. |
| See the |
| .I <netinet/in.h> |
| include file for valid IP protocols. |
| .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 only passed to the user 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 64KB. |
| .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. |
| |
| 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 \(em 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. |
| |
| 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). |
| |
| 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. |
| |
| 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). |
| |
| 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. |
| |
| 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. |
| |
| RAW sockets are generally rather unportable and should be avoided in |
| programs intended to be portable. |
| |
| 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. |
| |
| When the |
| .B IP_HDRINCL |
| option is set, datagrams will not be fragmented and are limited to |
| the interface MTU. |
| |
| 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) |
| |
| .B RFC\ 1191 |
| for path MTU discovery. |
| .B RFC\ 791 |
| and the |
| .I <linux/ip.h> |
| header file for the IP protocol. |