Home | History | Annotate | only in /external/libpcap/doc
Up to higher level directory
NameDateSize
DLT_ALLOCATE_HOWTO.md22-Oct-20201.3K
README.aix22-Oct-20203.1K
README.dag22-Oct-20205.1K
README.hpux22-Oct-20208K
README.linux.md22-Oct-20204.9K
README.macos22-Oct-20203.4K
README.septel22-Oct-20202K
README.sita22-Oct-20202.4K
README.tru6422-Oct-20201.6K
README.Win3222-Oct-20202.1K

README.aix

      1 Using BPF:
      2 
      3 (1) AIX 4.x's version of BPF is undocumented and somewhat unstandard; the
      4     current BPF support code includes changes that should work around
      5     that; it appears to compile and work on at least one AIX 4.3.3
      6     machine.
      7 
      8     Note that the BPF driver and the "/dev/bpf" devices might not exist
      9     on your machine; AIX's tcpdump loads the driver and creates the
     10     devices if they don't already exist.  Our libpcap should do the
     11     same, and the configure script should detect that it's on an AIX
     12     system and choose BPF even if the devices aren't there.
     13 
     14     Also note that tcpdump _binary_ compiled on AIX 4 may have a problem
     15     doing the initial loading of the BPF driver if copied to AIX 5 and
     16     run there (GH #52). tcpdump binary natively compiled on AIX 5 should
     17     not have this issue.
     18 
     19 (2) If libpcap doesn't compile on your machine when configured to use
     20     BPF, or if the workarounds fail to make it work correctly, you
     21     should send to tcpdump-workers (a] lists.tcpdump.org a detailed bug
     22     report (if the compile fails, send us the compile error messages;
     23     if it compiles but fails to work correctly, send us as detailed as
     24     possible a description of the symptoms, including indications of the
     25     network link-layer type being wrong or time stamps being wrong).
     26 
     27     If you fix the problems yourself, please submit a patch by forking
     28     the branch at
     29 
     30 	https://github.com/the-tcpdump-group/libpcap/issues
     31 
     32     and issuing a pull request, so we can incorporate the fixes into the
     33     next release.
     34 
     35     If you don't fix the problems yourself, you can, as a workaround,
     36     make libpcap use DLPI instead of BPF.
     37 
     38     This can be done by specifying the flag:
     39 
     40        --with-pcap=dlpi
     41 
     42     to the "configure" script for libpcap.
     43 
     44 If you use DLPI:
     45 
     46 (1) It is a good idea to have the latest version of the DLPI driver on
     47     your system, since certain versions may be buggy and cause your AIX
     48     system to crash.  DLPI is included in the fileset bos.rte.tty.  I
     49     found that the DLPI driver that came with AIX 4.3.2 was buggy, and
     50     had to upgrade to bos.rte.tty 4.3.2.4:
     51 
     52 	    lslpp -l bos.rte.tty
     53 
     54 	    bos.rte.tty     4.3.2.4  COMMITTED  Base TTY Support and Commands
     55 
     56     Updates for AIX filesets can be obtained from:
     57     ftp://service.software.ibm.com/aix/fixes/
     58 
     59     These updates can be installed with the smit program.
     60 
     61 (2) After compiling libpcap, you need to make sure that the DLPI driver
     62     is loaded.  Type:
     63 
     64 	    strload -q -d dlpi
     65 
     66     If the result is:
     67 
     68 	    dlpi: yes
     69 
     70     then the DLPI driver is loaded correctly.
     71 
     72     If it is:
     73 
     74 	    dlpi: no
     75 
     76     Then you need to type:
     77 
     78 	    strload -f /etc/dlpi.conf
     79 
     80     Check again with strload -q -d dlpi that the dlpi driver is loaded.
     81 
     82     Alternatively, you can uncomment the lines for DLPI in
     83     /etc/pse.conf and reboot the machine; this way DLPI will always
     84     be loaded when you boot your system.
     85 
     86 (3) There appears to be a problem in the DLPI code in some versions of
     87     AIX, causing a warning about DL_PROMISC_MULTI failing; this might
     88     be responsible for DLPI not being able to capture outgoing packets.
     89 

README.dag

      1 
      2 The following instructions apply if you have a Linux or FreeBSD platform and
      3 want libpcap to support the DAG range of passive network monitoring cards from
      4 Endace (http://www.endace.com, see below for further contact details).
      5 
      6 1) Install and build the DAG software distribution by following the
      7 instructions supplied with that package. Current Endace customers can download
      8 the DAG software distibution from https://www.endace.com
      9 
     10 2) Configure libcap. To allow the 'configure' script to locate the DAG
     11 software distribution use the '--with-dag' option:
     12 
     13         ./configure --with-dag=DIR
     14 
     15 Where DIR is the root of the DAG software distribution, for example
     16 /var/src/dag. If the DAG software is correctly detected 'configure' will
     17 report:
     18 
     19         checking whether we have DAG API... yes
     20 
     21 If 'configure' reports that there is no DAG API, the directory may have been
     22 incorrectly specified or the DAG software was not built before configuring
     23 libpcap.
     24 
     25 See also the libpcap INSTALL.txt file for further libpcap configuration
     26 options.
     27 
     28 Building libpcap at this stage will include support for both the native packet
     29 capture stream (linux or bpf) and for capturing from DAG cards. To build
     30 libpcap with only DAG support specify the capture type as 'dag' when
     31 configuring libpcap:
     32 
     33         ./configure --with-dag=DIR --with-pcap=dag
     34 
     35 Applications built with libpcap configured in this way will only detect DAG
     36 cards and will not capture from the native OS packet stream.
     37 
     38 ----------------------------------------------------------------------
     39 
     40 Libpcap when built for DAG cards against dag-2.5.1 or later releases:
     41 
     42 Timeouts are supported. pcap_dispatch() will return after to_ms milliseconds
     43 regardless of how many packets are received. If to_ms is zero pcap_dispatch()
     44 will block waiting for data indefinitely.
     45 
     46 pcap_dispatch() will block on and process a minimum of 64kB of data (before
     47 filtering) for efficiency. This can introduce high latencies on quiet
     48 interfaces unless a timeout value is set. The timeout expiring will override
     49 the 64kB minimum causing pcap_dispatch() to process any available data and
     50 return.
     51 
     52 pcap_setnonblock is supported. When nonblock is set, pcap_dispatch() will
     53 check once for available data, process any data available up to count, then
     54 return immediately.
     55 
     56 pcap_findalldevs() is supported, e.g. dag0, dag1...
     57 
     58 Some DAG cards can provide more than one 'stream' of received data.
     59 This can be data from different physical ports, or separated by filtering
     60 or load balancing mechanisms. Receive streams have even numbers, e.g.
     61 dag0:0, dag0:2 etc. Specifying transmit streams for capture is not supported.
     62 
     63 pcap_setfilter() is supported, BPF programs run in userspace.
     64 
     65 pcap_setdirection() is not supported. Only received traffic is captured.
     66 DAG cards normally do not have IP or link layer addresses assigned as
     67 they are used to passively monitor links.
     68 
     69 pcap_breakloop() is supported.
     70 
     71 pcap_datalink() and pcap_list_datalinks() are supported. The DAG card does
     72 not attempt to set the correct datalink type automatically where more than
     73 one type is possible.
     74 
     75 pcap_stats() is supported. ps_drop is the number of packets dropped due to
     76 RX stream buffer overflow, this count is before filters are applied (it will
     77 include packets that would have been dropped by the filter). The RX stream
     78 buffer size is user configurable outside libpcap, typically 16-512MB.
     79 
     80 pcap_get_selectable_fd() is not supported, as DAG cards do not support
     81 poll/select methods.
     82 
     83 pcap_inject() and pcap_sendpacket() are not supported.
     84 
     85 Some DAG cards now support capturing to multiple virtual interfaces, called
     86 streams. Capture streams have even numbers. These are available via libpcap
     87 as separate interfaces, e.g. dag0:0, dag0:2, dag0:4 etc. dag0:0 is the same
     88 as dag0. These are visible via pcap_findalldevs().
     89 
     90 libpcap now does NOT set the card's hardware snaplen (slen). This must now be
     91 set using the appropriate DAG coniguration program, e.g. dagthree, dagfour,
     92 dagsix, dagconfig. This is because the snaplen is currently shared between
     93 all of the streams. In future this may change if per-stream slen is
     94 implemented.
     95 
     96 DAG cards by default capture entire packets including the L2
     97 CRC/FCS. If the card is not configured to discard the CRC/FCS, this
     98 can confuse applications that use libpcap if they're not prepared for
     99 packets to have an FCS.
    100 
    101 Libpcap now reads the environment variable ERF_FCS_BITS to determine
    102 how many bits of CRC/FCS to strip from the end of the captured
    103 frame. This defaults to 32 for use with Ethernet. If the card is
    104 configured to strip the CRC/FCS, then set ERF_FCS_BITS=0. If used with
    105 a HDLC/PoS/PPP/Frame Relay link with 16 bit CRC/FCS, then set
    106 ERF_FCS_BITS=16.
    107 
    108 If you wish to create a pcap file that DOES contain the Ethernet FCS,
    109 specify the environment variable ERF_DONT_STRIP_FCS. This will cause
    110 the existing FCS to be captured into the pcap file. Note some
    111 applications may incorrectly report capture errors or oversize packets
    112 when reading these files.
    113 
    114 ----------------------------------------------------------------------
    115 
    116 Please submit bug reports via <support (a] endace.com>.
    117 
    118 Please also visit our Web site at:
    119 
    120         http://www.endace.com/
    121 
    122 For more information about Endace DAG cards contact <sales (a] endace.com>.
    123 

README.hpux

      1 For HP-UX 11i (11.11) and later, there are no known issues with
      2 promiscuous mode under HP-UX.  If you are using a earlier version of
      3 HP-UX and cannot upgrade, please continue reading.
      4 
      5 HP-UX patches to fix packet capture problems
      6 
      7 Note that packet-capture programs such as tcpdump may, on HP-UX, not be
      8 able to see packets sent from the machine on which they're running.
      9 Some articles on groups.google.com discussing this are:
     10 
     11 	http://groups.google.com/groups?selm=82ld3v%2480i%241%40mamenchi.zrz.TU-Berlin.DE
     12 
     13 which says:
     14 
     15   Newsgroups: comp.sys.hp.hpux
     16   Subject:  Re: Did someone made tcpdump working on 10.20 ?
     17   Date: 12/08/1999
     18   From: Lutz Jaenicke <jaenicke (a] emserv1.ee.TU-Berlin.DE>
     19 
     20   In article <82ks5i$5vc$1 (a] news1.dti.ne.jp>, mtsat <mtsat (a] iris.dti.ne.jp>
     21   wrote:
     22    >Hello,
     23    >
     24    >I downloaded and compiled tcpdump3.4 a couple of week ago. I tried to use
     25    >it, but I can only see incoming data, never outgoing.
     26    >Someone (raj) explained me that a patch was missing, and that this patch
     27    >must me "patched" (poked) in order to see outbound data in promiscuous mode.
     28    >Many things to do .... So the question is : did someone has already this
     29    >"ready to use" PHNE_**** patch ?
     30 
     31    Two things:
     32    1. You do need a late "LAN products cumulative patch" (e.g.  PHNE_18173
     33   for   s700/10.20).
     34    2. You must use
     35 echo 'lanc_outbound_promisc_flag/W1' | /usr/bin/adb -w /stand/vmunix /dev/kmem
     36      You can insert this e.g. into /sbin/init.d/lan
     37 
     38    Best regards,
     39    Lutz
     40 
     41 and
     42 
     43 	http://groups.google.com/groups?selm=88cf4t%24p03%241%40web1.cup.hp.com
     44 
     45 which says:
     46 
     47   Newsgroups: comp.sys.hp.hpux
     48   Subject: Re: tcpdump only shows incoming packets
     49   Date: 02/15/2000
     50   From: Rick Jones <foo (a] bar.baz.invalid>
     51 
     52   Harald Skotnes <harald (a] cc.uit.no> wrote:
     53   > I am running HPUX 11.0 on a C200 hanging on a 100Mb switch. I have
     54   > compiled libpcap-0.4 an tcpdump-3.4 and it seems to work. But at a
     55   > closer look I only get to see the incoming packets not the
     56   > outgoing. I have tried tcpflow-0.12 which also uses libpcap and the
     57   > same thing happens.  Could someone please give me a hint on how to
     58   > get this right?
     59 
     60   Search/Read the archives ?-)
     61 
     62   What you are seeing is expected, un-patched, behaviour for an HP-UX
     63   system.  On 11.00, you need to install the latest lancommon/DLPI
     64   patches, and then the latest driver patch for the interface(s) in use.
     65   At that point, a miracle happens and you should start seeing outbound
     66   traffic.
     67 
     68 [That article also mentions the patch that appears below.]
     69 
     70 and
     71 
     72 	http://groups.google.com/groups?selm=38AA973E.96BE7DF7%40cc.uit.no
     73 
     74 which says:
     75 
     76   Newsgroups: comp.sys.hp.hpux
     77   Subject: Re: tcpdump only shows incoming packets
     78   Date: 02/16/2000
     79   From: Harald Skotnes <harald (a] cc.uit.no>
     80 
     81   Rick Jones wrote:
     82 
     83 	...
     84 
     85   > What you are seeing is expected, un-patched, behaviour for an HP-UX
     86   > system. On 11.00, you need to install the latest lancommon/DLPI
     87   > patches, and then the latest driver patch for the interface(s) in
     88   > use. At that point, a miracle happens and you should start seeing
     89   > outbound traffic.
     90 
     91   Thanks a lot.  I have this problem on several machines running HPUX
     92   10.20 and 11.00.  The machines where patched up before y2k so did not
     93   know what to think.  Anyway I have now installed PHNE_19766,
     94   PHNE_19826, PHNE_20008, PHNE_20735 on the C200 and now I can see the
     95   outbound traffic too.  Thanks again.
     96 
     97 (although those patches may not be the ones to install - there may be
     98 later patches).
     99 
    100 And another message to tcpdump-workers (a] tcpdump.org, from Rick Jones:
    101 
    102   Date: Mon, 29 Apr 2002 15:59:55 -0700
    103   From: Rick Jones
    104   To: tcpdump-workers (a] tcpdump.org
    105   Subject: Re: [tcpdump-workers] I Can't Capture the Outbound Traffic
    106 
    107 	...
    108 
    109   http://itrc.hp.com/ would be one place to start in a search for the most
    110   up-to-date patches for DLPI and the lan driver(s) used on your system (I
    111   cannot guess because 9000/800 is too generic - one hs to use the "model"
    112   command these days and/or an ioscan command (see manpage) to guess what
    113   the drivers (btlan[3456], gelan, etc) might be involved in addition to
    114   DLPI.
    115 
    116   Another option is to upgrade to 11i as outbound promiscuous mode support
    117   is there in the base OS, no patches required.
    118 
    119 Another posting:
    120 
    121 	http://groups.google.com/groups?selm=7d6gvn%24b3%241%40ocean.cup.hp.com
    122 
    123 indicates that you need to install the optional STREAMS product to do
    124 captures on HP-UX 9.x:
    125 
    126   Newsgroups: comp.sys.hp.hpux
    127   Subject:  Re: tcpdump HP/UX 9.x
    128   Date: 03/22/1999
    129   From: Rick Jones <foo (a] bar.baz>
    130 
    131   Dave Barr (barr (a] cis.ohio-state.edu) wrote:
    132   : Has anyone ported tcpdump (or something similar) to HP/UX 9.x?
    133 
    134   I'm reasonably confident that any port of tcpdump to 9.X would require
    135   the (then optional) STREAMS product.  This would bring DLPI, which is
    136   what one uses to access interfaces in promiscuous mode.
    137 
    138   I'm not sure that HP even sells the 9.X STREAMS product any longer,
    139   since HP-UX 9.X is off the pricelist (well, maybe 9.10 for the old 68K
    140   devices).
    141 
    142   Your best bet is to be up on 10.20 or better if that is at all
    143   possible.  If your hardware is supported by it, I'd go with HP-UX 11.
    144   If you want to see the system's own outbound traffic, you'll never get
    145   that functionality on 9.X, but it might happen at some point for 10.20
    146   and 11.X.
    147 
    148   rick jones
    149 
    150 (as per other messages cited here, the ability to see the system's own
    151 outbound traffic did happen).
    152 
    153 Rick Jones reports that HP-UX 11i needs no patches for outbound
    154 promiscuous mode support.
    155 
    156 An additional note, from Jost Martin, for HP-UX 10.20:
    157 
    158 	Q: How do I get ethereral on HPUX to capture the _outgoing_ packets
    159 	   of an interface
    160 	A: You need to get PHNE_20892,PHNE_20725 and PHCO_10947 (or
    161 	   newer, this is as of 4.4.00) and its dependencies.  Then you can
    162 	   enable the feature as descibed below:
    163 
    164 	Patch Name: PHNE_20892
    165 	Patch Description: s700 10.20 PCI 100Base-T cumulative patch
    166 		To trace the outbound packets, please do the following
    167 		to turn on a global promiscuous switch before running
    168 		the promiscuous applications like snoop or tcpdump:
    169 
    170 		adb -w /stand/vmunix /dev/mem
    171 		lanc_outbound_promisc_flag/W 1
    172 		(adb will echo the result showing that the flag has
    173 		been changed)
    174 		$quit
    175 	(Thanks for this part to HP-support, Ratingen)
    176 
    177 		The attached hack does this and some security-related stuff
    178 	(thanks to hildeb (a] www.stahl.bau.tu-bs.de (Ralf Hildebrandt) who
    179 	posted the security-part some time ago)
    180 
    181 		 <<hack_ip_stack>>
    182 
    183 		(Don't switch IP-forwarding off, if you need it !)
    184 		Install the hack as /sbin/init.d/hacl_ip_stack (adjust
    185 	permissions !) and make a sequencing-symlink
    186 	/sbin/rc2.d/S350hack_ip_stack pointing to this script.
    187 		Now all this is done on every reboot.
    188 
    189 According to Rick Jones, the global promiscuous switch also has to be
    190 turned on for HP-UX 11.00, but not for 11i - and, in fact, the switch
    191 doesn't even exist on 11i.
    192 
    193 Here's the "hack_ip_stack" script:
    194 
    195 -----------------------------------Cut Here-------------------------------------
    196 #!/sbin/sh
    197 #
    198 # nettune:  hack kernel parms for safety
    199 
    200 OKAY=0
    201 ERROR=-1
    202 
    203 # /usr/contrib/bin fuer nettune auf Pfad
    204 PATH=/sbin:/usr/sbin:/usr/bin:/usr/contrib/bin
    205 export PATH
    206 
    207 
    208 ##########
    209 #  main  #
    210 ##########
    211 
    212 case $1 in
    213    start_msg)
    214       print "Tune IP-Stack for security"
    215       exit $OKAY
    216       ;;
    217 
    218    stop_msg)
    219       print "This action is not applicable"
    220       exit $OKAY
    221       ;;
    222 
    223    stop)
    224       exit $OKAY
    225       ;;
    226 
    227    start)
    228       ;;  # fall through
    229 
    230    *)
    231       print "USAGE: $0 {start_msg | stop_msg | start | stop}" >&2
    232       exit $ERROR
    233       ;;
    234    esac
    235 
    236 ###########
    237 #  start  #
    238 ###########
    239 
    240 #
    241 # tcp-Sequence-Numbers nicht mehr inkrementieren sondern random
    242 # Syn-Flood-Protection an
    243 # ip_forwarding aus
    244 # Source-Routing aus
    245 # Ausgehende Packets an ethereal/tcpdump etc.
    246 
    247 /usr/contrib/bin/nettune -s tcp_random_seq 2 || exit $ERROR
    248 /usr/contrib/bin/nettune -s hp_syn_protect 1 || exit $ERROR
    249 /usr/contrib/bin/nettune -s ip_forwarding 0 || exit $ERROR
    250 echo 'ip_block_source_routed/W1' | /usr/bin/adb -w /stand/vmunix /dev/kmem || exit $ERROR
    251 echo 'lanc_outbound_promisc_flag/W 1' | adb -w /stand/vmunix /dev/mem  || exit $ERROR
    252 
    253 exit $OKAY
    254 -----------------------------------Cut Here-------------------------------------
    255 

README.linux.md

      1 In order for libpcap to be able to capture packets on a Linux system,
      2 the "packet" protocol must be supported by your kernel.  If it is not,
      3 you may get error messages such as
      4 
      5 	modprobe: can't locate module net-pf-17
      6 
      7 in "/var/adm/messages", or may get messages such as
      8 
      9 	socket: Address family not supported by protocol
     10 
     11 from applications using libpcap.
     12 
     13 You must configure the kernel with the CONFIG_PACKET option for this
     14 protocol; the following note is from the Linux "Configure.help" file for
     15 the 2.0[.x] kernel:
     16 
     17 	Packet socket
     18 	CONFIG_PACKET
     19 	  The Packet protocol is used by applications which communicate
     20 	  directly with network devices without an intermediate network
     21 	  protocol implemented in the kernel, e.g. tcpdump. If you want them
     22 	  to work, choose Y.
     23 
     24 	  This driver is also available as a module called af_packet.o ( =
     25 	  code which can be inserted in and removed from the running kernel
     26 	  whenever you want). If you want to compile it as a module, say M
     27 	  here and read Documentation/modules.txt; if you use modprobe or
     28 	  kmod, you may also want to add "alias net-pf-17 af_packet" to
     29 	  /etc/modules.conf.
     30 
     31 and the note for the 2.2[.x] kernel says:
     32 
     33 	Packet socket
     34 	CONFIG_PACKET
     35 	  The Packet protocol is used by applications which communicate
     36 	  directly with network devices without an intermediate network
     37 	  protocol implemented in the kernel, e.g. tcpdump. If you want them
     38 	  to work, choose Y. This driver is also available as a module called
     39 	  af_packet.o ( = code which can be inserted in and removed from the
     40 	  running kernel whenever you want). If you want to compile it as a
     41 	  module, say M here and read Documentation/modules.txt.  You will
     42 	  need to add 'alias net-pf-17 af_packet' to your /etc/conf.modules
     43 	  file for the module version to function automatically.  If unsure,
     44 	  say Y.
     45 
     46 In addition, there is an option that, in 2.2 and later kernels, will
     47 allow packet capture filters specified to programs such as tcpdump to be
     48 executed in the kernel, so that packets that don't pass the filter won't
     49 be copied from the kernel to the program, rather than having all packets
     50 copied to the program and libpcap doing the filtering in user mode.
     51 
     52 Copying packets from the kernel to the program consumes a significant
     53 amount of CPU, so filtering in the kernel can reduce the overhead of
     54 capturing packets if a filter has been specified that discards a
     55 significant number of packets.  (If no filter is specified, it makes no
     56 difference whether the filtering isn't performed in the kernel or isn't
     57 performed in user mode. :-))
     58 
     59 The option for this is the CONFIG_FILTER option; the "Configure.help"
     60 file says:
     61 
     62 	Socket filtering
     63 	CONFIG_FILTER
     64 	  The Linux Socket Filter is derived from the Berkeley Packet Filter.
     65 	  If you say Y here, user-space programs can attach a filter to any
     66 	  socket and thereby tell the kernel that it should allow or disallow
     67 	  certain types of data to get through the socket. Linux Socket
     68 	  Filtering works on all socket types except TCP for now. See the text
     69 	  file linux/Documentation/networking/filter.txt for more information.
     70 	  If unsure, say N.
     71 
     72 Note that, by default, libpcap will, if libnl is present, build with it;
     73 it uses libnl to support monitor mode on mac80211 devices.  There is a
     74 configuration option to disable building with libnl, but, if that option
     75 is chosen, the monitor-mode APIs (as used by tcpdump's "-I" flag, and as
     76 will probably be used by other applications in the future) won't work
     77 properly on mac80211 devices.
     78 
     79 Linux's run-time linker allows shared libraries to be linked with other
     80 shared libraries, which means that if an older version of a shared
     81 library doesn't require routines from some other shared library, and a
     82 later version of the shared library does require those routines, the
     83 later version of the shared library can be linked with that other shared
     84 library and, if it's otherwise binary-compatible with the older version,
     85 can replace that older version without breaking applications built with
     86 the older version, and without breaking configure scripts or the build
     87 procedure for applications whose configure script doesn't use the
     88 pcap-config script if they build with the shared library.  (The build
     89 procedure for applications whose configure scripts use the pcap-config
     90 script if present will not break even if they build with the static
     91 library.)
     92 
     93 Statistics:
     94 Statistics reported by pcap are platform specific.  The statistics
     95 reported by pcap_stats on Linux are as follows:
     96 
     97 2.2.x
     98 =====
     99 ps_recv   Number of packets that were accepted by the pcap filter
    100 ps_drop   Always 0, this statistic is not gatherd on this platform
    101 
    102 2.4.x
    103 =====
    104 ps_recv   Number of packets that were accepted by the pcap filter
    105 ps_drop   Number of packets that had passed filtering but were not
    106           passed on to pcap due to things like buffer shortage, etc.
    107           This is useful because these are packets you are interested in
    108           but won't be reported by, for example, tcpdump output.
    109 

README.macos

      1 As with other systems using BPF, macOS allows users with read access to
      2 the BPF devices to capture packets with libpcap and allows users with
      3 write access to the BPF devices to send packets with libpcap.
      4 
      5 On some systems that use BPF, the BPF devices live on the root file
      6 system, and the permissions and/or ownership on those devices can be
      7 changed to give users other than root permission to read or write those
      8 devices.
      9 
     10 On newer versions of FreeBSD, the BPF devices live on devfs, and devfs
     11 can be configured to set the permissions and/or ownership of those
     12 devices to give users other than root permission to read or write those
     13 devices.
     14 
     15 On macOS, the BPF devices live on devfs, but the macOS version of devfs
     16 is based on an older (non-default) FreeBSD devfs, and that version of
     17 devfs cannot be configured to set the permissions and/or ownership of
     18 those devices.
     19 
     20 Therefore, we supply:
     21 
     22 	a "startup item" for older versions of macOS;
     23 
     24 	a launchd daemon for Tiger and later versions of macOS;
     25 
     26 Both of them will change the ownership of the BPF devices so that the
     27 "admin" group owns them, and will change the permission of the BPF
     28 devices to rw-rw----, so that all users in the "admin" group - i.e., all
     29 users with "Allow user to administer this computer" turned on - have
     30 both read and write access to them.
     31 
     32 The startup item is in the ChmodBPF directory in the source tree.  A
     33 /Library/StartupItems directory should be created if it doesn't already
     34 exist, and the ChmodBPF directory should be copied to the
     35 /Library/StartupItems directory (copy the entire directory, so that
     36 there's a /Library/StartupItems/ChmodBPF directory, containing all the
     37 files in the source tree's ChmodBPF directory; don't copy the individual
     38 items in that directory to /Library/StartupItems).  The ChmodBPF
     39 directory, and all files under it, must be owned by root.  Installing
     40 the files won't immediately cause the startup item to be executed; it
     41 will be executed on the next reboot.  To change the permissions before
     42 the reboot, run
     43 
     44 	sudo SystemStarter start ChmodBPF
     45 
     46 The launchd daemon is the chmod_bpf script, plus the
     47 org.tcpdump.chmod_bpf.plist launchd plist file.  chmod_bpf should be
     48 installed in /usr/local/bin/chmod_bpf, and org.tcpdump.chmod_bpf.plist
     49 should be installed in /Library/LaunchDaemons.  chmod_bpf, and
     50 org.tcpdump.chmod_bpf.plist, must be owned by root.  Installing the
     51 script and plist file won't immediately cause the script to be executed;
     52 it will be executed on the next reboot.  To change the permissions
     53 before the reboot, run
     54 
     55 	sudo /usr/local/bin/chmod_bpf
     56 
     57 or
     58 
     59 	sudo launchctl load /Library/LaunchDaemons/org.tcpdump.chmod_bpf.plist
     60 
     61 If you want to give a particular user permission to access the BPF
     62 devices, rather than giving all administrative users permission to
     63 access them, you can have the ChmodBPF/ChmodBPF script change the
     64 ownership of /dev/bpf* without changing the permissions.  If you want to
     65 give a particular user permission to read and write the BPF devices and
     66 give the administrative users permission to read but not write the BPF
     67 devices, you can have the script change the owner to that user, the
     68 group to "admin", and the permissions to rw-r-----.  Other possibilities
     69 are left as an exercise for the reader.
     70 
     71 (NOTE: due to a bug in Snow Leopard, if you change the permissions not
     72 to grant write permission to everybody who should be allowed to capture
     73 traffic, non-root users who cannot open the BPF devices for writing will
     74 not be able to capture outgoing packets.)
     75 

README.septel

      1 The following instructions apply if you have a Linux platform and want
      2 libpcap to support the Septel range of passive network monitoring cards
      3 from Intel (http://www.intel.com)
      4 
      5 1) Install and build the Septel software distribution by following the
      6 instructions supplied with that package.
      7 
      8 2) Configure libcap. To allow the 'configure' script to locate the Septel
      9 software distribution use the '--with-septel' option:
     10 
     11         ./configure --with-septel=DIR
     12 
     13 where DIR is the root of the Septel software distribution, for example
     14 /var/src/septel.
     15 
     16 By default (if you write only ./configure --with-septel) it takes
     17 ./../septel as argument for DIR.
     18 
     19 If the Septel software is correctly detected 'configure' will
     20 report:
     21 
     22         checking whether we have Septel API... yes
     23 
     24 If 'configure' reports that there is no Septel API, the directory may have been
     25 incorrectly specified or the Septel software was not built before configuring
     26 libpcap.
     27 
     28 See also the libpcap INSTALL.txt file for further libpcap configuration
     29 options.
     30 
     31 Building libpcap at this stage will include support for both the native
     32 packet capture stream and for capturing from Septel cards.  To build
     33 libpcap with only Septel support specify the capture type as 'septel'
     34 when configuring libpcap:
     35 
     36         ./configure --with-septel=DIR --with-pcap=septel
     37 
     38 Applications built with libpcap configured in this way will only detect Septel
     39 cards and will not capture from the native OS packet stream.
     40 
     41 Note: As mentioned in pcap-septel.c we should first edit the system.txt
     42 file to change the user part example (UPE) module id to 0xdd instead of
     43 0x2d for technical reason.  So this change in system.txt is crucial and
     44 things will go wrong if it's not done.  System.txt along with config.txt
     45 are configuration files that are edited by the user before running the
     46 gctload program that uses these files for initialising modules and
     47 configuring parameters.
     48 
     49 ----------------------------------------------------------------------
     50 for more information please contact me : gil_hoyek (a] hotmail.com
     51 

README.sita

      1 The following instructions apply if you have a Linux platform and want
      2 libpcap to support the 'ACN' WAN/LAN router product from SITA
      3 (http://www.sita.aero)
      4 
      5 This might also work on non-Linux Unix-compatible platforms, but that
      6 has not been tested.
      7 
      8 See also the libpcap INSTALL.txt file for further libpcap configuration
      9 options.
     10 
     11 These additions/extensions have been made to PCAP to allow it to
     12 capture packets from a SITA ACN device (and potentially others).
     13 
     14 To enable its support you need to ensure that the distribution has
     15 a correct configure.ac file; that can be created if neccessay by
     16 using the normal autoconf procedure of:
     17 
     18 aclocal
     19 autoconf
     20 autoheader
     21 automake
     22 
     23 Then run configure with the 'sita' option:
     24 
     25 ./configure --with-sita
     26 
     27 Applications built with libpcap configured in this way will only detect SITA
     28 ACN interfaces and will not capture from the native OS packet stream.
     29 
     30 The SITA extension provides a remote datascope operation for capturing
     31 both WAN and LAN protocols.  It effectively splits the operation of
     32 PCAP into two halves.  The top layer performs the majority of the
     33 work, but interfaces via a TCP session to remote agents that
     34 provide the lower layer functionality of actual sniffing and
     35 filtering. More detailed information regarding the functions and
     36 inter-device protocol and naming conventions are described in detail
     37 in 'pcap-sita.html'.
     38 
     39 pcap_findalldevs() reads the local system's /etc/hosts file looking
     40 for host names that match the format of IOP type devices.  ie.  aaa_I_x_y
     41 and then queries each associated IP address for a list of its WAN and
     42 LAN devices.  The local system the aggregates the lists obtained from
     43 each IOP, sorts it, and provides it (to Wireshark et.al) as the
     44 list of monitorable interfaces.
     45 
     46 Once a valid interface has been selected, pcap_open() is called
     47 which opens a TCP session (to a well known port) on the target IOP
     48 and tells it to start monitoring.
     49 
     50 All captured packets are then forwarded across that TCP session
     51 back to the local 'top layer' for forwarding to the actual
     52 sniffing program (wireshark...)
     53 
     54 Note that the DLT_SITA link-layer type includes a proprietary header
     55 that is documented as part of the SITA dissector of Wireshark and is
     56 also described in 'pcap-sita.html' for posterity sake.
     57 
     58 That header provides:
     59 - Packet direction (in/out) (1 octet)
     60 - Link layer hardware signal status (1 octet)
     61 - Transmit/Receive error status (2 octets)
     62 - Encapsulated WAN protocol ID (1 octet)
     63 
     64 
     65 

README.tru64

      1 The following instructions are applicable to Tru64 UNIX
      2 (formerly Digital UNIX (formerly DEC OSF/1)) version 4.0, and
      3 probably to later versions as well; at least some options apply to
      4 Digital UNIX 3.2 - perhaps all do.
      5 
      6 In order to use kernel packet filtering on this system, you have
      7 to configure it in such a way:
      8 
      9 Kernel configuration
     10 --------------------
     11 
     12 The packet filtering kernel option must be enabled at kernel
     13 installation.  If it was not the case, you can rebuild the kernel with
     14 "doconfig -c" after adding the following line in the kernel
     15 configuration file (/sys/conf/<HOSTNAME>):
     16 
     17 	option PACKETFILTER
     18 
     19 or use "doconfig" without any arguments to add the packet filter driver
     20 option via the kernel option menu (see the system administration
     21 documentation for information on how to do this).
     22 
     23 Device configuration
     24 --------------------
     25 
     26 Devices used for packet filtering must be created thanks to
     27 the following command (executed in the /dev directory):
     28 
     29 	./MAKEDEV pfilt
     30 
     31 Interface configuration
     32 -----------------------
     33 
     34 In order to capture all packets on a network, you may want to allow
     35 applications to put the interface on that network into "local copy"
     36 mode, so that tcpdump can see packets sent by the host on which it's
     37 running as well as packets received by that host, and to put the
     38 interface into "promiscuous" mode, so that tcpdump can see packets on
     39 the network segment not sent to the host on which it's running, by using
     40 the pfconfig(1) command:
     41 
     42 	pfconfig +c +p <network_device>
     43 
     44 or allow application to put any interface into "local copy" or
     45 "promiscuous" mode by using the command:
     46 
     47 	pfconfig +c +p -a
     48 
     49 Note: all instructions given require root privileges.
     50 

README.Win32

      1 Under Win32, libpcap is integrated in the WinPcap packet capture system.
      2 WinPcap provides a framework that allows libpcap to capture the packets
      3 under Windows 95, Windows 98, Windows ME, Windows NT 4, Windows 2000
      4 and Windows XP.
      5 WinPcap binaries and source code can be found at http://winpcap.polito.it:
      6 they include also a developer's pack with all the necessary to compile
      7 libpcap-based applications under Windows.
      8 
      9 How to compile libpcap with Visual Studio
     10 -----------------------------------------
     11 
     12 In order to compile libpcap you will need:
     13 
     14 - version 6 (or higher) of Microsoft Visual Studio
     15 - The November 2001 (or later) edition of Microsoft Platform
     16 Software Development Kit (SDK), that contains some necessary includes
     17 for IPv6 support. You can download it from http://www.microsoft.com/sdk
     18 - the latest WinPcap sources from http://winpcap.polito.it/install
     19 
     20 The WinPcap source code already contains a recent (usually the latest
     21 stable) version of libpcap. If you need to compile a different one,
     22 simply download it from www.tcpdump.org and copy the sources in the
     23 winpcap\wpcap\libpcap folder of the WinPcap distribution. If you want to
     24 compile a libpcap source retrieved from the tcpdump.org Git, you will
     25 have to create the scanner and the grammar by hand (with lex and yacc)
     26 or with the cygnus makefile, since The Visual Studio project is not able
     27 to build them.
     28 
     29 Open the project file winpcap\wpcap\prj\wpcap.dsw with Visual Studio and
     30 build wpcap.dll. wpcap.lib, the library file to link with the applications,
     31 will be generated in winpcap\wpcap\lib\. wpcap.dll will be generated in
     32 winpcap\wpcap\prj\release or winpcap\wpcap\prj\debug depending on the type
     33 of binary that is being created.
     34 
     35 How to compile libpcap with Cygnus
     36 ----------------------------------
     37 
     38 To build wpcap.dll, cd to the directory WPCAP/PRJ of the WinPcap source code
     39 distribution and type "make". libwpcap.a, the library file to link with the
     40 applications, will be generated in winpcap\wpcap\lib\. wpcap.dll will be
     41 generated in winpcap\wpcap\prj.
     42 
     43 Remember, you CANNOT use the MSVC-generated .lib files with gcc, use
     44 libwpcap.a instead.
     45 
     46 "make install" installs wpcap.dll in the Windows system folder.
     47