docs/ipfw2/index.mdwn

   1 [[!meta title="Ipfw3 Documentation"]]
   2 [[!meta robots="index, follow"]]
   3
   4
   5 bycn82
   6
   7 2 Mar. 2015
   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. It is comprised of several components, e.g. 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 DragonflyBSD is a logical continuation of the FreeBSD 4.x series, DragonFly's development has diverged significantly from FreeBSD's, e.g. a new Light Weight Kernel Threads implementation (LWKT), a lightweight ports/messaging system,
  17
  18 In DragonFly, each CPU has its own thread scheduler. Upon creation, threads are assigned to processors and are never preemptively switched from one processor to another; they are only migrated by the passing of an inter-processor interrupt (IPI) message between the CPUs involved. Inter-processor thread scheduling is also accomplished by sending asynchronous IPI messages. One advantage to this clean compartmentalization of the threading subsystem is that the processors' on-board caches in Symmetric Multiprocessor Systems do not contain duplicated data, allowing for higher performance by giving each processor in the system the ability to use its own cache to store different things to work on.
  19
  20 The LWKT subsystem is being employed to partition work among multiple kernel threads (for example in the networking code there is one thread per protocol per processor), reducing competition by removing the need to share certain resources among various kernel tasks.
  21
  22 The ipfw was rewritten from scratch for DragonflyBSD and named 'ipfw3', it is in modular design, and inherited the "SMP-Friendly" feature of DragonflyBSD's LWKT, it is a lockless and stateful firewall.
  23
  24 ## Brief notes on design
  25 Ipfw3 was in modular design. all the functionalities are implemented in different loadable modules, it can be loaded when it is required. the core of the ipfw3 only comes with basic 'accept/deny' actions. by triggering below command, the core module will be loaded.
  26
  27         kldload ipfw3
  28
  29 the fundamental framework is loaded now.
  30
  31         kldload ipfw3_basic
  32
  33 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
  34
  35         kldload ipfw3_layer2
  36
  37 and the 'layer2' module is loaded now, for example in this scenario, user can start to fire below command
  38
  39         ipfw3 add allow all from any to any layer2
  40
  41 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.
  42
  43 1. retrieve the module list from the kernel
  44 2. load the module accordingly
  45 3. parse the parameters
  46 4. inject into the kernel
  47
  48 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.
  49
  50 ## Compare with FreeBSD's IPFW
  51 Comparing to the IPFW from FreeBSD, this IPFW3 for DragonflyBSD is:
  52
  53 ### Much more extensible
  54
  55 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.
  56
  57 In this IPFW3 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.
  58
  59 ### Much more concise
  60
  61 In this IPFW3 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.
  62
  63     #1. ipfw3 add allow all
  64     #2. ipfw3 add allow icmp from 1.1.1.1
  65     #3. ipfw3 add allow tcp via em0
  66
  67 ### Higher Performance
  68
  69 It is using LWKT of DragonflyBSD, so every has one copy per cpu, it is lockless stateful firewall which can fully utilize the CPUs.
  70
  71
  72 # Modules
  73
  74 This IPFW3 is modular, there are two type of modules.
  75
  76 "Action Modules" are exists in the FreeBSD's IPFW,e.g. the dummynet and in-kernel NAT. they are providing the functionalities which will be applied to the traffic whom successfully passed all the filters.
  77
  78 "Filter modules" are come 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 ipfw3 command if it is needed to be loaded.
  79
  80 So the core IPFW3 module is just a framework, all the feature and functionalities are bring by the modules. more detail and examples of the modules can be found [here](/docs/ipfw2/modules).
  81
  82
  83 # Development
  84 This section will explain this IPFW3 in developer's angle or views
  85
  86 ##PFIL framework
  87 The PFIL framework was designed to tidy the kernel, all the packet filters can register it's filter function into the PFIL hook, and the functions in the hook will be triggered when the traffic reach different positions in the IP stack.
  88
  89 ##Tunnel between userspace and kernel
  90 in BSD,socketopt is the tunnel between userspace and kernel, so in IPFW3, all the operation are warpped in `IP_FW_X`in order to isolated the changes in IPFW3 modules only.
  91
  92 ##Performance
  93 IPFW3 is a `lock-free` stateful firewall, so everything should have a copy `per-cpu`. By fully use of multiple CPU at the same time,it can have a better performance.
  94
  95
  96 # Roadmap
  97 Submit log history can be found via
  98 https://github.com/bycn82