RA(1)

📦

version 5.0.2+git20250321.41f65e2 · 3 versions

5.0.2+git20250321.41f65e2 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
3.0.8.3 · nixos 26.05, nixpkgs unstable
3.0.8.2 · debian bookworm, fedora 43, fedora 44, opensuse-leap 16.0, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🦋 bestie, you're reading ra(1) and it's literally iconic 🦋

okay so welcome to the manual page for ra, the general commands manual. if you're here, you're about to read argus(8) data and honestly? slay. let's get into it 💅

✨ NAME ✨

ra — read argus(8) data.

like, that's the whole vibe. it reads argus data. periodt. 💖

🌸 SYNOPSIS 🌸

ra [raoptions] [-- filter-expression]

🎀 DESCRIPTION 🎀

okay so ra reads argus(8) data from literally anywhere: stdin, an argus-file, or a remote data source. and that remote source can be either an argus-server or a netflow data server. no cap. 🫶

it filters the records it encounters based on an optional filter-expression, and then either prints the contents of the argus(5) records it encounters to stdout, or appends them into an argus(5) datafile. that's the whole main character energy right there. ✨

💅 OPTIONS 💅

-A — print aggregate statistics for the input stream on termination. like a little summary era at the end. 📊
-b — dump the compiled transaction-matching code to standard output and stop. this is useful for debugging filter expressions. lowkey a peek behind the curtain. 🔍
-c <char> — specify a delimiter character for output columns. the default is ' ' (a space, bestie). 💬
-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. so maybe don't use it? but we still list it because facts. 🚫
-D <level> — print debug information corresponding to <level> to stderr, if program 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. so like, 1 is chill and 8 is everything. 🐛
-d — toggle whether to run this program as a daemon. like, do you want it to be a background girly? toggle it. 👑
-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 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. regex girlies rise up. 🔥

-E <file> — when using a filter expression at the end of the command, this option will cause ra(1) to append the records that are rejected by the filter into <file>. like a little reject pile, but make it a file. 📁
-F <conffile> — use <conffile> as a source of configuration information. the format of this file is identical to rarc(5). the data read from <conffile> overrides any prior configuration information. so it's giving override energy. 💅
-h — print an explanation of all the arguments. help is always a vibe. 🆘
-H — abbreviate numeric metrics, to make reading large values easier. use the -p <num> option to specify the precision right of the decimal. big numbers but cuter. 🔢
-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.

so like, you can have no labels, one set of labels, or labels every n lines. choose your own adventure. 📝

-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, smacclass, dmacclass)
icmp — ICMP specific data (icmpmap, inode)
encaps — Flow encapsulation type indications
behavior — Behavioral metrics and data
local — Locality 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)
score — scoring data

examples are:

-M dsrs=time,flow,metric
-M dsrs=-suser,-duser

eframe=<int> — set ethernet framing adjust for packet byte count.
json — print output in json format
label="regex" — match flow label with regex(3) regular expression.
lock[=nonblock] — aquire an exclusive record lock on output file(s).
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.
zero — print blank port fields as zero, rather that space.

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. so like, be careful bestie. 💀

-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 numbers to names (no lookups). -nnn will return you to full conversion, 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. it's giving cycle energy. 🔄
-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 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. so like, you can slice and dice. ✂️
-o option — can be used to give options in the format used in the configuration file. this is useful for specifying options for which there is no separate command-line flag. for list of options, and their possible values, see rarc(5). sneaky config vibes. 🤫
-p <digits> — print <digits> number of units of precision for floating point values. precision, but make it a choice. 🎯
-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. quiet girl era. 🤫
-r [- | <[type:]file[::soffset[:eoffset]] ...>] — read <type> data from <files> in the order presented on the commandline. '-' denotes stdin. Ra supports reading argus type data (default), cisco and ft, flow-tools type data. if you want to read a set of files and then, when done, read stdin, use multiple occurences 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. recursive but with boundaries. 🌀

-s <[-][[+[#]]field[:len[:format]] ...> — bestie, this is THE option, the one that decides which fields get printed. 💅

So like, ra.1 gets its field print list either from its rarc configuration files or straight off the command line. If there's no config anywhere, ra.1 falls back to a default printing field list, with default field lengths. But when you pass a space separated list of fields to -s, you get to completely redefine the list from the command line. No cap.

You can also finesse the config instead of nuking it: stick an optional - and/or +[#] in front of the field list and you can add or subtract fields from the configured list. Iconic.

Field lengths are hard constraints, okay? Meaning field output that blows past the field length gets truncated, and a * gets shoved in as the last character. When you see that little star, that's your sign to add more to the length spec for that specific field. 🫶

Field lengths (len) less than 1 are not permitted and will generate an error. Don't do it.

The optional format spec uses sprintf.1 syntax to format the value. Obsessed.

The available fields to print are:

srcid — Argus source identifier. In V3 records this is a 32-bit integer, IP address, or 4byte ascii string. In V5 records, the srcid is composed of the 128-bit sid or source id, and an optional 4-char inf or interface identifier, separated by a /. You can print out the sid and inf components separately.
sid — Argus source identifier. Introduced in V5 records. The sid is a maximu
inf — Optional 4-char string interface identifier for this flow data.
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 duration.
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.
smacclass — class of the source MAC addr. (UAA, LAA, ELI, SAI, AAI, RES, LM)
dmacclass — class of the destination MAC addr. (UAA, LAA, ELI, SAI, AAI, RES, LM)
senc — source encapsulations processed.
denc — destination encapsulations processed.
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.
sgreaddr — source GRE tunnel address.
dgreaddr — destination GRE tunnel address.
greproto — Next layer GRE tunnel protocol.
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, Status, 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 initiator (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 after 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 distribution
sintpktidl — source idle interpacket arrival time (mSec)
sintdistidl — source idle interpacket arrival time distribution
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 distribution (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
smss — source TCP maximum segment size
dmss — destination TCP maximum segment size
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.

Examles are:

-s saddr      print only the source address.
-s -bytes     removes the bytes field from list.
-s +2srcid    adds the source identifier after 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 sgreaddr   print the src address of the GRE tunnel in the flow.

-S <[URI://][user[:pass]@]host[:portnum]> — bestie, this is how you pull flow data from somewhere else. You're reading flow data over a bunch of different data formats and transport strategies, and the URI format is what tells ra what kind of flow data record you want (argus-tcp, argus-udp, cisco, jflow, sflow) plus the source, given as a name or an address. You can also hand over an optional user and password for protected access. And that optional :portnum? That's for when you want a port number that isn't the default, which is 561. 💅

Examples 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> — the time range you want to match your argus(5) records against. This one is so flexible — it does explicit ranges, relative ranges, and it even supports wildcarding in the time fields. Obsessed. ✨

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.

So the way time comparison actually works is with basic intersection operations. A record intersects a specified time range if there's any intersection at all between the time range of the record and the comparison time range — and ngl, that's the default behavior. A record includes the comparison time range when the intersection of the two ranges equals the comparison 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, and there are no 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 a remote server for <secs> of time. That's it, that's the whole vibe. ⏳
-u — print your time values using Unix time format (seconds from the Epoch). raw numbers only, no notes. 😌
-w <file> [filter-expression] — append matching data to <file>, in argus file format. And listen: an output-file of '-' makes ra write the argus(5) records to stdout, which is what lets you "chain" ra* style commands together. The optional filter-expression lets you select specific output. 💫
-X — resets all options back to their default values and overrides the rarc file contents. Use it as the first option. (Yes, first. Don't fight it.)
-z — modify the status field so it represents 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)
- 'R' — TCP Reset
-Z <s|d|b> — modify the status field so it represents actual TCP flag values. < 's'rc | 'd'st | 'b'oth >. The characters that can show up 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
-3 — generate Argus V3 (open source) formatted data when you're writing flow records to a file. ✨

🎀 RETURN VALUES 🎀

ra exits with one of these values, and bestie, you will be checking them:

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 🦋

okay so if arguments remain after option processing, the whole collection gets interpreted as a single filter expression. To mark the end of arguments, you need a '--' (double dash) before the filter expression goes onto the command line. Historically a '-' (single dash) was used to separate the filter expression from the command line options, but newer versions of getopt.1 now require the '--' (double dash). so, y'know. adapt. 💅

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

The syntax is very similar to the expression syntax for tcpdump(1), since the tcpdump compiler was a starting point for the argus(5) filter expression compiler. BUT — and this is important, no cap — the semantics for tcpdump(1)'s packet filter expressions are different when you apply them to transaction record filtering, 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 get transmitted to the ra application. If you do not want to send a filter to the remote argus, prepend the filter with the keyword "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. Possible 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 defined proto 'ip' reduces to the filter 'ipv4 or ipv6'.

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

In addition to all of 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 domain.

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 number.
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: mpls, eth, 802q, llc, pppoe, vxlan, isl, gre, geneve, ah, ipnip, ipnip6, chdlc
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 when the ethernet destination address is ehost. That ehost can be a name straight out of /etc/ethers, or just a number (peep ethers(3N) for the numeric format, bestie).
ether src ehost — true when the ethernet source address is ehost.
ether host ehost — true when either the ethernet source or the ethernet destination address is ehost. Covering both bases, love that for us.
gateway host — true when the transaction used host as a gateway. Like, the ethernet source or destination address was host, but neither the IP source nor the IP destination was host. 👀 host has to be a name, and it has to be findable in both /etc/hosts and /etc/ethers. An equivalent expression is

ether host ehost and not host host

which is flexible enough to work with either names or numbers for host / ehost.

dst net cidr — true when the IP destination address in the Argus record matches the cidr address.
src net cidr — true when the IP source address in the Argus record matches the cidr address.
net cidr — true when either the IP source or the IP destination address in the Argus record matches the cidr address.
dst port port — true when the network transaction is IP based, using either the TCP or UDP transport protocols, and has a destination port value of port. That port can be a number or a name as configured in the /etc/services file (see tcp(4P) and udp(4P)). If you use a name, both the protocol number and the port number get checked. If you use a number or an ambiguous name, the port number is checked for both UDP and TCP protocols — so like, 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. You can also specify port ranges with numeric values, such as port 53-215. ✨
src port port — true when the network transaction has a source port value of port.
port port — true when either the source or the destination port in the Argus record is port. And here's the cute part: any of the port expressions above can be prepended with the keywords tcp or udp, like

tcp src port port

which matches only tcp connections. slay.

ip proto protocol — true when 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 when the network transaction involved an ip multicast address. And if you specify ether multicast, you can select argus records that involve an ethernet multicast address. 🦋
broadcast — true when the network transaction involved an ip broadcast address. By specifying ether broadcast, you can select argus records that involve an ethernet broadcast address.
ether proto protocol — true when the Argus record is of ether type protocol. protocol can be a number or a name like ip, arp, or rarp.
[src | dst] loc [gt | gte | lt | lte | eq] number — true when the Locality value for addresses in the Argus record compares to number.
[src | dst] ttl [gt | gte | lt | lte | eq] number — true when the TTL in the Argus record compares to number.
[src | dst] tos [gt | gte | lt | lte | eq] number — true when the TOS in the Argus record (default) compares to number.
[src | dst] vid [gt | gte | lt | lte | eq] number — true when the VLAN id in the Argus record (default) compares to number.
[src | dst] vpri [gt | gte | lt | lte | eq] number — true when the VLAN priority in the Argus record (default) compares to number.
[src | dst] mid [gt | gte | lt | lte | eq] number — true when the MPLS Label in the Argus record (default) compares to number.
[src | dst] pkts [gt | gte | lt | lte | eq] number — true when the packet count in the Argus record (default) compares to number.
[src | dst] bytes [gt | gte | lt | lte | eq] number — true when the byte count in the Argus record (default) compares to number.
[src | dst] appbytes [gt | gte | lt | lte | eq] number — true when the application byte count in the Argus record (default) compares to number.
[src | dst] rate [gt | gte | lt | lte | eq] number — true when the rate in the Argus record (default) compares to number.
[src | dst] load [gt | gte | lt | lte | eq] number — true when the load in the Argus record (default) compares to number.

okay so now we get into the vibes of the primitives 💜 Ra filter expressions support primitives that are specific to flow states, and you can use them to select flow records that were in those states at the time they were generated:

normal, wait, timeout, est or con

There are also primitives that select flows which 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 too:

syn, synack, ecn, fin, finack, reset, reuse, retrans, outoforder and winshut

Primitives specific to TCP options, yes we have those:

tcpopt, mss, wscale, selackok, selack, tcpecho, tcpechoreply, tcptimestamp, tcpcc, tcpccnew, tcpccecho, secn and decn

Primitives specific to TCP metrics:

maxseg

And primitives specific to ICMP flows are supported:

echo, redirect, timexed and unreach

...where unreach can be further specified using the keywords unrnet, unrhost, unrproto, unrport, unrfrag, unrsrcfail, unrnetunk, unrhostunk, unriso, unrnetpro, unrhostpro, unrnettos, unrhosttos, unrfilter, unrhostpre, and unrprecut, that each correspond to the unreachable icmp codes. 💅

For some primitives, a direction qualifier is appropriate. These are:

frag, reset, retrans, outoforder and winshut

🌈 Combining primitives 🌈

Primitives may be combined using:

A parenthesized group of primitives and operators (parentheses are special to the Shell and must be escaped — do not forget this bestie, the shell will eat them otherwise 😭).
Negation (! or not).
Concatenation (and).
Alternation (or).

Negation has the highest precedence. Alternation and concatenation have equal precedence and associate left to right. And heads up: explicit and tokens, not juxtaposition, are now required for concatenation. no cap.

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 )

⚠️ Those three are genuinely different filters, okay? Read them twice. The parentheses change everything.

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's easier to pass it as a single, quoted argument. Multiple arguments get 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 variables specified in the file are set.

Ra then parses its command line options and sets 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 supercede all other values. 👑

🎉 EXAMPLES 🎉

the moment we've all been waiting for — actual commands, actual slay 💖

To report all TCP transactions from and to host narly.wave.com, reading 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

Write ra output in standard formats other than space separated columns:

ra -r argus.file -M json
ra -r argus.file -M xml

✨ OUTPUT FORMAT ✨

okay bestie, here's the tea on what ra spits out by default. 💖 Is this the objectively best data set you could ever generate? Not necessarily, but it's a totally valid starting point for playing with flow data in general — and ngl, it looks chef's kiss on an 80 column terminal. 💅

The standard 5-tuple flow format is:

time flgs proto saddr.sport dir daddr.dport pkts bytes state

time

The format of the time field is set by your .rarc file, using syntax that the strftime(3V) routine supports. Default is '%T', periodt.

Argus transactional data has both starting and ending transaction times, with precision down to the nanosecond. But ra just prints the 'stime' field by default — that's the record's starting time. 🕐

flgs

The flgs indicator is a fixed length field. It reports all kinds of flow record + protocol identifiers, states, and attributes. The format is:

T — Time Corrected/Adjusted
N — Netflow Originated Data
* — Multiple sub-IP encapsulations
e — Ethernet encapsulated flow
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
x — VXLAN encapsulation
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
R — TCP port reuse seen
* — 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

yes the same letters show up more than once with different meanings bestie, that's just how it is, no notes 💀

proto

The proto field tells you the upper protocol used in the transaction. It holds the first 4 characters of the official name of the protocol, as defined in RFC-1700 and configured via the /etc/protocols file. Argus also tries to sniff out the Realtime Transport Protocol (rtp) when it's in use — when it catches rtp, it says so right in this field with the string 'rtp'. 🌈

And if you pass -n twice (-nn), you get the actual protocol number displayed instead. iykyk.

shost

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

The 'src' is generally the entity that first transmits a packet that's part of a flow. But lowkey, the assignment of 'src' and 'dst' semantics gets a little complicated by the notion of loss, or half-duplex monitoring — especially when connection-oriented protocols like TCP are being reported. In that case, the 'src' is the entity that initiated the flow. 💅

dir

The dir field holds the direction of the transaction, as best as anyone can figure out from the datum, and it's used to show which hosts are transmitting. For TCP, dir indicates the actual source of the TCP connection, and the center character shows the state of the transaction:

- — transaction was NORMAL
| — transaction was RESET
o — transaction TIMED OUT.
? — direction of transaction is unknown.

daddr

The daddr field conveys the recipient of the data in the flow. Like shost, it's protocol dependent — for IP protocols it holds the dst IP address/name, and optionally the DSAP. 🎀

metrics

metrics are the general sets of fields that reflect the activity 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 that specific transaction. The fields are paired up with the previous host fields, and they represent the packets transmitted by the respective host. ✨

state

The state field shows the principle state for the transaction report, and it's protocol dependent. For all protocols except ICMP, this field reports the basic state of a transaction. 👑

REQ|INT (requested|initial)

This says it's the initial state report for a transaction, and it only shows up when the argus-server is in DETAIL mode. For TCP connections it's REQ, meaning a connection is being requested. For connectionless protocols like UDP, it's INT.

ACC (accepted)

This says a request/response condition happened, and a transaction has been detected between two hosts. For TCP, it means a connection request got answered and the connection will be accepted — only seen when the argus-server is in DETAIL mode. For connectionless protocols, this state means there was a single packet exchange between two hosts, which could count as a request/response transaction. 💖

EST|CON (established|connected)

This record type says the reported transaction is active, and has been established or is continuing. Read it as a state report of a currently active transaction. For TCP, EST is only seen in DETAIL mode, and it means the three way handshake for a connection has been completed. 🦋

CLO (closed)

TCP specific — this record type means the TCP connection has closed normally. 🎀

TIM (timeout)

No activity was seen relating to this transaction during the argus server's timeout period for this protocol. This state is only seen 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
UR NPRO — 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 🌸

Okay bestie, these are the vibes you'll actually see on your screen — real ra output, showing off all the different flavors argus data comes in. 💅 This output was made with the -n option to suppress number translation, so no hostnames, just numbers, periodt.

 Thu 12/29 06:40:32   S tcp  132.3.31.15.6439   -> 12.23.14.77.23   CLO

This is a totally normal tcp transaction heading 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 got RESET. 😭 A lot of the time that means the transaction was rejected, but — plot twist — some os's will use RST to close an active TCP. So use either the -z or -Zb options to specify exactly what conditions existed during the connection. iykyk.

 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 spotted with MBONE traffic. 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 retransmitted during the connection. it's giving "we tried, bestie." 💀

 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 — meaning 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 one represents a "ping" of host 12.9.1.115, and its response. 🏓

This next example shows the ra output of a complete TCP transaction, along with the preceding Arp and DNS requests, while reading from a remote argus-server. The '*' in the CLO report means at least one TCP packet was retransmitted during the transaction. The hostnames in this example are ficticious. (yes, exactly like that, don't come for me 🫶)

 % 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 👑

🫶 AUTHORS 🫶

Carter Bullard (carter@qosient.com). the blueprint, fr fr.

🎀 FILES 🎀

/etc/ra.conf

✨ SEE ALSO ✨

rarc(5) argus(8)

And now for the reading list, because we're ✨well-read✨ in this house:

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 Information 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 Center, SRI International, Menlo Park, Calif., May 1980.
McCanne, Steven, and Van Jacobson, The BSD Packet Filter: A New Architecture for User-level Capture, Lawrwnce Berkeley Laboratory, One Cyclotron Road, Berkeley, Calif., 94720, December 1992.

and that's the whole page, bestie!! 🌈 this manual is ra 5.0.3.0, dated 17 October 2023, and it lives at the very bottom of the page as RA(1) — that's your source, your version, and your date all in one lil footer. go forth and ra responsibly, mwah 💅💖✨

📦 where this page comes from

debian trixie: argus-client 1:5.0.2+git20250321.41f65e2-2 · GPL-2.0-or-later
ubuntu questing: argus-client 1:5.0.2+git20250321.41f65e2-2ubuntu1
ubuntu resolute: argus-client 1:5.0.2+git20250321.41f65e2-2ubuntu2 · GPL-2.0-or-later
ubuntu stonking: argus-client 1:5.0.2+git20250321.41f65e2-2ubuntu2 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms