README.aix
1# Compiling libpcap on AIX
2
3* Autoconf is expected to work everywhere.
4* Neither AIX lex nor AIX yacc nor AIX m4 are suitable.
5
6## AIX 7.1
7
8* libpcap build fails with rpcapd enabled.
9* GNU M4 1.4.17 works.
10* flex 2.6.4 and GNU Bison 3.5.1 work.
11* CMake 3.16.0 works.
12* GCC 8.3.0 works, XL C 12.1.0 works.
13
14## AIX 7.2
15
16* libpcap build fails with rpcapd enabled.
17* GNU M4 1.4.17 works.
18* flex 2.5.35 and GNU Bison 3.0.4 work.
19* GCC 7.2.0 works, XL C 13.1.3 works.
20
21## Other AIX-related information
22
23Using BPF:
24
25(1) AIX 4.x's version of BPF is undocumented and somewhat unstandard; the
26 current BPF support code includes changes that should work around
27 that; it appears to compile and work on at least one AIX 4.3.3
28 machine.
29
30 Note that the BPF driver and the "/dev/bpf" devices might not exist
31 on your machine; AIX's tcpdump loads the driver and creates the
32 devices if they don't already exist. Our libpcap should do the
33 same, and the configure script should detect that it's on an AIX
34 system and choose BPF even if the devices aren't there.
35
36 Also note that tcpdump _binary_ compiled on AIX 4 may have a problem
37 doing the initial loading of the BPF driver if copied to AIX 5 and
38 run there (GH #52). tcpdump binary natively compiled on AIX 5 should
39 not have this issue.
40
41(2) If libpcap doesn't compile on your machine when configured to use
42 BPF, or if the workarounds fail to make it work correctly, you
43 should send to tcpdump-workers@lists.tcpdump.org a detailed bug
44 report (if the compile fails, send us the compile error messages;
45 if it compiles but fails to work correctly, send us as detailed as
46 possible a description of the symptoms, including indications of the
47 network link-layer type being wrong or time stamps being wrong).
48
49 If you fix the problems yourself, please submit a patch by forking
50 the branch at
51
52 https://github.com/the-tcpdump-group/libpcap/tree/master
53
54 and issuing a pull request, so we can incorporate the fixes into the
55 next release.
56
57 If you don't fix the problems yourself, you can, as a workaround,
58 make libpcap use DLPI instead of BPF.
59
60 This can be done by specifying the flag:
61
62 --with-pcap=dlpi
63
64 to the "configure" script for libpcap.
65
66If you use DLPI:
67
68(1) It is a good idea to have the latest version of the DLPI driver on
69 your system, since certain versions may be buggy and cause your AIX
70 system to crash. DLPI is included in the fileset bos.rte.tty. I
71 found that the DLPI driver that came with AIX 4.3.2 was buggy, and
72 had to upgrade to bos.rte.tty 4.3.2.4:
73
74 lslpp -l bos.rte.tty
75
76 bos.rte.tty 4.3.2.4 COMMITTED Base TTY Support and Commands
77
78 Updates for AIX filesets can be obtained from:
79 ftp://service.software.ibm.com/aix/fixes/
80
81 These updates can be installed with the smit program.
82
83(2) After compiling libpcap, you need to make sure that the DLPI driver
84 is loaded. Type:
85
86 strload -q -d dlpi
87
88 If the result is:
89
90 dlpi: yes
91
92 then the DLPI driver is loaded correctly.
93
94 If it is:
95
96 dlpi: no
97
98 Then you need to type:
99
100 strload -f /etc/dlpi.conf
101
102 Check again with strload -q -d dlpi that the dlpi driver is loaded.
103
104 Alternatively, you can uncomment the lines for DLPI in
105 /etc/pse.conf and reboot the machine; this way DLPI will always
106 be loaded when you boot your system.
107
108(3) There appears to be a problem in the DLPI code in some versions of
109 AIX, causing a warning about DL_PROMISC_MULTI failing; this might
110 be responsible for DLPI not being able to capture outgoing packets.
111
README.dag
1
2The following instructions apply if you have a Linux or FreeBSD platform and
3want libpcap to support the DAG range of passive network monitoring cards from
4Endace (https://www.endace.com, see below for further contact details).
5
61) Install and build the DAG software distribution by following the
7instructions supplied with that package. Current Endace customers can download
8the DAG software distribution from https://www.endace.com
9
102) Configure libcap. To allow the 'configure' script to locate the DAG
11software distribution use the '--with-dag' option:
12
13 ./configure --with-dag=DIR
14
15Where DIR is the root of the DAG software distribution, for example
16/var/src/dag. If the DAG software is correctly detected 'configure' will
17report:
18
19 checking whether we have DAG API... yes
20
21If 'configure' reports that there is no DAG API, the directory may have been
22incorrectly specified or the DAG software was not built before configuring
23libpcap.
24
25See also the libpcap INSTALL.md file for further libpcap configuration
26options.
27
28Building libpcap at this stage will include support for both the native packet
29capture stream (linux or bpf) and for capturing from DAG cards. To build
30libpcap with only DAG support specify the capture type as 'dag' when
31configuring libpcap:
32
33 ./configure --with-dag=DIR --with-pcap=dag
34
35Applications built with libpcap configured in this way will only detect DAG
36cards and will not capture from the native OS packet stream.
37
38----------------------------------------------------------------------
39
40Libpcap when built for DAG cards against dag-2.5.1 or later releases:
41
42Timeouts are supported. pcap_dispatch() will return after to_ms milliseconds
43regardless of how many packets are received. If to_ms is zero pcap_dispatch()
44will block waiting for data indefinitely.
45
46pcap_dispatch() will block on and process a minimum of 64kB of data (before
47filtering) for efficiency. This can introduce high latencies on quiet
48interfaces unless a timeout value is set. The timeout expiring will override
49the 64kB minimum causing pcap_dispatch() to process any available data and
50return.
51
52pcap_setnonblock is supported. When nonblock is set, pcap_dispatch() will
53check once for available data, process any data available up to count, then
54return immediately.
55
56pcap_findalldevs() is supported, e.g. dag0, dag1...
57
58Some DAG cards can provide more than one 'stream' of received data.
59This can be data from different physical ports, or separated by filtering
60or load balancing mechanisms. Receive streams have even numbers, e.g.
61dag0:0, dag0:2 etc. Specifying transmit streams for capture is not supported.
62
63pcap_setfilter() is supported, BPF programs run in userspace.
64
65pcap_setdirection() is not supported. Only received traffic is captured.
66DAG cards normally do not have IP or link layer addresses assigned as
67they are used to passively monitor links.
68
69pcap_breakloop() is supported.
70
71pcap_datalink() and pcap_list_datalinks() are supported. The DAG card does
72not attempt to set the correct datalink type automatically where more than
73one type is possible.
74
75pcap_stats() is supported. ps_drop is the number of packets dropped due to
76RX stream buffer overflow, this count is before filters are applied (it will
77include packets that would have been dropped by the filter). The RX stream
78buffer size is user configurable outside libpcap, typically 16-512MB.
79
80pcap_get_selectable_fd() is not supported, as DAG cards do not support
81poll/select methods.
82
83pcap_inject() and pcap_sendpacket() are not supported.
84
85Some DAG cards now support capturing to multiple virtual interfaces, called
86streams. Capture streams have even numbers. These are available via libpcap
87as separate interfaces, e.g. dag0:0, dag0:2, dag0:4 etc. dag0:0 is the same
88as dag0. These are visible via pcap_findalldevs().
89
90libpcap now does NOT set the card's hardware snaplen (slen). This must now be
91set using the appropriate DAG configuration program, e.g. dagthree, dagfour,
92dagsix, dagconfig. This is because the snaplen is currently shared between
93all of the streams. In future this may change if per-stream slen is
94implemented.
95
96DAG cards by default capture entire packets including the L2
97CRC/FCS. If the card is not configured to discard the CRC/FCS, this
98can confuse applications that use libpcap if they're not prepared for
99packets to have an FCS.
100
101Libpcap now reads the environment variable ERF_FCS_BITS to determine
102how many bits of CRC/FCS to strip from the end of the captured
103frame. This defaults to 32 for use with Ethernet. If the card is
104configured to strip the CRC/FCS, then set ERF_FCS_BITS=0. If used with
105a HDLC/PoS/PPP/Frame Relay link with 16 bit CRC/FCS, then set
106ERF_FCS_BITS=16.
107
108If you wish to create a pcap file that DOES contain the Ethernet FCS,
109specify the environment variable ERF_DONT_STRIP_FCS. This will cause
110the existing FCS to be captured into the pcap file. Note some
111applications may incorrectly report capture errors or oversize packets
112when reading these files.
113
114----------------------------------------------------------------------
115
116Please submit bug reports via <support@endace.com>.
117
118Please also visit our Web site at:
119
120 https://www.endace.com/
121
122For more information about Endace DAG cards contact <sales@endace.com>.
123
README.linux
1Currently, libpcap supports packet capturing on Linux 2.6.27 and later;
2earlier versions are not supported.
3
4You must configure 2.6.x kernels with the CONFIG_PACKET_MMAP option for
5this protocol. 3.x and later kernels do not require that.
6
7Note that, by default, libpcap will, if libnl is present, build with it;
8it uses libnl to support monitor mode on mac80211 devices. There is a
9configuration option to disable building with libnl, but, if that option
10is chosen, the monitor-mode APIs (as used by tcpdump's "-I" flag, and as
11will probably be used by other applications in the future) won't work
12properly on mac80211 devices.
13
14Linux's run-time linker allows shared libraries to be linked with other
15shared libraries, which means that if an older version of a shared
16library doesn't require routines from some other shared library, and a
17later version of the shared library does require those routines, the
18later version of the shared library can be linked with that other shared
19library and, if it's otherwise binary-compatible with the older version,
20can replace that older version without breaking applications built with
21the older version, and without breaking configure scripts or the build
22procedure for applications whose configure script doesn't use the
23pcap-config script if they build with the shared library. (The build
24procedure for applications whose configure scripts use the pcap-config
25script if present will not break even if they build with the static
26library.)
27
28Statistics:
29Statistics reported by pcap are platform specific. The statistics
30reported by pcap_stats on Linux are as follows:
31
32ps_recv Number of packets that were accepted by the pcap filter
33ps_drop Number of packets that had passed filtering but were not
34 passed on to pcap due to things like buffer shortage, etc.
35 This is useful because these are packets you are interested in
36 but won't be reported by, for example, tcpdump output.
37
README.macos
1As with other systems using BPF, macOS allows users with read access to
2the BPF devices to capture packets with libpcap and allows users with
3write access to the BPF devices to send packets with libpcap.
4
5On some systems that use BPF, the BPF devices live on the root file
6system, and the permissions and/or ownership on those devices can be
7changed to give users other than root permission to read or write those
8devices.
9
10On newer versions of FreeBSD, the BPF devices live on devfs, and devfs
11can be configured to set the permissions and/or ownership of those
12devices to give users other than root permission to read or write those
13devices.
14
15On macOS, the BPF devices live on devfs, but the macOS version of devfs
16is based on an older (non-default) FreeBSD devfs, and that version of
17devfs cannot be configured to set the permissions and/or ownership of
18those devices.
19
20Therefore, 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
26Both 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
28devices to rw-rw----, so that all users in the "admin" group - i.e., all
29users with "Allow user to administer this computer" turned on - have
30both read and write access to them.
31
32The startup item is in the ChmodBPF directory in the source tree. A
33/Library/StartupItems directory should be created if it doesn't already
34exist, and the ChmodBPF directory should be copied to the
35/Library/StartupItems directory (copy the entire directory, so that
36there's a /Library/StartupItems/ChmodBPF directory, containing all the
37files in the source tree's ChmodBPF directory; don't copy the individual
38items in that directory to /Library/StartupItems). The ChmodBPF
39directory, and all files under it, must be owned by root. Installing
40the files won't immediately cause the startup item to be executed; it
41will be executed on the next reboot. To change the permissions before
42the reboot, run
43
44 sudo SystemStarter start ChmodBPF
45
46The launchd daemon is the chmod_bpf script, plus the
47org.tcpdump.chmod_bpf.plist launchd plist file. chmod_bpf should be
48installed in /usr/local/bin/chmod_bpf, and org.tcpdump.chmod_bpf.plist
49should be installed in /Library/LaunchDaemons. chmod_bpf, and
50org.tcpdump.chmod_bpf.plist, must be owned by root. Installing the
51script and plist file won't immediately cause the script to be executed;
52it will be executed on the next reboot. To change the permissions
53before the reboot, run
54
55 sudo /usr/local/bin/chmod_bpf
56
57or
58
59 sudo launchctl load /Library/LaunchDaemons/org.tcpdump.chmod_bpf.plist
60
61If you want to give a particular user permission to access the BPF
62devices, rather than giving all administrative users permission to
63access them, you can have the ChmodBPF/ChmodBPF script change the
64ownership of /dev/bpf* without changing the permissions. If you want to
65give a particular user permission to read and write the BPF devices and
66give the administrative users permission to read but not write the BPF
67devices, you can have the script change the owner to that user, the
68group to "admin", and the permissions to rw-r-----. Other possibilities
69are left as an exercise for the reader.
70
71(NOTE: due to a bug in Snow Leopard, if you change the permissions not
72to grant write permission to everybody who should be allowed to capture
73traffic, non-root users who cannot open the BPF devices for writing will
74not be able to capture outgoing packets.)
75
README.septel
1The following instructions apply if you have a Linux platform and want
2libpcap to support the Septel range of passive network monitoring cards
3from Intel (https://www.intel.com)
4
51) Install and build the Septel software distribution by following the
6instructions supplied with that package.
7
82) Configure libcap. To allow the 'configure' script to locate the Septel
9software distribution use the '--with-septel' option:
10
11 ./configure --with-septel=DIR
12
13where DIR is the root of the Septel software distribution, for example
14/var/src/septel.
15
16By default (if you write only ./configure --with-septel) it takes
17./../septel as argument for DIR.
18
19If the Septel software is correctly detected 'configure' will
20report:
21
22 checking whether we have Septel API... yes
23
24If 'configure' reports that there is no Septel API, the directory may have been
25incorrectly specified or the Septel software was not built before configuring
26libpcap.
27
28See also the libpcap INSTALL.md file for further libpcap configuration
29options.
30
31Building libpcap at this stage will include support for both the native
32packet capture stream and for capturing from Septel cards. To build
33libpcap with only Septel support specify the capture type as 'septel'
34when configuring libpcap:
35
36 ./configure --with-septel=DIR --with-pcap=septel
37
38Applications built with libpcap configured in this way will only detect Septel
39cards and will not capture from the native OS packet stream.
40
41Note: As mentioned in pcap-septel.c we should first edit the system.txt
42file to change the user part example (UPE) module id to 0xdd instead of
430x2d for technical reason. So this change in system.txt is crucial and
44things will go wrong if it's not done. System.txt along with config.txt
45are configuration files that are edited by the user before running the
46gctload program that uses these files for initialising modules and
47configuring parameters.
48
49----------------------------------------------------------------------
50for more information please contact me : gil_hoyek@hotmail.com
51
README.sita
1NOTE: this is not currently supported; the configure script doesn't
2support --with-sita, and CMake doesn't support enabling SITA ACN
3support. The code currently does not compile; it should really be
4implemented as an additional remote capture mechanism, using a URL,
5rather than as a separate version of libpcap that supports only the ACN
6product, but the infrastructure for that isn't yet available.
7
8The following instructions apply if you have a Linux platform and want
9libpcap to support the 'ACN' WAN/LAN router product from SITA
10(https://www.sita.aero)
11
12This might also work on non-Linux Unix-compatible platforms, but that
13has not been tested.
14
15See also the libpcap INSTALL.md file for further libpcap configuration
16options.
17
18These additions/extensions have been made to PCAP to allow it to
19capture packets from a SITA ACN device (and potentially others).
20
21To enable its support you need to ensure that the distribution has
22a correct configure.ac file; that can be created if necessary by
23using the normal autoconf procedure of:
24
25aclocal
26autoconf
27autoheader
28automake
29
30Then run configure with the 'sita' option:
31
32./configure --with-sita
33
34Applications built with libpcap configured in this way will only detect SITA
35ACN interfaces and will not capture from the native OS packet stream.
36
37The SITA extension provides a remote datascope operation for capturing
38both WAN and LAN protocols. It effectively splits the operation of
39PCAP into two halves. The top layer performs the majority of the
40work, but interfaces via a TCP session to remote agents that
41provide the lower layer functionality of actual sniffing and
42filtering. More detailed information regarding the functions and
43inter-device protocol and naming conventions are described in detail
44in 'pcap-sita.html'.
45
46pcap_findalldevs() reads the local system's /etc/hosts file looking
47for host names that match the format of IOP type devices. ie. aaa_I_x_y
48and then queries each associated IP address for a list of its WAN and
49LAN devices. The local system the aggregates the lists obtained from
50each IOP, sorts it, and provides it (to Wireshark et.al) as the
51list of monitorable interfaces.
52
53Once a valid interface has been selected, pcap_open() is called
54which opens a TCP session (to a well known port) on the target IOP
55and tells it to start monitoring.
56
57All captured packets are then forwarded across that TCP session
58back to the local 'top layer' for forwarding to the actual
59sniffing program (wireshark...)
60
61Note that the DLT_SITA link-layer type includes a proprietary header
62that is documented as part of the SITA dissector of Wireshark and is
63also described in 'pcap-sita.html' for posterity sake.
64
65That header provides:
66- Packet direction (in/out) (1 octet)
67- Link layer hardware signal status (1 octet)
68- Transmit/Receive error status (2 octets)
69- Encapsulated WAN protocol ID (1 octet)
70
71
72
README.solaris.md
1# Compiling libpcap on Solaris and related OSes
2
3* Autoconf works everywhere.
4* Neither Solaris lex nor Solaris yacc are suitable.
5* Neither illumos lex nor illumos yacc are suitable.
6* Solaris m4 and illumos m4 are suitable.
7
8## OmniOS r151042/AMD64
9
10* flex 2.6.4 and GNU Bison 3.8.2 work.
11* CMake 3.23.1 works.
12* GCC 11.2.0 and Clang 14.0.3 work.
13
14## OpenIndiana 2021.04/AMD64
15
16* flex 2.6.4 and GNU Bison 3.7.6 work.
17* CMake 3.21.1 works.
18* GCC 7.5.0 and GCC 10.3.0 work, Clang 9.0.1 works.
19
20For reference, the tests were done using a system installed from
21`OI-hipster-text-20210430.iso` plus the following packages:
22```shell
23xargs -L1 pkg install <<ENDOFTEXT
24developer/build/autoconf
25developer/parser/bison
26developer/lexer/flex
27developer/build/cmake
28developer/gcc-10
29developer/clang-90
30ENDOFTEXT
31```
32
33## Solaris 11/AMD64
34
35* flex 2.6.4 and GNU Bison 3.7.3 work.
36* CMake 3.21.0 works.
37* Clang 11.0 works, GCC 11.2 works.
38
39For reference, the tests were done using Oracle Solaris 11.4.42.111.0.
40
41## Solaris 11/SPARC
42
43* flex 2.6.4 and GNU Bison 3.7.1 work.
44* CMake 3.14.3 works.
45* Sun C 5.13, Sun C 5.14 and Sun C 5.15 work; GCC 5.5.0 and GCC 7.3.0 work.
46
47## Solaris 10/SPARC
48
49* libpcap build fails with rpcapd enabled.
50* flex 2.6.4 and GNU Bison 3.7.1 work.
51* CMake 3.14.3 works.
52* Sun C 5.13 works, GCC 5.5.0 works.
53
54## Solaris 9/SPARC
55
56* flex 2.5.35 and GNU Bison 3.0.2 work.
57* CMake 2.8.9 does not work.
58* Neither Sun C 5.8 nor Sun C 5.9 work, GCC 4.6.4 works.
59