1RA(1)                       General Commands Manual                      RA(1)
2
3
4

NAME

6       ra - read argus(8) data.
7

SYNOPSIS

9       ra [raoptions] [-- filter-expression]
10

DESCRIPTION

12       Ra  reads  argus(8)  data  from  either stdin, an argus-file, or from a
13       remote data source, which can either be an argus-server, or  a  netflow
14       data  server,  filters  the  records it encounters based on an optional
15       filter-expression and  either  prints  the  contents  of  the  argus(5)
16       records  that  it encounters to stdout or appends them into an argus(5)
17       datafile.
18

OPTIONS

20       -A  Print aggregate statistics for the input stream on termination.
21
22       -b  Dump the compiled transaction-matching code to standard output  and
23           stop.  This is useful for debugging filter expressions.
24
25       -c <char>
26           Specify a delimiter character for output columns (default is ' ').
27
28       -C <[host]:portnum> (deprecated)
29           Specify  a  source  of Netflow data. The optional host is the local
30           interface address where Netflow Cisco records are going to be read.
31           If absent, then it is implied that the interface address is AF_ANY.
32           This option is deprecated and the '-S cisco://address:port' is  now
33           the recommended option.
34
35       -D <level>
36           Print debug information corresponding to <level> to stderr, if pro‐
37           gram compiled to support debug printing.  As the  level  increases,
38           so  does  the amount of debug information ra(1) will print.  Values
39           range from 1-8.
40
41       -d  Toggle whether to run this program as a daemon.
42
43       -e <regex>
44           Match regular expression in flow user  data  fields.   Prepend  the
45           regex  with  either  "s:"  or "d:" to limit the match to either the
46           source or destination user data fields. At this time null bytes  in
47           the user data buffer terminate search.  Examples include:
48              "^SSH-"           - Look for ssh connections on any port.
49              "s:^GET"          - Look for HTTP GET requests in the source buffer.
50              "d:^HTTP.*Unauth" - Find unauthorized http response.
51
52           Depending  on  the  regular expression library that the system sup‐
53           ports, you will be able to match many types of  binary,  octal  and
54           hex expressions.  See regex.3, pcre.3 and the web for examples.
55
56
57       -E <file>
58           When  using  a  filter  expression  at the end of the command, this
59           option will cause ra(1) to append the records that are rejected  by
60           the filter into <file>
61
62       -F <conffile>
63           Use  <conffile> as a source of configuration information.  The for‐
64           mat of this file is identical  to  rarc(5).   The  data  read  from
65           <conffile> overrides any prior configuration information.
66
67       -h  Print an explanation of all the arguments.
68
69       -H  Abbreviate  numeric  metrics,  to make reading large values easier.
70           Use the -p <num> option to specify the precision right of the deci‐
71           mal.
72
73
74       -L <n>
75           Specify how ra will print header labels for the output.
76              Supported values are:
77                 -1  Don't print header labels.
78                  0  Print the header labels only once, as the beginning of output.
79                > 0  Print the header labels every n lines of output.
80
81
82       -M <mode [mode ...]>
83           Provide addition mode operators.  These are generally specific to the
84           individual ra* program, or a specific function. Available modes for ra()
85           are:
86
87              disa             - interpret DSCodepoints using the US DISA encodings
88              dsrs=dsrlist     - process these dsrs
89                 Where a dsrlist has the format:
90                    [+/-]dsr[,[+/-]dsr]
91
92                    Supported dsrs are:
93                      trans    transport information, such as source id and seq number.
94                      flow     flow key data (proto, saddr, sport, dir, daddr, dport)
95                      time     time stamp fields (stime, ltime).
96                      metric   basic ([s|d]bytes, [s|d]pkts, [s|d]rate, [s|d]load)
97                      agr      aggregation stats (trans, avgdur, mindur, maxdur, stdev).
98                      net      network objects (tcp, esp, rtp, icmp data).
99                      vlan     VLAN tag data
100                      mpls     MPLS label data
101                      jitter   Jitter data ([s|d]jit, [s|d]intpkt)
102                      ipattr   IP attributes ([s|d]ipid, [s|d]tos, [s|d]dsb, [s|d]ttl)
103                      psize    packet size information
104                      mac      MAC addresses (smac, dmac)
105                      icmp     ICMP specific data (icmpmap, inode)
106                      encaps   Flow encapsulation type indications
107                      behavior Behavioral metrics and data
108                      tadj     Time adjustment data
109                      cor      Multi-probe correlation data
110                      cocode   Country Codes
111                      asn      Autonomous System Number data
112                      suser    src user captured data bytes (suser)
113                      duser    dst captured user data bytes (duser)
114
115                 Examples are:
116                    -M dsrs=time,flow,metric
117                    -M dsrs=-suser,-duser
118
119              label="regex"    - match flow label with regex(3) regular expression.
120              man              - print management records
121              noman            - do not print management records
122              oui              - print oui labels in mac addresses
123
124              printer="format" - specify printer formats for printing user data.
125                 Supported formats are:
126                      ascii      print user buffer as ascii string. use '.' for unprintable chars.
127                      obfuscate  ascii printer with password obfuscation.
128                      hex        print hex dump of user buffer on separate lines.
129                      encode32   print user buffer as 32-bit chars.
130                      encode64   print user buffer using 64-bit chars.
131
132              poll             - successfully attach to remote data source and then exit
133              rmon             - modify data to support unidiretional RMON stat reporting
134              rtime:factor     - read data from a file, clocking records in as if they
135                                 being read in realtime.  Factor provides an opportunity
136                                 to specify a multiplication factor, enabling you to
137                                 read records in a fraction of real time, slowing down
138                                 reading considerably, or a factor of time, enabling
139                                 controlled speedup of the reading rate.
140
141              saslmech="mech"  - specify a mandatory SASL mech
142              sql="select"     - use "select" as select clause in mysql calls when supported.
143              TZ="tzset"       - specify a tzset(3) time zone specification
144              uni              - generate unidirectional flow data
145              xml              - print output in xml format.
146
147           Illegal  modes  are  not detectable by the standard library, and so
148           unexpected results in command line parsing may occur if care is not
149           taken with use of this option.
150
151       -n  Modify  number  to  name converstion.  This flag supports 4 states,
152           specified by the modulus of the number of -n flags set.  By default
153           ra*  programs  do  not provide hostname lookups, but they do lookup
154           port and protocol names.  The first -n will suppress port number to
155           service  conversion, -nn will suppress translation of protocol num‐
156           bers to names (no lookups).  -nnn will return you to  full  conver‐
157           sion,  translating  hostnames,  port  and protocol names, and -nnnn
158           will return you to the default behavior.   Because  this  indicator
159           can  be  set  in the .rarc file, multiple -n flags progress through
160           the cycle.
161
162       -N [io]<num>, [io]<start-end>, [io]<start+num>
163           Process the first <num> records, the inclusive range <start - end>,
164           or process <num + 1> records starting at index number <start>.  The
165           optional 1st  character  indicates  whether  the  specification  is
166           applied  to  the input or the output stream of records, the default
167           is input.  If applied to the input, these are the range of  records
168           that match the input filter.
169
170       -p <digits>
171           Print <digits> number of units of precision for floating point val‐
172           ues.
173
174       -q  Run in quiet mode. Configure Ra to not print out  the  contents  of
175           records.  This can be used for a number of maintenance tasks, where
176           you would be interested  in  the  outcome  of  a  program,  or  its
177           progress,  say  with  the  -D  option,  without printing each input
178           record.
179
180       -r [- | <[type:]file[::soffset[:eoffset]] ...>]
181           Read <type> data from <files> in the order presented on the comman‐
182           dline.  '-'  denotes  stdin.   Ra  supports reading argus type data
183           (default), cisco and ft, flow-tools type data.  If you want to read
184           a  set  of  files  and  then,  when  done, read stdin, use multiple
185           occurences of the -r option.  Ra can read gzip(1), bzip2(1),  xz(1)
186           and compress(1) compressed data files. Byte offset values allow the
187           specification of a range of records within  an  uncompressed  file.
188           Byte  offsets  must  be  aligned to record boundaries. Valid record
189           offsets can be obtained using +offset as an output field even  from
190           compressed files.
191
192           Examples are:
193              -r file1 file2              read argus records from file1, then file2.
194              -r file::34876              read argus records starting at byte offset 34876
195              -r file::34876:35846        read argus records starting at byte offset 34876 and ending at 35846
196              -r cisco:file               read cisco netflow records from file
197              -r ft:file                  read flow-tools based records
198
199
200       -R <dir dir ...>
201           Recursively  decend the directory and process all the regular files
202           that are encountered.  The function does not decend  to  links,  or
203           directories that begin with '.'.  The feature, like the -r command,
204           does not do any file type checking.
205
206       -s <[-][[+[#]]field[:len[:format]] ...>
207           Specify the fields to print.  ra.1 gets the field print list either
208           from its rarc configuration files or from the command-line.  In the
209           case where there is no configuration  given  ra.1  uses  a  default
210           printing  field  list, with default field lengths.  By specifying a
211           space separated list of fields, this option  provides  a  means  to
212           completely  redefine  the  list  from  the command line.  Using the
213           optional '-' and '+[#]' prepended to the field list, you can add or
214           subtract  fields  from the configured list.  Field lengths are hard
215           constraints, and field output that exceeds the field length will be
216           truncated,  and a '*' will be inserted as the last character.  When
217           you see this, add more to the length specification  for  that  spe‐
218           cific  field.   Field  lengths (len) less than 1, are not permitted
219           and will generate an error.  The optional  'format'  specification,
220           uses sprintf.1 syntax to format the value.  The available fields to
221           print are:
222
223           srcid       argus source identifier.
224           rank        Ordinal value of this output flow record i.e.  sequence
225                       number.
226           stime       record start time
227           ltime       record last time.
228           trans       aggregation record count.
229           flgs        flow state flags seen in transaction.
230           seq         argus sequence number.
231           dur         record total duration.
232           runtime     total  active  flow  run time.  This value is generated
233                       through aggregation, and is  the  sum  of  the  records
234                       duration.
235           idle        time  since  the  last  packet activity.  This value is
236                       useful in real-time processing, and is the current time
237                       - last time.
238           mean        average duration of aggregated records.
239           stddev      standard deviation of aggregated duration times.
240           sum         total accumulated durations of aggregated records.
241           min         minimum duration of aggregated records.
242           max         maximum duration of aggregated records.
243           smac        source MAC addr.
244           dmac        destination MAC addr.
245           soui        oui portion of the source MAC addr.
246           doui        oui portion of the destination MAC addr.
247           saddr       source IP addr.
248           daddr       destination IP addr.
249           proto       transaction protocol.
250           sport       source port number.
251           dport       destination port number.
252           stos        source TOS byte value.
253           dtos        destination TOS byte value.
254           sdsb        source diff serve byte value.
255           ddsb        destination diff serve byte value.
256           sco         source IP address country code.
257           dco         destination IP address country code.
258           sttl        src -> dst TTL value.
259           dttl        dst -> src TTL value.
260           shops       estimate of number of IP hops from src to this point.
261           dhops       estimate of number of IP hops from dst to this point.
262           sipid       source IP identifier.
263           dipid       destination IP identifier.
264           smpls       source MPLS identifier.
265           dmpls       destination MPLS identifier.
266           autoid      Auto generated identifier (mysql).
267           sas         Src origin AS
268           das         Dst origin AS
269           ias         Intermediate origin AS, AS of ICMP generator
270           cause       Argus  record cause code.  Valid values are Start, Sta‐
271                       tus, Stop, Close, Error
272           nstroke     Number of observed keystrokes.
273           snstroke    Number of observed keystrokes from initiator  (src)  to
274                       target (dst).
275           dnstroke    Number of observed keystrokes from target (dst) to ini‐
276                       tiator (src).
277           pkts        total transaction packet count.
278           spkts       src -> dst packet count.
279           dpkts       dst -> src packet count.
280           bytes       total transaction bytes.
281           sbytes      src -> dst transaction bytes.
282           dbytes      dst -> src transaction bytes.
283           appbytes    total application bytes.
284           sappbytes   src -> dst application bytes.
285           dappbytes   dst -> src application bytes.
286           pcr         producer consumer  ratio.
287           load        bits per second.
288           sload       source bits per second.
289           dload       destination bits per second.
290           loss        pkts retransmitted or dropped.
291           sloss       source pkts retransmitted or dropped.
292           dloss       destination pkts retransmitted or dropped.
293           ploss       percent pkts retransmitted or dropped.
294           psloss      percent source pkts retransmitted or dropped.
295           pdloss      percent destination pkts retransmitted or dropped.
296           retrans     pkts retransmitted.
297           sretrans    source pkts retransmitted.
298           dretrans    destination pkts retransmitted.
299           pretrans    percent pkts retransmitted.
300           psretrans   percent source pkts retransmitted.
301           pdretrans   percent destination pkts retransmitted.
302           sgap        source bytes missing  in  the  data  stream.  Available
303                       after argus-3.0.4
304           dgap        destination bytes missing in the data stream. Available
305                       after argus-3.0.4
306           rate        pkts per second.
307           srate       source pkts per second.
308           drate       destination pkts per second.
309           dir         direction of transaction
310           sintpkt     source interpacket arrival time (mSec)
311           sintdist    source interpacket arrival time distribution
312           sintpktact  source active interpacket arrival time (mSec)
313           sintdistact source active interpacket arrival time (mSec)
314           sintpktidl  source idle interpacket arrival time (mSec)
315           sintdistidl source idle interpacket arrival time (mSec)
316           dintpkt     destination interpacket arrival time (mSec)
317           dintdist    destination interpacket arrival time distribution
318           dintpktact  destination active interpacket arrival time (mSec)
319           dintdistact destination active interpacket arrival  time  distribu‐
320                       tion (mSec)
321           dintpktidl  destination idle interpacket arrival time (mSec)
322           dintdistidl destination idle interpacket arrival time distribution
323           sjit        source jitter (mSec).
324           sjitact     source active jitter (mSec).
325           sjitidle    source idle jitter (mSec).
326           djit        destination jitter (mSec).
327           djitact     destination active jitter (mSec).
328           djitidle    destination idle jitter (mSec).
329           state       transaction state
330           label       Metadata label.
331           suser       source user data buffer.
332           duser       destination user data buffer.
333           swin        source TCP window advertisement.
334           dwin        destination TCP window advertisement.
335           svlan       source VLAN identifier.
336           dvlan       destination VLAN identifier.
337           svid        source VLAN identifier.
338           dvid        destination VLAN identifier.
339           svpri       source VLAN priority.
340           dvpri       destination VLAN priority.
341           srng        start time for the filter timerange.
342           erng        end time for the filter timerange.
343           stcpb       source TCP base sequence number
344           dtcpb       destination TCP base sequence number
345           tcprtt      TCP  connection  setup  round-trip  time,  the  sum  of
346                       'synack' and 'ackdat'.
347           synack      TCP connection setup time, the time between the SYN and
348                       the SYN_ACK packets.
349           ackdat      TCP connection setup time, the time between the SYN_ACK
350                       and the ACK packets.
351           tcpopt      The TCP connection options  seen  at  initiation.   The
352                       tcpopt indicator consists of a fixed length field, that
353                       reports presence of any of the TCP options  that  argus
354                       tracks The format is:
355
356                        M            -  Maxiumum Segment Size
357                         w           -  Window Scale
358                          s          -  Selective ACK OK
359                           S         -  Selective ACK
360                            e        -  TCP Echo
361                             E       -  TCP Echo Reply
362                              T      -  TCP Timestamp
363                               c     -  TCP CC
364                                N    -  TCP CC New
365                                 O   -  TCP CC Echo
366                                  S  -  Source Explicit Congestion Notification
367                                   D -  Destination Explicit Congestion Notification
368
369           inode       ICMP intermediate node.
370           offset      record byte offset in file or stream.
371           smeansz     Mean of the flow packet size transmitted by the src (initiator).
372           dmeansz     Mean of the flow packet size transmitted by the dst (target).
373
374           spktsz      histogram for the src packet size distribution
375           smaxsz      maximum packet size for traffic transmitted by the src.
376           dpktsz      histogram for the dst packet size distribution
377           dmaxsz      maximum packet size for traffic transmitted by the dst.
378           sminsz      minimum packet size for traffic transmitted by the src.
379           dminsz      minimum packet size for traffic transmitted by the dst.
380
381           dminsz      minimum packet size for traffic transmitted by the dst.
382
383           Examles are:
384              -s saddr      print only the source address.
385              -s -bytes     removes the bytes field from list.
386              -s +2srcid    adds the source identifier as the 2nd field.
387              -s spkts:18   prints src pkt count with a column width of 18.
388              -s smpls      print the local mpls label in the flow.
389
390       -S <[URI://][user[:pass]@]host[:portnum]>
391           Specify  a remote source of flow data.  Read flow data from various
392           data format and transport strategies, using the URI format to indi‐
393           cate  the  type  of flow data record of interest (argus-tcp, argus-
394           udp, cisco, jflow, sflow) and the source, as a name or an addresss,
395           providing  an  option  user and password for protected access.  Use
396           the optional ':portnum' to specify a port  number  other  than  the
397           default; 561.
398
399           Examles are:
400              -S localhost                 request remote argus records from localhost, using default methods.
401              -S user@localhost            request argus records from localhost, as 'user'.
402              -S user:pass@localhost       request argus records from localhost, as 'user', with 'pass' password.
403              -S 192.168.0.4:12345         request via TCP argus records from 192.168.0.4, port 12345.
404              -S argus://user@anubis       request argus records from anubis, via TCP port 561, as 'user'.
405              -S argus-tcp://thoth:12345   request argus records via TCP from thoth, port 12345.
406              -S argus-udp://set:12345     request argus records via UDP from set, port 12345.
407              -S cisco://any:9996          read cisco netflow records from AF_ANY, on port 9996.
408              -S jflow://10.0.0.2:9898     read jflow records sent to 10.0.0.2, on port 9898.
409              -S sflow://localhost:6343    read sflow records sent to localhost interface, port 6343.
410
411
412       -t <timerange>
413           Specify the <time range> for matching argus(5) records. This option
414           supports a high degree of flexibility  in  specifing  explicit  and
415           relative time ranges with support for time field wildcarding.
416
417           The syntax for the <time range> is:
418           [timeComparisonInd]timeSpecification[-timeSpecification]
419              timeComparisonInd: [x]i | n | c    (default = i)
420                x  negation   reverses the result of the time comparison
421                i  intersects match records that were active during this time period
422                n  includes   match records that start before and end after the period
423                c  contained  match records that start and end during the period
424
425              timeSpecification: [[[yyyy/]mm/]dd.]HH[:MM[:SS]]
426                                   [yyyy/]mm/dd
427                                   yyyy
428                                   %d{ymdHMS}
429                                   seconds
430                                   { + | - }%d{ymdHMS}
431
432              where '*' can be used as a wildcard.
433
434           Examples are:
435              -t 14              specify the time range 2pm-3pm for today
436              -t 15-23           specify the time range 3pm-11pm for today
437              -t 2011            all records in the year 2011
438              -t 2011/08         all records in Aug of the year 2011
439              -t 2011/08-2011/10 all records in Aug, Sept, and Oct of the year 2011
440
441              -t **.14           specify 2pm-3pm, every day this month
442              -t 1270616652+2s   all records that span 10/04/07.01:04:12 EDT.
443              -t 1999y1m23d10h   matches 10-11am on Jan, 23, 1999
444              -t 10d*h*m15s      matches records that intersect the 15 sec,
445                                 any minute, any hour, on the 10th of this month
446              -t ****/11/23      all records in Nov 23rd, any year
447              -t 23.11:10-14     11:10:00 - 2pm on the 23rd of this month
448              -t -10m            matches 10 minutes before, to the present
449              -t -1M+1d          matches the first day of the this month.
450              -t -2h5m+5m        matches records that start before and end
451                                 after the range starting 2 hours 5 minutes
452                                 prior to the present, and lasting 5 minutes.
453
454           Time  is  compared  using  basic intersection operations.  A record
455           iPntersects a specified time range if  there  is  any  intersection
456           between the time range of the record and the comparison time range.
457           This is the default behavior.  A  record  includes  the  comparison
458           time range if the intersection of the two ranges equals the compar‐
459           ison time, and a record is contained when the  intersection  equals
460           the  duration of the record.  The comparison indicator is the first
461           character of the range specification, without spaces.
462
463           Examples are:
464              -t n14:10:15-14:10:19  records include these 4s.
465              -t c14:10-14:10:10     record starts and ends within these 10s.
466              -t xi-5s+25s           record starts or ends 5 seconds earlier and
467                                     20 seconds after 'now'.
468
469
470       -T <secs>
471           Read argus(5) from remote server for <secs> of time.
472
473       -u  Print time values using Unix time format (seconds from the Epoch).
474
475       -w <file> [filter-expression]
476           Append matching data to <file>, in argus file  format.  An  output-
477           file  of  '-'  directs  ra to write the argus(5) records to stdout,
478           allowing for "chaining" ra* style commands together.  The  optional
479           filter-expression can be used to select specific output.
480
481       -X  Resets  all  options to their default values and overrides the rarc
482           file contents (Use as the first option.)
483
484       -z  Modify status field to represent TCP state changes. The  values  of
485           the status field when this is enabled are:
486             's' - Syn Transmitted
487             'S' - Syn Acknowledged
488             'E' - TCP Established
489             'f' - Fin Transmitted  (FIN Wait State 1)
490             'F' - Fin Acknowledged (FIN Wait State 2)
491             'R' - TCP Reset
492
493       -Z <s|d|b>
494           Modify  status  field  to reprsent actual TCP flag values. <'s'rc |
495           'd'st | 'b'oth>.  The characters that can be present in the  status
496           field when this is enabled are:
497
498             'F' - Fin
499             'S' - Syn
500             'R' - Reset
501             'P' - Push
502             'A' - Ack
503             'U' - Urgent Pointer
504             '7' - Undefined 7th bit set
505             '8' - Undefined 8th bit set
506
507

RETURN VALUES

509       ra exits with one of the following values:
510
511          0  Records matched condition, considering the options provided.
512
513          1  No records matched the condition, or the source was not an argus stream.
514
515        > 1  An error occurred.
516
517

FILTER EXPRESSION

519       If  arguments  remain after option processing, the collection is inter‐
520       preted as a single filter expression.  In order to indicate the end  of
521       arguments,  a  '--' (double dash) is required before the filter expres‐
522       sion is added to the command line.  Historically, a '-'  (single  dash)
523       was  used  to  separate  the  filter  expression  from the command line
524       options, but newer versions of getopt.1 now require  the  '--'  (double
525       dash).
526
527
528       The filter expression specifies which argus(5) records will be selected
529       for processing.  If no expression is given, all records  are  selected,
530       otherwise,  only  those  records for which expression is `true' will be
531       printed.
532
533       The syntax is very similar to the expression syntax for tcpdump(1),  as
534       the  tcpdump  compiler  was  a  starting  point for the argus(5) filter
535       expression compiler.  However, the semantics  for  tcpdump(1)'s  packet
536       filter  expressions  are  different  when applied to transaction record
537       filtering, so there are some major differences.
538
539       When attached to a remote argus, ra will send the filter to  the  argus
540       process,  which  compiles the filter, and uses it to select which argus
541       records will be transmitted to the ra application.  If you do not  want
542       to  send a filter to the remote argus, prepend the filter with the key‐
543       word "local", to indicate that the filtering will be  done  within  the
544       local ra process.
545
546
547       The  expression consists of one or more primitives.  Primitives usually
548       consist of an id (name or number) preceded by one or  more  qualifiers.
549       There are three different kinds of qualifier:
550
551       type   qualifiers  say  what kind of thing the id name or number refers
552              to.  Possible types are srcid, encaps,  ether,  host,  net,  co,
553              port,  tos,  ttl,  ptks, bytes, appbytes, pcr, data, rate, load,
554              loss, ploss, vid, vpri, and mid.
555
556              E.g.,  `srcid  isis`,  `encaps   gre',   `host   sphynx',   `net
557              192.168.0.0/16',  `port domain', `ttl 1', 'ptks gt 2', 'ploss lt
558              5'.  If there is no type qualifier, host is assumed.
559
560       dir    qualifiers specify a particular  transfer  direction  to  and/or
561              from  an  id.   Possible directions are src, dst, src or dst and
562              src and dst.  E.g., `src sphynx', `dst net 192.168.0.0/24', `src
563              or dst port ftp', `src and dst tos 0x0a', `src or dst vid 0x12`,
564              `dst vpri 0x02` .  If there is no dir qualifier, src or  dst  is
565              assumed.
566
567       proto  qualifiers  restrict the match to a particular protocol.  Possi‐
568              ble values are those specified in the /etc/protocols system file
569              and  a  small  number of extensions, (that should be defined but
570              aren't).  Specific extended values are 'ipv4', (to specify  just
571              ip  version  4),  in  contrast to the defined proto 'ipv6'.  The
572              defined proto 'ip' reduces to the filter 'ipv4 or ipv6'.
573
574              When preceeded by ether, the protocol names and numbers that are
575              valid are specified in ./include/ethernames.h.
576
577       In  addition  to the above, there are some special `primitive' keywords
578       that don't follow the pattern: gateway, multicast, and broadcast.   All
579       of these are described below.
580
581       More complex filter expressions are built up by using the words and, or
582       and not to combine primitives.  E.g., `host foo and not  port  ftp  and
583       not  port  ftp-data'.  To save typing, identical qualifier lists can be
584       omitted.  E.g., `tcp dst port ftp or ftp-data or domain' is exactly the
585       same  as  `tcp  dst  port  ftp or tcp dst port ftp-data or tcp dst port
586       domain'.
587
588       Allowable primitives are:
589
590       srcid argusid
591              True if the argus identifier field in the Argus record is srcid,
592              which may be an IP address, a name or a decimal/hexidecimal num‐
593              ber.
594
595       seq [gt | gte | lt | lte | eq] number
596              True if the  transport  sequence  number  in  the  Argus  record
597              matches the sequence number expression.
598
599       encaps type
600              True  if  the encapsulation used by the flow in the Argus record
601              includes the type.  The list of valid encapsulation types is:
602                 eth, mpls, 802q, llc, pppoe, isl, gre, erspan, ah, ipnip, ipnip6, hdlc, chdlc,
603                 atm, sll, fddi, slip, arc, wlan, prism, avs, lrh, grh, teredo, udt, ipsec, juniper
604
605
606       dst host host
607              True if the IP destination field in the Argus record is host,
608              which may be either an address or a name.
609
610       src host host
611              True if the IP source field in the Argus record is host.
612
613       host host
614              True if either the IP source or destination in the Argus record is host.
615              Any of the above host expressions can be prepended with the keywords
616              ip, arp, or rarp as in:
617                   ip host host
618              which is equivalent to:
619                   ether proto ip and host host
620              If host is a name with multiple IP addresses, each address  will
621              be checked for a match.
622
623       ether dst ehost
624              True if the ethernet destination address is ehost.  Ehost may be
625              either a name from /etc/ethers or a number (see  ethers(3N)  for
626              numeric format).
627
628       ether src ehost
629              True if the ethernet source address is ehost.
630
631       ether host ehost
632              True  if  either  the  ethernet source or destination address is
633              ehost.
634
635       gateway host
636              True if the transaction used host as a gateway.  I.e., the  eth‐
637              ernet  source or destination address was host but neither the IP
638              source nor the IP destination was host.  Host must be a name and
639              must  be  found in both /etc/hosts and /etc/ethers.  (An equiva‐
640              lent expression is
641                   ether host ehost and not host host
642              which can be used with  either  names  or  numbers  for  host  /
643              ehost.)
644
645       dst net cidr
646              True  if  the IP destination address in the Argus record matches
647              the cidr address.
648
649       src net cidr
650              True if the IP source address in the Argus  record  matches  the
651              cidr address.
652
653       net cidr
654              True if either the IP source or destination address in the Argus
655              record matches cidr address.
656
657       dst port port
658              True if the network transaction is IP based,  using  either  the
659              TCP  or UDP transport protocols, and a destination port value of
660              port.  The port can be a number or a name as configured  in  the
661              /etc/services  file.(see  tcp(4P)  and  udp(4P)).   If a name is
662              used, both the protocol number and port number, are checked.  If
663              a  number  or ambiguous name is used, the port number is checked
664              for both UDP and TCP protocols (e.g., dst port  513  will  print
665              both tcp/login traffic and udp/who traffic, and port domain will
666              match both tcp/domain and udp/domain traffic).  Port ranges  can
667              be specified using numeric values, such as port 53-215.
668
669
670       src port port
671              True if the network transaction has a source port value of port.
672
673       port port
674              True  if  either  the  source  or  destination port in the Argus
675              record is port.  Any  of  the  above  port  expressions  can  be
676              prepended with the keywords, tcp or udp, as in:
677                   tcp src port port
678              which matches only tcp connections.
679
680       ip proto protocol
681              True  if  the  Argus record is an ip transaction (see ip(4P)) of
682              protocol type protocol.  Protocol can be a number or any of  the
683              string values found in /etc/protocols.
684
685       multicast
686              True  if  the  network  transaction  involved  an  ip  multicast
687              address.  By specifing ether multicast,  you  can  select  argus
688              records that involve an ethernet multicast address.
689
690       broadcast
691              True  if  the  network  transaction  involved  an  ip  broadcast
692              address.  By specifing ether broadcast,  you  can  select  argus
693              records that involve an ethernet broadcast address.
694
695       ether proto protocol
696              True  if  the  Argus record is of ether type protocol.  Protocol
697              can be a number or a name like ip, arp, or rarp.
698
699       [src | dst] ttl [gt | gte | lt | lte | eq] number
700              True if the TTL in the Argus record equals number.
701
702       [src | dst] tos [gt | gte | lt | lte | eq] number
703              True if the TOS in the Argus record (default) equals number.
704
705       [src | dst] vid [gt | gte | lt | lte | eq] number
706              True if th VLAN id in the Argus record (default) equals number.
707
708       [src | dst] vpri [gt | gte | lt | lte | eq] number
709              True if the VLAN priority in the Argus record  (default)  equals
710              number.
711
712       [src | dst] mid [gt | gte | lt | lte | eq] number
713              True if the MPLS Label in the Argus record (default) equals num‐
714              ber.
715
716       [src | dst] pkts [gt | gte | lt | lte | eq] number
717              True if the packet count in the Argus  record  (default)  equals
718              number.
719
720       [src | dst] bytes [gt | gte | lt | lte | eq] number
721              True if the byte count in the Argus record (default) equals num‐
722              ber.
723
724       [src | dst] appbytes [gt | gte | lt | lte | eq] number
725              True if the application byte count in the Argus record (default)
726              equals number.
727
728       [src | dst] rate [gt | gte | lt | lte | eq] number
729              True if the rate in the Argus record (default) equals number.
730
731       [src | dst] load [gt | gte | lt | lte | eq] number
732              True if the load in the Argus record (default) equals number.
733
734
735       Ra  filter  expressions  support  primitives  that are specific to flow
736       states and can be used to select flow records that were in these states
737       at the time they were generated.  normal, wait, timeout, est or con
738
739       Primitives  that select flows that experienced fragmentation.  frag and
740       fragonly
741
742       Support for selecting flows that used multiple pairs of  MAC  addresses
743       during their lifetime.  multipath
744
745
746       Primitives specific to TCP flows are supported.  syn, synack, ecn, fin,
747       finack, reset, retrans, outoforder and winshut
748
749       Primitives specific to TCP options are supported.  tcpopt, mss, wscale,
750       selackok, selack, tcpecho, tcpechoreply, tcptimestamp, tcpcc, tcpccnew,
751       tcpccecho, secn and decn
752
753       Primitives specific to ICMP flows are supported.  echo, unreach,  redi‐
754       rect and timexed
755
756
757       For  some  primitives, a direction qualifier is appropriate.  These are
758       frag, reset, retrans, outoforder and winshut
759
760
761       Primitives may be combined using:
762
763              A parenthesized group of primitives and  operators  (parentheses
764              are special to the Shell and must be escaped).
765
766              Negation (`!' or `not').
767
768              Concatenation (`and').
769
770              Alternation (`or').
771
772       Negation  has  highest  precedence.  Alternation and concatenation have
773       equal precedence and associate left to right.  Note that  explicit  and
774       tokens, not juxtaposition, are now required for concatenation.
775
776       If an identifier is given without a keyword, the most recent keyword is
777       assumed.  For example,
778            not host sphynx and anubis
779       is short for
780            not host sphynx and host anubis
781       which should not be confused with
782            not ( host sphynx or anubis )
783
784       Expression arguments can be passed to ra(1) as either a single argument
785       or  as multiple arguments, whichever is more convenient.  Generally, if
786       the expression contains Shell metacharacters, it is easier to  pass  it
787       as a single, quoted argument.  Multiple arguments are concatenated with
788       spaces before being parsed.
789
790
791   Startup Processing
792       Ra begins by searching for the configuration file .rarc  first  in  the
793       directory,  $ARGUSHOME  and then $HOME.  If a .rarc is found, all vari‐
794       ables specified in the file are set.
795
796       Ra then parses its command line options and set its internal  variables
797       accordingly.
798
799       If a configuration file is specified on the command-line, using the "-f
800       <confile>" option, the values in this .rarc  formatted  file  superceed
801       all other values.
802
803
804

EXAMPLES

806       To report all TCP transactions from and to host 'narly.wave.com', read‐
807       ing transaction data from argus-file argus.data:
808              ra -r argus.data - tcp and host narly.wave.com
809
810       To report all UDP based DNS traffic, reading transaction data from  the
811       remote argus.server:
812              ra -S argus.server - udp port domain
813
814       To  report  all UDP transactions seen by the remote argus.server on the
815       port range 53-256, but not sending  the  filter  to  the  remote  argus
816       process:
817              ra -S argus.server - local udp port 53-256
818
819       Create  the argus-file icmp.log with all ICMP events involving the host
820       nimrod, using data from argus-file, but reading  the  transaction  data
821       from stdin:
822              cat argus-file | ra -r - -w icmp.log - icmp and host nimrod
823
824       Read an argus-file at twice normal speed.
825              ra -r argus.file -M rtime:2
826
827

OUTPUT FORMAT

829       The  following  is  a brief description of the default output of .B ra.
830       While this is by no means the 'preferred' set of data that  one  should
831       generate,  it  represents  a starting point for using flow data in gen‐
832       eral.  This also looks pretty good on 80 column terminals.  The  format
833       is:
834                time  flgs proto  shost  dir  daddr metrics state
835
836       time
837           The  format of the time field is specified by the .rarc file, using
838           syntax supported by the routine strftime(3V).  The default is '%T'.
839           Argus transactional data contains both starting and ending transac‐
840           tion times, with precision  to  the  microsecond.  However,  ra  by
841           default prints out the 'stime' field, the records starting time.
842
843       flgs
844           The  flgs  indicator consists of a fixed length field. That reports
845           various  flow  record  and   protocol   identifiers,   states   and
846           attributes.  The format is:
847
848            T        -  Time Corrected/Adjusted
849            N        -  Netflow Originated Data
850             *       -  Multiple sub-IP encapsulations
851             e       -  Ethernet encapsulated flow
852             E       -  ERSPAN encapsulation
853             M       -  Multiple mac addresses seen
854             m       -  MPLS encapsulated flow
855             l       -  LLC encapsulated flow
856             v       -  802.1Q encapsulations/tags
857             w       -  802.11 wireless encapsulation
858             p       -  PPP over Enternet encapsulated flow
859             i       -  ISL encapsulated flow
860             G       -  GRE encapsulation
861             a       -  AH encapsulation
862             P       -  IP tunnel encapsulation
863             6       -  IPv6 tunnel encapsulation
864             H       -  HDLC encapsulation
865             C       -  Cisco HDLC encapsulation
866             A       -  ATM encapsulation
867             S       -  SLL encapsulation
868             F       -  FDDI encapsulation
869             s       -  SLIP encapsulation
870             R       -  ARCNET encapsulation
871              I      -  ICMP events mapped to this flow
872              U      -  ICMP Unreachable event mapped to this flow
873              R      -  ICMP Redirect event mapped to this flow
874              T      -  ICMP Time Exceeded mapped to this flow
875               *     -  Both Src and Dst loss/retransmission
876               s     -  Src loss/retransmissions
877               d     -  Dst loss/retransmissions
878               g     -  Gaps in sequence numbers were observed
879               &     -  Both Src and Dst packet out of order
880               i     -  Src packets out of order
881               r     -  Dst packets out of order
882                @    -  Both Src and Dst Window Closure
883                S    -  Src TCP Window Closure
884                D    -  Dst TCP Window Closure
885                *    -  Silence suppression used by both src and dst (RTP)
886                s    -  Silence suppression used by src
887                d    -  Silence suppression used by dst
888                 E   -  Both Src and Dst ECN
889                 x   -  Src Explicit Congestion Notification
890                 t   -  Dst ECN
891                  V  -  Fragment overlap seen (if fragments seen)
892                  f  -  Partial Fragment (if fragments seen)
893                  F  -  Fragments seen
894                   O  -  multiple IP options set
895                   S  -  IP option Strict Source Route
896                   L  -  IP option Loose Source Route
897                   T  -  IP option Time Stamp
898                   +  -  IP option Security
899                   R  -  IP option Record Route
900                   A  -  IP option Router Alert
901                   U  -  unknown IP options set
902
903
904       proto
905           The  proto  field indicates the upper protocol used in the transac‐
906           tion.  This field will contain the first 4 characters of the  offi‐
907           cial  name  for the protocol used, as defined in RFC-1700, and con‐
908           figured using the /etc/protocols file.  Argus attempts to discovery
909           the Realtime Transport Protocol (rtp), when it is being used.  When
910           it encounters rtp, it will indicate its use in this field, with the
911           string  'rtp'.   Use  of the -n option, twice (-nn), will cause the
912           actual protocol number to be displayed.
913
914       shost
915           The shost field is meant to convey the originator of  the  data  in
916           the  flow.   This field is protocol dependent, and for IP protocols
917           will contain the src IP address/name.  For TCP and UDP,  the  field
918           will also contain the port number/name, separated by a period.
919
920           The  'src'  is  generally  the entity that first transmits a packet
921           that is a part of a flow.  However, the  assignment  of  'src'  and
922           'dst'  semantics  is somewhat complicated by the notion of loss, or
923           half-duplex monitoring, especially when connection-oriented  proto‐
924           col  ,  such  as  TCP, are reported.  In this case the 'src' is the
925           entity that initiated the flow.
926
927       dir
928          The dir field will have the direction of the transaction, as can  be
929          best  determined from the datum, and is used to indicate which hosts
930          are transmitting. For TCP, the dir field indicates the actual source
931          of the TCP connection, and the center character indicating the state
932          of the transaction.
933               -  - transaction was NORMAL
934               |  - transaction was RESET
935               o  - transaction TIMED OUT.
936               ?  - direction of transaction is unknown.
937
938       daddr
939           The daddr field is meant to convey the recipient of the data in the
940           flow.   Like the shost field, this field is protocol dependent, and
941           for IP protocols will contain the dst IP address/name, and  option‐
942           ally the DSAP.
943
944
945       metrics
946           metrics  represent  the  general  sets  of  fields that reflect the
947           activity of the flow.  In the default output, there are  4  fields.
948           The  first  2  are  the  packet  counts and the last 2 are the byte
949           counts for the specific transaction.  The fields  are  paired  with
950           the  previous host fields, and represent the packets transmitted by
951           the respective host.
952
953       state
954           The state field indicates the principle state for  the  transaction
955           report,  and  is protocol dependent.  For all the protocols, except
956           ICMP, this field reports on the basic state of a transaction.
957
958         REQ|INT (requested|initial)
959           This indicates that this is the initial state report for a transac‐
960           tion and is seen only when the argus-server is in DETAIL mode.  For
961           TCP connections this is REQ, indicating that a connection is  being
962           requested.   For the connectionless protocols, such as UDP, this is
963           INT.
964
965         ACC (accepted)
966           This indicates that a request/response condition has occurred,  and
967           that  a  transaction has been detected between two hosts.  For TCP,
968           this indicates that a connection request has been answered, and the
969           connection  will  be  accepted.   This is only seen when the argus-
970           server is in DETAIL mode.  For the connectionless  protocols,  this
971           state  indicates  that  there  has  been  a  single packet exchange
972           between two hosts, and could qualify as a request/response transac‐
973           tion.
974
975         EST|CON (established|connected)
976           This record type indicates that the reported transaction is active,
977           and has been established or is continuing.  This should  be  inter‐
978           preted  as  a  state report of a currently active transaction.  For
979           TCP, the EST state is only seen in DETAIL mode, and indicates  that
980           the three way handshake has been completed for a connection.
981
982         CLO (closed)
983           TCP  specific,  this  record type indicates that the TCP connection
984           has closed normally.
985
986         TIM (timeout)
987           Activity was not seen relating  to  this  transaction,  during  the
988           argus  server's  timeout  period  for this protocol.  This state is
989           seen only when there were packets recorded since  the  last  report
990           for this transaction.
991
992
993       For  the  ICMP  and ICMPv6 protocols, the state field displays specific
994       aspects of the ICMP type.  ICMP state can have the values:
995
996          ECO     Echo Request
997          ECR     Echo Reply
998          SRC     Source Quench
999          RED     Redirect
1000          RTA     Router Advertisement
1001          RTS     Router Solicitation
1002          TXD     Time Exceeded
1003          PAR     Parameter Problem
1004          TST     Time Stamp Request
1005          TSR     Time Stamp Reply
1006          IRQ     Information Request
1007          IRR     Information Reply
1008          MAS     Mask Request
1009          MSR     Mask Reply
1010          URN     Unreachable network
1011          URH     Unreachable host
1012          URP     Unreachable port
1013          URF     Unreachable need fragmentation
1014          URS     Unreachable source failed
1015          URNU    Unreachable dst network unknown
1016          URHU    Unreachable dst host unknown
1017          URISO   Unreachable source host isolated
1018          URNPRO  Unreachable network administrative prohibited
1019          URHPRO  Unreachable host administrative prohibited
1020          URNTOS  Unreachable network TOS prohibited
1021          URHTOS  Unreachable host TOS prohibited
1022          URFIL   Unreachable administrative filter
1023          URPRE   Unreachable precedence violation
1024          URCUT   Unreachable precedence cutoff
1025
1026          MRQ     Membership Query
1027          MHR     Membership Report
1028          NRS     Neighbor Discovery Router Solicit
1029          NRA     Neighbor Discovery Router Advertisement
1030          NNS     Neighbor Discovery Neighbor Solicit
1031          NNA     Neighbor Discovery Neighbor Advertisement
1032          PTB     Packet Too Big
1033
1034

OUTPUT EXAMPLES

1036       These examples show typical ra output, and  demonstrates  a  number  of
1037       variations  seen in argus data.  This ra output was generated using the
1038       -n option to suppress number translation.
1039
1040 Thu 12/29 06:40:32   S tcp  132.3.31.15.6439   -> 12.23.14.77.23   CLO
1041       This  is  a  normal  tcp  transaction  to  the  telnet  port  on   host
1042       12.23.14.77.  The IP Option strict source route was seen.
1043
1044 Thu 12/29 06:40:32     tcp  132.3.31.15.6200  <|  12.23.14.77.25   RST
1045       This  tcp transaction from the smtp port of host 12.23.14.77 was RESET.
1046       In many cases this indicates that the transaction was rejected, however
1047       some  os's  will  use RST to close an active TCP.  Use either the -z or
1048       -Zb options to specify exactly what conditions existed during the  con‐
1049       nection.
1050
1051 Thu 12/29 03:39:05  M  igmp 12.88.14.10       <-> 128.2.2.10       CON
1052       This is an igmp transaction state report, usually seen with MBONE traf‐
1053       fic.  There was more than one source and destination MAC  address  pair
1054       used to support the transaction, suggesting a possible routing loop.
1055
1056 Thu 12/29 06:40:05 *   tcp  12.23.14.23.1043  <-> 12.23.14.27.6000 TIM
1057       This  is  an  X-windows  transaction, that has TIMEDOUT.   Packets were
1058       retransmitted during the connection.
1059
1060 Thu 12/29 07:42:09     udp   12.9.1.115.2262   -> 28.12.141.6.139  INT
1061       This is an initial netbios UDP  transaction  state  report,  indicating
1062       that this is the first datagram encountered for this transaction.
1063
1064 Thu 12/29 06:42:09     icmp  12.9.1.115       <-> 12.68.5.127      ECO
1065       This example represents a "ping" of host 12.9.1.115, and its response.
1066
1067 This  next example shows the ra output of a complete TCP transaction, with the
1068 preceeding Arp and DNS requests, while reading  from  a  remote  argus-server.
1069 The  '*' in the CLO report indicates that at least one TCP packet was retrans‐
1070 mitted during the transaction.  The hostnames in this example are ficticious.
1071
1072 % ra -S argus-tcp://argus-server and host i.qosient.com
1073 ra: Trying argus-server port 561
1074 ra: connected Argus Version 3.0
1075 Sat 12/03 15:29:38     arp  i.qosient.com     who-has  dsn.qosient.com  INT
1076 Sat 12/03 15:29:39     udp  i.qosient.com.1542  <->    dns.qosient.53   INT
1077 Sat 12/03 15:29:39     arp  i.qosient.com     who-has  qosient.com      INT
1078 Sat 12/03 15:29:39 *   tcp  i.qosient.com.1543   ->    qosient.com.smtp CLO
1079
1081       Copyright (c) 2000-2016 QoSient. All rights reserved.
1082

AUTHORS

1084       Carter Bullard (carter@qosient.com).
1085

FILES

1087       /etc/ra.conf
1088

SEE ALSO

1090       rarc(5) argus(8)
1091
1092       Postel, Jon, Internet Protocol, RFC 791, Network Information Center, SRI
1093       International, Menlo Park, Calif., May 1981.
1094
1095       Postel,  Jon, Internet Control Message Protocol, RFC 792, Network Infor‐
1096       mation Center, SRI International, Menlo Park, Calif., May 1981.
1097
1098       Postel, Jon, Transmission Control Protocol, RFC 793, Network Information
1099       Center, SRI International, Menlo Park, Calif., May 1981.
1100
1101       Postel,  Jon,  User Datagram Protocol, RFC 768, Network Information Cen‐
1102       ter, SRI International, Menlo Park, Calif., May 1980.
1103
1104       McCanne, Steven, and Van Jacobson, The BSD Packet Filter: A  New  Archi‐
1105       tecture  for  User-level  Capture,  Lawrwnce  Berkeley  Laboratory,  One
1106       Cyclotron Road, Berkeley, Calif., 94720, December 1992.
1107
1108
1109
1110ra 3.0.8                       12 November 2007                          RA(1)
Impressum