NOTES

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