man7/raw.7

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