summaryrefslogtreecommitdiffstats
path: root/man7/packet.7
diff options
context:
space:
mode:
Diffstat (limited to 'man7/packet.7')
-rw-r--r--man7/packet.7694
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 .