commit b19f1b294ac554dbc5b385f719d487d37bff7f06
parent 523ba2a2d02f6c4996f79f1cc07ed6276663eb48
Author: Jordan Ritter <jpr5@darkridge.com>
Date: Sun, 20 Feb 2005 05:15:52 +0000
documentation cleanup
Diffstat:
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/