softflowd.8 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422
  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 October 14, 2002
  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 6dDh
  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 s Ar sampling_rate
  51. .Op bpf_expression
  52. .Sh DESCRIPTION
  53. .Nm
  54. is a software implementation of a flow-based network traffic monitor.
  55. .Nm
  56. reads network traffic and gathers information about active traffic flows.
  57. A "traffic flow" is communication between two IP addresses or (if the
  58. overlying protocol is TCP or UDP) address/port tuples.
  59. .Pp
  60. The intended use of
  61. .Nm
  62. is as a software implementation of Cisco's NetFlow(tm) traffic account
  63. system.
  64. .Nm
  65. supports data export using versions 1, 5 or 9 of the NetFlow protocol.
  66. .Nm
  67. can also run in statistics-only mode, where it just collects summary
  68. information.
  69. However, too few statistics are collected to make this
  70. mode really useful for anything other than debugging.
  71. .Pp
  72. Network traffic may be obtained by listening on a promiscuous network
  73. interface or by reading stored
  74. .Xr pcap 3
  75. files, such as those written by
  76. .Xr tcpdump 8 .
  77. Traffic may be filtered with an optional
  78. .Xr bpf 4
  79. program, specified on the command-line as
  80. .Ar bpf_expression .
  81. .Nm
  82. is IPv6 capable and will track IPv6 flows if the NetFlow export protocol
  83. supports it (currently only NetFlow v.9 possesses an IPv6 export capability).
  84. .Pp
  85. .Nm
  86. tries to track only active traffic flows.
  87. When the
  88. flow has been quiescent for a period of time it is expired automatically.
  89. Flows may also be expired early if they approach their traffic counts
  90. exceed 2 Gib or if the number of flows being tracked exceeds
  91. .Ar max_flows
  92. (default: 8192).
  93. In this last case, flows are expired oldest-first.
  94. .Pp
  95. Upon expiry, the flow information is accumulated into statistics which may
  96. be viewed using
  97. .Xr softflowctl 8 .
  98. If the
  99. .Fl n
  100. option has been specified the flow information is formatted in a UDP datagram
  101. which is compatible with versions 1, 5 or 9 of Cisco's NetFlow(tm) accounting
  102. export format.
  103. These records are sent to the specified
  104. .Ar host
  105. and
  106. .Ar port .
  107. The host may represent a unicast host or a multicast group.
  108. .Pp
  109. The command-line options are as follows:
  110. .Bl -tag -width Ds
  111. .It Fl n Ar host:port
  112. Specify the
  113. .Ar host
  114. and
  115. .Ar port
  116. that the accounting datagrams are to be sent to.
  117. The host may be specified using a hostname or using a numeric IPv4 or
  118. IPv6 address.
  119. Numeric IPv6 addresses should be encosed in square brackets to avoid ambiguity
  120. between the address and the port.
  121. The destination port may be a portname listed in
  122. .Xr services 5
  123. or a numeric port.
  124. .It Fl i Xo
  125. .Sm off
  126. .Oo Ar if_ndx : Oc
  127. .Ar interface
  128. .Sm on
  129. .Xc
  130. Specify a network interface on which to listen for traffic.
  131. Either the
  132. .Fl i
  133. or the
  134. .Fl r
  135. options must be specified.
  136. .It Fl r Ar pcap_file
  137. Specify that
  138. .Nm
  139. should read from a
  140. .Xr pcap 3
  141. packet capture file (such as one created with the
  142. .Fl w
  143. option of
  144. .Xr tcpdump 8 )
  145. file rather than a network interface.
  146. .Nm
  147. processes the whole capture file and only expires flows when
  148. .Ar max_flows
  149. is exceeded.
  150. In this mode,
  151. .Nm
  152. will not fork and will automatically print summary statistics before
  153. exiting.
  154. .It Fl p Ar pidfile
  155. Specify an alternate location to store the process ID when in daemon mode.
  156. Default is
  157. .Pa /var/run/softflowd.pid
  158. .It Fl c Ar ctlsock
  159. Specify an alternate location for the remote control socket in daemon mode.
  160. Default is
  161. .Pa /var/run/softflowd.ctl
  162. .It Fl m Ar max_flows
  163. Specify the maximum number of flows to concurrently track.
  164. If this limit is exceeded, the flows which have least recently seen traffic
  165. are forcibly expired.
  166. In practice, the actual maximum may briefly exceed this limit by a
  167. small amount as expiry processing happens less frequently than traffic
  168. collection.
  169. The default is 8192 flows, which corresponds to slightly less
  170. than 800k of working data.
  171. .It Fl t Ar timeout_name=time
  172. Set the timeout names
  173. .Ar timeout_name
  174. to
  175. .Ar time .
  176. Refer to the
  177. .Sx Timeouts
  178. section for the valid timeout names and their meanings.
  179. The
  180. .Ar time
  181. parameter may be specified using one of the formats explained in the
  182. .Sx Time Formats
  183. section below.
  184. .It Fl d
  185. Specify that
  186. .Nm
  187. should not fork and daemonise itself.
  188. .It Fl 6
  189. Force
  190. .Nm
  191. to track IPv6 flows even if the NetFlow export protocol does not support
  192. reporting them.
  193. This is useful for debugging and statistics gathering only.
  194. .It Fl D
  195. Places
  196. .Nm
  197. in a debugging mode.
  198. This implies the
  199. .Fl d
  200. and
  201. .Fl 6
  202. flags and turns on additional debugging output.
  203. .It Fl h
  204. Display command-line usage information.
  205. .It Fl L Ar hoplimit
  206. Set the IPv4 TTL or the IPv6 hop limit to
  207. .Ar hoplimit .
  208. .Nm
  209. will use the default system TTL when exporting flows to a unicast host.
  210. When exporting to a multicast group, the default TTL will be 1
  211. (i.e. link-local).
  212. .It Fl T Ar track_level
  213. Specify which flow elements
  214. .Nm
  215. should be used to define a flow.
  216. .Ar track_level
  217. may be one of:
  218. .Dq full
  219. (track everything in the flow, the default),
  220. .Dq proto
  221. (track source and destination addresses and protocol), or
  222. .Dq ip
  223. (only track source and destination addresses).
  224. Selecting either of the latter options will produce flows with less information
  225. in them (e.g. TCP/UDP ports will not be recorded).
  226. This will cause flows to be consolidated, reducing the quantity of output
  227. and CPU load that
  228. .Nm
  229. will place on the system at the cost of some detail being lost.
  230. .It Fl v Ar netflow_version
  231. Specify which version of the NetFlow(tm) protocol
  232. .Nm
  233. should use for export of the flow data.
  234. Supported versions are 1, 5 and 9.
  235. Default is version 5.
  236. .It Fl s Ar sampling_rate
  237. Specify periodical sampling rate (denominator).
  238. .El
  239. .Pp
  240. Any further command-line arguments will be concatenated together and
  241. applied as a
  242. .Xr bpf 4
  243. packet filter.
  244. This filter will cause
  245. .Nm
  246. to ignore the specified traffic.
  247. .Ss Timeouts
  248. .Pp
  249. .Nm
  250. will expire quiescent flows after user-configurable periods.
  251. The exact timeout used depends on the nature of the flow.
  252. The various timeouts that may be set from the command-line (using the
  253. .Fl t
  254. option) and their meanings are:
  255. .Bl -tag -width Ds
  256. .It Ar general
  257. This is the general timeout applied to all traffic unless overridden by
  258. one of the other timeouts.
  259. .It Ar tcp
  260. This is the general TCP timeout, applied to open TCP connections.
  261. .It Ar tcp.rst
  262. This timeout is applied to a TCP connection when a RST packet has been
  263. sent by one or both endpoints.
  264. .It Ar tcp.fin
  265. This timeout is applied to a TCP connection when a FIN packet has been
  266. sent by both endpoints.
  267. .It Ar udp
  268. This is the general UDP timeout, applied to all UDP connections.
  269. .It Ar maxlife
  270. This is the maximum lifetime that a flow may exist for.
  271. All flows are forcibly expired when they pass
  272. .Ar maxlife
  273. seconds.
  274. To disable this feature, specify a
  275. .Ar maxlife
  276. of 0.
  277. .It Ar expint
  278. Specify the interval between expiry checks.
  279. Increase this to group more flows into a NetFlow packet.
  280. To disable this feature, specify a
  281. .Ar expint
  282. of 0.
  283. .El
  284. .Pp
  285. Flows may also be expired if there are not enough flow entries to hold them
  286. or if their traffic exceeds 2 Gib in either direction.
  287. .Xr softflowctl 8
  288. may be used to print information on the average lifetimes of flows and
  289. the reasons for their expiry.
  290. .Ss Time Formats
  291. .Pp
  292. .Nm
  293. command-line arguments that specify time may be expressed using a sequence
  294. of the form:
  295. .Sm off
  296. .Ar time Op Ar qualifier ,
  297. .Sm on
  298. where
  299. .Ar time
  300. is a positive integer value and
  301. .Ar qualifier
  302. is one of the following:
  303. .Pp
  304. .Bl -tag -width Ds -compact -offset indent
  305. .It Cm <none>
  306. seconds
  307. .It Cm s | Cm S
  308. seconds
  309. .It Cm m | Cm M
  310. minutes
  311. .It Cm h | Cm H
  312. hours
  313. .It Cm d | Cm D
  314. days
  315. .It Cm w | Cm W
  316. weeks
  317. .El
  318. .Pp
  319. Each member of the sequence is added together to calculate the total time value.
  320. .Pp
  321. Time format examples:
  322. .Pp
  323. .Bl -tag -width Ds -compact -offset indent
  324. .It 600
  325. 600 seconds (10 minutes)
  326. .It 10m
  327. 10 minutes
  328. .It 1h30m
  329. 1 hour 30 minutes (90 minutes)
  330. .El
  331. .Ss Run-time Control
  332. .Pp
  333. A daemonised
  334. .Nm
  335. instance may be controlled using the
  336. .Xr softflowctl 8
  337. command.
  338. This interface allows one to shut down the daemon, force expiry of
  339. all tracked flows and extract debugging and summary data.
  340. Also, receipt of a
  341. .Dv SIGTERM
  342. or
  343. .Dv SIGINT
  344. will cause
  345. .Nm
  346. to exit, after expiring all flows (and thus sending flow export packets
  347. if
  348. .Fl n
  349. was specified on the command-line).
  350. If you do not want to export flows upon shutdown, clear them first with
  351. .Xr softflowctl 8
  352. or use
  353. .Xr softflowctl 8 's
  354. .Dq exit
  355. command.
  356. .Sh EXAMPLES
  357. .Bl -tag -width Ds
  358. .It softflowd -i fxp0
  359. This command-line will cause
  360. .Nm
  361. to listen on interface fxp0 and to run in statistics gathering mode
  362. only (i.e. no NetFlow data export).
  363. .It softflowd -i fxp0 -n 10.1.0.2:4432
  364. This command-line will cause
  365. .Nm
  366. to listen on interface fxp0 and to export NetFlow v.5 datagrams on flow
  367. expiry to a flow collector running on 10.1.0.2 port 4432.
  368. .It softflowd -v 5 -i fxp0 -n 10.1.0.2:4432 -m 65536 -t udp=1m30s
  369. This command-line increases the number of concurrent flows that
  370. .Nm
  371. will track to 65536 and increases the timeout for UDP flows to 90 seconds.
  372. .It softflowd -v 9 -i fxp0 -n 224.0.1.20:4432 -L 64
  373. This command-line will export NetFlow v.9 flows to the multicast group
  374. 224.0.1.20.
  375. The export datagrams will have their TTL set to 64, so multicast receivers
  376. can be many hops away.
  377. .It softflowd -i fxp0 -p /var/run/sfd.pid.fxp0 -c /var/run/sfd.ctl.fxp0
  378. This command-line specifies alternate locations for the control socket
  379. and pid file.
  380. Similar command-lines are useful when running multiple
  381. instances of
  382. .Nm
  383. on a single machine.
  384. .El
  385. .Sh FILES
  386. .Bl -tag -width Ds
  387. .It Pa /var/run/softflowd.pid
  388. This file stores the process ID when
  389. .Nm
  390. is in daemon mode.
  391. This location may be overridden using the
  392. .Fl p
  393. command-line option.
  394. .It Pa /var/run/softflowd.ctl
  395. This is the remote control socket.
  396. .Nm
  397. listens on this socket for commands from
  398. .Xr softflowctl 8 .
  399. This location may be overridden using the
  400. .Fl c
  401. command-line option.
  402. .El
  403. .Sh BUGS
  404. Currently
  405. .Nm
  406. does not handle maliciously fragmented packets properly, i.e. packets
  407. fragemented such that the UDP or TCP header does not fit into the first
  408. fragment.
  409. It will product correct traffic counts when presented with maliciously
  410. fragmented packets, but will not record TCP or UDP port information.
  411. .Sh AUTHORS
  412. .An Damien Miller Aq djm@mindrot.org
  413. .Sh SEE ALSO
  414. .Xr softflowctl 8 ,
  415. .Xr tcpdump 8 ,
  416. .Xr pcap 3 ,
  417. .Xr bpf 4
  418. .Bd -literal
  419. http://www.ietf.org/rfc/rfc3954.txt
  420. .br
  421. http://www.cisco.com/en/US/products/sw/netmgtsw/ps1964/products_implementation_design_guide09186a00800d6a11.html
  422. .Ed