flowreplay.lyx 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125
  1. #LyX 1.3 created this file. For more info see http://www.lyx.org/
  2. \lyxformat 221
  3. \textclass article
  4. \language english
  5. \inputencoding latin1
  6. \fontscheme pslatex
  7. \graphics default
  8. \paperfontsize default
  9. \spacing single
  10. \papersize letterpaper
  11. \paperpackage a4
  12. \use_geometry 1
  13. \use_amsmath 0
  14. \use_natbib 0
  15. \use_numerical_citations 0
  16. \paperorientation portrait
  17. \leftmargin 10mm
  18. \topmargin 10mm
  19. \rightmargin 10mm
  20. \bottommargin 15mm
  21. \secnumdepth 4
  22. \tocdepth 3
  23. \paragraph_separation skip
  24. \defskip medskip
  25. \quotes_language english
  26. \quotes_times 2
  27. \papercolumns 1
  28. \papersides 1
  29. \paperpagestyle default
  30. \bullet 1
  31. 0
  32. 6
  33. -1
  34. \end_bullet
  35. \bullet 2
  36. 0
  37. 0
  38. -1
  39. \end_bullet
  40. \layout Title
  41. \color black
  42. Flowreplay Design Notes
  43. \layout Author
  44. \color black
  45. Aaron Turner
  46. \newline
  47. http://synfin.net/
  48. \layout Date
  49. \color black
  50. Last Edited:
  51. \newline
  52. October 23, 2003
  53. \layout Section
  54. \pagebreak_top
  55. \color black
  56. Overview
  57. \layout Standard
  58. \color black
  59. Tcpreplay
  60. \begin_inset Foot
  61. collapsed true
  62. \layout Standard
  63. \color black
  64. http://tcpreplay.sourceforge.net/
  65. \end_inset
  66. was designed to replay traffic previously captured in the pcap format back
  67. onto the wire for testing NIDS and other passive devices.
  68. Over time, it was enhanced to be able to test in-line network devices.
  69. However, a re-occurring feature request for tcpreplay is to connect to
  70. a server in order to test applications and host TCP/IP stacks.
  71. It was determined early on, that adding this feature to tcpreplay was far
  72. too complex, so I decided to create a new tool specifically designed for
  73. this.
  74. \layout Standard
  75. \color black
  76. Flowreplay is designed to replay traffic at Layer 4 or 7 depending on the
  77. protocol rather then at Layer 2 like tcpreplay does.
  78. This allows flowreplay to connect to one or more servers using a pcap savefile
  79. as the basis of the connections.
  80. Hence, flowreplay allows the testing of applications running on real servers
  81. rather then passive devices.
  82. \layout Section
  83. \color black
  84. Features
  85. \layout Subsection
  86. \color black
  87. Requirements
  88. \layout Enumerate
  89. \color black
  90. Full TCP/IP support, including IP fragments and TCP stream reassembly.
  91. \layout Enumerate
  92. \color black
  93. Support replaying TCP and UDP flows.
  94. \layout Enumerate
  95. \color black
  96. Code should handle each flow/service independently.
  97. \layout Enumerate
  98. \color black
  99. Should be able to connect to the server(s) in the pcap file or to a user
  100. specified IP address.
  101. \layout Enumerate
  102. \color black
  103. Support a plug-in architecture to allow adding application layer intelligence.
  104. \layout Enumerate
  105. \color black
  106. Plug-ins must be able to support multi-flow protocols like FTP.
  107. \layout Enumerate
  108. \color black
  109. Ship with a default plug-in which will work
  110. \begin_inset Quotes eld
  111. \end_inset
  112. well enough
  113. \begin_inset Quotes erd
  114. \end_inset
  115. for simple single-flow protocols like HTTP and telnet.
  116. \layout Enumerate
  117. \color black
  118. Flows being replayed
  119. \begin_inset Quotes eld
  120. \end_inset
  121. correctly
  122. \begin_inset Quotes erd
  123. \end_inset
  124. is more important then performance (Mbps).
  125. \layout Enumerate
  126. \color black
  127. Portable to run on common flavors of Unix and Unix-like systems.
  128. \layout Subsection
  129. \color black
  130. Wishes
  131. \layout Enumerate
  132. \color black
  133. Support clients connecting to flowreplay on a limited basis.
  134. Flowreplay would replay the server side of the connection.
  135. \layout Enumerate
  136. \color black
  137. Support other IP based traffic (ICMP, VRRP, OSPF, etc) via plug-ins.
  138. \layout Enumerate
  139. \color black
  140. Support non-IP traffic (ARP, STP, CDP, etc) via plug-ins.
  141. \layout Enumerate
  142. \color black
  143. Limit which flows are replayed using user defined filters.
  144. (bpf filter syntax?)
  145. \layout Enumerate
  146. \color black
  147. Process pcap files directly with no intermediary file conversions.
  148. \layout Enumerate
  149. \color black
  150. Should be able to scale to pcap files in the 100's of MB in size and 100+
  151. simultaneous flows on a P3 500MHz w/ 256MB of RAM.
  152. \layout Section
  153. \color black
  154. Design Thoughts
  155. \layout Subsection
  156. \color black
  157. Sending and Receiving traffic
  158. \layout Standard
  159. \color black
  160. Flowreplay must be able to process multiple connections to one or more devices.
  161. There are two options:
  162. \layout Enumerate
  163. \color black
  164. Use sockets
  165. \begin_inset Foot
  166. collapsed true
  167. \layout Standard
  168. \color black
  169. socket(2)
  170. \end_inset
  171. to send and receive data
  172. \layout Enumerate
  173. \color black
  174. Use libpcap
  175. \begin_inset Foot
  176. collapsed true
  177. \layout Standard
  178. \color black
  179. http://www.tcpdump.org/
  180. \end_inset
  181. to receive packets and libnet
  182. \begin_inset Foot
  183. collapsed true
  184. \layout Standard
  185. \color black
  186. http://www.packetfactory.net/projects/libnet/
  187. \end_inset
  188. to send packets
  189. \layout Standard
  190. \color black
  191. Although using libpcap/libnet would allow more simultaneous connections
  192. and greater flexibility, there would be a very high complexity cost associated
  193. with it.
  194. With that in mind, I've decided to use sockets to send and receive data.
  195. \layout Subsection
  196. \color black
  197. Handling Multiple Connections
  198. \layout Standard
  199. \color black
  200. Because a pcap file can contain multiple simultaneous flows, we need to
  201. be able to support that too.
  202. The biggest problem with this is reading packet data in a different order
  203. then stored in the pcap file.
  204. \layout Standard
  205. \color black
  206. Reading and writing to multiple sockets is easy with select() or poll(),
  207. however a pcap file has it's data stored serially, but we need to access
  208. it randomly.
  209. There are a number of possible solutions for this such as caching packets
  210. in RAM where they can be accessed more randomly, creating an index of the
  211. packets in the pcap file, or converting the pcap file to another format
  212. altogether.
  213. Alternatively, I've started looking at libpcapnav
  214. \begin_inset Foot
  215. collapsed true
  216. \layout Standard
  217. http://netdude.sourceforge.net/
  218. \end_inset
  219. as an alternate means to navigate a pcap file and process packets out of
  220. order.
  221. \layout Subsection
  222. \color black
  223. Data Synchronization
  224. \layout Standard
  225. \color black
  226. Knowing when to start sending client traffic in response to the server will
  227. be "tricky".
  228. Without understanding the actual protocol involved, probably the best general
  229. solution is waiting for a given period of time after no more data from
  230. the server has been received.
  231. Not sure what to do if the client traffic doesn't elicit a response from
  232. the server (implement some kind of timeout?).
  233. This will be the basis for the default plug-in.
  234. \layout Subsection
  235. \color black
  236. TCP/IP
  237. \layout Standard
  238. \color black
  239. Dealing with IP fragmentation and TCP stream reassembly will be another
  240. really complex problem.
  241. We're basically talking about implementing a significant portion of a TCP/IP
  242. stack.
  243. One thought is to use libnids
  244. \begin_inset Foot
  245. collapsed true
  246. \layout Standard
  247. \color black
  248. http://www.avet.com.pl/~nergal/libnids/
  249. \end_inset
  250. which basically implements a Linux 2.0.37 TCP/IP stack in user-space.
  251. Other solutions include porting a TCP/IP stack from Open/Net/FreeBSD or
  252. writing our own custom stack from scratch.
  253. \layout Section
  254. \color black
  255. Multiple Independent Flows
  256. \layout Standard
  257. \color black
  258. The biggest asynchronous problem, that pcap files are serial, has to be
  259. solved in a scaleable manner.
  260. Not much can be assumed about the network traffic contained in a pcap savefile
  261. other then Murphy's Law will be in effect.
  262. This means we'll have to deal with:
  263. \layout Itemize
  264. \color black
  265. Thousands of small simultaneous flows (captured on a busy network)
  266. \layout Itemize
  267. \color black
  268. Flows which
  269. \begin_inset Quotes eld
  270. \end_inset
  271. hang
  272. \begin_inset Quotes erd
  273. \end_inset
  274. mid-stream (an exploit against a server causes it to crash)
  275. \layout Itemize
  276. \color black
  277. Flows which contain large quantities of data (FTP transfers of ISO's for
  278. example)
  279. \layout Standard
  280. \color black
  281. How we implement parallel processing of the pcap savefile will dramatically
  282. effect how well we can scale.
  283. A few considerations:
  284. \layout Itemize
  285. Most Unix systems limit the maximum number of open file descriptors a single
  286. process can have.
  287. Generally speaking this shouldn't be a problem except for highly parallel
  288. pcap's.
  289. \layout Itemize
  290. While RAM isn't limitless, we can use mmap() to get around this.
  291. \layout Itemize
  292. Many Unix systems have enhanced solutions to poll() which will improve flow
  293. management.
  294. \layout Comment
  295. \color black
  296. Unix systems implement a maximum limit on the number of file descriptors
  297. a single process can open.
  298. My Linux box for example craps out at 1021 (it's really 1024, but 3 are
  299. reserved for STDIN, STDOUT, STDERR), which seems to be pretty standard
  300. for recent Unix's.
  301. This means we're limited to at most 1020 simultaneous flows if the pcap
  302. savefile is opened once and half that (510 flows) if the savefile is re-opened
  303. for each flow.
  304. \begin_inset Foot
  305. collapsed true
  306. \layout Standard
  307. \color black
  308. It appears that most Unix-like OS's allow root to increase the
  309. \begin_inset Quotes eld
  310. \end_inset
  311. hard-limit
  312. \begin_inset Quotes erd
  313. \end_inset
  314. beyond 1024.
  315. Compiling a list of methods to do this for common OS's should be added
  316. to the flowreplay documentation.
  317. \end_inset
  318. \layout Comment
  319. \color black
  320. RAM isn't limitless.
  321. Caching packets in memory may cause problems when one or more flows with
  322. a lot of data
  323. \begin_inset Quotes eld
  324. \end_inset
  325. hang
  326. \begin_inset Quotes erd
  327. \end_inset
  328. and their packets have to be cached so that other flows can be processed.
  329. If you work with large pcaps containing malicious traffic (say packet captures
  330. from DefCon), this sort of thing may be a real problem.
  331. Dealing with this situation would require complicated buffer limits and
  332. error handling.
  333. \layout Comment
  334. \color black
  335. Jumping around in the pcap file via fgetpos() and fsetpos() is probably
  336. the most disk I/O intensive solution and may effect performance.
  337. However, on systems with enough free memory, one would hope the system
  338. disk cache will provide a dramatic speedup.
  339. The
  340. \begin_inset Quotes eld
  341. \end_inset
  342. bookmarks
  343. \begin_inset Quotes erd
  344. \end_inset
  345. used by fgetpos/fsetpos are just 64 bit integers which are relatively space
  346. efficent compared to other solutions.
  347. \layout Comment
  348. \color black
  349. The other typical asynchronous issue is dealing with multiple sockets, which
  350. we will solve via poll()
  351. \begin_inset Foot
  352. collapsed true
  353. \layout Standard
  354. \color black
  355. poll(2)
  356. \end_inset
  357. .
  358. Each flow will define a
  359. \emph on
  360. struct pollfd
  361. \emph default
  362. and the amount of time in ms to timeout.
  363. Then prior to calling poll() we walk the list of flows and create the array
  364. of pollfd's and determine the flow(s) with the smallest timeout.
  365. A list of these flows is saved for when poll() returns.
  366. Finally, the current time is tucked away and the timeout and array of pollfd's
  367. is passed to poll().
  368. \layout Comment
  369. \color black
  370. When poll() returns, the sockets that returned ready have their plug-in
  371. called.
  372. If no sockets are ready, then the flows saved prior to calling poll() are
  373. processed.
  374. \layout Comment
  375. \color black
  376. Once all flows are processed, all the flows not processed have their timeout
  377. decremented by the time difference of the current time and when poll was
  378. last called and we start again.
  379. \layout Subsection
  380. \color black
  381. IP Fragments and TCP Streams
  382. \layout Standard
  383. \color black
  384. There are five major complications with flowreplay:
  385. \layout Enumerate
  386. \color black
  387. The IP datagrams may be fragmented- we won't be able to use the standard
  388. 5-tuple (src/dst IP, src/dst port, protocol) to lookup which flow a packet
  389. belongs to.
  390. \layout Enumerate
  391. \color black
  392. IP fragments may arrive out of order which will complicate ordering of data
  393. to be sent.
  394. \layout Enumerate
  395. \color black
  396. The TCP segments may arrive out of order which will complicate ordering
  397. of data to be sent.
  398. \layout Enumerate
  399. \color black
  400. Packets may be missing in the pcap file because they were dropped during
  401. capture.
  402. \layout Enumerate
  403. \color black
  404. There are tools like fragrouter which intentionally create non-deterministic
  405. situations.
  406. \layout Standard
  407. \color black
  408. First off, I've decided, that I'm not going to worry about fragrouter or
  409. it's cousins.
  410. I'll handle non-deterministic situations one and only one way, so that
  411. the way flowreplay handles the traffic will be deterministic.
  412. Perhaps, I'll make it easy for others to write a plug-in which will change
  413. it, but that's not something I'm going to concern myself with now.
  414. \layout Standard
  415. \color black
  416. Missing packets in the pcap file will probably make that flow unplayable.
  417. There are proabably certain situation where we can make an educated guess,
  418. but this is far too complex to worry about for the first stable release.
  419. \layout Standard
  420. \color black
  421. That still leaves creating a basic TCP/IP stack in user space.
  422. The good news it that there is already a library which does this called
  423. libnids.
  424. As of version 1.17, libnids can process packets from a pcap savefile (it's
  425. not documented in the man page, but the code is there).
  426. \layout Standard
  427. \color black
  428. A potential problem with libnids though is that it has to maintain it's
  429. own state/cache system.
  430. This not only means additional overhead, but jumping around in the pcap
  431. file as I'm planning on doing to handle multiple simultaneous flows is
  432. likely to really confuse libnids' state engine.
  433. Also, libnids is licensed under the GPL, but I want flowreplay released
  434. under a BSD-like license; I need to research if the two are compatible
  435. in this way.
  436. \layout Standard
  437. \color black
  438. Possible solutions:
  439. \layout Itemize
  440. \color black
  441. Developing a custom wedge between the capture file and libnids which will
  442. cause each packet to only be processed a single time.
  443. \layout Itemize
  444. \color black
  445. Use libnids to process the pcap file into a new flow-based format, effectively
  446. putting the TCP/IP stack into a dedicated utility.
  447. \layout Itemize
  448. \color black
  449. Develop a custom user-space TCP/IP stack, perhaps based on a BSD TCP/IP
  450. stack, much like libnids is based on Linux 2.0.37.
  451. \layout Itemize
  452. \color black
  453. Screw it and say that IP fragmentation and out of order IP packets/TCP segments
  454. are not supported.
  455. Not sure if this will meet the needs of potential users.
  456. \layout Subsection
  457. \color black
  458. Blocking
  459. \layout Standard
  460. \color black
  461. As earlier stated, one of the main goals of this project is to keep things
  462. single threaded to make coding plugins easier.
  463. One caveat of that is that any function which blocks will cause serious
  464. problems.
  465. \layout Standard
  466. \color black
  467. There are three major cases where blocking is likely to occur:
  468. \layout Enumerate
  469. \color black
  470. Opening a socket
  471. \layout Enumerate
  472. \color black
  473. Reading from a socket
  474. \layout Enumerate
  475. \color black
  476. Writing to a socket
  477. \layout Standard
  478. \color black
  479. Reading from sockets in a non-blocking manner is easy to solve for using
  480. poll() or select().
  481. Writing to a socket, or merely opening a TCP socket via connect() however
  482. requires a different method:
  483. \layout Quotation
  484. \color black
  485. It is possible to do non-blocking IO on sockets by setting the O_NONBLOCK
  486. flag on a socket file descriptor using fcntl(2).
  487. Then all operations that would block will (usually) return with EAGAIN
  488. (operation should be retried later); connect(2) will return EINPROGRESS
  489. error.
  490. The user can then wait for various events via poll(2) or select(2).
  491. \begin_inset Foot
  492. collapsed true
  493. \layout Standard
  494. \color black
  495. socket(7)
  496. \end_inset
  497. \layout Standard
  498. \color black
  499. If connect() returns EINPROGRESS, then we'll just have to do something like
  500. this:
  501. \layout LyX-Code
  502. \color black
  503. int e, len=sizeof(e);
  504. \layout LyX-Code
  505. \color black
  506. if (getsockopt(conn->s, SOL_SOCKET, SO_ERROR, &e, &len) < 0) {
  507. \layout LyX-Code
  508. \color black
  509. /* not yet */
  510. \layout LyX-Code
  511. \color black
  512. if(errno != EINPROGRESS){ /* yuck.
  513. kill it.
  514. */
  515. \layout LyX-Code
  516. \color black
  517. log_fn(LOG_DEBUG,"in-progress connect failed.
  518. Removing.");
  519. \layout LyX-Code
  520. \color black
  521. return -1;
  522. \layout LyX-Code
  523. \color black
  524. } else {
  525. \layout LyX-Code
  526. \color black
  527. return 0; /* no change, see if next time is better */
  528. \layout LyX-Code
  529. \color black
  530. }
  531. \layout LyX-Code
  532. \color black
  533. }
  534. \layout LyX-Code
  535. \color black
  536. /* the connect has finished.
  537. */
  538. \layout Quote
  539. \color black
  540. Note: It may not be totally right, but it works ok.
  541. (that chunk of code gets called after poll returns the socket as writable.
  542. if poll returns it as readable, then it's probably because of eof, connect
  543. fails.
  544. You must poll for both.
  545. \layout Section
  546. \color black
  547. pcap vs flow File Format
  548. \layout Standard
  549. \color black
  550. As stated before, the pcap file format really isn't well suited for flowreplay
  551. because it uses the raw packet as a container for data.
  552. Flowreplay however isn't interested in packets, it's interested in data
  553. streams
  554. \begin_inset Foot
  555. collapsed true
  556. \layout Standard
  557. \color black
  558. A
  559. \begin_inset Quotes eld
  560. \end_inset
  561. data stream
  562. \begin_inset Quotes erd
  563. \end_inset
  564. as I call it is a simplex communication from the client or server which
  565. is a complete query, response or message.
  566. \end_inset
  567. which may span one or more TCP/UDP segments, each comprised of an IP datagram
  568. which may be comprised of multiple IP fragments.
  569. Handling all this additional complexity requires a full TCP/IP stack in
  570. user space which would have additional feature requirements specific to
  571. flowreplay.
  572. \layout Standard
  573. \color black
  574. Rather then trying to do that, I've decided to create a pcap preprocessor
  575. for flowreplay called: flowprep.
  576. Flowprep will handle all the TCP/IP defragmentation/reassembly and write
  577. out a file containing the data streams for each flow.
  578. \layout Standard
  579. \color black
  580. A flow file will contain three sections:
  581. \layout Enumerate
  582. \color black
  583. A header which identifies this as a flowprep file and the file version
  584. \layout Enumerate
  585. \color black
  586. An index of all the flows contained in the file
  587. \layout Enumerate
  588. \color black
  589. The data streams themselves
  590. \layout Standard
  591. \align center
  592. \color black
  593. \begin_inset Graphics
  594. filename flowheader.eps
  595. \end_inset
  596. \layout Standard
  597. \color black
  598. At startup, the file header is validated and the data stream indexes are
  599. loaded into memory.
  600. Then the first data stream header from each flow is read.
  601. Then each flow and subsequent data stream is processed based upon the timestamp
  602. s and plug-ins.
  603. \layout Section
  604. \color black
  605. Plug-ins
  606. \layout Standard
  607. \color black
  608. Plug-ins will provide the
  609. \begin_inset Quotes eld
  610. \end_inset
  611. intelligence
  612. \begin_inset Quotes erd
  613. \end_inset
  614. in flowreplay.
  615. Flowreplay is designed to be a mere framework for connecting captured flows
  616. in a flow file with socket file handles.
  617. How data is processed and what should be done with it will be done via
  618. plug-ins.
  619. \layout Standard
  620. \color black
  621. Plug-ins will allow proper handling of a variety of protocols while hopefully
  622. keeping things simple.
  623. Another part of the consideration will be making it easy for others to
  624. contribute to flowreplay.
  625. I don't want to have to write all the protocol logic myself.
  626. \layout Subsection
  627. \color black
  628. Plug-in Basics
  629. \layout Standard
  630. \color black
  631. Each plug-in provides the logic for handling one or more services.
  632. The main purpose of a plug-in is to decide when flowreplay should send
  633. data via one or more sockets.
  634. The plug-in can use any
  635. \emph on
  636. non-blocking
  637. \emph default
  638. method of determining if it appropriate to send data or wait for data to
  639. received.
  640. If necessary, a plug-in can also modify the data sent.
  641. \layout Standard
  642. \color black
  643. Each time poll() returns, flowreplay calls the plug-ins for the flows which
  644. either have data waiting or in the case of a timeout, those flows which
  645. timed out.
  646. Afterwords, all the flows are processed and poll() is called on those flows
  647. which have their state set to POLL.
  648. And the process repeats until there are no more nodes in the tree.
  649. \layout Subsection
  650. \color black
  651. The Default Plug-in
  652. \layout Standard
  653. \color black
  654. Initially, flowreplay will ship with one basic plug-in called
  655. \begin_inset Quotes eld
  656. \end_inset
  657. default
  658. \begin_inset Quotes erd
  659. \end_inset
  660. .
  661. Any flow which doesn't have a specific plug-in defined, will use default.
  662. The goal of the default plug-in is to work
  663. \begin_inset Quotes eld
  664. \end_inset
  665. good enough
  666. \begin_inset Quotes erd
  667. \end_inset
  668. for a majority of single-flow protocols such as SMTP, HTTP, and Telnet.
  669. Protocols which use encryption (SSL, SSH, etc) or multiple flows (FTP,
  670. RPC, etc) will never work with the default plug-in.
  671. Furthermore, the default plug-in will only support connections
  672. \emph on
  673. to
  674. \emph default
  675. a server, it will not support accepting connections from clients.
  676. \layout Standard
  677. \color black
  678. The default plug-in will provide no data level manipulation and only a simple
  679. method for detecting when it is time to send data to the server.
  680. Detecting when to send data will be done by a
  681. \begin_inset Quotes eld
  682. \end_inset
  683. no more data
  684. \begin_inset Quotes erd
  685. \end_inset
  686. timeout value.
  687. Basically, by using the pcap file as a means to determine the order of
  688. the exchange, anytime it is the servers turn to send data, flowreplay will
  689. wait for the first byte of data and then start the
  690. \begin_inset Quotes eld
  691. \end_inset
  692. no more data
  693. \begin_inset Quotes erd
  694. \end_inset
  695. timer.
  696. Every time more data is received, the timer is reset.
  697. If the timer reaches zero, then flowreplay sends the next portion of the
  698. client side of the connection.
  699. This is repeated until the the flow has been completely replayed or a
  700. \begin_inset Quotes eld
  701. \end_inset
  702. server hung
  703. \begin_inset Quotes erd
  704. \end_inset
  705. timeout is reached.
  706. The server hung timeout is used to detect a server which crashed and never
  707. starts sending any data which would start the
  708. \begin_inset Quotes eld
  709. \end_inset
  710. no more data
  711. \begin_inset Quotes erd
  712. \end_inset
  713. timer.
  714. \layout Standard
  715. \color black
  716. Both the
  717. \begin_inset Quotes eld
  718. \end_inset
  719. no more data
  720. \begin_inset Quotes erd
  721. \end_inset
  722. and
  723. \begin_inset Quotes eld
  724. \end_inset
  725. server hung
  726. \begin_inset Quotes erd
  727. \end_inset
  728. timers will be user defined values and global to all flows using the default
  729. plug-in.
  730. \layout Subsection
  731. \color black
  732. Plug-in Details
  733. \layout Standard
  734. \color black
  735. Each plug-in will be comprised of the following:
  736. \layout Enumerate
  737. \color black
  738. An optional global data structure, for intra-flow communication
  739. \layout Enumerate
  740. \color black
  741. Per-flow data structure, for tracking flow state information
  742. \layout Enumerate
  743. \color black
  744. A list of functions which flow replay will call when certain well-defined
  745. conditions are met.
  746. \begin_deeper
  747. \layout Itemize
  748. \color black
  749. Required functions:
  750. \begin_deeper
  751. \layout Itemize
  752. \color black
  753. initialize_node() - called when a node in the tree created using this plug-in
  754. \layout Itemize
  755. \color black
  756. post_poll_timeout() - called when the poll() returned due to a timeout for
  757. this node
  758. \layout Itemize
  759. \color black
  760. post_poll_read() - called when the poll() returned due to the socket being
  761. ready
  762. \layout Itemize
  763. \color black
  764. buffer_full() - called when a the packet buffer for this flow is full
  765. \layout Itemize
  766. \color black
  767. delete_node() - called just prior to the node being free()'d
  768. \end_deeper
  769. \layout Itemize
  770. \color black
  771. Optional functions:
  772. \begin_deeper
  773. \layout Itemize
  774. \color black
  775. pre_send_data() - called before data is sent
  776. \layout Itemize
  777. \color black
  778. post_send_data() - called after data is sent
  779. \layout Itemize
  780. \color black
  781. pre_poll() - called prior to poll()
  782. \layout Itemize
  783. \color black
  784. post_poll_default() - called when poll() returns and neither the socket
  785. was ready or the node timed out
  786. \layout Itemize
  787. \color black
  788. open_socket() - called after the socket is opened
  789. \layout Itemize
  790. \color black
  791. close_socket() - called after the socket is closed
  792. \end_deeper
  793. \end_deeper
  794. \layout LyX-Code
  795. \layout LyX-Code
  796. \the_end