original/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 2012-03-25 "Linux" "Linux Programmer's Manual"
   8 .SH NAME
   9 packet, AF_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(AF_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 .IR 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 .I 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 AF_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 .I 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 .I sll_protocol
  89 and the
  90 .I 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 .SS Address Types
 106 The sockaddr_ll is a device independent physical layer address.
 107
 108 .in +4n
 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;   /* ARP hardware 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
 121
 122 .I 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 .I sll_ifindex
 129 is the interface index of the interface
 130 (see
 131 .BR netdevice (7));
 132 0 matches any interface (only permitted for binding).
 133 .I sll_hatype
 134 is an ARP type as defined in the
 135 .I <linux/if_arp.h>
 136 include file.
 137 .I 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 .I sll_addr
 154 and
 155 .I 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 .IR sll_family ,
 161 .IR sll_addr ,
 162 .IR sll_halen ,
 163 .IR sll_ifindex .
 164 The other fields should be 0.
 165 .I sll_hatype
 166 and
 167 .I sll_pkttype
 168 are set on received packets for your information.
 169 For bind only
 170 .I sll_protocol
 171 and
 172 .I sll_ifindex
 173 are used.
 174 .SS 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
 180 .B SOL_PACKET
 181 and one of the options
 182 .B PACKET_ADD_MEMBERSHIP
 183 to add a binding or
 184 .B PACKET_DROP_MEMBERSHIP
 185 to drop it.
 186 They both expect a
 187 .B packet_mreq
 188 structure as argument:
 189
 190 .in +4n
 191 .nf
 192 struct packet_mreq {
 193     int            mr_ifindex;    /* interface index */
 194     unsigned short mr_type;       /* action */
 195     unsigned short mr_alen;       /* address length */
 196     unsigned char  mr_address[8]; /* physical layer address */
 197 };
 198 .fi
 199 .in
 200
 201 .B mr_ifindex
 202 contains the interface index for the interface whose status
 203 should be changed.
 204 The
 205 .B mr_type
 206 parameter specifies which action to perform.
 207 .B PACKET_MR_PROMISC
 208 enables receiving all packets on a shared medium (often known as
 209 "promiscuous mode"),
 210 .B PACKET_MR_MULTICAST
 211 binds the socket to the physical layer multicast group specified in
 212 .B mr_address
 213 and
 214 .BR mr_alen ,
 215 and
 216 .B PACKET_MR_ALLMULTI
 217 sets the socket up to receive all multicast packets arriving at
 218 the interface.
 219
 220 In addition the traditional ioctls
 221 .BR SIOCSIFFLAGS ,
 222 .BR SIOCADDMULTI ,
 223 .B SIOCDELMULTI
 224 can be used for the same purpose.
 225 .SS Ioctls
 226 .B SIOCGSTAMP
 227 can be used to receive the timestamp of the last received packet.
 228 Argument is a
 229 .I struct timeval.
 230 .\" FIXME Document SIOCGSTAMPNS
 231
 232 In addition all standard ioctls defined in
 233 .BR netdevice (7)
 234 and
 235 .BR socket (7)
 236 are valid on packet sockets.
 237 .SS Error Handling
 238 Packet sockets do no error handling other than errors occurred
 239 while passing the packet to the device driver.
 240 They don't have the concept of a pending error.
 241 .SH ERRORS
 242 .TP
 243 .B EADDRNOTAVAIL
 244 Unknown multicast group address passed.
 245 .TP
 246 .B EFAULT
 247 User passed invalid memory address.
 248 .TP
 249 .B EINVAL
 250 Invalid argument.
 251 .TP
 252 .B EMSGSIZE
 253 Packet is bigger than interface MTU.
 254 .TP
 255 .B ENETDOWN
 256 Interface is not up.
 257 .TP
 258 .B ENOBUFS
 259 Not enough memory to allocate the packet.
 260 .TP
 261 .B ENODEV
 262 Unknown device name or interface index specified in interface address.
 263 .TP
 264 .B ENOENT
 265 No packet received.
 266 .TP
 267 .B ENOTCONN
 268 No interface address passed.
 269 .TP
 270 .B ENXIO
 271 Interface address contained an invalid interface index.
 272 .TP
 273 .B EPERM
 274 User has insufficient privileges to carry out this operation.
 275
 276 In addition other errors may be generated by the low-level driver.
 277 .SH VERSIONS
 278 .B AF_PACKET
 279 is a new feature in Linux 2.2.
 280 Earlier Linux versions supported only
 281 .BR SOCK_PACKET .
 282 .PP
 283 The include file
 284 .I <netpacket/packet.h>
 285 is present since glibc 2.1.
 286 Older systems need:
 287 .sp
 288 .in +4n
 289 .nf
 290 #include <asm/types.h>
 291 #include <linux/if_packet.h>
 292 #include <linux/if_ether.h>  /* The L2 protocols */
 293 .fi
 294 .in
 295 .SH NOTES
 296 For portable programs it is suggested to use
 297 .B AF_PACKET
 298 via
 299 .BR pcap (3);
 300 although this only covers a subset of the
 301 .B AF_PACKET
 302 features.
 303
 304 The
 305 .B SOCK_DGRAM
 306 packet sockets make no attempt to create or parse the IEEE 802.2 LLC
 307 header for a IEEE 802.3 frame.
 308 When
 309 .B ETH_P_802_3
 310 is specified as protocol for sending the kernel creates the
 311 802.3 frame and fills out the length field; the user has to supply the LLC
 312 header to get a fully conforming packet.
 313 Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol
 314 fields; instead they are supplied to the user as protocol
 315 .B ETH_P_802_2
 316 with the LLC header prepended.
 317 It is thus not possible to bind to
 318 .BR ETH_P_802_3 ;
 319 bind to
 320 .B ETH_P_802_2
 321 instead and do the protocol multiplex yourself.
 322 The default for sending is the standard Ethernet DIX
 323 encapsulation with the protocol filled in.
 324
 325 Packet sockets are not subject to the input or output firewall chains.
 326 .SS Compatibility
 327 In Linux 2.0, the only way to get a packet socket was by calling
 328 .BI "socket(AF_INET, SOCK_PACKET, " protocol )\fR.
 329 This is still supported but strongly deprecated.
 330 The main difference between the two methods is that
 331 .B SOCK_PACKET
 332 uses the old
 333 .I struct sockaddr_pkt
 334 to specify an interface, which doesn't provide physical layer
 335 independence.
 336
 337 .in +4n
 338 .nf
 339 struct sockaddr_pkt {
 340     unsigned short spkt_family;
 341     unsigned char  spkt_device[14];
 342     unsigned short spkt_protocol;
 343 };
 344 .fi
 345 .in
 346
 347 .I spkt_family
 348 contains
 349 the device type,
 350 .I spkt_protocol
 351 is the IEEE 802.3 protocol type as defined in
 352 .I <sys/if_ether.h>
 353 and
 354 .I spkt_device
 355 is the device name as a null-terminated string, for example, eth0.
 356
 357 This structure is obsolete and should not be used in new code.
 358 .SH BUGS
 359 glibc 2.1 does not have a define for
 360 .BR SOL_PACKET .
 361 The suggested workaround is to use:
 362 .in +4n
 363 .nf
 364
 365 #ifndef SOL_PACKET
 366 #define SOL_PACKET 263
 367 #endif
 368
 369 .fi
 370 .in
 371 This is fixed in later glibc versions and also does not occur on
 372 libc5 systems.
 373
 374 The IEEE 802.2/803.3 LLC handling could be considered as a bug.
 375
 376 Socket filters are not documented.
 377
 378 The
 379 .B MSG_TRUNC
 380 .BR recvmsg (2)
 381 extension is an ugly hack and should be replaced by a control message.
 382 There is currently no way to get the original destination address of
 383 packets via
 384 .BR SOCK_DGRAM .
 385 .\" .SH CREDITS
 386 .\" This man page was written by Andi Kleen with help from Matthew Wilcox.
 387 .\" AF_PACKET in Linux 2.2 was implemented
 388 .\" by Alexey Kuznetsov, based on code by Alan Cox and others.
 389 .SH "SEE ALSO"
 390 .BR socket (2),
 391 .BR pcap (3),
 392 .BR capabilities (7),
 393 .BR ip (7),
 394 .BR raw (7),
 395 .BR socket (7)
 396
 397 RFC\ 894 for the standard IP Ethernet encapsulation.
 398
 399 RFC\ 1700 for the IEEE 802.3 IP encapsulation.
 400
 401 The
 402 .I <linux/if_ether.h>
 403 include file for physical layer protocols.