1. $Id: HACKING 1470 2006-06-09 06:50:42Z aturner $
  2. Guide to Hacking Tcpreplay
  3. [Note: Pay attention to the last update date at the top of this file. If it
  4. was significantly long ago, this document may be out of date.]
  5. 0. Contributing Code
  6. If you contribute code the following will happen:
  7. a) You will be given credit in the CREDITS file
  8. b) Your code will be licensed under the same license as that of tcpreplay
  9. c) You will be assigning your copyright to me
  10. If you have any questions regarding any of the three above stipulations,
  11. feel free to email the list at: tcpreplay-users@lists.sourceforge.net
  12. 1. Introduction
  13. If you're reading this to find out how to add a new feature or fix a bug in
  14. tcpreplay or tcpprep, then you've come to the right place. This isn't the
  15. place to find answers regarding how to use tcpreplay, the meaning of life,
  16. etc.
  17. 2. File Layout
  18. The file layout is pretty simple:
  19. / - Base directory
  20. /lib - 3rd party libraries stolen verbatim
  21. /libopts - GNU AutoOpts code
  22. /src - Main code routines
  23. /src/common - Common routines for all binaries
  24. /src/tcpedit - libtcpedit
  25. /docs - Where to find documentation
  26. /test - Test scripts and stuff which is used during 'make test'
  27. /man - Unix man pages which get copied to $MANPATH
  28. 3. Coding Standards
  29. 1) Indent 4 spaces using spaces, not tabs
  30. 2) Opening braces for control blocks (if, while, etc) should be on the same line
  31. 3) Opening braces for functions should be on next line
  32. 4) Use provided warnx, dbg, and errx functions provided in err.h
  33. 5) Use provided safe_strdup, safe_malloc and safe_realloc functions provided
  34. in common/utils.h
  35. 6) Use provided strl* functions in lib/strlcat.c and lib/strlcpy.c
  36. [NOTE: Everything below this point is currently inaccurate.]
  37. 4. Adding support for additional DLTs (Data Link Types)
  38. There are a number of files/functions that need to be touched to add support
  39. for a new DLT to tcpreplay and tcpprep. Note that for a patch to be
  40. accepted, BOTH tcpreplay and tcpprep need to be updated to support the new
  41. DLT.
  42. 4a) dlt.h
  43. Two things need to be added here:
  44. - A structure defining the header
  45. - A #define for the length of the header
  46. example for DLT_CHDLC (Cisco HDLC):
  47. /* Cisco HDLC has a simple 32 bit header */
  48. #define CISCO_HDLC_LEN 4
  49. struct cisco_hdlc_header {
  50. u_int16_t address;
  51. u_int16_t protocol;
  52. }
  53. 4b) tcpreplay.c
  54. You will need to edit validate_l2() to process the DLT type as defined by
  55. pcap-bpf.h which is included with libpcap. The key here is that tcpreplay
  56. needs to be able to generate a valid 802.3 ethernet frame. Basically
  57. validate_l2() has to make sure that between the existing Layer 2 header (if
  58. any) and the user supplied arguments (-2, -I, -J, -K and -k) that enough
  59. information is available. Generally this means one of:
  60. - The DLT already has a valid header
  61. - User specified their own complete header via -2
  62. - The existing header + user specified MAC addresses are enough
  63. validate_l2() also calcuates the 'maxpacket' which is the maximum size of a
  64. packet that we can send out of the interface. Generally this is the length
  65. of the Layer 2 header + MTU. You shouldn't need to change anything here.
  66. 4c) edit_packet.c
  67. Next, you'll have to edit rewrite_l2() to add support for rewriting the
  68. Layer 2 header from your DLT to a standard 802.3 header. Note that
  69. do_packets.c will automatically fill out the source/destination MAC address
  70. if the appropriate flag is used (-I, -J, -K and -k) so there is no need to
  71. copy those values over here.
  72. 4d) tcpprep.c
  73. Look at process_raw_packets(). Should be painfully obvious what do do here.
  74. 4e) dlt_names.h
  75. Look in dlt_names.h and make sure your DLT type is listed here. Note that
  76. this file is generated by scripts/dlt2name.pl. If it's not listed here,
  77. your best bet is to edit scripts/dlt2name.pl and list it in the %known hash
  78. and then run:
  79. make dlt_names
  80. Note that editing dlt_names.h is NOT going to work, since it will get
  81. overwritten the next time it is regenerated.
  82. 5. Hacking tcprewrite
  83. tcprewrite order of execution:
  84. Figure out if input file's DLT is supported
  85. foreach (packet) {
  86. Update packet timestamp based on modifier
  87. Decide packet path via cache or CIDR lookup
  88. if (a Layer 2 header is specified) {
  89. if (existing Layer 2 header) {
  90. strip existing Layer 2 header
  91. }
  92. prepend specified Layer 2 header
  93. }
  94. if (primary path or single path) {
  95. re-write MAC addresses
  96. re-write IP addresses
  97. re-write Ports
  98. } else if (secondary path) {
  99. re-write MAC addresses
  100. re-write IP addresses
  101. re-write Ports
  102. }
  103. pad or truncate packet
  104. fix checksums
  105. write packet to outfile
  106. }