tcpstat v1.2 EXAMPLES OF USAGE
------------------------------
Paul Herman <pherman@frenchfries.net>
Cologne, Germany.

tcpstat has many options which may seem like a lot, but this is what makes
tcpstat so configurable.  It's real power is seen when the options are
combined.  So first:


BASIC USAGE
-----------
To simply get the basic garden variety statistics every 5 seconds, try:

 tcpstat -i fxp0
 tcpstat -r file.dump

The first one gathers its data from the "fxp0" interface (can be replaced
by "eth0" if you use Linux, for example), and the second line does the
same thing, but gets its data from a file.  These types of files can be
generated and saved using tcpdump(1).



OK, GOT THAT, BUT WHILE MONITORING AN
INTERFACE, TCPSTAT RUNS FOREVER. HOW DO I STOP IT?
--------------------------------------------------
One simple way is "Control-C" (or sending it a KILL signal...)  However,
sometimes admins like to run tcpstat for a long time unattended in the
background.  The solution in this case is to simply tell it how many
seconds it should run before quiting.

For example, you want to have tcpstat listen to eth0 for 2 Hours, and
write statistics in a file every minute.  2 Hours = 7200 seconds, and 1
minute is 60 seconds, so we just enter:

 tcpstat -i eth0 -s 7200 60 > output.file.txt

After 2 hours, all the statistics will be in the "output.file.txt" file.
By the way, the -s option has no effect when readind the data from a file,
of course.



OBSERVING TRAFFIC ONLY FOR CERTAIN PORTS
------------------------------------------
If you just want to get statistics from packets to or from certain ports,
try:

 tcpstat -f "port http" -i fxp0
 tcpstat -f "port (http or smtp)" -i fxp0

The first one shows statistics only for http traffic, while the second
command shows statistics for mail and web traffic combined.  In fact, the
filter option (-f) is very very cool indeed.  It can select certain hosts,
networks, IP protocols, packet length, and even IP flags like SYN, FIN,
ACK, etc.  See the manpage for tcpdump(1) for information on the syntax
of the -f option.



WHAT KIND OF STATISTICS ARE AVAILABLE?
--------------------------------------
Quite a few.  The manpage gives a complete list of all the output options
(these are the "%" thingies.)  Let's take a look at a few.

 tcpstat -o "Time: %r\tmin=%m\tmax=%M\n"
 tcpstat -o "Time: %r\ttcp=%T\tudp=%U\ticmp=%C\n"

First of all, you might ask, "what are all these '\' things?".  This is
standard notation for special output characters.  For example, every "\t"
is interpreted as a "tab" character (good for spacing), and each "\n" is a
new-line character.  It is usually a good idea to have a "\n" at the end,
otherwise all your lines will run together.  So back to the two examples.

The first example first displays a time stamp (the time in the middle of
the interval), then prints the minimum and maximum size of all packets in
that interval.  It would look something like:

  Time: 2.500000  min=88  max=88
  Time: 7.500000  min=76  max=88
  Time: 12.500000 min=48  max=384
  Time: 17.500000 min=44  max=436
  Time: 22.500000 min=88  max=88

The second example once again displays the time stamp for the interval,
and then reports how many TCP, UDP, and ICMP packets there were in each
interval.  It would look something like:

  Time: 2.500000  tcp=0   udp=0   icmp=9
  Time: 7.500000  tcp=0   udp=1   icmp=10
  Time: 12.500000 tcp=1   udp=14  icmp=9
  Time: 17.500000 tcp=5   udp=3   icmp=9
  Time: 22.500000 tcp=0   udp=0   icmp=8

Not surprising to see, that these two came from the same file.  Looking at
the first interval we see right away that there were only same sized ICMP
packets (in this case, they were just pings to my host.)



THE OTHER MODES OF OPERATION
----------------------------
tcpstat offers two other useful modes of operation:  "Accounting Mode",
and "Bandwidth Mode."  Say you have a 56k modem and you just recorded all
of your network traffic with tcpdump into a "dump.file" file.

 tcpstat -r dump.file -b 57600
 tcpstat -r dump.file -a

The first command will tell you exactly how often your modem was "maxed
out" (it is possible to achieve a faster baudrate that 56k with hardware
compression.)  The second command will display traffic estimates based on
this small sample, if you were continuously online for example.

These two commands are also useful for ISPs to decide if current lines are
adequate to handle current traffic, and to estimate how much traffic a
customer will pull each day, month, etc.  Of course, the larger the
sample, the more accurate your results.



WRITING DIFFERENT STATISTICS TO MULTIPLE FILES
----------------------------------------------
Starting in version 1.2 it is possible to write multiple statistics to
multiple files with just one tcpstat command.  Suppose you want daily
plots of nice looking graphs of TCP, UDP, and ICMP statistics on your web
page of your "vr0" interface.  First, you generate three separate files
which a graphing program like "gnuplot" can easily read and put something
like this in a crontab file:

  tcpstat -i vr0 -s 86400 -o "%s\t%T\n%3%s\t%U\n%4%s\t%C\n" \
	1>/tmp/stats/tcp.xy 3>/tmp/stats/udp.xy 4>/tmp/stats/icmp.xy

Then you can run your favorite gnuplot script on these files.  So what the
heck did that -o option do?  Starting from left to right:

  %s	- print a timestamp on stdout (default in the begining)
  \t	- follow timestamp with a tab character to separate data
  %T	- print the number of TCP packets for this interval
  \n	- ...followed by a newline
  %3	- tell tcpstat that the following data is outputed to filedesc 3
  %s\t	- once again, a timestamp followed by tab (like above) on filedesc 3
  %U	- print on filedesc 3 the number of UDP packets for this interval.
  \n	- newline on filedesc 3
  %4	- change to filedesc 4
  %s\t	- .... etc.
