1RATOP(1)                    General Commands Manual                   RATOP(1)
2
3
4

NAME

6       ratop - display and update sorted network flow data
7

SYNOPSIS

9       ratop [raoptions] [-- filter-expression]
10

DESCRIPTION

12       Ratop  reads  argus(8)  data  from an argus-file, or from a remote data
13       source, and  periodically  displays  a  sorted  list  of  network  flow
14       records.   When  read  from  a  file, ratop displays the resulting flow
15       caches when the file is completed, updating  its  status  display  line
16       with  each  input.   When  reading from a live argus data stream, ratop
17       will display data, asynchronously in realtime, as it is  received  from
18       the source.
19
20       Flow  data is aggregated as its read, (see racluster.1), resulting in a
21       single line for  each  network  transaction  encountered  in  the  data
22       stream.   The  default sorting key is total packets per flow, but other
23       keys can be used instead.  Flow records that have been  idle  for  more
24       than  the default 60s are removed.  Various output options, such as the
25       specific columns of data to display, the entry idle timeout value,  the
26       screen refresh rate, etc ... are all configurable.
27
28       ratop  uses  ncurses  and readline.3, when available, to provide a vi.1
29       look and feel for displaying, navigating  and  modifying  network  flow
30       data.
31
32       While running ratop a lot of help can be obtained from the on-line help
33       system, using the ":h" command.
34
35

OPTIONS

37       Command line option specifications are processed from  left  to  right.
38       Options  can  be  specified more than once.  If conflicting options are
39       specified, later specifications override earlier ones.  This  makes  it
40       viable to create a shell alias for ratop with preferred defaults speci‐
41       fied, then override those preferred defaults as desired on the  command
42       line.
43
44       ratop,  like  all  ra  based  clients,  supports a number of ra options
45       including filtering of input argus records through a terminating filter
46       expression,  and  the  ability  to specify the output style, format and
47       contents for printing data.  See ra(1) for a complete description of ra
48       options.  ratop(1) specific options are:
49
50       -m aggregation object
51           Supported aggregation objects are:
52              none           use a null flow key.
53              srcid          argus source identifier.
54              smac           source mac(ether) addr.
55              dmac           destination mac(ether) addr.
56              soui           oui portion of the source mac(ether) addr.
57              doui           oui portion of the destination mac(ether) addr.
58              smpls          source mpls label.
59              dmpls          destination label addr.
60              svlan          source vlan label.
61              dvlan          destination vlan addr.
62              saddr/[l|m]    source IP addr/[cidr len | m.a.s.k].
63              daddr/[l|m]    destination IP addr/[cidr len | m.a.s.k].
64              matrix/l       sorted src and dst IP addr/cidr len.
65              proto          transaction protocol.
66              sport          source port number. Implies use of 'proto'.
67              dport          destination port number. Implies use of 'proto'.
68              stos           source TOS byte value.
69              dtos           destination TOS byte value.
70              sttl           src -> dst TTL value.
71              dttl           dst -> src TTL value.
72              stcpb          src -> dst TCP base sequence number.
73              dtcpb          dst -> src TCP base sequence number.
74              inode[/l|m]]   intermediate  node  IP addr/[cidr len | m.a.s.k],
75                             source of ICMP mapped events.
76              sco            source ARIN country code, if present.
77              dco            destination ARIN country code, if present.
78              sas            source node origin AS number, if available.
79              das            destination node origin AS number, if available.
80              ias            intermediate node origin AS number, if available.
81
82       -M modes
83           Supported modes are:
84              correct        Attempt to correct the direction of
85                             flows by also searching the reverse
86                             flow key, if a match isn't found in
87                             the  cache.   This  mode  is  on by
88                             default when using the default full
89                             5-tuple flow key definitions.
90              nocorrect      Turn off flow correction for direc‐
91                             tion.  This mode is used by default
92                             if the flow key has been changed.
93              preserve       Preserve  fields  when  aggregating
94                             matching flow data.
95              nopreserve     Do not preserve fields when  aggre‐
96                             gating matching flow data.
97              norep          Do   not   generate   an  aggregate
98                             statistic for each flow.   This  is
99                             used primarily when the output rep‐
100                             resents a single object.  Primarily
101                             used when merging status records to
102                             generate single flows  that  repre‐
103                             sent single transactions.
104              rmon           Generate  data suitable for produc‐
105                             ing RMON types of metrics.
106              nocurses       Do not use the curses interface  to
107                             present  data.  This option is pri‐
108                             marily used when  debugging  ratop,
109                             to  get around the issues of screen
110                             maniuplation within a debugger like
111                             gdb or lldb.
112

DISPLAY

114       The  first several lines of the ratop display show global
115       state. The top line shows how ratop is running, with  the
116       list  of command line options that are in effect.  In the
117       upper most right corner is the current  time.   The  next
118       line  is  the column title line, that labels each column.
119       The bottom line is the command line, where you  will  see
120       and prepare ':' commands.  The line above the bottom line
121       is the status line, showing the number of flows that  are
122       in the ratop process queue, display queue, the total num‐
123       ber of flows read, the rate of flow records read, and the
124       current status, whether it is Active, reading records, or
125       Idle, when all input is complete.  This line can be  tog‐
126       gled on or off using ^G.
127
128       Flows  caches are displayed one per row and are sorted by
129       total pkts, by default.  ratop sorting can be  configured
130       using  the  rarc variable RA_SORT_ALGORITHMS, or by using
131       the ":P" command.
132
133       ratop supports 3 basic filters.  Like all other ra*  pro‐
134       grams,  ratop  will  send  its command line filter to its
135       remote argus data sources, to limit the load on the wire.
136       This  is  the  "remote"  filter.   Also, ratop supports a
137       "local" filter, that is applied  to  flow  record  input.
138       Normally  this  is used when the remote argus data source
139       doesn't support the syntax of the specific filter.  ratop
140       also  support  a "display" filter, that is used to select
141       which flow records are to be displayed.  This filter does
142       not  have  any  impact  on  the internal flow caches that
143       ratop is tracking, so you can change the "display" filter
144       at any time and see the current state of other flows.
145
146

COLOR

148       ratop  supports  color which is configured using the rarc
149       file.  The RA_COLOR_CONFIG file is a fall through  speci‐
150       fication  of  flow  filters  and field color definitions.
151       For flows that match a filter, specific fields in the row
152       will be painted the configured color.  Because the filter
153       specification supports the " cont " directive,  a  single
154       row can be painted by any number of color definitions.
155
156       When  color  is  enabled  ratop  will attempt to color IP
157       addresses to indicate that local host  address,  and  the
158       local  network.   This  is  very  helpful  in mobile host
159       installations, where you may not know what IP address has
160       been  assigned the localhost.  ratop also supports color‐
161       ing local addresses based on the RA_LOCAL rarc variable.
162
163       See racolor.conf.5.
164
165
166

ARGUS EVENTS

168       Introduced in  argus-3.0.8,  ratop  supports  correlating
169       specific  ARGUS_EVENT  data  with flow data, which can be
170       turned on through the use of the RA_CORRELATE_EVENTS rarc
171       variable.   ratop will process argus-lsof event data gen‐
172       erated by host bourne argi,  and  label  flow  data  with
173       user, pid and process name metadata.  While experimental,
174       it is production level functionality,  and  can  be  used
175       with other ra* programs to enhance flow data with host os
176       process information.  See  argus-3.0.8  documentation  on
177       ARGUS_EVENTS.
178
179
180

EXAMPLES

182       ratop  -r  argus.file  -s  rank  stime dur:14 saddr daddr
183       proto pkts bytes
184
185              Read the file argus.file, and display the  result‐
186              ing  aggregated  and  sorted list of flow records,
187              using the default sorting methods.
188
189
190       ratop -S localhost
191              Run ratop as a live display of realtime flow traf‐
192              fic.
193
194

SEE ALSO

196       rarc(5) racluster(1) racluster.conf(5)
197
198
199
200ratop 3.0.8                    12 November 2007                       RATOP(1)
Impressum