flowreplay.html 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  2. <!--Converted with LaTeX2HTML 2002-2-1 (1.70)
  3. original version by: Nikos Drakos, CBLU, University of Leeds
  4. * revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
  5. * with significant contributions from:
  6. Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
  7. <HTML>
  8. <HEAD>
  9. <TITLE>Flowreplay Design Notes</TITLE>
  10. <META NAME="description" CONTENT="Flowreplay Design Notes">
  11. <META NAME="keywords" CONTENT="flowreplay">
  12. <META NAME="resource-type" CONTENT="document">
  13. <META NAME="distribution" CONTENT="global">
  14. <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
  15. <META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
  16. <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
  17. <LINK REL="STYLESHEET" HREF="flowreplay.css">
  18. </HEAD>
  19. <BODY >
  20. <P>
  21. <P>
  22. <P>
  23. <P>
  24. <H1 ALIGN="CENTER"><SPAN ID="hue33">Flowreplay Design Notes</SPAN></H1>
  25. <DIV CLASS="author_info">
  26. <P ALIGN="CENTER"><STRONG><SPAN ID="hue35">Aaron Turner </SPAN></STRONG></P>
  27. <P ALIGN="CENTER"><I><SPAN ID="hue37">http://synfin.net/</SPAN></I></P>
  28. <P ALIGN="CENTER"><STRONG><SPAN ID="hue39">Last Edited:</SPAN>
  29. <BR><SPAN ID="hue41">October 23, 2003</SPAN></STRONG></P>
  30. </DIV>
  31. <P>
  32. <H1><A NAME="SECTION00010000000000000000">
  33. <SPAN CLASS="arabic">1</SPAN> <SPAN ID="hue43">Overview</SPAN></A>
  34. </H1>
  35. <P>
  36. <SPAN ID="hue45">Tcpreplay</SPAN><A NAME="tex2html1"
  37. HREF="#foot362"><SUP><SPAN CLASS="arabic">1</SPAN></SUP></A> <SPAN ID="hue49">was designed to replay traffic previously captured
  38. in the pcap format back onto the wire for testing NIDS and other passive
  39. devices. Over time, it was enhanced to be able to test in-line network
  40. devices. However, a re-occurring feature request for tcpreplay is
  41. to connect to a server in order to test applications and host TCP/IP
  42. stacks. It was determined early on, that adding this feature to tcpreplay
  43. was far too complex, so I decided to create a new tool specifically
  44. designed for this.</SPAN>
  45. <P>
  46. <SPAN ID="hue51">Flowreplay is designed to replay traffic at Layer
  47. 4 or 7 depending on the protocol rather then at Layer 2 like tcpreplay
  48. does. This allows flowreplay to connect to one or more servers using
  49. a pcap savefile as the basis of the connections. Hence, flowreplay
  50. allows the testing of applications running on real servers rather
  51. then passive devices. </SPAN>
  52. <P>
  53. <H1><A NAME="SECTION00020000000000000000">
  54. <SPAN CLASS="arabic">2</SPAN> <SPAN ID="hue53">Features</SPAN></A>
  55. </H1>
  56. <P>
  57. <H2><A NAME="SECTION00021000000000000000">
  58. <SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> <SPAN ID="hue55">Requirements</SPAN></A>
  59. </H2>
  60. <P>
  61. <OL>
  62. <LI><SPAN ID="hue58">Full TCP/IP support, including IP fragments and
  63. TCP stream reassembly.</SPAN>
  64. </LI>
  65. <LI><SPAN ID="hue60">Support replaying TCP and UDP flows.</SPAN>
  66. </LI>
  67. <LI><SPAN ID="hue62">Code should handle each flow/service independently.</SPAN>
  68. </LI>
  69. <LI><SPAN ID="hue64">Should be able to connect to the server(s) in the
  70. pcap file or to a user specified IP address.</SPAN>
  71. </LI>
  72. <LI><SPAN ID="hue66">Support a plug-in architecture to allow adding application
  73. layer intelligence.</SPAN>
  74. </LI>
  75. <LI><SPAN ID="hue68">Plug-ins must be able to support multi-flow protocols
  76. like FTP.</SPAN>
  77. </LI>
  78. <LI><SPAN ID="hue365">Ship with a default plug-in which will work ``well
  79. enough'' for simple single-flow protocols like HTTP and telnet.</SPAN>
  80. </LI>
  81. <LI><SPAN ID="hue366">Flows being replayed ``correctly'' is more important
  82. then performance (Mbps).</SPAN>
  83. </LI>
  84. <LI><SPAN ID="hue74">Portable to run on common flavors of Unix and Unix-like
  85. systems.</SPAN>
  86. </LI>
  87. </OL>
  88. <P>
  89. <H2><A NAME="SECTION00022000000000000000">
  90. <SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> <SPAN ID="hue77">Wishes</SPAN></A>
  91. </H2>
  92. <P>
  93. <OL>
  94. <LI><SPAN ID="hue80">Support clients connecting to flowreplay on a limited
  95. basis. Flowreplay would replay the server side of the connection.</SPAN>
  96. </LI>
  97. <LI><SPAN ID="hue82">Support other IP based traffic (ICMP, VRRP, OSPF,
  98. etc) via plug-ins.</SPAN>
  99. </LI>
  100. <LI><SPAN ID="hue84">Support non-IP traffic (ARP, STP, CDP, etc) via
  101. plug-ins.</SPAN>
  102. </LI>
  103. <LI><SPAN ID="hue86">Limit which flows are replayed using user defined
  104. filters. (bpf filter syntax?)</SPAN>
  105. </LI>
  106. <LI><SPAN ID="hue88">Process pcap files directly with no intermediary
  107. file conversions.</SPAN>
  108. </LI>
  109. <LI><SPAN ID="hue90">Should be able to scale to pcap files in the 100's
  110. of MB in size and 100+ simultaneous flows on a P3 500MHz w/ 256MB
  111. of RAM.</SPAN>
  112. </LI>
  113. </OL>
  114. <P>
  115. <H1><A NAME="SECTION00030000000000000000">
  116. <SPAN CLASS="arabic">3</SPAN> <SPAN ID="hue93">Design Thoughts</SPAN></A>
  117. </H1>
  118. <P>
  119. <H2><A NAME="SECTION00031000000000000000">
  120. <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> <SPAN ID="hue95">Sending and Receiving traffic</SPAN></A>
  121. </H2>
  122. <P>
  123. <SPAN ID="hue97">Flowreplay must be able to process multiple connections
  124. to one or more devices. There are two options:</SPAN>
  125. <P>
  126. <OL>
  127. <LI><SPAN ID="hue100">Use sockets</SPAN><A NAME="tex2html2"
  128. HREF="#foot370"><SUP><SPAN CLASS="arabic">2</SPAN></SUP></A> <SPAN ID="hue104">to send and receive data</SPAN>
  129. </LI>
  130. <LI><SPAN ID="hue106">Use libpcap</SPAN><A NAME="tex2html3"
  131. HREF="#foot371"><SUP><SPAN CLASS="arabic">3</SPAN></SUP></A> <SPAN ID="hue110">to receive packets and libnet</SPAN><A NAME="tex2html4"
  132. HREF="#foot372"><SUP><SPAN CLASS="arabic">4</SPAN></SUP></A> <SPAN ID="hue114">to send packets</SPAN>
  133. </LI>
  134. </OL>
  135. <SPAN ID="hue117">Although using libpcap/libnet would allow more simultaneous
  136. connections and greater flexibility, there would be a very high complexity
  137. cost associated with it. With that in mind, I've decided to use sockets
  138. to send and receive data.</SPAN>
  139. <P>
  140. <H2><A NAME="SECTION00032000000000000000">
  141. <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> <SPAN ID="hue119">Handling Multiple Connections</SPAN></A>
  142. </H2>
  143. <P>
  144. <SPAN ID="hue121">Because a pcap file can contain multiple simultaneous
  145. flows, we need to be able to support that too. The biggest problem
  146. with this is reading packet data in a different order then stored
  147. in the pcap file. </SPAN>
  148. <P>
  149. <SPAN ID="hue123">Reading and writing to multiple sockets is easy
  150. with select() or poll(), however a pcap file has it's data stored
  151. serially, but we need to access it randomly. There are a number of
  152. possible solutions for this such as caching packets in RAM where they
  153. can be accessed more randomly, creating an index of the packets in
  154. the pcap file, or converting the pcap file to another format altogether.
  155. Alternatively, I've started looking at libpcapnav</SPAN><A NAME="tex2html5"
  156. HREF="#foot124"><SUP><SPAN CLASS="arabic">5</SPAN></SUP></A> <SPAN ID="hue126">as an alternate means to navigate a pcap file and
  157. process packets out of order.</SPAN>
  158. <P>
  159. <H2><A NAME="SECTION00033000000000000000">
  160. <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> <SPAN ID="hue128">Data Synchronization</SPAN></A>
  161. </H2>
  162. <P>
  163. <SPAN ID="hue375">Knowing when to start sending client traffic in
  164. response to the server will be &#34;tricky&#34;. Without
  165. understanding the actual protocol involved, probably the best general
  166. solution is waiting for a given period of time after no more data
  167. from the server has been received. Not sure what to do if the client
  168. traffic doesn't elicit a response from the server (implement some
  169. kind of timeout?). This will be the basis for the default plug-in.</SPAN>
  170. <P>
  171. <H2><A NAME="SECTION00034000000000000000">
  172. <SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">4</SPAN> <SPAN ID="hue133">TCP/IP</SPAN></A>
  173. </H2>
  174. <P>
  175. <SPAN ID="hue135">Dealing with IP fragmentation and TCP stream reassembly
  176. will be another really complex problem. We're basically talking about
  177. implementing a significant portion of a TCP/IP stack. One thought
  178. is to use libnids</SPAN><A NAME="tex2html6"
  179. HREF="#foot403"><SUP><SPAN CLASS="arabic">6</SPAN></SUP></A> <SPAN ID="hue139">which basically implements a Linux 2.0.37 TCP/IP
  180. stack in user-space. Other solutions include porting a TCP/IP stack
  181. from Open/Net/FreeBSD or writing our own custom stack from scratch.</SPAN>
  182. <P>
  183. <H1><A NAME="SECTION00040000000000000000">
  184. <SPAN CLASS="arabic">4</SPAN> <SPAN ID="hue141">Multiple Independent Flows</SPAN></A>
  185. </H1>
  186. <P>
  187. <SPAN ID="hue143">The biggest asynchronous problem, that pcap files
  188. are serial, has to be solved in a scaleable manner. Not much can be
  189. assumed about the network traffic contained in a pcap savefile other
  190. then Murphy's Law will be in effect. This means we'll have to deal
  191. with:</SPAN>
  192. <P>
  193. <UL>
  194. <LI><SPAN ID="hue146">Thousands of small simultaneous flows (captured
  195. on a busy network)</SPAN>
  196. </LI>
  197. <LI><SPAN ID="hue379">Flows which ``hang'' mid-stream (an exploit
  198. against a server causes it to crash)</SPAN>
  199. </LI>
  200. <LI><SPAN ID="hue150">Flows which contain large quantities of data (FTP
  201. transfers of ISO's for example)</SPAN>
  202. </LI>
  203. </UL>
  204. <SPAN ID="hue153">How we implement parallel processing of the pcap
  205. savefile will dramatically effect how well we can scale. A few considerations:</SPAN>
  206. <P>
  207. <UL>
  208. <LI>Most Unix systems limit the maximum number of open file descriptors
  209. a single process can have. Generally speaking this shouldn't be a
  210. problem except for highly parallel pcap's.
  211. </LI>
  212. <LI>While RAM isn't limitless, we can use mmap() to get around this.
  213. </LI>
  214. <LI>Many Unix systems have enhanced solutions to poll() which will improve
  215. flow management.
  216. </LI>
  217. </UL>
  218. <P>
  219. <H2><A NAME="SECTION00041000000000000000">
  220. <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> <SPAN ID="hue157">IP Fragments and TCP Streams</SPAN></A>
  221. </H2>
  222. <P>
  223. <SPAN ID="hue159">There are five major complications with flowreplay:</SPAN>
  224. <P>
  225. <OL>
  226. <LI><SPAN ID="hue162">The IP datagrams may be fragmented- we won't be
  227. able to use the standard 5-tuple (src/dst IP, src/dst port, protocol)
  228. to lookup which flow a packet belongs to.</SPAN>
  229. </LI>
  230. <LI><SPAN ID="hue164">IP fragments may arrive out of order which will
  231. complicate ordering of data to be sent.</SPAN>
  232. </LI>
  233. <LI><SPAN ID="hue166">The TCP segments may arrive out of order which will
  234. complicate ordering of data to be sent.</SPAN>
  235. </LI>
  236. <LI><SPAN ID="hue168">Packets may be missing in the pcap file because
  237. they were dropped during capture.</SPAN>
  238. </LI>
  239. <LI><SPAN ID="hue170">There are tools like fragrouter which intentionally
  240. create non-deterministic situations.</SPAN>
  241. </LI>
  242. </OL>
  243. <SPAN ID="hue173">First off, I've decided, that I'm not going to worry
  244. about fragrouter or it's cousins. I'll handle non-deterministic situations
  245. one and only one way, so that the way flowreplay handles the traffic
  246. will be deterministic. Perhaps, I'll make it easy for others to write
  247. a plug-in which will change it, but that's not something I'm going
  248. to concern myself with now.</SPAN>
  249. <P>
  250. <SPAN ID="hue175">Missing packets in the pcap file will probably make
  251. that flow unplayable. There are proabably certain situation where
  252. we can make an educated guess, but this is far too complex to worry
  253. about for the first stable release.</SPAN>
  254. <P>
  255. <SPAN ID="hue177">That still leaves creating a basic TCP/IP stack
  256. in user space. The good news it that there is already a library which
  257. does this called libnids. As of version 1.17, libnids can process
  258. packets from a pcap savefile (it's not documented in the man page,
  259. but the code is there).</SPAN>
  260. <P>
  261. <SPAN ID="hue179">A potential problem with libnids though is that
  262. it has to maintain it's own state/cache system. This not only means
  263. additional overhead, but jumping around in the pcap file as I'm planning
  264. on doing to handle multiple simultaneous flows is likely to really
  265. confuse libnids' state engine. Also, libnids is licensed under the
  266. GPL, but I want flowreplay released under a BSD-like license; I need
  267. to research if the two are compatible in this way.</SPAN>
  268. <P>
  269. <SPAN ID="hue181">Possible solutions:</SPAN>
  270. <P>
  271. <UL>
  272. <LI><SPAN ID="hue184">Developing a custom wedge between the capture file
  273. and libnids which will cause each packet to only be processed a single
  274. time.</SPAN>
  275. </LI>
  276. <LI><SPAN ID="hue186">Use libnids to process the pcap file into a new
  277. flow-based format, effectively putting the TCP/IP stack into a dedicated
  278. utility.</SPAN>
  279. </LI>
  280. <LI><SPAN ID="hue188">Develop a custom user-space TCP/IP stack, perhaps
  281. based on a BSD TCP/IP stack, much like libnids is based on Linux 2.0.37.</SPAN>
  282. </LI>
  283. <LI><SPAN ID="hue190">Screw it and say that IP fragmentation and out of
  284. order IP packets/TCP segments are not supported. Not sure if this
  285. will meet the needs of potential users.</SPAN>
  286. </LI>
  287. </UL>
  288. <P>
  289. <H2><A NAME="SECTION00042000000000000000">
  290. <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> <SPAN ID="hue193">Blocking</SPAN></A>
  291. </H2>
  292. <P>
  293. <SPAN ID="hue195">As earlier stated, one of the main goals of this
  294. project is to keep things single threaded to make coding plugins easier.
  295. One caveat of that is that any function which blocks will cause serious
  296. problems.</SPAN>
  297. <P>
  298. <SPAN ID="hue197">There are three major cases where blocking is likely
  299. to occur:</SPAN>
  300. <P>
  301. <OL>
  302. <LI><SPAN ID="hue200">Opening a socket</SPAN>
  303. </LI>
  304. <LI><SPAN ID="hue202">Reading from a socket</SPAN>
  305. </LI>
  306. <LI><SPAN ID="hue204">Writing to a socket</SPAN>
  307. </LI>
  308. </OL>
  309. <SPAN ID="hue207">Reading from sockets in a non-blocking manner is
  310. easy to solve for using poll() or select(). Writing to a socket, or
  311. merely opening a TCP socket via connect() however requires a different
  312. method:</SPAN>
  313. <P>
  314. <BLOCKQUOTE>
  315. <SPAN ID="hue210">It is possible to do non-blocking IO on sockets
  316. by setting the O_NONBLOCK flag on a socket file descriptor using
  317. fcntl(2). Then all operations that would block will (usually) return
  318. with EAGAIN (operation should be retried later); connect(2) will return
  319. EINPROGRESS error. The user can then wait for various events via poll(2)
  320. or select(2).</SPAN><A NAME="tex2html7"
  321. HREF="#foot382"><SUP><SPAN CLASS="arabic">7</SPAN></SUP></A>
  322. </BLOCKQUOTE>
  323. <SPAN ID="hue215">If connect() returns EINPROGRESS, then we'll just
  324. have to do something like this:</SPAN>
  325. <P>
  326. <DL COMPACT>
  327. <DT>
  328. <DD><SPAN ID="hue218">int&nbsp;e,&nbsp;len=sizeof(e);</SPAN>
  329. <P>
  330. <SPAN ID="hue220">if&nbsp;(getsockopt(conn-&gt;s,&nbsp;SOL_SOCKET,&nbsp;SO_ERROR,&nbsp;&amp;e,&nbsp;&amp;len)&nbsp;&lt;&nbsp;0)&nbsp;{&nbsp;</SPAN>
  331. <P>
  332. &nbsp;<SPAN ID="hue383">&nbsp;&nbsp;&nbsp;/*&nbsp;not&nbsp;yet&nbsp;*/</SPAN>
  333. <P>
  334. &nbsp;<SPAN ID="hue384">&nbsp;&nbsp;&nbsp;if(errno&nbsp;!=&nbsp;EINPROGRESS){&nbsp;&nbsp;/*&nbsp;yuck.&nbsp;kill&nbsp;it.&nbsp;*/&nbsp;</SPAN>
  335. <P>
  336. &nbsp;<SPAN ID="hue385">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;log_fn(LOG_DEBUG,&#34;in-progress&nbsp;connect&nbsp;failed.&nbsp;Removing.&#34;);&nbsp;</SPAN>
  337. <P>
  338. &nbsp;<SPAN ID="hue231">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;-1;&nbsp;</SPAN>
  339. <P>
  340. &nbsp;<SPAN ID="hue233">&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{&nbsp;</SPAN>
  341. <P>
  342. &nbsp;<SPAN ID="hue386">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;0;&nbsp;/*&nbsp;no&nbsp;change,&nbsp;see&nbsp;if&nbsp;next&nbsp;time&nbsp;is&nbsp;better&nbsp;*/&nbsp;</SPAN>
  343. <P>
  344. &nbsp;<SPAN ID="hue238">&nbsp;&nbsp;&nbsp;}&nbsp;</SPAN>
  345. <P>
  346. <SPAN ID="hue240">}&nbsp;</SPAN>
  347. <P>
  348. <SPAN ID="hue387">/*&nbsp;the&nbsp;connect&nbsp;has&nbsp;finished.&nbsp;*/&nbsp;</SPAN>
  349. </DD>
  350. </DL><BLOCKQUOTE>
  351. <SPAN ID="hue247">Note: It may not be totally right, but it works
  352. ok. (that chunk of code gets called after poll returns the socket
  353. as writable. if poll returns it as readable, then it's probably because
  354. of eof, connect fails. You must poll for both.</SPAN>
  355. </BLOCKQUOTE>
  356. <P>
  357. <H1><A NAME="SECTION00050000000000000000">
  358. <SPAN CLASS="arabic">5</SPAN> <SPAN ID="hue250">pcap vs flow File Format</SPAN></A>
  359. </H1>
  360. <P>
  361. <SPAN ID="hue252">As stated before, the pcap file format really isn't
  362. well suited for flowreplay because it uses the raw packet as a container
  363. for data. Flowreplay however isn't interested in packets, it's interested
  364. in data streams</SPAN><A NAME="tex2html8"
  365. HREF="#foot404"><SUP><SPAN CLASS="arabic">8</SPAN></SUP></A> <SPAN ID="hue256">which may span one or more TCP/UDP segments, each
  366. comprised of an IP datagram which may be comprised of multiple IP
  367. fragments. Handling all this additional complexity requires a full
  368. TCP/IP stack in user space which would have additional feature requirements
  369. specific to flowreplay.</SPAN>
  370. <P>
  371. <SPAN ID="hue258">Rather then trying to do that, I've decided to create
  372. a pcap preprocessor for flowreplay called: flowprep. Flowprep will
  373. handle all the TCP/IP defragmentation/reassembly and write out a file
  374. containing the data streams for each flow.</SPAN>
  375. <P>
  376. <SPAN ID="hue260">A flow file will contain three sections:</SPAN>
  377. <P>
  378. <OL>
  379. <LI><SPAN ID="hue263">A header which identifies this as a flowprep file
  380. and the file version</SPAN>
  381. </LI>
  382. <LI><SPAN ID="hue265">An index of all the flows contained in the file</SPAN>
  383. </LI>
  384. <LI><SPAN ID="hue267">The data streams themselves</SPAN>
  385. </LI>
  386. </OL>
  387. <DIV ALIGN="CENTER">
  388. <SPAN ID="hue390"><IMG
  389. WIDTH="668" HEIGHT="748" ALIGN="BOTTOM" BORDER="0"
  390. SRC="img1.png"
  391. ALT="\includegraphics{flowheader.eps}"></SPAN>
  392. </DIV>
  393. <P>
  394. <SPAN ID="hue274">At startup, the file header is validated and the
  395. data stream indexes are loaded into memory. Then the first data stream
  396. header from each flow is read. Then each flow and subsequent data
  397. stream is processed based upon the timestamps and plug-ins.</SPAN>
  398. <P>
  399. <H1><A NAME="SECTION00060000000000000000">
  400. <SPAN CLASS="arabic">6</SPAN> <SPAN ID="hue276">Plug-ins</SPAN></A>
  401. </H1>
  402. <P>
  403. <SPAN ID="hue392">Plug-ins will provide the ``intelligence'' in
  404. flowreplay. Flowreplay is designed to be a mere framework for connecting
  405. captured flows in a flow file with socket file handles. How data is
  406. processed and what should be done with it will be done via plug-ins.</SPAN>
  407. <P>
  408. <SPAN ID="hue280">Plug-ins will allow proper handling of a variety
  409. of protocols while hopefully keeping things simple. Another part of
  410. the consideration will be making it easy for others to contribute
  411. to flowreplay. I don't want to have to write all the protocol logic
  412. myself.</SPAN>
  413. <P>
  414. <H2><A NAME="SECTION00061000000000000000">
  415. <SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">1</SPAN> <SPAN ID="hue282">Plug-in Basics</SPAN></A>
  416. </H2>
  417. <P>
  418. <SPAN ID="hue284">Each plug-in provides the logic for handling one
  419. or more services. The main purpose of a plug-in is to decide when
  420. flowreplay should send data via one or more sockets. The plug-in can
  421. use any</SPAN> <SPAN ID="hue394"><SPAN CLASS="textit">non-blocking</SPAN></SPAN> <SPAN ID="hue288">method
  422. of determining if it appropriate to send data or wait for data to
  423. received. If necessary, a plug-in can also modify the data sent.</SPAN>
  424. <P>
  425. <SPAN ID="hue290">Each time poll() returns, flowreplay calls the plug-ins
  426. for the flows which either have data waiting or in the case of a timeout,
  427. those flows which timed out. Afterwords, all the flows are processed
  428. and poll() is called on those flows which have their state set to
  429. POLL. And the process repeats until there are no more nodes in the
  430. tree.</SPAN>
  431. <P>
  432. <H2><A NAME="SECTION00062000000000000000">
  433. <SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">2</SPAN> <SPAN ID="hue292">The Default Plug-in</SPAN></A>
  434. </H2>
  435. <P>
  436. <SPAN ID="hue396">Initially, flowreplay will ship with one basic plug-in
  437. called ``default''. Any flow which doesn't have a specific plug-in
  438. defined, will use default. The goal of the default plug-in is to work
  439. ``good enough'' for a majority of single-flow protocols such as
  440. SMTP, HTTP, and Telnet. Protocols which use encryption (SSL, SSH,
  441. etc) or multiple flows (FTP, RPC, etc) will never work with the default
  442. plug-in. Furthermore, the default plug-in will only support connections</SPAN><SPAN ID="hue397"><SPAN CLASS="textit">to</SPAN></SPAN> <SPAN ID="hue299">a server, it will not
  443. support accepting connections from clients.</SPAN>
  444. <P>
  445. <SPAN ID="hue398">The default plug-in will provide no data level manipulation
  446. and only a simple method for detecting when it is time to send data
  447. to the server. Detecting when to send data will be done by a ``no
  448. more data'' timeout value. Basically, by using the pcap file as a
  449. means to determine the order of the exchange, anytime it is the servers
  450. turn to send data, flowreplay will wait for the first byte of data
  451. and then start the ``no more data'' timer. Every time more data
  452. is received, the timer is reset. If the timer reaches zero, then flowreplay
  453. sends the next portion of the client side of the connection. This
  454. is repeated until the the flow has been completely replayed or a ``server
  455. hung'' timeout is reached. The server hung timeout is used to detect
  456. a server which crashed and never starts sending any data which would
  457. start the ``no more data'' timer.</SPAN>
  458. <P>
  459. <SPAN ID="hue399">Both the ``no more data'' and ``server hung''
  460. timers will be user defined values and global to all flows using the
  461. default plug-in.</SPAN>
  462. <P>
  463. <H2><A NAME="SECTION00063000000000000000">
  464. <SPAN CLASS="arabic">6</SPAN>.<SPAN CLASS="arabic">3</SPAN> <SPAN ID="hue309">Plug-in Details</SPAN></A>
  465. </H2>
  466. <P>
  467. <SPAN ID="hue311">Each plug-in will be comprised of the following:</SPAN>
  468. <P>
  469. <OL>
  470. <LI><SPAN ID="hue314">An optional global data structure, for intra-flow
  471. communication</SPAN>
  472. </LI>
  473. <LI><SPAN ID="hue316">Per-flow data structure, for tracking flow state
  474. information</SPAN>
  475. </LI>
  476. <LI><SPAN ID="hue318">A list of functions which flow replay will call
  477. when certain well-defined conditions are met.</SPAN>
  478. <P>
  479. <UL>
  480. <LI><SPAN ID="hue321">Required functions:</SPAN>
  481. <P>
  482. <UL>
  483. <LI><SPAN ID="hue324">initialize_node() - called when a node in the tree
  484. created using this plug-in</SPAN>
  485. </LI>
  486. <LI><SPAN ID="hue326">post_poll_timeout() - called when the poll() returned
  487. due to a timeout for this node</SPAN>
  488. </LI>
  489. <LI><SPAN ID="hue328">post_poll_read() - called when the poll() returned
  490. due to the socket being ready</SPAN>
  491. </LI>
  492. <LI><SPAN ID="hue330">buffer_full() - called when a the packet buffer
  493. for this flow is full</SPAN>
  494. </LI>
  495. <LI><SPAN ID="hue332">delete_node() - called just prior to the node being
  496. free()'d</SPAN>
  497. </LI>
  498. </UL>
  499. </LI>
  500. <LI><SPAN ID="hue335">Optional functions:</SPAN>
  501. <P>
  502. <UL>
  503. <LI><SPAN ID="hue338">pre_send_data() - called before data is sent</SPAN>
  504. </LI>
  505. <LI><SPAN ID="hue340">post_send_data() - called after data is sent</SPAN>
  506. </LI>
  507. <LI><SPAN ID="hue342">pre_poll() - called prior to poll()</SPAN>
  508. </LI>
  509. <LI><SPAN ID="hue344">post_poll_default() - called when poll() returns
  510. and neither the socket was ready or the node timed out </SPAN>
  511. </LI>
  512. <LI><SPAN ID="hue346">open_socket() - called after the socket is opened</SPAN>
  513. </LI>
  514. <LI><SPAN ID="hue348">close_socket() - called after the socket is closed</SPAN>
  515. </LI>
  516. </UL>
  517. </LI>
  518. </UL>
  519. </LI>
  520. </OL>
  521. <DL COMPACT>
  522. <DT>
  523. <DD><P>
  524. </DD>
  525. </DL>
  526. <P>
  527. <H1><A NAME="SECTION00070000000000000000">
  528. About this document ...</A>
  529. </H1>
  530. <STRONG><SPAN ID="hue33">Flowreplay Design Notes</SPAN></STRONG><P>
  531. This document was generated using the
  532. <A HREF="http://www.latex2html.org/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 2002-2-1 (1.70)
  533. <P>
  534. Copyright &#169; 1993, 1994, 1995, 1996,
  535. <A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>,
  536. Computer Based Learning Unit, University of Leeds.
  537. <BR>
  538. Copyright &#169; 1997, 1998, 1999,
  539. <A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>,
  540. Mathematics Department, Macquarie University, Sydney.
  541. <P>
  542. The command line arguments were: <BR>
  543. <STRONG>latex2html</STRONG> <TT>-nonavigation -no_subdir -split 0 -show_section_numbers flowreplay.tex</TT>
  544. <P>
  545. The translation was initiated by Aaron Turner on 2005-02-10
  546. <BR><HR><H4>Footnotes</H4>
  547. <DL>
  548. <DT><A NAME="foot362">...Tcpreplay</A><A
  549. HREF="flowreplay.html#tex2html1"><SUP><SPAN CLASS="arabic">1</SPAN></SUP></A></DT>
  550. <DD><SPAN ID="hue47">http://tcpreplay.sourceforge.net/</SPAN>
  551. </DD>
  552. <DT><A NAME="foot370">...&nbsp;</A><A
  553. HREF="flowreplay.html#tex2html2"><SUP><SPAN CLASS="arabic">2</SPAN></SUP></A></DT>
  554. <DD><SPAN ID="hue102">socket(2)</SPAN>
  555. </DD>
  556. <DT><A NAME="foot371">...&nbsp;</A><A
  557. HREF="flowreplay.html#tex2html3"><SUP><SPAN CLASS="arabic">3</SPAN></SUP></A></DT>
  558. <DD><SPAN ID="hue108">http://www.tcpdump.org/</SPAN>
  559. </DD>
  560. <DT><A NAME="foot372">...&nbsp;</A><A
  561. HREF="flowreplay.html#tex2html4"><SUP><SPAN CLASS="arabic">4</SPAN></SUP></A></DT>
  562. <DD><SPAN ID="hue112">http://www.packetfactory.net/projects/libnet/</SPAN>
  563. </DD>
  564. <DT><A NAME="foot124">...&nbsp;</A><A
  565. HREF="flowreplay.html#tex2html5"><SUP><SPAN CLASS="arabic">5</SPAN></SUP></A></DT>
  566. <DD>http://netdude.sourceforge.net/
  567. </DD>
  568. <DT><A NAME="foot403">...&nbsp;</A><A
  569. HREF="flowreplay.html#tex2html6"><SUP><SPAN CLASS="arabic">6</SPAN></SUP></A></DT>
  570. <DD><SPAN ID="hue377">http://www.avet.com.pl/~nergal/libnids/</SPAN>
  571. </DD>
  572. <DT><A NAME="foot382">...&nbsp;</A><A
  573. HREF="flowreplay.html#tex2html7"><SUP><SPAN CLASS="arabic">7</SPAN></SUP></A></DT>
  574. <DD><SPAN ID="hue212">socket(7)</SPAN>
  575. </DD>
  576. <DT><A NAME="foot404">...&nbsp;</A><A
  577. HREF="flowreplay.html#tex2html8"><SUP><SPAN CLASS="arabic">8</SPAN></SUP></A></DT>
  578. <DD><SPAN ID="hue389">A ``data stream'' as I call it is a simplex
  579. communication from the client or server which is a complete query,
  580. response or message.</SPAN>
  581. </DD>
  582. </DL>
  583. <BR><HR>
  584. <ADDRESS>
  585. Aaron Turner
  586. 2005-02-10
  587. </ADDRESS>
  588. </BODY>
  589. </HTML>