diff options
Diffstat (limited to 'man7/packet.7')
| -rw-r--r-- | man7/packet.7 | 694 |
1 files changed, 0 insertions, 694 deletions
diff --git a/man7/packet.7 b/man7/packet.7 deleted file mode 100644 index 5d9d0cf..0000000 --- a/man7/packet.7 +++ /dev/null @@ -1,694 +0,0 @@ -.\" SPDX-License-Identifier: Linux-man-pages-1-para -.\" -.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. -.\" -.\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $ -.\" -.TH packet 7 2023-10-31 "Linux man-pages 6.7" -.SH NAME -packet \- packet interface on device level -.SH SYNOPSIS -.nf -.B #include <sys/socket.h> -.B #include <linux/if_packet.h> -.B #include <net/ethernet.h> /* the L2 protocols */ -.P -.BI "packet_socket = socket(AF_PACKET, int " socket_type ", int "protocol ); -.fi -.SH DESCRIPTION -Packet sockets are used to receive or send raw packets at the device driver -(OSI Layer 2) level. -They allow the user to implement protocol modules in user space -on top of the physical layer. -.P -The -.I socket_type -is either -.B SOCK_RAW -for raw packets including the link-level header or -.B SOCK_DGRAM -for cooked packets with the link-level header removed. -The link-level header information is available in a common format in a -.I sockaddr_ll -structure. -.I protocol -is the IEEE 802.3 protocol number in network byte order. -See the -.I <linux/if_ether.h> -include file for a list of allowed protocols. -When protocol -is set to -.BR htons(ETH_P_ALL) , -then all protocols are received. -All incoming packets of that protocol type will be passed to the packet -socket before they are passed to the protocols implemented in the kernel. -If -.I protocol -is set to zero, -no packets are received. -.BR bind (2) -can optionally be called with a nonzero -.I sll_protocol -to start receiving packets for the protocols specified. -.P -In order to create a packet socket, a process must have the -.B CAP_NET_RAW -capability in the user namespace that governs its network namespace. -.P -.B SOCK_RAW -packets are passed to and from the device driver without any changes in -the packet data. -When receiving a packet, the address is still parsed and -passed in a standard -.I sockaddr_ll -address structure. -When transmitting a packet, the user-supplied buffer -should contain the physical-layer header. -That packet is then -queued unmodified to the network driver of the interface defined by the -destination address. -Some device drivers always add other headers. -.B SOCK_RAW -is similar to but not compatible with the obsolete -.B AF_INET/SOCK_PACKET -of Linux 2.0. -.P -.B SOCK_DGRAM -operates on a slightly higher level. -The physical header is removed before the packet is passed to the user. -Packets sent through a -.B SOCK_DGRAM -packet socket get a suitable physical-layer header based on the -information in the -.I sockaddr_ll -destination address before they are queued. -.P -By default, all packets of the specified protocol type -are passed to a packet socket. -To get packets only from a specific interface use -.BR bind (2) -specifying an address in a -.I struct sockaddr_ll -to bind the packet socket to an interface. -Fields used for binding are -.I sll_family -(should be -.BR AF_PACKET ), -.IR sll_protocol , -and -.IR sll_ifindex . -.P -The -.BR connect (2) -operation is not supported on packet sockets. -.P -When the -.B MSG_TRUNC -flag is passed to -.BR recvmsg (2), -.BR recv (2), -or -.BR recvfrom (2), -the real length of the packet on the wire is always returned, -even when it is longer than the buffer. -.SS Address types -The -.I sockaddr_ll -structure is a device-independent physical-layer address. -.P -.in +4n -.EX -struct sockaddr_ll { - unsigned short sll_family; /* Always AF_PACKET */ - unsigned short sll_protocol; /* Physical\-layer protocol */ - int sll_ifindex; /* Interface number */ - unsigned short sll_hatype; /* ARP hardware type */ - unsigned char sll_pkttype; /* Packet type */ - unsigned char sll_halen; /* Length of address */ - unsigned char sll_addr[8]; /* Physical\-layer address */ -}; -.EE -.in -.P -The fields of this structure are as follows: -.TP -.I sll_protocol -is the standard ethernet protocol type in network byte order as defined -in the -.I <linux/if_ether.h> -include file. -It defaults to the socket's protocol. -.TP -.I sll_ifindex -is the interface index of the interface -(see -.BR netdevice (7)); -0 matches any interface (only permitted for binding). -.I sll_hatype -is an ARP type as defined in the -.I <linux/if_arp.h> -include file. -.TP -.I sll_pkttype -contains the packet type. -Valid types are -.B PACKET_HOST -for a packet addressed to the local host, -.B PACKET_BROADCAST -for a physical-layer broadcast packet, -.B PACKET_MULTICAST -for a packet sent to a physical-layer multicast address, -.B PACKET_OTHERHOST -for a packet to some other host that has been caught by a device driver -in promiscuous mode, and -.B PACKET_OUTGOING -for a packet originating from the local host that is looped back to a packet -socket. -These types make sense only for receiving. -.TP -.I sll_addr -.TQ -.I sll_halen -contain the physical-layer (e.g., IEEE 802.3) address and its length. -The exact interpretation depends on the device. -.P -When you send packets, it is enough to specify -.IR sll_family , -.IR sll_addr , -.IR sll_halen , -.IR sll_ifindex , -and -.IR sll_protocol . -The other fields should be 0. -.I sll_hatype -and -.I sll_pkttype -are set on received packets for your information. -.SS Socket options -Packet socket options are configured by calling -.BR setsockopt (2) -with level -.BR SOL_PACKET . -.TP -.B PACKET_ADD_MEMBERSHIP -.PD 0 -.TP -.B PACKET_DROP_MEMBERSHIP -.PD -Packet sockets can be used to configure physical-layer multicasting -and promiscuous mode. -.B PACKET_ADD_MEMBERSHIP -adds a binding and -.B PACKET_DROP_MEMBERSHIP -drops it. -They both expect a -.I packet_mreq -structure as argument: -.IP -.in +4n -.EX -struct packet_mreq { - int mr_ifindex; /* interface index */ - unsigned short mr_type; /* action */ - unsigned short mr_alen; /* address length */ - unsigned char mr_address[8]; /* physical\-layer address */ -}; -.EE -.in -.IP -.I mr_ifindex -contains the interface index for the interface whose status -should be changed. -The -.I mr_type -field specifies which action to perform. -.B PACKET_MR_PROMISC -enables receiving all packets on a shared medium (often known as -"promiscuous mode"), -.B PACKET_MR_MULTICAST -binds the socket to the physical-layer multicast group specified in -.I mr_address -and -.IR mr_alen , -and -.B PACKET_MR_ALLMULTI -sets the socket up to receive all multicast packets arriving at -the interface. -.IP -In addition, the traditional ioctls -.BR SIOCSIFFLAGS , -.BR SIOCADDMULTI , -.B SIOCDELMULTI -can be used for the same purpose. -.TP -.BR PACKET_AUXDATA " (since Linux 2.6.21)" -.\" commit 8dc4194474159660d7f37c495e3fc3f10d0db8cc -If this binary option is enabled, the packet socket passes a metadata -structure along with each packet in the -.BR recvmsg (2) -control field. -The structure can be read with -.BR cmsg (3). -It is defined as -.IP -.in +4n -.EX -struct tpacket_auxdata { - __u32 tp_status; - __u32 tp_len; /* packet length */ - __u32 tp_snaplen; /* captured length */ - __u16 tp_mac; - __u16 tp_net; - __u16 tp_vlan_tci; - __u16 tp_vlan_tpid; /* Since Linux 3.14; earlier, these - were unused padding bytes */ -.\" commit a0cdfcf39362410d5ea983f4daf67b38de129408 added tp_vlan_tpid -}; -.EE -.in -.TP -.BR PACKET_FANOUT " (since Linux 3.1)" -.\" commit dc99f600698dcac69b8f56dda9a8a00d645c5ffc -To scale processing across threads, packet sockets can form a fanout -group. -In this mode, each matching packet is enqueued onto only one -socket in the group. -A socket joins a fanout group by calling -.BR setsockopt (2) -with level -.B SOL_PACKET -and option -.BR PACKET_FANOUT . -Each network namespace can have up to 65536 independent groups. -A socket selects a group by encoding the ID in the first 16 bits of -the integer option value. -The first packet socket to join a group implicitly creates it. -To successfully join an existing group, subsequent packet sockets -must have the same protocol, device settings, fanout mode, and -flags (see below). -Packet sockets can leave a fanout group only by closing the socket. -The group is deleted when the last socket is closed. -.IP -Fanout supports multiple algorithms to spread traffic between sockets, -as follows: -.RS -.IP \[bu] 3 -The default mode, -.BR PACKET_FANOUT_HASH , -sends packets from the same flow to the same socket to maintain -per-flow ordering. -For each packet, it chooses a socket by taking the packet flow hash -modulo the number of sockets in the group, where a flow hash is a hash -over network-layer address and optional transport-layer port fields. -.IP \[bu] -The load-balance mode -.B PACKET_FANOUT_LB -implements a round-robin algorithm. -.IP \[bu] -.B PACKET_FANOUT_CPU -selects the socket based on the CPU that the packet arrived on. -.IP \[bu] -.B PACKET_FANOUT_ROLLOVER -processes all data on a single socket, moving to the next when one -becomes backlogged. -.IP \[bu] -.B PACKET_FANOUT_RND -selects the socket using a pseudo-random number generator. -.IP \[bu] -.B PACKET_FANOUT_QM -.\" commit 2d36097d26b5991d71a2cf4a20c1a158f0f1bfcd -(available since Linux 3.14) -selects the socket using the recorded queue_mapping of the received skb. -.RE -.IP -Fanout modes can take additional options. -IP fragmentation causes packets from the same flow to have different -flow hashes. -The flag -.BR PACKET_FANOUT_FLAG_DEFRAG , -if set, causes packets to be defragmented before fanout is applied, to -preserve order even in this case. -Fanout mode and options are communicated in the second 16 bits of the -integer option value. -The flag -.B PACKET_FANOUT_FLAG_ROLLOVER -enables the roll over mechanism as a backup strategy: if the -original fanout algorithm selects a backlogged socket, the packet -rolls over to the next available one. -.TP -.BR PACKET_LOSS " (with " PACKET_TX_RING ) -When a malformed packet is encountered on a transmit ring, -the default is to reset its -.I tp_status -to -.B TP_STATUS_WRONG_FORMAT -and abort the transmission immediately. -The malformed packet blocks itself and subsequently enqueued packets from -being sent. -The format error must be fixed, the associated -.I tp_status -reset to -.BR TP_STATUS_SEND_REQUEST , -and the transmission process restarted via -.BR send (2). -However, if -.B PACKET_LOSS -is set, any malformed packet will be skipped, its -.I tp_status -reset to -.BR TP_STATUS_AVAILABLE , -and the transmission process continued. -.TP -.BR PACKET_RESERVE " (with " PACKET_RX_RING ) -By default, a packet receive ring writes packets immediately following the -metadata structure and alignment padding. -This integer option reserves additional headroom. -.TP -.B PACKET_RX_RING -Create a memory-mapped ring buffer for asynchronous packet reception. -The packet socket reserves a contiguous region of application address -space, lays it out into an array of packet slots and copies packets -(up to -.IR tp_snaplen ) -into subsequent slots. -Each packet is preceded by a metadata structure similar to -.IR tpacket_auxdata . -The protocol fields encode the offset to the data -from the start of the metadata header. -.I tp_net -stores the offset to the network layer. -If the packet socket is of type -.BR SOCK_DGRAM , -then -.I tp_mac -is the same. -If it is of type -.BR SOCK_RAW , -then that field stores the offset to the link-layer frame. -Packet socket and application communicate the head and tail of the ring -through the -.I tp_status -field. -The packet socket owns all slots with -.I tp_status -equal to -.BR TP_STATUS_KERNEL . -After filling a slot, it changes the status of the slot to transfer -ownership to the application. -During normal operation, the new -.I tp_status -value has at least the -.B TP_STATUS_USER -bit set to signal that a received packet has been stored. -When the application has finished processing a packet, it transfers -ownership of the slot back to the socket by setting -.I tp_status -equal to -.BR TP_STATUS_KERNEL . -.IP -Packet sockets implement multiple variants of the packet ring. -The implementation details are described in -.I Documentation/networking/packet_mmap.rst -in the Linux kernel source tree. -.TP -.B PACKET_STATISTICS -Retrieve packet socket statistics in the form of a structure -.IP -.in +4n -.EX -struct tpacket_stats { - unsigned int tp_packets; /* Total packet count */ - unsigned int tp_drops; /* Dropped packet count */ -}; -.EE -.in -.IP -Receiving statistics resets the internal counters. -The statistics structure differs when using a ring of variant -.BR TPACKET_V3 . -.TP -.BR PACKET_TIMESTAMP " (with " PACKET_RX_RING "; since Linux 2.6.36)" -.\" commit 614f60fa9d73a9e8fdff3df83381907fea7c5649 -The packet receive ring always stores a timestamp in the metadata header. -By default, this is a software generated timestamp generated when the -packet is copied into the ring. -This integer option selects the type of timestamp. -Besides the default, it support the two hardware formats described in -.I Documentation/networking/timestamping.rst -in the Linux kernel source tree. -.TP -.BR PACKET_TX_RING " (since Linux 2.6.31)" -.\" commit 69e3c75f4d541a6eb151b3ef91f34033cb3ad6e1 -Create a memory-mapped ring buffer for packet transmission. -This option is similar to -.B PACKET_RX_RING -and takes the same arguments. -The application writes packets into slots with -.I tp_status -equal to -.B TP_STATUS_AVAILABLE -and schedules them for transmission by changing -.I tp_status -to -.BR TP_STATUS_SEND_REQUEST . -When packets are ready to be transmitted, the application calls -.BR send (2) -or a variant thereof. -The -.I buf -and -.I len -fields of this call are ignored. -If an address is passed using -.BR sendto (2) -or -.BR sendmsg (2), -then that overrides the socket default. -On successful transmission, the socket resets -.I tp_status -to -.BR TP_STATUS_AVAILABLE . -It immediately aborts the transmission on error unless -.B PACKET_LOSS -is set. -.TP -.BR PACKET_VERSION " (with " PACKET_RX_RING "; since Linux 2.6.27)" -.\" commit bbd6ef87c544d88c30e4b762b1b61ef267a7d279 -By default, -.B PACKET_RX_RING -creates a packet receive ring of variant -.BR TPACKET_V1 . -To create another variant, configure the desired variant by setting this -integer option before creating the ring. -.TP -.BR PACKET_QDISC_BYPASS " (since Linux 3.14)" -.\" commit d346a3fae3ff1d99f5d0c819bf86edf9094a26a1 -By default, packets sent through packet sockets pass through the kernel's -qdisc (traffic control) layer, which is fine for the vast majority of use -cases. -For traffic generator appliances using packet sockets -that intend to brute-force flood the network\[em]for example, -to test devices under load in a similar -fashion to pktgen\[em]this layer can be bypassed by setting -this integer option to 1. -A side effect is that packet buffering in the qdisc layer is avoided, -which will lead to increased drops when network -device transmit queues are busy; -therefore, use at your own risk. -.SS Ioctls -.B SIOCGSTAMP -can be used to receive the timestamp of the last received packet. -Argument is a -.I struct timeval -variable. -.\" FIXME Document SIOCGSTAMPNS -.P -In addition, all standard ioctls defined in -.BR netdevice (7) -and -.BR socket (7) -are valid on packet sockets. -.SS Error handling -Packet sockets do no error handling other than errors occurred -while passing the packet to the device driver. -They don't have the concept of a pending error. -.SH ERRORS -.TP -.B EADDRNOTAVAIL -Unknown multicast group address passed. -.TP -.B EFAULT -User passed invalid memory address. -.TP -.B EINVAL -Invalid argument. -.TP -.B EMSGSIZE -Packet is bigger than interface MTU. -.TP -.B ENETDOWN -Interface is not up. -.TP -.B ENOBUFS -Not enough memory to allocate the packet. -.TP -.B ENODEV -Unknown device name or interface index specified in interface address. -.TP -.B ENOENT -No packet received. -.TP -.B ENOTCONN -No interface address passed. -.TP -.B ENXIO -Interface address contained an invalid interface index. -.TP -.B EPERM -User has insufficient privileges to carry out this operation. -.P -In addition, other errors may be generated by the low-level driver. -.SH VERSIONS -.B AF_PACKET -is a new feature in Linux 2.2. -Earlier Linux versions supported only -.BR SOCK_PACKET . -.SH NOTES -For portable programs it is suggested to use -.B AF_PACKET -via -.BR pcap (3); -although this covers only a subset of the -.B AF_PACKET -features. -.P -The -.B SOCK_DGRAM -packet sockets make no attempt to create or parse the IEEE 802.2 LLC -header for a IEEE 802.3 frame. -When -.B ETH_P_802_3 -is specified as protocol for sending the kernel creates the -802.3 frame and fills out the length field; the user has to supply the LLC -header to get a fully conforming packet. -Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol -fields; instead they are supplied to the user as protocol -.B ETH_P_802_2 -with the LLC header prefixed. -It is thus not possible to bind to -.BR ETH_P_802_3 ; -bind to -.B ETH_P_802_2 -instead and do the protocol multiplex yourself. -The default for sending is the standard Ethernet DIX -encapsulation with the protocol filled in. -.P -Packet sockets are not subject to the input or output firewall chains. -.SS Compatibility -In Linux 2.0, the only way to get a packet socket was with the call: -.P -.in +4n -.EX -socket(AF_INET, SOCK_PACKET, protocol) -.EE -.in -.P -This is still supported, but deprecated and strongly discouraged. -The main difference between the two methods is that -.B SOCK_PACKET -uses the old -.I struct sockaddr_pkt -to specify an interface, which doesn't provide physical-layer -independence. -.P -.in +4n -.EX -struct sockaddr_pkt { - unsigned short spkt_family; - unsigned char spkt_device[14]; - unsigned short spkt_protocol; -}; -.EE -.in -.P -.I spkt_family -contains -the device type, -.I spkt_protocol -is the IEEE 802.3 protocol type as defined in -.I <sys/if_ether.h> -and -.I spkt_device -is the device name as a null-terminated string, for example, eth0. -.P -This structure is obsolete and should not be used in new code. -.SH BUGS -.SS LLC header handling -The IEEE 802.2/803.3 LLC handling could be considered as a bug. -.SS MSG_TRUNC issues -The -.B MSG_TRUNC -.BR recvmsg (2) -extension is an ugly hack and should be replaced by a control message. -There is currently no way to get the original destination address of -packets via -.BR SOCK_DGRAM . -.SS spkt_device device name truncation -The -.I spkt_device -field of -.I sockaddr_pkt -has a size of 14 bytes, -which is less than the constant -.B IFNAMSIZ -defined in -.I <net/if.h> -which is 16 bytes and describes the system limit for a network interface name. -This means the names of network devices longer than 14 bytes -will be truncated to fit into -.IR spkt_device . -All these lengths include the terminating null byte (\[aq]\e0\[aq])). -.P -Issues from this with old code typically show up with -very long interface names used by the -.B Predictable Network Interface Names -feature enabled by default in many modern Linux distributions. -.P -The preferred solution is to rewrite code to avoid -.BR SOCK_PACKET . -Possible user solutions are to disable -.B Predictable Network Interface Names -or to rename the interface to a name of at most 13 bytes, -for example using the -.BR ip (8) -tool. -.SS Documentation issues -Socket filters are not documented. -.\" .SH CREDITS -.\" This man page was written by Andi Kleen with help from Matthew Wilcox. -.\" AF_PACKET in Linux 2.2 was implemented -.\" by Alexey Kuznetsov, based on code by Alan Cox and others. -.SH SEE ALSO -.BR socket (2), -.BR pcap (3), -.BR capabilities (7), -.BR ip (7), -.BR raw (7), -.BR socket (7), -.BR ip (8), -.P -RFC\ 894 for the standard IP Ethernet encapsulation. -RFC\ 1700 for the IEEE 802.3 IP encapsulation. -.P -The -.I <linux/if_ether.h> -include file for physical-layer protocols. -.P -The Linux kernel source tree. -.I Documentation/networking/filter.rst -describes how to apply Berkeley Packet Filters to packet sockets. -.I tools/testing/selftests/net/psock_tpacket.c -contains example source code for all available versions of -.B PACKET_RX_RING -and -.BR PACKET_TX_RING . |