RATOP(1)

💅 RATOP(1) — the manual, but make it cute

okay bestie, welcome to ratop(1), from the General Commands Manual — it's the live, sorted, vibing network flow display and honestly it ate ✨

---

✨ NAME ✨

ratop — display and update sorted network flow data 🦋

---

🌸 SYNOPSIS 🌸

ratop [raoptions] [-- filter-expression]

---

💖 DESCRIPTION 💖

So ratop reads argus(8) data — either from an argus-file or from a remote data source — and then, like clockwork, it periodically shows you a sorted list of network flow records. It's giving main character energy for your packet data, no cap.

• When it's reading from a file, ratop shows you the resulting flow caches once the file is done, and it updates its status display line with every single input. patient queen. 🎀
• When it's reading from a live argus data stream, ratop displays data asynchronously, in realtime, as it arrives from the source. literally live-streaming but for flows 🔥

Flow data gets aggregated as it's read (peep racluster.1), so you end up with a single line for each network transaction encountered in the data stream. iconic. The default sorting key is total packets per flow, but you can swap that key out for others if you want. Flow records that have been idle for more than the default 60s get removed. bye girl 👋

And like, everything is configurable: which specific columns of data show up, the entry idle timeout value, the screen refresh rate, etc... all of it. 💅

ratop uses ncurses and readline.3, when available, to give you an emacs.1 or vi.1 look and feel for displaying, navigating and modifying network flow data. Configure those features using readline's configuration strategy. See man readline. 🧚

And while you're running ratop, there's a LOT of help available from the on-line help system — just use the :h command. iykyk 🫶

---

⭐ OPTIONS ⭐

Command line option specifications are processed from left to right. Options can be specified more than once. If conflicting options get specified, later specifications override earlier ones. This is lowkey the best part, because it means you can make a shell alias for ratop with all your preferred defaults baked in, then override those defaults whenever you feel like it on the command line. slay ✨

ratop, like all ra based clients, supports a bunch of ra options — including filtering input argus records through a terminating filter expression, and the ability to specify the output style, format and contents for printing data. See ra(1) for a complete description of ra options. The ratop(1) specific options are:

• -m aggregation object — pick your aggregation object, bestie. Supported aggregation objects are:
  • none — use a null flow key.
  • srcid — argus source identifier.
  • smac — source mac(ether) addr.
  • dmac — destination mac(ether) addr.
  • soui — oui portion of the source mac(ether) addr.
  • doui — oui portion of the destination mac(ether) addr.
  • smpls — source mpls label.
  • dmpls — destination label addr.
  • svlan — source vlan label.
  • dvlan — destination vlan addr.
  • saddr/[l|m] — source IP addr/[cidr len | m.a.s.k].
  • daddr/[l|m] — destination IP addr/[cidr len | m.a.s.k].
  • matrix/l — sorted src and dst IP addr/cidr len.
  • proto — transaction protocol.
  • sport — source port number. Implies use of 'proto'.
  • dport — destination port number. Implies use of 'proto'.
  • stos — source TOS byte value.
  • dtos — destination TOS byte value.
  • sttl — src -> dst TTL value.
  • dttl — dst -> src TTL value.
  • stcpb — src -> dst TCP base sequence number.
  • dtcpb — dst -> src TCP base sequence number.
  • inode[/l|m]] — intermediate node IP addr/[cidr len | m.a.s.k], source of ICMP mapped events.
  • sco — source ARIN country code, if present.
  • dco — destination ARIN country code, if present.
  • sas — source node origin AS number, if available.
  • das — destination node origin AS number, if available.
  • ias — intermediate node origin AS number, if available.
• -M modes — set the modes, babe. Supported modes are:
  • correct — Attempt to correct the direction of flows by also searching the reverse flow key, if a match isn't found in the cache. This mode is on by default when using the default full 5-tuple flow key definitions.
  • nocorrect — Turn off flow correction for direction. This mode is used by default if the flow key has been changed.
  • preserve — Preserve fields when aggregating matching flow data.
  • nopreserve — Do not preserve fields when aggregating matching flow data.
  • norep — Do not generate an aggregate statistic for each flow. This is used primarily when the output represents a single object. Primarily used when merging status records to generate single flows that represent single transactions.
  • rmon — Generate data suitable for producing RMON types of metrics.
  • nocurses — Do not use the curses interface to present data. This option is primarily used when debugging ratop, to get around the issues of screen manipulation within a debugger like gdb or lldb. 🐛

---

🦋 DISPLAY 🦋

The first several lines of the ratop display show global state. Let's break down the vibe check:

• The top line shows how ratop is running, with the list of command line options that are in effect. In the upper most right corner is the current time. ⏰
• The next line is the column title line, which labels each column.
• The bottom line is the command line, where you'll see and prepare ':' commands.
• The line above the bottom line is the status line, showing the number of flows in the ratop process queue, the display queue, the total number of flows read, the rate of flow records read, and the current status — whether it's Active, reading records, or Idle, when all input is complete. This line can be toggled on or off using ^G. 🎀

Flow caches are displayed one per row, and they're sorted by total pkts by default. ratop sorting can be configured using the rarc variable RA_SORT_ALGORITHMS, or by using the ":P" command. ✨

ratop supports 3 basic filters:

• Like all other ra* programs, ratop will send its command line filter to its remote argus data sources, to limit the load on the wire. This is the "remote" filter. 📡
• ratop also supports a "local" filter, which is applied to flow record input. Normally this gets used when the remote argus data source doesn't support the syntax of the specific filter.
• ratop also supports a "display" filter, used to select which flow records are to be displayed. This filter has no impact on the internal flow caches that ratop is tracking, so you can change the "display" filter at any time and see the current state of other flows. obsessed 💅

---

🌈 COLOR 🌈

ratop supports color, and you configure it using the rarc file. The RA_COLOR_CONFIG file is a fall through specification of flow filters and field color definitions. For flows that match a filter, specific fields in the row will be painted the configured color. And because the filter specification supports the " cont " directive, a single row can be painted by any number of color definitions. no cap 🌈

When color is enabled, ratop will attempt to color IP addresses to indicate the local host address and the local network. This is very helpful in mobile host installations, where you may not know what IP address has been assigned the localhost. ratop also supports coloring local addresses based on the RA_LOCAL rarc variable. 💜

See racolor.conf.5.

---

🔥 ARGUS EVENTS 🔥

Introduced in argus-3.0.8, ratop supports correlating specific ARGUS_EVENT data with flow data, which can be turned on through the use of the RA_CORRELATE_EVENTS rarc variable. ratop will process argus-lsof event data generated by host bourne argi, and label flow data with user, pid and process name metadata. While experimental, it is production level functionality, and can be used with other ra* programs to enhance flow data with host os process information. See the argus-3.0.8 documentation on ARGUS_EVENTS. 🔥

---

🍓 EXAMPLES 🍓

ratop -r argus.file -s rank stime dur:14 saddr daddr proto pkts bytes

Read the file argus.file, and display the resulting aggregated and sorted list of flow records, using the default sorting methods. 💖

ratop -S localhost

Run ratop as a live display of realtime flow traffic. ⚡

---

👑 COPYRIGHT 👑

Copyright (c) 2000-2024 QoSient. All rights reserved.

---

🫶 AUTHORS 🫶

Carter Bullard (carter@qosient.com).

---

💫 SEE ALSO 💫

rarc(5) racluster(1) racluster.conf(5) readline(3)

---

and that's the whole thing bestie, you're so welcome 🎀

this was ratop version 5.0.3, dated 12 July 2023 — mwah, go read your flows 💅✨