softflowd.html 19 KB

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