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 framework of the ipfw3 only comes with default'accept' or 'deny' actions. by triggering below command, the core module will be loaded.
  26
  27         kldload ipfw3
  28
  29 the fundamental core framework is loaded now.
  30
  31 More basic firewall filtering features like 'filtering based on source IP' are implemented in basic module, so basic module need to be loaded before we start to the features. and below is the command to load the basic module, the basic module is relying on the core framework, so the core framework will be loaded automatically if it is not loaded yet,
  32
  33         kldload ipfw3_basic
  34
  35 The basic module is loaded now. then the user can start to use the filters which was implemented in the basic module. besides the basic module, there are layer2 module, layer4 module, in-kernel NAT module, dummynet module.
  36
  37 Each module contains 2 parts. library in user-space which will be loaded and parse the command line into rules. and kernel space portion will be invoked when the traffic hit the firewall and it will trigger the correct action according to the firewall rules.
  38
  39 ## Compare with FreeBSD's IPFW
  40 Ipfw3 inherited all feature from FreeBSD's ipfw, and lots of new features are introduced from PF or other rivals.
  41
  42 **Much more extensible**
  43
  44 Every filter/action needs to be identified using ID, but there are only 8 bits space to store the ID, so theoretically it can support 256 filters/actions in maximum in FreeBSD' ipfw. While in ipfw3, the space for ID are still the same, but one space introduced to keep the module's ID, so theoretically ipfw3 can have 256 modules and 256 filter/action in each module.
  45
  46 And in ipfw3, both user-space library and kernel space module are implemented with a simple interface, it is quite easy to build your own filter/module by following the interface.
  47
  48 **Much more concise**
  49
  50 the rules of ipfw3 are much more concise. for example, the simple rule command like
  51
  52     ipfw add allow ip from any to any
  53
  54 the "from any to any" actually is just try to make the rule more human-readable. In ipfw3 we support the syntax of FreeBSD's ipfw, but we recommend to use simplified version as below:
  55
  56     #1. ipfw3 add allow all
  57     #2. ipfw3 add allow icmp from 1.1.1.1
  58     #3. ipfw3 add allow tcp via em0
  59
  60 **Higher Performance**
  61
  62 All modern CPUs are having mutil-cores, and each core are running independently. So the LWKT of DragonflyBSD is the best way to fully utilize the CPU power. by duplicating the environment for each CPU, all the CPU can run as fast as it can without any interference. So it is a lockless and stateful firewall.
  63
  64
  65 # Basic Configuration
  66
  67 ## Core Framework
  68
  69 Below actions are directly supported from the core framework.
  70
  71 **accept**  -- accept the traffic
  72
  73 **deny**  -- deny the traffic
  74
  75 the default action of the firewall was compiled in the core framework. but it still can be interfered by below sysctl when the module was loading into the kernel.
  76
  77     sysctl net.filters_default_to_accept
  78
  79 ## Basic Module
  80
  81 Below filter/actions are supported in basic module.
  82
  83 **proto** -- matches traffic protocol, it is implicit after the action.
  84
  85 **from** -- matches the source.
  86
  87 Filter 'from' supports multiple type of parameters.
  88
  89     from 8.8.8.8        -- match traffic from IP 8.8.8.8
  90     from table 1        -- match traffic where source IP found in table 1
  91     from any            -- not filtering
  92     from me             -- match traffic from the host
  93     from 192.168.1.0/24 -- match traffic from the IP range
  94
  95 **to** -- matches the destination.
  96
  97 Filter 'to' supports same parameters as filter 'from'
  98
  99 **count** -- action count the traffic
 100
 101 **skipto** -- skipto another line in the rules
 102
 103 **forward** -- forward the current traffic to a destination
 104
 105 **in** -- matches the in direction traffic
 106
 107 **out** -- matches the out direction traffic
 108
 109 **via** -- matches the traffic go throught an interface
 110
 111 **xmit** -- matches the out direction traffic thought an interface
 112
 113 **recv** -- matches the in direction traffic thought an interface
 114
 115 **src-port** --matches the src port of TCP/UDP traffic
 116
 117 **dst-port** --matches the dst port of TCP/UDP traffic
 118
 119 **prob** -- randomly match the traffic
 120
 121 **keep-state** -- setup a state in current CPU only
 122
 123 **check-state** -- loop the state table current CPU, match if its state exists
 124
 125 **tag** -- add a tag the traffic
 126
 127 **untag** -- remove the tag from the traffic
 128
 129 **tagged** -- matched the traffic with the tag
 130
 131 **//** -- append some comment at the end of the rule
 132
 133 ## Layer2 Module
 134
 135 **layer2** -- matches layer2 traffic
 136
 137 **mac** -- matches layer2 traffic with src and dst MAC addresses
 138
 139 **mac-from** -- matches layer2 traffic with src MAC address (supports lookup table)
 140
 141 **mac-to** -- matches layer2 traffic with dst MAC address (supports lookup table)
 142
 143 ## Layer4 Module
 144
 145 **tcpflag**  -- matches the TCP flag
 146
 147 **uid** -- matches the sockets owner ID
 148
 149 **gid** -- matches the sockets owner's group ID
 150
 151 **established** --matched the established TCP connection
 152
 153 **bpf**  -- filter traffic with bpf syntax
 154
 155 ## NAT Module
 156
 157 **nat** -- NAT traffic with pre-defined NAT configuration
 158
 159 ## Dummynet3 Module
 160
 161 **pipe** -- pipe traffic with pre-defined pipe configuration
 162
 163 **queue** -- queue traffic with pre-defined queue configuration
 164
 165 # Advanced Configuration
 166
 167 ## Rule Set
 168
 169 ## Lookup Table
 170
 171 ## Enhanced Forwarding
 172
 173 ## General BPF Filtering
 174
 175 ## Stateful
 176
 177 ## In-Kernel NAT
 178
 179 #Additional Topics
 180
 181 ## Logging
 182
 183 Ipfw3 support 10 pseudo ipfw interfaces for logging. and the pseudo intercaces can be create with below command:
 184
 185         ifconfig ipfw1 create
 186
 187 Traffic matching a rule with the 'log' action will be captured by the BPF and duplicated into an ipfw pseudo interface accordingly. e.g.
 188
 189         ipfw add 100 allow log 1 icmp from 8.8.8.8
 190
 191 Above rule will attach the ICMP packet to the ipfw1 interface and the ICMP packets are from 8.8.8.8.
 192
 193 # Example Rules