Ubuntu Manpage: ra - read argus(8) data.

Provided by: argus-client_2.0.6.fixes.1-3_amd64

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