Debian Codegraph @

upstream/debian-unstable/man7/raw.7

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