NOTES

   1 #
   2 # $Id: NOTES 5355 2010-02-18 18:58:43Z luigi $
   3 #
   4
   5 ---------------------------------------------------------------------
   6 ---  DEVELOPER NOTES ------------------------------------------------
   7
   8 Both the client and the kernel code use almost unmodified sources
   9 from FreeBSD (just a very small number of sections #ifdef'ed out
  10 for features not relevant or not implemented).
  11
  12 In both cases we provide two set of headers:
  13  - one set is made of empty files, automatically generated, to replace
  14    FreeBSD headers not available or conflicting on the ported platforms.
  15  - one set is made of custom files, sometimes copied verbatim
  16    from FreeBSD, sometimes containing only the minimal set of
  17    macros/ struct/ prototypes required by the port.
  18
  19 Additionally, we have a small set of .c files providing functions not
  20 available in the port platforms, and hooks for the sockopt/packet
  21 data.
  22
  23
  24 TODO 20100205:
  25 + use an appropriate identifier instead of LINUX24
  26 + find the discharging module hook, in order to force a queue flush
  27 + better matching on interface names (case insensitive etc ?)
  28 + match by interface address
  29 + verify path
  30 + send keepalives
  31 + pullup of data in external buffers
  32 + O_TAG
  33 + O_DIVERT
  34 + O_TEE
  35 + O_SETFIB
  36 + kmem_cache_alloc
  37
  38 TODO (OpenWRT) 20090622
  39 + add a module compilation for 2.6
  40
  41 TODO (FreeBSD, general)
  42 + New features related to the forthcoming IPv6 are missing, as the IPv6
  43 support for lookup tables that currently support IPv4 addresses only.
  44 One of the goal of this project is to add the tables feature to the
  45 IPv6 protocol.
  46
  47 + The current code implements rules listing requests as a single
  48 request returning both static and dynamic rules as a whole block. This
  49 operation requires a lock to be held for the time needed to get the
  50 full list of rules, regardless of the requested rules.  I propose to
  51 break up the rule request in two parts, for static and dynamic rules, in
  52 order to avoid to lock the whole struct for a subset of rules required.
  53
  54 + At last, due to improvement and contribution to the code, the tool
  55 significantly grown over the time with new functionalities and features,
  56 leaving the general view aside. An example of this will be the use of
  57 dispatching table instead some very long switch case, making the resulting
  58 code more readable and hopefully a faster execution.
  59
  60 + XXX can't find the ipfw_* indirection...
  61
  62 DETAILED PORTING INFO
  63
  64 --- ipfw (userland) on linux ---
  65
  66 The port is relatively trivial. Communication with the kernel occurs
  67 through a raw socket using [gs]etsockopt(), and all is needed is the
  68 availability of ip_fw.h and ip_dummynet.h headers to describe the
  69 relevant data structures.
  70
  71 --- kernel ipfw on linux ---
  72
  73 Sources are mostly unmodified, except for commenting out
  74 unsupported features (tables, in-kernel nat...).
  75 The port requires a rather large number of empty headers.
  76 Other porting issues are in ipfw2_mod.c
  77
  78 --- build as an Openwrt package
  79
  80 ------ WINDOWS PORT ------
  81
  82 We started from the wipfw port available at [WIPFW] , but
  83 most of the port is done from scratch using the most recent
  84 version of ipfw+dummynet from HEAD/RELENG_7 as of March 2009
  85
  86 # WIPFW: wipfw.sourceforge.net
  87 #binary:
  88 http://downloads.sourceforge.net/wipfw/wipfw-0.3.2b.zip?use_mirror=mesh
  89 http://downloads.sourceforge.net/wipfw/wipfw-0.2.8-source.zip
  90
  91 --- DEVELOPMENT TOOLS:
  92
  93 At least initially, to build the code you need a pc with
  94 windows installed and the [WINDDK] from the microsoft site.
  95 Other tools like the new WDK should work as well.
  96
  97 The 'standard' way used by WDK/WINDDK is to run a 'build'
  98 script which in turn calls nmake and then the microsoft
  99 compiler [CL] and linker [LINK]. See the documentation for
 100 command line switches for these tools, they are similar but
 101 not the same as the equivalent gcc switches. In particular,
 102 a / is often used to replace - though both forms are accepted.
 103
 104 The steps to do in order to launch the build environment follows:
 105
 106  + download winddk from microsoft.com
 107  + install
 108  + run the Free Build Enviroment from:
 109
 110         Start -> All Program -> WINDDK ->
 111         [NT|XP|2000] -> Free Build Environment
 112
 113  + change dir to .src and type `build' in command line
 114
 115 For our purposes, however, it is much more convenient to use
 116 cygwin [CYGWIN] and invoke CL and LINK using gmake
 117
 118 A debugging tools is:
 119         http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx
 120 it simply display the kernel-mode debug output.
 121 Use the DbgPrint() function, that is something similar to printk().
 122 Can be lauched with dbgview.exe.
 123
 124 After a succesfully compilation and link, you can launch the program
 125 in user space simply executing the binary file, while for the kernel
 126 space you need to do the following steps:
 127
 128 cp ipfw.sys /cygdrive/c/WINDOWS/system32/drivers/
 129 ipfw install_drv System32\DRIVERS\ip_fw.sys
 130 net start ip_fw
 131
 132
 133 =======
 134 --- ARCHITECTURE ---
 135
 136 The main part of the userland program mostly work as the
 137 unix equivalent, the only issue is to provide empty
 138 header files to replace those not available in Windows,
 139 and include the winsock2 headers to access some network
 140 related functions and headers.
 141
 142 Communication with the kernel module does not use a raw IP socket
 143 as in the unix version. Instead, we inherit the same method
 144 used in ipfw -- a replacement for socket() creates a handle
 145 to access the control structure, and setsockopt/getsockopt
 146 replacements are also used to communicate with the kernel
 147 side. This is implemented in win32.c
 148
 149 In order to load the module and activate it, we also use
 150 the same technique suggested in wipfw -- the main() is
 151 extended (with a wrapper) so that it can handle additional
 152 commands to install/control/deinstall the service and
 153 call the appropriate actions. See svcmain.c for details.
 154
 155 --- PORTING ISSUES:
 156
 157 Most of the unix hierarchy of headers is not available so we
 158 have to replicate them.
 159
 160 gcc attributes are also not present.
 161
 162 C99 types are not present, remapped in <sys/cdefs.h>
 163 Also, we don't have C99 initializers which sometimes gives trouble.
 164
 165 --- USEFUL LINKS:
 166
 167 [WIPFW]
 168         http://wipfw.sourceforge.net/
 169
 170 [WINDDK]
 171         http://www.microsoft.com/whdc/devtools/ddk/default.mspx
 172
 173 [CL]
 174         http://msdn.microsoft.com/en-us/library/610ecb4h.aspx
 175         command line syntax
 176
 177 [CYGWIN]
 178         http://www.cygwin.com/setup.exe
 179 Windows Driver Kit
 180 http://www.microsoft.com/whdc/DevTools/WDK/WDKpkg.mspx
 181
 182 Debug Symbols for WinXP SP3
 183 http://www.microsoft.com/whdc/devtools/debugging/symbolpkg.mspx#d
 184
 185 DbgView
 186 http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx
 187
 188 Cygwin
 189 http://www.cygwin.com/
 190 (installazione pacchetti di default + categoria devel)
 191
 192 Winrar (il WDK e' distribuito in un file .iso)
 193 http://www.rarlab.com/download.htm
 194
 195 puttycyg (terminale per cygwin)
 196 http://code.google.com/p/puttycyg/
 197
 198 Tortoise SVN
 199 http://tortoisesvn.net/downloads
 200
 201 EditPlus
 202 http://www.editplus.com/