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