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