softflowd.8 11 KB

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