-
Notifications
You must be signed in to change notification settings - Fork 29
/
softflowd.html
540 lines (405 loc) · 18.6 KB
/
softflowd.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Sat Aug 13 06:54:00 2022 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title></title>
</head>
<body>
<hr>
<p>SOFTFLOWD(8) BSD System Manager’s Manual
SOFTFLOWD(8)</p>
<p style="margin-top: 1em"><b>NAME</b></p>
<p style="margin-left:6%;"><b>softflowd</b> — Traffic
flow monitoring</p>
<p style="margin-top: 1em"><b>SYNOPSIS</b></p>
<p style="margin-left:19%;"><b>softflowd</b>
[<b>-6dDhbalN</b>] [<b>-L </b><i>hoplimit</i>]
[<b>-T </b><i>track_level</i>]
[<b>-c </b><i>ctl_sock</i>] [</p>
<p><b>-i </b> [ <i><br>
if_ndx</i>:]<i>interface</i> ]
[<b>-m </b><i>max_flows</i>]
[<b>-n </b><i>host:port</i>]
[<b>-p </b><i>pidfile</i>]
[<b>-r </b><i>pcap_file</i>]
[<b>-t </b><i>timeout_name=seconds</i>]
[<b>-v </b><i>netflow_version</i>]
[<b>-P </b><i>transport_protocol</i>]
[<b>-A </b><i>time_format</i>]
[<b>-s </b><i>sampling_rate</i>]
[<b>-C </b><i>capture_length</i>]
[<b>-R </b><i>receive_port</i>]
[<b>-S </b><i>send_interface_name</i>]
[<b>-x </b><i>number_of_mpls_labels</i>]
[bpf_expression]</p>
<p style="margin-top: 1em"><b>DESCRIPTION</b></p>
<p style="margin-left:6%;"><b>softflowd</b> is a software
implementation of a flow-based network traffic monitor.
<b>softflowd</b> reads network traffic and gathers
information about active traffic flows. A "traffic
flow" is communication between two IP addresses or (if
the overlying protocol is TCP or UDP) address/port
tuples.</p>
<p style="margin-left:6%; margin-top: 1em">The intended use
of <b>softflowd</b> is as a software implementation of
Cisco’s NetFlow(tm) traffic account system.
<b>softflowd</b> supports data export using versions 1, 5, 9
or 10 (a.k.a. IPFIX) of the NetFlow protocol.
<b>softflowd</b> can also run in statistics-only mode, where
it just collects summary information. However, too few
statistics are collected to make this mode really useful for
anything other than debugging.</p>
<p style="margin-left:6%; margin-top: 1em">Network traffic
may be obtained by listening on a promiscuous network
interface (unless the <b>-N</b> option is given) or by
reading stored pcap(3) files, such as those written by
tcpdump(8). Traffic may be filtered with an optional bpf(4)
program, specified on the command-line as
<i>bpf_expression</i>. <b>softflowd</b> is IPv6 capable and
will track IPv6 flows if the NetFlow export protocol
supports it (currently only NetFlow v.9 possesses an IPv6
export capability).</p>
<p style="margin-left:6%; margin-top: 1em"><b>softflowd</b>
tries to track only active traffic flows. When the flow has
been quiescent for a period of time it is expired
automatically. Flows may also be expired early if they
approach their traffic counts exceed 2 Gib or if the number
of flows being tracked exceeds <i>max_flows</i> (default:
8192). In this last case, flows are expired
oldest-first.</p>
<p style="margin-left:6%; margin-top: 1em">Upon expiry, the
flow information is accumulated into statistics which may be
viewed using softflowctl(8). If the <b>-n</b> option has
been specified the flow information is formatted in a UDP
datagram which is compatible with versions 1, 5 or 9 of
Cisco’s NetFlow(tm) accounting export format. These
records are sent to the specified <i>host</i> and
<i>port</i>. The host may represent a unicast host or a
multicast group.</p>
<p style="margin-left:6%; margin-top: 1em">The command-line
options are as follows:</p>
<p style="margin-top: 1em"><b>-n</b> <i>host:port</i></p>
<p style="margin-left:17%;">Specify the <i>host</i> and
<i>port</i> that the accounting datagrams are to be sent to.
The host may be specified using a hostname or using a
numeric IPv4 or IPv6 address. Numeric IPv6 addresses should
be enclosed in square brackets to avoid ambiguity between
the address and the port. The destination port may be a
portname listed in services(5) or a numeric port. Comma can
be used for specifying multiple destinations.</p>
<p style="margin-top: 1em"><b>-N</b></p>
<p style="margin-left:17%; margin-top: 1em">Do not put the
interface into promiscuous mode. Note that the interface
might be in promiscuous mode for some other reason.</p>
<p style="margin-top: 1em"><b>-i</b> <br>
[ <i><br>
if_ndx</i>:]<i>interface</i></p>
<p style="margin-left:17%;">Specify a network interface on
which to listen for traffic. Either the <b>-i</b> or the
<b>-r</b> options must be specified.</p>
<p style="margin-top: 1em"><b>-r</b> <i>pcap_file</i></p>
<p style="margin-left:17%;">Specify that <b>softflowd</b>
should read from a pcap(3) packet capture file (such as one
created with the <b>-w</b> option of tcpdump(8)) file rather
than a network interface. <b>softflowd</b> processes the
whole capture file and only expires flows when
<i>max_flows</i> is exceeded. In this mode, <b>softflowd</b>
will not fork and will automatically print summary
statistics before exiting.</p>
<p style="margin-top: 1em"><b>-p</b> <i>pidfile</i></p>
<p style="margin-left:17%;">Specify an alternate location
to store the process ID when in daemon mode. Default is
<i>/var/run/softflowd.pid</i></p>
<p style="margin-top: 1em"><b>-c</b> <i>ctlsock</i></p>
<p style="margin-left:17%;">Specify an alternate location
for the remote control socket in daemon mode. Default is
<i>/var/run/softflowd.ctl</i></p>
<p style="margin-top: 1em"><b>-m</b> <i>max_flows</i></p>
<p style="margin-left:17%;">Specify the maximum number of
flows to concurrently track. If this limit is exceeded, the
flows which have least recently seen traffic are forcibly
expired. In practice, the actual maximum may briefly exceed
this limit by a small amount as expiry processing happens
less frequently than traffic collection. The default is 8192
flows, which corresponds to slightly less than 800k of
working data.</p>
<p style="margin-top: 1em"><b>-t</b>
<i>timeout_name=time</i></p>
<p style="margin-left:17%;">Set the timeout names
<i>timeout_name</i> to <i>time</i>. Refer to the
<i>Timeouts</i> section for the valid timeout names and
their meanings. The <i>time</i> parameter may be specified
using one of the formats explained in the <i>Time
Formats</i> section below.</p>
<p style="margin-top: 1em"><b>-d</b></p>
<p style="margin-left:17%; margin-top: 1em">Specify that
<b>softflowd</b> should not fork and daemonise itself.</p>
<p style="margin-top: 1em"><b>-6</b></p>
<p style="margin-left:17%; margin-top: 1em">Force
<b>softflowd</b> to track IPv6 flows even if the NetFlow
export protocol does not support reporting them. This is
useful for debugging and statistics gathering only.</p>
<p style="margin-top: 1em"><b>-D</b></p>
<p style="margin-left:17%; margin-top: 1em">Places
<b>softflowd</b> in a debugging mode. This implies the
<b>-d</b> and <b>-6</b> flags and turns on additional
debugging output.</p>
<p style="margin-top: 1em"><b>-B</b> <i>size_bytes</i></p>
<p style="margin-left:17%;">Libpcap buffer size in
bytes</p>
<p style="margin-top: 1em"><b>-b</b></p>
<p style="margin-left:17%; margin-top: 1em">Bidirectional
mode in IPFIX (-b work with -v 10)</p>
<p style="margin-top: 1em"><b>-a</b></p>
<p style="margin-left:17%; margin-top: 1em">Adjusting time
for reading pcap file (-a work with -r)</p>
<p style="margin-top: 1em"><b>-l</b></p>
<p style="margin-left:17%; margin-top: 1em">Load balancing
mode for multiple destinations which are specified with
-n</p>
<p style="margin-top: 1em"><b>-x</b>
<i>number_of_mpls_labels</i></p>
<p style="margin-left:17%;">specify number of mpls labels
for export</p>
<p style="margin-top: 1em"><b>-h</b></p>
<p style="margin-left:17%; margin-top: 1em">Display
command-line usage information.</p>
<p style="margin-top: 1em"><b>-L</b> <i>hoplimit</i></p>
<p style="margin-left:17%;">Set the IPv4 TTL or the IPv6
hop limit to <i>hoplimit</i>. <b>softflowd</b> will use the
default system TTL when exporting flows to a unicast host.
When exporting to a multicast group, the default TTL will be
1 (i.e. link-local).</p>
<p style="margin-top: 1em"><b>-T</b> <i>track_level</i></p>
<p style="margin-left:17%;">Specify which flow elements
<b>softflowd</b> should be used to define a flow.
<i>track_level</i> may be one of: “ether” (track
everything including source and destination addresses,
source and destination port, source and destination ethernet
address, vlanid and protocol), “vlan” (track
source and destination addresses, source and destination
port, vlanid and protocol), “full” (track source
and destination addresses, source and destination port and
protocol in the flow, the default), “proto”
(track source and destination addresses and protocol), or
“ip” (only track source and destination
addresses). Selecting either of the latter options will
produce flows with less information in them (e.g. TCP/UDP
ports will not be recorded). This will cause flows to be
consolidated, reducing the quantity of output and CPU load
that <b>softflowd</b> will place on the system at the cost
of some detail being lost.</p>
<p style="margin-top: 1em"><b>-v</b>
<i>netflow_version</i></p>
<p style="margin-left:17%;">Specify which version of the
NetFlow(tm) protocol <b>softflowd</b> should use for export
of the flow data. Supported versions are 1, 5, 9, 10(IPFIX),
and psamp. Default is version 5.</p>
<p style="margin-top: 1em"><b>-P</b>
<i>transport_protocol</i></p>
<p style="margin-left:17%;">Specify transport layer
protocol for exporting packets. Supported transport layer
protocols are udp, tcp, and sctp.</p>
<p style="margin-top: 1em"><b>-A</b> <i>time_format</i></p>
<p style="margin-left:17%;">Specify absolute time format
form exporting records. Supported time formats are sec,
milli, micro, and nano.</p>
<p style="margin-top: 1em"><b>-s</b>
<i>sampling_rate</i></p>
<p style="margin-left:17%;">Specify periodical sampling
rate (denominator).</p>
<p style="margin-top: 1em"><b>-C</b>
<i>capture_length</i></p>
<p style="margin-left:17%;">Specify length for packet
capture (snaplen).</p>
<p style="margin-top: 1em"><b>-R</b>
<i>receive_port</i></p>
<p style="margin-left:17%;">Specify port number for PSAMP
receive mode.</p>
<p style="margin-top: 1em"><b>-S</b>
<i>send_interface_name</i></p>
<p style="margin-left:17%;">Specify send interface name.
(This option works on Linux only because of use of
SO_BINDTODEVICE for setsockopt.)</p>
<p style="margin-left:6%; margin-top: 1em">Any further
command-line arguments will be concatenated together and
applied as a bpf(4) packet filter. This filter will cause
<b>softflowd</b> to ignore the specified traffic.</p>
<p style="margin-left:6%; margin-top: 1em"><b>Timeouts <br>
softflowd</b> will expire quiescent flows after
user-configurable periods. The exact timeout used depends on
the nature of the flow. The various timeouts that may be set
from the command-line (using the <b>-t</b> option) and their
meanings are:</p>
<p style="margin-top: 1em"><i>general</i></p>
<p style="margin-left:17%;">This is the general timeout
applied to all traffic unless overridden by one of the other
timeouts.</p>
<p style="margin-top: 1em"><i>tcp</i></p>
<p style="margin-left:17%; margin-top: 1em">This is the
general TCP timeout, applied to open TCP connections.</p>
<p style="margin-top: 1em"><i>tcp.rst</i></p>
<p style="margin-left:17%;">This timeout is applied to a
TCP connection when a RST packet has been sent by one or
both endpoints.</p>
<p style="margin-top: 1em"><i>tcp.fin</i></p>
<p style="margin-left:17%;">This timeout is applied to a
TCP connection when a FIN packet has been sent by both
endpoints.</p>
<p style="margin-top: 1em"><i>udp</i></p>
<p style="margin-left:17%; margin-top: 1em">This is the
general UDP timeout, applied to all UDP connections.</p>
<p style="margin-top: 1em"><i>maxlife</i></p>
<p style="margin-left:17%;">This is the maximum lifetime
that a flow may exist for. All flows are forcibly expired
when they pass <i>maxlife</i> seconds. To disable this
feature, specify a <i>maxlife</i> of 0.</p>
<p style="margin-top: 1em"><i>expint</i></p>
<p style="margin-left:17%; margin-top: 1em">Specify the
interval between expiry checks. Increase this to group more
flows into a NetFlow packet. To disable this feature,
specify a <i>expint</i> of 0.</p>
<p style="margin-left:6%; margin-top: 1em">Flows may also
be expired if there are not enough flow entries to hold them
or if their traffic exceeds 2 Gib in either direction.
softflowctl(8) may be used to print information on the
average lifetimes of flows and the reasons for their
expiry.</p>
<p style="margin-left:6%; margin-top: 1em"><b>Time Formats
<br>
softflowd</b> command-line arguments that specify time may
be expressed using a sequence of the form:
<i>time</i>[<i>qualifier</i>], where <i>time</i> is a
positive integer value and <i>qualifier</i> is one of the
following:</p>
<p style="margin-top: 1em"><b><none></b></p>
<p style="margin-left:24%; margin-top: 1em">seconds</p>
<p><b>s</b> | <b>S</b></p>
<p style="margin-left:24%; margin-top: 1em">seconds</p>
<p><b>m</b> | <b>M</b></p>
<p style="margin-left:24%; margin-top: 1em">minutes</p>
<p><b>h</b> | <b>H</b></p>
<p style="margin-left:24%; margin-top: 1em">hours</p>
<p><b>d</b> | <b>D</b></p>
<p style="margin-left:24%; margin-top: 1em">days</p>
<p><b>w</b> | <b>W</b></p>
<p style="margin-left:24%; margin-top: 1em">weeks</p>
<p style="margin-left:6%; margin-top: 1em">Each member of
the sequence is added together to calculate the total time
value.</p>
<p style="margin-left:6%; margin-top: 1em">Time format
examples:</p>
<p style="margin-top: 1em">600</p>
<p style="margin-left:24%; margin-top: 1em">600 seconds (10
minutes)</p>
<p>10m</p>
<p style="margin-left:24%; margin-top: 1em">10 minutes</p>
<p>1h30m</p>
<p style="margin-left:24%; margin-top: 1em">1 hour 30
minutes (90 minutes)</p>
<p style="margin-left:6%; margin-top: 1em"><b>Run-time
Control</b> <br>
A daemonised <b>softflowd</b> instance may be controlled
using the softflowctl(8) command. This interface allows one
to shut down the daemon, force expiry of all tracked flows
and extract debugging and summary data. Also, receipt of a
SIGTERM or SIGINT will cause <b>softflowd</b> to exit, after
expiring all flows (and thus sending flow export packets if
<b>-n</b> was specified on the command-line). If you do not
want to export flows upon shutdown, clear them first with
softflowctl(8) or use softflowctl(8) ’s
“exit” command.</p>
<p style="margin-top: 1em"><b>EXAMPLES</b> <br>
softflowd -i fxp0</p>
<p style="margin-left:17%;">This command-line will cause
<b>softflowd</b> to listen on interface fxp0 and to run in
statistics gathering mode only (i.e. no NetFlow data
export).</p>
<p style="margin-top: 1em">softflowd -i fxp0 -n
10.1.0.2:4432</p>
<p style="margin-left:17%;">This command-line will cause
<b>softflowd</b> to listen on interface fxp0 and to export
NetFlow v.5 datagrams on flow expiry to a flow collector
running on 10.1.0.2 port 4432.</p>
<p style="margin-top: 1em">softflowd -i fxp0 -n
10.1.0.2:4432,10.1.0.3:4432</p>
<p style="margin-left:17%;">This command-line will cause
<b>softflowd</b> to listen on interface fxp0 and to export
NetFlow v.5 datagrams on flow expiry to a flow collector
running on 10.1.0.2 port 4432 and 10.1.0.3 port 4432.</p>
<p style="margin-top: 1em">softflowd -i fxp0 -l -n
10.1.0.2:4432,10.1.0.3:4432</p>
<p style="margin-left:17%;">This command-line will cause
<b>softflowd</b> to listen on interface fxp0 and to export
NetFlow v.5 datagrams on flow expiry to a flow collector
running on 10.1.0.2 port 4432 and 10.1.0.3 port 4432 with
load balncing mode. Odd netflow packets will be sent to
10.1.0.2 port 4432 and even netflow packets will be sent to
10.1.0.3 port 4432.</p>
<p style="margin-top: 1em">softflowd -v 5 -i fxp0 -n
10.1.0.2:4432 -m 65536 -t udp=1m30s</p>
<p style="margin-left:17%;">This command-line increases the
number of concurrent flows that <b>softflowd</b> will track
to 65536 and increases the timeout for UDP flows to 90
seconds.</p>
<p style="margin-top: 1em">softflowd -v 9 -i fxp0 -n
224.0.1.20:4432 -L 64</p>
<p style="margin-left:17%;">This command-line will export
NetFlow v.9 flows to the multicast group 224.0.1.20. The
export datagrams will have their TTL set to 64, so multicast
receivers can be many hops away.</p>
<p style="margin-top: 1em">softflowd -i fxp0 -p
/var/run/sfd.pid.fxp0 -c /var/run/sfd.ctl.fxp0</p>
<p style="margin-left:17%;">This command-line specifies
alternate locations for the control socket and pid file.
Similar command-lines are useful when running multiple
instances of <b>softflowd</b> on a single machine.</p>
<p style="margin-top: 1em"><b>FILES</b> <br>
/var/run/softflowd.pid</p>
<p style="margin-left:17%;">This file stores the process ID
when <b>softflowd</b> is in daemon mode. This location may
be overridden using the <b>-p</b> command-line option.</p>
<p style="margin-top: 1em">/var/run/softflowd.ctl</p>
<p style="margin-left:17%;">This is the remote control
socket. <b>softflowd</b> listens on this socket for commands
from softflowctl(8). This location may be overridden using
the <b>-c</b> command-line option.</p>
<p style="margin-top: 1em"><b>BUGS</b></p>
<p style="margin-left:6%;">Currently <b>softflowd</b> does
not handle maliciously fragmented packets properly, i.e.
packets fragemented such that the UDP or TCP header does not
fit into the first fragment. It will product correct traffic
counts when presented with maliciously fragmented packets,
but will not record TCP or UDP port information. Please
report bugs in softflowd to
https://github.com/irino/softflowd/issues</p>
<p style="margin-top: 1em"><b>AUTHORS</b></p>
<p style="margin-left:6%;">Damien Miller
<[email protected]> <br>
Hitoshi Irino (current maintainer)
<[email protected]></p>
<p style="margin-top: 1em"><b>SEE ALSO</b></p>
<p style="margin-left:6%;">softflowctl(8), tcpdump(8),
pcap(3), bpf(4)</p>
<p style="margin-left:6%; margin-top: 1em">http://www.ietf.org/rfc/rfc3954.txt
<br>
http://www.cisco.com/en/US/products/sw/netmgtsw/ps1964/products_implementation_design_guide09186a00800d6a11.html
<br>
http://www.ietf.org/rfc/rfc5101.txt <br>
http://www.ietf.org/rfc/rfc5103.txt</p>
<p style="margin-left:6%; margin-top: 1em">BSD
November 17, 2019 BSD</p>
<hr>
</body>
</html>