man7/packet.7

   1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   2 .\" Permission is granted to distribute possibly modified copies
   3 .\" of this page provided the header is included verbatim,
   4 .\" and in case of nontrivial modification author and date
   5 .\" of the modification is added to the header.
   6 .\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $
   7 .TH PACKET  7 1999-04-29 "Linux Man Page" "Linux Programmer's Manual"
   8 .SH NAME
   9 packet, PF_PACKET \- packet interface on device level.
  10 .SH SYNOPSIS
  11 .nf
  12 .B #include <sys/socket.h>
  13 .br
  14 .B #include <netpacket/packet.h>
  15 .br
  16 .B #include <net/ethernet.h>     /* the L2 protocols */
  17 .sp
  18 .BI "packet_socket = socket(PF_PACKET, int " socket_type ", int "protocol );
  19 .fi
  20 .SH DESCRIPTION
  21 Packet sockets are used to receive or send raw packets at the device driver
  22 (OSI Layer 2) level.
  23 They allow the user to implement protocol modules in user space
  24 on top of the physical layer.
  25
  26 The
  27 .I socket_type
  28 is either
  29 .B SOCK_RAW
  30 for raw packets including the link level header or
  31 .B SOCK_DGRAM
  32 for cooked packets with the link level header removed.
  33 The link level
  34 header information is available in a common format in a
  35 .BR sockaddr_ll .
  36 .I protocol
  37 is the IEEE 802.3 protocol number in network order.
  38 See the
  39 .I <linux/if_ether.h>
  40 include file for a list of allowed protocols.
  41 When protocol
  42 is set to
  43 .B htons(ETH_P_ALL)
  44 then all protocols are received.
  45 All incoming packets of that protocol type will be passed to the packet
  46 socket before they are passed to the protocols implemented in the kernel.
  47
  48 Only processes with effective UID 0 or the
  49 .B CAP_NET_RAW
  50 capability may open packet sockets.
  51
  52 .B SOCK_RAW
  53 packets are passed to and from the device driver without any changes in
  54 the packet data.
  55 When receiving a packet, the address is still parsed and
  56 passed in a standard
  57 .B sockaddr_ll
  58 address structure.
  59 When transmitting a packet, the user supplied buffer
  60 should contain the physical layer header.
  61 That packet is then
  62 queued unmodified to the network driver of the interface defined by the
  63 destination address.
  64 Some device drivers always add other headers.
  65 .B SOCK_RAW
  66 is similar to but not compatible with the obsolete
  67 .B PF_INET/SOCK_PACKET
  68 of Linux 2.0.
  69
  70 .B SOCK_DGRAM
  71 operates on a slightly higher level.
  72 The physical header is removed before the packet is passed to the user.
  73 Packets sent through a
  74 .B SOCK_DGRAM
  75 packet socket get a suitable physical layer header based on the
  76 information in the
  77 .B sockaddr_ll
  78 destination address before they are queued.
  79
  80 By default all packets of the specified protocol type
  81 are passed to a packet socket.
  82 To only get packets from a specific interface use
  83 .BR bind (2)
  84 specifying an address in a
  85 .I struct sockaddr_ll
  86 to bind the packet socket to an interface.
  87 Only the
  88 .B sll_protocol
  89 and the
  90 .B sll_ifindex
  91 address fields are used for purposes of binding.
  92
  93 The
  94 .BR connect (2)
  95 operation is not supported on packet sockets.
  96
  97 When the
  98 .B MSG_TRUNC
  99 flag is passed to
 100 .BR recvmsg (2),
 101 .BR recv (2),
 102 .BR recvfrom (2)
 103 the real length of the packet on the wire is always returned,
 104 even when it is longer than the buffer.
 105 .SH "ADDRESS TYPES"
 106 The sockaddr_ll is a device independent physical layer address.
 107
 108 .in +0.25i
 109 .nf
 110 struct sockaddr_ll {
 111     unsigned short sll_family;   /* Always AF_PACKET */
 112     unsigned short sll_protocol; /* Physical layer protocol */
 113     int            sll_ifindex;  /* Interface number */
 114     unsigned short sll_hatype;   /* Header type */
 115     unsigned char  sll_pkttype;  /* Packet type */
 116     unsigned char  sll_halen;    /* Length of address */
 117     unsigned char  sll_addr[8];  /* Physical layer address */
 118 };
 119 .fi
 120 .in -0.25i
 121
 122 .B sll_protocol
 123 is the standard ethernet protocol type in network order as defined
 124 in the
 125 .I <linux/if_ether.h>
 126 include file.
 127 It defaults to the socket's protocol.
 128 .B sll_ifindex
 129 is the interface index of the interface
 130 (see
 131 .BR netdevice (7));
 132 0 matches any interface (only legal for binding).
 133 .B sll_hatype
 134 is a ARP type as defined in the
 135 .I <linux/if_arp.h>
 136 include file.
 137 .B sll_pkttype
 138 contains the packet type.
 139 Valid types are
 140 .B PACKET_HOST
 141 for a packet addressed to the local host,
 142 .B PACKET_BROADCAST
 143 for a physical layer broadcast packet,
 144 .B PACKET_MULTICAST
 145 for a packet sent to a physical layer multicast address,
 146 .B PACKET_OTHERHOST
 147 for a packet to some other host that has been caught by a device driver
 148 in promiscuous mode, and
 149 .B PACKET_OUTGOING
 150 for a packet originated from the local host that is looped back to a packet
 151 socket.
 152 These types make only sense for receiving.
 153 .B sll_addr
 154 and
 155 .B sll_halen
 156 contain the physical layer (e.g. IEEE 802.3) address and its length.
 157 The exact interpretation depends on the device.
 158
 159 When you send packets it is enough to specify
 160 .BR sll_family ,
 161 .BR sll_addr ,
 162 .BR sll_halen ,
 163 .BR sll_ifindex .
 164 The other fields should be 0.
 165 .B sll_hatype
 166 and
 167 .B sll_pkttype
 168 are set on received packets for your information.
 169 For bind only
 170 .B sll_protocol
 171 and
 172 .B sll_ifindex
 173 are used.
 174 .SH "SOCKET OPTIONS"
 175 Packet sockets can be used to configure physical layer multicasting
 176 and promiscuous mode.
 177 It works by calling
 178 .BR setsockopt (2)
 179 on a packet socket for SOL_PACKET and one of the options
 180 .B PACKET_ADD_MEMBERSHIP
 181 to add a binding or
 182 .B PACKET_DROP_MEMBERSHIP
 183 to drop it.
 184 They both expect a
 185 .B packet_mreq
 186 structure as argument:
 187
 188 .in +0.25i
 189 .nf
 190 struct packet_mreq {
 191     int            mr_ifindex;    /* interface index */
 192     unsigned short mr_type;       /* action */
 193     unsigned short mr_alen;       /* address length */
 194     unsigned char  mr_address[8]; /* physical layer address */
 195 };
 196 .fi
 197 .in -0.25i
 198
 199 .B mr_ifindex
 200 contains the interface index for the interface whose status
 201 should be changed.
 202 The
 203 .B mr_type
 204 parameter specifies which action to perform.
 205 .B PACKET_MR_PROMISC
 206 enables receiving all packets on a shared medium (often known as
 207 ``promiscuous mode''),
 208 .B PACKET_MR_MULTICAST
 209 binds the socket to the physical layer multicast group specified in
 210 .B mr_address
 211 and
 212 .BR mr_alen ,
 213 and
 214 .B PACKET_MR_ALLMULTI
 215 sets the socket up to receive all multicast packets arriving at
 216 the interface.
 217
 218 In addition the traditional ioctls
 219 .BR SIOCSIFFLAGS ,
 220 .BR SIOCADDMULTI ,
 221 .B SIOCDELMULTI
 222 can be used for the same purpose.
 223 .SH IOCTLS
 224 .B SIOCGSTAMP
 225 can be used to receive the time stamp of the last received packet.
 226 Argument is a
 227 .I struct timeval.
 228
 229 In addition all standard ioctls defined in
 230 .BR netdevice (7)
 231 and
 232 .BR socket (7)
 233 are valid on packet sockets.
 234 .SH "ERROR HANDLING"
 235 Packet sockets do no error handling other than errors occurred
 236 while passing the packet to the device driver.
 237 They don't have the concept of a pending error.
 238 .SH COMPATIBILITY
 239 In Linux 2.0, the only way to get a packet socket was by calling
 240 .BI "socket(PF_INET, SOCK_PACKET, " protocol )\fR.
 241 This is still supported but strongly deprecated.
 242 The main difference between the two methods is that
 243 .B SOCK_PACKET
 244 uses the old
 245 .I struct sockaddr_pkt
 246 to specify an interface, which doesn't provide physical layer
 247 independence.
 248
 249 .in +0.25i
 250 .nf
 251 struct sockaddr_pkt {
 252     unsigned short spkt_family;
 253     unsigned char  spkt_device[14];
 254     unsigned short spkt_protocol;
 255 };
 256 .fi
 257 .in -0.25i
 258
 259 .B spkt_family
 260 contains
 261 the device type,
 262 .B spkt_protocol
 263 is the IEEE 802.3 protocol type as defined in
 264 .I <sys/if_ether.h>
 265 and
 266 .B spkt_device
 267 is the device name as a null terminated string, e.g. eth0.
 268
 269 This structure is obsolete and should not be used in new code.
 270 .SH NOTES
 271 For portable programs it is suggested to use
 272 .B PF_PACKET
 273 via
 274 .BR pcap (3);
 275 although this only covers a subset of the
 276 .B PF_PACKET
 277 features.
 278
 279 The
 280 .B SOCK_DGRAM
 281 packet sockets make no attempt to create or parse the IEEE 802.2 LLC
 282 header for a IEEE 802.3 frame.
 283 When
 284 .B ETH_P_802_3
 285 is specified as protocol for sending the kernel creates the
 286 802.3 frame and fills out the length field; the user has to supply the LLC
 287 header to get a fully conforming packet.
 288 Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol
 289 fields; instead they are supplied to the user as protocol
 290 .B ETH_P_802_2
 291 with the LLC header prepended.
 292 It is thus not possible to bind to
 293 .BR ETH_P_802_3 ;
 294 bind to
 295 .B ETH_P_802_2
 296 instead and do the protocol multiplex yourself.
 297 The default for sending is the standard Ethernet DIX
 298 encapsulation with the protocol filled in.
 299
 300 Packet sockets are not subject to the input or output firewall chains.
 301 .SH ERRORS
 302 .TP
 303 .B ENETDOWN
 304 Interface is not up.
 305 .TP
 306 .B ENOTCONN
 307 No interface address passed.
 308 .TP
 309 .B ENODEV
 310 Unknown device name or interface index specified in interface address.
 311 .TP
 312 .B EMSGSIZE
 313 Packet is bigger than interface MTU.
 314 .TP
 315 .B ENOBUFS
 316 Not enough memory to allocate the packet.
 317 .TP
 318 .B EFAULT
 319 User passed invalid memory address.
 320 .TP
 321 .B EINVAL
 322 Invalid argument.
 323 .TP
 324 .B ENXIO
 325 Interface address contained illegal interface index.
 326 .TP
 327 .B EPERM
 328 User has insufficient privileges to carry out this operation.
 329 .TP
 330 .B EADDRNOTAVAIL
 331 Unknown multicast group address passed.
 332 .TP
 333 .B ENOENT
 334 No packet received.
 335
 336 In addition other errors may be generated by the low-level driver.
 337 .SH VERSIONS
 338 .B PF_PACKET
 339 is a new feature in Linux 2.2.
 340 Earlier Linux versions supported only
 341 .BR SOCK_PACKET .
 342 .SH BUGS
 343 glibc 2.1 does not have a define for
 344 .BR SOL_PACKET .
 345 The suggested workaround is to use:
 346 .in +0.5i
 347 .nf
 348
 349 #ifndef SOL_PACKET
 350 #define SOL_PACKET 263
 351 #endif
 352
 353 .fi
 354 .in -0.5i
 355 This is fixed in later glibc versions and also does not occur on
 356 libc5 systems.
 357
 358 The IEEE 802.2/803.3 LLC handling could be considered as a bug.
 359
 360 Socket filters are not documented.
 361
 362 The
 363 .I MSG_TRUNC
 364 .BR recvmsg ()
 365 extension is an ugly hack and should be replaced by a control message.
 366 There is currently no way to get the original destination address of
 367 packets via SOCK_DGRAM.
 368 .SH HISTORICAL NOTE
 369 The include file
 370 .I <netpacket/packet.h>
 371 is present since glibc2.1.
 372 Older systems need
 373 .sp
 374 .nf
 375 .B #include <asm/types.h>
 376 .br
 377 .B #include <linux/if_packet.h>
 378 .br
 379 .B #include <linux/if_ether.h>  /* The L2 protocols */
 380 .br
 381 .fi
 382 .\" .SH CREDITS
 383 .\" This man page was written by Andi Kleen with help from Matthew Wilcox.
 384 .\" PF_PACKET in Linux 2.2 was implemented
 385 .\" by Alexey Kuznetsov, based on code by Alan Cox and others.
 386 .SH "SEE ALSO"
 387 .BR socket (2),
 388 .BR pcap (3),
 389 .BR capabilities (7),
 390 .BR ip (7),
 391 .BR raw (7),
 392 .BR socket (7)
 393
 394 RFC\ 894 for the standard IP Ethernet encapsulation.
 395
 396 RFC\ 1700 for the IEEE 802.3 IP encapsulation.
 397
 398 The
 399 .I <linux/if_ether.h>
 400 include file for physical layer protocols.