Content-type: text/html Manpage of stakstreams

stakstreams

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

NAME

stak - Statistical Traffic Analysis Kit  

SYNOPSIS

stakstreams [-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

stakstreams 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.

stakstreams determines flows, protocols or nodes causing the highest amount of traffic. This utility is higly experimental.

 

USAGE

stakstreams 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 STREAMTRAFFIC ANALYZER SPECIFIC OPTIONS are stakstreams-specific and do not apply to other stak utilities.

In this mode, stak tries to keep track of every TCP connection and UDP or ICMP stream present on the interface. Every detected conversation is allocated its own set of traffic counters; besides, stak attempts to identify common protocols (like HTTP or FTP). The feature is still experimental, and consumes HUGE amounts of system resources. Do not trust the -m and -f options, avoid leaving stakstreams somewhere in the background and without supervision.

The reports might be generated in three different ways:

host-oriented reports
a list of most active (or least active, depending on sorting options) hosts is printed, with an optional list of conversations below every entry.
stream-oriented reports
stakstreams print an overall list of most/least active streams.
protocol-oriented reports
show the mostly utilized protocols, with an optional list of conversations classified as a specific protocol below every entry.

 

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 '@'.
-c
Color (ANSI-compatible) output in modes that support it (currently: stream analyzer and "abusers detection" mode).
-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.
-n
Turns off asynchronous reverse DNS lookups. stak will print numeric IPs rather than fully qualified domain names.
-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.

 

STREAM TRAFFIC ANALYZER SPECIFIC OPTIONS

-z M
Limit memory used by the conversation engine to M kilobytes. When the amount of allocated memory gets beyond the set limit, a number of least active conversation is dropped. DO NOT trust this option.
-Z F
Drop F conversations after a memory overlimit. Default: 4000.
-u
Output resource usage statistics (CPU, memory) before every report.
-Y
Use tabs instead of spaces to separate columns.
-d
Increase verbosity level. This will print the guessed conversation protocol below every printed conversation entry. Again, please keep on mind that the stream analyzer feature is highly experimental, and it still lacks ability to recognize many common protocols. Only the basic ones (HTTP, FTP, FTP Data, POP3, SMTP) are supported for now. The remaining streams are classified as "Unknown" and "Unidentified".
-1 N
Node-driven reports. Print a list of N most/least active nodes (and, optionally, conversations associated with them)
-2 N
Stream-driven reports. Print a list of N most/least active streams.
-3 N
Protocol-driven reports. Output a list of N top protocols.
-b
Brief output. Supress the conversation lists - valid only for node and protocol driven reports.

Sorting options:

-R
Consider received data counters. Makes sense only for node-driven reports. This is the default.
-T
Consider sent data counters. As above, only for node-driven reports.
-M
Consider momentary counters (default).
-A
Consider overall counters.
-B
Consider byte counters (default).
-P
Consider packet counters.
-D
Descending sort - the most active hosts/nodes/protocols first. This is the default.
-N
Ascending sort - the least active hosts/nodes/protocols first.

 

BUGS AND LIMITATIONS

The TRAFFIC ANALYZER (stakstreams) operation mode is experimental. It consumes large amounts of system resources. Memory leaks in code that provides this feature are possible; besides, the code still needs a lot of improvements, as well as this manual page.

 

SEE ALSO

stakrate(1), stakhosts(1), stakasta(1), stak(1), stakextract(1), tcpdump(1), regex(7), pcap(3), bpf(4)

 

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

Copyright 2003 - 2004 Mateusz Golicz. All rights reserved.

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.


 

Index

NAME
SYNOPSIS
DESCRIPTION
USAGE
GENERIC OPTIONS
STREAM TRAFFIC ANALYZER SPECIFIC OPTIONS
BUGS AND LIMITATIONS
SEE ALSO
AUTHOR
LICENSE

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