[[!meta title="IPFW2 Documentation"]]
[[!meta robots="index, follow"]]


bycn82

(under development)

---

[[!toc  levels=3]]

# Introduction
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.

I am re-writing it from scratch for DragonflyBSD and call it IPFW2('ipfw too'). This ipfw2 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.

In order to achieve best performance, it inherited the "SMP-Friendly" feature from DragonflyBSD, then it becomes a "lockless" stateful firewall.

## Brief notes on design
Before user starts to use the ipfw2 utility to add rules, the ipfw2 kernel module should be loaded into the kernel by running below command.

        kldload ipfw2

the fundamental framework is loaded now, it can support the default rules only. And continue run below command

        kldload ipfw2_basic

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 

        kldload ipfw2_layer2

and the 'layer2' module is loaded now, for example in this scenario, user can start to fire below command 

        ipfw add allow all from any to any layer2

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.

1. ipfw2 retrieve the module list from the kernel
2. ipfw2 load the module accordingly
3. ipfw2 start to parse the parameters 
4. inject into the kernel

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.

## Compare with FreeBSD's ipfw
Comparing to the IPFW from FreeBSD,this IPFW2 for DragonflyBSD is:

### Much more extensible

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.

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.

### Much more concise

In this ipfw2 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.

    #1. ipfw add allow all 
    #2. ipfw add allow icmp from 1.1.1.1
    #3. ipfw add allow tcp via em0

### Higher Performance

It is using LWKT of DragonflyBSD, so every has one copy per cpu, it is lockless stateful firewall which can fully utilize the CPUs.


# Modules

This ipfw2 is modular, there are two type of modules.

"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.

"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 ipfw2 command if it is needed to be loaded. 

So the core ipfw2 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).


# Development
This section will explain this ipfw2 in developer's angle or views

##PFIL framework
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.

##Tunnel between userspace and kernel
in BSD,socketopt is the tunnel between userspace and kernel, so in ipfw2, all the operation are warpped in `IP_FW_X`in order to isolated the changes in ipfw2 modules only.

##Performance
IPFW2 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.


# Roadmap
Submit log history can be found via
https://github.com/bycn82