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