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