github.com/gopacket/gopacket@v1.1.0/pcap/doc.go (about)

     1  // Copyright 2012 Google, Inc. All rights reserved.
     2  //
     3  // Use of this source code is governed by a BSD-style license
     4  // that can be found in the LICENSE file in the root of the source
     5  // tree.
     6  
     7  /*
     8  Package pcap allows users of gopacket to read packets off the wire or from
     9  pcap files.
    10  
    11  This package is meant to be used with its parent,
    12  http://github.com/gopacket/gopacket, although it can also be used independently
    13  if you just want to get packet data from the wire.
    14  
    15  Depending on libpcap version, os support, or file timestamp resolution,
    16  nanosecond resolution is used for the internal timestamps. Returned timestamps
    17  are always scaled to nanosecond resolution due to the usage of time.Time.
    18  libpcap must be at least version 1.5 to support nanosecond timestamps. OpenLive
    19  supports only microsecond resolution.
    20  
    21  # Reading PCAP Files
    22  
    23  The following code can be used to read in data from a pcap file.
    24  
    25  	if handle, err := pcap.OpenOffline("/path/to/my/file"); err != nil {
    26  	  panic(err)
    27  	} else {
    28  	  packetSource := gopacket.NewPacketSource(handle, handle.LinkType())
    29  	  for packet := range packetSource.Packets() {
    30  	    handlePacket(packet)  // Do something with a packet here.
    31  	  }
    32  	}
    33  
    34  # Reading Live Packets
    35  
    36  The following code can be used to read in data from a live device, in this case
    37  "eth0". Be aware, that OpenLive only supports microsecond resolution.
    38  
    39  	if handle, err := pcap.OpenLive("eth0", 1600, true, pcap.BlockForever); err != nil {
    40  	  panic(err)
    41  	} else if err := handle.SetBPFFilter("tcp and port 80"); err != nil {  // optional
    42  	  panic(err)
    43  	} else {
    44  	  packetSource := gopacket.NewPacketSource(handle, handle.LinkType())
    45  	  for packet := range packetSource.Packets() {
    46  	    handlePacket(packet)  // Do something with a packet here.
    47  	  }
    48  	}
    49  
    50  # Inactive Handles
    51  
    52  Newer PCAP functionality requires the concept of an 'inactive' PCAP handle.
    53  Instead of constantly adding new arguments to pcap_open_live, users now call
    54  pcap_create to create a handle, set it up with a bunch of optional function
    55  calls, then call pcap_activate to activate it.  This library mirrors that
    56  mechanism, for those that want to expose/use these new features:
    57  
    58  	inactive, err := pcap.NewInactiveHandle(deviceName)
    59  	if err != nil {
    60  	  log.Fatal(err)
    61  	}
    62  	defer inactive.CleanUp()
    63  
    64  	// Call various functions on inactive to set it up the way you'd like:
    65  	if err = inactive.SetTimeout(time.Minute); err != nil {
    66  	  log.Fatal(err)
    67  	} else if err = inactive.SetTimestampSource("foo"); err != nil {
    68  	  log.Fatal(err)
    69  	}
    70  
    71  	// Finally, create the actual handle by calling Activate:
    72  	handle, err := inactive.Activate()  // after this, inactive is no longer valid
    73  	if err != nil {
    74  	  log.Fatal(err)
    75  	}
    76  	defer handle.Close()
    77  
    78  	// Now use your handle as you see fit.
    79  
    80  # PCAP Timeouts
    81  
    82  pcap.OpenLive and pcap.SetTimeout both take timeouts.
    83  If you don't care about timeouts, just pass in BlockForever,
    84  which should do what you expect with minimal fuss.
    85  
    86  A timeout of 0 is not recommended.  Some platforms, like Macs
    87  (http://www.manpages.info/macosx/pcap.3.html) say:
    88  
    89  	The read timeout is used to arrange that the read not necessarily return
    90  	immediately when a packet is seen, but that it wait for some amount of time
    91  	to allow more packets to arrive and to read multiple packets from the OS
    92  	kernel in one operation.
    93  
    94  This means that if you only capture one packet, the kernel might decide to wait
    95  'timeout' for more packets to batch with it before returning.  A timeout of
    96  0, then, means 'wait forever for more packets', which is... not good.
    97  
    98  To get around this, we've introduced the following behavior:  if a negative
    99  timeout is passed in, we set the positive timeout in the handle, then loop
   100  internally in ReadPacketData/ZeroCopyReadPacketData when we see timeout
   101  errors.
   102  
   103  # PCAP File Writing
   104  
   105  This package does not implement PCAP file writing.  However, gopacket/pcapgo
   106  does!  Look there if you'd like to write PCAP files.
   107  
   108  # Note For Windows Users
   109  
   110  gopacket can use winpcap or npcap. If both are installed at the same time,
   111  npcap is preferred. Make sure the right windows service is loaded (npcap for npcap
   112  and npf for winpcap).
   113  */
   114  package pcap