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 2016-10-08 "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 In order to create a raw socket, a process must have the
  34 .B CAP_NET_RAW
  35 capability in the user namespace that governs its network namespace.
  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 .SS Socket options
 116 Raw socket options can be set with
 117 .BR setsockopt (2)
 118 and read with
 119 .BR getsockopt (2)
 120 by passing the
 121 .B IPPROTO_RAW
 122 .\" Or SOL_RAW on Linux
 123 family flag.
 124 .TP
 125 .B ICMP_FILTER
 126 Enable a special filter for raw sockets bound to the
 127 .B IPPROTO_ICMP
 128 protocol.
 129 The value has a bit set for each ICMP message type which
 130 should be filtered out.
 131 The default is to filter no ICMP messages.
 132 .PP
 133 In addition, all
 134 .BR ip (7)
 135 .B IPPROTO_IP
 136 socket options valid for datagram sockets are supported.
 137 .SS Error handling
 138 Errors originating from the network are passed to the user only when the
 139 socket is connected or the
 140 .B IP_RECVERR
 141 flag is enabled.
 142 For connected sockets, only
 143 .B EMSGSIZE
 144 and
 145 .B EPROTO
 146 are passed for compatibility.
 147 With
 148 .BR IP_RECVERR ,
 149 all network errors are saved in the error queue.
 150 .SH ERRORS
 151 .TP
 152 .B EACCES
 153 User tried to send to a broadcast address without having the
 154 broadcast flag set on the socket.
 155 .TP
 156 .B EFAULT
 157 An invalid memory address was supplied.
 158 .TP
 159 .B EINVAL
 160 Invalid argument.
 161 .TP
 162 .B EMSGSIZE
 163 Packet too big.
 164 Either Path MTU Discovery is enabled (the
 165 .B IP_MTU_DISCOVER
 166 socket flag) or the packet size exceeds the maximum allowed IPv4
 167 packet size of 64KB.
 168 .TP
 169 .B EOPNOTSUPP
 170 Invalid flag has been passed to a socket call (like
 171 .BR MSG_OOB ).
 172 .TP
 173 .B EPERM
 174 The user doesn't have permission to open raw sockets.
 175 Only processes with an effective user ID of 0 or the
 176 .B CAP_NET_RAW
 177 attribute may do that.
 178 .TP
 179 .B EPROTO
 180 An ICMP error has arrived reporting a parameter problem.
 181 .SH VERSIONS
 182 .B IP_RECVERR
 183 and
 184 .B ICMP_FILTER
 185 are new in Linux 2.2.
 186 They are Linux extensions and should not be used in portable programs.
 187
 188 Linux 2.0 enabled some bug-to-bug compatibility with BSD in the
 189 raw socket code when the
 190 .B SO_BSDCOMPAT
 191 socket option was set; since Linux 2.2,
 192 this option no longer has that effect.
 193 .SH NOTES
 194 By default, raw sockets do path MTU (Maximum Transmission Unit) discovery.
 195 This means the kernel
 196 will keep track of the MTU to a specific target IP address and return
 197 .B EMSGSIZE
 198 when a raw packet write exceeds it.
 199 When this happens, the application should decrease the packet size.
 200 Path MTU discovery can be also turned off using the
 201 .B IP_MTU_DISCOVER
 202 socket option or the
 203 .I /proc/sys/net/ipv4/ip_no_pmtu_disc
 204 file, see
 205 .BR ip (7)
 206 for details.
 207 When turned off, raw sockets will fragment outgoing packets
 208 that exceed the interface MTU.
 209 However, disabling it is not recommended
 210 for performance and reliability reasons.
 211
 212 A raw socket can be bound to a specific local address using the
 213 .BR bind (2)
 214 call.
 215 If it isn't bound, all packets with the specified IP protocol are received.
 216 In addition, a raw socket can be bound to a specific network device using
 217 .BR SO_BINDTODEVICE ;
 218 see
 219 .BR socket (7).
 220
 221 An
 222 .B IPPROTO_RAW
 223 socket is send only.
 224 If you really want to receive all IP packets, use a
 225 .BR packet (7)
 226 socket with the
 227 .B ETH_P_IP
 228 protocol.
 229 Note that packet sockets don't reassemble IP fragments,
 230 unlike raw sockets.
 231
 232 If you want to receive all ICMP packets for a datagram socket,
 233 it is often better to use
 234 .B IP_RECVERR
 235 on that particular socket; see
 236 .BR ip (7).
 237
 238 Raw sockets may tap all IP protocols in Linux, even
 239 protocols like ICMP or TCP which have a protocol module in the kernel.
 240 In this case, the packets are passed to both the kernel module and the raw
 241 socket(s).
 242 This should not be relied upon in portable programs, many other BSD
 243 socket implementation have limitations here.
 244
 245 Linux never changes headers passed from the user (except for filling
 246 in some zeroed fields as described for
 247 .BR IP_HDRINCL ).
 248 This differs from many other implementations of raw sockets.
 249
 250 Raw sockets are generally rather unportable and should be avoided in
 251 programs intended to be portable.
 252
 253 Sending on raw sockets should take the IP protocol from
 254 .IR sin_port ;
 255 this ability was lost in Linux 2.2.
 256 The workaround is to use
 257 .BR IP_HDRINCL .
 258 .SH BUGS
 259 Transparent proxy extensions are not described.
 260
 261 When the
 262 .B IP_HDRINCL
 263 option is set, datagrams will not be fragmented and are limited to
 264 the interface MTU.
 265
 266 Setting the IP protocol for sending in
 267 .I sin_port
 268 got lost in Linux 2.2.
 269 The protocol that the socket was bound to or that
 270 was specified in the initial
 271 .BR socket (2)
 272 call is always used.
 273 .\" .SH AUTHORS
 274 .\" This man page was written by Andi Kleen.
 275 .SH SEE ALSO
 276 .BR recvmsg (2),
 277 .BR sendmsg (2),
 278 .BR capabilities (7),
 279 .BR ip (7),
 280 .BR socket (7)
 281
 282 .B RFC\ 1191
 283 for path MTU discovery.
 284 .B RFC\ 791
 285 and the
 286 .I <linux/ip.h>
 287 header file for the IP protocol.