docs/ipfw2/index.mdwn

   1 [[!meta title="IPFW2 Documentation"]]
   2 [[!meta robots="index, follow"]]
   3
   4
   5 bycn82
   6
   7 (under development)
   8
   9 ---
  10
  11 [[!toc  levels=3]]
  12
  13 # Introduction
  14 IPFW is a controlling utility for ipfw/ipacct facilities for FreeBSD 2.0 which released in November, 1994. After 20 years of evolution. it becomes a stateful firewall which supports Layer2 to Layer4. It is comprised of several components: the kernel firewall filter rule processor and its integrated packet accounting facility, the logging facility, NAT, the dummynet(4) traffic shaper, a forward facility, a bridge facility, and an ipstealth facility. It is one of the most advanced opensource firewall.
  15
  16 I am re-writing it from scratch for DragonflyBSD and call it IPFW2. This IPFW2 will be in modular design, all the functionality are originally from loadable modules and should be not that difficult for normal users/developer to create a module in order to meet their own requirements.
  17 ## Brief notes on design
  18 Before users start to use the IPFW2 utility to add rules, the IPFW2 kernel should be enable/loaded into the kernel. by running below command
  19
  20         kldload ipfw
  21
  22 the fundamental framework is loaded now, it can support the default rules only. continue run below command
  23
  24         kldload ipfw_basic
  25
  26 the basic IPFW2 module is loaded into kernel now,together with all the basic functionality. in order to user more function which is implemented in other modules, users can run below command
  27
  28         kldload ipfw_layer2
  29
  30 so the 'layer2' module will be loaded, for example in this scenario, user can start to fire below command
  31
  32         ipfw add allow all from any to any layer2
  33
  34 it means user want to add add rule which allow all the layer2 traffic. when user fire the command in the console, actually in the back-end, it will do below things.
  35
  36 1. ipfw retrieve the module name list from the kernel
  37 2. ipfw load the module accordingly
  38 3. ipfw start to parse the parameters
  39 4. inject into the kernel
  40
  41 In the kernel space, when the traffic comes, it will filter again the rule, in each ipfw_insn has unique module + opcode. it will automatically link to the filter function which will be registered during the module was loaded.
  42
  43 ## Compare with FreeBSD's ipfw
  44 Comparing to the IPFW from FreeBSD,this IPFW for DragonflyBSD is:
  45
  46 **Much more extensible**
  47
  48 Every feature/function needs to be identified by an ID, but there are only 8bits space to store the ID, so theoretically it can support 256 features/functions in maximum.
  49
  50 In this IPFW for DragonflyBSD, the space for ID are the same, so also 8bits, but one space for each module and it has 8bits for module ID, so so theoretically it can have 256 modules and 256 features/functions in each module, so 256*256 feature/functions in maximum.
  51
  52 **Much more concise**
  53
  54 In this IPFW for DragonflyBSD, the rules are much more concise. for example, the simple rule command like "ipfw add allow ip from any to any".  the "from any to any" actually is just try to make the rule more readable. but actually "ipfw add allow ip" is much more concise. and another example "ipfw add allow ip from 1.1.1.1 to any" cannot be better than "ipfw add allow from 1.1.1.1". because "from any " and "to any" are actually useless.
  55
  56     #1. ipfw add allow all
  57     #2. ipfw add allow icmp from 1.1.1.1
  58     #3. ipfw add allow tcp via em0
  59
  60 **Much more flexible**
  61
  62 It supports concise mode and full mode which is same as IPFW in FreeBSD in user angle of view.
  63
  64
  65 # Configuration
  66 # Modules
  67 Modules are loadable,and every module comes with a kernel part and userspace part. the kernel part need to be loaded manually, and the userpsace part can be loaded automatically when user fires the ipfw command.
  68 ## Filter Modules
  69 When the ipfw module was loaded, it comes with 2 opcodes in order to support the default behavior of the ipfw. so below 2 opcodes are embeded in the ipfw.ko
  70       accept
  71       deby
  72 by fire command `kldload ipfw', the default module is loaded. and all other modules are relying on this module.
  73 ### Basic Module
  74 Basic Module contains all the basic features. it has multiple opcodes list below.
  75         proto
  76         from
  77         to
  78         in
  79         out
  80         via
  81         recv
  82         xmit
  83
  84
  85
  86 ### Layer2 Module
  87
  88         layer2
  89         mac-type
  90
  91 ### Layer4 Module
  92
  93         tcpflag
  94
  95
  96 ### Connection Module
  97
  98         pps
  99         lps
 100
 101 ## Action Modules
 102
 103 ### Dummynet
 104
 105 ### NAT
 106
 107 ### LOG
 108
 109 # Development
 110 ## How to create a module
 111 # Roadmap
 112 [in plan]: Add layer2 support for 'forward' keyword.
 113
 114 [in plan]: Policy routing as PF/NPF.
 115
 116 [in plan]: Port in-kernel NAT from FreeBSD.
 117
 118 18-11-2014: Integrate with dummynet module.
 119
 120 18-11-2014: Add 'forward' keyword.
 121
 122 17-11-2014: Add 'skipto' keyword.
 123
 124 16-11-2014: Show the "from any to any" when 'from' and 'to' is not exists.
 125
 126 11-11-2014: Release alpha 0.1 version which is in modular.
 127
 128 29-10-2014: Extended the 'ipfw_insn' size.