Building libpcap on Windows with Visual Studio
==============================================

Unlike the UN*Xes on which libpcap can capture network traffic, Windows
has no network traffic capture mechanism that libpcap can use.
Therefore, libpcap requires a driver, and a library to access the
driver, provided by the Npcap or WinPcap projects.

Those projects include versions of libpcap built to use that driver and
library; these instructions are for people who want to build libpcap
source releases, or libpcap from the Git repository, as a replacement
for the version provided with Npcap or WinPcap.

Npcap and WinPcap SDK
---------------------

In order to build libpcap, you will need to download Npcap and its
software development kit (SDK) or WinPcap and its software development
kit.

Npcap is currently being developed and maintained, and offers many
additional capabilities that WinPcap does not.

WinPcap is no longer being developed or maintained; it should be used
only if there is some other requirement to use it rather than Npcap,
such as a requirement to support versions of Windows earlier than
Windows Vista, which is the earliest version supported by Npcap.

Npcap and its SDK can be downloaded from its home page:

  https://npcap.org

The SDK is a ZIP archive; create a folder on your C: drive, e.g.
C:\npcap-sdk, and put the contents of the ZIP archive into that folder.

The WinPcap installer can be downloaded from

  https://www.winpcap.org/install/default.htm

and the WinPcap Developer's Kit can be downloaded from

  https://www.winpcap.org/devel.htm

Required build tools
--------------------

The Developer's Kit is a ZIP archive; it contains a folder named
WpdPack, which you should place on your C: drive, e.g. C:\WpdPack.

Building libpcap on Windows requires Visual Studio 2015 or later.  The
Community Edition of Visual Studio can be downloaded at no cost from

  https://visualstudio.microsoft.com

Additional tools are also required.  Chocolatey is a package manager for
Windows with which those tools, and other tools, can be installed; it
can be downloaded from

  https://chocolatey.org

It is a command-line tool; a GUI tool, Chocolatey GUI, is provided as a
Chocolatey package, which can be installed from the command line:

	choco install chocolateygui

For convenience, the "choco install" command can be run with the "-y"
flag, forcing it to automatically answer all questions asked of the user
with "yes":

	choco install -y chocolateygui

The required tools are:

### CMake ###

libpcap does not provide supported project files for Visual Studio
(there are currently unsupported project files provided, but we do not
guarantee that they will work or that we will continue to provide them).
It does provide files for CMake, which is a cross-platform tool that
runs on UN*Xes and on Windows and that can generate project files for
UN*X Make, the Ninja build system, and Visual Studio, among other build
systems.

Visual Studio 2015 does not provide CMake; an installer can be
downloaded from

  https://cmake.org/download/

When you run the installer, you should choose to add CMake to the system
PATH for all users and to create the desktop icon.

CMake can also be installed as the Chocolatey package "cmake":

	choco install -y cmake

Visual Studio 2017 and later provide CMake, so you will not need to
install CMake if you have installed Visual Studio 2017 or later.  They
include built-in support for CMake-based projects:

  https://devblogs.microsoft.com/cppblog/cmake-support-in-visual-studio/

For Visual Studio 2017, make sure "Visual C++ tools for CMake" is
installed; for Visual Studio 2019, make sure "C++ CMake tools for
Windows" is intalled.

### winflexbison ###

libpcap uses the Flex lexical-analyzer generator and the Bison or
Berkeley YACC parser generators to generate the parser for filter
expressions.  Windows versions of Flex and Bison can be downloaded from

  https://sourceforge.net/projects/winflexbison/

The downloaded file is a ZIP archive; create a folder on your C: drive,
e.g. C:\Program Files\winflexbison, and put the contents of the ZIP
archive into that folder.  Then add that folder to the system PATH
environment variable.

Git
---

An optional tool, required only if you will be building from a Git
repository rather than from a release source tarball, is Git.  Git is
provided as an optional installation component, "Git for Windows", with
Visual Studio 2017 and later.

Building from the Visual Studio GUI
-----------------------------------

### Visual Studio 2017 ###

Open the folder containing the libpcap source with Open > Folder.
Visual Studio will run CMake; however, you will need to indicate where
the Npcap or WinPcap SDK is installed.

To do this, go to Project > "Change CMake Settings" > pcap and:

Choose which configuration type to build, if you don't want the default
Debug build.

In the CMakeSettings.json tab, change cmakeCommandArgs to include

	-DPacket_ROOT={path-to-sdk}

where {path-to-sdk} is the path of the directory containing the Npcap or
WinPcap SDK.  Note that backslashes in the path must be specified as two
backslashes.

Save the configuration changes with File > "Save CMakeSettings.json" or
with control-S.

Visual Studio will then re-run CMake.  If that completes without errors,
you can build with CMake > "Build All".

### Visual Studio 2019 ###

Open the folder containing the libpcap source with Open > Folder.
Visual Studio will run CMake; however, you will need to indicate where
the Npcap or WinPcap SDK is installed.

To do this, go to Project > "CMake Settings for pcap" and:

Choose which configuration type to build, if you don't want the default
Debug build.

Scroll down to "Cmake variables and cache", scroll through the list
looking for the entry for Packet_ROOT, and either type in the path of
the directory containing the Npcap or WinPcap SDK or use the "Browse..."
button to browse for that directory.

Save the configuration changes with File > "Save CMakeSettings.json" or
with control-S.

Visual Studio will then re-run CMake.  If that completes without errors,
you can build with Build > "Build All".

Building from the command line
------------------------------

Start the appropriate Native Tools command line prompt.

Change to the directory into which you want to build libpcap, possibly
after creating it first.  One choice is to create it as a subdirectory
of the libpcap source directory.

Run the command

	cmake "-DPacket_ROOT={path-to-sdk}" {path-to-libpcap-source}

where {path-to-sdk} is the path of the directory containing the Npcap or
WinPcap SDK and {path-to-libpcap-source} is the pathname of the
top-level source directory for libpcap.

Run the command

	msbuild/m pcap.sln

to compile libpcap.

Using BPF:

(1) AIX 4.x's version of BPF is undocumented and somewhat unstandard; the
    current BPF support code includes changes that should work around
    that; it appears to compile and work on at least one AIX 4.3.3
    machine.

    Note that the BPF driver and the "/dev/bpf" devices might not exist
    on your machine; AIX's tcpdump loads the driver and creates the
    devices if they don't already exist.  Our libpcap should do the
    same, and the configure script should detect that it's on an AIX
    system and choose BPF even if the devices aren't there.

    Also note that tcpdump _binary_ compiled on AIX 4 may have a problem
    doing the initial loading of the BPF driver if copied to AIX 5 and
    run there (GH #52). tcpdump binary natively compiled on AIX 5 should
    not have this issue.

(2) If libpcap doesn't compile on your machine when configured to use
    BPF, or if the workarounds fail to make it work correctly, you
    should send to tcpdump-workers@lists.tcpdump.org a detailed bug
    report (if the compile fails, send us the compile error messages;
    if it compiles but fails to work correctly, send us as detailed as
    possible a description of the symptoms, including indications of the
    network link-layer type being wrong or time stamps being wrong).

    If you fix the problems yourself, please submit a patch by forking
    the branch at

	https://github.com/the-tcpdump-group/libpcap/tree/master

    and issuing a pull request, so we can incorporate the fixes into the
    next release.

    If you don't fix the problems yourself, you can, as a workaround,
    make libpcap use DLPI instead of BPF.

    This can be done by specifying the flag:

       --with-pcap=dlpi

    to the "configure" script for libpcap.

If you use DLPI:

(1) It is a good idea to have the latest version of the DLPI driver on
    your system, since certain versions may be buggy and cause your AIX
    system to crash.  DLPI is included in the fileset bos.rte.tty.  I
    found that the DLPI driver that came with AIX 4.3.2 was buggy, and
    had to upgrade to bos.rte.tty 4.3.2.4:

	    lslpp -l bos.rte.tty

	    bos.rte.tty     4.3.2.4  COMMITTED  Base TTY Support and Commands

    Updates for AIX filesets can be obtained from:
    ftp://service.software.ibm.com/aix/fixes/

    These updates can be installed with the smit program.

(2) After compiling libpcap, you need to make sure that the DLPI driver
    is loaded.  Type:

	    strload -q -d dlpi

    If the result is:

	    dlpi: yes

    then the DLPI driver is loaded correctly.

    If it is:

	    dlpi: no

    Then you need to type:

	    strload -f /etc/dlpi.conf

    Check again with strload -q -d dlpi that the dlpi driver is loaded.

    Alternatively, you can uncomment the lines for DLPI in
    /etc/pse.conf and reboot the machine; this way DLPI will always
    be loaded when you boot your system.

(3) There appears to be a problem in the DLPI code in some versions of
    AIX, causing a warning about DL_PROMISC_MULTI failing; this might
    be responsible for DLPI not being able to capture outgoing packets.

		    How to write a libpcap module

WARNING: this document describes an unstable interface; future releases
of libpcap may, and some probably will, change the interface in an
incompatible fashion.  If you submit your module to the libpcap
developers for inclusion in libpcap, not only does that make it more
likely that it will be available in the libpcap provided by operating
system vendors (such as Linux distributions), but it also means that we
will attempt to update it to handle future changes to this interface.
If we add new capabilities, we may have to ask you how to provide those
additional capabilities if you're using an underlying mechanism for
which we have neither the source code nor the documentation.

NOTE: this document assumes familiarity with the entire libpcap API.

TODO: more routines, more stuff that the activate routine has to do
(such as setting the list of DLT_s), convert to Markdown?

On Linux, *BSD, macOS, Solaris, AIX, HP-UX, IRIX, and Tru64 UNIX,
Libpcap supports capturing on network interfaces as supported by the
operating system networking stack, using the native packet capture
mechanism provided by the OS.  On Windows, it supports it with the help
of the driver and library supplied by WinPcap and Npcap.

In addition, it also supports capturing on other types of devices, such
as:

	specialized capture cards, such as Endace DAG cards;

	network adapters that provide special high-performance code
	paths, such as CSPI Myricom adapters;

	buses such as USB;

	software communication channels such as D-Bus and Linux netlink;

	etc..

Support for those devices is provided by modules compiled into libpcap.

If you want to add such a module, you would first have to check the list
of link-layer header types supported by libpcap, to see if one of those
would be sufficient for your device.  The current version of the list
can be found at

	https://www.tcpdump.org/linktypes.html

If none of those would work for your device, please read
doc/DLT_ALLOCATE_HOWTO.md and the introductory paragraphs on the Web
page mentioned above, and then send a request for the new link-layer
header type to tcpdump-workers@lists.tcpdump.org.

Once you have a link-layer header type value or values that you can use,
you can add new module.

The module should be a C source file, with a name of the form
pcap-{MOD}.c, where {MOD} is a name appropriate for your device; for
example, the support for DAG cards is in pcap-dag.c, and the support for
capturing USB traffic on Linux is pcap-usb-linux.c.

Your module is assumed to support one or more named devices.  The names
should be relatively short names, containing only lower-case
alphanumeric characters, consisting of a prefix that ends with an
alphabetic character and, if there can be more than one device instance,
possibly followed by a numerical device ID, such as "mydevice" or
"mydevice0"/"mydevice1"/....  If you have more than one type of device
that you can support, you can have more than one prefix, each of which
can be followed by a numerical device ID.

The two exported functions that your module must provide are routines to
provide a list of device instances and a program to initialize a
created-but-not-activated pcap_t for an instance of one of your devices.

The "list of device instances" routine takes, as arguments:

	a pointer to a pcap_if_list_t;

	a pointer to an error message buffer.

The error message buffer may be assumed to be PCAP_ERRBUF_SIZE bytes
large, but must not be assumed to be larger.  By convention, the routine
typically has a name containing "findalldevs".

The routine should attempt to determine what device instances are
available and add them to the list pointed to by the first argument;
this may be impossible for some modules, but, for those modules, it may
be difficult to capture on the devices using Wirehshark (although it
should be possible to capture on them using tcpdump, TShark, or other
programs that take a device name on the command line), so we recommend
that your routine provide the list of devices if possible.  If it
cannot, it should just immediately return 0.

The routine should add devices to the list by calling the add_dev()
routine in libpcap, declared in the pcap-int.h header.  It takes, as
arguments:

	the pointer to the pcap_if_list_t passed as an argument to the
	routine;

	the device name, as described above;

	a 32-bit word of flags, as provided by pcap_findalldevs();

	a text description of the device, or NULL if there is no
	description;

	the error message buffer pointer provided to the routine.

add_dev() will, if it succeeds, return a pointer to a pcap_if_t that was
added to the list of devices.  If it fails, it will return NULL; in this
case, the error message buffer has been filled in with an error string,
and your routine must return -1 to indicate the error.

If your routine succeeds, it must return 0.  If it fails, it must fill
in the error message buffer with an error string and return -1.

The "initialize the pcap_t" routine takes, as arguments:

	a pointer to a device name;

	a pointer to an error message buffer;

	a pointer to an int.

It returns a pointer to a pcap_t.

Your module will probably need, for each pcap_t for an opened device, a
private data structure to maintain its own information about the opened
device.  These should be allocated per opened instance, not per device;
if, for example, mydevice0 can be captured on by more than one program
at the same time, there will be more than one pcap_t opened for
mydevice0, and so there will be separate private data structures for
each pcap_t.  If you need to maintain per-device, rather than per-opened
instance information, you will have to maintain that yourself.

The routine should first check the device to see whether it looks like a
device that this module would handle; for example, it should begin with
one of the device name prefixes for your module and, if your devices
have instance numbers, be followed by a number.  If it is not one of
those devices, you must set the integer pointed to by the third
argument to 0, to indicate that this is *not* one of the devices for
your module, and return NULL.

If it *is* one of those devices, it should call pcap_create_common,
passing to it the error message buffer as the first argument and the
size of the per-opened instance data structure as the second argument.
If it fails, it will return NULL; you must return NULL in this case.

If it succeeds, the pcap_t pointed to by the return value has been
partially initialized, but you will need to complete the process.  It
has a "priv" member, which is a void * that points to the private data
structure attached to it; that structure has been initialized to zeroes.

What you need to set are some function pointers to your routines to
handle certain operations:

	activate_op
		the routine called when pcap_activate() is done on the
		pcap_t

	can_set_rfmon_op
		the routine called when pcap_can_set_rfmon() is done on
		the pcap_t - if your device doesn't support 802.11
		monitor mode, you can leave this as initialized by
		pcap_create_common(), as that routine will return "no,
		monitor mode isn't supported".

Once you've set the activate_op and, if necessary, the can_set_rfmon_op,
you must return the pcap_t * that was returned to you.

Your activate routine takes, as an argument, a pointer to the pcap_t
being activated, and returns an int.

The perameters set for the device in the pcap_create() call, and after
that call(), are mostly in the opt member of the pcap_t:

	device
		the name of the device

	timeout
		the buffering timeout, in milliseconds

	buffer_size
		the buffer size to use

	promisc
		1 if promiscuous mode is to be used, 0 otherwise

	rfmon
		1 if monitor mode is to be used, 0 otherwise

	immediate
		1 if the device should be in immediate mode, 0 otherwise

	nonblock
		1 if the device should be in non-blocking mode, 0
		otherwise

	tstamp_type
		the type of time stamp to supply

	tstamp_precision
		the time stamp precision to supply

The snapshot member of the pcap_t structure will contain the snapshot
length to be used.

Your routine should attempt to set up the device for capturing.  If it
fails, it must return an error indication which is one of the PCAP_ERROR
values.  For PCAP_ERROR, it must also set the errbuf member of the
pcap_t to an error string.  For PCAP_ERROR_NO_SUCH_DEVICE and
PCAP_ERROR_PERM_DENIED, it may set it to an error string providing
additional information that may be useful for debugging, or may just
leave it as a null string.

If it succeeds, it must set certain function pointers in the pcap_t
structure:

	read_op
		called whenever packets are to be read

	inject_op
		called whenever packets are to be injected

	setfilter_op
		called whenever pcap_setfilter() is called

	setdirection_op
		called whenever pcap_setdirection() is called

	set_datalink_op
		called whnever pcap_set_datalink() is called

	getnonblock_op
		called whenever pcap_getnonblock() is called

	setnonblock_op
		called whenever pcap_setnonblock() is called

	stats_op
		called whenever pcap_stats() is called

	cleanup_op
		called if the activate routine fails or pcap_close() is
		called

and must also set the linktype member to the DLT_ value for the device.

On UN*Xes, if the device supports waiting for packets to arrive with
select()/poll()/epoll()/kqueues etc., it should set the selectable_fd
member of the structure to the descriptor you would use with those
calls.  If it does not, then, if that's because the device polls for
packets rather than receiving interrupts or other signals when packets
arrive, it should have a struct timeval in the private data structure,
set the value of that struct timeval to the poll timeout, and set the
required_select_timeout member of the pcap_t to point to the struct
timeval.

The read_op routine is called when pcap_dispatch(), pcap_loop(),
pcap_next(), or pcap_next_ex() is called.  It is passed the same
arguments as pcap_dispatch() is called.

The routine should first check if the break_loop member of the pcap_t is
non-zero and, if so, set that member to zero and return
PCAP_ERROR_BREAK.

Then, if the pcap_t is in blocking mode (as opposed to non-blocking
mode), and there are no packets immediately available to be passed to
the callback, it should block waiting for packets to arrive, using the
buffering timeout, first, and read packets from the device if necessary.

Then it should loop through the available packets, calling the callback
routine for each packet:

	If the PACKET_COUNT_IS_UNLIMITED() macro evaluates to true when
	passed the packet count argument, the loop should continue until
	there are no more packets immediately available or the
	break_loop member of the pcap_t is non-zero.  If the break_loop
	member is fount to be non-zero, it should set that member to
	zero and return PCAP_ERROR_BREAK.

	If it doesn't evaluat to true, then the loop should also
	terminate if the specified number of packets have been delivered
	to the callback.

Note that there is *NO* requirement that the packet header or data
provided to the callback remain available, or valid, after the callback
routine returns; if the callback needs to save the data for other code
to use, it must make a copy of that data.  This means that the module is
free to, for example, overwrite the buffer into which it read the
packet, or release back to the kernel a packet in a memory-mapped
buffer shared between the kernel and userland, after the callback
returns.

If an error occurs when reading packets from the device, it must set the
errbuf member of the pcap_t to an error string and return PCAP_ERROR.

If no error occurs, it must return the number of packets that were
supplied to the callback routine.

The inject routine is passed a pointer to the pcap_t, a buffer
containing the contents of the packet to inject, and the number of bytes
in the packet.  If the device doesn't support packet injection, the
routine must set the errbuf member of the pcap_t to a message indicating
that packet injection isn't supported and return PCAP_ERROR.  Otherwise,
it should attempt to inject the packet; if the attempt fails, it must
set the errbuf member of the pcap_t to an error message and return
PCAP_ERROR.  Otherwise, it should return the number of bytes injected.

The setfilter routine is passed a pointer to the pcap_t and a pointer
to a struct bpf_program containing a BPF program to be used as a filter.
If the mechanism used by your module can perform filtering with a BPF
program, it would attempt to set that filter to the specified program.

If that failed because the program was too large, or used BPF features
not supported by that mechanism, the module should fall back on
filtering in userland by saving a copy of the filter with a call to
install_bpf_program(), setting a flag in the private data instructure
indicating that filtering is being done by the module and, in the read
routine's main loop, checking the flag and, if it's set, calling
pcap_filter(), passing it the fcode.bf_insns member of the pcap_t, the
raw packet data, the on-the-wire length of the packet, and the captured
length of the packet, and only passing the packet to the callback
routine, and counting it, if pcap_filter() returns a non-zero value.
(If the flag is not set, all packets should be passed to the callback
routine and counted, as the filtering is being done by the mechanism
used by the module.)  If install_bpf_program() returns a negative value,
the routine should return PCAP_ERROR.

If the attempt to set the filter failed for any other reason, the
routine must set the errbuf member of the pcap_t to an error message and
return PCAP_ERROR.

If the attempt to set the filter succeeded, or it failed because the
mechanism used by the module rejected it and the call to
install_bpf_program() succeeded, the routine should return 0.

If the mechanism the module uses doesn't support filtering, the pointer
to the setfilter routine can just be set to point to
install_bpf_program; the module does not need a routine of its own to
handle that.

The setdirection routine is passed a pointer to the pcap_t and a
pcap_direction_t indicating which packet directions should be accepted.
If the module can't arrange to handle only incoming packets or only
outgoing packets, it can set the pointer to the setdirection routine to
NULL, and calls to pcap_setdirection() will fail with an error message
indicating that setting the direction isn't supported.

XXX describe set_datalink, including what the activate routine has to do
XXX

XXX describe the rest of the routines XXX

The following instructions apply if you have a Linux or FreeBSD platform and
want libpcap to support the DAG range of passive network monitoring cards from
Endace (https://www.endace.com, see below for further contact details).

1) Install and build the DAG software distribution by following the
instructions supplied with that package. Current Endace customers can download
the DAG software distribution from https://www.endace.com

2) Configure libcap. To allow the 'configure' script to locate the DAG
software distribution use the '--with-dag' option:

        ./configure --with-dag=DIR

Where DIR is the root of the DAG software distribution, for example
/var/src/dag. If the DAG software is correctly detected 'configure' will
report:

        checking whether we have DAG API... yes

If 'configure' reports that there is no DAG API, the directory may have been
incorrectly specified or the DAG software was not built before configuring
libpcap.

See also the libpcap INSTALL.txt file for further libpcap configuration
options.

Building libpcap at this stage will include support for both the native packet
capture stream (linux or bpf) and for capturing from DAG cards. To build
libpcap with only DAG support specify the capture type as 'dag' when
configuring libpcap:

        ./configure --with-dag=DIR --with-pcap=dag

Applications built with libpcap configured in this way will only detect DAG
cards and will not capture from the native OS packet stream.

----------------------------------------------------------------------

Libpcap when built for DAG cards against dag-2.5.1 or later releases:

Timeouts are supported. pcap_dispatch() will return after to_ms milliseconds
regardless of how many packets are received. If to_ms is zero pcap_dispatch()
will block waiting for data indefinitely.

pcap_dispatch() will block on and process a minimum of 64kB of data (before
filtering) for efficiency. This can introduce high latencies on quiet
interfaces unless a timeout value is set. The timeout expiring will override
the 64kB minimum causing pcap_dispatch() to process any available data and
return.

pcap_setnonblock is supported. When nonblock is set, pcap_dispatch() will
check once for available data, process any data available up to count, then
return immediately.

pcap_findalldevs() is supported, e.g. dag0, dag1...

Some DAG cards can provide more than one 'stream' of received data.
This can be data from different physical ports, or separated by filtering
or load balancing mechanisms. Receive streams have even numbers, e.g.
dag0:0, dag0:2 etc. Specifying transmit streams for capture is not supported.

pcap_setfilter() is supported, BPF programs run in userspace.

pcap_setdirection() is not supported. Only received traffic is captured.
DAG cards normally do not have IP or link layer addresses assigned as
they are used to passively monitor links.

pcap_breakloop() is supported.

pcap_datalink() and pcap_list_datalinks() are supported. The DAG card does
not attempt to set the correct datalink type automatically where more than
one type is possible.

pcap_stats() is supported. ps_drop is the number of packets dropped due to
RX stream buffer overflow, this count is before filters are applied (it will
include packets that would have been dropped by the filter). The RX stream
buffer size is user configurable outside libpcap, typically 16-512MB.

pcap_get_selectable_fd() is not supported, as DAG cards do not support
poll/select methods.

pcap_inject() and pcap_sendpacket() are not supported.

Some DAG cards now support capturing to multiple virtual interfaces, called
streams. Capture streams have even numbers. These are available via libpcap
as separate interfaces, e.g. dag0:0, dag0:2, dag0:4 etc. dag0:0 is the same
as dag0. These are visible via pcap_findalldevs().

libpcap now does NOT set the card's hardware snaplen (slen). This must now be
set using the appropriate DAG configuration program, e.g. dagthree, dagfour,
dagsix, dagconfig. This is because the snaplen is currently shared between
all of the streams. In future this may change if per-stream slen is
implemented.

DAG cards by default capture entire packets including the L2
CRC/FCS. If the card is not configured to discard the CRC/FCS, this
can confuse applications that use libpcap if they're not prepared for
packets to have an FCS.

Libpcap now reads the environment variable ERF_FCS_BITS to determine
how many bits of CRC/FCS to strip from the end of the captured
frame. This defaults to 32 for use with Ethernet. If the card is
configured to strip the CRC/FCS, then set ERF_FCS_BITS=0. If used with
a HDLC/PoS/PPP/Frame Relay link with 16 bit CRC/FCS, then set
ERF_FCS_BITS=16.

If you wish to create a pcap file that DOES contain the Ethernet FCS,
specify the environment variable ERF_DONT_STRIP_FCS. This will cause
the existing FCS to be captured into the pcap file. Note some
applications may incorrectly report capture errors or oversize packets
when reading these files.

----------------------------------------------------------------------

Please submit bug reports via <support@endace.com>.

Please also visit our Web site at:

        https://www.endace.com/

For more information about Endace DAG cards contact <sales@endace.com>.

For HP-UX 11i (11.11) and later, there are no known issues with
promiscuous mode under HP-UX.  If you are using a earlier version of
HP-UX and cannot upgrade, please continue reading.

HP-UX patches to fix packet capture problems

Note that packet-capture programs such as tcpdump may, on HP-UX, not be
able to see packets sent from the machine on which they're running.
Some articles on groups.google.com discussing this are:

	https://groups.google.com/groups?selm=82ld3v%2480i%241%40mamenchi.zrz.TU-Berlin.DE

which says:

  Newsgroups: comp.sys.hp.hpux
  Subject:  Re: Did someone made tcpdump working on 10.20 ?
  Date: 12/08/1999
  From: Lutz Jaenicke <jaenicke@emserv1.ee.TU-Berlin.DE>

  In article <82ks5i$5vc$1@news1.dti.ne.jp>, mtsat <mtsat@iris.dti.ne.jp>
  wrote:
   >Hello,
   >
   >I downloaded and compiled tcpdump3.4 a couple of week ago. I tried to use
   >it, but I can only see incoming data, never outgoing.
   >Someone (raj) explained me that a patch was missing, and that this patch
   >must me "patched" (poked) in order to see outbound data in promiscuous mode.
   >Many things to do .... So the question is : did someone has already this
   >"ready to use" PHNE_**** patch ?

   Two things:
   1. You do need a late "LAN products cumulative patch" (e.g.  PHNE_18173
  for   s700/10.20).
   2. You must use
echo 'lanc_outbound_promisc_flag/W1' | /usr/bin/adb -w /stand/vmunix /dev/kmem
     You can insert this e.g. into /sbin/init.d/lan

   Best regards,
   Lutz

and

	http://groups.google.com/groups?selm=88cf4t%24p03%241%40web1.cup.hp.com

which says:

  Newsgroups: comp.sys.hp.hpux
  Subject: Re: tcpdump only shows incoming packets
  Date: 02/15/2000
  From: Rick Jones <foo@bar.baz.invalid>

  Harald Skotnes <harald@cc.uit.no> wrote:
  > I am running HPUX 11.0 on a C200 hanging on a 100Mb switch. I have
  > compiled libpcap-0.4 an tcpdump-3.4 and it seems to work. But at a
  > closer look I only get to see the incoming packets not the
  > outgoing. I have tried tcpflow-0.12 which also uses libpcap and the
  > same thing happens.  Could someone please give me a hint on how to
  > get this right?

  Search/Read the archives ?-)

  What you are seeing is expected, un-patched, behaviour for an HP-UX
  system.  On 11.00, you need to install the latest lancommon/DLPI
  patches, and then the latest driver patch for the interface(s) in use.
  At that point, a miracle happens and you should start seeing outbound
  traffic.

[That article also mentions the patch that appears below.]

and

	https://groups.google.com/groups?selm=38AA973E.96BE7DF7%40cc.uit.no

which says:

  Newsgroups: comp.sys.hp.hpux
  Subject: Re: tcpdump only shows incoming packets
  Date: 02/16/2000
  From: Harald Skotnes <harald@cc.uit.no>

  Rick Jones wrote:

	...

  > What you are seeing is expected, un-patched, behaviour for an HP-UX
  > system. On 11.00, you need to install the latest lancommon/DLPI
  > patches, and then the latest driver patch for the interface(s) in
  > use. At that point, a miracle happens and you should start seeing
  > outbound traffic.

  Thanks a lot.  I have this problem on several machines running HPUX
  10.20 and 11.00.  The machines where patched up before y2k so did not
  know what to think.  Anyway I have now installed PHNE_19766,
  PHNE_19826, PHNE_20008, PHNE_20735 on the C200 and now I can see the
  outbound traffic too.  Thanks again.

(although those patches may not be the ones to install - there may be
later patches).

And another message to tcpdump-workers@tcpdump.org, from Rick Jones:

  Date: Mon, 29 Apr 2002 15:59:55 -0700
  From: Rick Jones
  To: tcpdump-workers@tcpdump.org
  Subject: Re: [tcpdump-workers] I Can't Capture the Outbound Traffic

	...

  http://itrc.hp.com/ would be one place to start in a search for the most
  up-to-date patches for DLPI and the lan driver(s) used on your system (I
  cannot guess because 9000/800 is too generic - one hs to use the "model"
  command these days and/or an ioscan command (see manpage) to guess what
  the drivers (btlan[3456], gelan, etc) might be involved in addition to
  DLPI.

  Another option is to upgrade to 11i as outbound promiscuous mode support
  is there in the base OS, no patches required.

Another posting:

	https://groups.google.com/groups?selm=7d6gvn%24b3%241%40ocean.cup.hp.com

indicates that you need to install the optional STREAMS product to do
captures on HP-UX 9.x:

  Newsgroups: comp.sys.hp.hpux
  Subject:  Re: tcpdump HP/UX 9.x
  Date: 03/22/1999
  From: Rick Jones <foo@bar.baz>

  Dave Barr (barr@cis.ohio-state.edu) wrote:
  : Has anyone ported tcpdump (or something similar) to HP/UX 9.x?

  I'm reasonably confident that any port of tcpdump to 9.X would require
  the (then optional) STREAMS product.  This would bring DLPI, which is
  what one uses to access interfaces in promiscuous mode.

  I'm not sure that HP even sells the 9.X STREAMS product any longer,
  since HP-UX 9.X is off the pricelist (well, maybe 9.10 for the old 68K
  devices).

  Your best bet is to be up on 10.20 or better if that is at all
  possible.  If your hardware is supported by it, I'd go with HP-UX 11.
  If you want to see the system's own outbound traffic, you'll never get
  that functionality on 9.X, but it might happen at some point for 10.20
  and 11.X.

  rick jones

(as per other messages cited here, the ability to see the system's own
outbound traffic did happen).

Rick Jones reports that HP-UX 11i needs no patches for outbound
promiscuous mode support.

An additional note, from Jost Martin, for HP-UX 10.20:

	Q: How do I get ethereral on HPUX to capture the _outgoing_ packets
	   of an interface
	A: You need to get PHNE_20892,PHNE_20725 and PHCO_10947 (or
	   newer, this is as of 4.4.00) and its dependencies.  Then you can
	   enable the feature as described below:

	Patch Name: PHNE_20892
	Patch Description: s700 10.20 PCI 100Base-T cumulative patch
		To trace the outbound packets, please do the following
		to turn on a global promiscuous switch before running
		the promiscuous applications like snoop or tcpdump:

		adb -w /stand/vmunix /dev/mem
		lanc_outbound_promisc_flag/W 1
		(adb will echo the result showing that the flag has
		been changed)
		$quit
	(Thanks for this part to HP-support, Ratingen)

		The attached hack does this and some security-related stuff
	(thanks to hildeb@www.stahl.bau.tu-bs.de (Ralf Hildebrandt) who
	posted the security-part some time ago)

		 <<hack_ip_stack>>

		(Don't switch IP-forwarding off, if you need it !)
		Install the hack as /sbin/init.d/hacl_ip_stack (adjust
	permissions !) and make a sequencing-symlink
	/sbin/rc2.d/S350hack_ip_stack pointing to this script.
		Now all this is done on every reboot.

According to Rick Jones, the global promiscuous switch also has to be
turned on for HP-UX 11.00, but not for 11i - and, in fact, the switch
doesn't even exist on 11i.

Here's the "hack_ip_stack" script:

-----------------------------------Cut Here-------------------------------------
#!/sbin/sh
#
# nettune:  hack kernel parms for safety

OKAY=0
ERROR=-1

# /usr/contrib/bin fuer nettune auf Pfad
PATH=/sbin:/usr/sbin:/usr/bin:/usr/contrib/bin
export PATH


##########
#  main  #
##########

case $1 in
   start_msg)
      print "Tune IP-Stack for security"
      exit $OKAY
      ;;

   stop_msg)
      print "This action is not applicable"
      exit $OKAY
      ;;

   stop)
      exit $OKAY
      ;;

   start)
      ;;  # fall through

   *)
      print "USAGE: $0 {start_msg | stop_msg | start | stop}" >&2
      exit $ERROR
      ;;
   esac

###########
#  start  #
###########

#
# tcp-Sequence-Numbers nicht mehr inkrementieren sondern random
# Syn-Flood-Protection an
# ip_forwarding aus
# Source-Routing aus
# Ausgehende Packets an ethereal/tcpdump etc.

/usr/contrib/bin/nettune -s tcp_random_seq 2 || exit $ERROR
/usr/contrib/bin/nettune -s hp_syn_protect 1 || exit $ERROR
/usr/contrib/bin/nettune -s ip_forwarding 0 || exit $ERROR
echo 'ip_block_source_routed/W1' | /usr/bin/adb -w /stand/vmunix /dev/kmem || exit $ERROR
echo 'lanc_outbound_promisc_flag/W 1' | adb -w /stand/vmunix /dev/mem  || exit $ERROR

exit $OKAY
-----------------------------------Cut Here-------------------------------------

Currently, libpcap supports packet capturing on Linux 2.6.27 and later;
earlier versions are not supported.

You must configure 2.26.x kernels with the CONFIG_PACKET_MMAP option for
this protocol.  3.x and later kernels do not require that.

Note that, by default, libpcap will, if libnl is present, build with it;
it uses libnl to support monitor mode on mac80211 devices.  There is a
configuration option to disable building with libnl, but, if that option
is chosen, the monitor-mode APIs (as used by tcpdump's "-I" flag, and as
will probably be used by other applications in the future) won't work
properly on mac80211 devices.

Linux's run-time linker allows shared libraries to be linked with other
shared libraries, which means that if an older version of a shared
library doesn't require routines from some other shared library, and a
later version of the shared library does require those routines, the
later version of the shared library can be linked with that other shared
library and, if it's otherwise binary-compatible with the older version,
can replace that older version without breaking applications built with
the older version, and without breaking configure scripts or the build
procedure for applications whose configure script doesn't use the
pcap-config script if they build with the shared library.  (The build
procedure for applications whose configure scripts use the pcap-config
script if present will not break even if they build with the static
library.)

Statistics:
Statistics reported by pcap are platform specific.  The statistics
reported by pcap_stats on Linux are as follows:

ps_recv   Number of packets that were accepted by the pcap filter
ps_drop   Number of packets that had passed filtering but were not
          passed on to pcap due to things like buffer shortage, etc.
          This is useful because these are packets you are interested in
          but won't be reported by, for example, tcpdump output.

As with other systems using BPF, macOS allows users with read access to
the BPF devices to capture packets with libpcap and allows users with
write access to the BPF devices to send packets with libpcap.

On some systems that use BPF, the BPF devices live on the root file
system, and the permissions and/or ownership on those devices can be
changed to give users other than root permission to read or write those
devices.

On newer versions of FreeBSD, the BPF devices live on devfs, and devfs
can be configured to set the permissions and/or ownership of those
devices to give users other than root permission to read or write those
devices.

On macOS, the BPF devices live on devfs, but the macOS version of devfs
is based on an older (non-default) FreeBSD devfs, and that version of
devfs cannot be configured to set the permissions and/or ownership of
those devices.

Therefore, we supply:

	a "startup item" for older versions of macOS;

	a launchd daemon for Tiger and later versions of macOS;

Both of them will change the ownership of the BPF devices so that the
"admin" group owns them, and will change the permission of the BPF
devices to rw-rw----, so that all users in the "admin" group - i.e., all
users with "Allow user to administer this computer" turned on - have
both read and write access to them.

The startup item is in the ChmodBPF directory in the source tree.  A
/Library/StartupItems directory should be created if it doesn't already
exist, and the ChmodBPF directory should be copied to the
/Library/StartupItems directory (copy the entire directory, so that
there's a /Library/StartupItems/ChmodBPF directory, containing all the
files in the source tree's ChmodBPF directory; don't copy the individual
items in that directory to /Library/StartupItems).  The ChmodBPF
directory, and all files under it, must be owned by root.  Installing
the files won't immediately cause the startup item to be executed; it
will be executed on the next reboot.  To change the permissions before
the reboot, run

	sudo SystemStarter start ChmodBPF

The launchd daemon is the chmod_bpf script, plus the
org.tcpdump.chmod_bpf.plist launchd plist file.  chmod_bpf should be
installed in /usr/local/bin/chmod_bpf, and org.tcpdump.chmod_bpf.plist
should be installed in /Library/LaunchDaemons.  chmod_bpf, and
org.tcpdump.chmod_bpf.plist, must be owned by root.  Installing the
script and plist file won't immediately cause the script to be executed;
it will be executed on the next reboot.  To change the permissions
before the reboot, run

	sudo /usr/local/bin/chmod_bpf

or

	sudo launchctl load /Library/LaunchDaemons/org.tcpdump.chmod_bpf.plist

If you want to give a particular user permission to access the BPF
devices, rather than giving all administrative users permission to
access them, you can have the ChmodBPF/ChmodBPF script change the
ownership of /dev/bpf* without changing the permissions.  If you want to
give a particular user permission to read and write the BPF devices and
give the administrative users permission to read but not write the BPF
devices, you can have the script change the owner to that user, the
group to "admin", and the permissions to rw-r-----.  Other possibilities
are left as an exercise for the reader.

(NOTE: due to a bug in Snow Leopard, if you change the permissions not
to grant write permission to everybody who should be allowed to capture
traffic, non-root users who cannot open the BPF devices for writing will
not be able to capture outgoing packets.)

The following instructions apply if you have a Linux platform and want
libpcap to support the Septel range of passive network monitoring cards
from Intel (https://www.intel.com)

1) Install and build the Septel software distribution by following the
instructions supplied with that package.

2) Configure libcap. To allow the 'configure' script to locate the Septel
software distribution use the '--with-septel' option:

        ./configure --with-septel=DIR

where DIR is the root of the Septel software distribution, for example
/var/src/septel.

By default (if you write only ./configure --with-septel) it takes
./../septel as argument for DIR.

If the Septel software is correctly detected 'configure' will
report:

        checking whether we have Septel API... yes

If 'configure' reports that there is no Septel API, the directory may have been
incorrectly specified or the Septel software was not built before configuring
libpcap.

See also the libpcap INSTALL.txt file for further libpcap configuration
options.

Building libpcap at this stage will include support for both the native
packet capture stream and for capturing from Septel cards.  To build
libpcap with only Septel support specify the capture type as 'septel'
when configuring libpcap:

        ./configure --with-septel=DIR --with-pcap=septel

Applications built with libpcap configured in this way will only detect Septel
cards and will not capture from the native OS packet stream.

Note: As mentioned in pcap-septel.c we should first edit the system.txt
file to change the user part example (UPE) module id to 0xdd instead of
0x2d for technical reason.  So this change in system.txt is crucial and
things will go wrong if it's not done.  System.txt along with config.txt
are configuration files that are edited by the user before running the
gctload program that uses these files for initialising modules and
configuring parameters.

----------------------------------------------------------------------
for more information please contact me : gil_hoyek@hotmail.com

NOTE: this is not currently supported; the configure script doesn't
support --with-sita, and CMake doesn't support enabling SITA ACN
support.  The code currently does not compile; it should really be
implemented as an additional remote capture mechanism, using a URL,
rather than as a separate version of libpcap that supports only the ACN
product, but the infrastructure for that isn't yet available.

The following instructions apply if you have a Linux platform and want
libpcap to support the 'ACN' WAN/LAN router product from SITA
(https://www.sita.aero)

This might also work on non-Linux Unix-compatible platforms, but that
has not been tested.

See also the libpcap INSTALL.txt file for further libpcap configuration
options.

These additions/extensions have been made to PCAP to allow it to
capture packets from a SITA ACN device (and potentially others).

To enable its support you need to ensure that the distribution has
a correct configure.ac file; that can be created if necessary by
using the normal autoconf procedure of:

aclocal
autoconf
autoheader
automake

Then run configure with the 'sita' option:

./configure --with-sita

Applications built with libpcap configured in this way will only detect SITA
ACN interfaces and will not capture from the native OS packet stream.

The SITA extension provides a remote datascope operation for capturing
both WAN and LAN protocols.  It effectively splits the operation of
PCAP into two halves.  The top layer performs the majority of the
work, but interfaces via a TCP session to remote agents that
provide the lower layer functionality of actual sniffing and
filtering. More detailed information regarding the functions and
inter-device protocol and naming conventions are described in detail
in 'pcap-sita.html'.

pcap_findalldevs() reads the local system's /etc/hosts file looking
for host names that match the format of IOP type devices.  ie.  aaa_I_x_y
and then queries each associated IP address for a list of its WAN and
LAN devices.  The local system the aggregates the lists obtained from
each IOP, sorts it, and provides it (to Wireshark et.al) as the
list of monitorable interfaces.

Once a valid interface has been selected, pcap_open() is called
which opens a TCP session (to a well known port) on the target IOP
and tells it to start monitoring.

All captured packets are then forwarded across that TCP session
back to the local 'top layer' for forwarding to the actual
sniffing program (wireshark...)

Note that the DLT_SITA link-layer type includes a proprietary header
that is documented as part of the SITA dissector of Wireshark and is
also described in 'pcap-sita.html' for posterity sake.

That header provides:
- Packet direction (in/out) (1 octet)
- Link layer hardware signal status (1 octet)
- Transmit/Receive error status (2 octets)
- Encapsulated WAN protocol ID (1 octet)

The following instructions are applicable to Tru64 UNIX
(formerly Digital UNIX (formerly DEC OSF/1)) version 4.0, and
probably to later versions as well; at least some options apply to
Digital UNIX 3.2 - perhaps all do.

In order to use kernel packet filtering on this system, you have
to configure it in such a way:

Kernel configuration
--------------------

The packet filtering kernel option must be enabled at kernel
installation.  If it was not the case, you can rebuild the kernel with
"doconfig -c" after adding the following line in the kernel
configuration file (/sys/conf/<HOSTNAME>):

	option PACKETFILTER

or use "doconfig" without any arguments to add the packet filter driver
option via the kernel option menu (see the system administration
documentation for information on how to do this).

Device configuration
--------------------

Devices used for packet filtering must be created thanks to
the following command (executed in the /dev directory):

	./MAKEDEV pfilt

Interface configuration
-----------------------

In order to capture all packets on a network, you may want to allow
applications to put the interface on that network into "local copy"
mode, so that tcpdump can see packets sent by the host on which it's
running as well as packets received by that host, and to put the
interface into "promiscuous" mode, so that tcpdump can see packets on
the network segment not sent to the host on which it's running, by using
the pfconfig(1) command:

	pfconfig +c +p <network_device>

or allow application to put any interface into "local copy" or
"promiscuous" mode by using the command:

	pfconfig +c +p -a

Note: all instructions given require root privileges.