Provided by: argus-client_2.0.6.fixes.1-3_i386 bug

NAME

       ra - read argus(8) data.

COPYRIGHT

       Copyright (c) 2000-2003 QoSient. All rights reserved.

SYNOPSIS

       ra
       ra [raoptions] [- filter-expression]

DESCRIPTION

       Ra  reads  argus(8)  data  from  either stdin, an argus-file, or from a
       remote argus-server, filters the records  it  encounters  based  on  an
       optional  filter-expression   and  either  prints  the  contents of the
       argus(5) records that it encounters to stdout or writes them  out  into
       an argus(5) datafile.

OPTIONS

       -A  When generating ASCII output, print the application byte counts.

       -b  Dump  the compiled transaction-matching code to standard output and
           stop.  This is useful for debugging filter expressions.

       -C [host:]<portnum>
           Indicate the optional host and required port number for the  remote
           Cisco  Netflow  record source.  This will cause ra(1) to open a UDP
           socket, binding on the host and supplied port, and attempt to  read
           Cisco Netflow records from the open socket.

       -d <bytes>
           Print  specified  number  of  <bytes>  from  the  user data capture
           buffer.  The <bytes> value can be a number, or an  expression  that
           specifies  the number of bytes for either the source or destination
           buffer.  Formats include:
              -d 32      print 32 bytes from the src and dst buffer
              -d s24     print 24 bytes from the src buffer
              -d d16     print 16 bytes from the dst buffer
              -d s32:d8  print 32 bytes from the src buffer and
                                8 bytes from the dst buffer

       -D <level>
           Print debug information corresponding  to  <level>  to  stderr,  if
           program   compiled   to  support  debug  printing.   As  the  level
           increases, so does the  amount  of  debug  information  ra(1)  will
           print.  Values range from 1-8.

       -E <file>
           When  using  a  filter  expression  at the end of the command, this
           option will cause ra(1) to write the records that are  rejected  by
           the filter into <file>

       -F <conffile>
           Use  <conffile>  as  a  source  of  configuration information.  The
           format of this file is identical to rarc(5).  The  data  read  from
           <conffile> overrides any prior configuration information.

       -h  Print an explanation of all the arguments.

       -n  Do  not  translate  host  and  service  numbers  to names. -nn will
           suppress translation of protocol numbers, as well.

       -p <digits>
           Print <digits> number of units of precision for fraction of time.

       -q  Run in quiet mode. Configure Ra to not print out  the  contents  of
           records.   This  can  be used with the -T and -a options to support
           aggregate activity without printing each input record.

       -r <file file ...> -
           Read data from <files> in the order presented on  the  commandline.
           ’-’ denotes stdin.  Because this option can have many arguments, it
           must be terminated with a ’-’.  The ’-’ of  subsequent  options  is
           sufficient.    Ra   can  read  gzip(1),  bzip2(1)  and  compress(1)
           compressed data files.

       -R  Print response data when available. This option  applies  to  ICMP,
           arp  and  BOOTP traffic to indicate the responses to these protocol
           specific queries.

       -s <[-][[+[#]]field ...> -
           Specify the fields to print. Ra uses a default printing field list,
           by  specifying a field you can replace this list completely, or you
           can modify the existing default print list, using the optional  ’-’
           and ’+[#]’ form of the command.  The available fields to print are:

              startime, lasttime, count, dur, avgdur,
              saddr, daddr, proto, sport, dport, ipid,
              stos, dtos, sttl, dttl, bytes, sbytes, dbytes,
              pkts, spkts, dpkts, load, loss, rate,
              srcid, ind, mac, dir, jitter, status, user,
              win, trans, seq, vlan, mpls

           Examles are:
              -s srcaddr    print only the source address.
              -s -bytes     removes the bytes field from list.
              -s +2srcid    adds MAC addresses as the 2nd field.
              -s mac pkts   prints MAC addresses and src and dst pkt counts.

       -S <host[:portnum]>
           Specify a remote argus-server <host>. Use the optional

       -t <timerange>
           Specify the <time range> for matching argus(5) records. The  syntax
           for the <time range> is:

           timeSpecification[-timeSpecification]
           timeSpecification: [[[yyyy/]mm/]dd.]hh[:mm[:ss]]
                                [yyyy/]mm/dd
                                -%d{yMdhms}

           Examples are:
              -t 14             matches 2pm-3pm any day
              -t 23.11:10-14    11:10:00 - 2pm on the 23rd
              -t 11/23          all records on Nov 23rd
              -t 1999/01/23.10  10-11am on Jan, 23, 1999
              -t -10m           matches 10 minutes before to the present
              -t -2h5m-2h       matches range between 2 hours 5 minutes before
                                until 2 hours before.

       -T <secs>
           Read argus(5) from remote server for <secs> of time.

       -u  Write out time values using UTC time format.

       -w <file>
           Write out matching data to <file>, in argus file format. An output-
           file of ’-’ directs ra to write the  argus(5)  records  to  stdout,
           allowing for "chaining" ra* style commands together.

       -z  Print Argus TCP state changes for each tcp transaction. Values are
             ’s’ - Syn Transmitted
             ’S’ - Syn Acknowledged
             ’E’ - TCP Established
             ’f’ - Fin Transmitted  (FIN Wait State 1)
             ’F’ - Fin Acknowledged (FIN Wait State 2)
             ’R’ - TCP Reset

       -Z <s|d|b>
           Print actual TCP flag values. <’s’rc | ’d’st | ’b’oth>.
             ’F’ - Fin
             ’S’ - Syn
             ’R’ - Reset
             ’P’ - Push
             ’A’ - Ack
             ’U’ - Urgent Pointer
             ’7’ - Undefined 7th bit set
             ’8’ - Undefined 8th bit set

FILTER EXPRESSION

       If   arguments  remain  after  option  processing,  the  collection  is
       interpreted as a single filter expression.  In order  to  indicate  the
       end  of arguments, a ’-’ is recommended before the filter expression is
       added to the command line.
       The filter expression specifies which argus(5) records will be selected
       for  processing.   If no expression is given, all records are selected,
       otherwise, only those records for which expression is  ‘true’  will  be
       printed.

       The  syntax is very similar to the expression syntax for tcpdump(1), as
       the tcpdump compiler was the basis for the argus(5)  filter  expression
       compiler.   The semantics for tcpdump(1)s packet filter expression are
       different when applied to transaction record filtering,  so  there  are
       some major differences.

       The  expression consists of one or more primitives.  Primitives usually
       consist of an id (name or number) preceded by one or  more  qualifiers.
       There are three different kinds of qualifier:

       type   qualifiers  say  what kind of thing the id name or number refers
              to.  Possible types are srcid, host, net, port, tos,  ttl,  vid,
              and mid.

              E.g., ‘srcid isis‘, ‘host sphynx’, ‘net 192.168’, ‘port domain’,
              ‘ttl 1’.  If there is no type qualifier, host is assumed.

       dir    qualifiers specify a particular  transfer  direction  to  and/or
              from  an  id.   Possible directions are src, dst, src or dst and
              src and dst.  E.g., ‘src sphynx’, ‘dst net 192.168’, ‘src or dst
              port  ftp’,  ‘src  and dst tos 0x0a’, ‘src or dst vid 0x12‘.  If
              there is no dir qualifier, src or dst is assumed.

       proto  qualifiers  restrict  the  match  to  a   particular   protocol.
              Possible values are those specified in the /etc/protocols system
              file.  When preceeded by ether, the protocol names  and  numbers
              that are valid are specified in ./include/ethernames.h.

       In  addition  to the above, there are some special ‘primitive’ keywords
       that don’t follow the pattern: gateway, multicast, and broadcast.   All
       of these are described below.

       More complex filter expressions are built up by using the words and, or
       and not to combine primitives.  E.g., ‘host foo and not  port  ftp  and
       not  port  ftp-data’.  To save typing, identical qualifier lists can be
       omitted.  E.g., ‘tcp dst port ftp or ftp-data or domain’ is exactly the
       same  as  ‘tcp  dst  port  ftp or tcp dst port ftp-data or tcp dst port
       domain’.

       Allowable primitives are:

       srcid argusid
              True if the argus identifier field of the Argus record is srcid,
              which  may  be  an  IP  address, a name or a decimal/hexidecimal
              number.

       dst host host
              True if the IP destination field of the Argus  record  is  host,
              which may be either an address or a name.

       src host host
              True if the IP source field of the Argus record is host.

       host host
              True  if either the IP source or destination of the Argus record
              is host.  Any of the above host  expressions  can  be  prepended
              with the keywords, ip, arp, or rarp as in:
                   ip host host
              which is equivalent to:
                   ether proto \ip and host host
              If  host is a name with multiple IP addresses, each address will
              be checked for a match.

       ether dst ehost
              True if the ethernet destination address is ehost.  Ehost may be
              either  a  name from /etc/ethers or a number (see ethers(3N) for
              numeric format).

       ether src ehost
              True if the ethernet source address is ehost.

       ether host ehost
              True if either the ethernet source  or  destination  address  is
              ehost.

       gateway host
              True  if  the  transaction  used  host  as a gateway.  I.e., the
              ethernet source or destination address was host but neither  the
              IP  source nor the IP destination was host.  Host must be a name
              and must be found  in  both  /etc/hosts  and  /etc/ethers.   (An
              equivalent expression is
                   ether host ehost and not host host
              which  can  be  used  with  either  names  or numbers for host /
              ehost.)

       dst net net
              True if the IP destination address of the  Argus  record  has  a
              network number of net, which may be either an address or a name.

       src net net
              True if the IP source address of the Argus record has a  network
              number of net.

       net net
              True if either the IP source or destination address of the Argus
              record has a network number of net.

       dst port port
              True if the network transaction is ip/tcp or ip/udp  and  has  a
              destination  port  value of port.  The port can be a number or a
              name used in /etc/services (see tcp(4P) and udp(4P)).  If a name
              is  used,  both  the port number and protocol are checked.  If a
              number or ambiguous name  is  used,  only  the  port  number  is
              checked  (e.g.,  dst  port 513 will print both tcp/login traffic
              and udp/who traffic, and port domain will print both  tcp/domain
              and udp/domain traffic).

       src port port
              True if the network transaction has a source port value of port.

       port port
              True if either the source  or  destination  port  of  the  Argus
              record  is  port.   Any  of  the  above  port expressions can be
              prepended with the keywords, tcp or udp, as in:
                   tcp src port port
              which matches only tcp connections.

       ip proto protocol
              True if the Argus record is an ip transaction  (see  ip(4P))  of
              protocol  type protocol.  Protocol can be a number or any of the
              string values found in /etc/protocolsk.

       multicast
              True  if  the  network  transaction  involved  an  ip  multicast
              address.   By  specifing  ether  multicast, you can select argus
              records that involve an ethernet multicast address.

       broadcast
              True  if  the  network  transaction  involved  an  ip  broadcast
              address.   By  specifing  ether  broadcast, you can select argus
              records that involve an ethernet broadcast address.

       ether proto protocol
              True if the Argus record is of ether  type  protocol.   Protocol
              can  be  a  number  or a name like ip, arp, or rarp.  Note these
              identifiers are also keywords and must be escaped via  backslash
              (\).

       dst ttl number
              True if the destination TTL of the Argus record equals number.

       src ttl number
              True if the source TTL of the Argus record equals number.

       ttl number
              True if either the source or destination TTL of the Argus record
              equals number.

       dst tos number
              True if the destination TOS of the Argus record equals number.

       src tos number
              True if the source TOS of the Argus record equals number.

       tos number
              True if either the source or destination TOS of the Argus record
              equals number.

       dst vid number
              True  if  the  destination  VLAN  id  of the Argus record equals
              number.

       src vid number
              True if the source VLAN id of the Argus record equals number.

       vid number
              True if either the source or destination VLAN id  of  the  Argus
              record equals number.

       dst mid number
              True  if  the  destination MPLS Label of the Argus record equals
              number.

       src mid number
              True if the source MPLS Label of the Argus record equals number.

       mid number
              True if either the source or destination MPLS Label of the Argus
              record equals number.

       Ra filter expressions support primitives  that  are  specific  to  flow
       states and can be used to select flow records that were in these states
       at the time they were generated.  normal, wait, timeout, est or con

       Primitives that select flows that experienced fragmentation.  frag  and
       fragonly

       Support  for  selecting flows that used multiple pairs of MAC addresses
       during their lifetime.  multipath

       Primitives specific to TCP flows are  supported.   syn,  synack,  data,
       ecn, fin, finack, reset, retrans, outoforder and winshut

       Primitives  specific  to  ICMP  flows  are  supported.   echo, unreach,
       redirect and timexed

       For some primitives, a direction qualifier is appropriate.   These  are
       frag, reset, retrans, outoforder and winshut

       Primitives may be combined using:

              A  parenthesized  group of primitives and operators (parentheses
              are special to the Shell and must be escaped).

              Negation (‘!’ or ‘not’).

              Concatenation (‘and’).

              Alternation (‘or’).

       Negation has highest precedence.  Alternation  and  concatenation  have
       equal  precedence  and associate left to right.  Note that explicit and
       tokens, not juxtaposition, are now required for concatenation.

       If an identifier is given without a keyword, the most recent keyword is
       assumed.  For example,
            not host sphynx and anubis
       is short for
            not host sphynx and host anubis
       which should not be confused with
            not ( host sphynx or anubis )

       Expression arguments can be passed to ra(1) as either a single argument
       or as multiple arguments, whichever is more convenient.  Generally,  if
       the  expression  contains Shell metacharacters, it is easier to pass it
       as a single, quoted argument.  Multiple arguments are concatenated with
       spaces before being parsed.

   Startup Processing
       Ra  begins  by  searching for the configuration file .rarc first in the
       directory, $ARGUSHOME and  then  $HOME.   If  a  .rarc  is  found,  all
       variables specified in the file are set.

       Ra  then parses its command line options and set its internal variables
       accordingly.

       If a configuration file is specified on the command-line, using the "-f
       <confile>"  option,  the  values in this .rarc formatted file superceed
       all other values.

EXAMPLES

       To report all TCP  transactions  from  and  to  host  ’narly.wave.com’,
       reading transaction data from argus-file argus.data:
              ra -r argus.data - tcp and host narly.wave.com

       Create  the argus-file icmp.log with all ICMP events involving the host
       nimrod, using data from argus-file, but reading  the  transaction  data
       from stdin:
              cat argus-file | ra -r - -w icmp.log - icmp and host nimrod

OUTPUT FORMAT

       The  following  is a brief description of the output format of ra which
       reports transaction data in various  levels  of  detail.   The  general
       format is:
                time proto  srchost  dir  dsthost  [count] status

       time
           The  format of the time field is specified by the .rarc file, using
           syntax supported by the  routine  localtime(3V).   The  default  is
           Argus   transaction   data   contains   both  starting  and  ending
           transaction times, with precision to the microsecond.  However,  ra
           prints  out  only one of these dates depending on the status of the
           argus server.  When the argus server is running in default mode, ra
           reports  the  transaction  starting  time.   When  the server is in
           DETAIL mode, the transaction ending time is reported.

       mac.addr
           mac.addr is  an  optional  field,  specified  using  the  -m  flag.
           mac.addr  represents the first source and destination MAC addresses
           seen for a particular transaction.  These addresses are paired with
           the  host.port  fields,  so  the  direction  indicator is needed to
           distinguish between the source and destination MAC addresses.

       proto [options protocol]
           The proto indicator consists of two fields. The first  is  protocol
           specific and the designations are:
             m       -  MPLS encapsulated flow
             q       -  802.1Q encapsulated flow
             p       -  PPP over Enternet encapsulated flow
             E       -  Multiple encapsulations/tags
              s      -  Src TCP packet retransmissions
              d      -  Dst TCP packet retransmissions
              *      -  Both Src and Dst TCP retransmissions
              i      -  Src TCP packets out of order
              r      -  Dst TCP packets out of order
              &      -  Both Src and Dst packet out of order
               S     -  Src TCP Window Closure
               D     -  Dst TCP Window Closure
               @     -  Both Src and Dst Window Closure
               x     -  Src TCP Explicit Congestion Notification
               t     -  Dst TCP ECN
               E     -  Both Src and Dst ECN
                M    -  Multiple physical layer paths
                 I   -  ICMP event mapped to this flow
                  S  -  IP option Strict Source Route
                  L  -  IP option Loose Source Route
                  T  -  IP option Time Stamp
                  +  -  IP option Security
                  R  -  IP option Record Route
                  A  -  IP option Router Alert
                  O  -  multiple IP options set
                  E  -  unknown IP options set
                   F -  Fragments seen
                   f -  Partial Fragment
                   V -  Fragment overlap seen

           The   second  field  indicates  the  upper  protocol  used  in  the
           transaction.  This field will contain the first 4 characters of the
           official name for the protocol used, as defined in RFC-1700.  Argus
           attempts to discovery the Realtime Transport Protocol, when  it  is
           being  used.   When  it encounters RTP, it will indicate its use in
           this field, with the string ’rtp’.  Use of  the  -n  option,  twice
           (-nn), will cause the actual protocol number to be displayed.

       host
           The  host  field  is protocol dependent, and for all protocols will
           contain the IP address/name.  For TCP and UDP, the field will  also
           contain the port number/name, separated by a period.

       dir
          The  dir field will have the direction of the transaction, as can be
          best determined from the datum, and is used to indicate which  hosts
          are transmitting. For TCP, the dir field indicates the actual source
          of the TCP connection, and the center character indicating the state
          of the transaction.
               -  - transaction was NORMAL
               |  - transaction was RESET
               o  - transaction TIMED OUT.
               ?  - direction of transaction is unknown.

       count
           count  is  an optional field, specified using the -c option.  There
           are 4 fields that are produced.  The first 2 are the packet  counts
           and  the  last  2 are the byte counts for the specific transaction.
           The fields are paired with the previous host fields, and  represent
           the packets transmitted by the respective host.

       status
           The status field indicates the principle status for the transaction
           report, and is protocol dependent.  For all the  protocols,  except
           ICMP, this field reports on the basic state of a transaction.

         REQ|INT (requested|initial)
           This  indicates  that  this  is  the  initial  status  report for a
           transaction and is seen only when the  argus-server  is  in  DETAIL
           mode.    For  TCP  connections  this  is  REQ,  indicating  that  a
           connection is being requested.  For the  connectionless  protocols,
           such as UDP, this is INT.

         ACC (accepted)
           This  indicates that a request/response condition has occurred, and
           that a transaction has been detected between two hosts.   For  TCP,
           this indicates that a connection request has been answered, and the
           connection will be accepted.  This is only  seen  when  the  argus-
           server  is  in DETAIL mode.  For the connectionless protocols, this
           state indicates that  there  has  been  a  single  packet  exchange
           between   two  hosts,  and  could  qualify  as  a  request/response
           transaction.

         EST|CON (established|connected)
           This record type indicates that the reported transaction is active,
           and  has  been  established  or  is  continuing.   This  should  be
           interpreted as a status report of a currently  active  transaction.
           For  TCP, the EST status is only seen in DETAIL mode, and indicates
           that the three way handshake has been completed for a connection.

         CLO (closed)
           TCP specific, this record type indicates that  the  TCP  connection
           has closed normally.

         TIM (timeout)
           Activity  was  not  seen  relating  to this transaction, during the
           argus server’s timeout period for this protocol.   This  status  is
           seen  only  when  there were packets recorded since the last report
           for this transaction.

       For the ICMP protocol, the status field displays  specific  aspects  of
       the ICMP type.  ICMP status can have the values:

          ECO     Echo Request
          ECR     Echo Reply
          SRC     Source Quench
          RED     Redirect
          RTA     Router Advertisement
          RTS     Router Solicitation
          TXD     Time Exceeded
          PAR     Parameter Problem
          TST     Time Stamp Request
          TSR     Time Stamp Reply
          IRQ     Information Request
          IRR     Information Reply
          MAS     Mask Request
          MSR     Mask Reply
          URN     Unreachable network
          URH     Unreachable host
          URP     Unreachable port
          URF     Unreachable need fragmentation
          URS     Unreachable source failed
          URNU    Unreachable dst network unknown
          URHU    Unreachable dst host unknown
          URISO   Unreachable source host isolated
          URNPRO  Unreachable network administrative prohibited
          URHPRO  Unreachable host administrative prohibited
          URNTOS  Unreachable network TOS prohibited
          URHTOS  Unreachable host TOS prohibited
          URFIL   Unreachable administrative filter
          URPRE   Unreachable precedence violation
          URCUT   Unreachable precedence cutoff

OUTPUT EXAMPLES

       These  examples  show  typical  ra output, and demonstrates a number of
       variations seen in argus data.  This ra output was generated using  the
       -n option to suppress number translation.

 Thu 12/29 06:40:32   S tcp  132.3.31.15.6439   -> 12.23.14.77.23   CLO
       This   is  a  normal  tcp  transaction  to  the  telnet  port  on  host
       12.23.14.77.  The IP Option strict source route was seen.

 Thu 12/29 06:40:32     tcp  132.3.31.15.6200  <|  12.23.14.77.25   RST
       This tcp transaction from the smtp port of host 12.23.14.77 was  RESET,
       indicating that the transaction was denied.

 Thu 12/29 03:39:05  M  igmp 12.88.14.10       <-> 128.2.2.10       CON
       This  is  an  igmp  transaction  status report, usually seen with MBONE
       traffic.  There was more than one source and  destination  MAC  address
       pair  used  to  support  the transaction, suggesting a possible routing
       loop.

 Thu 12/29 06:40:05 *   tcp  12.23.14.23.1043  <-> 12.23.14.27.6000 TIM
       This is an X-windows transaction, that  has  TIMEDOUT.    Packets  were
       retransmitted during the connection.

 Thu 12/29 07:42:09     udp   12.9.1.115.2262   -> 28.12.141.6.139  INT
       This  is  an  initial netbios UDP transaction status report, indicating
       that this is the first datagram encountered for this transaction.

 Thu 12/29 06:42:09     icmp  12.9.1.115       <-> 12.68.5.127      ECO
       This example represents a "ping" of host 12.9.1.115, and its  response.

 This  next example shows the ra output of a complete TCP transaction, with the
 preceeding Arp and DNS requests, while reading  from  a  remote  argus-server.
 The  ’*’  in  the  CLO  report  indicates  that  at  least  one TCP packet was
 retransmitted during the transaction.   The  hostnames  in  this  example  are
 ficticious.

 % ra -S argus-server and host i.qosient.com
 ra: Trying argus-server port 561
 ra: connected Argus Version 2.0
 Sat 12/03 15:29:38     arp  i.qosient.com     who-has  dsn.qosient.com  INT
 Sat 12/03 15:29:39     udp  i.qosient.com.1542  <->    dns.qosient.53   INT
 Sat 12/03 15:29:39     arp  i.qosient.com     who-has  qosient.com      INT
 Sat 12/03 15:29:39 *   tcp  i.qosient.com.1543   ->    qosient.com.smtp CLO

AUTHORS

       Carter Bullard (carter@qosient.com).

FILES

       /etc/ra.conf

SEE ALSO

       argus(8) tcpdump(1),

       Postel, Jon, Internet Protocol, RFC 791, Network Information Center, SRI
       International, Menlo Park, Calif., May 1981.

       Postel,  Jon,  Internet  Control  Message  Protocol,  RFC  792,  Network
       Information Center, SRI International, Menlo Park, Calif., May 1981.

       Postel, Jon, Transmission Control Protocol, RFC 793, Network Information
       Center, SRI International, Menlo Park, Calif., May 1981.

       Postel, Jon,  User  Datagram  Protocol,  RFC  768,  Network  Information
       Center, SRI International, Menlo Park, Calif., May 1980.

       McCanne,  Steven,  and  Van  Jacobson,  The  BSD  Packet  Filter:  A New
       Architecture for User-level Capture, Lawrwnce Berkeley  Laboratory,  One
       Cyclotron Road, Berkeley, Calif., 94720, December 1992.