The BPF Traffic collector
=========================

    These directories contain a TCP and UDP traffic logging system.
It can be used for locating suspicious network data traffic.
The following programs are included:

trafd      - tcp/udp data traffic collector daemon
 trafstart - simple example to start trafd
 trafstop  - backup memory traffic table to tmp file and shutdown daemon
 trafdump  - backup memory traffic table to tmp file without shutdown
 trafsave  - append memory traffic table to log file and restart collect
 tratd.sh  - example to start/stop trafd from */rc.d
traflog    - manage daemon log files
trafstat   - grab current traffic statistics from daemon
trafstatd  - allow remote request of the current traffic statistics
trafshow   - full screen visualization of the network data traffic
             (also allowed separately, into 'trafshow-x.y.tgz' archive)

    First and last program use the Berkeley Packet Filter mechanism and may be
used with BSD4.3, BSDI, Ultrix, Linux and some other OS Unix like BSD. Several
former versions of the BPFT tested and safe work only under BSDI BSD/386 v1.0,
versions 2.* propertly work on the FreeBSD >=2.2.8, versions 3.* don't work
on FreeBSD <3.0 (require library 'cap')

    Before compile this stuff edit main Makefile as you need, also some useful
definition you may find in include/traffic.h and include/pathnames.h.

    To build the programs, just enter 'make' from the BPFT root directory.
To install the programs, just type 'make install' and to clean - apparently
f system crash and trafsave one per day totall type 'make uninstall'.

    If you want allow remote users to request traffic statistics from your
daemon then use trafstatd on server side and trafstat on client. Trafstatd
run from inetd only. Add the following line to your /etc/inetd.conf:

trafstat stream tcp nowait root /usr/local/bin/trafstatd trafstatd

and add line to your /etc/services:

trafstat	150/tcp		trafstatd	# network traffic statistic

    The trafstat service used TCP port number 150 for default, but you may
overwrite it from command line when execute trafstat program.

    We recomend: more often invoke trafdump via cron (each 10 min for example)
to avoid loss data as a result of system crash and trafsave one per day to
have log file aligment by days. Log file is binary file with little size,
average size per day is several kilobytes.


Quick reference:
================

For more information see man pages: trafd(8), trafstatd(8), traflog(1) and
trafstat(1).

trafd
-----

Usage:	trafd [-dOpr] [-c count] [-i iface] [-f suffix] [-F file | expr]
Where:
	-c count	count number of packets and exit
	-d		print compiled packet-matching code and exit
	-f suffux	extension for traffic save & dump files
	-F file		use file as input for the filter expression
	-i interface	current support: ethernet, slip, ppp, loopback
			(see pcap(3), tcpdump(1) for details)
	-O		don't run the packet-matching code optimizer
			(see pcap(3), tcpdump(1) for details)
	-p		don't put the interface into promiscuous mode
	-r		attempt to resume data from dumped file if exist
	expr		filter expression like tcpdump's
	-V		print version information and exit
	-X		use only ip information (don't store port and protocol,
			store data lenght)

Note:
-----
Filter expression is full compatible with tcpdump. See tcpdump(1) section
OPTIONS sub-section 'expression'.


trafstat
--------

Usage:	trafstat [-i iface] [-b | -fnN] [host] [port]
Where:
	-b		binary output, use redirect to file
	-f		convert addresses to name only for local hosts
	-i interface	current support: ethernet, slip, ppp, loopback
			(see pcap(3), tcpdump(1) for details)
	-n		don't convert addresses to host names
	-N		output only host names without domain
	-V		print version information and exit
	host		obtain traffic statistics from 'host' via network
	port		port number, default 150


traflog
-------

Usage:	traflog -l [-i iface] [-b #] [-e #] [-r]
	traflog -d [-fnN] [-F file | pattern]
	traflog [-i iface] [-b #] [-e #] [-aAfnNrs] [-o format] [-w file] \
		[-S order] [-F file | pattern]
	traflog -V
	traflog -h
Where:
	-a		output all log file records, default only last
	-b #number	begin offset
	-b datetime	begin time ([yy[mm[dd[HH[MM]]]]])
	-d		print pattern table, use for test pattern
	-e #number	end offset
	-e datetime	end time ([yy[mm[dd[HH[MM]]]]])
	-f		convert addresses to name only for local hosts
	-F file		use file as input for the pattern expression
	-h		print usage information and exit
	-i name		interface name or file name
        -i file         file with trafd data
	-l		print records list of the log file
	-n		don't convert addresses to host names
	-N		output only host names without domain
	-o format	output by format described in traflog.format
	-r		print only number of records or number of Kb
	-s		output summary traffic
	-S order	sort output in specified order ( "f", "t", "b", "s",
			"d" is equvalence to "from", "to", "bytes", "srcport,
			"dstport")
	-V		print version information and exit
	-w file		binary output to file
	pattern		pattern expression

Note:
-----
Parameters '-b #nnn' and '-e #nnn' use with escaped "#" in unix shells:
traflog -b \#500 -e \#1000

If 'name' not exist interface then it interprete as file name.
Pattern may contain following keywords: from, to, mask, port, proto.
For example:

from turbo.nsk.su 	to ns.nsk.su 	port domain
			to all 		port ftp port ftp-data
from TURBONET		to all
from 192.188.187.127 mask 255.255.255.224 port all
from all to 144.206.0.0 proto tcp

Traflog output example:
-----------------------

 (fxp0) e9asu.surgut.elektra.ru at Sep  4 20:59:47 - Sep  6 08:46:13
 Summary: 65419240 data bytes, 73315120 all bytes, 444 records
     From        Port        To      Port    Proto      Data          All
<from addr> <from port> <to addr> <to port> <proto> <data len> <packet len>

   Full traffic size contents in the 'All' column. The 'Data' column contents
summary size of the ip packets data (ip packet size without header).


Environment variables:
======================

IFF_LISTEN		set the name of the network interface.
			the same as '-i interface' and -i overwrite it value.
			supported by trafd, trafstat, traflog, trafshow.

PATTERNPATH		set the default directory name where find pattern
			files.
			supported only by traflog.

FORMATPATH		set the full name of file with user defined
			description of the traffic output format.
			supported only by traflog.


Syslog facility:
----------------

    trafd use the system logger daemon (syslogd) for the logging various
information.
    Thus, it use options LOG_PID for log the process id and LOG_CONS for
if cannot pass the message to syslogd it will attempt to write the message
to console, use facility 'daemon' and levels 'info', 'notice', 'warning'
and 'error'. (Facility defined in include/traffic.h, see #define
SYSLOG_FACILITY)
    If you want additional information about condition of your daemon, 
i.e. what is it doing and how do it do, then you should set syslog message
level in your syslog.conf up to 'info'.


    The latest versions of these programs are available from
ftp://ftp.grumbler.org/pub/bpft or http://bpft.by.ru (versions 4.*)
ftp://ftp.riss-telecom.ru/pub/dev/trafd/ (versions 3.*)
ftp://ftp.turbo.nsk.su/pub/unix/ (original versions: 2.*)

CREDITS:
--------

1st release, versions 1.0 to 2.0:
Vladimir Vorobyev <bob@turbo.nsk.su>
CAD lab., Siberian State Academy of Telecommunication
Novosibirsk, Russia.

Versions 3.0, 3.0.1:
Vitaly V. Belekhov <vitaly@riss-telecom.ru>
RISS-Telecom Networking Center

Other branch 3.* versions:
Stanislav A Svirid <count@riss-telecom.ru>
RISS-Telecom Networking Center

Modifications to 4.0 and above:
Stas Degteff <g@grumbler.org>
Yekaterinburg, Russia.

