Debian Codegraph @

upstream/debian-unstable/man7/packet.7

raw
1 .\" Copyright 1999, Andi Kleen <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-1-para
5 .\"
6 .TH packet 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 packet \- packet interface on device level
9 .SH SYNOPSIS
10 .nf
11 .B #include <sys/socket.h>
12 .B #include <linux/if_packet.h>
13 .B #include <net/ethernet.h> /* the L2 protocols */
14 .P
15 .BI "packet_socket = socket(AF_PACKET, int " socket_type ", int "protocol );
16 .fi
17 .SH DESCRIPTION
18 Packet sockets are used to receive or send raw packets at the device driver
19 (OSI Layer 2) level.
20 They allow the user to implement protocol modules in user space
21 on top of the physical layer.
22 .P
23 The
24 .I socket_type
25 is either
26 .B SOCK_RAW
27 for raw packets including the link-level header or
28 .B SOCK_DGRAM
29 for cooked packets with the link-level header removed.
30 The link-level header information is available in a common format in a
31 .I sockaddr_ll
32 structure.
33 .I protocol
34 is the IEEE 802.3 protocol number in network byte order.
35 See the
36 .I <linux/if_ether.h>
37 include file for a list of allowed protocols.
38 When protocol
39 is set to
40 .BR htons(ETH_P_ALL) ,
41 then all protocols are received.
42 All incoming packets of that protocol type will be passed to the packet
43 socket before they are passed to the protocols implemented in the kernel.
44 If
45 .I protocol
46 is set to zero,
47 no packets are received.
48 .BR bind (2)
49 can optionally be called with a nonzero
50 .I sll_protocol
51 to start receiving packets for the protocols specified.
52 .P
53 In order to create a packet socket, a process must have the
54 .B CAP_NET_RAW
55 capability in the user namespace that governs its network namespace.
56 .P
57 .B SOCK_RAW
58 packets are passed to and from the device driver without any changes in
59 the packet data.
60 When receiving a packet, the address is still parsed and
61 passed in a standard
62 .I sockaddr_ll
63 address structure.
64 When transmitting a packet, the user-supplied buffer
65 should contain the physical-layer header.
66 That packet is then
67 queued unmodified to the network driver of the interface defined by the
68 destination address.
69 Some device drivers always add other headers.
70 .B SOCK_RAW
71 is similar to but not compatible with the obsolete
72 .B AF_INET/SOCK_PACKET
73 of Linux 2.0.
74 .P
75 .B SOCK_DGRAM
76 operates on a slightly higher level.
77 The physical header is removed before the packet is passed to the user.
78 Packets sent through a
79 .B SOCK_DGRAM
80 packet socket get a suitable physical-layer header based on the
81 information in the
82 .I sockaddr_ll
83 destination address before they are queued.
84 .P
85 By default, all packets of the specified protocol type
86 are passed to a packet socket.
87 To get packets only from a specific interface use
88 .BR bind (2)
89 specifying an address in a
90 .I struct sockaddr_ll
91 to bind the packet socket to an interface.
92 Fields used for binding are
93 .I sll_family
94 (should be
95 .BR AF_PACKET ),
96 .IR sll_protocol ,
97 and
98 .IR sll_ifindex .
99 .P
100 The
101 .BR connect (2)
102 operation is not supported on packet sockets.
103 .P
104 When the
105 .B MSG_TRUNC
106 flag is passed to
107 .BR recvmsg (2),
108 .BR recv (2),
109 or
110 .BR recvfrom (2),
111 the real size of the packet on the wire is always returned,
112 even when it is longer than the buffer.
113 .SS Address types
114 The
115 .I sockaddr_ll
116 structure is a device-independent physical-layer address.
117 .P
118 .in +4n
119 .EX
120 struct sockaddr_ll {
121 unsigned short sll_family; /* Always AF_PACKET */
122 unsigned short sll_protocol; /* Physical\-layer protocol */
123 int sll_ifindex; /* Interface number */
124 unsigned short sll_hatype; /* ARP hardware type */
125 unsigned char sll_pkttype; /* Packet type */
126 unsigned char sll_halen; /* Size of address */
127 unsigned char sll_addr[8]; /* Physical\-layer address */
128 };
129 .EE
130 .in
131 .P
132 The fields of this structure are as follows:
133 .TP
134 .I sll_protocol
135 is the standard ethernet protocol type in network byte order as defined
136 in the
137 .I <linux/if_ether.h>
138 include file.
139 It defaults to the socket's protocol.
140 .TP
141 .I sll_ifindex
142 is the interface index of the interface
143 (see
144 .BR netdevice (7));
145 0 matches any interface (only permitted for binding).
146 .I sll_hatype
147 is an ARP type as defined in the
148 .I <linux/if_arp.h>
149 include file.
150 .TP
151 .I sll_pkttype
152 contains the packet type.
153 Valid types are
154 .B PACKET_HOST
155 for a packet addressed to the local host,
156 .B PACKET_BROADCAST
157 for a physical-layer broadcast packet,
158 .B PACKET_MULTICAST
159 for a packet sent to a physical-layer multicast address,
160 .B PACKET_OTHERHOST
161 for a packet to some other host that has been caught by a device driver
162 in promiscuous mode, and
163 .B PACKET_OUTGOING
164 for a packet originating from the local host that is looped back to a packet
165 socket.
166 These types make sense only for receiving.
167 .TP
168 .I sll_addr
169 .TQ
170 .I sll_halen
171 contain the physical-layer (e.g., IEEE 802.3) address and its size.
172 The exact interpretation depends on the device.
173 .P
174 When you send packets, it is enough to specify
175 .IR sll_family ,
176 .IR sll_addr ,
177 .IR sll_halen ,
178 .IR sll_ifindex ,
179 and
180 .IR sll_protocol .
181 The other fields should be 0.
182 .I sll_hatype
183 and
184 .I sll_pkttype
185 are set on received packets for your information.
186 .SS Socket options
187 Packet socket options are configured by calling
188 .BR setsockopt (2)
189 with level
190 .BR SOL_PACKET .
191 .TP
192 .B PACKET_ADD_MEMBERSHIP
193 .PD 0
194 .TP
195 .B PACKET_DROP_MEMBERSHIP
196 .PD
197 Packet sockets can be used to configure physical-layer multicasting
198 and promiscuous mode.
199 .B PACKET_ADD_MEMBERSHIP
200 adds a binding and
201 .B PACKET_DROP_MEMBERSHIP
202 drops it.
203 They both expect a
204 .I packet_mreq
205 structure as argument:
206 .IP
207 .in +4n
208 .EX
209 struct packet_mreq {
210 int mr_ifindex; /* interface index */
211 unsigned short mr_type; /* action */
212 unsigned short mr_alen; /* address size */
213 unsigned char mr_address[8]; /* physical\-layer address */
214 };
215 .EE
216 .in
217 .IP
218 .I mr_ifindex
219 contains the interface index for the interface whose status
220 should be changed.
221 The
222 .I mr_type
223 field specifies which action to perform.
224 .B PACKET_MR_PROMISC
225 enables receiving all packets on a shared medium (often known as
226 "promiscuous mode"),
227 .B PACKET_MR_MULTICAST
228 binds the socket to the physical-layer multicast group specified in
229 .I mr_address
230 and
231 .IR mr_alen ,
232 and
233 .B PACKET_MR_ALLMULTI
234 sets the socket up to receive all multicast packets arriving at
235 the interface.
236 .IP
237 In addition, the traditional ioctls
238 .BR SIOCSIFFLAGS ,
239 .BR SIOCADDMULTI ,
240 .B SIOCDELMULTI
241 can be used for the same purpose.
242 .TP
243 .BR PACKET_AUXDATA " (since Linux 2.6.21)"
244 .\" commit 8dc4194474159660d7f37c495e3fc3f10d0db8cc
245 If this binary option is enabled, the packet socket passes a metadata
246 structure along with each packet in the
247 .BR recvmsg (2)
248 control field.
249 The structure can be read with
250 .BR cmsg (3).
251 It is defined as
252 .IP
253 .in +4n
254 .EX
255 struct tpacket_auxdata {
256 __u32 tp_status;
257 __u32 tp_len; /* packet size */
258 __u32 tp_snaplen; /* captured size */
259 __u16 tp_mac;
260 __u16 tp_net;
261 __u16 tp_vlan_tci;
262 __u16 tp_vlan_tpid; /* Since Linux 3.14; earlier, these
263 were unused padding bytes */
264 .\" commit a0cdfcf39362410d5ea983f4daf67b38de129408 added tp_vlan_tpid
265 };
266 .EE
267 .in
268 .TP
269 .BR PACKET_FANOUT " (since Linux 3.1)"
270 .\" commit dc99f600698dcac69b8f56dda9a8a00d645c5ffc
271 To scale processing across threads, packet sockets can form a fanout
272 group.
273 In this mode, each matching packet is enqueued onto only one
274 socket in the group.
275 A socket joins a fanout group by calling
276 .BR setsockopt (2)
277 with level
278 .B SOL_PACKET
279 and option
280 .BR PACKET_FANOUT .
281 Each network namespace can have up to 65536 independent groups.
282 A socket selects a group by encoding the ID in the first 16 bits of
283 the integer option value.
284 The first packet socket to join a group implicitly creates it.
285 To successfully join an existing group, subsequent packet sockets
286 must have the same protocol, device settings, fanout mode, and
287 flags (see below).
288 Packet sockets can leave a fanout group only by closing the socket.
289 The group is deleted when the last socket is closed.
290 .IP
291 Fanout supports multiple algorithms to spread traffic between sockets,
292 as follows:
293 .RS
294 .IP \[bu] 3
295 The default mode,
296 .BR PACKET_FANOUT_HASH ,
297 sends packets from the same flow to the same socket to maintain
298 per-flow ordering.
299 For each packet, it chooses a socket by taking the packet flow hash
300 modulo the number of sockets in the group, where a flow hash is a hash
301 over network-layer address and optional transport-layer port fields.
302 .IP \[bu]
303 The load-balance mode
304 .B PACKET_FANOUT_LB
305 implements a round-robin algorithm.
306 .IP \[bu]
307 .B PACKET_FANOUT_CPU
308 selects the socket based on the CPU that the packet arrived on.
309 .IP \[bu]
310 .B PACKET_FANOUT_ROLLOVER
311 processes all data on a single socket, moving to the next when one
312 becomes backlogged.
313 .IP \[bu]
314 .B PACKET_FANOUT_RND
315 selects the socket using a pseudo-random number generator.
316 .IP \[bu]
317 .B PACKET_FANOUT_QM
318 .\" commit 2d36097d26b5991d71a2cf4a20c1a158f0f1bfcd
319 (available since Linux 3.14)
320 selects the socket using the recorded queue_mapping of the received skb.
321 .RE
322 .IP
323 Fanout modes can take additional options.
324 IP fragmentation causes packets from the same flow to have different
325 flow hashes.
326 The flag
327 .BR PACKET_FANOUT_FLAG_DEFRAG ,
328 if set, causes packets to be defragmented before fanout is applied, to
329 preserve order even in this case.
330 Fanout mode and options are communicated in the second 16 bits of the
331 integer option value.
332 The flag
333 .B PACKET_FANOUT_FLAG_ROLLOVER
334 enables the roll over mechanism as a backup strategy: if the
335 original fanout algorithm selects a backlogged socket, the packet
336 rolls over to the next available one.
337 .TP
338 .BR PACKET_LOSS " (with " PACKET_TX_RING )
339 When a malformed packet is encountered on a transmit ring,
340 the default is to reset its
341 .I tp_status
342 to
343 .B TP_STATUS_WRONG_FORMAT
344 and abort the transmission immediately.
345 The malformed packet blocks itself and subsequently enqueued packets from
346 being sent.
347 The format error must be fixed, the associated
348 .I tp_status
349 reset to
350 .BR TP_STATUS_SEND_REQUEST ,
351 and the transmission process restarted via
352 .BR send (2).
353 However, if
354 .B PACKET_LOSS
355 is set, any malformed packet will be skipped, its
356 .I tp_status
357 reset to
358 .BR TP_STATUS_AVAILABLE ,
359 and the transmission process continued.
360 .TP
361 .BR PACKET_RESERVE " (with " PACKET_RX_RING )
362 By default, a packet receive ring writes packets immediately following the
363 metadata structure and alignment padding.
364 This integer option reserves additional headroom.
365 .TP
366 .B PACKET_RX_RING
367 Create a memory-mapped ring buffer for asynchronous packet reception.
368 The packet socket reserves a contiguous region of application address
369 space, lays it out into an array of packet slots and copies packets
370 (up to
371 .IR tp_snaplen )
372 into subsequent slots.
373 Each packet is preceded by a metadata structure similar to
374 .IR tpacket_auxdata .
375 The protocol fields encode the offset to the data
376 from the start of the metadata header.
377 .I tp_net
378 stores the offset to the network layer.
379 If the packet socket is of type
380 .BR SOCK_DGRAM ,
381 then
382 .I tp_mac
383 is the same.
384 If it is of type
385 .BR SOCK_RAW ,
386 then that field stores the offset to the link-layer frame.
387 Packet socket and application communicate the head and tail of the ring
388 through the
389 .I tp_status
390 field.
391 The packet socket owns all slots with
392 .I tp_status
393 equal to
394 .BR TP_STATUS_KERNEL .
395 After filling a slot, it changes the status of the slot to transfer
396 ownership to the application.
397 During normal operation, the new
398 .I tp_status
399 value has at least the
400 .B TP_STATUS_USER
401 bit set to signal that a received packet has been stored.
402 When the application has finished processing a packet, it transfers
403 ownership of the slot back to the socket by setting
404 .I tp_status
405 equal to
406 .BR TP_STATUS_KERNEL .
407 .IP
408 Packet sockets implement multiple variants of the packet ring.
409 The implementation details are described in
410 .I Documentation/networking/packet_mmap.rst
411 in the Linux kernel source tree.
412 .TP
413 .B PACKET_STATISTICS
414 Retrieve packet socket statistics in the form of a structure
415 .IP
416 .in +4n
417 .EX
418 struct tpacket_stats {
419 unsigned int tp_packets; /* Total packet count */
420 unsigned int tp_drops; /* Dropped packet count */
421 };
422 .EE
423 .in
424 .IP
425 Receiving statistics resets the internal counters.
426 The statistics structure differs when using a ring of variant
427 .BR TPACKET_V3 .
428 .TP
429 .BR PACKET_TIMESTAMP " (with " PACKET_RX_RING "; since Linux 2.6.36)"
430 .\" commit 614f60fa9d73a9e8fdff3df83381907fea7c5649
431 The packet receive ring always stores a timestamp in the metadata header.
432 By default, this is a software generated timestamp generated when the
433 packet is copied into the ring.
434 This integer option selects the type of timestamp.
435 Besides the default, it support the two hardware formats described in
436 .I Documentation/networking/timestamping.rst
437 in the Linux kernel source tree.
438 .TP
439 .BR PACKET_TX_RING " (since Linux 2.6.31)"
440 .\" commit 69e3c75f4d541a6eb151b3ef91f34033cb3ad6e1
441 Create a memory-mapped ring buffer for packet transmission.
442 This option is similar to
443 .B PACKET_RX_RING
444 and takes the same arguments.
445 The application writes packets into slots with
446 .I tp_status
447 equal to
448 .B TP_STATUS_AVAILABLE
449 and schedules them for transmission by changing
450 .I tp_status
451 to
452 .BR TP_STATUS_SEND_REQUEST .
453 When packets are ready to be transmitted, the application calls
454 .BR send (2)
455 or a variant thereof.
456 The
457 .I buf
458 and
459 .I len
460 fields of this call are ignored.
461 If an address is passed using
462 .BR sendto (2)
463 or
464 .BR sendmsg (2),
465 then that overrides the socket default.
466 On successful transmission, the socket resets
467 .I tp_status
468 to
469 .BR TP_STATUS_AVAILABLE .
470 It immediately aborts the transmission on error unless
471 .B PACKET_LOSS
472 is set.
473 .TP
474 .BR PACKET_VERSION " (with " PACKET_RX_RING "; since Linux 2.6.27)"
475 .\" commit bbd6ef87c544d88c30e4b762b1b61ef267a7d279
476 By default,
477 .B PACKET_RX_RING
478 creates a packet receive ring of variant
479 .BR TPACKET_V1 .
480 To create another variant, configure the desired variant by setting this
481 integer option before creating the ring.
482 .TP
483 .BR PACKET_QDISC_BYPASS " (since Linux 3.14)"
484 .\" commit d346a3fae3ff1d99f5d0c819bf86edf9094a26a1
485 By default, packets sent through packet sockets pass through the kernel's
486 qdisc (traffic control) layer, which is fine for the vast majority of use
487 cases.
488 For traffic generator appliances using packet sockets
489 that intend to brute-force flood the network\[em]for example,
490 to test devices under load in a similar
491 fashion to pktgen\[em]this layer can be bypassed by setting
492 this integer option to 1.
493 A side effect is that packet buffering in the qdisc layer is avoided,
494 which will lead to increased drops when network
495 device transmit queues are busy;
496 therefore, use at your own risk.
497 .SS Ioctls
498 .B SIOCGSTAMP
499 can be used to receive the timestamp of the last received packet.
500 Argument is a
501 .I struct timeval
502 variable.
503 .\" FIXME Document SIOCGSTAMPNS
504 .P
505 In addition, all standard ioctls defined in
506 .BR netdevice (7)
507 and
508 .BR socket (7)
509 are valid on packet sockets.
510 .SS Error handling
511 Packet sockets do no error handling other than errors occurred
512 while passing the packet to the device driver.
513 They don't have the concept of a pending error.
514 .SH ERRORS
515 .TP
516 .B EADDRNOTAVAIL
517 Unknown multicast group address passed.
518 .TP
519 .B EFAULT
520 User passed invalid memory address.
521 .TP
522 .B EINVAL
523 Invalid argument.
524 .TP
525 .B EMSGSIZE
526 Packet is bigger than interface MTU.
527 .TP
528 .B ENETDOWN
529 Interface is not up.
530 .TP
531 .B ENOBUFS
532 Not enough memory to allocate the packet.
533 .TP
534 .B ENODEV
535 Unknown device name or interface index specified in interface address.
536 .TP
537 .B ENOENT
538 No packet received.
539 .TP
540 .B ENOTCONN
541 No interface address passed.
542 .TP
543 .B ENXIO
544 Interface address contained an invalid interface index.
545 .TP
546 .B EPERM
547 User has insufficient privileges to carry out this operation.
548 .P
549 In addition, other errors may be generated by the low-level driver.
550 .SH VERSIONS
551 .B AF_PACKET
552 is a new feature in Linux 2.2.
553 Earlier Linux versions supported only
554 .BR SOCK_PACKET .
555 .SH NOTES
556 For portable programs it is suggested to use
557 .B AF_PACKET
558 via
559 .BR pcap (3);
560 although this covers only a subset of the
561 .B AF_PACKET
562 features.
563 .P
564 The
565 .B SOCK_DGRAM
566 packet sockets make no attempt to create or parse the IEEE 802.2 LLC
567 header for a IEEE 802.3 frame.
568 When
569 .B ETH_P_802_3
570 is specified as protocol for sending the kernel creates the
571 802.3 frame and fills out the size field;
572 the user has to supply the LLC header to get a fully conforming packet.
573 Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol fields;
574 instead they are supplied to the user as protocol
575 .B ETH_P_802_2
576 with the LLC header prefixed.
577 It is thus not possible to bind to
578 .BR ETH_P_802_3 ;
579 bind to
580 .B ETH_P_802_2
581 instead and do the protocol multiplex yourself.
582 The default for sending is the standard Ethernet DIX
583 encapsulation with the protocol filled in.
584 .P
585 Packet sockets are not subject to the input or output firewall chains.
586 .SS Compatibility
587 In Linux 2.0, the only way to get a packet socket was with the call:
588 .P
589 .in +4n
590 .EX
591 socket(AF_INET, SOCK_PACKET, protocol)
592 .EE
593 .in
594 .P
595 This is still supported, but deprecated and strongly discouraged.
596 The main difference between the two methods is that
597 .B SOCK_PACKET
598 uses the old
599 .I struct sockaddr_pkt
600 to specify an interface, which doesn't provide physical-layer
601 independence.
602 .P
603 .in +4n
604 .EX
605 struct sockaddr_pkt {
606 unsigned short spkt_family;
607 unsigned char spkt_device[14];
608 unsigned short spkt_protocol;
609 };
610 .EE
611 .in
612 .P
613 .I spkt_family
614 contains
615 the device type,
616 .I spkt_protocol
617 is the IEEE 802.3 protocol type as defined in
618 .I <sys/if_ether.h>
619 and
620 .I spkt_device
621 is the device name as a null-terminated string, for example, eth0.
622 .P
623 This structure is obsolete and should not be used in new code.
624 .SH BUGS
625 .SS LLC header handling
626 The IEEE 802.2/803.3 LLC handling could be considered as a bug.
627 .SS MSG_TRUNC issues
628 The
629 .B MSG_TRUNC
630 .BR recvmsg (2)
631 extension is an ugly hack and should be replaced by a control message.
632 There is currently no way to get the original destination address of
633 packets via
634 .BR SOCK_DGRAM .
635 .SS spkt_device device name truncation
636 The
637 .I spkt_device
638 field of
639 .I sockaddr_pkt
640 has a size of 14 bytes,
641 which is less than the constant
642 .B IFNAMSIZ
643 defined in
644 .I <net/if.h>
645 which is 16 bytes and describes the system limit for a network interface name.
646 This means the names of network devices longer than 14 bytes
647 will be truncated to fit into
648 .IR spkt_device .
649 All these sizes include the terminating null byte (\[aq]\[rs]0\[aq])).
650 .P
651 Issues from this with old code typically show up with
652 very long interface names used by the
653 .B Predictable Network Interface Names
654 feature enabled by default in many modern Linux distributions.
655 .P
656 The preferred solution is to rewrite code to avoid
657 .BR SOCK_PACKET .
658 Possible user solutions are to disable
659 .B Predictable Network Interface Names
660 or to rename the interface to a name of at most 13 bytes,
661 for example using the
662 .BR ip (8)
663 tool.
664 .SS Documentation issues
665 Socket filters are not documented.
666 .\" .SH CREDITS
667 .\" This man page was written by Andi Kleen with help from Matthew Wilcox.
668 .\" AF_PACKET in Linux 2.2 was implemented
669 .\" by Alexey Kuznetsov, based on code by Alan Cox and others.
670 .SH SEE ALSO
671 .BR socket (2),
672 .BR pcap (3),
673 .BR capabilities (7),
674 .BR ip (7),
675 .BR raw (7),
676 .BR socket (7),
677 .BR ip (8),
678 .P
679 RFC\ 894 for the standard IP Ethernet encapsulation.
680 RFC\ 1700 for the IEEE 802.3 IP encapsulation.
681 .P
682 The
683 .I <linux/if_ether.h>
684 include file for physical-layer protocols.
685 .P
686 The Linux kernel source tree.
687 .I Documentation/networking/filter.rst
688 describes how to apply Berkeley Packet Filters to packet sockets.
689 .I tools/testing/selftests/net/psock_tpacket.c
690 contains example source code for all available versions of
691 .B PACKET_RX_RING
692 and
693 .BR PACKET_TX_RING .