DragonFly On-Line Manual Pages
ipaudit(1) DragonFly General Commands Manual ipaudit(1)
NAME
ipaudit - IP traffic summarizer
SYNOPSIS
ipaudit -CHLNcefgiolmprstwx INTERFACE[:INTERFACE[: .. ] ]
DESCRIPTION
ipaudit is an IP traffic monitor. It listens to a network interface in
promiscuous mode (or reads data previously dumped to a file) and
tallies the total traffic for every "connection". A connection is a
combination of ip address pairs, protocol and for tcp/udp protocols,
the ports numbers.
OUTPUT
If hosts 105.33.41.107 telnets to 211.117.5.11 this creates a single
connection. ipaudit will tally the total bytes of traffic and total
packet count in each direction between the two hosts.
When ipaudit reports its findings, this telnet connection will be
listed as
105.033.041.107 211.117.005.011 6 1105 23 19934 2993 41 33
The columns are (1) host 1 ip (2) host 2 ip, (3) protocol, (4) host 1
port, (5) host 2 port, (6) host 1 bytes received, (7) host 2 bytes
received, (8) host 1 packets received, (9) host 2 packets received.
For protocol other then tcp/udp where there are no ports, the port
numbers are set to 0 in the output. Note that the host ip octets are
padded on the left with 0 to make 3 digits. This help make the output
more readable.
As another example, if the first host now sends 10 ping packets to a
non-existent host 105.33.41.188 then it will be reported as an output
line
105.033.041.107 105.033.041.188 1 0 0 0 680 0 10
This says that address 105.33.41.188 received 680 bytes in 10 packets
of protocol 1 - even though there is no such address!
The output is extended using the options. The -t option adds the
connection starting and ending times to each output line, for example
105.033.041.107 211.117.005.011 6 1105 23 19934 2993 41 33
14:01:32.0495 14:04:23.9491 2 1
The -e option adds the Ethernet address for the two hosts to each
output line,
105.033.041.107 211.117.005.011 6 1105 23 19934 2993 41 33
005000c0fa45 005000d1cc21
COMMAND LINE OPTIONS
Causes ipaudit to ignore configuration file. See section on
CONFIGURATION FILE below.
Read configuration info from alternate configuration file.
interface
Network interface to read data from. If reading multiple
interfaces run them together with only a colon : (no spaces) in
between, like
ipaudit eth0:eth1:eth3
-G Ignore config file. See CONFIGURATION FILE section below.
-g config_file
Reads configuration from config_file. See CONFIGURATION FILE
section below.
-r dumpfile
Reads network info from dumpfile instead of reading live from
network. Such a dumpfile could have been produced by the
programs ipaudit , tcpdump or ethereal (http://www.zing.org)
among others. You can read from standard input using '-' as the
file name.
-c npacket
Terminate program after reading npacket packets.
-w dumpfile
Writes first nlen bytes of every packet to dumpfile (see -s
option about nlen). Can later be read by ipaudit , tcpdump ,
ethereal , etc. The -w option does not affect traffic analysis
- it will still take place. By default this writes ALL of the
packets to the file. Use the -p option to write traffic for
specific protocols and ports only. However the -p option does
not affect normal output, all packets are still logged and
stored. Contrast this with the -f option. The option -w- will
write packets to standard output where they can then be piped to
another program which reads pcap packets. See EXAMPLES section
below for an example of sending output from ipaudit to tcpdump
and also a second instance of ipaudit.
-p prot[,port..][:prot[,port..]..
Only dump packets with specific protocols and ports. For
example, -p1:6:17 dumps only packets with protocols 1 (icmp), 6
(tcp) and 17 (udp). You can also break down udp and tcp
packets by port numbers - for example -p1:6,21,23 will only dump
icmp packets, ftp packets (protocol 6, port 21) and telnet
packets (protocol 6, port 23).
-s nlen
Save no more than first nlen packet bytes. Default is 96,
minimum is 68.
-i pidfile
Save the program process id to pidfile. This is used to
terminate program execution when sampling time has expired. Use
command like
kill -2 `cat pidfile`
to signal ipaudit to stop. Once ipaudit receives this signal,
it will print a list of traffic that it has seen.
-l ip-range[:ip-range[:ip-range[..]]]
Normally, the two ip address within a line of output are printed
in ip sorted order. But if you are monitoring a link between
two networks, you might want the addresses of one (local)
network to come first on an output line. ip-range is list of ip
ranges that defines the local network. Any ip address in this
range is considered local and is printed first on the output
line. If neither or both ip address belongs to the group of ip-
range then they are printed in the default sorted order.
There can be many ip-ranges separate by colons. No spaces may
appear in the argument. Each ip-range can be either a single ip
address such as 127.0.0.23 which indicates a range of one, a
partial ip address such as 127.0.5 which indicates a range from
127.0.5.0 to 127.0.5.255, a low and high ip address separate by
a hypen (-), and a single ip address, a slash (/) and an integer
between 0 and 32 (a "net address") which indicates a network.
If you run ipaudit with the debug option (-d) the program will
print the entire list of ip ranges, so you can check their
values.
Here is a list of arguments to -l along with the corresponding
range.
COMMAND: ipaudit -l 137.99.11
RANGE: 137.99.11.0-137.99.11.255
COMMAND: ipaudit -l 137.99.11:127.0.5/23
RANGE: 137.99.11.0-137.99.11.255,127.0.4.0-127.0.5.255
COMMAND: ipaudit -l 127.1.5.17-127.1.7.131
RANGE: 127.1.5.17-127.1.7.131
The following example,
ipaudit -c 10000 -l 137.11 eth0
will tally 10,000 packets and list the results on-screen,
placing ip addresses beginning with 137.11 first on each output
line. Note that ipaudit pads the bytes with leading zeros, so
that the output will actually start like
137.011.nnn.nnn ...
You can turn off this padding with the -S option.
-m Does not turn on promiscuous mode on interface. By default
promiscuous mode is enabled. Note that interface may be in
promiscuous mode for other reasons.
-x program
After ipaudit ends, either from receiving a signal or reaching
its packet limit (-c option), call program. This option is
intend for calling reports scripts which read ipaudit output
after completion. You can send at most one argument to this
program, for example
ipaudit -c 10000 -x 'report traffic.out' -o traffic.out eth0
runs ipaudit for 10,000 steps, places the output in the file
traffic.out, and then calls the program 'report' with the
argument 'traffic.out' - telling 'report' where to find its
input file.
Note that to send an argument 'traffic.out' to 'report' we
needed to enclose both options together in a single pair of
quotes. Without the quotes -x would think that we were running
'report' without an option (and, the option traffic.out would be
interpreted as the network interface - not what you wanted at
all).
-o outfile
Writes traffic list to outfile upon completion. By default, it
writes traffic to stdout.
-t Adds packets connection times to each line of traffic output.
The time are in the format HH:MM:SS.SSSS where HH, MM and SS are
hours, minutes and seconds (to a precision of 1/10,000). The
first (second) time is the time the first (last) packet in the
connection was detected. This is followed by two integers
between 1 and 2. The first (second) integer is the source
machine of the first packet (second) packet. A 1 (2) means the
first (second) ip address on the line was the source.
-b Write traffic list in binary format (experimental).
-e Write Ethernet addresses for each host. Program stops with an
error if you are using a non-Ethernet interface.
-f Filter incoming packets according to filter string. For
example,
ipaudit -f "host 137.99.17.17" eth0
will pass the string "host 137.99.17.17" to the pcap library's
filter routine. Thus ipaudit will only see packets with
137.99.17.17 in one of the two ip addresses. The filter
commands are extensive and are explained fully in the tcpdump
man page.
Note that the -f command is different from the -p command. The
-f command filters packets before ipaudit reads them. Thus -f
affects what is stored in the normal output (directed by the -o
command) AND in the packet dump (directed by the -w command).
The -p command filter packets after ipaudit reads them, but
before it writes them to the dump file. Thus the normal output
(-o) is not affected, but the packet dump (-w) is.
-C Print ICMP type and code information in port field of the
sending IP address. By default the port fields are set to zero
for all ICMP (and all non-TCP and non-UDP traffic). Note that
ICMP type/code data is not like TCP/UDP port data, because each
IP address in an IP connection has its own port address. In the
ICMP case, the type/code info applies to the entire
'connection', not to just the sender or receiver. However, in
ipaudit output the type/code information is placed in the port
field of the packet sender when the -C option is used.
The type/code fields are each a byte, the port value is assigned
is the corresponding two byte value. The following table shows
the standard values (taken from TCP/IP Illustrated Vol 1, W.R.
Stevens)
0 Echo reply
768 Network unreachable
769 Host unreachable
770 Protocol unreachable
771 Port unreachable
772 Fragmentation needed but don't-fragment bit set
773 Source route failed
774 Destination network Unknown
775 Destination host Unknown
776 Source host isolated (obsolete)
777 Destination network administratively prohibited
777 Destination host administratively prohibited
778 Network Unreachable for TOS
779 Communication administratively prohited by filtering
780 Host precedence Violation
781 Precedence cutoff in effect
1024 Source quench
1280 Redirect for network
1281 Redirect for host
1282 Redirect for type-of-service and network
1283 Redirect for type-of-service and host
2048 Echo request
2304 Router advertisement
2560 Router solicitation
2816 Time-to-live equals 0 during transit
2817 Time-to-live equals 0 during reassembly
3072 IP header bad
3073 Required option missing
3328 Time stamp request
3584 Time stamp reply
3840 Information request (obsolete)
4096 Information reply (obsolete)
4352 Address mask request
4608 Address mask reply
-H Store host IPs only. On output the protocol and port fields
will be set to zero.
-L hostportlimit, hostlimit
Normally information is stored for every connection , which is a
combination of host ip addresses, protocol and ports. Sometimes
the traffic that is monitored will have a large number of
connections, for example when scans are taking place where the
ports numbers change repeatedly. hostportlimit sets a limit on
the number of connections stored with unique port addresses.
Otherwise ipaudit's hash table can overflow memory. When this
limit is exceeded, ipaudit will set all ports to zero and store
only host ips and protocols. Under some conditions even this
precaution is not enough, for example when a Denial of Service
attack where every packet has a unique forged source ip address.
hostlimit sets a limit on the number of unique host pairs which
are stored. When this limit is exceeded then every host ip is
stored as 0.0.0.0. Only the protocol number will remain
unchanged.
By default there is no hostportlimit or hostlimit. You might
want to set these limits. If so set them larger than your
typical connection count. In our case the connection count
never exceeds 200000 unless there is a DoS attack. The option
-L500000,100000 works for us.
-N n_hash_slots
ipaudit stores connections in a hash table. The number of slots
in this table is set when the program starts. Each slot can
hold multiple connections, and storage and retrieval become
inefficient when there are too few slots. You can control the
number of slots with this option. The default number of slots
(typically 1,000,000) is printed when the -v option is given.
-M See discussion below READING MULTIPLE NETWORK INTERFACES. The
-M option turns off ipaudit removal of duplicate packets.
-S By default ipaudit pads the ip addresses with leading zeroes,
for example
128.010.223.005
This option tells ipaudit to print ip addresses without leading
zeroes,
128.10.223.5
CONFIGURATION FILE
In addition to command line options you can use a configuration file.
When IPAUDIT starts it first looks for a file named "ipaudit.conf" in
the current directory, then in the home directory. You can also give
the '-g' (see COMMAND LINE OPTIONS above) to specify a configuration
file.
The configuration can contain comments beginning with #.
The options in the config file are specified by keyword/value pairs.
For example, to configure ipaudit to write the time information for
each connection the option is
writetime on
In keyword is 'writetime' and the option is 'on'. Many options are
either ON/OFF. The words TRUE, YES and OK are synonymous with ON. Any
other word means OFF.
Other options require one or more values, for example
interface eth0 eth1
tells ipaudit to read interfaces eth0 and eth1.
Below is a list of config file options:
interface i1 [i2] [i3]
List interface(s) to read packets from.
ethernet {on/off}
Like -e option, prints ethernet addresses on each connection
written. Default is off.
writetime {on/off}
Like -t option, writes times with connection data.
promisc {on/off}
Like -m option, puts interface(s) in promiscuous mode if on.
Default is on.
icmptype {on/off}
Like -C option, writes ICMP type and code information in port
field of the sending IP address.
hostonly {on/off}
Like -H option, Save and write information only for host pairs,
not for "connections", host pairs, protocols and ports.
hostip ip
Like -I option, tells ipaudit to write *all* packets (the first
length bytes as set by -s or packetlen options) for the host ip,
regardless of the setting for -p or saveport options.
hostportlimit hostportlimit hostlimit
Like -L option, sets limit for number of unique host-
pair/protocol/port connections, and a separate limit for the
number of unique host-pair connections.
hashslots nslots
Like the -N option, sets the number of slots in the hash table
used by ipaudit.
filter bpf_filter
Like -f option, specifies bpf filter.
progfile program_name
Like -x option, gives program name to run after ipaudit
completes.
pidfile file_name
Like -i option, write out file with process id.
readfile file_name
Like -r option, gives name of pcap packet capture file to be
read.
writefile file_name
Like -w option, gives name of pcap packet capture file to write.
savefile file_name
Like -w option, synonymous with the writefile config file option
above.
outfile file_name
Like -o option, name of output file for ipaudit output
count packet_limit
Like -c option, maximum number of packets to read.
saveport protocol>[,port[,port]..][:<protocol[,port[,port]..]]..
Like -p option, limits which protocols/ports packets must have
to be saved with writefile(savefile) option.
packetlen length
Like -s option, maximum number of bytes saved for each packet.
localrange ip_range
Like -l option, determines which range(s) of ip addresses are
considered local when writing ipaudit output.
shortip
Like -S option, prints ip addresses without leading 0s.
allowduplicate
Like -M option, turns off duplicate packet detection used when
reading multiple interfaces.
READING MULTIPLE NETWORK INTERFACES
ipaudit has the ability to read network data from more than one i
network interface at a time. You can specify multiple interfaces on
the command line such as
ipaudit -t eth0:eth1
with the interface names separated by colons (:). Also, in the config
file you use the interface option such as
interface eth0 eth1
There are some details to consider when monitoring multiple interfaces.
In particular there is the issue of double counting packets that travel
between interfaces. Consider the following example. Suppose you have
a router with four interfaces A, B, C and D. Interface A connects to
the Internet. Interfaces B, C and D connect to three separate internal
networks called Net-B, Net-C and Net-D. If Net-B sends a packet to
Net-C it will be seen twice. Once as it travels into the router
through interface B, and a second time when it travels out of the
router through interface C. If ipaudit simply recorded every packet
on every interface, it would have two copies of every packet that
travels between B and C. Similarly they would also be two copies of
every packet sent between B and D and between C and D. This is a
problem which ipaudit attempts to solve.
The solution is to record the interface for the first packet of each
connection. Then, subsequent packets for this connection are recorded
only if they are read from the same interface. In this way duplicate
packets are ignored.
This technique should work fine under normal circumstances, but it
fails when the hostportlimit is reached (see discussion about the -L
option). When the hostportlimit is reached ipaudit stops recording ip
addresses. In order to save memory it sets all ip address to 0.0.0.0.
The correct ip address is needed to successfully remove duplicate
packet information. When this information is lost many different
connections are stored together, making it impossible to remove
duplicate packets by noting which interface they were read from. If
you wish, you can run ipaudit without removing duplicate packets with
the -M option.
EXAMPLES
ipaudit -w dump.fil -p1:2:6,21,23 eth0
This runs tells ipaudit to write all packet header for icmp,
telnet, and ftp to dump.fil and to read traffic from the network
interface eth0. ipaudit will continue to run until it is
interrupted with control-C or the kill command, at which time it
will list on the terminal a summary of traffic that it saw.
ipaudit -i ipaudit.pid -o traffic.out le0
Read traffic from interface le0 and place in the file
traffic.out when program completes. The process id number is
written to ipaudit.pid at the program start. Thus you can
terminate ipaudit with the command kill -2 `cat ipaudit.pid`
ipaudit -c 50000 eth0 > traffic.out
Read 50,000 packets of traffic from eth0, pipe default stdout
output into file traffic.out.
ipaudit -w- -oipaudit.out eth0:eth1 | tcpdump -r- -wtest.cap port 23 or
port 111 or net 10.1.4
Reads data from interfaces eth0 and eth0 while writing output to
ipaudit.out. In addition raw packets are sent to standard out
(-w- option) and are piped to tcpdump. The trick here is that
tcpdump is used to write raw packets instead of ipaudit. The
advantage is that tcpdump offers finer control than ipaudit's -p
option over what packets are written to the capture file. In
this example it is necessary to write the ipaudit output
directly to file instead of to standard out (the default) so as
not to interfere with the packets written to standard out. You
could also use the BPF filters called by ipaudit to accomplish
the same thing,
ipaudit -w- -oipaudit.out eth0:eth1 | ipaudit -r- -wtest.cap -f
'port 23 or port 111 or net 10.1.4'
EXAMPLE OUTPUT
without -t option
192.051.201.068 192.051.201.076 6 2076 139 0 58 0 1
192.051.201.001 224.000.000.009 17 520 520 0 1092 0 2
192.051.091.021 192.051.091.127 17 138 138 0 243 0 1
192.051.221.242 192.051.221.255 17 138 138 0 248 0 1
192.051.201.021 192.051.201.070 17 123 123 180 180 2 2
Columns are ip address for first (second) machine, protocol number (1
is icmp, 6 is tcp, 17 is udp), udp/tcp ports on first (second) machine
(set to 0 if protocol not udp/tcp), bytes received by first (second)
machine, number of packets received by first (second) machine.
with -t option
192.051.201.068 192.051.201.076 6 2076 139 0 58 0 1 13:38:59.8229
13:38:59.8229 1 1
192.051.201.001 224.000.000.009 17 520 520 0 1092 0 2 13:38:59.1435
13:38:59.9248 1 1
192.051.091.021 192.051.091.127 17 138 138 0 243 0 1 13:38:56.5373
13:38:56.5373 1 1
192.051.221.242 192.051.221.255 17 138 138 0 248 0 1 13:38:54.7191
13:38:54.7191 1 1
192.051.201.021 192.051.201.070 17 123 123 180 180 2 2 13:38:54.6649
13:38:57.5350 2 1
As above but with the addition of time the first (last) packet was
detected, and the machine which sent the first (last) packet.
BUGS
Sometimes under Linux when reading lo and eth0 interfaces
simultaneously packets on the lo interface are dropped.
If a non-existant interface is specified then ipaudit refuses to read
*any* interface and gives no error message.
Hash table size is fixed at run-time. Would be nice to have
dynamically adjusted hash table size.
Report any bugs to jon.rifkin@uconn.edu. If possible, run with -d
option and email output. Thanks.
AUTHOR
j rifkin jon.rifkin@uconn.edu
http://www.sp.uconn.edu/~jrifkin
VERSION
0.95 Jan 19, 2001
SEE ALSO
ipstrings(1) total(1) tcpdump(1) pcap(3)
ipaudit 0.95 January 19, 2001 ipaudit(1)