/usr/share/doc/flowscan/html/CampusIO.html

    <HTML> 
	<HEAD> 
	    <TITLE>CampusIO - a FlowScan module for reporting on campus traffic I/O

</TITLE> 
	</HEAD>

	<BODY>

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#CONFIGURATION">CONFIGURATION</A>
	<LI><A HREF="#METHODS">METHODS</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
	<LI><A HREF="#BUGS">BUGS</A>
	<LI><A HREF="#AUTHOR">AUTHOR</A>
	<LI><A HREF="#VERSION">VERSION</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<H1><A NAME="NAME">NAME

</A></H1>
CampusIO - a FlowScan module for reporting on campus traffic I/O


<P>

<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS

</A></H1>
<PRE>   $ flowscan CampusIO
</PRE>

<P>

or in <EM>flowscan.cf</EM>:


<P>

<PRE>   ReportClasses CampusIO
</PRE>

<P>

<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION

</A></H1>
CampusIO is a general flowscan report for reporting on flows of traffic in
and out of a site or campus. It does this by processing flows reported by
one or more routers at the network border. The site or campus may be an
Autonomous System (AS), as is often the case for large universities, but
this is not necessary. CampusIO can be used by smaller institutions and
other enterprises as well.


<P>

<CODE>flowscan</CODE> will run the CampusIO report if you configure this in your <EM>flowscan.cf</EM>:


<P>

<PRE>   ReportClasses CampusIO
</PRE>

<P>

<P>
<HR>
<H1><A NAME="CONFIGURATION">CONFIGURATION

</A></H1>
CampusIO's configuration file is <EM>CampusIO.cf</EM>. This configuration file is located in the directory in which the <EM>flowscan</EM> script resides.


<P>

The CampusIO configuration directives include:


<P>

<DL>
<DT><STRONG><A NAME="item_NextHops">NextHops

</A></STRONG><DD>
This directive is suggested if <A HREF="#item_OutputIfIndexes">OutputIfIndexes</A> is not defined. Defining <A HREF="#item_NextHops">NextHops</A> causes <CODE>flowscan</CODE> to identify outbound flows by their nexthop value.  <A HREF="#item_NextHops">NextHops</A> is a comma-seperated list of IP addresses or resolvable hostnames, e.g.:


<P>

<PRE>   # NextHops
   NextHops gateway.provider.net, gateway.other.net
</PRE>

<P>

If neither <A HREF="#item_NextHops">NextHops</A> nor <CODE>OutputIfIdexes</CODE> is defined, <CODE>CampusIO</CODE>
will use the flows' destination addresses to determine whether or not they
are outbound. This is a less reliable and more CPU intensive method than <A HREF="#item_NextHops">NextHops</A> or <CODE>OutputIfIdexes</CODE>.


<P>

<DT><STRONG><A NAME="item_OutputIfIndexes">OutputIfIndexes

</A></STRONG><DD>
This directive is suggested if <A HREF="#item_NextHops">NextHops</A> is not defined. Defining
<A HREF="#item_OutputIfIndexes">OutputIfIndexes</A> causes <CODE>flowscan</CODE> to identify outbound flows by their output interface value.  <A HREF="#item_OutputIfIndexes">OutputIfIndexes</A> is a comma-seperated list of ifIndexes as determined using SNMP, e.g.:


<P>

<PRE>   $ snmpwalk router.our.domain public interfaces.ifTable.ifEntry.ifDescr
</PRE>

<P>

or by looking at the raw flows from Cflowd to determine the <CODE>$output_if</CODE>. e.g.:


<P>

<PRE>   # OutputIfIndexes
   OutputIfIndexes 1, 2, 3
</PRE>

<P>

If neither <A HREF="#item_NextHops">NextHops</A> nor <CODE>OutputIfIdexes</CODE> is defined, <CODE>CampusIO</CODE>
will use the flows' destination addresses to determine whether or not they
are outbound. This is a less reliable and more CPU intensive method than <A HREF="#item_NextHops">NextHops</A> or <CODE>OutputIfIdexes</CODE>.


<P>

<DT><STRONG><A NAME="item_LocalSubnetFiles">LocalSubnetFiles

</A></STRONG><DD>
This directive is required. It is a a comma-seperated list of files
containing the definitions of ``local'' subnets. E.g.:


<P>

<PRE>   # LocalSubnetFiles local_nets.boulder
   LocalSubnetFiles bin/local_nets.boulder
</PRE>

<P>

<DT><STRONG><A NAME="item_OutputDir">OutputDir

</A></STRONG><DD>
This directive is required. It is the directory in which RRD files will be
written. E.g.:


<P>

<PRE>   # OutputDir /var/local/flows/graphs
   OutputDir graphs
</PRE>

<P>

<DT><STRONG><A NAME="item_LocalNextHops">LocalNextHops

</A></STRONG><DD>
This is an ``advanced'' option which is only required if you are exporting
and collecting flows from multiple routers to the same FlowScan. It is a
comma-seperated list of IP addresses or resolvable hostnames.


<P>

Specify all the local routers for which you have configured cflowd to
collecting flows on this FlowScan host. This will ensure that the same
traffic isn't counted twice by ignoring flows destined for these next-hops,
which otherwise might look as if they're inbound flows. FlowScan will only
count flows that represent traffic forwarded outside this set of local
routers.


<P>

E.g.:


<P>

<PRE>   # LocalNextHops other-router.our.domain
</PRE>

<P>

<DT><STRONG><A NAME="item_TCPServices">TCPServices

</A></STRONG><DD>
This directive is optional, but is required if you wish to produce the
CampusIO service graphs. It is a comma-seperated list of TCP services by
name or number. E.g., it is recommended that it contain at least the
services shown here:


<P>

<PRE>   # TCPServices ftp-data, ftp, smtp, nntp, www, 7070, 554
   TCPServices ftp-data, ftp, smtp, nntp, www, 7070, 554
</PRE>

<P>

<DT><STRONG><A NAME="item_UDPServices">UDPServices

</A></STRONG><DD>
This directive is optional. It is a comma-seperated list of UDP services by
name or number. E.g.:


<P>

<PRE>   # UDPServices domain, snmp, snmp-trap
</PRE>

<P>

<DT><STRONG><A NAME="item_Protocols">Protocols

</A></STRONG><DD>
This directive is optional, but is required if you wish to produce the
CampusIO protocol graphs. It is a comma-seperated list of IP protocols by
name. E.g.:


<P>

<PRE>   # Protocols icmp, tcp, udp
   Protocols icmp, tcp, udp
</PRE>

<P>

<DT><STRONG><A NAME="item_ASPairs">ASPairs

</A></STRONG><DD>
This directive is optional, but is required if you wish to build any custom
AS graphs. It is a list of source and destination AS pairs. E.g.:


<P>

<PRE>   # source_AS:destination_AS, e.g.:
   # ASPairs 0:0
   ASPairs 0:0
</PRE>

<P>

Note that the effect of setting ASPairs will be different based on whether
you specified ``peer-as'' or ``origin-as'' when you configured your Cisco.
This option was intended to be used when ``peer-as'' is configured.


<P>

See the <A HREF="#item_BGPDumpFile">BGPDumpFile</A> directive for other AS-related features.


<P>

<DT><STRONG><A NAME="item_Verbose">Verbose

</A></STRONG><DD>
This directive is optional. If non-zero, it makes <CODE>flowscan</CODE> more verbose with respect to messages and warnings. Currently the values <CODE>1</CODE> and <CODE>2</CODE> are understood, the higher value causing more messages to be produced.
E.g.:


<P>

<PRE>   # Verbose (OPTIONAL, non-zero = true)
   Verbose 1
</PRE>

<P>

<DT><STRONG><A NAME="item_NapsterSubnetFiles">NapsterSubnetFiles

</A></STRONG><DD>
This directive is optional, but is required if you wish to produce the
CampusIO service graphs. It is a comma-seperated list of files containing
the definitions of ``Napster'' subnets. E.g.:


<P>

<PRE>   # NapsterSubnetFiles (OPTIONAL)
   NapsterSubnetFiles bin/Napster_subnets.boulder
</PRE>

<P>

<DT><STRONG><A NAME="item_NapsterSeconds">NapsterSeconds

</A></STRONG><DD>
This directive is optional. It is the number of seconds after which a given
campus host has communicated with a host within the ``Napster''
<CODE>subnet(s)</CODE> will no longer be considered to be using the Napster
application. E.g. Half an hour:


<P>

<PRE>   # NapsterSeconds (OPTIONAL)
   NapsterSeconds 1800
</PRE>

<P>

<DT><STRONG><A NAME="item_NapsterPorts">NapsterPorts

</A></STRONG><DD>
This directive is optional. It a comma-seperated list of default TCP ports
used by Napster. These will be used to determine the confidence level of
whether or not it's really Napster traffic. If confidence is low, it will
be reported as ``NapsterMaybe'' rather than ``NapUser'' traffic. E.g.,
reasonable values are:


<P>

<PRE>   # NapsterPorts (OPTIONAL)
   NapsterPorts 8875, 4444, 5555, 6666, 6697, 6688, 6699, 7777, 8888
</PRE>

<P>

<DT><STRONG><A NAME="item_TopN">TopN

</A></STRONG><DD>
This directive is optional. It's use requires the <CODE>HTML::Table</CODE> perl module.  <A HREF="#item_TopN">TopN</A> is the number of entries to show in the tables that will be generated in
HTML top reports. E.g.:


<P>

<PRE>   # TopN (OPTIONAL)
   TopN 10
</PRE>

<P>

If you'd prefer to see hostnames rather than IP addresses in your top
reports, use the <EM>ip2hostname</EM> script. E.g.:


<P>

<PRE>   $ ip2hostname -I *.*.*.*_*.html
</PRE>

<P>

<DT><STRONG><A NAME="item_ReportPrefixFormat">ReportPrefixFormat

</A></STRONG><DD>
This directive is optional. It is used to specify the file name prefix for
the HTML or text reports such as the ``originAS'', ``pathAS'', and ``Top
Talkers'' reports. You should use <CODE>strftime(3)</CODE> format
specifiers in the value, and it may also specify sub-directories. If not
set, the prefix defaults to the null string, which means that, every five
minutes, subsequent reports will overwrite the previous. E.g.:


<P>

<PRE>   # Preserve one day of HTML reports using the time of day as the dir name:
   ReportPrefixFormat html/CampusIO/%H:%M/
</PRE>

<P>

or:


<P>

<PRE>   # Preserve one month by using the day of month in the dir name (like sar(1)):
   ReportPrefixFormat html/CampusIO/%d/%H:%M_
</PRE>

<P>

<DT><STRONG><A NAME="item_BGPDumpFile">BGPDumpFile

</A></STRONG><DD>
This directive is optional and is <STRONG>experimental</STRONG>. In combination with
<A HREF="#item_TopN">TopN</A> and <A HREF="#item_ASNFile">ASNFile</A> it causes FlowScan to produce ``Top ASN'' reports which show the ``top''
Autonomous Systems with which your site exchanges traffic.


<P>

<A HREF="#item_BGPDumpFile">BGPDumpFile</A> requires the <CODE>ParseBGPDump</CODE> perl module by Sean McCreary, which is supplied with CAIDA's CoralReef
Package:


<P>

<PRE>   <A HREF="http://www.caida.org/tools/measurement/coralreef/status.xml">http://www.caida.org/tools/measurement/coralreef/status.xml</A>
</PRE>

<P>

Unfortunately, CoralReef is governed by a different license than FlowScan
itself. The <EM>Copyright</EM> file says this:


<P>

<PRE>   Permission to use, copy, modify and distribute any part of this
   CoralReef software package for educational, research and non-profit
   purposes, without fee, and without a written agreement is hereby
   granted, provided that the above copyright notice, this paragraph
   and the following paragraphs appear in all copies.
   [...]
</PRE>

<P>

<PRE>   The CoralReef software package is developed by the CoralReef
   development team at the University of California, San Diego under
   the Cooperative Association for Internet Data Analysis (CAIDA)
   Program. Support for this effort is provided by the CAIDA grant
   NCR-9711092, and by CAIDA members.
</PRE>

<P>

After fetching the <CODE>coral</CODE> release from:


<P>

<PRE>   <A HREF="http://www.caida.org/tools/measurement/coralreef/dists/coral-3.4.1-public.tar.gz">http://www.caida.org/tools/measurement/coralreef/dists/coral-3.4.1-public.tar.gz</A>
</PRE>

<P>

install <CODE>ParseBGPDump.pm</CODE> in FlowScan's perl include path, such as in the <CODE>bin</CODE> sub-directory:


<P>

<PRE>   $ cd /tmp
   $ gunzip -c coral-3.4.1-public.tar.gz |tar x coral-3.4.1-public/./libsrc/misc-perl/ParseBGPDump.pm
   $ mv coral-3.4.1-public/./libsrc/misc-perl/ParseBGPDump.pm $PREFIX/bin/ParseBGPDump.pm
</PRE>

<P>

Also you must specify <A HREF="#item_TopN">TopN</A> to be greater than zero, e.g. 10, and the
<CODE>HTML::Table</CODE> perl module is required if you do so.


<P>

The <A HREF="#item_BGPDumpFile">BGPDumpFile</A> value is the name of a file containing the output of
<CODE>show ip bgp</CODE> from a Cisco router, ideally from the router that is exporting flows. If
this option is used, and the specified file exists, it will cause the
``originAS'' and ``pathAS'' reports to be generated. E.g.:


<P>

<PRE>   TopN 10
   BGPDumpFile etc/router.our.domain.bgp
</PRE>

<P>

One way to create the file itself, is to set up rsh access to your Cisco,
e.g.:


<P>

<PRE>   ip rcmd rsh-enable
   ip rcmd remote-host username 10.10.42.69 username
</PRE>

<P>

Then do something like this:


<P>

<PRE>   $ cd $PREFIX
   $ mkdir etc
   $ echo show ip bgp &gt;etc/router.our.domain.bgp # required by ParseBGPDump.pm
   $ time rsh router.our.domain &quot;show ip bgp&quot; &gt;&gt;etc/router.our.domain.bgp
      65.65s real     0.01s user     0.05s system
   $ wc -l /tmp/router.our.domain.bgp
    197883 /tmp/router.our.domain.bgp
</PRE>

<P>

Once <CODE>flowscan</CODE> is up and running with <A HREF="#item_BGPDumpFile">BGPDumpFile</A> configured, it will reload that file if its timestamp indicates that it has
been modified. This allows you to ``freshen'' the image of the routing
table without having to restart <CODE>flowscan</CODE> itself.


<P>

Using the <A HREF="#item_BGPDumpFile">BGPDumpFile</A> option causes <CODE>FlowScan</CODE> to use much more memory than usual. This memory is used to store a <CODE>Net::Patricia</CODE>
trie containing a node for every prefix in the BGP routing table. For
instance, on my system it caused the <CODE>FlowScan</CODE> process to grow to over 50MB, compared to less than 10MB without <A HREF="#item_BGPDumpFile">BGPDumpFile</A>
configured.


<P>

<DT><STRONG><A NAME="item_ASNFile">ASNFile

</A></STRONG><DD>
This directive is optional and is only useful in conjunction with
<A HREF="#item_BGPDumpFile">BGPDumpFile</A>. If specified, this directive will cause the AS names rather than just
their numbers to appear in the Top ASN HTML reports. Its value should be
the path to a file having the format of the file downloaded from this URL:


<P>

<PRE>   <A HREF="ftp://ftp.arin.net/netinfo/asn.txt">ftp://ftp.arin.net/netinfo/asn.txt</A>
</PRE>

<P>

E.g.:


<P>

<PRE>   TopN 10
   BGPDumpFile etc/router.our.domain.bgp
   ASNfile etc/asn.txt
</PRE>

<P>

Once <CODE>flowscan</CODE> is up and running with <A HREF="#item_ASNFile">ASNFile</A> configured, it will reload the file if its timestamp indicates that it has
been modified.


<P>

</DL>
<P>
<HR>
<H1><A NAME="METHODS">METHODS

</A></H1>
This module provides no public methods. It is a report module meant only
for use by <CODE>flowscan</CODE>. Please see the <CODE>FlowScan</CODE> module documentation for information on how to write a FlowScan report
module.


<P>

<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO

</A></H1>
<CODE>perl(1),</CODE> FlowScan, SubNetIO, <CODE>flowscan(1),</CODE>
Net::Patricia.


<P>

<P>
<HR>
<H1><A NAME="BUGS">BUGS

</A></H1>
When using the <A HREF="#item_BGPDumpFile">BGPDumpFile</A> directive, <CODE>ParseBGPDump</CODE> issues a bunch of warnings which can safely be ignored:


<P>

<PRE>   Failed to parse table version from: show ip bgp
    at (eval 4) line 1
   Failed to parse router IP address from: show ip bgp
    at (eval 4) line 1
   Nexthop not found:    Network          Next Hop            Metric LocPrf Weight Path
   $ at (eval 4) line 1
   Metric not found:    Network          Next Hop            Metric LocPrf Weight Path
   $ at (eval 4) line 1
   Local Preference not found:    Network          Next Hop            Metric LocPrf Weight Path
   $ at (eval 4) line 1
   Weight not found:    Network          Next Hop            Metric LocPrf Weight Path
   $ at (eval 4) line 1
   Origin code not found:    Network          Next Hop            Metric LocPrf Weight Path
   $ at (eval 4) line 1
   Possible truncated file, end-of-dump prompt not found
    at (eval 4) line 1
</PRE>

<P>

I'm not keen on patching <CODE>ParseBGPDump</CODE> to fix this since its license isn't compatible with the GPL. We probably
just need to hack up a complete replacement for <CODE>ParseBGPDump</CODE>.


<P>

When using the <A HREF="#item_BGPDumpFile">BGPDumpFile</A> directive, <CODE>ParseBGPDump</CODE> sometimes mistakes the <CODE>Weight</CODE> for the first ASN in the path. This has the totally undesirable effect of
producing a ``Top Path ASNs'' report that erroneously reports the weight as
one of the Top ASNs! I assume this is an indication of the difficulty of
parsing the output of <CODE>show ip
bgp</CODE>, which apparently was meant for human consumption.


<P>

When using the <A HREF="#item_ASPairs">ASPairs</A> directive, CampusIO will create RRD files that have a <CODE>:</CODE> character in the file name. While RRDTool is able to create RRD files with
those names, it is not able to graph from them. To work around this
problem, create symbolic links in your <A HREF="#item_OutputDir">OutputDir</A>
before attempting to graph from these files. For example:


<P>

<PRE>   $ ln -s 0:n.rrd Us2Them.rrd
   $ ln -s n:0.rrd Them2Us.rrd
</PRE>

<P>

<P>
<HR>
<H1><A NAME="AUTHOR">AUTHOR

</A></H1>
Dave Plonka <A
HREF="MAILTO:<plonka@doit.wisc.edu>"><plonka@doit.wisc.edu></A>


<P>

Copyright (C) 1998-2001 Dave Plonka. This program is free software; you can
redistribute it and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.


<P>

<P>
<HR>
<H1><A NAME="VERSION">VERSION

</A></H1>
The version number is the module file RCS revision number (<STRONG>$Revision: 1.63 $</STRONG>) with the minor number printed right justified with leading zeroes to 3
decimal places. For instance, RCS revision 1.1 would yield a package
version number of 1.001.


<P>

This is so that revision 1.10 (which is version 1.010), for example, will
test greater than revision 1.2 (which is version 1.002) when you want to <STRONG>require</STRONG> a minimum version of this module.


<P>

</DL>
    </BODY>

    </HTML>
flowscan 1.006-13.2 / usr / share / doc / flowscan / html / CampusIO.html
