Provided by: argus-client_2.0.6.fixes.1-3_amd64 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.