Debian Codegraph @

man/flent.1

raw
1 .\" Man page generated from reStructuredText
2 .\" by the Docutils 0.22.4 manpage writer.
3 .
4 .
5 .nr rst2man-indent-level 0
6 .
7 .de1 rstReportMargin
8 \\$1 \\n[an-margin]
9 level \\n[rst2man-indent-level]
10 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
11 -
12 \\n[rst2man-indent0]
13 \\n[rst2man-indent1]
14 \\n[rst2man-indent2]
15 ..
16 .de1 INDENT
17 .\" .rstReportMargin pre:
18 . RS \\$1
19 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
20 . nr rst2man-indent-level +1
21 .\" .rstReportMargin post:
22 ..
23 .de UNINDENT
24 . RE
25 .\" indent \\n[an-margin]
26 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
27 .nr rst2man-indent-level -1
28 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
30 ..
31 .TH "FLENT" "1" "June 16, 2026" "2.3.0" "Flent: The FLExible Network Tester"
32 .SH NAME
33 flent \- Flent: The FLExible Network Tester
34 .SH INTRODUCTION
35 .sp
36 Flent is a wrapper around \fInetperf\fP and similar tools to run predefined
37 tests and aggregate and plot the results. It defines several tests that
38 can be run against one or more hosts, primarily targeted at testing for
39 the presence of bufferbloat under various conditions.
40 .sp
41 The aggregated data is saved in (gzipped) JSON format for later
42 processing and/or import into other tools. The JSON format is documented
43 below.
44 .sp
45 Apart from the JSON format, the data can be output as csv values, emacs
46 org mode tables or plots. Each test can specify several different plots,
47 including time\-series plots of the values against each other, as well as
48 CDF plots of (e.g.) ping times.
49 .sp
50 Plots can be output to the formats supported by matplotlib by specifying
51 the output filename with \fB\-o\fP \fIoutput.{png,ps,pdf,svg}\fP\&. If no output
52 file is specified, the plot is displayed using matplotlib’s interactive
53 plot browser, which also allows saving of the output (in .png format).
54 .SS Requirements
55 .sp
56 Flent runs on Python, versions 2.7+ and 3.3+. Plotting requires a functional
57 \fBmatplotlib\fP installation (but everything else can run without
58 \fBmatplotlib\fP). For the interactive plot viewer, a graphical display (and
59 suitably configured \fBmatplotlib\fP) is required.
60 .sp
61 Most tests employ the \fBnetperf\fP benchmarking tool to run the tests.
62 Version 2.6 or higher is required, and netperf must be compiled with the
63 \fB\-\-enable\-demo\fP option passed to \fB\&./configure\fP\&. Some tests use
64 iperf in addition to, or instead of netperf. Both tools must be available in the
65 \fBPATH\fP\&.
66 .sp
67 For ICMP ping measurements, the version of ping employed must support output
68 timestamping (the \-D parameter to GNU ping). This is not supported by the BSD
69 and OSX versions of ping. As an alternative to the regular ping command, the
70 \fBfping\fP utility (see \%<http://\:fping\:.org>) can be employed. In that case
71 fping must be version 3.5 or greater. Flent will attempt to detect the presence
72 of fping in the \fBPATH\fP and check for support for the \-D parameter. If
73 this check is successful, \fBfping\fP will be employed for ping data,
74 otherwise the system ping will be used.
75 .sp
76 The \fBirtt\fP tool is highly recommended for UDP measurements. See
77 \%<https://\:github\:.com/\:peteheist/\:irtt>\&. Flent will automatically detect if irtt is
78 available in the \fBPATH\fP and use it if it is detected. Note that the
79 server component of irtt needs to be running on the target host(s) as well.
80 .SH RUNNING FLENT
81 .sp
82 When run, flent must be supplied either (a) a test name and one or more host
83 names to connect to, or (b) one or more input files containing data from
84 previous runs to post\-process.
85 .sp
86 Test names, hostnames and input file names can all be specified as unqualified
87 arguments, and flent will do its best to guess which is which. For each
88 argument, if it is an existing file, it is assumed to be an input file, if it is
89 the name of an existing test configuration it’s assumed to be a test name, and
90 if neither of those are true, it is assumed to be a host name. The \fB\-i\fP
91 and \fB\-H\fP switches can be used to explicitly specify the interpretation
92 of an argument.
93 .SS Invocation
94 .sp
95 \fBflent\fP [\fIoptions\fP] \fI<host|test|input file\fP ...\fI>\fP
96 .SS General options
97 .INDENT 0.0
98 .TP
99 .B \-o OUTPUT, \-\-output=OUTPUT
100 File to write processed output to (default standard out).
101 .UNINDENT
102 .INDENT 0.0
103 .TP
104 .B \-D DATA_DIR, \-\-data\-dir=DATA_DIR
105 Directory to store data files in. Defaults to the current directory.
106 .UNINDENT
107 .INDENT 0.0
108 .TP
109 .B \-i INPUT, \-\-input=INPUT
110 File to read input from (instead of running tests). Input files can also be
111 specified as unqualified arguments without using the \fB\-i\fP switch.
112 .UNINDENT
113 .INDENT 0.0
114 .TP
115 .B \-f FORMAT, \-\-format=FORMAT
116 Select output format (plot, csv, org_table, stats). Default is no processed
117 output (just writes the JSON data file).
118 .UNINDENT
119 .INDENT 0.0
120 .TP
121 .B \-p PLOT, \-\-plot=PLOT
122 Select which plot to output for the given test (implies \fB\-f\fP plot). Use the
123 \fB\-\-list\-plots\fP option to see available plots.
124 .UNINDENT
125 .INDENT 0.0
126 .TP
127 .B \-t TITLE, \-\-title\-extra=TITLE
128 Text to add to plot title and data file name.
129 .UNINDENT
130 .INDENT 0.0
131 .TP
132 .B \-n NOTE, \-\-note=NOTE
133 Add arbitrary text as a note to be stored in the JSON data file (under the
134 \fINOTE\fP key in the metadata object).
135 .UNINDENT
136 .INDENT 0.0
137 .TP
138 .B \-r RCFILE, \-\-rcfile=RCFILE
139 Load configuration data from \fIRCFILE\fP (default \fI~/.flentrc\fP). See section
140 below for information on the rc file format.
141 .UNINDENT
142 .INDENT 0.0
143 .TP
144 .B \-x, \-\-extended\-metadata
145 Collect extended metadata and store it with the data file. May include
146 details of your machine you don’t want to distribute; see the section on the
147 data format below.
148 .UNINDENT
149 .INDENT 0.0
150 .TP
151 .B \-\-remote\-metadata=HOSTNAME
152 Collect extended metadata from a remote host. \fIHOSTNAME\fP is passed verbatim
153 to ssh, so can include hosts specified in ~/.ssh/config. Note that gathering
154 the data can take some time, since it involves executing several remote
155 commands. This option can be specified multiple times and implies
156 \fB\-\-extended\-metadata\fP\&.
157 .UNINDENT
158 .INDENT 0.0
159 .TP
160 .B \-\-gui
161 Run the flent GUI. All other options are used as defaults in the GUI, but can
162 be changed once it is running. The GUI can also be started by running the
163 \fBflent\-gui\fP binary. For more information on the GUI, see the
164 The Flent GUI section.
165 .UNINDENT
166 .INDENT 0.0
167 .TP
168 .B \-\-new\-gui\-instance
169 Start a new GUI instance. Otherwise, flent will try to connect to an already
170 running GUI instance and have that load any new data files specified as
171 arguments. Implies \fB\-\-gui\fP when passed on the command line, but not when
172 set in the rc file. Note that when multiple GUI instances are running, there
173 is no guarantee as to which instance will get a subsequent open request (if
174 run again without \fB\-\-new\-gui\-instance\fP).
175 .UNINDENT
176 .INDENT 0.0
177 .TP
178 .B \-\-gui\-no\-defer
179 Normally, the GUI defers redrawing plots until they are needed to avoid
180 redrawing all open plots every time an option changes. This switch turns off
181 that optimisation in favour of always redrawing everything straight away.
182 This is useful when loading a bunch of plots from the command line and then
183 wanting to flip through them without drawing delay.
184 .UNINDENT
185 .INDENT 0.0
186 .TP
187 .B \-b BATCH_NAME, \-\-batch\-name=BATCH_NAME
188 Run test batch BATCH_NAME (must be specified in a batch file loaded by the
189 \fB\-\-batch\-file\fP option). Can be supplied multiple times.
190 .UNINDENT
191 .INDENT 0.0
192 .TP
193 .B \-B BATCH_FILE, \-\-batch\-file=BATCH_FILE
194 Load batch file BATCH_FILE. Can be specified multiple times, in which case
195 the files will be combined (with identically\-named sections being overridden
196 by later files). See appropriate section below for an explanation of the
197 batch file format.
198 .UNINDENT
199 .INDENT 0.0
200 .TP
201 .B \-\-batch\-override=key=value
202 Override parameter ’key’ in the batch config and set it to ’value’. The key
203 name will be case folded to lower case. Can be specified multiple times.
204 .UNINDENT
205 .INDENT 0.0
206 .TP
207 .B \-\-batch\-dry\-run
208 Dry batch run. Prints what would be done, but doesn’t actually run any tests.
209 .UNINDENT
210 .INDENT 0.0
211 .TP
212 .B \-\-batch\-verbose
213 Be verbose during batch run: Print all commands executed.
214 .UNINDENT
215 .INDENT 0.0
216 .TP
217 .B \-\-batch\-no\-shuffle
218 Do not randomise the order of test runs within each batch.
219 .UNINDENT
220 .INDENT 0.0
221 .TP
222 .B \-\-batch\-repetitions=REPETITIONS
223 Shorthand for \fB\-\-batch\-override\fP \fB\(aqrepetitions=REPETITIONS’\fP\&.
224 .UNINDENT
225 .INDENT 0.0
226 .TP
227 .B \-\-batch\-title=TITLE
228 Shorthand for \fB\-\-batch\-override\fP \fB\(aqbatch_title=TITLE’\fP\&.
229 .UNINDENT
230 .INDENT 0.0
231 .TP
232 .B \-\-batch\-resume=DIR
233 Try to resume a previously interrupted batch run. The argument is the
234 top\-level output directory from the previous run.
235 .sp
236 This will attempt to find a data file in the resume directory and load the
237 BATCH_TIME from the previous run from that and continue. The assumption is
238 that the output directory and filenames are generated from the batch time, so
239 that they will match with the previous run when the same time is used. Then,
240 tests for which data files already exist will be skipped on this run. If the
241 rest of the batch invocation is different from the one being resumed, results
242 may not be what you want.
243 .sp
244 There\(aqs a check to ensure that the generated output path is a subdirectory of
245 the resume directory, and the whole run will be aborted if it isn\(aqt.
246 .UNINDENT
247 .SS Test configuration options
248 .sp
249 These options affect the behaviour of the test being run and have no effect when
250 parsing input files.
251 .INDENT 0.0
252 .TP
253 .B \-H HOST, \-\-host=HOST
254 Host to connect to for tests. For tests that support it, multiple hosts can
255 be specified by supplying this option multiple times. Hosts can also be
256 specified as unqualified arguments; this parameter guarantees that the
257 argument be interpreted as a host name (rather than being subject to
258 auto\-detection between input files, hostnames and test names).
259 .UNINDENT
260 .INDENT 0.0
261 .TP
262 .B \-\-local\-bind=IP
263 Local hostname or IP address to bind to (for test tools that support this).
264 Can be specified multiple times for tests that connect to more than one host;
265 if it is, it must be specified as many times as there are hosts.
266 .UNINDENT
267 .INDENT 0.0
268 .TP
269 .B \-\-remote\-host=idx=HOSTNAME
270 A remote hostname to connect to when starting a test. The idx is the runner
271 index, which is assigned sequentially to each \fIrunner\fP (and so it is \fInot\fP
272 the same as the sequence of hostnames). Look for the \(aqIDX\(aq key in SERIES_META
273 for a test get the idx used here, but note that the idx assignment depends on
274 the exact arguments to the test.
275 .sp
276 This works by simply prepending \(aqssh HOSTNAME\(aq to the runner command, so it
277 relies on the same binaries being in the same places on both machines, and
278 won\(aqt work for all runners.
279 .sp
280 This option can be specified multiple times to have multiple runners run on
281 remote hosts.
282 .UNINDENT
283 .INDENT 0.0
284 .TP
285 .B \-l LENGTH, \-\-length=LENGTH
286 Base test length (some tests may add some time to this).
287 .UNINDENT
288 .INDENT 0.0
289 .TP
290 .B \-s STEP_SIZE, \-\-step\-size=STEP_SIZE
291 Measurement data point step size.
292 .UNINDENT
293 .INDENT 0.0
294 .TP
295 .B \-d DELAY, \-\-delay=DELAY
296 Number of seconds to delay parts of test (such as bandwidth loaders).
297 .UNINDENT
298 .INDENT 0.0
299 .TP
300 .B \-4, \-\-ipv4
301 Use IPv4 for tests (some tests may ignore this).
302 .UNINDENT
303 .INDENT 0.0
304 .TP
305 .B \-6, \-\-ipv6
306 Use IPv6 for tests (some tests may ignore this).
307 .UNINDENT
308 .INDENT 0.0
309 .TP
310 .B \-\-socket\-timeout=SOCKET_TIMEOUT
311 Socket timeout (in seconds) used for UDP delay measurement, to prevent stalls
312 on packet loss. Only enabled if the installed netperf version is detected to
313 support this (requires SVN version of netperf).
314 .sp
315 For the default value, see the output of flent \fB\-h\fP\&. The value of
316 this parameter is an implicit upper bound on how long a round\-trip time that
317 can be measured. As such you may need to adjust it if you are experiencing
318 latency above the default value. Set to 0 to disable.
319 .UNINDENT
320 .INDENT 0.0
321 .TP
322 .B \-\-send\-size=SEND_SIZE
323 Send size (in bytes) used for TCP tests. Netperf uses the socket buffer size
324 by default, which if too large can cause spikes in the throughput results.
325 Lowering this value will increase CPU usage but also improves the fidelity
326 of the throughput results without having to decrease the socket buffer size.
327 .sp
328 Can be specified multiple times, with each value corresponding to a stream
329 of a test. If only specified once, the same value will be applied to all
330 flows.
331 .UNINDENT
332 .INDENT 0.0
333 .TP
334 .B \-\-test\-parameter=key=value
335 Arbitrary test parameter in key=value format. Key will be case folded to
336 lower case. The values are stored with the results metadata, and so can be
337 used for storing arbitrary information relevant for a particular test run.
338 .sp
339 In addition to serving as simple metadata, the test parameters can also
340 affect the behaviour of some test configurations. See the Supplied Tests
341 section for information on these.
342 .sp
343 This option can be specified multiple times to set multiple test parameters.
344 .UNINDENT
345 .INDENT 0.0
346 .TP
347 .B \-\-swap\-up\-down
348 Switch upstream and downstream directions for data transfer. This means that
349 ’upload’ will become ’download’ and vice versa. Works by exchanging netperf
350 \fBTCP_MAERTS\fP and \fBTCP_STREAM\fP parameters, so only works for tests that employ
351 these as their data transfer, and only for the TCP streams.
352 .UNINDENT
353 .INDENT 0.0
354 .TP
355 .B \-\-socket\-stats
356 Parse socket stats during test. This will capture and parse socket
357 statistics for all TCP upload flows during a test, adding TCP cwnd and RTT
358 values to the test data. Requires the \(aqss\(aq utility to be present on the
359 system, and can fail if there are too many simultaneous upload flows; which
360 is why this option is not enabled by default.
361 .UNINDENT
362 .INDENT 0.0
363 .TP
364 .B \-\-marking\-name
365 Define a new symbolic name that can be used when specifying flow markings
366 using the \(aqmarkings\(aq test parameter. This can be used to make it easier to
367 specify custom diffserv markings on flows by using symbolic names for each
368 marking value instead of the hex codes. Values specified here will be used
369 in addition to the common values (listed below), and cannot override the
370 built\-in names. Names will be case\-folded when matching.
371 .sp
372 The list of symbolic markings natively supported, along with their hex
373 expansions, are:
374 .INDENT 7.0
375 .INDENT 3.5
376 .sp
377 .EX
378 AF11: 0x28 CS0: 0x00
379 AF12: 0x30 CS1: 0x20
380 AF13: 0x38 CS2: 0x40
381 AF21: 0x48 CS3: 0x60
382 AF22: 0x50 CS4: 0x80
383 AF23: 0x58 CS5: 0xa0
384 AF31: 0x68 CS6: 0xc0
385 AF32: 0x70 CS7: 0xe0
386 AF33: 0x78 EF: 0xb8
387 AF41: 0x88
388 AF42: 0x90
389 AF43: 0x98
390 .EE
391 .UNINDENT
392 .UNINDENT
393 .sp
394 Note that the hexadecimal values denote the value of the full ToS byte
395 (including the two ECN bits), so they need to be right\-shifted by two bits
396 to get the corresponding diffserv code points.
397 .UNINDENT
398 .SS Plot configuration options
399 .sp
400 These options are used to configure the appearance of plot output and only make
401 sense combined with \fB\-f\fP \fIplot\fP\&.
402 .INDENT 0.0
403 .TP
404 .B \-\-label\-x=LABEL
405 .UNINDENT
406 .INDENT 0.0
407 .TP
408 .B \-\-label\-y=LABEL
409 Override the figure axis labels. Can be specified twice, corresponding to
410 figures with multiple axes.
411 .UNINDENT
412 .INDENT 0.0
413 .TP
414 .B \-I, \-\-invert\-latency\-y
415 Invert latency data series axis (typically the Y\-axis), making plots show
416 ’better\(aq values upwards.
417 .UNINDENT
418 .INDENT 0.0
419 .TP
420 .B \-z, \-\-zero\-y
421 Always start Y axis of plot at zero, instead of autoscaling the axis.
422 Autoscaling is still enabled for the upper bound. This also disables log
423 scale if enabled.
424 .UNINDENT
425 .INDENT 0.0
426 .TP
427 .B \-\-log\-scale={log2,log10}
428 Use the specified logarithmic scale on plots.
429 .UNINDENT
430 .INDENT 0.0
431 .TP
432 .B \-\-norm\-factor=FACTOR
433 Data normalisation factor. Divide all data points by this value. Can be
434 specified multiple times, in which case each value corresponds to a data
435 series.
436 .UNINDENT
437 .INDENT 0.0
438 .TP
439 .B \-\-bounds\-x=BOUNDS
440 .UNINDENT
441 .INDENT 0.0
442 .TP
443 .B \-\-bounds\-y=BOUNDS
444 Specify bounds of the plot axes. If specifying one number, that will become
445 the upper bound. Specify two numbers separated by a comma to specify both
446 upper and lower bounds. To specify just the lower bound, add a comma
447 afterwards. Can be specified twice, corresponding to figures with multiple
448 axes.
449 .UNINDENT
450 .INDENT 0.0
451 .TP
452 .B \-S, \-\-scale\-mode
453 Treat file names (except for the first one) passed as unqualified arguments
454 as if passed as \fB\-\-scale\-data\fP (default as if passed as
455 \fB\-\-input\fP).
456 .UNINDENT
457 .INDENT 0.0
458 .TP
459 .B \-\-concatenate
460 Concatenate multiple result sets into one data series. This means that each
461 data file will have its time axis shifted by the preceding series duration
462 and appended to the first data set specified. Only works for data sets from
463 the same test, obviously.
464 .UNINDENT
465 .INDENT 0.0
466 .TP
467 .B \-\-absolute\-time
468 Plot data points with absolute UNIX time on the x\-axis. This requires the
469 absolute starting time for the test run to be stored in the data file, and so
470 it won’t work with data files that predates this feature.
471 .UNINDENT
472 .INDENT 0.0
473 .TP
474 .B \-\-subplot\-combine
475 When plotting multiple data series, plot each one on a separate subplot
476 instead of combining them into one plot. This mode is not supported for all
477 plot types, and only works when \fB\-\-scale\-mode\fP is disabled.
478 .UNINDENT
479 .INDENT 0.0
480 .TP
481 .B \-\-skip\-missing\-series
482 Skip missing series entirely from bar plots, instead of leaving an empty
483 space for it.
484 .UNINDENT
485 .INDENT 0.0
486 .TP
487 .B \-\-no\-print\-n
488 Do not print the number of data points on combined plots. When using plot
489 types that combines results from several test runs, the number of data series
490 in each combined data point is normally added after the series name, (n=X)
491 for X data series. This option turns that off.
492 .UNINDENT
493 .INDENT 0.0
494 .TP
495 .B \-\-no\-annotation
496 Exclude annotation with hostnames, time and test length from plots.
497 .UNINDENT
498 .INDENT 0.0
499 .TP
500 .B \-\-figure\-note=NOTE, \-\-fig\-note=NOTE
501 Add a note (arbitrary text) to the bottom\-left of the figure.
502 .UNINDENT
503 .INDENT 0.0
504 .TP
505 .B \-\-no\-title
506 Exclude title from plots.
507 .UNINDENT
508 .INDENT 0.0
509 .TP
510 .B \-\-override\-title=TITLE
511 Override plot title with this string. Completely discards the configured
512 title (from the test configuration), as well as the title stored in the data
513 set, and replaces it with the value supplied here. This is useful to override
514 the plot title \fIat the time of plotting\fP, for instance to add a title to an
515 aggregate plot from several data series. When this parameter is specified,
516 \fB\-\-no\-title\fP has no effect.
517 .UNINDENT
518 .INDENT 0.0
519 .TP
520 .B \-\-no\-labels
521 Hides tick labels from box and bar plots.
522 .UNINDENT
523 .INDENT 0.0
524 .TP
525 .B \-\-no\-markers
526 Don’t use line markers to differentiate data series on plots.
527 .UNINDENT
528 .INDENT 0.0
529 .TP
530 .B \-\-no\-legend
531 Exclude legend from plots.
532 .UNINDENT
533 .INDENT 0.0
534 .TP
535 .B \-\-horizontal\-legend
536 Place a horizontal legend below the plot instead of a vertical one next to
537 it. Doesn\(aqt always work well if there are too many items in the legend.
538 .UNINDENT
539 .INDENT 0.0
540 .TP
541 .B \-\-legend\-title=LEGEND_TITLE
542 Override legend title on plot.
543 .UNINDENT
544 .INDENT 0.0
545 .TP
546 .B \-\-legend\-placement=LEGEND_PLACEMENT
547 Control legend placement. Enabling this option will place the legend inside
548 the plot at the specified location. Can be one of \(aqbest\(aq, \(aqupper right\(aq,
549 \(aqupper left\(aq, \(aqlower left\(aq, \(aqlower right\(aq, \(aqright\(aq, \(aqcenter left\(aq, \(aqcenter
550 right\(aq, \(aqlower center\(aq, \(aqupper center\(aq or \(aqcenter\(aq.
551 .UNINDENT
552 .INDENT 0.0
553 .TP
554 .B \-\-legend\-columns=LEGEND_COLUMNS
555 .TP
556 .B Set the number of columns in the legend.
557 .UNINDENT
558 .INDENT 0.0
559 .TP
560 .B \-\-reverse\-legend
561 Reverse the order of items in the legend. This can be useful to make the
562 legend order match the data series in some cases.
563 .UNINDENT
564 .INDENT 0.0
565 .TP
566 .B \-\-filter\-legend
567 Filter legend labels by removing the longest common substring from all
568 entries. This is not particularly smart, so use with care.
569 .UNINDENT
570 .INDENT 0.0
571 .TP
572 .B \-\-replace\-legend=src=dest
573 Replace \(aqsrc\(aq with \(aqdst\(aq in legends. Can be specified multiple times.
574 .UNINDENT
575 .INDENT 0.0
576 .TP
577 .B \-\-filter\-regexp=REGEXP
578 Filter the plot legend by the supplied regular expression (removing any text
579 from the legend that matches the expression). Can be specified multiple
580 times, in which case the filters will be applied in the order specified. Note
581 that for combining several plot results, the regular expression is also
582 applied before the grouping logic, meaning that a too wide filter can mess up
583 the grouping.
584 .UNINDENT
585 .INDENT 0.0
586 .TP
587 .B \-\-override\-label=LABEL
588 Override dataset label. Can be specified multiple times when multiple
589 datasets are being plotted, in which case the order of labels corresponds to
590 the order of datasets.
591 .sp
592 Like \fB\-\-override\-title\fP, this is applied \fIat the time of plotting\fP\&.
593 .UNINDENT
594 .INDENT 0.0
595 .TP
596 .B \-\-filter\-series=SERIES
597 Filter out specified series from plot. Can be specified multiple times.
598 .UNINDENT
599 .INDENT 0.0
600 .TP
601 .B \-\-split\-group=LABEL
602 Split data sets into groups when creating box plots. Specify this option
603 multiple times to define the new groups; the value of each option is the
604 group name.
605 .sp
606 Say you\(aqre plotting nine datasets which are really testing two variables with
607 three values each. In this case, it can be useful to have the box plot of the
608 results be split into three parts (corresponding to the values of one
609 variable) with each three boxes in each of them (corresponding to the values
610 of the second variable). This option makes this possible; simply specify it
611 three times with the labels to be used for the three groups.
612 .sp
613 A constraint on this option is that the number of datasets being plotted must
614 be divisible by the number of groups.
615 .UNINDENT
616 .INDENT 0.0
617 .TP
618 .B \-\-colours=COLOURS
619 Comma\-separated list of colours to be used for the plot colour cycle. Can be
620 specified in any format understood by matplotlib (including HTML hex values
621 prefixed with a #).
622 .sp
623 Yes, this option uses British spelling. No, American spelling is not
624 supported.
625 .UNINDENT
626 .INDENT 0.0
627 .TP
628 .B \-\-override\-colour\-mode=MODE
629 Override colour_mode attribute. This changes the way colours are
630 assigned to bar plots. The default is \(aqgroups\(aq which assigns a separate
631 colour to each group of data series. The alternative is \(aqseries\(aq which
632 assigns a separate colour to each series, repeating them for each data
633 group.
634 .UNINDENT
635 .INDENT 0.0
636 .TP
637 .B \-\-override\-group\-by=GROUP
638 Override the \fBgroup_by\fP setting for combination plots. This is useful to,
639 for instance, switch to splitting up combined data sets by batch run instead
640 of by file name.
641 .UNINDENT
642 .INDENT 0.0
643 .TP
644 .B \-\-combine\-save\-dir=DIRNAME
645 When doing a combination plot save the intermediate data to \fBDIRNAME\fP\&. This
646 can then be used for subsequent plotting to avoid having to load all the
647 source data files again on each plot.
648 .UNINDENT
649 .INDENT 0.0
650 .TP
651 .B \-\-figure\-width=FIG_WIDTH
652 Figure width in inches. Used when saving plots to file and for default size
653 of the interactive plot window.
654 .UNINDENT
655 .INDENT 0.0
656 .TP
657 .B \-\-figure\-height=FIG_HEIGHT
658 Figure height in inches. Used when saving plots to file and for default size
659 of the interactive plot window.
660 .UNINDENT
661 .INDENT 0.0
662 .TP
663 .B \-\-figure\-dpi=FIG_DPI
664 Figure DPI. Used when saving plots to raster format files.
665 .UNINDENT
666 .INDENT 0.0
667 .TP
668 .B \-\-fallback\-layout
669 Use the fallback layout engine (tight_layout built in to matplotlib). Use
670 this if text is cut off on saved figures. The downside to the fallback engine
671 is that the size of the figure (as specified by \fB\-\-figure\-width\fP and
672 \fB\-\-figure\-height\fP) is no longer kept constant.)
673 .UNINDENT
674 .INDENT 0.0
675 .TP
676 .B \-\-no\-matplotlibrc
677 Don’t load included matplotlibrc values. Use this if autodetection of custom
678 matplotlibrc fails and flent is inadvertently overriding rc values.
679 .UNINDENT
680 .INDENT 0.0
681 .TP
682 .B \-\-no\-hover\-highlight
683 Don\(aqt highlight data series on hover in interactive plot views. Use this if
684 redrawing is too slow, or the highlighting is undesired for other reasons.
685 .UNINDENT
686 .INDENT 0.0
687 .TP
688 .B \-\-scale\-data=SCALE_DATA
689 Additional data files to consider when scaling the plot axes (for plotting
690 several plots with identical axes). Note, this displays only the first data
691 set, but with axis scaling taking into account the additional data sets. Can
692 be supplied multiple times; see also \fB\-\-scale\-mode\fP\&.
693 .UNINDENT
694 .SS Test tool\-related options
695 .INDENT 0.0
696 .TP
697 .B \-\-control\-host=HOST
698 Hostname for the test control connection (for test tools that support this).
699 Default: First hostname of test target.
700 .sp
701 When running tests that uses D\-ITG as a test tool (such as the voip\-*
702 tests), this switch controls where flent will look for the D\-ITG control
703 server (see section below on running tests with D\-ITG). For Netperf\-based
704 tests, this option is passed to Netperf to control where to point the control
705 connection. This is useful to, for instance, to run the control server
706 communication over a separate control network so as to not interfere with
707 test traffic.
708 .sp
709 There is also a per\-flow setting for this for tests that connect to multiple
710 hosts; see the \fIcontrol_hosts\fP test parameter in Supplied Tests\&. If both are
711 set, the per\-flow setting takes precedence for those tests that use it.
712 .UNINDENT
713 .INDENT 0.0
714 .TP
715 .B \-\-control\-local\-bind=IP
716 Local hostname or IP to bind control connection to (for test tools that
717 support it; currently netperf). If not supplied, the value for
718 \fB\-\-local\-bind\fP will be used. Note that if this value is passed but
719 \fB\-\-local\-bind\fP is \fInot\fP, netperf will use the value specified here to
720 bind the data connections to as well.
721 .UNINDENT
722 .INDENT 0.0
723 .TP
724 .B \-\-netperf\-control\-port=PORT
725 Port for Netperf control server. Default: 12865.
726 .UNINDENT
727 .INDENT 0.0
728 .TP
729 .B \-\-ditg\-control\-port=PORT
730 Port for D\-ITG control server. Default: 8000.
731 .UNINDENT
732 .INDENT 0.0
733 .TP
734 .B \-\-ditg\-control\-secret=SECRET
735 Secret for D\-ITG control server authentication. Default: ’’.
736 .UNINDENT
737 .INDENT 0.0
738 .TP
739 .B \-\-http\-getter\-urllist=FILENAME
740 When running HTTP tests, the http\-getter tool is used to fetch URLs (see
741 \%<https://\:github\:.com/\:tohojo/\:http-getter>). This option specifies the filename
742 containing the list of HTTP URLs to get. Can also be a URL, which will then
743 be downloaded as part of each test iteration. If not specified, this is set
744 to \%<http:/>/<hostname>/filelist.txt where <hostname> is the first test
745 hostname.
746 .UNINDENT
747 .INDENT 0.0
748 .TP
749 .B \-\-http\-getter\-dns\-servers=DNS_SERVERS
750 DNS servers to use for http\-getter lookups. Format is
751 host[:port][,host[:port]]... This option will only work if libcurl supports
752 it (needs to be built with the ares resolver). Default is none (use the
753 system resolver).
754 .UNINDENT
755 .INDENT 0.0
756 .TP
757 .B \-\-http\-getter\-timeout=MILLISECONDS
758 Timeout for HTTP connections. Default is to use the test length.
759 .UNINDENT
760 .INDENT 0.0
761 .TP
762 .B \-\-http\-getter\-workers=NUMBER
763 Number of workers to use for getting HTTP urls. Default is 4.
764 .UNINDENT
765 .INDENT 0.0
766 .TP
767 .B \-\-irtt\-sampling\-interval=MILLISECONDS
768 Override the sampling interval passed to irtt, in milliseconds. Can be used
769 to run irtt with a higher sampling frequency than the rest of the test. If
770 set, this will override the sampling interval for all instances of irtt used
771 in the test.
772 .UNINDENT
773 .SS Misc and debugging options:
774 .INDENT 0.0
775 .TP
776 .B \-L LOG_FILE, \-\-log\-file=LOG_FILE
777 Write debug log (test program output) to log file.
778 .UNINDENT
779 .INDENT 0.0
780 .TP
781 .B \-\-list\-tests
782 List available tests and exit.
783 .UNINDENT
784 .INDENT 0.0
785 .TP
786 .B \-\-list\-plots
787 List available plots for selected test and exit.
788 .UNINDENT
789 .INDENT 0.0
790 .TP
791 .B \-V, \-\-version
792 Show Flent version information and exit.
793 .UNINDENT
794 .INDENT 0.0
795 .TP
796 .B \-v, \-\-verbose
797 Enable verbose logging to console.
798 .UNINDENT
799 .INDENT 0.0
800 .TP
801 .B \-q, \-\-quiet
802 Disable normal logging to console (and only log warnings and errors).
803 .UNINDENT
804 .INDENT 0.0
805 .TP
806 .B \-\-debug\-error
807 Print full exception backtraces to console.
808 .UNINDENT
809 .INDENT 0.0
810 .TP
811 .B \-h, \-\-help
812 Show usage help message and exit.
813 .UNINDENT
814 .SS Signals
815 .sp
816 Flent will abort what it is currently doing on receiving a \fBSIGINT\fP \-\- this
817 includes killing all runners, cleaning up temporary files and shutting down as
818 gracefully as possible. Runners are killed with \fBSIGTERM\fP in this mode, and
819 their output is discarded. If a batch run is in progress, the current test will
820 be interrupted in this way, and the rest of the batch run is aborted. Previously
821 completed tests and their results are not aborted. Post\-commands marked as
822 ’essential’ will be run after the test is interrupted. Additionally, flent
823 converts \fBSIGTERM\fP into \fBSIGINT\fP internally and reacts accordingly.
824 .sp
825 Upon receiving a \fBSIGUSR1\fP, flent will try to gracefully abort the test it is
826 currently running, and parse the output of the runners to the extent that any
827 such output exists. That is, each runner will be killed by a \fBSIGINT\fP, which
828 will cause a graceful shutdown for at least ping and netperf (although netperf
829 running in \fITCP_MAERTS\fP mode will bug out when interrupted like this, so
830 end\-of\-tests statistics will be missing). Flent will only react once to a
831 \fBSIGUSR1\fP, sending exactly one \fBSIGINT\fP to the active runners, then wait for
832 them to exit. This may take several seconds in the case of netperf. If the
833 runners for some reason fail to exit, flent will be stuck and will need to be
834 killed with \fBSIGINT\fP\&. If running in batch mode, \fBSIGUSR1\fP will only affect
835 the currently running test; subsequent tests will still be run.
836 .SH SUPPLIED TESTS
837 .sp
838 Test are supplied as Python files and can specify commands to run etc.
839 For a full list of the tests supported by flent, see the
840 \fB\-\-list\-tests\fP option.
841 .SS The Realtime Response Under Load (RRUL) test
842 .sp
843 This test exists in a couple of variants and is a partial implementation of the
844 RRUL specification as written by Dave Taht (see
845 \%<https://\:www\:.bufferbloat\:.net/\:projects/\:bloat/\:wiki/\:RRUL_Spec/>). It works
846 by running RTT measurement using ICMP ping and UDP roundtrip time measurement,
847 while loading up the link with eight TCP streams (four downloads, four uploads).
848 This quite reliably saturates the measured link (wherever the bottleneck might
849 be), and thus exposes bufferbloat when it is present.
850 .SS Simple TCP flow tests
851 .sp
852 These tests combine a TCP flow (either in one direction, or both) with an ICMP
853 ping measurement. It’s a simpler test than RRUL, but in some cases the single
854 TCP flow can be sufficient to saturate the link.
855 .SS UDP flood test
856 .sp
857 This test runs \fIiperf\fP configured to emit 100Mbps of UDP packets targeted at the
858 test host, while measuring RTT using ICMP ping. It is useful for observing
859 latency in the face of a completely unresponsive packet stream.
860 .SS Test parameters
861 .sp
862 Some test parameters (set with \fB\-\-test\-parameter\fP ) affect the way tests
863 behave. These are:
864 .INDENT 0.0
865 .TP
866 .B upload_streams
867 .UNINDENT
868 .INDENT 0.0
869 .TP
870 .B download_streams
871 .UNINDENT
872 .INDENT 0.0
873 .TP
874 .B bidir_streams
875 These set the number of streams for the tests that are configurable. The
876 \fBtcp_nup\fP, \fBtcp_ndown\fP and \fBrrul_be_nflows\fP tests understand
877 \fBupload_streams\fP and \fBdownload_streams\fP, while the \fBrrul_var\fP test
878 understands \fBbidir_streams\fP\&. If any of these parameter is set to the
879 special value \fBnum_cpus\fP the number of streams will be set to the number of
880 CPUs on the system (if this information is available).
881 .UNINDENT
882 .INDENT 0.0
883 .TP
884 .B tcp_cong_control
885 Set the congestion control used for TCP flows, for platforms that supports
886 setting it. This can be specified as a simple string to set the same value
887 for upstream and downstream, or two comma\-separated values to set it
888 separately for the upstream and downstream directions. On Linux, any value in
889 the sysctl \fBnet.ipv4.tcp_allowed_congestion_control\fP can be used.
890 .sp
891 If a congestion control is specified that is not available on the system
892 running the test, setting it will simply fail. In addition, some tests
893 override the congestion control for one or more flows. The actual congestion
894 control used is stored in the \fBCONG_CONTROL\fP per\-test metadata field.
895 .UNINDENT
896 .INDENT 0.0
897 .TP
898 .B udp_bandwidth
899 .UNINDENT
900 .INDENT 0.0
901 .TP
902 .B udp_bandwidths
903 .UNINDENT
904 .INDENT 0.0
905 .TP
906 .B udp_pktsize
907 .UNINDENT
908 .INDENT 0.0
909 .TP
910 .B udp_pktsizes
911 This sets the bandwidth and packet size of each UDP stream in the \fBudp_*\fP
912 tests. The option is passed to \fBiperf\fP so can be in any syntax the iperf
913 understands (e.g. \fB20M\fP for 20 Mbps).
914 .sp
915 When running multiple UDP streams use the plural versions of the options
916 (\fBudp_bandwidths\fP and \fBudp_pktsizes\fP) to specify individual per\-stream
917 values (comma\-separated per stream), or the singular versions to specify the
918 same value for all streams.
919 .UNINDENT
920 .INDENT 0.0
921 .TP
922 .B burst_length
923 .UNINDENT
924 .INDENT 0.0
925 .TP
926 .B burst_ports
927 .UNINDENT
928 .INDENT 0.0
929 .TP
930 .B burst_psize
931 .UNINDENT
932 .INDENT 0.0
933 .TP
934 .B burst_tos
935 These set the length, number of ports to use, packet size and TOS value for
936 the packet bursts generated in the \fBburst*\fP tests.
937 .UNINDENT
938 .INDENT 0.0
939 .TP
940 .B cpu_stats_hosts
941 .UNINDENT
942 .INDENT 0.0
943 .TP
944 .B netstat_hosts
945 .UNINDENT
946 .INDENT 0.0
947 .TP
948 .B qdisc_stats_hosts
949 .UNINDENT
950 .INDENT 0.0
951 .TP
952 .B wifi_stats_hosts
953 These set hostnames to gather statistics from from during the test. The
954 hostnames are passed to SSH, so can be anything understood by SSH (including
955 using \fBusername@host\fP syntax, or using hosts defined in \fB~/.ssh/config\fP).
956 This will attempt to run remote commands on these hosts to gather the
957 required statistics, so passwordless login has to be enabled for. Multiple
958 hostnames can be specified, separated by commas.
959 .sp
960 CPU stats and netstat output is global to the machine being connected to. The
961 qdisc and WiFi stats need extra parameters to work. These are
962 \fBqdisc_stats_interfaces\fP, \fBwifi_stats_interfaces\fP and
963 \fBwifi_stats_stations\fP\&. The two former specify which interfaces to gather
964 statistics from. These are paired with the hostnames, and so must contain the
965 same number of elements (also comma\-separated) as the \fB_hosts\fP variables.
966 To specify multiple interfaces on the same host, duplicate the hostname. The
967 \fBwifi_stats_stations\fP parameter specifies MAC addresses of stations to
968 gather statistics for. This list is the same for all hosts, but only stations
969 present in debugfs on each host are actually captured.
970 .sp
971 The qdisc stats gather statistics output from \fBtc \-s\fP, while the WiFi stats
972 gather statistics from debugfs. These are gathered by looping in a shell
973 script; however, for better performance, the \fBtc_iterate\fP and
974 \fBwifistats_iterate\fP programmes available in the \fBmisc/\fP directory of the
975 source code tarball can be installed. On low\-powered systems this can be
976 critical to get correct statistics. The helper programmes are packaged for
977 LEDE/OpenWrt in the \fBflent\-tools\fP package.
978 .UNINDENT
979 .INDENT 0.0
980 .TP
981 .B ping_hosts
982 .UNINDENT
983 .INDENT 0.0
984 .TP
985 .B ping_local_binds
986 .UNINDENT
987 .INDENT 0.0
988 .TP
989 .B ping_labels
990 These are used to define one or more extra host names that will receive a
991 ping flow while a test is run. The \fBping_hosts\fP variable simply specifies
992 hostnames to ping (several can be specified by separating them with commas).
993 The \fBping_local_binds\fP variable sets local IP address(es) to bind to for
994 the extra ping flows. If specified, it must contain the same number of local
995 addresses as the number of ping hosts. The same local address can be
996 specified multiple times, however. The \fBping_labels\fP variable is used to
997 label each of the ping flows; if not specified, Flent will create a default
998 label based on the target hostname for each flow.
999 .UNINDENT
1000 .INDENT 0.0
1001 .TP
1002 .B voip_host
1003 .UNINDENT
1004 .INDENT 0.0
1005 .TP
1006 .B voip_local_bind
1007 .UNINDENT
1008 .INDENT 0.0
1009 .TP
1010 .B voip_control_host
1011 .UNINDENT
1012 .INDENT 0.0
1013 .TP
1014 .B voip_marking
1015 Similar to the ping variants above, these parameters specify a hostname that
1016 will receive a VoIP test. However, unlike the ping parameters, only one
1017 hostname can be specified for VoIP tests, and that end\-host needs to have
1018 either D\-ITG (and the control server) or the IRTT server running. The marking
1019 setting controls which DiffServ marking is applied to the VoIP flow and
1020 defaults to no marking being set.
1021 .UNINDENT
1022 .INDENT 0.0
1023 .TP
1024 .B control_hosts
1025 Hostnames to use for the control connections for the \fBrtt_fair*\fP tests.
1026 Comma\-separated. If specified, it must contain as many hostnames as the
1027 number of target hostnames specified for the test.
1028 .UNINDENT
1029 .INDENT 0.0
1030 .TP
1031 .B markings
1032 .UNINDENT
1033 .INDENT 0.0
1034 .TP
1035 .B labels
1036 Flow markings to use for each of the flows in the \fBrtt_fair*\fP tests.
1037 Comma\-separated values of markings understood by Netperf (such as \(dqCS0\(dq).
1038 Only supports setting the same marking on both the upstream and downstream
1039 packets of each flow (so no \(dqCS0,CS0\(dq setting as can be used for Netperf). If
1040 not set, defaults to CS0 (best effort). If set, each value corresponds to a
1041 flow, and any extra flows will be set to CS0. By default each flow will be
1042 labelled according to its marking; to override these labels, use the
1043 \fBlabels\fP parameter.
1044 .UNINDENT
1045 .INDENT 0.0
1046 .TP
1047 .B stream_delays
1048 Specify a per\-stream delay (in seconds) for the different streams started up
1049 by a test. Use commas to separate values for the different streams. This can
1050 be used to create tests with staggered start times, for example to test TCP
1051 flow startup convergence times. What exactly constitutes a stream depends on
1052 the test. For example, the rtt_fair* tests considers each hostname a stream,
1053 whether or not there is one or two flows going to that host.
1054 .UNINDENT
1055 .SH THE FLENT GUI
1056 .sp
1057 Flent comes equipped with a GUI to browse and plot previously captured datasets.
1058 The GUI requires PyQt4; if this is installed, it can be launched with the
1059 \fB\-\-gui\fP parameter, or by launching the \fBflent\-gui\fP binary.
1060 Additionally, if Flent is launched without parameters and without a controlling
1061 terminal, the GUI will be launched automatically.
1062 .sp
1063 The GUI can be used for interactively plotting previously captured datasets, and
1064 makes it easy to compare results from several test runs. It presents a tabbed
1065 interface to graphs of data files, allows dynamic configuration of plots, and
1066 includes a metadata browser. For each loaded data file, additional data files
1067 can be loaded and added to the plot, similar to what happens when specifying
1068 multiple input files for plotting on the command line. A checkbox controls
1069 whether the added data files are added as separate entries to the plot, or
1070 whether they are used for scaling the output (mirroring the
1071 \fB\-\-scale\-mode\fP ) command line switch.
1072 .sp
1073 The GUI also incorporates matplotlib’s interactive browsing toolbar, enabling
1074 panning and zooming of the plot area, dynamic configuration of plot and axis
1075 parameters and labels and saving the plots to file. The exact dynamic features
1076 supported depends on the installed version of matplotlib.
1077 .SH CONFIGURATION FILES
1078 .SS The RC file
1079 .sp
1080 Some of the command line options can be specified in an rc file. By default,
1081 flent looks for this in \fB~/.flentrc\fP, but an alternative location can be
1082 specified with the \fB\-\-rcfile\fP command line option.
1083 .sp
1084 The rc file allows options to be specified globally, an optionally overridden
1085 for specific tests. For an explanation of the options, refer to the annotated
1086 example rc file, by default installed to
1087 \fB/usr/share/doc/flent/flentrc.example\fP\&.
1088 .SS Batch Files
1089 .sp
1090 Flent supports reading batch files to automate running several tests and
1091 do setup/teardown of test environment etc. This greatly aids
1092 reproducibility of tests.
1093 .sp
1094 The batch file is parsed as an ini file, and can have three types of sections:
1095 batches, commands and args. Each section also has a name; type and name are
1096 separated with two colons. \(aqBatches\(aq are named tests that can be selected from
1097 the command line, \(aqcommands\(aq are system commands to be run before or after each
1098 test run, and \(aqargs\(aq are used in the looping mechanism (which allows repeating
1099 tests multiple times with different parameters).
1100 .sp
1101 Variables in sections control the operation of Flent and can be modified in
1102 several ways: Sections of the same type can inherit from each other and the
1103 variables in an \(aqarg\(aq section will be interpolated into the batch definition on
1104 each iteration of a loop. In addition, variable contents can be substituted into
1105 other variables by using the ${varname} syntax. These three operations are
1106 resolved in this order (inheritance, arg interpolation and variable
1107 substitution).
1108 .sp
1109 An annotated example batchfile is distributed with the source code, and is by
1110 default installed to \fB/usr/share/doc/flent/batchfile.example\fP\&.
1111 .SH THE DATA FILE FORMAT
1112 .sp
1113 The aggregated test data is saved in a file called
1114 \fB<test_name>\-<date>.<title>.flent.gz\fP (the title part is omitted if no title is
1115 specified by the \fB\-t\fP parameter). This file contains the data points
1116 generated during the test, as well as some metadata.
1117 .SS The top\-level object keys
1118 .INDENT 0.0
1119 .TP
1120 .B version
1121 The file format version as an integer.
1122 .UNINDENT
1123 .INDENT 0.0
1124 .TP
1125 .B x_values
1126 An array of the x values for the test data (typically the time
1127 values for timeseries data).
1128 .UNINDENT
1129 .INDENT 0.0
1130 .TP
1131 .B results
1132 A JSON object containing the result data series. The keys are the
1133 data series names; the value for each key is an array of y values
1134 for that data series. The data array has the same length as the
1135 \fBx_values\fP array, but there may be missing data points
1136 (signified by null values).
1137 .UNINDENT
1138 .INDENT 0.0
1139 .TP
1140 .B metadata
1141 An object containing various data points about the test run. The
1142 metadata values are read in as configuration parameters when the
1143 data set is loaded in for further processing. Not all tests use all
1144 the parameters, but they are saved anyway.
1145 .UNINDENT
1146 .INDENT 0.0
1147 .TP
1148 .B raw_values
1149 An array of objects for each data series. Each element of the array
1150 contains the raw values as parsed from the test tool corresponding
1151 to that data series.
1152 .UNINDENT
1153 .SS Metadata keys
1154 .INDENT 0.0
1155 .TP
1156 .B NAME
1157 The test name.
1158 .UNINDENT
1159 .INDENT 0.0
1160 .TP
1161 .B TITLE
1162 Any extra title specified by the \fB\-\-title\-extra\fP parameter
1163 when the test was run.
1164 .UNINDENT
1165 .INDENT 0.0
1166 .TP
1167 .B HOSTS
1168 List of the server hostnames connected to during the test.
1169 .UNINDENT
1170 .INDENT 0.0
1171 .TP
1172 .B LOCAL_HOST
1173 The hostname of the machine that ran the test.
1174 .UNINDENT
1175 .INDENT 0.0
1176 .TP
1177 .B LENGTH
1178 Test length in seconds, as specified by the \fB\-\-length\fP parameter.
1179 .UNINDENT
1180 .INDENT 0.0
1181 .TP
1182 .B TOTAL_LENGTH
1183 Actual data series length, after the test has added time to the
1184 \fBLENGTH\fP\&.
1185 .UNINDENT
1186 .INDENT 0.0
1187 .TP
1188 .B STEP_SIZE
1189 Time step size granularity.
1190 .UNINDENT
1191 .INDENT 0.0
1192 .TP
1193 .B TIME
1194 ISO timestamp of the time the test was initiated.
1195 .UNINDENT
1196 .INDENT 0.0
1197 .TP
1198 .B NOTE
1199 Arbitrary text as entered with the \fB\-\-note\fP switch when the
1200 test was run.
1201 .UNINDENT
1202 .INDENT 0.0
1203 .TP
1204 .B FLENT_VERSION
1205 Version of Flent that generated the data file.
1206 .UNINDENT
1207 .INDENT 0.0
1208 .TP
1209 .B IP_VERSION
1210 IP version used to run test (as specified by command line
1211 parameters, or auto\-detected from \fBgetaddrinfo()\fP if unspecified).
1212 .UNINDENT
1213 .INDENT 0.0
1214 .TP
1215 .B KERNEL_NAME
1216 The kernel name as reported by \fBuname \-s\fP\&.
1217 .UNINDENT
1218 .INDENT 0.0
1219 .TP
1220 .B KERNEL_RELEASE
1221 The kernel release as reported by \fBuname \-r\fP\&.
1222 .UNINDENT
1223 .INDENT 0.0
1224 .TP
1225 .B MODULE_VERSIONS
1226 The sha1sum of certain interesting Linux kernel modules, if
1227 available. Can be used to match test data to specific code versions,
1228 if the kernel build is instrumented to, e.g., set the build ID to a
1229 git revision.
1230 .UNINDENT
1231 .INDENT 0.0
1232 .TP
1233 .B SYSCTLS
1234 The values of several networking\-related sysctls on the host (if
1235 available; Linux only).
1236 .UNINDENT
1237 .INDENT 0.0
1238 .TP
1239 .B EGRESS_INFO
1240 Interface name, qdisc, offload, driver and BQL configuration of the
1241 interface used to reach the test target. This requires that the
1242 \fBip\fP binary is present on Linux, but can be extracted from
1243 \fBroute\fP on BSD. Qdisc information requires the
1244 \fBtc\fP binary to be present, and offload information requires
1245 \fBethtool\fP\&.
1246 .sp
1247 If the \fB\-\-remote\-metadata\fP is used, the extended metadata
1248 info is gathered for each of the hostnames specified. This is
1249 gathered under the \fBREMOTE_METADATA\fP key in the metadata
1250 object, keyed by the hostname values passed to
1251 \fB\-\-remote\-metadata\fP \&. Additionally, the
1252 \fBREMOTE_METADATA\fP object will contain an object called
1253 \fBINGRESS_INFO\fP which is a duplicate of
1254 \fBEGRESS_INFO\fP, but with the destination IP exchanged for the
1255 source address of the host running flent. The assumption here is
1256 that \fB\-\-remote\-metadata\fP is used to capture metadata of a
1257 router known to be in the test path, in which case
1258 \fBINGRESS_INFO\fP will contain information about the reverse
1259 path from the router (which is ingress from the point of view of the
1260 host running flent). If the host being queried for remote metadata
1261 is off the path, the contents of \fBINGRESS_INFO\fP will
1262 probably be the same as that of \fBEGRESS_INFO\fP .
1263 .UNINDENT
1264 .SS Extended metadata
1265 .sp
1266 If the \fB\-\-extended\-metadata\fP switch is turned on, the following
1267 additional values are collected and stored (to the extent they are available
1268 from the platform):
1269 .INDENT 0.0
1270 .TP
1271 .B IP_ADDRS
1272 IP addresses assigned to the machine running flent.
1273 .UNINDENT
1274 .INDENT 0.0
1275 .TP
1276 .B GATEWAYS
1277 IP addresses of all detected default gateways on the system, and the
1278 interfaces they are reachable through. Only available if the
1279 \fBnetstat\fP binary is present on the system.
1280 .UNINDENT
1281 .INDENT 0.0
1282 .TP
1283 .B EGRESS_INFO
1284 In the \fBEGRESS_INFO\fP key, the IP address of the next\-hop
1285 router and the interface MAC address are added if extended metadata
1286 is enabled.
1287 .UNINDENT
1288 .SH OUTPUT FORMATS
1289 .sp
1290 The following output formats are currently supported by Flent:
1291 .SS Plot output (\fB\-f plot\fP )
1292 .sp
1293 Output test data as one of a series of graphical plots of timeseries data or
1294 summarised as a CDF plot. Each test supplies a number of different plots; the
1295 list of plots for a given test is output by the \fB\-\-list\-plots\fP switch
1296 (which must be supplied along with a test name).
1297 .sp
1298 The plots are drawn by matplotlib, and can be displayed on the screen
1299 interactively (requires a graphical display), or output to a file in svg, pdf,
1300 ps and png formats. Using the \fB\-o\fP switch turns out file output (the
1301 file format is inferred from the file name), while not supplying the switch
1302 turns on the interactive plot viewer.
1303 .SS Tabulated output (\fB\-f csv\fP and \fB\-f org_table\fP )
1304 .sp
1305 These formats output the numeric data in a tabulated format to be consumed by
1306 other applications. The \fIcsv\fP output format is a comma\-separated output that can
1307 be imported into e.g. spreadsheets, while \fIorg_table\fP outputs a tabulated output
1308 in the table format supported by Emacs org mode. The data is output in text
1309 format to standard output, or written to a file if invoked with the \fB\-o\fP
1310 parameter.
1311 .SS Statistics output (\fB\-f stats\fP )
1312 .sp
1313 This output format outputs various statistics about the test data, such as total
1314 bandwidth consumed, and various statistical measures (min/max/mean/median/std
1315 dev/variance) for each data source specified in the relevant test (this can
1316 include some data sources not includes on plots). The data is output in text
1317 format to standard output, or written to a file if invoked with the \fB\-o\fP
1318 parameter.
1319 .SS Metadata output (\fB\-f metadata\fP )
1320 .sp
1321 This output format outputs the test metadata as pretty\-printed JSON (also
1322 suitable for human consumption). It is output as a list of objects, where each
1323 object corresponds to the metadata of one test. Mostly useful for inspecting
1324 metadata of stored data files.
1325 .SH MISC INFO
1326 .SS Running tests with the D\-ITG tool
1327 .sp
1328 This version of flent has experimental support for running and parsing the
1329 output of the D\-ITG test tool (see
1330 \%<http://\:traffic\:.comics\:.unina\:.it/\:software/\:ITG/>). Flent supports parsing the
1331 one\-way delay as measured by D\-ITG. However, in order to do so, the data needs
1332 to be collected at the receiver end, statistics extracted, and the result passed
1333 back to flent on the sending side.
1334 .sp
1335 To perform this function, flent supports a control server which will listen to
1336 XML\-RPC requests, spawn an appropriate ITGRecv instance and, after the test is
1337 done, parse its output and make it available for flent to retrieve. This control
1338 server is available as a Python file that by default is installed in
1339 \fB/usr/share/doc/flent/misc\fP\&. It currently requires a patched version of
1340 D\-ITG v2.8.1. The patch is also included in the same directory.
1341 .sp
1342 Note that the D\-ITG server is finicky and not designed with security in mind.
1343 For this reason, the control server includes HMAC authentication to only allow
1344 authenticated clients to run a test against the server; however there is
1345 currently no support for enforcement of this in e.g. firewall rules. Please bear
1346 this in mind when running a publicly reachable ITGRecv instance (with or without
1347 the control server). Another security issue with the control server is that the
1348 Python XML\-RPC library by default is vulnerable to XML entity expansion attacks.
1349 For this reason, it is highly recommended to install the \fBdefusedxml\fP
1350 library (available at \%<https://\:pypi\:.python\:.org/\:pypi/\:defusedxml/>) on the host
1351 running the control server. The server will try to find the library on startup
1352 and refuse to run if it is not available, unless explicitly told otherwise.
1353 .sp
1354 Due to the hassle of using D\-ITG, it is recommended to install \fBirtt\fP
1355 instead and use that for VoIP tests.
1356 .SS Bugs
1357 .sp
1358 Under some conditions (such as severe bufferbloat), the UDP RTT measurements
1359 done by netperf can experience packet loss to the extent that the test aborts
1360 completely, which can cause missing data points for some measurement series.
1361 The \-\-socket\-timeout feature can alleviate this, but requires a recent SVN
1362 version of netperf to work. Flent tries to detect if netperf supports this
1363 option and enables it for the UDP measurements if it does. Using \fBirtt\fP
1364 for UDP measurements is a way to alleviate this; Flent will automatically detect
1365 the availability of irtt and use it if available.
1366 .sp
1367 Probably many other bugs. Please report any found to
1368 \%<https://\:github\:.com/\:tohojo/\:flent/\:issues> and include the output of \fBflent
1369 \-\-version\fP in the report. A debug log (as obtained with \fBflent
1370 \-\-log\-file\fP ) is also often useful.
1371 .SH Author
1372 Toke Høiland-Jørgensen
1373 .SH Copyright
1374 2012-2024, Toke Høiland-Jørgensen and contributors. Source code is GPLv3. Documentation is CC-BY-SA. Neither license affects any output produced by Flent
1375 .\" End of generated man page.