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