1RA(1) General Commands Manual RA(1)
2
6 ra - read argus(8) data.
7
9 ra [raoptions] [-- filter-expression]
10
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
20 -A Print aggregate statistics for the input stream on termination.
21 -b Dump the compiled transaction-matching code to standard output and
23 stop. This is useful for debugging filter expressions.
24 -c <char>
26 Specify a delimiter character for output columns (default is ' ').
27 -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 -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 -d Toggle whether to run this program as a daemon.
42 -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 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 -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 -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 -h Print an explanation of all the arguments.
68 -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 -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 -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 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 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 Examples are:
116 -M dsrs=time,flow,metric
117 -M dsrs=-suser,-duser
118 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 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 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 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 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 -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 -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 -p <digits>
171 Print <digits> number of units of precision for floating point val‐
172 ues.
173 -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 -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 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 -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 -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 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 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 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 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 dminsz minimum packet size for traffic transmitted by the dst.
382 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 -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 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 -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 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 timeSpecification: [[[yyyy/]mm/]dd.]HH[:MM[:SS]]
426 [yyyy/]mm/dd
427 yyyy
428 %d{ymdHMS}
429 seconds
430 { + | - }%d{ymdHMS}
431 where '*' can be used as a wildcard.
433 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 -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 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 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 -T <secs>
471 Read argus(5) from remote server for <secs> of time.
472 -u Print time values using Unix time format (seconds from the Epoch).
474 -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 -X Resets all options to their default values and overrides the rarc
482 file contents (Use as the first option.)
483 -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 -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 '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
509 ra exits with one of the following values:
510 0 Records matched condition, considering the options provided.
512 1 No records matched the condition, or the source was not an argus stream.
514 > 1 An error occurred.
516
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 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 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 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 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 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 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 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 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 When preceeded by ether, the protocol names and numbers that are
575 valid are specified in ./include/ethernames.h.
576 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 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 Allowable primitives are:
589 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 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 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 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 src host host
611 True if the IP source field in the Argus record is host.
612 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 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 ether src ehost
629 True if the ethernet source address is ehost.
630 ether host ehost
632 True if either the ethernet source or destination address is
633 ehost.
634 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 dst net cidr
646 True if the IP destination address in the Argus record matches
647 the cidr address.
648 src net cidr
650 True if the IP source address in the Argus record matches the
651 cidr address.
652 net cidr
654 True if either the IP source or destination address in the Argus
655 record matches cidr address.
656 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 src port port
671 True if the network transaction has a source port value of port.
672 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 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 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 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 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 [src | dst] ttl [gt | gte | lt | lte | eq] number
700 True if the TTL in the Argus record equals number.
701 [src | dst] tos [gt | gte | lt | lte | eq] number
703 True if the TOS in the Argus record (default) equals number.
704 [src | dst] vid [gt | gte | lt | lte | eq] number
706 True if th VLAN id in the Argus record (default) equals number.
707 [src | dst] vpri [gt | gte | lt | lte | eq] number
709 True if the VLAN priority in the Argus record (default) equals
710 number.
711 [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 [src | dst] pkts [gt | gte | lt | lte | eq] number
717 True if the packet count in the Argus record (default) equals
718 number.
719 [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 [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 [src | dst] rate [gt | gte | lt | lte | eq] number
729 True if the rate in the Argus record (default) equals number.
730 [src | dst] load [gt | gte | lt | lte | eq] number
732 True if the load in the Argus record (default) equals number.
733 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 Primitives that select flows that experienced fragmentation. frag and
740 fragonly
741 Support for selecting flows that used multiple pairs of MAC addresses
743 during their lifetime. multipath
744 Primitives specific to TCP flows are supported. syn, synack, ecn, fin,
747 finack, reset, retrans, outoforder and winshut
748 Primitives specific to TCP options are supported. tcpopt, mss, wscale,
750 selackok, selack, tcpecho, tcpechoreply, tcptimestamp, tcpcc, tcpccnew,
751 tcpccecho, secn and decn
752 Primitives specific to ICMP flows are supported. echo, unreach, redi‐
754 rect and timexed
755 For some primitives, a direction qualifier is appropriate. These are
758 frag, reset, retrans, outoforder and winshut
759 Primitives may be combined using:
762 A parenthesized group of primitives and operators (parentheses
764 are special to the Shell and must be escaped).
765 Negation (`!' or `not').
767 Concatenation (`and').
769 Alternation (`or').
771 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 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 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 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 Ra then parses its command line options and set its internal variables
797 accordingly.
798 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
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 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 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 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 Read an argus-file at twice normal speed.
825 ra -r argus.file -M rtime:2
826
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 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 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 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 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 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 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 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 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 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 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 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 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 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 CLO (closed)
983 TCP specific, this record type indicates that the TCP connection
984 has closed normally.
985 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 For the ICMP and ICMPv6 protocols, the state field displays specific
994 aspects of the ICMP type. ICMP state can have the values:
995 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 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
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 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 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 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 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 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 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 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 % 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
1084 Carter Bullard (carter@qosient.com).
1085
1087 /etc/ra.conf
1088
1090 rarc(5) argus(8)
1091 Postel, Jon, Internet Protocol, RFC 791, Network Information Center, SRI
1093 International, Menlo Park, Calif., May 1981.
1094 Postel, Jon, Internet Control Message Protocol, RFC 792, Network Infor‐
1096 mation Center, SRI International, Menlo Park, Calif., May 1981.
1097 Postel, Jon, Transmission Control Protocol, RFC 793, Network Information
1099 Center, SRI International, Menlo Park, Calif., May 1981.
1100 Postel, Jon, User Datagram Protocol, RFC 768, Network Information Cen‐
1102 ter, SRI International, Menlo Park, Calif., May 1980.
1103 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.
1107ra 3.0.8 12 November 2007 RA(1)