Content-type: text/html
Manpage of stakhosts
stakhosts
Section: User Commands (1)
Updated: 21-March-2004
Index
Return to Main Contents
NAME
stak - Statistical Traffic Analysis Kit
SYNOPSIS
stakhosts [-i <interface>] [-p <prefix>] [-s <snarflen>] [-r <n> | -g | -k] [-q <n>] [-lcvjx] [-X <expression> [-0 <c>]] [-f <filtering expression>] [-byt] [-a <n>] [-A | -M] [-P | -B] [-O | -I] <class/mask> [<class/mask> [<class/mask> ...]]
DESCRIPTION
stakhosts
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.
stakhosts
determines the top ten (or other number of) hosts in the local network generating the
highest traffic. Average or momentary, packet or byte and input or output traffic rates
might be considered while composing the host list.
USAGE
stakhosts
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
BANDWIDTH ABUSERS MODE SPECIFIC OPTIONS
are stakhosts-specific and do not apply to other
stak
utilities.
In order to make
stakhosts
operate properly, it is necessary to specify IP classes that
are considered
the local net.
Only hosts from these classes will appear on the report.
For instance, to print the top "bandwidth abusers" in 10.0.0.0/8,
you could use:
-
# stakhosts -i eth5 -cr 1 10.0.0.0/8
Momentary Rx Momentary Tx Average Rx Average Tx
Bps pps | Bps pps | Bps pps | Bps pps
10.69.0.23 41.72k 37.81 | 30.40k 42.79 | 48.29k 47.17 | 17.28k 33.27
10.67.0.22 40.79k 31.84 | 1.14k 18.91 | 34.92k 26.32 | 1.02k 16.88
10.70.0.58 24.61k 42.79 | 19.99k 48.76 | 14.03k 24.83 | 10.80k 28.30
10.67.0.7 22.07k 53.73 | 15.41k 47.76 | 15.46k 42.70 | 14.43k 44.19
10.70.0.114 20.11k 15.92 | 0.00 0.00 | 10.04k 7.94 | 0.00 0.00
10.70.0.184 15.58k 12.94 | 59.70 1.00 | 14.40k 13.90 |754.22 2.98
10.1.0.150 14.49k 11.94 | 1.70k 14.93 | 10.79k 8.94 | 1.20k 9.93
10.3.0.51 14.33k 22.89 | 4.27k 24.88 | 9.92k 21.35 | 4.84k 25.32
10.69.0.53 13.61k 9.95 |358.21 5.97 | 12.45k 9.43 |357.50 5.96
10.2.0.97 13.56k 12.94 |497.51 7.96 | 13.10k 11.92 |549.16 8.94
This reads: the most bandwith-consuming host in the 10.0.0.0/8 subnet
is 10.69.0.23, which receives currently 41.72 kilobytes per second and
transmits 30.40 kBps. The averages since the application startup
By default, the output is sorted by current byte input (rx) counters. This
behaviour can be changed using the
-A
(order by average rates),
-P
(order by packet counters),
-O
(order by output (tx) counters) options, for instance:
-
# stakhosts -i eth5 -cr 1 -PO 10.0.0.0/8 172.16.0.0/16
Would take the momentary transmit packet counters into consideration.
The
-b
option might be used to force
stakhosts
to present counters in bits per second instead of bytes per second. The amount
of hosts shown can be changed by using the
-a
option, to show the top 20 hosts:
-
# stakhosts -i eth5 -cr 1 -b -a 20 10.0.0.0/8
Options like
-y
or
-x
might be used to improve the readability, while the
-d
(dump) option makes the utility dump the counters in a form suitable for
further processing using tools like
awk
or
sed.
By default, transfers between hosts in the specified networks (ie. in 10.0.0.0/8) are
not taken into the consideration while updating the counters. To make them being
accounted too, use the
-C
option.
Like in case of every
stak
component, the processed packets are subject to packet filtering. For instance, by issuing
a command like:
-
# stakhosts -i eth5 -cr 1 -f 'tcp[13] & 2 != 0' -a 20 10.0.0.0/8
one could see the hosts generating the highest amount of TCP SYN packets (a likely
sources of DDoS attacks).
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.
BANDWIDTH ABUSERS MODE SPECIFIC OPTIONS
- -a N
-
-
Print N top nodes.
- -b
-
Use bit units. The output is to be presented in bits (b) rather than bytes (B).
- -d
-
Alternative ("dump") output format. Instead of showing top N nodes,
stakhosts
will dump the whole host list in a form that can be easily parsed by automated
tools. The output format is:
-
<host IP>:<overall input bytes #>:<overall output bytes #>:<momentary input bytes #>:<momentary output bytes #>:<overall packet input #>:<overall packet output #>:<momentary packet input #>:<momentary packet output #>
- -f
-
Print spaces instead of "pipes" (|) as column separators. Normally,
stakhosts
will use characters imitating a vertical line ('|') to separate columns in order to improve
readability. This option disables this feature.
- -C
-
Account local transfers too.
stakhosts
will also account 'local' transfers, ie. transfers between two hosts in IP classes specified. By default, such transfers are ignored.
- -t
-
Print total amount of transferred data instead of overall speed.
- -O
-
Consider overall transfer rates while sorting the host list.
- -M
-
Consider momentary transfer rates while sorting the host list (default).
- -P
-
Consider packet counters while sorting the host list.
- -B
-
Consider byte counters while sorting the list (default).
- -O
-
Consider output (TX) counters while sorting the list.
- -I
-
Consider input (RX) counters while sorting the list (default).
SEE ALSO
stakrate(1),
stak(1),
stakasta(1),
stakstreams(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
-
- BANDWIDTH ABUSERS MODE SPECIFIC OPTIONS
-
- SEE ALSO
-
- AUTHOR
-
- LICENSE
-
This document was created by
man2html,
using the manual pages.
Time: 14:59:02 GMT, March 21, 2004