docs/ipfw2/modules/index.mdwn

   1 [[!meta title="IPFW3 Modules"]]
   2 [[!meta robots="index, follow"]]
   3
   4
   5 bycn82
   6
   7 21 apr. 2015
   8
   9 ---
  10
  11 [[!toc  levels=3]]
  12
  13 # Modules
  14 This IPFW3 is designed in modular, this document will introduce all the modules with examples with below format.
  15
  16 **keyword** description of the keyword
  17
  18     e.g. sample usage of this keyword in firewall rule
  19
  20 *description of this rule*
  21
  22 ## Core IPFW3 Module
  23 Core IPFW3 modle is the fundamental module. all other modules are rely on it. it can be loaded by
  24
  25     kldload ipfw3
  26
  27 the IPFW3 module is loaded, and it will accept or deny all traffic. and it was configured by IPFIREWALL_DEFAULT_TO_ACCEPT in Makefile of IPFW3 module.
  28
  29 ## Action Modules
  30
  31 ### In-kernel NAT
  32 IPFW3 supports in-kernel NAT using the kernel version of libalias. and NAT configuration should be prepared before configure NAT rule.
  33
  34     e.g kldload ipfw3_nat
  35         ipfw3 nat 1 config if em0 reset
  36         ipfw3 add nat 1 icmp from 1.1.1.1 out via em0
  37         ipfw3 add nat 1 icmp recv em0
  38 *as in the example, the nat configuration should be prepared first. and nat rule should apple to both direction traffic. when the traffic goes out from em0, it will create an alias and the return will recognize the alias and traffic the IP address back.*
  39
  40 ### Dummynet
  41 Dummynet is a traffic shaper, packet scheduler and network emulator, a subsystem that can artificially queue,delay or drop packets emulating the behaviour of certain network links or queueing systems.
  42
  43     e.g kldload dummynet3
  44         ipfw3 pipe 1 config bw 100kbps
  45         ipfw add pipe 1 all from 1.1.1.1 out via em1
  46 *as in the example, the pipe configuration define a network shaper, it will limit the bandwidth to 100kbps, and the next rule apply the bandwidth pipe to traffic which from 1.1.1.1 via em1*
  47
  48 ### Lookup Table
  49 Lookup table was designed to speed up the query in large number of ip/mac/ifaces. for ip/mac are using the radix tree structure to speed up. and iface is using the int list to keep the interface status in this table.
  50
  51     e.g. ipfw3 add allow icmp in via em0 from 192.168.1.1
  52          ipfw3 add allow icmp in via em0 from 192.168.1.2
  53          ipfw3 add allow icmp in via em0 from 192.168.1.3
  54          ...
  55 above rules will loop multiple times for the different ip addresses.as well as the 'in' and 'via em0' filter. in order to reduce the common filters of this rules. it can be rewritten as
  56
  57     e.g. ipfw3 table 1 type ip name office
  58          ipfw3 table append 1 ip 192.168.1.1
  59          ipfw3 table append 1 ip 192.168.1.2
  60          ipfw3 table append 1 ip 192.168.1.3
  61          ...
  62          ipfw3 add allow icmp in via em0 from table 1
  63
  64 above rules will prepare a lookup table with ip addresses. it will filter 'in' and 'via em0' once for each packet and loop inside the table. and below rule will filter according to the table id.
  65
  66          ipfw3 add allow tcp from table 1
  67
  68 technically, the ip type table can be use in filter 'from' and 'to', and iface type table can be used in filter 'via' 'xmit' 'recv', and MAC type table can be use in filter 'mac'.
  69
  70
  71
  72 ### Log
  73 under development.
  74
  75 ## Filter Modules
  76 ### Basic
  77
  78 Basic modules is the most common and useful module in IPFW3 , it brings lots of useful functionalities into the IPFW3 . by trigger below command on the command line
  79
  80     kldload ipfw3_basic
  81
  82 the "ipfw3_basic" module will be loaded into kernel, and the "ipfw3" core module will be automatically loaded. below are the features from this module:
  83
  84 **count** is an action which only update the counter and continue to the next rule.
  85
  86     e.g. ipfw3 add count icmp from 1.1.1.1
  87 *count the icmp traffic from 1.1.1.1*
  88
  89
  90 **skipto** is an action which will update the counter and skipto to the specific next rule.
  91
  92     e.g. ipfw3 add skipto 1234 icmp from 1.1.1.1
  93 *skip the icmp traffic from 1.1.1.1 to line 1234*
  94
  95
  96 **forward** is an action which can change the next-hop on matching packets to ipaddr, which can be an IP address in dotted quad format or a host name.  The search terminates if this rule matches.
  97
  98 If ipaddr it can be is a local addresses, then matching packets will be forwarded to port (or the port number in the packet if one is not specified in the rule) on the local machine.
  99
 100     e.g. ipfw3 add forward 127.0.0.1:8080 tcp from 1.1.1.1
 101 *this will directly the traffic to localhost 8080 port *
 102
 103 If ipaddr is not a local address, then the port number (if specified) is ignored, and the packet will be forwarded to the remote address, using the route as found in the local routing table for that IP.
 104
 105     e.g. ipfw3 add forward 8.8.8.8 udp from 1.1.1.1
 106 *this will route the udp traffic to 8.8.8.8  *
 107
 108 and use comma to separate multiple ip addresses. forward-option can be 'round-robin' or 'sticky'. 'sticky' is calculated based on the src ip addresses, and if no forward-option, by default it will be 'random'.
 109
 110     e.g. ipfw3 add forward 192.168.1.2:8080,192.168.1.3:8080 tcp to 192.168.1.1
 111 *this will randomly redirect the traffic *
 112
 113     e.g. ipfw3 add forward 192.168.1.2:8080,192.168.1.3:8080 tcp to 192.168.1.1 round-robin
 114 *this will redirect the traffic in round-robin way*
 115
 116     e.g. ipfw3 add forward 192.168.1.2:8080,192.168.1.3:8080 tcp to 192.168.1.1 sticky
 117 *this will redirect the traffic in sticky way according to the src ip *
 118
 119 **in** is a filter, it will match the in coming traffic.
 120
 121 **out** is a filter, it will match the out going traffic.
 122
 123 **via** is a filter, it will match the traffic via the specific interface.
 124
 125 **xmit** is a combination of 'out' and 'via'
 126
 127 **recv** is a combination of 'in' and 'via'
 128
 129 **proto** is a filter, it will match the protocol. it is optional. the first filter after the action is always a protocol filter.
 130
 131 **from** is a combination of multiple opcodes. it will parse the parameters and use different opcode accordingly. it supports 'any', 'me', IP address or an subnet range. or a lookup table.
 132
 133 **to** same as filter 'from'.
 134
 135 **prob** is an filter which will randomly match according to the porbility.
 136
 137     e.g. ipfw3 add allow icmp prob 50
 138 *it will allow 50% of icmp*
 139
 140 **keep_state**
 141
 142 **check_state**
 143
 144 **tag** is an action, it will tag the traffic, and the tag is within the system.
 145
 146 **untag** is an action, it will remote the tag from the traffic.
 147
 148 **tagged** is a filter, it will match when the traffic is tagged and the tag value is match.
 149
 150 **//** means all the text after are comment,
 151 ### Layer2
 152 Layer2 module are focusing the layer2 traffic
 153
 154 **layer2** is a filter which match when the traffic is in layer2
 155 **mac** is a filter, it accept 2 parameters. and it will match the dst and src mac addresses.
 156
 157     e.g. ipfw3 add allow all mac 11:11:11:11:11:11 22:22:22:22:22:22
 158 *it will match the traffic which destination mac is 11:11:11:11:11:11, and soruce mac address is 22:22:22:22:22:22*
 159
 160 **mac-type**
 161
 162 **mac-from**
 163
 164 **mac-to**
 165
 166 **src-port** is a filter which match the source port.
 167
 168 **dst-port** is a filter which match the destination port.
 169
 170 ### Layer4
 171 Layer4 module contains the filters which can be used to match base on Layer4 features. like TCP, UDP, the ICMP also included in this module.
 172 **tcpflag**
 173
 174 **uid**
 175
 176 **gid**
 177
 178 **established**
 179
 180 ### Layer7
 181 under development,