
	Aguri: An Aggregation-based Traffic Profiler

			version 0.7	March 13, 2003

    Aguri is an aggregation-based traffic profiler that records summary
    information of network traffic.
    Aguri can be used as a flexible traffic monitoring tool which covers
    a wide range of application, from short-term trouble detection to
    long-term trend monitoring.

    Aguri adapts itself to spatial traffic distribution by aggregating
    small spatial fractions so that it does not require any predefined rule.
    Thus, aguri is capable to detect unexpected increase of unknown
    protocols and DoS attacks.
    Temporal aggregation is achieved by creating a summary of summaries
    applying the same algorithm to its outputs.

    By default, aguri records 4 fields in an IPv4 or IPv6 packet, that is,
    source address, destination address, source port number, destination
    port number.

What's new since version 0.5:
	- agurify.pl is extended to plot graphs by default.
	- new 3D style graphs.
	- improved aggregation algorithm.
	- bpf filter supprt.
	- OpenBSD pflog support.
    Changes from version 0.5:
	- there is a change in the log directory.
	  the <interface> directory is added under the log directory
	  to support more than 2 interfaces.
		change from <aguri.log>/<year>/<month>/<day>/
		       to   <aguri.log>/<ifname>/<year>/<month>/<day>/
	- the default output interval is changed from 5 seconds to 10 seconds.
	- the dafault node number per tree is changed from 256 to 512.

Spatial aggregation:

    The basic algorithm of aguri is quite simple.
    If there is no resource constraints (e.g., memory consumption or
    execution time), we could profile every address occurrence in every
    packet, and then, aggregate addresses whose count is less than a
    threshold value.
    This approach is probably ok for post-analysis of a saved packet trace.
    However, for continuous real-time monitoring, aguri approximates the
    above algorithm in exchange for the precision, by keeping track of
    addresses in a radix (patricia) tree and managing leaf nodes using the
    least-recently-used (LRU) replacement policy.

    When a leaf node is reclaimed, the counter value of the node is
    aggregated to its parent node.  By doing this, counter values are
    never lost even though the granularity may be reduced.

    To produce a summary output, aguri walks the tree in the post-order and
    aggregates a node if its count is less than a threshold, or outputs the
    node information if the count is above the threshold.

    To continue profiling, it is enough to reset the counter of each node.
    The current tree and the LRU list are left as they are, and used for
    the next cycle.

    Aguri monitors network traffic using libpcap(3), and produces a
    summary when it receives a HUP signal.
    Periodic summaries can be obtained by sending HUP signals from
    cron(8) to the running aguri program.

Temporal aggregation:

    The same algorithm can be used to produce a summary of summaries.
    Aguri accepts its summary outputs as inputs so that a coarse-grained
    summary can be produced from fine-grained summaries.
    For example, a 1-hour-long summary can be created out of 60
    1-minute-long summaries.

Archive and Visualization:

    Scripts used to archive aguri outputs, and to plot graphs can be found
    under the "scripts" directory.  See "scripts/README" for more
    information.

Aguri Output Format:

    The aguri summary format consists of a header and a body.
    A header starts with "%!AGURI-1.0" and ends at the first blank line.
    A line starts with "%%" contains a predefined keyword.
    A line starts with "%" is a comment line.

    A body consists of blocks, each block consists of a type line and
    entry lines.

	[<type>]
	<entry-line>

   [<type>] is either [src address], [dst address], [ip:proto:srcport],
   or [ip:proto:dstport].
   <entry-line> looks like:
   
        150.65.0.0/16   13848361 (4.96%/7.04%)

   here
	<address>/<prefix> <byte-count> (<node>%/<sub-tree>%)
   a leaf nodes does't have "/<prefix>" and "/<sub-tree>%" so it looks like:
	<address> <byte-count> (<node>%)

   <ip:proto:port> types are similar to <address> types but "ip" represents
   the ip version (4 or 6), "proto" represents the protocol number (e.g.,
   6 for TCP), and "port" represents the port number for TCP or UDP.
   The three fields (8bits, 8 bits, 16bits, respectively) are concatenated
   into 32 bits and handled in a single tree.

Setting Parameters:

   There are several parameters that affect the granularity of aggregation:
       - the number of nodes in the tree
       - the threshold value
       - the length of a period
       - levels of time-scale aggregarion

   but aguri is not too sensitive to these parameters.
   If the counter value of a node is close to the threshold,
   the node could be aggregated by the given granularity.
   However, if the counter value is big enough, the node should not be
   aggregated regardless of the parameter setting.
   And this is the basic idea of the program, capturing a rough
   traffic profile by aggregating small fractions.


FAQ
    Q.	Where does the name of aguri come from?
    A.	From "aggregation".
	Aguri is also a (not-so-common) first name in Japanese.
	(you might remember a Japanse F-1 racer, Aguri Suzuki.)


Aguri is a product of WIDE Project, and written by Kenjiro Cho and
Ryo Kaizaki.
The latest version of aguri is available from
http://www.csl.sony.co.jp/~kjc/software.html

Send bug reports, suggestions, etc. to
	Kenjiro Cho
	kjc@csl.sony.co.jp
     and
	Ryo Kaizaki
	kaizaki@sfc.wide.ad.jp
