| RA(1) | General Commands Manual | RA(1) |
ra - read argus(8) data.
ra [raoptions] [-- filter-expression]
Ra reads argus(8) data from either stdin, an argus-file, or from a remote data source, which can either be an argus-server, or a netflow data 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 appends them into an argus(5) datafile.
"^SSH-" - Look for ssh connections on any port. "s:^GET" - Look for HTTP GET requests in the source buffer. "d:^HTTP.*Unauth" - Find unauthorized http response.
Depending on the regular expression library that the system supports, you will be able to match many types of binary, octal and hex expressions. See regex.3, pcre.3 and the web for examples.
Supported values are:
-1 Don't print header labels.
0 Print the header labels only once, as the beginning of output.
> 0 Print the header labels every n lines of output.
Provide addition mode operators. These are generally specific to the individual ra* program, or a specific function. Available modes for ra() are:Illegal modes are not detectable by the standard library, and so unexpected results in command line parsing may occur if care is not taken with use of this option.
disa - interpret DSCodepoints using the US DISA encodings dsrs=dsrlist - process these dsrs Where a dsrlist has the format: [+/-]dsr[,[+/-]dsr] Supported dsrs are: trans transport information, such as source id and seq number. flow flow key data (proto, saddr, sport, dir, daddr, dport) time time stamp fields (stime, ltime). metric basic ([s|d]bytes, [s|d]pkts, [s|d]rate, [s|d]load) agr aggregation stats (trans, avgdur, mindur, maxdur, stdev). net network objects (tcp, esp, rtp, icmp data). vlan VLAN tag data mpls MPLS label data jitter Jitter data ([s|d]jit, [s|d]intpkt) ipattr IP attributes ([s|d]ipid, [s|d]tos, [s|d]dsb, [s|d]ttl) psize packet size information mac MAC addresses (smac, dmac) icmp ICMP specific data (icmpmap, inode) encaps Flow encapsulation type indications behavior Behavioral metrics and data tadj Time adjustment data cor Multi-probe correlation data cocode Country Codes asn Autonomous System Number data suser src user captured data bytes (suser) duser dst captured user data bytes (duser) Examples are: -M dsrs=time,flow,metric -M dsrs=-suser,-duser label="regex" - match flow label with regex(3) regular expression. man - print management records noman - do not print management records oui - print oui labels in mac addresses printer="format" - specify printer formats for printing user data. Supported formats are: ascii print user buffer as ascii string. use '.' for unprintable chars. obfuscate ascii printer with password obfuscation. hex print hex dump of user buffer on separate lines. encode32 print user buffer as 32-bit chars. encode64 print user buffer using 64-bit chars. poll - successfully attach to remote data source and then exit rmon - modify data to support unidiretional RMON stat reporting rtime:factor - read data from a file, clocking records in as if they being read in realtime. Factor provides an opportunity to specify a multiplication factor, enabling you to read records in a fraction of real time, slowing down reading considerably, or a factor of time, enabling controlled speedup of the reading rate. saslmech="mech" - specify a mandatory SASL mech sql="select" - use "select" as select clause in mysql calls when supported. TZ="tzset" - specify a tzset(3) time zone specification uni - generate unidirectional flow data xml - print output in xml format.
Examples are:
-r file1 file2 read argus records from file1, then file2. -r file::34876 read argus records starting at byte offset 34876 -r file::34876:35846 read argus records starting at byte offset 34876 and ending at 35846 -r cisco:file read cisco netflow records from file -r ft:file read flow-tools based records
M - Maxiumum Segment Size
w - Window Scale
s - Selective ACK OK
S - Selective ACK
e - TCP Echo
E - TCP Echo Reply
T - TCP Timestamp
c - TCP CC
N - TCP CC New
O - TCP CC Echo
S - Source Explicit Congestion Notification
D - Destination Explicit Congestion Notification
ICMP intermediate node.
record byte offset in file or stream.
Mean of the flow packet size transmitted by the src (initiator).
Mean of the flow packet size transmitted by the dst (target).
histogram for the src packet size distribution
maximum packet size for traffic transmitted by the src.
histogram for the dst packet size distribution
maximum packet size for traffic transmitted by the dst.
minimum packet size for traffic transmitted by the src.
minimum packet size for traffic transmitted by the dst.
minimum packet size for traffic transmitted by the dst.
Examles are:
-s saddr print only the source address. -s -bytes removes the bytes field from list. -s +2srcid adds the source identifier as the 2nd field. -s spkts:18 prints src pkt count with a column width of 18. -s smpls print the local mpls label in the flow.
Examles are:
-S localhost request remote argus records from localhost, using default methods. -S user@localhost request argus records from localhost, as 'user'. -S user:pass@localhost request argus records from localhost, as 'user', with 'pass' password. -S 192.168.0.4:12345 request via TCP argus records from 192.168.0.4, port 12345. -S argus://user@anubis request argus records from anubis, via TCP port 561, as 'user'. -S argus-tcp://thoth:12345 request argus records via TCP from thoth, port 12345. -S argus-udp://set:12345 request argus records via UDP from set, port 12345. -S cisco://any:9996 read cisco netflow records from AF_ANY, on port 9996. -S jflow://10.0.0.2:9898 read jflow records sent to 10.0.0.2, on port 9898. -S sflow://localhost:6343 read sflow records sent to localhost interface, port 6343.
The syntax for the <time range> is:
[timeComparisonInd]timeSpecification[-timeSpecification]
timeComparisonInd: [x]i | n | c (default = i)
x negation reverses the result of the time comparison
i intersects match records that were active during this time period
n includes match records that start before and end after the period
c contained match records that start and end during the period
timeSpecification: [[[yyyy/]mm/]dd.]HH[:MM[:SS]]
[yyyy/]mm/dd
yyyy
%d{ymdHMS}
seconds
{ + | - }%d{ymdHMS}
where '*' can be used as a wildcard.
Examples are:
-t 14 specify the time range 2pm-3pm for today
-t 15-23 specify the time range 3pm-11pm for today
-t 2011 all records in the year 2011
-t 2011/08 all records in Aug of the year 2011
-t 2011/08-2011/10 all records in Aug, Sept, and Oct of the year 2011
-t **.14 specify 2pm-3pm, every day this month
-t 1270616652+2s all records that span 10/04/07.01:04:12 EDT.
-t 1999y1m23d10h matches 10-11am on Jan, 23, 1999
-t 10d*h*m15s matches records that intersect the 15 sec,
any minute, any hour, on the 10th of this month
-t ****/11/23 all records in Nov 23rd, any year
-t 23.11:10-14 11:10:00 - 2pm on the 23rd of this month
-t -10m matches 10 minutes before, to the present
-t -1M+1d matches the first day of the this month.
-t -2h5m+5m matches records that start before and end
after the range starting 2 hours 5 minutes
prior to the present, and lasting 5 minutes.
Time is compared using basic intersection operations. A record
iPntersects a specified time range if there is any intersection
between the time range of the record and the comparison time range.
This is the default behavior. A record includes the
comparison time range if the intersection of the two ranges equals
the comparison time, and a record is contained when
the intersection equals the duration of the record. The comparison
indicator is the first character of the range specification,
without spaces.
Examples are:
-t n14:10:15-14:10:19 records include these 4s.
-t c14:10-14:10:10 record starts and ends within these 10s.
-t xi-5s+25s record starts or ends 5 seconds earlier and
20 seconds after 'now'.
'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
'F' - Fin 'S' - Syn 'R' - Reset 'P' - Push 'A' - Ack 'U' - Urgent Pointer '7' - Undefined 7th bit set '8' - Undefined 8th bit set
ra exits with one of the following values:
0 Records matched condition, considering the options provided. 1 No records matched the condition, or the source was not an argus stream. > 1 An error occurred.
If arguments remain after option processing, the collection is interpreted as a single filter expression. In order to indicate the end of arguments, a '--' (double dash) is required before the filter expression is added to the command line. Historically, a '-' (single dash) was used to separate the filter expression from the command line options, but newer versions of getopt.1 now require the '--' (double dash).
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 a starting point for the argus(5) filter expression compiler. However, the semantics for tcpdump(1)'s packet filter expressions are different when applied to transaction record filtering, so there are some major differences.
When attached to a remote argus, ra will send the filter to the argus process, which compiles the filter, and uses it to select which argus records will be transmitted to the ra application. If you do not want to send a filter to the remote argus, prepend the filter with the keyword "local", to indicate that the filtering will be done within the local ra process.
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:
E.g., `srcid isis`, `encaps gre', `host sphynx', `net 192.168.0.0/16', `port domain', `ttl 1', 'ptks gt 2', 'ploss lt 5'. If there is no type qualifier, host is assumed.
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:
eth, mpls, 802q, llc, pppoe, isl, gre, erspan, ah, ipnip, ipnip6, hdlc, chdlc,
atm, sll, fddi, slip, arc, wlan, prism, avs, lrh, grh, teredo, udt, ipsec, juniper
True if the IP destination field in the Argus record is host, which may be either an address or a name.
True if the IP source field in the Argus record is host.
True if either the IP source or destination in 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
ether proto ip and host host
ether host ehost and not host host
tcp src port port
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, ecn, fin, finack, reset, retrans, outoforder and winshut
Primitives specific to TCP options are supported. tcpopt, mss, wscale, selackok, selack, tcpecho, tcpechoreply, tcptimestamp, tcpcc, tcpccnew, tcpccecho, secn and decn
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:
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
not host sphynx and host anubis
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.
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.
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
To report all UDP based DNS traffic, reading transaction data from the remote argus.server:
ra -S argus.server - udp port domain
To report all UDP transactions seen by the remote argus.server on the port range 53-256, but not sending the filter to the remote argus process:
ra -S argus.server - local udp port 53-256
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
Read an argus-file at twice normal speed.
ra -r argus.file -M rtime:2
The following is a brief description of the default output of .B
ra. While this is by no means the 'preferred' set of data that one should
generate, it represents a starting point for using flow data in general.
This also looks pretty good on 80 column terminals. The format is:
time flgs proto shost dir daddr metrics state
T - Time Corrected/Adjusted
N - Netflow Originated Data
* - Multiple sub-IP encapsulations
e - Ethernet encapsulated flow
E - ERSPAN encapsulation
M - Multiple mac addresses seen
m - MPLS encapsulated flow
l - LLC encapsulated flow
v - 802.1Q encapsulations/tags
w - 802.11 wireless encapsulation
p - PPP over Enternet encapsulated flow
i - ISL encapsulated flow
G - GRE encapsulation
a - AH encapsulation
P - IP tunnel encapsulation
6 - IPv6 tunnel encapsulation
H - HDLC encapsulation
C - Cisco HDLC encapsulation
A - ATM encapsulation
S - SLL encapsulation
F - FDDI encapsulation
s - SLIP encapsulation
R - ARCNET encapsulation
I - ICMP events mapped to this flow
U - ICMP Unreachable event mapped to this flow
R - ICMP Redirect event mapped to this flow
T - ICMP Time Exceeded mapped to this flow
* - Both Src and Dst loss/retransmission
s - Src loss/retransmissions
d - Dst loss/retransmissions
g - Gaps in sequence numbers were observed
& - Both Src and Dst packet out of order
i - Src packets out of order
r - Dst packets out of order
@ - Both Src and Dst Window Closure
S - Src TCP Window Closure
D - Dst TCP Window Closure
* - Silence suppression used by both src and dst (RTP)
s - Silence suppression used by src
d - Silence suppression used by dst
E - Both Src and Dst ECN
x - Src Explicit Congestion Notification
t - Dst ECN
V - Fragment overlap seen (if fragments seen)
f - Partial Fragment (if fragments seen)
F - Fragments seen
O - multiple IP options set
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
U - unknown IP options set
The 'src' is generally the entity that first transmits a packet that is a part of a flow. However, the assignment of 'src' and 'dst' semantics is somewhat complicated by the notion of loss, or half-duplex monitoring, especially when connection-oriented protocol , such as TCP, are reported. In this case the 'src' is the entity that initiated the flow.
- - transaction was NORMAL
| - transaction was RESET
o - transaction TIMED OUT.
? - direction of transaction is unknown.
For the ICMP and ICMPv6 protocols, the state field displays specific aspects of the ICMP type. ICMP state 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 MRQ Membership Query MHR Membership Report NRS Neighbor Discovery Router Solicit NRA Neighbor Discovery Router Advertisement NNS Neighbor Discovery Neighbor Solicit NNA Neighbor Discovery Neighbor Advertisement PTB Packet Too Big
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
Thu 12/29 06:40:32 tcp 132.3.31.15.6200 <| 12.23.14.77.25 RST
Thu 12/29 03:39:05 M igmp 12.88.14.10 <-> 128.2.2.10 CON
Thu 12/29 06:40:05 * tcp 12.23.14.23.1043 <-> 12.23.14.27.6000 TIM
Thu 12/29 07:42:09 udp 12.9.1.115.2262 -> 28.12.141.6.139 INT
Thu 12/29 06:42:09 icmp 12.9.1.115 <-> 12.68.5.127 ECO
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-tcp://argus-server and host i.qosient.com ra: Trying argus-server port 561 ra: connected Argus Version 3.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
Copyright (c) 2000-2016 QoSient. All rights reserved.
Carter Bullard (carter@qosient.com).
/etc/ra.conf
rarc(5) argus(8)
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.
| 12 November 2007 | ra 3.0.8 |