1. $Id: HACKING 1348 2005-06-13 06:22:17Z 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 me: aturner@pobox.com
  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. /docs - Where to find documentation
  25. /test - Test scripts and stuff which is used during 'make test'
  26. /man - Unix man pages which get copied to $MANPATH
  27. 3. Coding Standards
  28. 1) Indent 4 spaces using spaces, not tabs
  29. 2) Opening braces for control blocks (if, while, etc) should be on the same line
  30. 3) Opening braces for functions should be on next line
  31. 4) Use provided warnx, dbg, and errx functions provided in err.h
  32. 5) Use provided safe_strdup, safe_malloc and safe_realloc functions provided
  33. in common/utils.h
  34. 6) Use provided strl* functions in lib/strlcat.c and lib/strlcpy.c
  35. [NOTE: Everything below this point is currently inaccurate.]
  36. 4. Adding support for additional DLTs (Data Link Types)
  37. There are a number of files/functions that need to be touched to add support
  38. for a new DLT to tcpreplay and tcpprep. Note that for a patch to be
  39. accepted, BOTH tcpreplay and tcpprep need to be updated to support the new
  40. DLT.
  41. 4a) dlt.h
  42. Two things need to be added here:
  43. - A structure defining the header
  44. - A #define for the length of the header
  45. example for DLT_CHDLC (Cisco HDLC):
  46. /* Cisco HDLC has a simple 32 bit header */
  47. #define CISCO_HDLC_LEN 4
  48. struct cisco_hdlc_header {
  49. u_int16_t address;
  50. u_int16_t protocol;
  51. }
  52. 4b) tcpreplay.c
  53. You will need to edit validate_l2() to process the DLT type as defined by
  54. pcap-bpf.h which is included with libpcap. The key here is that tcpreplay
  55. needs to be able to generate a valid 802.3 ethernet frame. Basically
  56. validate_l2() has to make sure that between the existing Layer 2 header (if
  57. any) and the user supplied arguments (-2, -I, -J, -K and -k) that enough
  58. information is available. Generally this means one of:
  59. - The DLT already has a valid header
  60. - User specified their own complete header via -2
  61. - The existing header + user specified MAC addresses are enough
  62. validate_l2() also calcuates the 'maxpacket' which is the maximum size of a
  63. packet that we can send out of the interface. Generally this is the length
  64. of the Layer 2 header + MTU. You shouldn't need to change anything here.
  65. 4c) edit_packet.c
  66. Next, you'll have to edit rewrite_l2() to add support for rewriting the
  67. Layer 2 header from your DLT to a standard 802.3 header. Note that
  68. do_packets.c will automatically fill out the source/destination MAC address
  69. if the appropriate flag is used (-I, -J, -K and -k) so there is no need to
  70. copy those values over here.
  71. 4d) tcpprep.c
  72. Look at process_raw_packets(). Should be painfully obvious what do do here.
  73. 4e) dlt_names.h
  74. Look in dlt_names.h and make sure your DLT type is listed here. Note that
  75. this file is generated by scripts/dlt2name.pl. If it's not listed here,
  76. your best bet is to edit scripts/dlt2name.pl and list it in the %known hash
  77. and then run:
  78. make dlt_names
  79. Note that editing dlt_names.h is NOT going to work, since it will get
  80. overwritten the next time it is regenerated.
  81. 5. Hacking tcprewrite
  82. tcprewrite order of execution:
  83. Figure out if input file's DLT is supported
  84. foreach (packet) {
  85. Update packet timestamp based on modifier
  86. Decide packet path via cache or CIDR lookup
  87. if (a Layer 2 header is specified) {
  88. if (existing Layer 2 header) {
  89. strip existing Layer 2 header
  90. }
  91. prepend specified Layer 2 header
  92. }
  93. if (primary path or single path) {
  94. re-write MAC addresses
  95. re-write IP addresses
  96. re-write Ports
  97. } else if (secondary path) {
  98. re-write MAC addresses
  99. re-write IP addresses
  100. re-write Ports
  101. }
  102. pad or truncate packet
  103. fix checksums
  104. write packet to outfile
  105. }