1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
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.
10 .\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $
12 .TH PACKET 7 2016-10-08 "Linux" "Linux Programmer's Manual"
14 packet \- packet interface on device level
17 .B #include <sys/socket.h>
19 .B #include <linux/if_packet.h>
21 .B #include <net/ethernet.h> /* the L2 protocols */
23 .BI "packet_socket = socket(AF_PACKET, int " socket_type ", int "protocol );
26 Packet sockets are used to receive or send raw packets at the device driver
28 They allow the user to implement protocol modules in user space
29 on top of the physical layer.
35 for raw packets including the link-level header or
37 for cooked packets with the link-level header removed.
38 The link-level header information is available in a common format in a
42 is the IEEE 802.3 protocol number in network byte order.
45 include file for a list of allowed protocols.
48 .BR htons(ETH_P_ALL) ,
49 then all protocols are received.
50 All incoming packets of that protocol type will be passed to the packet
51 socket before they are passed to the protocols implemented in the kernel.
53 In order to create a packet socket, a process must have the
55 capability in the user namespace that governs its network namespace.
58 packets are passed to and from the device driver without any changes in
60 When receiving a packet, the address is still parsed and
64 When transmitting a packet, the user-supplied buffer
65 should contain the physical-layer header.
67 queued unmodified to the network driver of the interface defined by the
69 Some device drivers always add other headers.
71 is similar to but not compatible with the obsolete
72 .B AF_INET/SOCK_PACKET
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
80 packet socket get a suitable physical-layer header based on the
83 destination address before they are queued.
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
89 specifying an address in a
91 to bind the packet socket to an interface.
92 Fields used for binding are
102 operation is not supported on packet sockets.
111 the real length of the packet on the wire is always returned,
112 even when it is longer than the buffer.
116 structure is a device-independent physical-layer address.
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; /* Length of address */
127 unsigned char sll_addr[8]; /* Physical-layer address */
132 The fields of this structure are as follows:
135 is the standard ethernet protocol type in network byte order as defined
137 .I <linux/if_ether.h>
139 It defaults to the socket's protocol.
142 is the interface index of the interface
145 0 matches any interface (only permitted for binding).
147 is an ARP type as defined in the
152 contains the packet type.
155 for a packet addressed to the local host,
157 for a physical-layer broadcast packet,
159 for a packet sent to a physical-layer multicast address,
161 for a packet to some other host that has been caught by a device driver
162 in promiscuous mode, and
164 for a packet originating from the local host that is looped back to a packet
166 These types make sense only for receiving.
171 contain the physical-layer (e.g., IEEE 802.3) address and its length.
172 The exact interpretation depends on the device.
174 When you send packets, it is enough to specify
181 The other fields should be 0.
185 are set on received packets for your information.
187 Packet socket options are configured by calling
192 .BR PACKET_ADD_MEMBERSHIP
195 .BR PACKET_DROP_MEMBERSHIP
197 Packet sockets can be used to configure physical-layer multicasting
198 and promiscuous mode.
199 .B PACKET_ADD_MEMBERSHIP
201 .B PACKET_DROP_MEMBERSHIP
205 structure as argument:
210 int mr_ifindex; /* interface index */
211 unsigned short mr_type; /* action */
212 unsigned short mr_alen; /* address length */
213 unsigned char mr_address[8]; /* physical-layer address */
219 contains the interface index for the interface whose status
223 field specifies which action to perform.
225 enables receiving all packets on a shared medium (often known as
227 .B PACKET_MR_MULTICAST
228 binds the socket to the physical-layer multicast group specified in
233 .B PACKET_MR_ALLMULTI
234 sets the socket up to receive all multicast packets arriving at
237 In addition, the traditional ioctls
241 can be used for the same purpose.
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
249 The structure can be read with
255 struct tpacket_auxdata {
257 __u32 tp_len; /* packet length */
258 __u32 tp_snaplen; /* captured length */
267 .BR PACKET_FANOUT " (since Linux 3.1)"
268 .\" commit dc99f600698dcac69b8f56dda9a8a00d645c5ffc
269 To scale processing across threads, packet sockets can form a fanout
271 In this mode, each matching packet is enqueued onto only one
273 A socket joins a fanout group by calling
279 Each network namespace can have up to 65536 independent groups.
280 A socket selects a group by encoding the ID in the first 16 bits of
281 the integer option value.
282 The first packet socket to join a group implicitly creates it.
283 To successfully join an existing group, subsequent packet sockets
284 must have the same protocol, device settings, fanout mode and
286 Packet sockets can leave a fanout group only by closing the socket.
287 The group is deleted when the last socket is closed.
289 Fanout supports multiple algorithms to spread traffic between sockets,
294 .BR PACKET_FANOUT_HASH ,
295 sends packets from the same flow to the same socket to maintain
297 For each packet, it chooses a socket by taking the packet flow hash
298 modulo the number of sockets in the group, where a flow hash is a hash
299 over network-layer address and optional transport-layer port fields.
301 The load-balance mode
303 implements a round-robin algorithm.
305 .BR PACKET_FANOUT_CPU
306 selects the socket based on the CPU that the packet arrived on.
308 .BR PACKET_FANOUT_ROLLOVER
309 processes all data on a single socket, moving to the next when one
312 .BR PACKET_FANOUT_RND
313 selects the socket using a pseudo-random number generator.
316 .\" commit 2d36097d26b5991d71a2cf4a20c1a158f0f1bfcd
317 (available since Linux 3.14)
318 selects the socket using the recorded queue_mapping of the received skb.
321 Fanout modes can take additional options.
322 IP fragmentation causes packets from the same flow to have different
325 .BR PACKET_FANOUT_FLAG_DEFRAG ,
326 if set, causes packets to be defragmented before fanout is applied, to
327 preserve order even in this case.
328 Fanout mode and options are communicated in the second 16 bits of the
329 integer option value.
331 .BR PACKET_FANOUT_FLAG_ROLLOVER
332 enables the roll over mechanism as a backup strategy: if the
333 original fanout algorithm selects a backlogged socket, the packet
334 rolls over to the next available one.
336 .BR PACKET_LOSS " (with " PACKET_TX_RING )
337 When a malformed packet is encountered on a transmit ring,
338 the default is to reset its
341 .BR TP_STATUS_WRONG_FORMAT
342 and abort the transmission immediately.
343 The malformed packet blocks itself and subsequently enqueued packets from
345 The format error must be fixed, the associated
348 .BR TP_STATUS_SEND_REQUEST ,
349 and the transmission process restarted via
353 is set, any malformed packet will be skipped, its
356 .BR TP_STATUS_AVAILABLE ,
357 and the transmission process continued.
359 .BR PACKET_RESERVE " (with " PACKET_RX_RING )
360 By default, a packet receive ring writes packets immediately following the
361 metadata structure and alignment padding.
362 This integer option reserves additional headroom.
365 Create a memory-mapped ring buffer for asynchronous packet reception.
366 The packet socket reserves a contiguous region of application address
367 space, lays it out into an array of packet slots and copies packets
370 into subsequent slots.
371 Each packet is preceded by a metadata structure similar to
372 .IR tpacket_auxdata .
373 The protocol fields encode the offset to the data
374 from the start of the metadata header.
376 stores the offset to the network layer.
377 If the packet socket is of type
384 then that field stores the offset to the link-layer frame.
385 Packet socket and application communicate the head and tail of the ring
389 The packet socket owns all slots with
392 .BR TP_STATUS_KERNEL .
393 After filling a slot, it changes the status of the slot to transfer
394 ownership to the application.
395 During normal operation, the new
397 value has at least the
399 bit set to signal that a received packet has been stored.
400 When the application has finished processing a packet, it transfers
401 ownership of the slot back to the socket by setting
404 .BR TP_STATUS_KERNEL .
406 Packet sockets implement multiple variants of the packet ring.
407 The implementation details are described in
408 .IR Documentation/networking/packet_mmap.txt
409 in the Linux kernel source tree.
411 .BR PACKET_STATISTICS
412 Retrieve packet socket statistics in the form of a structure
416 struct tpacket_stats {
417 unsigned int tp_packets; /* Total packet count */
418 unsigned int tp_drops; /* Dropped packet count */
423 Receiving statistics resets the internal counters.
424 The statistics structure differs when using a ring of variant
427 .BR PACKET_TIMESTAMP " (with " PACKET_RX_RING "; since Linux 2.6.36)"
428 .\" commit 614f60fa9d73a9e8fdff3df83381907fea7c5649
429 The packet receive ring always stores a timestamp in the metadata header.
430 By default, this is a software generated timestamp generated when the
431 packet is copied into the ring.
432 This integer option selects the type of timestamp.
433 Besides the default, it support the two hardware formats described in
434 .IR Documentation/networking/timestamping.txt
435 in the Linux kernel source tree.
437 .BR PACKET_TX_RING " (since Linux 2.6.31)"
438 .\" commit 69e3c75f4d541a6eb151b3ef91f34033cb3ad6e1
439 Create a memory-mapped ring buffer for packet transmission.
440 This option is similar to
442 and takes the same arguments.
443 The application writes packets into slots with
446 .BR TP_STATUS_AVAILABLE
447 and schedules them for transmission by changing
450 .BR TP_STATUS_SEND_REQUEST .
451 When packets are ready to be transmitted, the application calls
453 or a variant thereof.
458 fields of this call are ignored.
459 If an address is passed using
463 then that overrides the socket default.
464 On successful transmission, the socket resets
467 .BR TP_STATUS_AVAILABLE .
468 It immediately aborts the transmission on error unless
472 .BR PACKET_VERSION " (with " PACKET_RX_RING "; since Linux 2.6.27)"
473 .\" commit bbd6ef87c544d88c30e4b762b1b61ef267a7d279
476 creates a packet receive ring of variant
478 To create another variant, configure the desired variant by setting this
479 integer option before creating the ring.
481 .BR PACKET_QDISC_BYPASS " (since Linux 3.14)"
482 .\" commit d346a3fae3ff1d99f5d0c819bf86edf9094a26a1
483 By default, packets sent through packet sockets pass through the kernel's
484 qdisc (traffic control) layer, which is fine for the vast majority of use
486 For traffic generator appliances using packet sockets
487 that intend to brute-force flood the network\(emfor example,
488 to test devices under load in a similar
489 fashion to pktgen\(emthis layer can be bypassed by setting
490 this integer option to 1.
491 A side effect is that packet buffering in the qdisc layer is avoided,
492 which will lead to increased drops when network
493 device transmit queues are busy;
494 therefore, use at your own risk.
497 can be used to receive the timestamp of the last received packet.
501 .\" FIXME Document SIOCGSTAMPNS
503 In addition, all standard ioctls defined in
507 are valid on packet sockets.
509 Packet sockets do no error handling other than errors occurred
510 while passing the packet to the device driver.
511 They don't have the concept of a pending error.
515 Unknown multicast group address passed.
518 User passed invalid memory address.
524 Packet is bigger than interface MTU.
530 Not enough memory to allocate the packet.
533 Unknown device name or interface index specified in interface address.
539 No interface address passed.
542 Interface address contained an invalid interface index.
545 User has insufficient privileges to carry out this operation.
547 In addition, other errors may be generated by the low-level driver.
550 is a new feature in Linux 2.2.
551 Earlier Linux versions supported only
555 For portable programs it is suggested to use
559 although this covers only a subset of the
565 packet sockets make no attempt to create or parse the IEEE 802.2 LLC
566 header for a IEEE 802.3 frame.
569 is specified as protocol for sending the kernel creates the
570 802.3 frame and fills out the length field; the user has to supply the LLC
571 header to get a fully conforming packet.
572 Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol
573 fields; instead they are supplied to the user as protocol
575 with the LLC header prefixed.
576 It is thus not possible to bind to
580 instead and do the protocol multiplex yourself.
581 The default for sending is the standard Ethernet DIX
582 encapsulation with the protocol filled in.
584 Packet sockets are not subject to the input or output firewall chains.
586 In Linux 2.0, the only way to get a packet socket was with the call:
588 socket(AF_INET, SOCK_PACKET, protocol)
590 This is still supported, but deprecated and strongly discouraged.
591 The main difference between the two methods is that
594 .I struct sockaddr_pkt
595 to specify an interface, which doesn't provide physical-layer
600 struct sockaddr_pkt {
601 unsigned short spkt_family;
602 unsigned char spkt_device[14];
603 unsigned short spkt_protocol;
612 is the IEEE 802.3 protocol type as defined in
616 is the device name as a null-terminated string, for example, eth0.
618 This structure is obsolete and should not be used in new code.
620 The IEEE 802.2/803.3 LLC handling could be considered as a bug.
622 Socket filters are not documented.
627 extension is an ugly hack and should be replaced by a control message.
628 There is currently no way to get the original destination address of
632 .\" This man page was written by Andi Kleen with help from Matthew Wilcox.
633 .\" AF_PACKET in Linux 2.2 was implemented
634 .\" by Alexey Kuznetsov, based on code by Alan Cox and others.
638 .BR capabilities (7),
643 RFC\ 894 for the standard IP Ethernet encapsulation.
644 RFC\ 1700 for the IEEE 802.3 IP encapsulation.
647 .I <linux/if_ether.h>
648 include file for physical-layer protocols.
650 The Linux kernel source tree.
651 .IR /Documentation/networking/filter.txt
652 describes how to apply Berkeley Packet Filters to packet sockets.
653 .IR /tools/testing/selftests/net/psock_tpacket.c
654 contains example source code for all available versions of