


ipaudit(1)					       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  num-
       bers.


OUTPUT
       If  hosts  105.33.41.107 telnets to 211.117.5.11 this cre-
       ates 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 out-
       put line, for example

       105.033.041.107 211.117.005.011 6 1105 23 19934 2993 41 33



ipaudit 0.95		   Jan 19, 2001				1





ipaudit(1)					       ipaudit(1)


       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 CONFIGU-
	      RATION 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 ethe-
	      real (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



ipaudit 0.95		   Jan 19, 2001				2





ipaudit(1)					       ipaudit(1)


	      traffic for  specific  protocols	and  ports  only.
	      However  the  -p option does not affect normal out-
	      put, all packets are still logged and stored.  Con-
	      trast 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 out-
	      put 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



ipaudit 0.95		   Jan 19, 2001				3





ipaudit(1)					       ipaudit(1)


	      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 sin-
	      gle ip address, a slash (/) and an integer  between
	      0	 and  32 (a "net address") which indicates a net-
	      work.  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 rea-
	      sons.


       -x program
	      After  ipaudit ends, either from receiving a signal
	      or reaching its packet limit (-c option), call pro-
	      gram.   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  traf-
	      fic.out eth0



ipaudit 0.95		   Jan 19, 2001				4





ipaudit(1)					       ipaudit(1)


	      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 traf-
	      fic  output.   The   time	  are	in   the   format
	      HH:MM:SS.SSSS  where  HH, MM and SS are hours, min-
	      utes 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  exten-
	      sive  and	 are  explained	 fully in the tcpdump man
	      page.

	      Note that the -f command is different from  the  -p



ipaudit 0.95		   Jan 19, 2001				5





ipaudit(1)					       ipaudit(1)


	      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  com-
	      mand).
	       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 val-
	      ues  (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 prohib-
	      ited
		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



ipaudit 0.95		   Jan 19, 2001				6





ipaudit(1)					       ipaudit(1)


	       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, pro-
	      tocol  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 con-
	      ditions 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  pro-
	      gram  starts.   Each slot can hold multiple connec-
	      tions, and storage and retrieval become inefficient
	      when  there are too few slots.  You can control the
	      number of slots  with  this  option.   The  default



ipaudit 0.95		   Jan 19, 2001				7





ipaudit(1)					       ipaudit(1)


	      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 lead-
	      ing 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 configu-
       ration  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 key-
       word/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.





ipaudit 0.95		   Jan 19, 2001				8





ipaudit(1)					       ipaudit(1)


       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 informa-
	      tion 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, pro-
	      tocols and ports.


       hostip ip
	      Like -I option, tells ipaudit to write *all*  pack-
	      ets  (the	 first length bytes as set by -s or pack-
	      etlen 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 connec-
	      tions.


       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.






ipaudit 0.95		   Jan 19, 2001				9





ipaudit(1)					       ipaudit(1)


       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  con-
	      fig 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]..][:<proto-
       col[,port[,port]..]]..
	      Like  -p option, limits which protocols/ports pack-
	      ets 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 detec-
	      tion used when reading multiple interfaces.



ipaudit 0.95		   Jan 19, 2001			       10





ipaudit(1)					       ipaudit(1)


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 multi-
       ple interfaces.	In particular there is the issue of  dou-
       ble counting packets that travel between interfaces.  Con-
       sider 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 ipau-
       dit 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  circum-
       stances,	 but  it  fails when the hostportlimit is reached
       (see discussion about the  -L  option).	 When  the  host-
       portlimit 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, mak-
       ing 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



ipaudit 0.95		   Jan 19, 2001			       11





ipaudit(1)					       ipaudit(1)


	      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  pro-
	      cess  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 tcp-
	      dump is used to write raw packets instead of  ipau-
	      dit.   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,



ipaudit 0.95		   Jan 19, 2001			       12





ipaudit(1)					       ipaudit(1)


       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 mes-
       sage.

       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		   Jan 19, 2001			       13


