man7/packet.7

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