softflowd.8 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483
  1. .\" Copyright (c) 2002 Damien Miller. All rights reserved.
  2. .\" Portions Copyright (c) 2001 Kevin Steves. All rights reserved.
  3. .\"
  4. .\" Redistribution and use in source and binary forms, with or without
  5. .\" modification, are permitted provided that the following conditions
  6. .\" are met:
  7. .\" 1. Redistributions of source code must retain the above copyright
  8. .\" notice, this list of conditions and the following disclaimer.
  9. .\" 2. Redistributions in binary form must reproduce the above copyright
  10. .\" notice, this list of conditions and the following disclaimer in the
  11. .\" documentation and/or other materials provided with the distribution.
  12. .\"
  13. .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  14. .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  15. .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  16. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  17. .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  18. .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  19. .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  20. .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  21. .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  22. .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  23. .\"
  24. .Dd November 17, 2019
  25. .Dt SOFTFLOWD 8
  26. .Os
  27. .Sh NAME
  28. .Nm softflowd
  29. .Nd Traffic flow monitoring
  30. .Sh SYNOPSIS
  31. .Nm softflowd
  32. .Op Fl 6dDhbalN
  33. .Op Fl L Ar hoplimit
  34. .Op Fl T Ar track_level
  35. .Op Fl c Ar ctl_sock
  36. .Bk -words
  37. .Oo Fl i\ \&
  38. .Sm off
  39. .Oo Ar if_ndx : Oc
  40. .Ar interface
  41. .Sm on
  42. .Oc
  43. .Ek
  44. .Op Fl m Ar max_flows
  45. .Op Fl n Ar host:port
  46. .Op Fl p Ar pidfile
  47. .Op Fl r Ar pcap_file
  48. .Op Fl t Ar timeout_name=seconds
  49. .Op Fl v Ar netflow_version
  50. .Op Fl P Ar transport_protocol
  51. .Op Fl A Ar time_format
  52. .Op Fl s Ar sampling_rate
  53. .Op Fl C Ar capture_length
  54. .Op Fl R Ar receive_port
  55. .Op Fl S Ar send_interface_name
  56. .Op Fl x Ar number_of_mpls_labels
  57. .Op bpf_expression
  58. .Sh DESCRIPTION
  59. .Nm
  60. is a software implementation of a flow-based network traffic monitor.
  61. .Nm
  62. reads network traffic and gathers information about active traffic flows.
  63. A "traffic flow" is communication between two IP addresses or (if the
  64. overlying protocol is TCP or UDP) address/port tuples.
  65. .Pp
  66. The intended use of
  67. .Nm
  68. is as a software implementation of Cisco's NetFlow(tm) traffic account
  69. system.
  70. .Nm
  71. supports data export using versions 1, 5, 9 or 10 (a.k.a. IPFIX) of the NetFlow protocol.
  72. .Nm
  73. can also run in statistics-only mode, where it just collects summary
  74. information.
  75. However, too few statistics are collected to make this
  76. mode really useful for anything other than debugging.
  77. .Pp
  78. Network traffic may be obtained by listening on a promiscuous network
  79. interface (unless the
  80. .Fl N
  81. option is given) or by reading stored
  82. .Xr pcap 3
  83. files, such as those written by
  84. .Xr tcpdump 8 .
  85. Traffic may be filtered with an optional
  86. .Xr bpf 4
  87. program, specified on the command-line as
  88. .Ar bpf_expression .
  89. .Nm
  90. is IPv6 capable and will track IPv6 flows if the NetFlow export protocol
  91. supports it (currently only NetFlow v.9 possesses an IPv6 export capability).
  92. .Pp
  93. .Nm
  94. tries to track only active traffic flows.
  95. When the
  96. flow has been quiescent for a period of time it is expired automatically.
  97. Flows may also be expired early if they approach their traffic counts
  98. exceed 2 Gib or if the number of flows being tracked exceeds
  99. .Ar max_flows
  100. (default: 8192).
  101. In this last case, flows are expired oldest-first.
  102. .Pp
  103. Upon expiry, the flow information is accumulated into statistics which may
  104. be viewed using
  105. .Xr softflowctl 8 .
  106. If the
  107. .Fl n
  108. option has been specified the flow information is formatted in a UDP datagram
  109. which is compatible with versions 1, 5 or 9 of Cisco's NetFlow(tm) accounting
  110. export format.
  111. These records are sent to the specified
  112. .Ar host
  113. and
  114. .Ar port .
  115. The host may represent a unicast host or a multicast group.
  116. .Pp
  117. The command-line options are as follows:
  118. .Bl -tag -width Ds
  119. .It Fl n Ar host:port
  120. Specify the
  121. .Ar host
  122. and
  123. .Ar port
  124. that the accounting datagrams are to be sent to.
  125. The host may be specified using a hostname or using a numeric IPv4 or
  126. IPv6 address.
  127. Numeric IPv6 addresses should be enclosed in square brackets to avoid ambiguity
  128. between the address and the port.
  129. The destination port may be a portname listed in
  130. .Xr services 5
  131. or a numeric port.
  132. Comma can be used for specifying multiple destinations.
  133. .It Fl N
  134. Do not put the interface into promiscuous mode. Note that the interface
  135. might be in promiscuous mode for some other reason.
  136. .It Fl i Xo
  137. .Sm off
  138. .Oo Ar if_ndx : Oc
  139. .Ar interface
  140. .Sm on
  141. .Xc
  142. Specify a network interface on which to listen for traffic.
  143. Either the
  144. .Fl i
  145. or the
  146. .Fl r
  147. options must be specified.
  148. .It Fl r Ar pcap_file
  149. Specify that
  150. .Nm
  151. should read from a
  152. .Xr pcap 3
  153. packet capture file (such as one created with the
  154. .Fl w
  155. option of
  156. .Xr tcpdump 8 )
  157. file rather than a network interface.
  158. .Nm
  159. processes the whole capture file and only expires flows when
  160. .Ar max_flows
  161. is exceeded.
  162. In this mode,
  163. .Nm
  164. will not fork and will automatically print summary statistics before
  165. exiting.
  166. .It Fl p Ar pidfile
  167. Specify an alternate location to store the process ID when in daemon mode.
  168. Default is
  169. .Pa /var/run/softflowd.pid
  170. .It Fl c Ar ctlsock
  171. Specify an alternate location for the remote control socket in daemon mode.
  172. Default is
  173. .Pa /var/run/softflowd.ctl
  174. .It Fl m Ar max_flows
  175. Specify the maximum number of flows to concurrently track.
  176. If this limit is exceeded, the flows which have least recently seen traffic
  177. are forcibly expired.
  178. In practice, the actual maximum may briefly exceed this limit by a
  179. small amount as expiry processing happens less frequently than traffic
  180. collection.
  181. The default is 8192 flows, which corresponds to slightly less
  182. than 800k of working data.
  183. .It Fl t Ar timeout_name=time
  184. Set the timeout names
  185. .Ar timeout_name
  186. to
  187. .Ar time .
  188. Refer to the
  189. .Sx Timeouts
  190. section for the valid timeout names and their meanings.
  191. The
  192. .Ar time
  193. parameter may be specified using one of the formats explained in the
  194. .Sx Time Formats
  195. section below.
  196. .It Fl d
  197. Specify that
  198. .Nm
  199. should not fork and daemonise itself.
  200. .It Fl 6
  201. Force
  202. .Nm
  203. to track IPv6 flows even if the NetFlow export protocol does not support
  204. reporting them.
  205. This is useful for debugging and statistics gathering only.
  206. .It Fl D
  207. Places
  208. .Nm
  209. in a debugging mode.
  210. This implies the
  211. .Fl d
  212. and
  213. .Fl 6
  214. flags and turns on additional debugging output.
  215. .It Fl B Ar size_bytes
  216. Libpcap buffer size in bytes
  217. .It Fl b
  218. Bidirectional mode in IPFIX (-b work with -v 10)
  219. .It Fl a
  220. Adjusting time for reading pcap file (-a work with -r)
  221. .It Fl l
  222. Load balancing mode for multiple destinations which are specified with -n
  223. .It Fl x Ar number_of_mpls_labels
  224. specify number of mpls labels for export
  225. .It Fl h
  226. Display command-line usage information.
  227. .It Fl L Ar hoplimit
  228. Set the IPv4 TTL or the IPv6 hop limit to
  229. .Ar hoplimit .
  230. .Nm
  231. will use the default system TTL when exporting flows to a unicast host.
  232. When exporting to a multicast group, the default TTL will be 1
  233. (i.e. link-local).
  234. .It Fl T Ar track_level
  235. Specify which flow elements
  236. .Nm
  237. should be used to define a flow.
  238. .Ar track_level
  239. may be one of:
  240. .Dq ether
  241. (track everything including source and destination addresses, source and destination port, source and destination ethernet address, vlanid and protocol),
  242. .Dq vlan
  243. (track source and destination addresses, source and destination port, vlanid and protocol),
  244. .Dq full
  245. (track source and destination addresses, source and destination port and protocol in the flow, the default),
  246. .Dq proto
  247. (track source and destination addresses and protocol), or
  248. .Dq ip
  249. (only track source and destination addresses).
  250. Selecting either of the latter options will produce flows with less information
  251. in them (e.g. TCP/UDP ports will not be recorded).
  252. This will cause flows to be consolidated, reducing the quantity of output
  253. and CPU load that
  254. .Nm
  255. will place on the system at the cost of some detail being lost.
  256. .It Fl v Ar netflow_version
  257. Specify which version of the NetFlow(tm) protocol
  258. .Nm
  259. should use for export of the flow data.
  260. Supported versions are 1, 5, 9, 10(IPFIX), and psamp.
  261. Default is version 5.
  262. .It Fl P Ar transport_protocol
  263. Specify transport layer protocol for exporting packets.
  264. Supported transport layer protocols are udp, tcp, and sctp.
  265. .It Fl A Ar time_format
  266. Specify absolute time format form exporting records.
  267. Supported time formats are sec, milli, micro, and nano.
  268. .It Fl s Ar sampling_rate
  269. Specify periodical sampling rate (denominator).
  270. .It Fl C Ar capture_length
  271. Specify length for packet capture (snaplen).
  272. .It Fl R Ar receive_port
  273. Specify port number for PSAMP receive mode.
  274. .It Fl S Ar send_interface_name
  275. Specify send interface name.
  276. (This option works on Linux only because of use of SO_BINDTODEVICE for
  277. setsockopt.)
  278. .El
  279. .Pp
  280. Any further command-line arguments will be concatenated together and
  281. applied as a
  282. .Xr bpf 4
  283. packet filter.
  284. This filter will cause
  285. .Nm
  286. to ignore the specified traffic.
  287. .Ss Timeouts
  288. .Pp
  289. .Nm
  290. will expire quiescent flows after user-configurable periods.
  291. The exact timeout used depends on the nature of the flow.
  292. The various timeouts that may be set from the command-line (using the
  293. .Fl t
  294. option) and their meanings are:
  295. .Bl -tag -width Ds
  296. .It Ar general
  297. This is the general timeout applied to all traffic unless overridden by
  298. one of the other timeouts.
  299. .It Ar tcp
  300. This is the general TCP timeout, applied to open TCP connections.
  301. .It Ar tcp.rst
  302. This timeout is applied to a TCP connection when a RST packet has been
  303. sent by one or both endpoints.
  304. .It Ar tcp.fin
  305. This timeout is applied to a TCP connection when a FIN packet has been
  306. sent by both endpoints.
  307. .It Ar udp
  308. This is the general UDP timeout, applied to all UDP connections.
  309. .It Ar maxlife
  310. This is the maximum lifetime that a flow may exist for.
  311. All flows are forcibly expired when they pass
  312. .Ar maxlife
  313. seconds.
  314. To disable this feature, specify a
  315. .Ar maxlife
  316. of 0.
  317. .It Ar expint
  318. Specify the interval between expiry checks.
  319. Increase this to group more flows into a NetFlow packet.
  320. To disable this feature, specify a
  321. .Ar expint
  322. of 0.
  323. .El
  324. .Pp
  325. Flows may also be expired if there are not enough flow entries to hold them
  326. or if their traffic exceeds 2 Gib in either direction.
  327. .Xr softflowctl 8
  328. may be used to print information on the average lifetimes of flows and
  329. the reasons for their expiry.
  330. .Ss Time Formats
  331. .Pp
  332. .Nm
  333. command-line arguments that specify time may be expressed using a sequence
  334. of the form:
  335. .Sm off
  336. .Ar time Op Ar qualifier ,
  337. .Sm on
  338. where
  339. .Ar time
  340. is a positive integer value and
  341. .Ar qualifier
  342. is one of the following:
  343. .Pp
  344. .Bl -tag -width Ds -compact -offset indent
  345. .It Cm <none>
  346. seconds
  347. .It Cm s | Cm S
  348. seconds
  349. .It Cm m | Cm M
  350. minutes
  351. .It Cm h | Cm H
  352. hours
  353. .It Cm d | Cm D
  354. days
  355. .It Cm w | Cm W
  356. weeks
  357. .El
  358. .Pp
  359. Each member of the sequence is added together to calculate the total time value.
  360. .Pp
  361. Time format examples:
  362. .Pp
  363. .Bl -tag -width Ds -compact -offset indent
  364. .It 600
  365. 600 seconds (10 minutes)
  366. .It 10m
  367. 10 minutes
  368. .It 1h30m
  369. 1 hour 30 minutes (90 minutes)
  370. .El
  371. .Ss Run-time Control
  372. .Pp
  373. A daemonised
  374. .Nm
  375. instance may be controlled using the
  376. .Xr softflowctl 8
  377. command.
  378. This interface allows one to shut down the daemon, force expiry of
  379. all tracked flows and extract debugging and summary data.
  380. Also, receipt of a
  381. .Dv SIGTERM
  382. or
  383. .Dv SIGINT
  384. will cause
  385. .Nm
  386. to exit, after expiring all flows (and thus sending flow export packets
  387. if
  388. .Fl n
  389. was specified on the command-line).
  390. If you do not want to export flows upon shutdown, clear them first with
  391. .Xr softflowctl 8
  392. or use
  393. .Xr softflowctl 8 's
  394. .Dq exit
  395. command.
  396. .Sh EXAMPLES
  397. .Bl -tag -width Ds
  398. .It softflowd -i fxp0
  399. This command-line will cause
  400. .Nm
  401. to listen on interface fxp0 and to run in statistics gathering mode
  402. only (i.e. no NetFlow data export).
  403. .It softflowd -i fxp0 -n 10.1.0.2:4432
  404. This command-line will cause
  405. .Nm
  406. to listen on interface fxp0 and to export NetFlow v.5 datagrams on flow
  407. expiry to a flow collector running on 10.1.0.2 port 4432.
  408. .It softflowd -i fxp0 -n 10.1.0.2:4432,10.1.0.3:4432
  409. This command-line will cause
  410. .Nm
  411. to listen on interface fxp0 and to export NetFlow v.5 datagrams on flow
  412. expiry to a flow collector running on 10.1.0.2 port 4432 and 10.1.0.3
  413. port 4432.
  414. .It softflowd -i fxp0 -l -n 10.1.0.2:4432,10.1.0.3:4432
  415. This command-line will cause
  416. .Nm
  417. to listen on interface fxp0 and to export NetFlow v.5 datagrams on flow
  418. expiry to a flow collector running on 10.1.0.2 port 4432 and 10.1.0.3
  419. port 4432 with load balncing mode. Odd netflow packets will be sent to
  420. 10.1.0.2 port 4432 and even netflow packets will be sent to 10.1.0.3
  421. port 4432.
  422. .It softflowd -v 5 -i fxp0 -n 10.1.0.2:4432 -m 65536 -t udp=1m30s
  423. This command-line increases the number of concurrent flows that
  424. .Nm
  425. will track to 65536 and increases the timeout for UDP flows to 90 seconds.
  426. .It softflowd -v 9 -i fxp0 -n 224.0.1.20:4432 -L 64
  427. This command-line will export NetFlow v.9 flows to the multicast group
  428. 224.0.1.20.
  429. The export datagrams will have their TTL set to 64, so multicast receivers
  430. can be many hops away.
  431. .It softflowd -i fxp0 -p /var/run/sfd.pid.fxp0 -c /var/run/sfd.ctl.fxp0
  432. This command-line specifies alternate locations for the control socket
  433. and pid file.
  434. Similar command-lines are useful when running multiple
  435. instances of
  436. .Nm
  437. on a single machine.
  438. .El
  439. .Sh FILES
  440. .Bl -tag -width Ds
  441. .It Pa /var/run/softflowd.pid
  442. This file stores the process ID when
  443. .Nm
  444. is in daemon mode.
  445. This location may be overridden using the
  446. .Fl p
  447. command-line option.
  448. .It Pa /var/run/softflowd.ctl
  449. This is the remote control socket.
  450. .Nm
  451. listens on this socket for commands from
  452. .Xr softflowctl 8 .
  453. This location may be overridden using the
  454. .Fl c
  455. command-line option.
  456. .El
  457. .Sh BUGS
  458. Currently
  459. .Nm
  460. does not handle maliciously fragmented packets properly, i.e. packets
  461. fragemented such that the UDP or TCP header does not fit into the first
  462. fragment.
  463. It will product correct traffic counts when presented with maliciously
  464. fragmented packets, but will not record TCP or UDP port information.
  465. Please report bugs in softflowd
  466. to https://github.com/irino/softflowd/issues
  467. .Sh AUTHORS
  468. .An Damien Miller Aq djm@mindrot.org
  469. .An Hitoshi Irino (current maintainer) Aq irino@sfc.wide.ad.jp
  470. .Sh SEE ALSO
  471. .Xr softflowctl 8 ,
  472. .Xr tcpdump 8 ,
  473. .Xr pcap 3 ,
  474. .Xr bpf 4
  475. .Bd -literal
  476. http://www.ietf.org/rfc/rfc3954.txt
  477. .br
  478. http://www.cisco.com/en/US/products/sw/netmgtsw/ps1964/products_implementation_design_guide09186a00800d6a11.html
  479. http://www.ietf.org/rfc/rfc5101.txt
  480. .br
  481. http://www.ietf.org/rfc/rfc5103.txt
  482. .br
  483. .Ed