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