=head1 NAME

README - information about C<FlowScan>

=head1 DESCRIPTION

C<FlowScan> is a network analysis and reporting tool.  It processes IP
flows recorded C<cflowd>-format raw flow files and reports on what it
finds.

This document is the C<FlowScan> C<README> $Revision: 1.10 $,
$Date: 2001/02/28 21:50:17 $.

=head1 Announcement

I'm pleased to announce the release of C<FlowScan-1.006>.  C<FlowScan>
is a tool to monitor and graph flow information from Cisco and
Riverstone routers in near real-time.

Amonst many other things, C<FlowScan> can measure and graph traffic for
applications such as Napster.  A sample of what FlowScan can do is at:

   http://wwwstats.net.wisc.edu

=head1 Changes in FlowScan-1.006 (since FlowScan-1.005)

=over 4

=item *

The CampusIO and SubNetIO reports were enhanced with a new optional
configuration directive: C<TopN>.  When defined, this directive causes
"Top Talker" reports to be produced.  These HTML reports contain the
most active (i.e. "top") source and destination addresses.

=item *

The CampusIO and SubNetIO reports were enhanced to record the number of
local IP addresses that where active for each network and subnet into
the RRD files.  This enables users to estimate the number of active
hosts hosts over time, detect "scans" which systematically sweep across
network address space, and to calculate the average bytes, packets, and
flows per host.

=item *

The template Makefile used to produce the graphs was enhanced to allow
the inclusion of "events" in the graphs, similarly to what can be done
with Cricket.  This allows you to label events such as configuration
changes and outages to discover correlations with traffic measurement.

=item *

Two new utilities suitable for stand-alone use, are included.
<kbd>ip2hostname</kbd> converts IP addresses to their respective
hostnames. <kbd>event2vrule</kbd> adds "events" to C<rrdtool> graphs.

=item *

Added support for LFAP (Lightweight Flow Accouting Protocol) used by
Riverstone and Enterasys (formerly Cabletron) routers.  This currently
requires C<slate> (from C<http://www.nmops.org>) and C<lfapd> by Steven
Premeau <premeau@uwp.edu>.  C<lfapd> produces time-stamped raw flow
files in the same cflowd-defined format that is processed by FlowScan.

=item *

Added the ability for the C<CampusIO> report to identify outbound flows
based solely on the flow's destination IP address.  While this is less
trustworthy than using C<NextHops> or C<OutputIfIndexes>, it is now the
default and will be useful for environments where the flow nexthop or
output ifIndex values are not meaningful.

=item *

The C<CampusIO> report contains a new B<experimental> feature which
reads a BGP routing table, and therefore can determine which Autonomous
systems source, transit, or sink most of your institution's traffic.
The C<CampusIO> report was enhanced with new optional configuration
directives:  C<BGPDumpFile>, C<TopN>, C<ReportPrefixFormat>.  When
properly defined, these directives cause C<CampusIO> to create tabular
HTML reports named C<{origin|path}_{in|out}.html> under C<OutputDir>
after analyzing each raw flow file.  These reports show the "top"
Autonomous Systems with which your site exchanges traffic.

=item *

A C<WebProxyIfIndex> directive was added to the C<CampusIO> report.
This allows one to specify the index of the interface to which HTTP
traffic is being transparently redirected.  This enables C<FlowScan> to
properly count HTTP flows even though NetFlow v5 does not accurately
report the nexthop value for flows which are transparently redirected
via a Cisco route-map.

=item *

C<CampusIO> now contains a fix for a bug introduced in
C<FlowScan-1.005> which would sometimes cause perl to abort with this
message:

   patricia.c:645: patricia_lookup: Assertion `prefix' failed.

This would happen if the C<NextHops> or C<LocalNextHops> were specified
by name rather than IP address.  It also would happen if the boulder
C<SUBNET> values were specified incorrectly.

=back

=head1 Availability

FlowScan is licensed under the GNU General Public License, and is
available to you at:

   http://net.doit.wisc.edu/~plonka/FlowScan/

=head1 Mailing Lists

=over 4

There are two mailing lists having to do with FlowScan:

=item * flowscan

a general mailing list for FlowScan users.

=item * flowscan-announce

a B<low-volume>, restricted post mailing list to keep
FlowScan users informed of news regarding FlowScan. 

=back

The lists' respective archives are available at:

   http://net.doit.wisc.edu/~plonka/list/flowscan

and:

   http://net.doit.wisc.edu/~plonka/list/flowscan-announce

Announcements will be "cross-posted" to both lists, so there's no need to
join both.

These lists are hosted by the Division of Information Technology's
Network Engineering Technology group at the University of Wisconsin -
Madison.  To subscribe to either of them, send email to:

   majordomo@net.doit.wisc.edu

containing either:

   subscribe flowscan

I<or>:

   subscribe flowscan-announce

You should receive an automatic response that will request that you
verify your request to become a member of the list, to which you must
reply with the authentication information there-in. Then, in response
to your reply, you should receive a welcome message.  If you have any
questions about the administrative policies of this list's manager,
please contact:

   owner-flowscan@net.doit.wisc.edu

I<or>:

   owner-flowscan-announce@net.doit.wisc.edu

=head1 FlowScan Resources

Overview:

   http://www.caida.org/tools/utilities/flowscan/

Paper - "FlowScan: A Network Traffic Flow Reporting and Visualization Tool":

   HTML:       http://net.doit.wisc.edu/~plonka/lisa/FlowScan/
   PostScript: http://net.doit.wisc.edu/~plonka/lisa/FlowScan/out.ps.gz

   http://www.caida.org/tools/utilities/flowscan/

LISA XIV (New Orleans, Dec. 2000) Presentation:

   http://net.doit.wisc.edu/~plonka/lisa/FlowScan/presentation/

NANOG 21 (Atlanta, Feb. 2001) Presentation:

   http://www.nanog.org/mtg-0102/plonka.html
   http://net.doit.wisc.edu/~plonka/nanog/

Other:

   http://wwwstats.net.wisc.edu
   http://net.doit.wisc.edu/data/Napster/
   http://net.doit.wisc.edu/data/flow/size/

=head1 Contributors

   Alexander Kunz <Alexander.Kunz@nextra.de>
   Kevin Gannon <kevin@gannons.net>
   John Payne <john@sackheads.org>
   Michael Hare <Michael.Hare@doit.wisc.edu>
   Steven Premeau <premeau@uwp.edu>

=head1 Thanks

I'd like to thank the participants in the FlowScan mailing list for
their efforts and feedback.

Also, thanks to Daniel McRobb, Tobi Oetiker, and CAIDA for providing
the main tools upon which FlowScan is built, namely "cflowd" and
"RRDTOOL".

=head1 Copyright and Disclaimer

=over 4

Note that this document is provided `as is'. The information in it is
not warranted to be correct.  Use it at your own risk.

   Copyright (c) 2000-2001 Dave Plonka <plonka@doit.wisc.edu>.
   All rights reserved.

This document may be reproduced and distributed in its entirety
(including this authorship, copyright, and permission notice), provided
that no charge is made for the document itself.

=back
