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('ipfw too'). This ipfw will be designed in modular, all the functionalities are originally from loadable modules and should be not that difficult for normal users/developers to create a module in order to meet their own requirements.
  17 ## Brief notes on design
  18 Before user starts to use the ipfw utility to add rules, the ipfw kernel module should be 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. And continue run below command
  23
  24         kldload ipfw_basic
  25
  26 the basic module together with all the basic functionalities have been loaded. If user wants more functions which implemented in other modules, for example, the 'layer2' module in order to filer the layer2 traffic, so user should run below
  27
  28         kldload ipfw_layer2
  29
  30 and the 'layer2' module is loaded now, 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, below steps will be done.
  35
  36 1. ipfw retrieve the module 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 rules, 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 feature mode which is same as ipfw in FreeBSD in user angle of view.
  63
  64
  65 # Modules
  66 Some modules are exists in the FreeBSD's ipfw,e.g. the dummynet and in-kernel NAT. they are "action modules" providing the functionalities which will be applied to the traffic whom successfully passed all the filters.
  67
  68 Some modules are "filter modules" which is new in this ipfw. And every "filter module" comes with a kernel part and user-space part. the kernel part contains all the "check-function" and it requires to be loaded manually, while the user-space part contains all the "parse-and-show functions" and it will be loaded automatically when user fires the ipfw command if it is needed to be loaded.
  69
  70 ## Filter Modules
  71 When the ipfw 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
  72       allow
  73       deny
  74 by firing command `kldload ipfw', the default ipfw will be loaded. and all other modules are relying on this module.
  75 ### Basic Module
  76 By firing command `kldload ipfw_basic', the basic module will be loaded. and this module brings all the basic functionalities , and examples list below.
  77
  78     ipfw add allow all
  79     ipfw add deny all
  80     ipfw add allow proto icmp
  81     ipfw add allow icmp  /* proto keyword is optional */
  82     ipfw add allow icmp from 1.1.1.1
  83     ipfw add allow icmp to 2.2.2.2
  84     ipfw add allow all in
  85     ipfw add allow all out
  86     ipfw add allow via em0
  87     ipfw add allow xmit em0
  88     ipfw add allow recv em0
  89
  90     ipfw add count icmp
  91     ipfw add skipto 100 icmp
  92     ipfw add fwd 1.2.3.4 icmp
  93
  94     ipfw add check-state
  95     ipfw add allow icmp keep-state
  96
  97     ipfw add allow icmp prob 60%
  98
  99 ### Layer2 Module
 100 By firing command `kldload ipfw_layer2', the layer2 module will be loaded. and this module brings all the functionlities which related to the layer2 traffic.
 101
 102     ipfw add allow all layer2
 103     ipfw add deny all mac 11:11:11:11:11:11 to 22:22:22:22:22:22
 104
 105 A sysctl 'net.link.ether.ipfw' to control whether the layer2 traffic will be processed by ipfw.
 106 ### Layer4 Module
 107 By firing command `kldload ipfw_layer4', the layer4 module will be loaded. and this module brings all the functionlities which related to the layer4 traffic.
 108         tcpflag
 109         ...
 110 It will be just a sample to demonstrate how to filter the traffic in different
 111 angle of view. it can be a good example to demonstrate how to do L7 traffic shaping or integrate with NDI technologies.
 112 ### Connection Module
 113 This modules is focusing on the connections. for example to limit X packets per second, or limit X connections between 2 IP addresses.
 114         pps
 115         conns
 116
 117 ## Action Modules
 118 ### Dummynet
 119 Luigi's nice work.
 120
 121 ### NAT
 122 Libalias is the library used to do masquerading and IP address translation (NAT). But libalias is not designed to use in kernel space originally. so lots of hiccups when porting it into kernel space.
 123
 124     ipfw nat 1 config if em0 reset
 125     ipfw add allow icmp via em0
 126
 127 ### LOG
 128 Log is an facility which can track down all the traffic and since ipfw2 can support multiple action in one rule ....
 129
 130 # Development
 131 This section will be an example of how we create a "filter module" in order to match the traffic of skype application, it is kind of "L7 filter".
 132 ## User-space part of the module
 133 ## Kernel part of the module
 134 # Roadmap
 135
 136 [in plan]: 'tag' 'untag' 'tagged'
 137
 138 [in plan]: Multi-Routing to enhance the policy routing.
 139
 140 [in plan]: Policy routing as PF/NPF.
 141
 142
 143 01-12-2014: 'keep-state' and 'check-state' to make it a Stateful firewall.
 144
 145 24-11-2014: Port in-kernel NAT from FreeBSD.
 146
 147 18-11-2014: Integrate with dummynet module.
 148
 149 18-11-2014: Add 'forward' keyword.
 150
 151 17-11-2014: Add 'skipto' keyword.
 152
 153 16-11-2014: Show the "from any to any" when 'from' and 'to' is not exists.
 154
 155 11-11-2014: Release alpha 0.1 version which is in modular.
 156
 157 29-10-2014: Extended the 'ipfw_insn' size.