man7/raw.7

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