ongrep

A cleaned up fork of ngrep for OpenBSD
git clone git://git.sgregoratto.me/ongrep
Log | Files | Refs | README | LICENSE

commit b19f1b294ac554dbc5b385f719d487d37bff7f06
parent 523ba2a2d02f6c4996f79f1cc07ed6276663eb48
Author: Jordan Ritter <jpr5@darkridge.com>
Date:   Sun, 20 Feb 2005 05:15:52 +0000

documentation cleanup

Diffstat:
DBUGS | 28----------------------------
DREADME | 155-------------------------------------------------------------------------------
DREADME.pcre | 30------------------------------
DTODO | 7-------
RCREDITS -> doc/CREDITS.txt | 0
RINSTALL -> doc/INSTALL.txt | 0
Adoc/PCRE.txt | 32++++++++++++++++++++++++++++++++
Adoc/README.txt | 154+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
8 files changed, 186 insertions(+), 220 deletions(-)

diff --git a/BUGS b/BUGS @@ -1,28 +0,0 @@ -Known bugs: - - o error message: ngrep uses obsolete (PF_INET,SOCK_PACKET) - - Not a bug in ngrep. Upgrade to the latest libpcap: - - http://www.tcpdump.org/release/libpcap-0.6.2.tar.gz - - o ngrep reports duplicate packets on the local loopback interface - - Not a bug in ngrep. Upgrade to the latest libpcap: - - http://www.tcpdump.org/release/libpcap-0.6.2.tar.gz - - o 'ngrep host foo.com' segfaults after displaying interface info - - Technically, not a bug in ngrep. A particular API call in - libpcap segfaults on certain operating systems (FreeBSD is - one). Newer versions of libpcap obviate the need to use that - particular API. You can get it at: - - http://www.tcpdump.org/release/libpcap-0.6.2.tar.gz - - For the time being, a configure switch '--without-restart' is - provided to turn off the API call. If your copy of ngrep - segfaults after displaying the interface info, try recompiling - with this switch. - diff --git a/README b/README @@ -1,155 +0,0 @@ - -Program: ngrep -Author: Jordan Ritter <jpr5@darkridge.com> -Version: 1.42 (3.28.2004) - - -Goal: - - A program that mimicks as much functionality in GNU grep as - possible, applied at the network layer. - - -Description: - - ngrep strives to provide most of GNU grep's common features, - applying them to the network layer. ngrep is a pcap-aware tool that - will allow you to specify extended regular or hexadecimal - expressions to match against data payloads of packets. It currently - recognizes TCP, UDP and ICMP across Ethernet, PPP, SLIP, FDDI, Token - Ring and null interfaces, and understands bpf filter logic in the - same fashion as more common packet sniffing tools, such as tcpdump - and snoop. - - -Usage: - - ngrep <-hXViwqpevxlDtTRM> <-IO pcap_dump> <-n num> <-d dev> <-A num> - <-s snaplen> <-S limitlen> <-W normal|byline|none> <-c cols> - <-P char> <-F file> <match expression> <bpf filter> - - -h is help/usage - -X is interpret match expression as hexadecimal - -V is version information - -i is ignore case - -w is word-regex (expression must match as a word) - -q is be quiet (don't print packet reception hash marks) - -p is don't go into promiscuous mode - -e is show empty packets - -v is invert match - -x is print in alternate hexdump format - -l is make stdout line buffered - -D is replay pcap_dumps with their recorded time intervals - -t is print timestamp every time a packet is matched - -T is print delta timestamp every time a packet is matched - -R is don't do privilege revocation logic - -M is don't do multi-line match (do single-line match instead) - -O is dump matched packets in pcap format to pcap_dump - -I is read packet stream from pcap format file pcap_dump - -n is look at only num packets - -d is use a device different from the default (pcap) - -A is dump num packets after a match - -s is set the bpf caplen - -S is set the limitlen on matched packets - -W is set the dump format (normal, byline, none) - -c is force the column width to the specified size - -P is set the non-printable display char to what is specified - -F is read the bpf filter from the specified file - - <match expression> is either an extended regular expression or a - hexadecimal string. see the man page for more - information. - - <bpf filter> is any bpf filter statement. - - -Tips: - - o When the intention is to match all packets (i.e. blank regex), it - is technically faster to use an empty regex, '', than to use '.*' - or '*'. - - o Always try to craft a BPF filter; this is doubly important on - interfaces that are very busy and are seeing large amounts of - packets. The parser takes a certain amount of time, and while - negligible on a slow interface, it can add up very quickly on a - busy one. - - o Hexadecimal expressions can be in straight numeric form, - 'DEADBEEF', or in symbolic form, '0xDEADBEEF'. A byte is the - smallest unit of measure you can match against. - - o As of v1.28, ngrep doesn't require a match expression. There are - cases where it will be confused and think part of your bpf filter - is the match expression, as in: - - % ngrep not port 80 - interface: eth0 (192.168.1.0/255.255.255.0) - filter: ip and ( port 80 ) - match: not - - In cases like this, you will need to specify a blank match expression: - - % ngrep '' not port 80 - interface: eth0 (192.168.1.0/255.255.255.0) - filter: ip and ( not port 80 ) - - - Please see http://ngrep.sourceforge.net/usage.html for more detailed - examples describing ngrep usage. - - -Miscellany: - - Please see the CREDITS file for a listing of the people who helped - make ngrep what it is today. Also, please note that ngrep is - released under a BSD-style license, though it currently relies upon - the GNU regex library, which is protected under the GPL. - - Also, it is _highly recommended_ that you upgrade to the latest - version of libpcap. All versions 0.5 and more recent fix really - annoying and in some cases fatal problems with the packet capture - library. If you happen to be using Windows, please check the - WinPcap site to see if there are any updates. - - -Useful sites: - - o Unix libpcap: - - http://www.tcpdump.org/release/ - - o Windows libpcap: - - http://winpcap.polito.it/install/ - - -Known Working Platforms: - - o Linux 2.0 - 2.4 - (RH6+, SuSE, TurboLinux, Debian)/x86 - RedHat/alpha - Cobalt (Qube2) Linux/MIPS - Slackware 7, 8.1 - Gentoo - o Solaris 2.5.1, 2.6/SPARC, Solaris 7, Solaris 8/SPARC, Solaris 9/SPARC - o FreeBSD 2.2.5, 3.1, 3.2, 3.4-RC, 3.4-RELEASE, 4.0, 5.0 - o OpenBSD 2.4 (after upgrading pcap from 0.2), 2.9, 3.0, 3.1 - o NetBSD 1.5/SPARC - o Digital Unix V4.0D (OSF/1), Tru64 5.0, Tru64 5.1A - o HPUX 11 - o IRIX - o AIX 4.3.3.0/PowerPC - o BeOS R5 - o Mac OS X 10.2, 10.2.6 - - -Support, Feedback, & Patches - - If you need help, have constructive feedback, or would like to - submit a patch, please visit ngrep's project at SourceForge and use - the online tools there. It will help the author better manage the - various requests and patches so that nothing is lost or missed (as - has been the case in the past, unfortunately). - - ngrep Project Website: http://sourceforge.net/projects/ngrep/ diff --git a/README.pcre b/README.pcre @@ -1,30 +0,0 @@ -A note on PCRE vs GNU regex: - - I ran several tests comparing GNU regex to the PCRE library - using 10 million loop iterations: optimized vs. non-optimized, - match vs. non-match. The conclusion I came to was that an - unoptimized PCRE program is almost double the match and - non-match times of the GNU regex library yields, and when using - optimization a PCRE program would perform almost the same in the - non-match case, but again almost twice that of the match case. - - The test subject was "how now brown cow", and the pattern we - were searching for in the match case was "now brown", and in the - non-match case "not brown". Obviously, the speed of matches is - directly related to the actual regex itself, and a - well-formulated regex certainly performs more efficiently than a - simple substring match. However, this test is indicative of how - most people use ngrep, so the test results are still important. - - Granted, on the single-match level the time difference is - absolutely unnoticeable (it took 10 million loop iterations to - compute it), so this may not mean anything to you. Likewise, - the stripped binary sizes are also within 10k of each other on - the test compile box. - - If absolute speed is not the issue, then compile against PCRE - since it has better licensing. If you're after the fastest you - can get (for you netops and netadmins out there, you know who - you are), then compile against GNU regex. The speed really - helps when piping those 500MB pcap dump files through ngrep over - and over. diff --git a/TODO b/TODO @@ -1,7 +0,0 @@ -Todo: - - o add timerange functionality for replaying pcap_dumps ala -r - date-date using 'date' format MMDDhhmmCCYY - - o IPv6 support - diff --git a/CREDITS b/doc/CREDITS.txt diff --git a/INSTALL b/doc/INSTALL.txt diff --git a/doc/PCRE.txt b/doc/PCRE.txt @@ -0,0 +1,32 @@ +$Id$ + +A quick note on PCRE vs GNU regex: + + I ran several tests comparing GNU regex to the PCRE library + using 10 million loop iterations: optimized vs. non-optimized, + match vs. non-match. The conclusion I came to was that an + unoptimized PCRE program is almost double the match and + non-match times of the GNU regex library yields, and when using + optimization a PCRE program would perform almost the same in the + non-match case, but again almost twice that of the match case. + + The test subject was "how now brown cow", and the pattern we + were searching for in the match case was "now brown", and in the + non-match case "not brown". Obviously, the speed of matches is + directly related to the actual regex itself, and a + well-formulated regex certainly performs more efficiently than a + simple substring match. However, this test is indicative of how + most people use ngrep, so the test results are still important. + + Granted, on the single-match level the time difference is + absolutely unnoticeable (it took 10 million loop iterations to + compute it), so this may not mean anything to you. Likewise, + the stripped binary sizes are also within 10k of each other on + the test compile box. + + If absolute speed is not the issue, then compile against PCRE + since it has better licensing. If you're after the fastest you + can get (for you netops and netadmins out there, you know who + you are), then compile against GNU regex. The speed really + helps when piping those 500MB pcap dump files through ngrep over + and over. diff --git a/doc/README.txt b/doc/README.txt @@ -0,0 +1,154 @@ +$Id$ + +Program: ngrep +Author: Jordan Ritter <jpr5@darkridge.com> +Version: 1.43-cvs (2.19.2005) + + +Goal: + + A program that mimicks as much functionality in GNU grep as + possible, applied at the network layer. + + +Description: + + ngrep strives to provide most of GNU grep's common features, + applying them to the network layer. ngrep is a pcap-aware tool that + will allow you to specify extended regular or hexadecimal + expressions to match against data payloads of packets. It currently + recognizes TCP, UDP and ICMP across Ethernet, PPP, SLIP, FDDI, Token + Ring and null interfaces, and understands bpf filter logic in the + same fashion as more common packet sniffing tools, such as tcpdump + and snoop. + + +Usage: ngrep <-LhXViwqpevxlDtTRM> <-IO pcap_dump> <-n num> <-d dev> <-A num> + <-s snaplen> <-S limitlen> <-W normal|byline|none> <-c cols> + <-P char> <-F file> <match expression> <bpf filter> + -h is help/usage + -V is version information + -q is be quiet (don't print packet reception hash marks) + -e is show empty packets + -i is ignore case + -v is invert match + -R is don't do privilege revocation logic + -x is print in alternate hexdump format + -X is interpret match expression as hexadecimal + -w is word-regex (expression must match as a word) + -p is don't go into promiscuous mode + -l is make stdout line buffered + -D is replay pcap_dumps with their recorded time intervals + -t is print timestamp every time a packet is matched + -T is print delta timestamp every time a packet is matched + -M is don't do multi-line match (do single-line match instead) + -I is read packet stream from pcap format file pcap_dump + -O is dump matched packets in pcap format to pcap_dump + -n is look at only num packets + -A is dump num packets after a match + -s is set the bpf caplen + -S is set the limitlen on matched packets + -W is set the dump format (normal, byline, none) + -c is force the column width to the specified size + -P is set the non-printable display char to what is specified + -F is read the bpf filter from the specified file + -d is use specified device instead of the pcap default + +On Win32: + -L is show the winpcap device list index + + +Tips: + + o When the intention is to match all packets (i.e. blank regex), it + is technically faster to use an empty regex (``'') than to use + ``.*'' or ``*''. + + o When sniffing interfaces that are very busy or are seeing large + amounts of packet traffic, make sure to craft a BPF filter to + limit what PCAP has to deliver to ngrep. The ngrep parser takes a + certain amount of time and while negligible on a slow interface, + it can add up very quickly on a busy one. + + o Hexadecimal expressions can be in straight numeric form, + 'DEADBEEF', or in symbolic form, '0xDEADBEEF'. A byte is the + smallest unit of measure you can match against. + + o As of v1.28, ngrep doesn't require a match expression. However, + there are cases where ngrep can be confused and think part of your + bpf filter is the match expression, as in: + + % ngrep not port 80 + interface: eth0 (192.168.1.0/255.255.255.0) + filter: ip and ( port 80 ) + match: not + + In cases like this, you will need to specify a blank match expression: + + % ngrep '' not port 80 + interface: eth0 (192.168.1.0/255.255.255.0) + filter: ip and ( not port 80 ) + + + Please see http://ngrep.sourceforge.net/usage.html for more detailed + examples describing ngrep usage. + + +Miscellany: + + Please see the ``doc/CREDITS.txt'' file for a listing of the people + who helped make ngrep what it is today. Also, please note that + ngrep is released under a BSD-style license, though it currently + relies upon the GNU regex library, which is protected under the GPL. + + Also, it is _highly recommended_ that you upgrade to the latest + version of libpcap. All versions 0.5 and more recent fix really + annoying and in some cases fatal problems with the packet capture + library. If you happen to be using Windows, please check the + WinPcap site to see if there are any updates. + + +Useful sites: + + o Unix libpcap: + + http://www.tcpdump.org/release/ + + o Windows libpcap: + + http://www.winpcap.org/install/ + + +Known Working Platforms: + + o Linux 2.0 - 2.6 + (RH6+, SuSE, TurboLinux, Debian)/x86 + RedHat/alpha + Cobalt (Qube2) Linux/MIPS + Slackware 7, 8.1 + Gentoo + o Solaris 2.5.1, 2.6/SPARC, Solaris 7, Solaris 8/SPARC, Solaris 9/SPARC + o FreeBSD 2.2.5, 3.1, 3.2, 3.4-RC, 3.4-RELEASE, 4.0, 5.0 + o OpenBSD 2.4 (after upgrading pcap from 0.2), 2.9, 3.0, 3.1 + o NetBSD 1.5/SPARC + o Digital Unix V4.0D (OSF/1), Tru64 5.0, Tru64 5.1A + o HPUX 11 + o IRIX + o AIX 4.3.3.0/PowerPC + o BeOS R5 + o Mac OS X 10.2, 10.2.6 + + In other words, pretty much everything. + + +Support, Feedback, & Patches + + If you need help, have constructive feedback, or would like to + submit a patch, please visit ngrep's project at SourceForge and use + the online tools there. It will help the author better manage the + various requests and patches so that nothing is lost or missed (as + has been the case in the past, unfortunately). + + ngrep Project Website: + + http://sourceforge.net/projects/ngrep/