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 2014-02-26 "Linux" "Linux Programmer's Manual"
14 packet \- packet interface on device level
17 .B #include <sys/socket.h>
19 .B #include <netpacket/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
41 is the IEEE 802.3 protocol number in network byte order.
44 include file for a list of allowed protocols.
48 then all protocols are received.
49 All incoming packets of that protocol type will be passed to the packet
50 socket before they are passed to the protocols implemented in the kernel.
52 Only processes with effective UID 0 or the
54 capability may open packet sockets.
57 packets are passed to and from the device driver without any changes in
59 When receiving a packet, the address is still parsed and
63 When transmitting a packet, the user supplied buffer
64 should contain the physical layer header.
66 queued unmodified to the network driver of the interface defined by the
68 Some device drivers always add other headers.
70 is similar to but not compatible with the obsolete
71 .B AF_INET/SOCK_PACKET
75 operates on a slightly higher level.
76 The physical header is removed before the packet is passed to the user.
77 Packets sent through a
79 packet socket get a suitable physical layer header based on the
82 destination address before they are queued.
84 By default all packets of the specified protocol type
85 are passed to a packet socket.
86 To get packets only from a specific interface use
88 specifying an address in a
90 to bind the packet socket to an interface.
95 address fields are used for purposes of binding.
99 operation is not supported on packet sockets.
107 the real length of the packet on the wire is always returned,
108 even when it is longer than the buffer.
112 is a device independent physical layer address.
117 unsigned short sll_family; /* Always AF_PACKET */
118 unsigned short sll_protocol; /* Physical layer protocol */
119 int sll_ifindex; /* Interface number */
120 unsigned short sll_hatype; /* ARP hardware type */
121 unsigned char sll_pkttype; /* Packet type */
122 unsigned char sll_halen; /* Length of address */
123 unsigned char sll_addr[8]; /* Physical layer address */
129 is the standard ethernet protocol type in network byte order as defined
131 .I <linux/if_ether.h>
133 It defaults to the socket's protocol.
135 is the interface index of the interface
138 0 matches any interface (only permitted for binding).
140 is an ARP type as defined in the
144 contains the packet type.
147 for a packet addressed to the local host,
149 for a physical layer broadcast packet,
151 for a packet sent to a physical layer multicast address,
153 for a packet to some other host that has been caught by a device driver
154 in promiscuous mode, and
156 for a packet originated from the local host that is looped back to a packet
158 These types make sense only for receiving.
162 contain the physical layer (e.g., IEEE 802.3) address and its length.
163 The exact interpretation depends on the device.
165 When you send packets it is enough to specify
170 The other fields should be 0.
174 are set on received packets for your information.
181 Packet socket options are configured by calling
186 .BR PACKET_ADD_MEMBERSHIP
189 .BR PACKET_DROP_MEMBERSHIP
191 Packet sockets can be used to configure physical layer multicasting
192 and promiscuous mode.
193 .B PACKET_ADD_MEMBERSHIP
195 .B PACKET_DROP_MEMBERSHIP
199 structure as argument:
204 int mr_ifindex; /* interface index */
205 unsigned short mr_type; /* action */
206 unsigned short mr_alen; /* address length */
207 unsigned char mr_address[8]; /* physical layer address */
213 contains the interface index for the interface whose status
217 parameter specifies which action to perform.
219 enables receiving all packets on a shared medium (often known as
221 .B PACKET_MR_MULTICAST
222 binds the socket to the physical layer multicast group specified in
227 .B PACKET_MR_ALLMULTI
228 sets the socket up to receive all multicast packets arriving at
231 In addition, the traditional ioctls
235 can be used for the same purpose.
237 .BR PACKET_AUXDATA " (since Linux 2.6.21)"
238 .\" commit 8dc4194474159660d7f37c495e3fc3f10d0db8cc
239 If this binary option is enabled, the packet socket passes a metadata
240 structure along with each packet in the
243 The structure can be read with
249 struct tpacket_auxdata {
251 __u32 tp_len; /* packet length */
252 __u32 tp_snaplen; /* captured length */
261 .BR PACKET_FANOUT " (since Linux 3.1)"
262 .\" commit dc99f600698dcac69b8f56dda9a8a00d645c5ffc
263 To scale processing across threads, packet sockets can form a fanout
265 In this mode, each matching packet is enqueued onto only one
267 A socket joins a fanout group by calling
273 Each network namespace can have up to 65536 independent groups.
274 A socket selects a group by encoding the ID in the first 16 bits of
275 the integer option value.
276 The first packet socket to join a group implicitly creates it.
277 To successfully join an existing group, subsequent packet sockets
278 must have the same protocol, device settings, fanout mode and
280 Packet sockets can leave a fanout group only by closing the socket.
281 The group is deleted when the last socket is closed.
283 Fanout supports multiple algorithms to spread traffic between sockets.
285 .BR PACKET_FANOUT_HASH ,
286 sends packets from the same flow to the same socket to maintain
288 For each packet, it chooses a socket by taking the packet flow hash
289 modulo the number of sockets in the group, where a flow hash is a hash
290 over network-layer address and optional transport-layer port fields.
291 The load-balance mode
293 implements a round-robin algorithm.
294 .BR PACKET_FANOUT_CPU
295 selects the socket based on the CPU that the packet arrived on.
296 .BR PACKET_FANOUT_ROLLOVER
297 processes all data on a single socket, moves to the next when one
299 .BR PACKET_FANOUT_RND
300 selects the socket using a pseudo-random number generator.
302 .\" commit 2d36097d26b5991d71a2cf4a20c1a158f0f1bfcd
303 (available since Linux 3.14)
304 selects the socket using the recorded queue_mapping of the received skb.
306 Fanout modes can take additional options.
307 IP fragmentation causes packets from the same flow to have different
310 .BR PACKET_FANOUT_FLAG_DEFRAG ,
311 if set, causes packet to be defragmented before fanout is applied, to
312 preserve order even in this case.
313 Fanout mode and options are communicated in the second 16 bits of the
314 integer option value.
316 .BR PACKET_FANOUT_FLAG_ROLLOVER
317 enables the roll over mechanism as a backup strategy: if the
318 original fanout algorithm selects a backlogged socket, the packet
319 rolls over to the next available one.
321 .BR PACKET_LOSS " (with " PACKET_TX_RING )
322 If set, do not silently drop a packet on transmission error, but
323 return it with status set to
324 .BR TP_STATUS_WRONG_FORMAT .
326 .BR PACKET_RESERVE " (with " PACKET_RX_RING )
327 By default, a packet receive ring writes packets immediately following the
328 metadata structure and alignment padding.
329 This integer option reserves additional headroom.
332 Create a memory-mapped ring buffer for asynchronous packet reception.
333 The packet socket reserves a contiguous region of application address
334 space, lays it out into an array of packet slots and copies packets
337 into subsequent slots.
338 Each packet is preceded by a metadata structure similar to
339 .IR tpacket_auxdata .
340 The protocol fields encode the offset to the data
341 from the start of the metadata header.
343 stores the offset to the network layer.
344 If the packet socket is of type
351 then that field stores the offset to the link-layer frame.
352 Packet socket and application communicate the head and tail of the ring
356 The packet socket owns all slots with status
357 .BR TP_STATUS_KERNEL .
358 After filling a slot, it changes the status of the slot to transfer
359 ownership to the application.
360 During normal operation, the new status is
362 to signal that a correctly received packet has been stored.
363 When the application has finished processing a packet, it transfers
364 ownership of the slot back to the socket by setting the status to
365 .BR TP_STATUS_KERNEL .
366 Packet sockets implement multiple variants of the packet ring.
367 The implementation details are described in
368 .IR Documentation/networking/packet_mmap.txt
369 in the Linux kernel source tree.
371 .BR PACKET_STATISTICS
372 Retrieve packet socket statistics in the form of a structure
376 struct tpacket_stats {
377 unsigned int tp_packets; /* Total packet count */
378 unsigned int tp_drops; /* Dropped packet count */
383 Receiving statistics resets the internal counters.
384 The statistics structure differs when using a ring of variant
387 .BR PACKET_TIMESTAMP " (with " PACKET_RX_RING "; since Linux 2.6.36)"
388 .\" commit 614f60fa9d73a9e8fdff3df83381907fea7c5649
389 The packet receive ring always stores a timestamp in the metadata header.
390 By default, this is a software generated timestamp generated when the
391 packet is copied into the ring.
392 This integer option selects the type of timestamp.
393 Besides the default, it support the two hardware formats described in
394 .IR Documentation/networking/timestamping.txt
395 in the Linux kernel source tree.
397 .BR PACKET_TX_RING " (since Linux 2.6.31)"
398 .\" commit 69e3c75f4d541a6eb151b3ef91f34033cb3ad6e1
399 Create a memory-mapped ring buffer for packet transmission.
400 This option is similar to
402 and takes the same arguments.
403 The application writes packets into slots with status
404 .BR TP_STATUS_AVAILABLE
405 and schedules them for transmission by changing the status to
406 .BR TP_STATUS_SEND_REQUEST .
407 When packets are ready to be transmitted, the application calls
409 or a variant thereof.
414 fields of this call are ignored.
415 If an address is passed using
419 then that overrides the socket default.
420 On successful transmission, the socket resets the slot to
421 .BR TP_STATUS_AVAILABLE .
422 It discards packets silently on error unless
426 .BR PACKET_VERSION " (with " PACKET_RX_RING "; since Linux 2.6.27)"
427 .\" commit bbd6ef87c544d88c30e4b762b1b61ef267a7d279
430 creates a packet receive ring of variant
432 To create another variant, configure the desired variant by setting this
433 integer option before creating the ring.
435 .BR PACKET_QDISC_BYPASS " (since Linux 3.14)"
436 .\" commit d346a3fae3ff1d99f5d0c819bf86edf9094a26a1
437 By default, packets sent through packet sockets pass through the kernel's
438 qdisc (traffic control) layer, which is fine for the vast majority of use
440 For traffic generator appliances using packet sockets
441 that intend to brute-force flood the network\(emfor example,
442 to test devices under load in a similar
443 fashion to pktgen\(emthis layer can be bypassed by setting
444 this integer option to 1.
445 A side effect is that packet buffering in the qdisc layer is avoided,
446 which will lead to increased drops when network
447 device transmit queues are busy;
448 therefore, use at your own risk.
451 can be used to receive the timestamp of the last received packet.
455 .\" FIXME Document SIOCGSTAMPNS
457 In addition, all standard ioctls defined in
461 are valid on packet sockets.
463 Packet sockets do no error handling other than errors occurred
464 while passing the packet to the device driver.
465 They don't have the concept of a pending error.
469 Unknown multicast group address passed.
472 User passed invalid memory address.
478 Packet is bigger than interface MTU.
484 Not enough memory to allocate the packet.
487 Unknown device name or interface index specified in interface address.
493 No interface address passed.
496 Interface address contained an invalid interface index.
499 User has insufficient privileges to carry out this operation.
501 In addition, other errors may be generated by the low-level driver.
504 is a new feature in Linux 2.2.
505 Earlier Linux versions supported only
509 .I <netpacket/packet.h>
510 is present since glibc 2.1.
515 #include <asm/types.h>
516 #include <linux/if_packet.h>
517 #include <linux/if_ether.h> /* The L2 protocols */
521 For portable programs it is suggested to use
525 although this covers only a subset of the
531 packet sockets make no attempt to create or parse the IEEE 802.2 LLC
532 header for a IEEE 802.3 frame.
535 is specified as protocol for sending the kernel creates the
536 802.3 frame and fills out the length field; the user has to supply the LLC
537 header to get a fully conforming packet.
538 Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol
539 fields; instead they are supplied to the user as protocol
541 with the LLC header prefixed.
542 It is thus not possible to bind to
546 instead and do the protocol multiplex yourself.
547 The default for sending is the standard Ethernet DIX
548 encapsulation with the protocol filled in.
550 Packet sockets are not subject to the input or output firewall chains.
552 In Linux 2.0, the only way to get a packet socket was by calling
553 .BI "socket(AF_INET, SOCK_PACKET, " protocol )\fR.
554 This is still supported but strongly deprecated.
555 The main difference between the two methods is that
558 .I struct sockaddr_pkt
559 to specify an interface, which doesn't provide physical layer
564 struct sockaddr_pkt {
565 unsigned short spkt_family;
566 unsigned char spkt_device[14];
567 unsigned short spkt_protocol;
576 is the IEEE 802.3 protocol type as defined in
580 is the device name as a null-terminated string, for example, eth0.
582 This structure is obsolete and should not be used in new code.
584 glibc 2.1 does not have a define for
586 The suggested workaround is to use:
591 #define SOL_PACKET 263
596 This is fixed in later glibc versions and also does not occur on
599 The IEEE 802.2/803.3 LLC handling could be considered as a bug.
601 Socket filters are not documented.
606 extension is an ugly hack and should be replaced by a control message.
607 There is currently no way to get the original destination address of
611 .\" This man page was written by Andi Kleen with help from Matthew Wilcox.
612 .\" AF_PACKET in Linux 2.2 was implemented
613 .\" by Alexey Kuznetsov, based on code by Alan Cox and others.
617 .BR capabilities (7),
622 RFC\ 894 for the standard IP Ethernet encapsulation.
623 RFC\ 1700 for the IEEE 802.3 IP encapsulation.
626 .I <linux/if_ether.h>
627 include file for physical layer protocols.
629 This page is part of release 3.65 of the Linux
632 A description of the project,
633 and information about reporting bugs,
635 \%http://www.kernel.org/doc/man\-pages/.