1RA(1) General Commands Manual RA(1)
2
6 ra - read argus(8) data.
7
9 Copyright (c) 2000-2003 QoSient. All rights reserved.
10
12 ra
13 ra [raoptions] [- filter-expression]
14
16 Ra reads argus(8) data from either stdin, an argus-file, or from a
17 remote argus-server, filters the records it encounters based on an
18 optional filter-expression and either prints the contents of the
19 argus(5) records that it encounters to stdout or writes them out into
20 an argus(5) datafile.
21
23 -A When generating ASCII output, print the application byte counts.
24 -b Dump the compiled transaction-matching code to standard output and
26 stop. This is useful for debugging filter expressions.
27 -C [host:]<portnum>
29 Indicate the optional host and required port number for the remote
30 Cisco Netflow record source. This will cause ra(1) to open a UDP
31 socket, binding on the host and supplied port, and attempt to read
32 Cisco Netflow records from the open socket.
33 -d <bytes>
35 Print specified number of <bytes> from the user data capture buf‐
36 fer. The <bytes> value can be a number, or an expression that
37 specifies the number of bytes for either the source or destination
38 buffer. Formats include:
39 -d 32 print 32 bytes from the src and dst buffer
40 -d s24 print 24 bytes from the src buffer
41 -d d16 print 16 bytes from the dst buffer
42 -d s32:d8 print 32 bytes from the src buffer and
43 8 bytes from the dst buffer
44 -D <level>
46 Print debug information corresponding to <level> to stderr, if pro‐
47 gram compiled to support debug printing. As the level increases,
48 so does the amount of debug information ra(1) will print. Values
49 range from 1-8.
50 -E <file>
52 When using a filter expression at the end of the command, this
53 option will cause ra(1) to write the records that are rejected by
54 the filter into <file>
55 -F <conffile>
57 Use <conffile> as a source of configuration information. The for‐
58 mat of this file is identical to rarc(5). The data read from
59 <conffile> overrides any prior configuration information.
60 -h Print an explanation of all the arguments.
62 -n Do not translate host and service numbers to names. -nn will sup‐
64 press translation of protocol numbers, as well.
65 -p <digits>
67 Print <digits> number of units of precision for fraction of time.
68 -q Run in quiet mode. Configure Ra to not print out the contents of
70 records. This can be used with the -T and -a options to support
71 aggregate activity without printing each input record.
72 -r <file file ...> -
74 Read data from <files> in the order presented on the commandline.
75 '-' denotes stdin. Because this option can have many arguments, it
76 must be terminated with a '-'. The '-' of subsequent options is
77 sufficient. Ra can read gzip(1), bzip2(1) and compress(1) com‐
78 pressed data files.
79 -R Print response data when available. This option applies to ICMP,
81 arp and BOOTP traffic to indicate the responses to these protocol
82 specific queries.
83 -s <[-][[+[#]]field ...> -
85 Specify the fields to print. Ra uses a default printing field list,
86 by specifying a field you can replace this list completely, or you
87 can modify the existing default print list, using the optional '-'
88 and '+[#]' form of the command. The available fields to print are:
89 startime, lasttime, count, dur, avgdur,
91 saddr, daddr, proto, sport, dport, ipid,
92 stos, dtos, sttl, dttl, bytes, sbytes, dbytes,
93 pkts, spkts, dpkts, load, loss, rate,
94 srcid, ind, mac, dir, jitter, status, user,
95 win, trans, seq, vlan, mpls
96 Examles are:
98 -s srcaddr print only the source address.
99 -s -bytes removes the bytes field from list.
100 -s +2srcid adds MAC addresses as the 2nd field.
101 -s mac pkts prints MAC addresses and src and dst pkt counts.
102 -S <host[:portnum]>
104 Specify a remote argus-server <host>. Use the optional
105 -t <timerange>
107 Specify the <time range> for matching argus(5) records. The syntax
108 for the <time range> is:
109 timeSpecification[-timeSpecification]
111 timeSpecification: [[[yyyy/]mm/]dd.]hh[:mm[:ss]]
112 [yyyy/]mm/dd
113 -%d{yMdhms}
114 Examples are:
116 -t 14 matches 2pm-3pm any day
117 -t 23.11:10-14 11:10:00 - 2pm on the 23rd
118 -t 11/23 all records on Nov 23rd
119 -t 1999/01/23.10 10-11am on Jan, 23, 1999
120 -t -10m matches 10 minutes before to the present
121 -t -2h5m-2h matches range between 2 hours 5 minutes before
122 until 2 hours before.
123 -T <secs>
126 Read argus(5) from remote server for <secs> of time.
127 -u Write out time values using UTC time format.
129 -w <file>
131 Write out matching data to <file>, in argus file format. An output-
132 file of '-' directs ra to write the argus(5) records to stdout,
133 allowing for "chaining" ra* style commands together.
134 -z Print Argus TCP state changes for each tcp transaction. Values are
136 's' - Syn Transmitted
137 'S' - Syn Acknowledged
138 'E' - TCP Established
139 'f' - Fin Transmitted (FIN Wait State 1)
140 'F' - Fin Acknowledged (FIN Wait State 2)
141 'R' - TCP Reset
142 -Z <s|d|b>
145 Print actual TCP flag values. <'s'rc | 'd'st | 'b'oth>.
146 'F' - Fin
147 'S' - Syn
148 'R' - Reset
149 'P' - Push
150 'A' - Ack
151 'U' - Urgent Pointer
152 '7' - Undefined 7th bit set
153 '8' - Undefined 8th bit set
154
157 If arguments remain after option processing, the collection is inter‐
158 preted as a single filter expression. In order to indicate the end of
159 arguments, a '-' is recommended before the filter expression is added
160 to the command line.
161 The filter expression specifies which argus(5) records will be selected
162 for processing. If no expression is given, all records are selected,
163 otherwise, only those records for which expression is `true' will be
164 printed.
165 The syntax is very similar to the expression syntax for tcpdump(1), as
167 the tcpdump compiler was the basis for the argus(5) filter expression
168 compiler. The semantics for tcpdump(1)'s packet filter expression are
169 different when applied to transaction record filtering, so there are
170 some major differences.
171 The expression consists of one or more primitives. Primitives usually
173 consist of an id (name or number) preceded by one or more qualifiers.
174 There are three different kinds of qualifier:
175 type qualifiers say what kind of thing the id name or number refers
177 to. Possible types are srcid, host, net, port, tos, ttl, vid,
178 and mid.
179 E.g., `srcid isis`, `host sphynx', `net 192.168', `port domain',
181 `ttl 1'. If there is no type qualifier, host is assumed.
182 dir qualifiers specify a particular transfer direction to and/or
184 from an id. Possible directions are src, dst, src or dst and
185 src and dst. E.g., `src sphynx', `dst net 192.168', `src or dst
186 port ftp', `src and dst tos 0x0a', `src or dst vid 0x12`. If
187 there is no dir qualifier, src or dst is assumed.
188 proto qualifiers restrict the match to a particular protocol. Possi‐
190 ble values are those specified in the /etc/protocols system
191 file. When preceeded by ether, the protocol names and numbers
192 that are valid are specified in ./include/ethernames.h.
193 In addition to the above, there are some special `primitive' keywords
195 that don't follow the pattern: gateway, multicast, and broadcast. All
196 of these are described below.
197 More complex filter expressions are built up by using the words and, or
199 and not to combine primitives. E.g., `host foo and not port ftp and
200 not port ftp-data'. To save typing, identical qualifier lists can be
201 omitted. E.g., `tcp dst port ftp or ftp-data or domain' is exactly the
202 same as `tcp dst port ftp or tcp dst port ftp-data or tcp dst port
203 domain'.
204 Allowable primitives are:
206 srcid argusid
208 True if the argus identifier field of the Argus record is srcid,
209 which may be an IP address, a name or a decimal/hexidecimal num‐
210 ber.
211 dst host host
213 True if the IP destination field of the Argus record is host,
214 which may be either an address or a name.
215 src host host
217 True if the IP source field of the Argus record is host.
218 host host
220 True if either the IP source or destination of the Argus record
221 is host. Any of the above host expressions can be prepended
222 with the keywords, ip, arp, or rarp as in:
223 ip host host
224 which is equivalent to:
225 ether proto \ip and host host
226 If host is a name with multiple IP addresses, each address will
227 be checked for a match.
228 ether dst ehost
230 True if the ethernet destination address is ehost. Ehost may be
231 either a name from /etc/ethers or a number (see ethers(3N) for
232 numeric format).
233 ether src ehost
235 True if the ethernet source address is ehost.
236 ether host ehost
238 True if either the ethernet source or destination address is
239 ehost.
240 gateway host
242 True if the transaction used host as a gateway. I.e., the eth‐
243 ernet source or destination address was host but neither the IP
244 source nor the IP destination was host. Host must be a name and
245 must be found in both /etc/hosts and /etc/ethers. (An equiva‐
246 lent expression is
247 ether host ehost and not host host
248 which can be used with either names or numbers for host /
249 ehost.)
250 dst net net
252 True if the IP destination address of the Argus record has a
253 network number of net, which may be either an address or a name.
254 src net net
256 True if the IP source address of the Argus record has a network
257 number of net.
258 net net
260 True if either the IP source or destination address of the Argus
261 record has a network number of net.
262 dst port port
264 True if the network transaction is ip/tcp or ip/udp and has a
265 destination port value of port. The port can be a number or a
266 name used in /etc/services (see tcp(4P) and udp(4P)). If a name
267 is used, both the port number and protocol are checked. If a
268 number or ambiguous name is used, only the port number is
269 checked (e.g., dst port 513 will print both tcp/login traffic
270 and udp/who traffic, and port domain will print both tcp/domain
271 and udp/domain traffic).
272 src port port
274 True if the network transaction has a source port value of port.
275 port port
277 True if either the source or destination port of the Argus
278 record is port. Any of the above port expressions can be
279 prepended with the keywords, tcp or udp, as in:
280 tcp src port port
281 which matches only tcp connections.
282 ip proto protocol
284 True if the Argus record is an ip transaction (see ip(4P)) of
285 protocol type protocol. Protocol can be a number or any of the
286 string values found in /etc/protocolsk.
287 multicast
289 True if the network transaction involved an ip multicast
290 address. By specifing ether multicast, you can select argus
291 records that involve an ethernet multicast address.
292 broadcast
294 True if the network transaction involved an ip broadcast
295 address. By specifing ether broadcast, you can select argus
296 records that involve an ethernet broadcast address.
297 ether proto protocol
299 True if the Argus record is of ether type protocol. Protocol
300 can be a number or a name like ip, arp, or rarp. Note these
301 identifiers are also keywords and must be escaped via backslash
302 (\).
303 dst ttl number
305 True if the destination TTL of the Argus record equals number.
306 src ttl number
308 True if the source TTL of the Argus record equals number.
309 ttl number
311 True if either the source or destination TTL of the Argus record
312 equals number.
313 dst tos number
315 True if the destination TOS of the Argus record equals number.
316 src tos number
318 True if the source TOS of the Argus record equals number.
319 tos number
321 True if either the source or destination TOS of the Argus record
322 equals number.
323 dst vid number
325 True if the destination VLAN id of the Argus record equals num‐
326 ber.
327 src vid number
329 True if the source VLAN id of the Argus record equals number.
330 vid number
332 True if either the source or destination VLAN id of the Argus
333 record equals number.
334 dst mid number
336 True if the destination MPLS Label of the Argus record equals
337 number.
338 src mid number
340 True if the source MPLS Label of the Argus record equals number.
341 mid number
343 True if either the source or destination MPLS Label of the Argus
344 record equals number.
345 Ra filter expressions support primitives that are specific to flow
348 states and can be used to select flow records that were in these states
349 at the time they were generated. normal, wait, timeout, est or con
350 Primitives that select flows that experienced fragmentation. frag and
352 fragonly
353 Support for selecting flows that used multiple pairs of MAC addresses
355 during their lifetime. multipath
356 Primitives specific to TCP flows are supported. syn, synack, data,
359 ecn, fin, finack, reset, retrans, outoforder and winshut
360 Primitives specific to ICMP flows are supported. echo, unreach, redi‐
362 rect and timexed
363 For some primitives, a direction qualifier is appropriate. These are
366 frag, reset, retrans, outoforder and winshut
367 Primitives may be combined using:
370 A parenthesized group of primitives and operators (parentheses
372 are special to the Shell and must be escaped).
373 Negation (`!' or `not').
375 Concatenation (`and').
377 Alternation (`or').
379 Negation has highest precedence. Alternation and concatenation have
381 equal precedence and associate left to right. Note that explicit and
382 tokens, not juxtaposition, are now required for concatenation.
383 If an identifier is given without a keyword, the most recent keyword is
385 assumed. For example,
386 not host sphynx and anubis
387 is short for
388 not host sphynx and host anubis
389 which should not be confused with
390 not ( host sphynx or anubis )
391 Expression arguments can be passed to ra(1) as either a single argument
393 or as multiple arguments, whichever is more convenient. Generally, if
394 the expression contains Shell metacharacters, it is easier to pass it
395 as a single, quoted argument. Multiple arguments are concatenated with
396 spaces before being parsed.
397 Startup Processing
400 Ra begins by searching for the configuration file .rarc first in the
401 directory, $ARGUSHOME and then $HOME. If a .rarc is found, all vari‐
402 ables specified in the file are set.
403 Ra then parses its command line options and set its internal variables
405 accordingly.
406 If a configuration file is specified on the command-line, using the "-f
408 <confile>" option, the values in this .rarc formatted file superceed
409 all other values.
410
414 To report all TCP transactions from and to host 'narly.wave.com', read‐
415 ing transaction data from argus-file argus.data:
416 ra -r argus.data - tcp and host narly.wave.com
417 Create the argus-file icmp.log with all ICMP events involving the host
419 nimrod, using data from argus-file, but reading the transaction data
420 from stdin:
421 cat argus-file | ra -r - -w icmp.log - icmp and host nimrod
422
424 The following is a brief description of the output format of ra which
425 reports transaction data in various levels of detail. The general for‐
426 mat is:
427 time proto srchost dir dsthost [count] status
428 time
430 The format of the time field is specified by the .rarc file, using
431 syntax supported by the routine localtime(3V). The default is
432 Argus transaction data contains both starting and ending transac‐
433 tion times, with precision to the microsecond. However, ra prints
434 out only one of these dates depending on the status of the argus
435 server. When the argus server is running in default mode, ra
436 reports the transaction starting time. When the server is in
437 DETAIL mode, the transaction ending time is reported.
438 mac.addr
440 mac.addr is an optional field, specified using the -m flag.
441 mac.addr represents the first source and destination MAC addresses
442 seen for a particular transaction. These addresses are paired with
443 the host.port fields, so the direction indicator is needed to dis‐
444 tinguish between the source and destination MAC addresses.
445 proto [options protocol]
447 The proto indicator consists of two fields. The first is protocol
448 specific and the designations are:
449 m - MPLS encapsulated flow
450 q - 802.1Q encapsulated flow
451 p - PPP over Enternet encapsulated flow
452 E - Multiple encapsulations/tags
453 s - Src TCP packet retransmissions
454 d - Dst TCP packet retransmissions
455 * - Both Src and Dst TCP retransmissions
456 i - Src TCP packets out of order
457 r - Dst TCP packets out of order
458 & - Both Src and Dst packet out of order
459 S - Src TCP Window Closure
460 D - Dst TCP Window Closure
461 @ - Both Src and Dst Window Closure
462 x - Src TCP Explicit Congestion Notification
463 t - Dst TCP ECN
464 E - Both Src and Dst ECN
465 M - Multiple physical layer paths
466 I - ICMP event mapped to this flow
467 S - IP option Strict Source Route
468 L - IP option Loose Source Route
469 T - IP option Time Stamp
470 + - IP option Security
471 R - IP option Record Route
472 A - IP option Router Alert
473 O - multiple IP options set
474 E - unknown IP options set
475 F - Fragments seen
476 f - Partial Fragment
477 V - Fragment overlap seen
478 The second field indicates the upper protocol used in the transac‐
480 tion. This field will contain the first 4 characters of the offi‐
481 cial name for the protocol used, as defined in RFC-1700. Argus
482 attempts to discovery the Realtime Transport Protocol, when it is
483 being used. When it encounters RTP, it will indicate its use in
484 this field, with the string 'rtp'. Use of the -n option, twice
485 (-nn), will cause the actual protocol number to be displayed.
486 host
488 The host field is protocol dependent, and for all protocols will
489 contain the IP address/name. For TCP and UDP, the field will also
490 contain the port number/name, separated by a period.
491 dir
493 The dir field will have the direction of the transaction, as can be
494 best determined from the datum, and is used to indicate which hosts
495 are transmitting. For TCP, the dir field indicates the actual source
496 of the TCP connection, and the center character indicating the state
497 of the transaction.
498 - - transaction was NORMAL
499 | - transaction was RESET
500 o - transaction TIMED OUT.
501 ? - direction of transaction is unknown.
502 count
504 count is an optional field, specified using the -c option. There
505 are 4 fields that are produced. The first 2 are the packet counts
506 and the last 2 are the byte counts for the specific transaction.
507 The fields are paired with the previous host fields, and represent
508 the packets transmitted by the respective host.
509 status
511 The status field indicates the principle status for the transaction
512 report, and is protocol dependent. For all the protocols, except
513 ICMP, this field reports on the basic state of a transaction.
514 REQ|INT (requested|initial)
516 This indicates that this is the initial status report for a trans‐
517 action and is seen only when the argus-server is in DETAIL mode.
518 For TCP connections this is REQ, indicating that a connection is
519 being requested. For the connectionless protocols, such as UDP,
520 this is INT.
521 ACC (accepted)
523 This indicates that a request/response condition has occurred, and
524 that a transaction has been detected between two hosts. For TCP,
525 this indicates that a connection request has been answered, and the
526 connection will be accepted. This is only seen when the argus-
527 server is in DETAIL mode. For the connectionless protocols, this
528 state indicates that there has been a single packet exchange
529 between two hosts, and could qualify as a request/response transac‐
530 tion.
531 EST|CON (established|connected)
533 This record type indicates that the reported transaction is active,
534 and has been established or is continuing. This should be inter‐
535 preted as a status report of a currently active transaction. For
536 TCP, the EST status is only seen in DETAIL mode, and indicates that
537 the three way handshake has been completed for a connection.
538 CLO (closed)
540 TCP specific, this record type indicates that the TCP connection
541 has closed normally.
542 TIM (timeout)
544 Activity was not seen relating to this transaction, during the
545 argus server's timeout period for this protocol. This status is
546 seen only when there were packets recorded since the last report
547 for this transaction.
548 For the ICMP protocol, the status field displays specific aspects of
551 the ICMP type. ICMP status can have the values:
552 ECO Echo Request
554 ECR Echo Reply
555 SRC Source Quench
556 RED Redirect
557 RTA Router Advertisement
558 RTS Router Solicitation
559 TXD Time Exceeded
560 PAR Parameter Problem
561 TST Time Stamp Request
562 TSR Time Stamp Reply
563 IRQ Information Request
564 IRR Information Reply
565 MAS Mask Request
566 MSR Mask Reply
567 URN Unreachable network
568 URH Unreachable host
569 URP Unreachable port
570 URF Unreachable need fragmentation
571 URS Unreachable source failed
572 URNU Unreachable dst network unknown
573 URHU Unreachable dst host unknown
574 URISO Unreachable source host isolated
575 URNPRO Unreachable network administrative prohibited
576 URHPRO Unreachable host administrative prohibited
577 URNTOS Unreachable network TOS prohibited
578 URHTOS Unreachable host TOS prohibited
579 URFIL Unreachable administrative filter
580 URPRE Unreachable precedence violation
581 URCUT Unreachable precedence cutoff
582
585 These examples show typical ra output, and demonstrates a number of
586 variations seen in argus data. This ra output was generated using the
587 -n option to suppress number translation.
588 Thu 12/29 06:40:32 S tcp 132.3.31.15.6439 -> 12.23.14.77.23 CLO
590 This is a normal tcp transaction to the telnet port on host
591 12.23.14.77. The IP Option strict source route was seen.
592 Thu 12/29 06:40:32 tcp 132.3.31.15.6200 <| 12.23.14.77.25 RST
594 This tcp transaction from the smtp port of host 12.23.14.77 was RESET,
595 indicating that the transaction was denied.
596 Thu 12/29 03:39:05 M igmp 12.88.14.10 <-> 128.2.2.10 CON
598 This is an igmp transaction status report, usually seen with MBONE
599 traffic. There was more than one source and destination MAC address
600 pair used to support the transaction, suggesting a possible routing
601 loop.
602 Thu 12/29 06:40:05 * tcp 12.23.14.23.1043 <-> 12.23.14.27.6000 TIM
604 This is an X-windows transaction, that has TIMEDOUT. Packets were
605 retransmitted during the connection.
606 Thu 12/29 07:42:09 udp 12.9.1.115.2262 -> 28.12.141.6.139 INT
608 This is an initial netbios UDP transaction status report, indicating
609 that this is the first datagram encountered for this transaction.
610 Thu 12/29 06:42:09 icmp 12.9.1.115 <-> 12.68.5.127 ECO
612 This example represents a "ping" of host 12.9.1.115, and its response.
613 This next example shows the ra output of a complete TCP transaction, with the
615 preceeding Arp and DNS requests, while reading from a remote argus-server.
616 The '*' in the CLO report indicates that at least one TCP packet was retrans‐
617 mitted during the transaction. The hostnames in this example are ficticious.
618 % ra -S argus-server and host i.qosient.com
620 ra: Trying argus-server port 561
621 ra: connected Argus Version 2.0
622 Sat 12/03 15:29:38 arp i.qosient.com who-has dsn.qosient.com INT
623 Sat 12/03 15:29:39 udp i.qosient.com.1542 <-> dns.qosient.53 INT
624 Sat 12/03 15:29:39 arp i.qosient.com who-has qosient.com INT
625 Sat 12/03 15:29:39 * tcp i.qosient.com.1543 -> qosient.com.smtp CLO
626
628 Carter Bullard (carter@qosient.com).
629
631 /etc/ra.conf
632
634 argus(8) tcpdump(1),
635 Postel, Jon, Internet Protocol, RFC 791, Network Information Center, SRI
637 International, Menlo Park, Calif., May 1981.
638 Postel, Jon, Internet Control Message Protocol, RFC 792, Network Infor‐
640 mation Center, SRI International, Menlo Park, Calif., May 1981.
641 Postel, Jon, Transmission Control Protocol, RFC 793, Network Information
643 Center, SRI International, Menlo Park, Calif., May 1981.
644 Postel, Jon, User Datagram Protocol, RFC 768, Network Information Cen‐
646 ter, SRI International, Menlo Park, Calif., May 1980.
647 McCanne, Steven, and Van Jacobson, The BSD Packet Filter: A New Archi‐
649 tecture for User-level Capture, Lawrwnce Berkeley Laboratory, One
650 Cyclotron Road, Berkeley, Calif., 94720, December 1992.
651ra 2.0 12 November 2000 RA(1)