Content-type: text/html Manpage of stakasta

stakasta

Section: User Commands (1)
Updated: 21-March-2004
Index Return to Main Contents

NAME

stak - Statistical Traffic Analysis Kit

SYNOPSIS

stakasta [-i <interface>] [-p <prefix>] [-s <snarflen>] [-r <n> | -g | -k] [-q <n>] [-lcvjx] [-X <expression> [-0 <c>]] [-f <filtering expression>] [-um] [-t <n> | -y <n>[,<n>[,<n>]]] [-a <filename>] [-I <class/mask>[,<class/mask>...]] [-O <class/mask>[,<class/mask>...]] [filename]

DESCRIPTION

stakasta is a part of the Statistical Traffic Analysis Kit (STAK), which is a set of utilities designed to help an administrator to figure out what is happening in his network at the moment.

stakasta determines the top ten (or other number of) autonomous systems sending and being addressed the highest amount of data. The utility needs a database of routes and, optionally, AS information; such a database might be obtained from your Regional Internet Registry (RIPE, ARIN, APNIC), however it must be processed into a form understandable by stakasta.

Tools for downloading and processing the European database are included in the stak package. You can find the file syntax in the DATA FILES section of this manual if you want to process and use the databases from other RIRs.

USAGE

stakasta accepts parameters in a standard, short getopt(3) form.

There are several options concerning the stak sniffer framework, common for the all stak utilities - these options have been described in the GENERIC OPTIONS section below.

The remaining options, described in the AS TRAFFIC ANALYZER SPECIFIC OPTIONS are stakasta-specific and do not apply to other stak utilities.

To operate properly, stakasta needs at least a database of routes, and optionally, to improve readability - a file containing autonomous systems' names. By default, these files are searched at /usr/local/stak/data.routes and /usr/local/stak/data.as respectively, but you could use any files, specyfing them on the command line. A typical invocation of stakasta would look like:

: # stakasta -i eth5 -r 1 ./data.routes
Received data : 4.34 MB (4549271 bytes, 11605 packets).
Transmitted data : 4.34 MB (4549271 bytes, 11605 packets).
Unidentified sources : 1.22 MB (1277646 bytes, 2939 packets, 28.08 %).
Unidentified destinations: 1.04 MB (1090355 bytes, 2966 packets, 23.97 %).
Source systems:
01 AS30851 Input @ 11.99 Mb/s (34.74 %) Output @ 12.80 Mb/s (37.08 %)
02 AS5617 Input @ 3.88 Mb/s (11.24 %) Output @ 1.53 Mb/s ( 4.42 %)
03 AS3301 Input @ 161.94 kb/s ( 0.46 %) Output @ 575.08 kb/s ( 1.63 %)
04 AS3320 Input @ 1.56 Mb/s ( 4.53 %) Output @ 565.28 kb/s ( 1.60 %)
05 AS12827 Input @ 168.03 kb/s ( 0.48 %) Output @ 495.42 kb/s ( 1.40 %)
(...)
Destination systems:
01 AS30851 Input @ 11.99 Mb/s (34.74 %) Output @ 12.80 Mb/s (37.08 %)
02 AS5617 Input @ 3.88 Mb/s (11.24 %) Output @ 1.53 Mb/s ( 4.42 %)
03 AS3320 Input @ 1.56 Mb/s ( 4.53 %) Output @ 565.28 kb/s ( 1.60 %)
04 AS12301 Input @ 458.75 kb/s ( 1.30 %) Output @ 7.32 kb/s ( 0.02 %)
05 AS3215 Input @ 450.11 kb/s ( 1.27 %) Output @ 201.39 kb/s ( 0.57 %)
(...)

This reads: the traffic seen on eth5 originates mainly (in 37.74%, twelve point eight megabits) from the AS30851 and is being send mainly to the same AS (in 34.74%). As one could easily guess, this is because the AS30851 is on the local net. The local net could be however excluded using the -I (ignore while accouting input) and -O (ignore while accouting output) options. In case of the author's network, something like:

: stakasta -i eth5 -r 1 -I 217.173.160.0/20,213.25.115.0/24,213.216.97.0/24,10.0.0.0/8 -O 217.173.160.0/20,213.25.115.0/24,213.216.97.0/24,10.0.0.0/8 ./data.routes

Would give a clearer image of the situation.

To print other number of most active systems, use the -t option. Also, the -m option can be specified to see the current output rates instead of the default, average ones.

Sometimes one is interested only in traffic exchange with some particular ASes. The -y option seems useful in such a case. To watch the localnet traffic exchange with AS8246, AS5617 and AS3301:

: stakasta -i eth5 -r 1 -y 8246,5617,3301

(assuming the data.routes is available in /usr/local/stak)

GENERIC OPTIONS

-0 c: Replace every NUL character (ASCII 0) with c before doing regular expression based matching. Ignored if the -x option was not specified. The default is '@'.
-f f: BPF filter expression to use. Using this option causes stak to ignore any packets not matching the specified BPF filter expression. For a detailed description of BPF filter expressions syntax, consult the tcpdump(1) manual page.
-g: Signal-based report generation policy. The reports are dumped whenever stak receives a SIGUSR1 signal.
-h -?: Print help. stak dumps a short help on available command-line options and quits, regardless of other options.
-i I: Bind to interface I. The default is 'eth0', which of course will cause a failure on systems other than Linux. Make sure you specify the datalink prefix (see -p) when you order stak to bind to an interface of an uncommon type.
-k: Interactive report generation. The reports are dumped whenever data is available on the standard input, which usually means you'll have to press RETURN in order to generate a report.
-l: Make stdout line-buffered. This option is useful when reports are redirected (eg. using shell redirection) to a file.
-p N: Datalink layer header prefix length. Every (or at least almost every) known datalink layer protocol prefixes a packet with its own header - which has to be stripped before the actual data essential for stak (the IP protocol header) can be read. stak is able to determine automatically how many bytes to skip only for the most common datalink layer protocols (Ethernet, FDDI, TokenRing, loopback, PPP) - in other cases the prefix length must be specified using this option. It is EXTREMELY IMPORTANT to set the right value - otherwise stak might print completely irrevelant reports and output invalid IP addresses. The default is autosense, or if that fails - 14 bytes, which is the length of an Ethernet header.
-q N: Orders stak to quit after outputting N reports.
-r N: Time-based report generation policy. The reports will be dumped on stdout every N seconds. This is the default (with N = 0.1).
-s N: Capture at least N bytes. For performance reasons, stak does not acquire the whole packet from network, it just reads and processes first N bytes. The default is 64 bytes, which might be not enough if you are using complicated BPF expressions or filtering the packets using a regular expression. In such cases, it is good to set the capture length to MTU on the interface. The value is automatically increased to at least 1500 (which is the default MTU for an Ethernet interface) if one of -x, -E or -T options is used. This option does NOT affect statistical data (amount of bytes, per-second byte rate) collected by stak - the accounted packet size is always the 'real' one.
-v: Print exact values. Normally, stak uses SI prefixes (like k - kilo, M - mega, G - giga, T - tera) to make the printed numeric values more attractive for a human being. The -v option disables this feature, causing stak to print exact values.
-x: Clear the screen before printing each report. This assumes your terminal is capable of understanding certain control sequences.
-X r: Regular expression-based filtering. This option will cause stak to ignore packets that DO NOT match specified regular expression. Before any tests, NUL characters occuring in a packet are replaced with an other character, as specified in the -0 option (the default is '@'). Consult regex(5) manual for a detailed description of POSIX regular expressions. In addition to standard regex syntax, you may use the \r (CR), \n (LF), \t (TAB), \\ (\) and \xNN (hex NN) special sequences.

AS TRAFFIC ANALYZER SPECIFIC OPTIONS

-u: Increase verbosity level while loading the data files. Useful for testing the databases.
-m: Show momentary traffic rates instead of the default average ones.
-t <n>: Show top N systems (default: 10)
-a <filename>: Load AS information from the specified file. See the DATA FILES section for the file format.
-y <ASN>[,<ASN>[,<ASN>...]]: Show only entries concerning the given ASes.
-I <class/mask>[,<class/mask>[,<class/mask>...]]: Do not account traffic directed to specified classes. Useful for eliminating your local network from the reports.
-O <class/mask>[,<class/mask>[,<class/mask>...]]: Like above, but concerns traffic originating from specified classes.

DATA FILES

The stakasta requires the database to be split into two files: one (mandatory) containing information on association between routes in the Internet and AS numbers (data.routes) and one (optional) containing ASes description (like the remark: field in the RIPE database) - data.as

Both files are fully plaintext and use a line-by-line data organisation approach. The data.routes is syntax is:

: <route> AS<number>
<route> AS<number>
(...)

for instance:

: 193.254.30.0/24 AS12726
212.166.64.0/19 AS12321
212.80.191.0/24 AS12541
195.2.0.0/19 AS1273 (...)

Similarily, the

data.as file consists of lines containing:

: AS<number> <information> [information [information]...]

eg.

: AS3255 UARNET-AS Ukrainian Academic and Research Network
AS6837 SWISSCOM-TRANSIT-AS Swisscom
AS20728 GUNESSIG Gunes Sigorta
AS15756 CARAVAN ISP CARAVAN

These data can be acquired from a Regional Internet Registry (a RIR) - depending on your

region, that would be RIPE NCC, ARIN, APNIC or LACNIC. Tools for downloading and converting the RIPE NCC database into format acceptable by stakasta are provided in the stak package. You are free to write your own tools to convert other RIRs databases and the author would be very grateful if you send such tools to him and allow to redistribute them in further versions of stak.

AUTHOR

Mateusz Golicz <ziewk@jaszczur.org>

Feel free to send comments, suggestions, bug reports, etc. The author is not a native english speaker, and is aware of the fact that his english is far from perfect. Because of that, reports on grammar or vocabulary mistakes in this manual are also welcome.

The asynchronous DNS resolver part was taken from mtr - a very handy traceroute replacement by Matt Kimball.

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, Version 2, as published by the Free Software Foundation. A copy of this license is distributed with this software in the file "COPYING".

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Read the file "COPYING" for more details.

This document was created by man2html, using the manual pages.
Time: 14:58:37 GMT, March 21, 2004