.\" Copyright (c) 2000-2016 QoSient, LLC .\" All rights reserved. .\" .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 2, or (at your option) .\" any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with this program; if not, write to the Free Software .\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. .\" . .de TQ . br . ns . TP \\$1 .. .TH RA 1 "12 November 2007" "ra 3.0.8" .SH NAME \fBra\fP \- read \fBargus(8)\fP data. .SH SYNOPSIS \fBra [\fBraoptions\fP] [\fB--\fP \fIfilter-expression\fP] .SH DESCRIPTION .IX "ra command" "" "\fLra\fP \(em argus data" .LP .B Ra reads .BR argus(8) data from either \fIstdin\fP, an \fIargus-file\fP, or from a remote data source, which can either be an \fIargus-server\fP, or a netflow data server, filters the records it encounters based on an optional \fIfilter-expression\fP and either prints the contents of the .BR argus(5) records that it encounters to \fBstdout\fP or appends them into an .B argus(5) datafile. .LP .SH OPTIONS .TP 4 4 .B \-A Print aggregate statistics for the input stream on termination. .TP 4 4 .B \-b Dump the compiled transaction-matching code to standard output and stop. This is useful for debugging filter expressions. .TP 4 4 .B \-c Specify a delimiter character for output columns (default is ' '). .TP 4 4 .B \-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. .TP 4 4 .B \-D Print debug information corresponding to \fB\fP to stderr, if program compiled to support debug printing. As the level increases, so does the amount of debug information .B ra(1) will print. Values range from 1-8. .TP 4 4 .B \-d Toggle whether to run this program as a daemon. .TP 4 4 .B \-e 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: .nf "^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. .fi Depending on the regular expression library that the system supports, you will be able to match many types of binary, octal and hex expressions. See regex.3, pcre.3 and the web for examples. .TP 4 4 .B \-E When using a filter expression at the end of the command, this option will cause .B ra(1) to append the records that are rejected by the filter into .B .TP 4 4 .B \-F Use \fB\fP as a source of configuration information. The format of this file is identical to \fBrarc(5)\fP. The data read from \fB\fP overrides any prior configuration information. .TP 4 4 .B \-h Print an explanation of all the arguments. .TP 4 4 .B \-H Abbreviate numeric metrics, to make reading large values easier. Use the \fB-p \fP option to specify the precision right of the decimal. .TP 4 4 .B \-L Specify how \fBra\fP will print header labels for the output. .nf 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 \fIn\fP lines of output. .TP 4 4 .B \-M Provide addition mode operators. These are generally specific to the individual ra* program, or a specific function. Available modes for ra() are: .nf 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. .fi 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. .TP 4 4 .B \-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 \fB-n\fP will suppress port number to service conversion, \fB-nn\fP will suppress translation of protocol numbers to names (no lookups). \fB-nnn\fP will return you to full conversion, translating hostnames, port and protocol names, and \fB-nnnn\fP will return you to the default behavior. Because this indicator can be set in the .rarc file, multiple \fB-n\fP flags progress through the cycle. .TP 4 .B \-N [io], [io], [io] Process the first \fB\fP records, the inclusive range \fB\fP, or process records starting at index number \fB\fP. The optional 1st character indicates whether the specification is applied 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. .TP 4 4 .B \-p Print \fB\fP number of units of precision for floating point values. .TP 4 4 .B \-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. .TP 4 4 .B \-r [- | <[type:]file[::soffset[:eoffset]] ...>] Read \fB\fP data from \fB\fP in the order presented on the commandline. '\fB\-\fP' denotes stdin. Ra supports reading \fBargus\fP type data (default), \fBcisco\fP and \fBft\fP, flow-tools type data. If you want to read a set of files and then, when done, read stdin, use multiple occurences of the \fI-r\fP option. Ra can read \fBgzip(1)\fP, \fBbzip2(1)\fP, \fBxz(1)\fP and \fBcompress(1)\fP 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: .nf -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 .fi .TP 4 4 .B \-R 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. .TP 4 4 .B \-s <[-][[+[#]]field[:len[:format]] ...> Specify the \fBfields\fP to print. \fBra.1\fP 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 \fBra.1\fP 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 optional '-' 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 specific field. Field lengths (len) less than 1, are not permitted and will generate an error. The optional 'format' specification, uses \fBsprintf.1\fP syntax to format the value. The available fields to print are: .PD 0 .RS .TP 12 .B srcid argus source identifier. .TP .B rank Ordinal value of this output flow record i.e. sequence number. .TP .B stime record start time .TP .B ltime record last time. .TP .B trans aggregation record count. .TP .B flgs flow state flags seen in transaction. .TP .B seq argus sequence number. .TP .B dur record total duration. .TP .B runtime total active flow run time. This value is generated through aggregation, and is the sum of the records duration. .TP .B idle time since the last packet activity. This value is useful in real-time processing, and is the current time - last time. .TP .B mean average duration of aggregated records. .TP .B stddev standard deviation of aggregated duration times. .TP .B sum total accumulated durations of aggregated records. .TP .B min minimum duration of aggregated records. .TP .B max maximum duration of aggregated records. .TP .B smac source MAC addr. .TP .B dmac destination MAC addr. .TP .B soui oui portion of the source MAC addr. .TP .B doui oui portion of the destination MAC addr. .TP .B saddr source IP addr. .TP .B daddr destination IP addr. .TP .B proto transaction protocol. .TP .B sport source port number. .TP .B dport destination port number. .TP .B stos source TOS byte value. .TP .B dtos destination TOS byte value. .TP .B sdsb source diff serve byte value. .TP .B ddsb destination diff serve byte value. .TP .B sco source IP address country code. .TP .B dco destination IP address country code. .TP .B sttl src -> dst TTL value. .TP .B dttl dst -> src TTL value. .TP .B shops estimate of number of IP hops from src to this point. .TP .B dhops estimate of number of IP hops from dst to this point. .TP .B sipid source IP identifier. .TP .B dipid destination IP identifier. .TP .B smpls source MPLS identifier. .TP .B dmpls destination MPLS identifier. .TP .B autoid Auto generated identifier (mysql). .TP .B sas Src origin AS .TP .B das Dst origin AS .TP .B ias Intermediate origin AS, AS of ICMP generator .TP .B cause Argus record cause code. Valid values are Start, Status, Stop, Close, Error .TP .B nstroke Number of observed keystrokes. .TP .B snstroke Number of observed keystrokes from initiator (src) to target (dst). .TP .B dnstroke Number of observed keystrokes from target (dst) to initiator (src). .TP .B pkts total transaction packet count. .TP .B spkts src -> dst packet count. .TP .B dpkts dst -> src packet count. .TP .B bytes total transaction bytes. .TP .B sbytes src -> dst transaction bytes. .TP .B dbytes dst -> src transaction bytes. .TP .B appbytes total application bytes. .TP .B sappbytes src -> dst application bytes. .TP .B dappbytes dst -> src application bytes. .TP .B pcr producer consumer ratio. .TP .B load bits per second. .TP .B sload source bits per second. .TP .B dload destination bits per second. .TP .B loss pkts retransmitted or dropped. .TP .B sloss source pkts retransmitted or dropped. .TP .B dloss destination pkts retransmitted or dropped. .TP .B ploss percent pkts retransmitted or dropped. .TP .B psloss percent source pkts retransmitted or dropped. .TP .B pdloss percent destination pkts retransmitted or dropped. .TP .B retrans pkts retransmitted. .TP .B sretrans source pkts retransmitted. .TP .B dretrans destination pkts retransmitted. .TP .B pretrans percent pkts retransmitted. .TP .B psretrans percent source pkts retransmitted. .TP .B pdretrans percent destination pkts retransmitted. .TP .B sgap source bytes missing in the data stream. Available after argus-3.0.4 .TP .B dgap destination bytes missing in the data stream. Available after argus-3.0.4 .TP .B rate pkts per second. .TP .B srate source pkts per second. .TP .B drate destination pkts per second. .TP .B dir direction of transaction .TP .B sintpkt source interpacket arrival time (mSec) .TP .B sintdist source interpacket arrival time distribution .TP .B sintpktact source active interpacket arrival time (mSec) .TP .B sintdistact source active interpacket arrival time (mSec) .TP .B sintpktidl source idle interpacket arrival time (mSec) .TP .B sintdistidl source idle interpacket arrival time (mSec) .TP .B dintpkt destination interpacket arrival time (mSec) .TP .B dintdist destination interpacket arrival time distribution .TP .B dintpktact destination active interpacket arrival time (mSec) .TP .B dintdistact destination active interpacket arrival time distribution (mSec) .TP .B dintpktidl destination idle interpacket arrival time (mSec) .TP .B dintdistidl destination idle interpacket arrival time distribution .TP .B sjit source jitter (mSec). .TP .B sjitact source active jitter (mSec). .TP .B sjitidle source idle jitter (mSec). .TP .B djit destination jitter (mSec). .TP .B djitact destination active jitter (mSec). .TP .B djitidle destination idle jitter (mSec). .TP .B state transaction state .TP .B label Metadata label. .TP .B suser source user data buffer. .TP .B duser destination user data buffer. .TP .B swin source TCP window advertisement. .TP .B dwin destination TCP window advertisement. .TP .B svlan source VLAN identifier. .TP .B dvlan destination VLAN identifier. .TP .B svid source VLAN identifier. .TP .B dvid destination VLAN identifier. .TP .B svpri source VLAN priority. .TP .B dvpri destination VLAN priority. .TP .B srng start time for the filter timerange. .TP .B erng end time for the filter timerange. .TP .B stcpb source TCP base sequence number .TP .B dtcpb destination TCP base sequence number .TP .B tcprtt TCP connection setup round-trip time, the sum of 'synack' and 'ackdat'. .TP .B synack TCP connection setup time, the time between the SYN and the SYN_ACK packets. .TP .B ackdat TCP connection setup time, the time between the SYN_ACK and the ACK packets. .TP .B tcpopt The TCP connection options seen at initiation. The \fItcpopt\fP indicator consists of a fixed length field, that reports presence of any of the TCP options that argus tracks The format is: .nf .sp .5 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 .TP .B inode ICMP intermediate node. .TP .B offset record byte offset in file or stream. .TP .B smeansz Mean of the flow packet size transmitted by the src (initiator). .TP .B dmeansz Mean of the flow packet size transmitted by the dst (target). .TP .B spktsz histogram for the src packet size distribution .TP .B smaxsz maximum packet size for traffic transmitted by the src. .TP .B dpktsz histogram for the dst packet size distribution .TP .B dmaxsz maximum packet size for traffic transmitted by the dst. .TP .B sminsz minimum packet size for traffic transmitted by the src. .TP .B dminsz minimum packet size for traffic transmitted by the dst. .TP .B dminsz minimum packet size for traffic transmitted by the dst. .PD 1 .RE .RS Examles are: .nf -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. .fi .RE .TP 4 4 .B \-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 indicate 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 default; 561. Examles are: .nf -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. .fi .TP 4 4 .B \-t Specify the \fB