Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RA(1)			    General Commands Manual			 RA(1)

NAME
       ra - read argus(8) data.

SYNOPSIS
       ra [raoptions] [-- filter-expression]

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

OPTIONS
       -A  Print aggregate statistics for the input stream on termination.

       -b  Dump	the compiled transaction-matching code to standard output  and
	   stop.  This is useful for debugging filter expressions.

       -c <char>
	   Specify a delimiter character for output columns (default is	' ').

       -C <[host]:portnum> (deprecated)
	   Specify  a  source  of Netflow data.	The optional host is the local
	   interface address where Netflow Cisco records are going to be read.
	   If absent, then it is implied that the interface address is AF_ANY.
	   This	option is deprecated and the '-S cisco://address:port' is  now
	   the recommended option.

       -D <level>
	   Print debug information corresponding to <level> to stderr, if pro-
	   gram	 compiled  to support debug printing.  As the level increases,
	   so does the amount of debug information ra(1) will  print.	Values
	   range from 1-8.

       -d  Toggle whether to run this program as a daemon.

       -e <regex>
	   Match  regular  expression  in  flow	user data fields.  Prepend the
	   regex with either "s:" or "d:" to limit the	match  to  either  the
	   source  or destination user data fields. At this time null bytes in
	   the user data buffer	terminate search.  Examples include:
	      "^SSH-"		- Look for ssh connections on any port.
	      "s:^GET"		- Look for HTTP	GET requests in	the source buffer.
	      "d:^HTTP.*Unauth"	- Find unauthorized http response.

	   Depending on	the regular expression library that  the  system  sup-
	   ports,  you	will  be able to match many types of binary, octal and
	   hex expressions.  See regex.3, pcre.3 and the web for examples.

       -E <file>
	   When	using a	filter expression at the end of	the command, this  op-
	   tion	 will  cause  ra(1) to append the records that are rejected by
	   the filter into <file>

       -F <conffile>
	   Use <conffile> as a source of configuration information.  The  for-
	   mat	of  this  file	is  identical  to rarc(5).  The	data read from
	   <conffile> overrides	any prior configuration	information.

       -h  Print an explanation	of all the arguments.

       -H  Abbreviate numeric metrics, to make reading	large  values  easier.
	   Use the -p <num> option to specify the precision right of the deci-
	   mal.

       -L <n>
	   Specify how ra will print header labels for the output.
	      Supported	values are:
		 -1  Don't print header	labels.
		  0  Print the header labels only once,	as the beginning of output.
		> 0  Print the header labels every n lines of output.

       -M <mode	[mode ...]>
	   Provide addition mode operators.  These are generally specific to the
	   individual ra* program, or a	specific function. Available modes for ra()
	   are:

	      disa	       - interpret DSCodepoints	using the US DISA encodings
	      dsrs=dsrlist     - process these dsrs
		 Where a dsrlist has the format:
		    [+/-]dsr[,[+/-]dsr]

		    Supported dsrs are:
		      trans    transport information, such as source id	and seq	number.
		      flow     flow key	data (proto, saddr, sport, dir,	daddr, dport)
		      time     time stamp fields (stime, ltime).
		      metric   basic ([s|d]bytes, [s|d]pkts, [s|d]rate,	[s|d]load)
		      agr      aggregation stats (trans, avgdur, mindur, maxdur, stdev).
		      net      network objects (tcp, esp, rtp, icmp data).
		      vlan     VLAN tag	data
		      mpls     MPLS label data
		      jitter   Jitter data ([s|d]jit, [s|d]intpkt)
		      ipattr   IP attributes ([s|d]ipid, [s|d]tos, [s|d]dsb, [s|d]ttl)
		      psize    packet size information
		      mac      MAC addresses (smac, dmac)
		      icmp     ICMP specific data (icmpmap, inode)
		      encaps   Flow encapsulation type indications
		      behavior Behavioral metrics and data
		      tadj     Time adjustment data
		      cor      Multi-probe correlation data
		      cocode   Country Codes
		      asn      Autonomous System Number	data
		      suser    src user	captured data bytes (suser)
		      duser    dst captured user data bytes (duser)

		 Examples are:
		    -M dsrs=time,flow,metric
		    -M dsrs=-suser,-duser

	      label="regex"    - match flow label with regex(3)	regular	expression.
	      man	       - print management records
	      noman	       - do not	print management records
	      oui	       - print oui labels in mac addresses

	      printer="format" - specify printer formats for printing user data.
		 Supported formats are:
		      ascii	 print user buffer as ascii string. use	'.' for	unprintable chars.
		      obfuscate	 ascii printer with password obfuscation.
		      hex	 print hex dump	of user	buffer on separate lines.
		      encode32	 print user buffer as 32-bit chars.
		      encode64	 print user buffer using 64-bit	chars.

	      poll	       - successfully attach to	remote data source and then exit
	      rmon	       - modify	data to	support	unidiretional RMON stat	reporting
	      rtime:factor     - read data from	a file,	clocking records in as if they
				 being read in realtime.  Factor provides an opportunity
				 to specify a multiplication factor, enabling you to
				 read records in a fraction of real time, slowing down
				 reading considerably, or a factor of time, enabling
				 controlled speedup of the reading rate.

	      saslmech="mech"  - specify a mandatory SASL mech
	      sql="select"     - use "select" as select	clause in mysql	calls when supported.
	      TZ="tzset"       - specify a tzset(3) time zone specification
	      uni	       - generate unidirectional flow data
	      xml	       - print output in xml format.

	   Illegal  modes  are	not detectable by the standard library,	and so
	   unexpected results in command line parsing may occur	if care	is not
	   taken with use of this option.

       -n  Modify number to name converstion.  This flag  supports  4  states,
	   specified by	the modulus of the number of -n	flags set.  By default
	   ra*	programs  do  not provide hostname lookups, but	they do	lookup
	   port	and protocol names.  The first -n will suppress	port number to
	   service conversion, -nn will	suppress translation of	protocol  num-
	   bers	 to  names (no lookups).  -nnn will return you to full conver-
	   sion, translating hostnames,	port and  protocol  names,  and	 -nnnn
	   will	 return	 you to	the default behavior.	Because	this indicator
	   can be set in the .rarc file, multiple -n  flags  progress  through
	   the cycle.

       -N [io]<num>, [io]<start-end>, [io]<start+num>
	   Process the first <num> records, the	inclusive range	<start - end>,
	   or process <num + 1>	records	starting at index number <start>.  The
	   optional  1st  character indicates whether the specification	is ap-
	   plied to the	input or the output stream of records, the default  is
	   input.   If	applied	 to  the input,	these are the range of records
	   that	match the input	filter.

       -p <digits>
	   Print <digits> number of units of precision for floating point val-
	   ues.

       -q  Run in quiet	mode. Configure	Ra to not print	out  the  contents  of
	   records.  This can be used for a number of maintenance tasks, where
	   you	would  be  interested  in  the	outcome	 of  a program,	or its
	   progress, say with the  -D  option,	without	 printing  each	 input
	   record.

       -r [- | <[type:]file[::soffset[:eoffset]] ...>]
	   Read	<type> data from <files> in the	order presented	on the comman-
	   dline. '-' denotes stdin.  Ra supports reading argus	type data (de-
	   fault),  cisco and ft, flow-tools type data.	 If you	want to	read a
	   set of files	and then, when done,  read  stdin,  use	 multiple  oc-
	   curences  of	 the  -r option.  Ra can read gzip(1), bzip2(1), xz(1)
	   and compress(1) compressed data files. Byte offset values allow the
	   specification of a range of records within  an  uncompressed	 file.
	   Byte	 offsets  must	be  aligned to record boundaries. Valid	record
	   offsets can be obtained using +offset as an output field even  from
	   compressed files.

	   Examples are:
	      -r file1 file2		  read argus records from file1, then file2.
	      -r file::34876		  read argus records starting at byte offset 34876
	      -r file::34876:35846	  read argus records starting at byte offset 34876 and ending at 35846
	      -r cisco:file		  read cisco netflow records from file
	      -r ft:file		  read flow-tools based	records

       -R <dir dir ...>
	   Recursively	decend the directory and process all the regular files
	   that	are encountered.  The function does not	decend	to  links,  or
	   directories that begin with '.'.  The feature, like the -r command,
	   does	not do any file	type checking.

       -s <[-][[+[#]]field[:len[:format]] ...>
	   Specify the fields to print.	 ra.1 gets the field print list	either
	   from	its rarc configuration files or	from the command-line.	In the
	   case	 where	there  is  no  configuration given ra.1	uses a default
	   printing field list,	with default field lengths.  By	 specifying  a
	   space  separated  list  of  fields, this option provides a means to
	   completely redefine the list	from the command line.	Using the  op-
	   tional  '-'	and '+[#]' prepended to	the field list,	you can	add or
	   subtract fields from	the configured list.  Field lengths  are  hard
	   constraints,	and field output that exceeds the field	length will be
	   truncated,  and a '*' will be inserted as the last character.  When
	   you see this, add more to the length	specification  for  that  spe-
	   cific  field.   Field  lengths (len)	less than 1, are not permitted
	   and will generate an	error.	The optional  'format'	specification,
	   uses	sprintf.1 syntax to format the value.  The available fields to
	   print are:

	   srcid       argus source identifier.
	   rank	       Ordinal	value of this output flow record i.e. sequence
		       number.
	   stime       record start time
	   ltime       record last time.
	   trans       aggregation record count.
	   flgs	       flow state flags	seen in	transaction.
	   seq	       argus sequence number.
	   dur	       record total duration.
	   runtime     total active flow run time.  This  value	 is  generated
		       through	aggregation, and is the	sum of the records du-
		       ration.
	   idle	       time since the last packet  activity.   This  value  is
		       useful in real-time processing, and is the current time
		       - last time.
	   mean	       average duration	of aggregated records.
	   stddev      standard	deviation of aggregated	duration times.
	   sum	       total accumulated durations of aggregated records.
	   min	       minimum duration	of aggregated records.
	   max	       maximum duration	of aggregated records.
	   smac	       source MAC addr.
	   dmac	       destination MAC addr.
	   soui	       oui portion of the source MAC addr.
	   doui	       oui portion of the destination MAC addr.
	   saddr       source IP addr.
	   daddr       destination IP addr.
	   proto       transaction protocol.
	   sport       source port number.
	   dport       destination port	number.
	   stos	       source TOS byte value.
	   dtos	       destination TOS byte value.
	   sdsb	       source diff serve byte value.
	   ddsb	       destination diff	serve byte value.
	   sco	       source IP address country code.
	   dco	       destination IP address country code.
	   sttl	       src -> dst TTL value.
	   dttl	       dst -> src TTL value.
	   shops       estimate	of number of IP	hops from src to this point.
	   dhops       estimate	of number of IP	hops from dst to this point.
	   sipid       source IP identifier.
	   dipid       destination IP identifier.
	   smpls       source MPLS identifier.
	   dmpls       destination MPLS	identifier.
	   autoid      Auto generated identifier (mysql).
	   sas	       Src origin AS
	   das	       Dst origin AS
	   ias	       Intermediate origin AS, AS of ICMP generator
	   cause       Argus  record cause code.  Valid	values are Start, Sta-
		       tus, Stop, Close, Error
	   nstroke     Number of observed keystrokes.
	   snstroke    Number of observed keystrokes from initiator  (src)  to
		       target (dst).
	   dnstroke    Number of observed keystrokes from target (dst) to ini-
		       tiator (src).
	   pkts	       total transaction packet	count.
	   spkts       src -> dst packet count.
	   dpkts       dst -> src packet count.
	   bytes       total transaction bytes.
	   sbytes      src -> dst transaction bytes.
	   dbytes      dst -> src transaction bytes.
	   appbytes    total application bytes.
	   sappbytes   src -> dst application bytes.
	   dappbytes   dst -> src application bytes.
	   pcr	       producer	consumer  ratio.
	   load	       bits per	second.
	   sload       source bits per second.
	   dload       destination bits	per second.
	   loss	       pkts retransmitted or dropped.
	   sloss       source pkts retransmitted or dropped.
	   dloss       destination pkts	retransmitted or dropped.
	   ploss       percent pkts retransmitted or dropped.
	   psloss      percent source pkts retransmitted or dropped.
	   pdloss      percent destination pkts	retransmitted or dropped.
	   retrans     pkts retransmitted.
	   sretrans    source pkts retransmitted.
	   dretrans    destination pkts	retransmitted.
	   pretrans    percent pkts retransmitted.
	   psretrans   percent source pkts retransmitted.
	   pdretrans   percent destination pkts	retransmitted.
	   sgap	       source  bytes missing in	the data stream. Available af-
		       ter argus-3.0.4
	   dgap	       destination bytes missing in the	data stream. Available
		       after argus-3.0.4
	   rate	       pkts per	second.
	   srate       source pkts per second.
	   drate       destination pkts	per second.
	   dir	       direction of transaction
	   sintpkt     source interpacket arrival time (mSec)
	   sintdist    source interpacket arrival time distribution
	   sintpktact  source active interpacket arrival time (mSec)
	   sintdistact source active interpacket arrival time (mSec)
	   sintpktidl  source idle interpacket arrival time (mSec)
	   sintdistidl source idle interpacket arrival time (mSec)
	   dintpkt     destination interpacket arrival time (mSec)
	   dintdist    destination interpacket arrival time distribution
	   dintpktact  destination active interpacket arrival time (mSec)
	   dintdistact destination active interpacket arrival  time  distribu-
		       tion (mSec)
	   dintpktidl  destination idle	interpacket arrival time (mSec)
	   dintdistidl destination idle	interpacket arrival time distribution
	   sjit	       source jitter (mSec).
	   sjitact     source active jitter (mSec).
	   sjitidle    source idle jitter (mSec).
	   djit	       destination jitter (mSec).
	   djitact     destination active jitter (mSec).
	   djitidle    destination idle	jitter (mSec).
	   state       transaction state
	   label       Metadata	label.
	   suser       source user data	buffer.
	   duser       destination user	data buffer.
	   swin	       source TCP window advertisement.
	   dwin	       destination TCP window advertisement.
	   svlan       source VLAN identifier.
	   dvlan       destination VLAN	identifier.
	   svid	       source VLAN identifier.
	   dvid	       destination VLAN	identifier.
	   svpri       source VLAN priority.
	   dvpri       destination VLAN	priority.
	   srng	       start time for the filter timerange.
	   erng	       end time	for the	filter timerange.
	   stcpb       source TCP base sequence	number
	   dtcpb       destination TCP base sequence number
	   tcprtt      TCP  connection	setup  round-trip  time,  the  sum  of
		       'synack'	and 'ackdat'.
	   synack      TCP connection setup time, the time between the SYN and
		       the SYN_ACK packets.
	   ackdat      TCP connection setup time, the time between the SYN_ACK
		       and the ACK packets.
	   tcpopt      The TCP connection options  seen	 at  initiation.   The
		       tcpopt indicator	consists of a fixed length field, that
		       reports	presence  of any of the	TCP options that argus
		       tracks The format is:

			M	     -	Maxiumum Segment Size
			 w	     -	Window Scale
			  s	     -	Selective ACK OK
			   S	     -	Selective ACK
			    e	     -	TCP Echo
			     E	     -	TCP Echo Reply
			      T	     -	TCP Timestamp
			       c     -	TCP CC
				N    -	TCP CC New
				 O   -	TCP CC Echo
				  S  -	Source Explicit	Congestion Notification
				   D -	Destination Explicit Congestion	Notification

	   inode       ICMP intermediate node.
	   offset      record byte offset in file or stream.
	   smeansz     Mean of the flow	packet size transmitted	by the src (initiator).
	   dmeansz     Mean of the flow	packet size transmitted	by the dst (target).

	   spktsz      histogram for the src packet size distribution
	   smaxsz      maximum packet size for traffic transmitted by the src.
	   dpktsz      histogram for the dst packet size distribution
	   dmaxsz      maximum packet size for traffic transmitted by the dst.
	   sminsz      minimum packet size for traffic transmitted by the src.
	   dminsz      minimum packet size for traffic transmitted by the dst.

	   dminsz      minimum packet size for traffic transmitted by the dst.

	   Examles are:
	      -s saddr	    print only the source address.
	      -s -bytes	    removes the	bytes field from list.
	      -s +2srcid    adds the source identifier as the 2nd field.
	      -s spkts:18   prints src pkt count with a	column width of	18.
	      -s smpls	    print the local mpls label in the flow.

       -S <[URI://][user[:pass]@]host[:portnum]>
	   Specify a remote source of flow data.  Read flow data from  various
	   data	format and transport strategies, using the URI format to indi-
	   cate	 the  type  of flow data record	of interest (argus-tcp,	argus-
	   udp,	cisco, jflow, sflow) and the source, as	a name or an addresss,
	   providing an	option user and	password for  protected	 access.   Use
	   the optional	':portnum' to specify a	port number other than the de-
	   fault; 561.

	   Examles are:
	      -S localhost		   request remote argus	records	from localhost,	using default methods.
	      -S user@localhost		   request argus records from localhost, as 'user'.
	      -S user:pass@localhost	   request argus records from localhost, as 'user', with 'pass'	password.
	      -S 192.168.0.4:12345	   request via TCP argus records from 192.168.0.4, port	12345.
	      -S argus://user@anubis	   request argus records from anubis, via TCP port 561,	as 'user'.
	      -S argus-tcp://thoth:12345   request argus records via TCP from thoth, port 12345.
	      -S argus-udp://set:12345	   request argus records via UDP from set, port	12345.
	      -S cisco://any:9996	   read	cisco netflow records from AF_ANY, on port 9996.
	      -S jflow://10.0.0.2:9898	   read	jflow records sent to 10.0.0.2,	on port	9898.
	      -S sflow://localhost:6343	   read	sflow records sent to localhost	interface, port	6343.

       -t <timerange>
	   Specify the <time range> for	matching argus(5) records. This	option
	   supports  a	high  degree  of flexibility in	specifing explicit and
	   relative time ranges	with support for time field wildcarding.

	   The syntax for the <time range> is:
	   [timeComparisonInd]timeSpecification[-timeSpecification]
	      timeComparisonInd: [x]i |	n | c	 (default = i)
		x  negation   reverses the result of the time comparison
		i  intersects match records that were active during this time period
		n  includes   match records that start before and end after the	period
		c  contained  match records that start and end during the period

	      timeSpecification: [[[yyyy/]mm/]dd.]HH[:MM[:SS]]
				   [yyyy/]mm/dd
				   yyyy
				   %d{ymdHMS}
				   seconds
				   { + | - }%d{ymdHMS}

	      where '*'	can be used as a wildcard.

	   Examples are:
	      -t 14		 specify the time range	2pm-3pm	for today
	      -t 15-23		 specify the time range	3pm-11pm for today
	      -t 2011		 all records in	the year 2011
	      -t 2011/08	 all records in	Aug of the year	2011
	      -t 2011/08-2011/10 all records in	Aug, Sept, and Oct of the year 2011

	      -t **.14		 specify 2pm-3pm, every	day this month
	      -t 1270616652+2s	 all records that span 10/04/07.01:04:12 EDT.
	      -t 1999y1m23d10h	 matches 10-11am on Jan, 23, 1999
	      -t 10d*h*m15s	 matches records that intersect	the 15 sec,
				 any minute, any hour, on the 10th of this month
	      -t ****/11/23	 all records in	Nov 23rd, any year
	      -t 23.11:10-14	 11:10:00 - 2pm	on the 23rd of this month
	      -t -10m		 matches 10 minutes before, to the present
	      -t -1M+1d		 matches the first day of the this month.
	      -t -2h5m+5m	 matches records that start before and end
				 after the range starting 2 hours 5 minutes
				 prior to the present, and lasting 5 minutes.

	   Time	is compared using basic	intersection operations.  A record iP-
	   ntersects a specified time range if there is	any  intersection  be-
	   tween  the  time range of the record	and the	comparison time	range.
	   This	is the default behavior.  A  record  includes  the  comparison
	   time	range if the intersection of the two ranges equals the compar-
	   ison	 time,	and a record is	contained when the intersection	equals
	   the duration	of the record.	The comparison indicator is the	 first
	   character of	the range specification, without spaces.

	   Examples are:
	      -t n14:10:15-14:10:19  records include these 4s.
	      -t c14:10-14:10:10     record starts and ends within these 10s.
	      -t xi-5s+25s	     record starts or ends 5 seconds earlier and
				     20	seconds	after 'now'.

       -T <secs>
	   Read	argus(5) from remote server for	<secs> of time.

       -u  Print time values using Unix	time format (seconds from the Epoch).

       -w <file> [filter-expression]
	   Append  matching  data  to <file>, in argus file format. An output-
	   file	of '-' directs ra to write the argus(5)	records	to stdout, al-
	   lowing for "chaining" ra* style commands  together.	 The  optional
	   filter-expression can be used to select specific output.

       -X  Resets  all	options	to their default values	and overrides the rarc
	   file	contents (Use as the first option.)

       -z  Modify status field to represent TCP	state changes. The  values  of
	   the status field when this is enabled are:
	     's' - Syn Transmitted
	     'S' - Syn Acknowledged
	     'E' - TCP Established
	     'f' - Fin Transmitted  (FIN Wait State 1)
	     'F' - Fin Acknowledged (FIN Wait State 2)
	     'C' - Normal Closed
	     'R' - TCP Reset

       -Z <s|d|b>
	   Modify  status  field  to reprsent actual TCP flag values. <'s'rc |
	   'd'st | 'b'oth>.  The characters that can be	present	in the	status
	   field when this is enabled are:

	     'F' - Fin
	     'S' - Syn
	     'R' - Reset
	     'P' - Push
	     'A' - Ack
	     'U' - Urgent Pointer
	     '7' - Undefined 7th bit set
	     '8' - Undefined 8th bit set

RETURN VALUES
       ra exits	with one of the	following values:

	  0  Records matched condition,	considering the	options	provided.

	  1  No	records	matched	the condition, or the source was not an	argus stream.

	> 1  An	error occurred.

FILTER EXPRESSION
       If  arguments  remain after option processing, the collection is	inter-
       preted as a single filter expression.  In order to indicate the end  of
       arguments,  a  '--' (double dash) is required before the	filter expres-
       sion is added to	the command line.  Historically, a '-'	(single	 dash)
       was  used  to  separate the filter expression from the command line op-
       tions, but newer	versions of getopt.1  now  require  the	 '--'  (double
       dash).

       The filter expression specifies which argus(5) records will be selected
       for  processing.	  If no	expression is given, all records are selected,
       otherwise, only those records for which expression is  `true'  will  be
       printed.

       The  syntax is very similar to the expression syntax for	tcpdump(1), as
       the tcpdump compiler was	a starting point for the argus(5)  filter  ex-
       pression	compiler.  However, the	semantics for tcpdump(1)'s packet fil-
       ter  expressions	 are different when applied to transaction record fil-
       tering, so there	are some major differences.

       When attached to	a remote argus,	ra will	send the filter	to  the	 argus
       process,	 which	compiles the filter, and uses it to select which argus
       records will be transmitted to the ra application.  If you do not  want
       to  send	a filter to the	remote argus, prepend the filter with the key-
       word "local", to	indicate that the filtering will be  done  within  the
       local ra	process.

       The  expression consists	of one or more primitives.  Primitives usually
       consist of an id	(name or number) preceded by one or  more  qualifiers.
       There are three different kinds of qualifier:

       type   qualifiers  say  what kind of thing the id name or number	refers
	      to.  Possible types are srcid, encaps,  ether,  host,  net,  co,
	      port,  tos,  ttl,	 ptks, bytes, appbytes,	pcr, data, rate, load,
	      loss, ploss, vid,	vpri, and mid.

	      E.g.,  `srcid  isis`,  `encaps   gre',   `host   sphynx',	  `net
	      192.168.0.0/16',	`port domain', `ttl 1',	'ptks gt 2', 'ploss lt
	      5'.  If there is no type qualifier, host is assumed.

       dir    qualifiers specify a particular  transfer	 direction  to	and/or
	      from  an	id.   Possible directions are src, dst,	src or dst and
	      src and dst.  E.g., `src sphynx',	`dst net 192.168.0.0/24', `src
	      or dst port ftp',	`src and dst tos 0x0a',	`src or	dst vid	0x12`,
	      `dst vpri	0x02` .	 If there is no	dir qualifier, src or  dst  is
	      assumed.

       proto  qualifiers  restrict the match to	a particular protocol.	Possi-
	      ble values are those specified in	the /etc/protocols system file
	      and a small number of extensions,	(that should  be  defined  but
	      aren't).	 Specific extended values are 'ipv4', (to specify just
	      ip version 4), in	contrast to the	defined	proto 'ipv6'.  The de-
	      fined proto 'ip' reduces to the filter 'ipv4 or ipv6'.

	      When preceeded by	ether, the protocol names and numbers that are
	      valid are	specified in ./include/ethernames.h.

       In addition to the above, there are some	special	 `primitive'  keywords
       that  don't follow the pattern: gateway,	multicast, and broadcast.  All
       of these	are described below.

       More complex filter expressions are built up by using the words and, or
       and not to combine primitives.  E.g., `host foo and not	port  ftp  and
       not  port  ftp-data'.  To save typing, identical	qualifier lists	can be
       omitted.	 E.g., `tcp dst	port ftp or ftp-data or	domain'	is exactly the
       same as `tcp dst	port ftp or tcp	dst port ftp-data or tcp dst port  do-
       main'.

       Allowable primitives are:

       srcid argusid
	      True if the argus	identifier field in the	Argus record is	srcid,
	      which may	be an IP address, a name or a decimal/hexidecimal num-
	      ber.

       seq [gt | gte | lt | lte	| eq] number
	      True  if	the  transport	sequence  number  in  the Argus	record
	      matches the sequence number expression.

       encaps type
	      True if the encapsulation	used by	the flow in the	 Argus	record
	      includes the type.  The list of valid encapsulation types	is:
		 eth, mpls, 802q, llc, pppoe, isl, gre,	erspan,	ah, ipnip, ipnip6, hdlc, chdlc,
		 atm, sll, fddi, slip, arc, wlan, prism, avs, lrh, grh,	teredo,	udt, ipsec, juniper

       dst host	host
	      True if the IP destination field in the Argus record is host,
	      which may	be either an address or	a name.

       src host	host
	      True if the IP source field in the Argus record is host.

       host host
	      True if either the IP source or destination in the Argus record is host.
	      Any of the above host expressions	can be prepended with the keywords
	      ip, arp, or rarp as in:
		   ip host host
	      which is equivalent to:
		   ether proto ip and host host
	      If  host is a name with multiple IP addresses, each address will
	      be checked for a match.

       ether dst ehost
	      True if the ethernet destination address is ehost.  Ehost	may be
	      either a name from /etc/ethers or	a number (see  ethers(3N)  for
	      numeric format).

       ether src ehost
	      True if the ethernet source address is ehost.

       ether host ehost
	      True  if	either	the  ethernet source or	destination address is
	      ehost.

       gateway host
	      True if the transaction used host	as a gateway.  I.e., the  eth-
	      ernet  source or destination address was host but	neither	the IP
	      source nor the IP	destination was	host.  Host must be a name and
	      must be found in both /etc/hosts and /etc/ethers.	  (An  equiva-
	      lent expression is
		   ether host ehost and	not host host
	      which  can  be  used  with  either  names	 or numbers for	host /
	      ehost.)

       dst net cidr
	      True if the IP destination address in the	Argus  record  matches
	      the cidr address.

       src net cidr
	      True  if	the  IP	source address in the Argus record matches the
	      cidr address.

       net cidr
	      True if either the IP source or destination address in the Argus
	      record matches cidr address.

       dst port	port
	      True if the network transaction is IP based,  using  either  the
	      TCP  or UDP transport protocols, and a destination port value of
	      port.  The port can be a number or a name	as configured  in  the
	      /etc/services  file.(see	tcp(4P)	 and  udp(4P)).	  If a name is
	      used, both the protocol number and port number, are checked.  If
	      a	number or ambiguous name is used, the port number  is  checked
	      for  both	 UDP  and TCP protocols	(e.g., dst port	513 will print
	      both tcp/login traffic and udp/who traffic, and port domain will
	      match both tcp/domain and	udp/domain traffic).  Port ranges  can
	      be specified using numeric values, such as port 53-215.

       src port	port
	      True if the network transaction has a source port	value of port.

       port port
	      True  if	either	the  source  or	 destination port in the Argus
	      record is	port.  Any  of	the  above  port  expressions  can  be
	      prepended	with the keywords, tcp or udp, as in:
		   tcp src port	port
	      which matches only tcp connections.

       ip proto	protocol
	      True  if	the  Argus record is an	ip transaction (see ip(4P)) of
	      protocol type protocol.  Protocol	can be a number	or any of  the
	      string values found in /etc/protocols.

       multicast
	      True  if	the  network  transaction involved an ip multicast ad-
	      dress.  By specifing  ether  multicast,  you  can	 select	 argus
	      records that involve an ethernet multicast address.

       broadcast
	      True  if	the  network  transaction involved an ip broadcast ad-
	      dress.  By specifing  ether  broadcast,  you  can	 select	 argus
	      records that involve an ethernet broadcast address.

       ether proto protocol
	      True  if	the  Argus record is of	ether type protocol.  Protocol
	      can be a number or a name	like ip, arp, or rarp.

       [src | dst] ttl [gt | gte | lt |	lte | eq] number
	      True if the TTL in the Argus record equals number.

       [src | dst] tos [gt | gte | lt |	lte | eq] number
	      True if the TOS in the Argus record (default) equals number.

       [src | dst] vid [gt | gte | lt |	lte | eq] number
	      True if th VLAN id in the	Argus record (default) equals number.

       [src | dst] vpri	[gt | gte | lt | lte | eq] number
	      True if the VLAN priority	in the Argus record  (default)	equals
	      number.

       [src | dst] mid [gt | gte | lt |	lte | eq] number
	      True if the MPLS Label in	the Argus record (default) equals num-
	      ber.

       [src | dst] pkts	[gt | gte | lt | lte | eq] number
	      True  if	the  packet count in the Argus record (default)	equals
	      number.

       [src | dst] bytes [gt | gte | lt	| lte |	eq] number
	      True if the byte count in	the Argus record (default) equals num-
	      ber.

       [src | dst] appbytes [gt	| gte |	lt | lte | eq] number
	      True if the application byte count in the	Argus record (default)
	      equals number.

       [src | dst] rate	[gt | gte | lt | lte | eq] number
	      True if the rate in the Argus record (default) equals number.

       [src | dst] load	[gt | gte | lt | lte | eq] number
	      True if the load in the Argus record (default) equals number.

       Ra filter expressions support primitives	 that  are  specific  to  flow
       states and can be used to select	flow records that were in these	states
       at the time they	were generated.	 normal, wait, timeout,	est or con

       Primitives  that	select flows that experienced fragmentation.  frag and
       fragonly

       Support for selecting flows that	used multiple pairs of	MAC  addresses
       during their lifetime.  multipath

       Primitives specific to TCP flows	are supported.	syn, synack, ecn, fin,
       finack, reset, retrans, outoforder and winshut

       Primitives specific to TCP options are supported.  tcpopt, mss, wscale,
       selackok, selack, tcpecho, tcpechoreply,	tcptimestamp, tcpcc, tcpccnew,
       tcpccecho, secn and decn

       Primitives  specific to ICMP flows are supported.  echo,	unreach, redi-
       rect and	timexed

       For some	primitives, a direction	qualifier is appropriate.   These  are
       frag, reset, retrans, outoforder	and winshut

       Primitives may be combined using:

	      A	 parenthesized	group of primitives and	operators (parentheses
	      are special to the Shell and must	be escaped).

	      Negation (`!' or `not').

	      Concatenation (`and').

	      Alternation (`or').

       Negation	has highest precedence.	 Alternation  and  concatenation  have
       equal  precedence  and associate	left to	right.	Note that explicit and
       tokens, not juxtaposition, are now required for concatenation.

       If an identifier	is given without a keyword, the	most recent keyword is
       assumed.	 For example,
	    not	host sphynx and	anubis
       is short	for
	    not	host sphynx and	host anubis
       which should not	be confused with
	    not	( host sphynx or anubis	)

       Expression arguments can	be passed to ra(1) as either a single argument
       or as multiple arguments, whichever is more convenient.	Generally,  if
       the  expression	contains Shell metacharacters, it is easier to pass it
       as a single, quoted argument.  Multiple arguments are concatenated with
       spaces before being parsed.

   Startup Processing
       Ra begins by searching for the configuration file .rarc	first  in  the
       directory,  $ARGUSHOME  and then	$HOME.	If a .rarc is found, all vari-
       ables specified in the file are set.

       Ra then parses its command line options and set its internal  variables
       accordingly.

       If a configuration file is specified on the command-line, using the "-f
       <confile>"  option,  the	 values	in this	.rarc formatted	file superceed
       all other values.

EXAMPLES
       To report all TCP transactions from and to host 'narly.wave.com', read-
       ing transaction data from argus-file argus.data:
	      ra -r argus.data - tcp and host narly.wave.com

       To report all UDP based DNS traffic, reading transaction	data from  the
       remote argus.server:
	      ra -S argus.server - udp port domain

       To  report  all UDP transactions	seen by	the remote argus.server	on the
       port range 53-256, but not sending  the	filter	to  the	 remote	 argus
       process:
	      ra -S argus.server - local udp port 53-256

       Create  the argus-file icmp.log with all	ICMP events involving the host
       nimrod, using data from argus-file, but reading	the  transaction  data
       from stdin:
	      cat argus-file | ra -r - -w icmp.log - icmp and host nimrod

       Read an argus-file at twice normal speed.
	      ra -r argus.file -M rtime:2

OUTPUT FORMAT
       The  following  is  a brief description of the default output of	.B ra.
       While this is by	no means the 'preferred' set of	data that  one	should
       generate,  it  represents  a starting point for using flow data in gen-
       eral.  This also	looks pretty good on 80	column terminals.  The	format
       is:
		time  flgs proto  shost	 dir  daddr metrics state

       time
	   The	format of the time field is specified by the .rarc file, using
	   syntax supported by the routine strftime(3V).  The default is '%T'.
	   Argus transactional data contains both starting and ending transac-
	   tion	times, with precision to the microsecond. However, ra  by  de-
	   fault prints	out the	'stime'	field, the records starting time.

       flgs
	   The	flgs  indicator	consists of a fixed length field. That reports
	   various flow	record and protocol identifiers,  states  and  attrib-
	   utes.  The format is:

	    T	     -	Time Corrected/Adjusted
	    N	     -	Netflow	Originated Data
	     *	     -	Multiple sub-IP	encapsulations
	     e	     -	Ethernet encapsulated flow
	     E	     -	ERSPAN encapsulation
	     M	     -	Multiple mac addresses seen
	     m	     -	MPLS encapsulated flow
	     l	     -	LLC encapsulated flow
	     v	     -	802.1Q encapsulations/tags
	     w	     -	802.11 wireless	encapsulation
	     p	     -	PPP over Enternet encapsulated flow
	     i	     -	ISL encapsulated flow
	     G	     -	GRE encapsulation
	     a	     -	AH encapsulation
	     P	     -	IP tunnel encapsulation
	     6	     -	IPv6 tunnel encapsulation
	     H	     -	HDLC encapsulation
	     C	     -	Cisco HDLC encapsulation
	     A	     -	ATM encapsulation
	     S	     -	SLL encapsulation
	     F	     -	FDDI encapsulation
	     s	     -	SLIP encapsulation
	     R	     -	ARCNET encapsulation
	      I	     -	ICMP events mapped to this flow
	      U	     -	ICMP Unreachable event mapped to this flow
	      R	     -	ICMP Redirect event mapped to this flow
	      T	     -	ICMP Time Exceeded mapped to this flow
	       *     -	Both Src and Dst loss/retransmission
	       s     -	Src loss/retransmissions
	       d     -	Dst loss/retransmissions
	       g     -	Gaps in	sequence numbers were observed
	       &     -	Both Src and Dst packet	out of order
	       i     -	Src packets out	of order
	       r     -	Dst packets out	of order
		@    -	Both Src and Dst Window	Closure
		S    -	Src TCP	Window Closure
		D    -	Dst TCP	Window Closure
		*    -	Silence	suppression used by both src and dst (RTP)
		s    -	Silence	suppression used by src
		d    -	Silence	suppression used by dst
		 E   -	Both Src and Dst ECN
		 x   -	Src Explicit Congestion	Notification
		 t   -	Dst ECN
		  V  -	Fragment overlap seen (if fragments seen)
		  f  -	Partial	Fragment (if fragments seen)
		  F  -	Fragments seen
		   O  -	 multiple IP options set
		   S  -	 IP option Strict Source Route
		   L  -	 IP option Loose Source	Route
		   T  -	 IP option Time	Stamp
		   +  -	 IP option Security
		   R  -	 IP option Record Route
		   A  -	 IP option Router Alert
		   U  -	 unknown IP options set

       proto
	   The	proto  field indicates the upper protocol used in the transac-
	   tion.  This field will contain the first 4 characters of the	 offi-
	   cial	 name  for the protocol	used, as defined in RFC-1700, and con-
	   figured using the /etc/protocols file.  Argus attempts to discovery
	   the Realtime	Transport Protocol (rtp), when it is being used.  When
	   it encounters rtp, it will indicate its use in this field, with the
	   string 'rtp'.  Use of the -n	option,	twice (-nn),  will  cause  the
	   actual protocol number to be	displayed.

       shost
	   The	shost  field  is meant to convey the originator	of the data in
	   the flow.  This field is protocol dependent,	and for	 IP  protocols
	   will	 contain  the src IP address/name.  For	TCP and	UDP, the field
	   will	also contain the port number/name, separated by	a period.

	   The 'src' is	generally the entity that  first  transmits  a	packet
	   that	 is  a	part  of a flow.  However, the assignment of 'src' and
	   'dst' semantics is somewhat complicated by the notion of  loss,  or
	   half-duplex	monitoring, especially when connection-oriented	proto-
	   col , such as TCP, are reported.  In	this case the 'src' is the en-
	   tity	that initiated the flow.

       dir
	  The dir field	will have the direction	of the transaction, as can  be
	  best	determined from	the datum, and is used to indicate which hosts
	  are transmitting. For	TCP, the dir field indicates the actual	source
	  of the TCP connection, and the center	character indicating the state
	  of the transaction.
	       -  - transaction	was NORMAL
	       |  - transaction	was RESET
	       o  - transaction	TIMED OUT.
	       ?  - direction of transaction is	unknown.

       daddr
	   The daddr field is meant to convey the recipient of the data	in the
	   flow.  Like the shost field,	this field is protocol dependent,  and
	   for	IP protocols will contain the dst IP address/name, and option-
	   ally	the DSAP.

       metrics
	   metrics represent the general sets of fields	that reflect  the  ac-
	   tivity  of  the  flow.   In the default output, there are 4 fields.
	   The first 2 are the packet counts and  the  last  2	are  the  byte
	   counts  for	the  specific transaction.  The	fields are paired with
	   the previous	host fields, and represent the packets transmitted  by
	   the respective host.

       state
	   The	state  field indicates the principle state for the transaction
	   report, and is protocol dependent.  For all the  protocols,	except
	   ICMP, this field reports on the basic state of a transaction.

	 REQ|INT (requested|initial)
	   This	indicates that this is the initial state report	for a transac-
	   tion	and is seen only when the argus-server is in DETAIL mode.  For
	   TCP	connections this is REQ, indicating that a connection is being
	   requested.  For the connectionless protocols, such as UDP, this  is
	   INT.

	 ACC (accepted)
	   This	 indicates that	a request/response condition has occurred, and
	   that	a transaction has been detected	between	two hosts.   For  TCP,
	   this	indicates that a connection request has	been answered, and the
	   connection  will  be	 accepted.   This is only seen when the	argus-
	   server is in	DETAIL mode.  For the connectionless  protocols,  this
	   state  indicates  that  there has been a single packet exchange be-
	   tween two hosts, and	could qualify as a  request/response  transac-
	   tion.

	 EST|CON (established|connected)
	   This	record type indicates that the reported	transaction is active,
	   and	has  been established or is continuing.	 This should be	inter-
	   preted as a state report of a currently  active  transaction.   For
	   TCP,	 the EST state is only seen in DETAIL mode, and	indicates that
	   the three way handshake has been completed for a connection.

	 CLO (closed)
	   TCP specific, this record type indicates that  the  TCP  connection
	   has closed normally.

	 TIM (timeout)
	   Activity  was not seen relating to this transaction,	during the ar-
	   gus server's	timeout	period for this	protocol.  This	state is  seen
	   only	 when  there  were  packets recorded since the last report for
	   this	transaction.

       For the ICMP and	ICMPv6 protocols, the state  field  displays  specific
       aspects of the ICMP type.  ICMP state can have the values:

	  ECO	  Echo Request
	  ECR	  Echo Reply
	  SRC	  Source Quench
	  RED	  Redirect
	  RTA	  Router Advertisement
	  RTS	  Router Solicitation
	  TXD	  Time Exceeded
	  PAR	  Parameter Problem
	  TST	  Time Stamp Request
	  TSR	  Time Stamp Reply
	  IRQ	  Information Request
	  IRR	  Information Reply
	  MAS	  Mask Request
	  MSR	  Mask Reply
	  URN	  Unreachable network
	  URH	  Unreachable host
	  URP	  Unreachable port
	  URF	  Unreachable need fragmentation
	  URS	  Unreachable source failed
	  URNU	  Unreachable dst network unknown
	  URHU	  Unreachable dst host unknown
	  URISO	  Unreachable source host isolated
	  URNPRO  Unreachable network administrative prohibited
	  URHPRO  Unreachable host administrative prohibited
	  URNTOS  Unreachable network TOS prohibited
	  URHTOS  Unreachable host TOS prohibited
	  URFIL	  Unreachable administrative filter
	  URPRE	  Unreachable precedence violation
	  URCUT	  Unreachable precedence cutoff

	  MRQ	  Membership Query
	  MHR	  Membership Report
	  NRS	  Neighbor Discovery Router Solicit
	  NRA	  Neighbor Discovery Router Advertisement
	  NNS	  Neighbor Discovery Neighbor Solicit
	  NNA	  Neighbor Discovery Neighbor Advertisement
	  PTB	  Packet Too Big

OUTPUT EXAMPLES
       These  examples	show  typical  ra output, and demonstrates a number of
       variations seen in argus	data.  This ra output was generated using  the
       -n option to suppress number translation.

 Thu 12/29 06:40:32   S	tcp  132.3.31.15.6439	-> 12.23.14.77.23   CLO
       This   is  a  normal  tcp  transaction  to  the	telnet	port  on  host
       12.23.14.77.  The IP Option strict source route was seen.

 Thu 12/29 06:40:32	tcp  132.3.31.15.6200  <|  12.23.14.77.25   RST
       This tcp	transaction from the smtp port of host 12.23.14.77 was	RESET.
       In many cases this indicates that the transaction was rejected, however
       some  os's  will	 use RST to close an active TCP.  Use either the -z or
       -Zb options to specify exactly what conditions existed during the  con-
       nection.

 Thu 12/29 03:39:05  M	igmp 12.88.14.10       <-> 128.2.2.10	    CON
       This is an igmp transaction state report, usually seen with MBONE traf-
       fic.   There  was more than one source and destination MAC address pair
       used to support the transaction,	suggesting a possible routing loop.

 Thu 12/29 06:40:05 *	tcp  12.23.14.23.1043  <-> 12.23.14.27.6000 TIM
       This is an X-windows transaction, that has TIMEDOUT.   Packets were re-
       transmitted during the connection.

 Thu 12/29 07:42:09	udp   12.9.1.115.2262	-> 28.12.141.6.139  INT
       This is an initial netbios UDP  transaction  state  report,  indicating
       that this is the	first datagram encountered for this transaction.

 Thu 12/29 06:42:09	icmp  12.9.1.115       <-> 12.68.5.127	    ECO
       This example represents a "ping"	of host	12.9.1.115, and	its response.

 This  next example shows the ra output	of a complete TCP transaction, with the
 preceeding Arp	and DNS	requests, while	reading	 from  a  remote  argus-server.
 The  '*' in the CLO report indicates that at least one	TCP packet was retrans-
 mitted	during the transaction.	 The hostnames in this example are ficticious.

 % ra -S argus-tcp://argus-server and host i.qosient.com
 ra: Trying argus-server port 561
 ra: connected Argus Version 3.0
 Sat 12/03 15:29:38	arp  i.qosient.com     who-has	dsn.qosient.com	 INT
 Sat 12/03 15:29:39	udp  i.qosient.com.1542	 <->	dns.qosient.53	 INT
 Sat 12/03 15:29:39	arp  i.qosient.com     who-has	qosient.com	 INT
 Sat 12/03 15:29:39 *	tcp  i.qosient.com.1543	  ->	qosient.com.smtp CLO

COPYRIGHT
       Copyright (c) 2000-2016 QoSient.	All rights reserved.

AUTHORS
       Carter Bullard (carter@qosient.com).

FILES
       /etc/ra.conf

SEE ALSO
       rarc(5) argus(8)

       Postel, Jon, Internet Protocol, RFC 791,	Network	Information Center, SRI
       International, Menlo Park, Calif., May 1981.

       Postel, Jon, Internet Control Message Protocol, RFC 792,	Network	 Infor-
       mation Center, SRI International, Menlo Park, Calif., May 1981.

       Postel, Jon, Transmission Control Protocol, RFC 793, Network Information
       Center, SRI International, Menlo	Park, Calif., May 1981.

       Postel,	Jon,  User Datagram Protocol, RFC 768, Network Information Cen-
       ter, SRI	International, Menlo Park, Calif., May 1980.

       McCanne,	Steven,	and Van	Jacobson, The BSD Packet Filter: A  New	 Archi-
       tecture	for  User-level	 Capture, Lawrwnce Berkeley Laboratory,	One Cy-
       clotron Road, Berkeley, Calif., 94720, December 1992.

ra 3.0.8		       12 November 2007				 RA(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ra&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help