man7/raw.7

   1 '\" t
   2 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM_ONE_PARA)
   5 .\" Permission is granted to distribute possibly modified copies
   6 .\" of this page provided the header is included verbatim,
   7 .\" and in case of nontrivial modification author and date
   8 .\" of the modification is added to the header.
   9 .\" %%%LICENSE_END
  10 .\"
  11 .\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $
  12 .\"
  13 .TH RAW  7 2015-03-29 "Linux" "Linux Programmer's Manual"
  14 .SH NAME
  15 raw \- Linux IPv4 raw sockets
  16 .SH SYNOPSIS
  17 .B #include <sys/socket.h>
  18 .br
  19 .B #include <netinet/in.h>
  20 .br
  21 .BI "raw_socket = socket(AF_INET, SOCK_RAW, int " protocol );
  22 .SH DESCRIPTION
  23 Raw sockets allow new IPv4 protocols to be implemented in user space.
  24 A raw socket receives or sends the raw datagram not
  25 including link level headers.
  26
  27 The IPv4 layer generates an IP header when sending a packet unless the
  28 .B IP_HDRINCL
  29 socket option is enabled on the socket.
  30 When it is enabled, the packet must contain an IP header.
  31 For receiving, the IP header is always included in the packet.
  32
  33 Only processes with an effective user ID of 0 or the
  34 .B CAP_NET_RAW
  35 capability are allowed to open raw sockets.
  36
  37 All packets or errors matching the
  38 .I protocol
  39 number specified
  40 for the raw socket are passed to this socket.
  41 For a list of the allowed protocols see RFC\ 1700 assigned numbers and
  42 .BR getprotobyname (3).
  43
  44 A protocol of
  45 .B IPPROTO_RAW
  46 implies enabled
  47 .B IP_HDRINCL
  48 and is able to send any IP protocol that is specified in the passed
  49 header.
  50 Receiving of all IP protocols via
  51 .B IPPROTO_RAW
  52 is not possible using raw sockets.
  53 .RS
  54 .TS
  55 tab(:) allbox;
  56 c s
  57 l l.
  58 IP Header fields modified on sending by \fBIP_HDRINCL\fP
  59 IP Checksum:Always filled in
  60 Source Address:Filled in when zero
  61 Packet ID:Filled in when zero
  62 Total Length:Always filled in
  63 .TE
  64 .RE
  65 .sp
  66 .PP
  67 If
  68 .B IP_HDRINCL
  69 is specified and the IP header has a nonzero destination address, then
  70 the destination address of the socket is used to route the packet.
  71 When
  72 .B MSG_DONTROUTE
  73 is specified, the destination address should refer to a local interface,
  74 otherwise a routing table lookup is done anyway but gatewayed routes
  75 are ignored.
  76
  77 If
  78 .B IP_HDRINCL
  79 isn't set, then IP header options can be set on raw sockets with
  80 .BR setsockopt (2);
  81 see
  82 .BR ip (7)
  83 for more information.
  84
  85 Starting with Linux 2.2, all IP header fields and options can be set using
  86 IP socket options.
  87 This means raw sockets are usually needed only for new
  88 protocols or protocols with no user interface (like ICMP).
  89
  90 When a packet is received, it is passed to any raw sockets which have
  91 been bound to its protocol before it is passed to other protocol handlers
  92 (e.g., kernel protocol modules).
  93 .SS Address format
  94 Raw sockets use the standard
  95 .I sockaddr_in
  96 address structure defined in
  97 .BR ip (7).
  98 The
  99 .I sin_port
 100 field could be used to specify the IP protocol number,
 101 but it is ignored for sending in Linux 2.2 and later, and should be always
 102 set to 0 (see BUGS).
 103 For incoming packets,
 104 .I sin_port
 105 .\" commit f59fc7f30b710d45aadf715460b3e60dbe9d3418
 106 is set to zero.
 107 See the
 108 .I <netinet/in.h>
 109 include file for valid IP protocols.
 110 .SS Socket options
 111 Raw socket options can be set with
 112 .BR setsockopt (2)
 113 and read with
 114 .BR getsockopt (2)
 115 by passing the
 116 .B IPPROTO_RAW
 117 .\" Or SOL_RAW on Linux
 118 family flag.
 119 .TP
 120 .B ICMP_FILTER
 121 Enable a special filter for raw sockets bound to the
 122 .B IPPROTO_ICMP
 123 protocol.
 124 The value has a bit set for each ICMP message type which
 125 should be filtered out.
 126 The default is to filter no ICMP messages.
 127 .PP
 128 In addition, all
 129 .BR ip (7)
 130 .B IPPROTO_IP
 131 socket options valid for datagram sockets are supported.
 132 .SS Error handling
 133 Errors originating from the network are passed to the user only when the
 134 socket is connected or the
 135 .B IP_RECVERR
 136 flag is enabled.
 137 For connected sockets, only
 138 .B EMSGSIZE
 139 and
 140 .B EPROTO
 141 are passed for compatibility.
 142 With
 143 .BR IP_RECVERR ,
 144 all network errors are saved in the error queue.
 145 .SH ERRORS
 146 .TP
 147 .B EACCES
 148 User tried to send to a broadcast address without having the
 149 broadcast flag set on the socket.
 150 .TP
 151 .B EFAULT
 152 An invalid memory address was supplied.
 153 .TP
 154 .B EINVAL
 155 Invalid argument.
 156 .TP
 157 .B EMSGSIZE
 158 Packet too big.
 159 Either Path MTU Discovery is enabled (the
 160 .B IP_MTU_DISCOVER
 161 socket flag) or the packet size exceeds the maximum allowed IPv4
 162 packet size of 64KB.
 163 .TP
 164 .B EOPNOTSUPP
 165 Invalid flag has been passed to a socket call (like
 166 .BR MSG_OOB ).
 167 .TP
 168 .B EPERM
 169 The user doesn't have permission to open raw sockets.
 170 Only processes with an effective user ID of 0 or the
 171 .B CAP_NET_RAW
 172 attribute may do that.
 173 .TP
 174 .B EPROTO
 175 An ICMP error has arrived reporting a parameter problem.
 176 .SH VERSIONS
 177 .B IP_RECVERR
 178 and
 179 .B ICMP_FILTER
 180 are new in Linux 2.2.
 181 They are Linux extensions and should not be used in portable programs.
 182
 183 Linux 2.0 enabled some bug-to-bug compatibility with BSD in the
 184 raw socket code when the
 185 .B SO_BSDCOMPAT
 186 socket option was set; since Linux 2.2,
 187 this option no longer has that effect.
 188 .SH NOTES
 189 By default, raw sockets do path MTU (Maximum Transmission Unit) discovery.
 190 This means the kernel
 191 will keep track of the MTU to a specific target IP address and return
 192 .B EMSGSIZE
 193 when a raw packet write exceeds it.
 194 When this happens, the application should decrease the packet size.
 195 Path MTU discovery can be also turned off using the
 196 .B IP_MTU_DISCOVER
 197 socket option or the
 198 .I /proc/sys/net/ipv4/ip_no_pmtu_disc
 199 file, see
 200 .BR ip (7)
 201 for details.
 202 When turned off, raw sockets will fragment outgoing packets
 203 that exceed the interface MTU.
 204 However, disabling it is not recommended
 205 for performance and reliability reasons.
 206
 207 A raw socket can be bound to a specific local address using the
 208 .BR bind (2)
 209 call.
 210 If it isn't bound, all packets with the specified IP protocol are received.
 211 In addition, a raw socket can be bound to a specific network device using
 212 .BR SO_BINDTODEVICE ;
 213 see
 214 .BR socket (7).
 215
 216 An
 217 .B IPPROTO_RAW
 218 socket is send only.
 219 If you really want to receive all IP packets, use a
 220 .BR packet (7)
 221 socket with the
 222 .B ETH_P_IP
 223 protocol.
 224 Note that packet sockets don't reassemble IP fragments,
 225 unlike raw sockets.
 226
 227 If you want to receive all ICMP packets for a datagram socket,
 228 it is often better to use
 229 .B IP_RECVERR
 230 on that particular socket; see
 231 .BR ip (7).
 232
 233 Raw sockets may tap all IP protocols in Linux, even
 234 protocols like ICMP or TCP which have a protocol module in the kernel.
 235 In this case, the packets are passed to both the kernel module and the raw
 236 socket(s).
 237 This should not be relied upon in portable programs, many other BSD
 238 socket implementation have limitations here.
 239
 240 Linux never changes headers passed from the user (except for filling
 241 in some zeroed fields as described for
 242 .BR IP_HDRINCL ).
 243 This differs from many other implementations of raw sockets.
 244
 245 Raw sockets are generally rather unportable and should be avoided in
 246 programs intended to be portable.
 247
 248 Sending on raw sockets should take the IP protocol from
 249 .IR sin_port ;
 250 this ability was lost in Linux 2.2.
 251 The workaround is to use
 252 .BR IP_HDRINCL .
 253 .SH BUGS
 254 Transparent proxy extensions are not described.
 255
 256 When the
 257 .B IP_HDRINCL
 258 option is set, datagrams will not be fragmented and are limited to
 259 the interface MTU.
 260
 261 Setting the IP protocol for sending in
 262 .I sin_port
 263 got lost in Linux 2.2.
 264 The protocol that the socket was bound to or that
 265 was specified in the initial
 266 .BR socket (2)
 267 call is always used.
 268 .\" .SH AUTHORS
 269 .\" This man page was written by Andi Kleen.
 270 .SH SEE ALSO
 271 .BR recvmsg (2),
 272 .BR sendmsg (2),
 273 .BR capabilities (7),
 274 .BR ip (7),
 275 .BR socket (7)
 276
 277 .B RFC\ 1191
 278 for path MTU discovery.
 279 .B RFC\ 791
 280 and the
 281 .I <linux/ip.h>
 282 header file for the IP protocol.