mirror of https://github.com/mkerrisk/man-pages
403 lines
10 KiB
Groff
403 lines
10 KiB
Groff
.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
|
|
.\" Permission is granted to distribute possibly modified copies
|
|
.\" of this page provided the header is included verbatim,
|
|
.\" and in case of nontrivial modification author and date
|
|
.\" of the modification is added to the header.
|
|
.\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $
|
|
.TH PACKET 7 2008-08-08 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
packet, AF_PACKET \- packet interface on device level.
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sys/socket.h>
|
|
.br
|
|
.B #include <netpacket/packet.h>
|
|
.br
|
|
.B #include <net/ethernet.h> /* the L2 protocols */
|
|
.sp
|
|
.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.
|
|
|
|
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
|
|
.IR sockaddr_ll .
|
|
.I protocol
|
|
is the IEEE 802.3 protocol number in network order.
|
|
See the
|
|
.I <linux/if_ether.h>
|
|
include file for a list of allowed protocols.
|
|
When protocol
|
|
is set to
|
|
.B 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.
|
|
|
|
Only processes with effective UID 0 or the
|
|
.B CAP_NET_RAW
|
|
capability may open packet sockets.
|
|
|
|
.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.
|
|
|
|
.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.
|
|
|
|
By default all packets of the specified protocol type
|
|
are passed to a packet socket.
|
|
To only get packets 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.
|
|
Only the
|
|
.I sll_protocol
|
|
and the
|
|
.I sll_ifindex
|
|
address fields are used for purposes of binding.
|
|
|
|
The
|
|
.BR connect (2)
|
|
operation is not supported on packet sockets.
|
|
|
|
When the
|
|
.B MSG_TRUNC
|
|
flag is passed to
|
|
.BR recvmsg (2),
|
|
.BR recv (2),
|
|
.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 sockaddr_ll is a device independent physical layer address.
|
|
|
|
.in +4n
|
|
.nf
|
|
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; /* Header type */
|
|
unsigned char sll_pkttype; /* Packet type */
|
|
unsigned char sll_halen; /* Length of address */
|
|
unsigned char sll_addr[8]; /* Physical layer address */
|
|
};
|
|
.fi
|
|
.in
|
|
|
|
.I sll_protocol
|
|
is the standard ethernet protocol type in network order as defined
|
|
in the
|
|
.I <linux/if_ether.h>
|
|
include file.
|
|
It defaults to the socket's protocol.
|
|
.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 a ARP type as defined in the
|
|
.I <linux/if_arp.h>
|
|
include file.
|
|
.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 originated from the local host that is looped back to a packet
|
|
socket.
|
|
These types make only sense for receiving.
|
|
.I sll_addr
|
|
and
|
|
.I sll_halen
|
|
contain the physical layer (e.g., IEEE 802.3) address and its length.
|
|
The exact interpretation depends on the device.
|
|
|
|
When you send packets it is enough to specify
|
|
.IR sll_family ,
|
|
.IR sll_addr ,
|
|
.IR sll_halen ,
|
|
.IR sll_ifindex .
|
|
The other fields should be 0.
|
|
.I sll_hatype
|
|
and
|
|
.I sll_pkttype
|
|
are set on received packets for your information.
|
|
For bind only
|
|
.I sll_protocol
|
|
and
|
|
.I sll_ifindex
|
|
are used.
|
|
.SS Socket Options
|
|
Packet sockets can be used to configure physical layer multicasting
|
|
and promiscuous mode.
|
|
It works by calling
|
|
.BR setsockopt (2)
|
|
on a packet socket for
|
|
.B SOL_PACKET
|
|
and one of the options
|
|
.B PACKET_ADD_MEMBERSHIP
|
|
to add a binding or
|
|
.B PACKET_DROP_MEMBERSHIP
|
|
to drop it.
|
|
They both expect a
|
|
.B packet_mreq
|
|
structure as argument:
|
|
|
|
.in +4n
|
|
.nf
|
|
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 */
|
|
};
|
|
.fi
|
|
.in
|
|
|
|
.B mr_ifindex
|
|
contains the interface index for the interface whose status
|
|
should be changed.
|
|
The
|
|
.B mr_type
|
|
parameter 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
|
|
.B mr_address
|
|
and
|
|
.BR mr_alen ,
|
|
and
|
|
.B PACKET_MR_ALLMULTI
|
|
sets the socket up to receive all multicast packets arriving at
|
|
the interface.
|
|
|
|
In addition the traditional ioctls
|
|
.BR SIOCSIFFLAGS ,
|
|
.BR SIOCADDMULTI ,
|
|
.B SIOCDELMULTI
|
|
can be used for the same purpose.
|
|
.SS Ioctls
|
|
.B SIOCGSTAMP
|
|
can be used to receive the timestamp of the last received packet.
|
|
Argument is a
|
|
.I struct timeval.
|
|
|
|
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.
|
|
|
|
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 .
|
|
.PP
|
|
The include file
|
|
.I <netpacket/packet.h>
|
|
is present since glibc 2.1.
|
|
Older systems need:
|
|
.sp
|
|
.in +4n
|
|
.nf
|
|
#include <asm/types.h>
|
|
#include <linux/if_packet.h>
|
|
#include <linux/if_ether.h> /* The L2 protocols */
|
|
.fi
|
|
.in
|
|
.SH NOTES
|
|
For portable programs it is suggested to use
|
|
.B AF_PACKET
|
|
via
|
|
.BR pcap (3);
|
|
although this only covers a subset of the
|
|
.B AF_PACKET
|
|
features.
|
|
|
|
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 prepended.
|
|
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.
|
|
|
|
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 by calling
|
|
.BI "socket(AF_INET, SOCK_PACKET, " protocol )\fR.
|
|
This is still supported but strongly deprecated.
|
|
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.
|
|
|
|
.in +4n
|
|
.nf
|
|
struct sockaddr_pkt {
|
|
unsigned short spkt_family;
|
|
unsigned char spkt_device[14];
|
|
unsigned short spkt_protocol;
|
|
};
|
|
.fi
|
|
.in
|
|
|
|
.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.
|
|
|
|
This structure is obsolete and should not be used in new code.
|
|
.SH BUGS
|
|
glibc 2.1 does not have a define for
|
|
.BR SOL_PACKET .
|
|
The suggested workaround is to use:
|
|
.in +4n
|
|
.nf
|
|
|
|
#ifndef SOL_PACKET
|
|
#define SOL_PACKET 263
|
|
#endif
|
|
|
|
.fi
|
|
.in
|
|
This is fixed in later glibc versions and also does not occur on
|
|
libc5 systems.
|
|
|
|
The IEEE 802.2/803.3 LLC handling could be considered as a bug.
|
|
|
|
Socket filters are not documented.
|
|
|
|
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 .
|
|
.\" .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)
|
|
|
|
RFC\ 894 for the standard IP Ethernet encapsulation.
|
|
|
|
RFC\ 1700 for the IEEE 802.3 IP encapsulation.
|
|
|
|
The
|
|
.I <linux/if_ether.h>
|
|
include file for physical layer protocols.
|