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