| blob | 910b41464231e25f67e81c9184876f0f0383222a |
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.