· 8 years ago · May 31, 2018, 07:20 AM
1IPFW(8) FreeBSD System Manager's Manual IPFW(8)
2
3NAME
4 ipfw -- IP firewall and traffic shaper control program
5
6SYNOPSIS
7 ipfw [-cq] add rule
8 ipfw [-acdefnNStT] [set N] {list | show} [rule | first-last ...]
9 ipfw [-f | -q] [set N] flush
10 ipfw [-q] [set N] {delete | zero | resetlog} [number ...]
11 ipfw enable
12 {firewall | altq | one_pass | debug | verbose | dyn_keepalive}
13 ipfw disable
14 {firewall | altq | one_pass | debug | verbose | dyn_keepalive}
15
16 ipfw set [disable number ...] [enable number ...]
17 ipfw set move [rule] number to number
18 ipfw set swap number number
19 ipfw set show
20
21 ipfw table number add addr[/masklen] [value]
22 ipfw table number delete addr[/masklen]
23 ipfw table number flush
24 ipfw table number list
25
26 ipfw {pipe | queue} number config config-options
27 ipfw [-s [field]] {pipe | queue} {delete | list | show} [number ...]
28
29 ipfw nat number config config-options
30
31 ipfw [-cfnNqS] [-p preproc [preproc-flags]] pathname
32
33DESCRIPTION
34 The ipfw utility is the user interface for controlling the ipfw(4) fire-
35 wall and the dummynet(4) traffic shaper in FreeBSD.
36
37 An ipfw configuration, or ruleset, is made of a list of rules numbered
38 from 1 to 65535. Packets are passed to ipfw from a number of different
39 places in the protocol stack (depending on the source and destination of
40 the packet, it is possible that ipfw is invoked multiple times on the
41 same packet). The packet passed to the firewall is compared against each
42 of the rules in the firewall ruleset. When a match is found, the action
43 corresponding to the matching rule is performed.
44
45 Depending on the action and certain system settings, packets can be rein-
46 jected into the firewall at some rule after the matching one for further
47 processing.
48
49 An ipfw ruleset always includes a default rule (numbered 65535) which
50 cannot be modified or deleted, and matches all packets. The action asso-
51 ciated with the default rule can be either deny or allow depending on how
52 the kernel is configured.
53
54 If the ruleset includes one or more rules with the keep-state or limit
55 option, then ipfw assumes a stateful behaviour, i.e., upon a match it
56 will create dynamic rules matching the exact parameters (addresses and
57 ports) of the matching packet.
58
59 These dynamic rules, which have a limited lifetime, are checked at the
60 first occurrence of a check-state, keep-state or limit rule, and are typ-
61 ically used to open the firewall on-demand to legitimate traffic only.
62 See the STATEFUL FIREWALL and EXAMPLES Sections below for more informa-
63 tion on the stateful behaviour of ipfw.
64
65 All rules (including dynamic ones) have a few associated counters: a
66 packet count, a byte count, a log count and a timestamp indicating the
67 time of the last match. Counters can be displayed or reset with ipfw
68 commands.
69
70 Rules can be added with the add command; deleted individually or in
71 groups with the delete command, and globally (except those in set 31)
72 with the flush command; displayed, optionally with the content of the
73 counters, using the show and list commands. Finally, counters can be
74 reset with the zero and resetlog commands.
75
76 Also, each rule belongs to one of 32 different sets , and there are ipfw
77 commands to atomically manipulate sets, such as enable, disable, swap
78 sets, move all rules in a set to another one, delete all rules in a set.
79 These can be useful to install temporary configurations, or to test them.
80 See Section SETS OF RULES for more information on sets.
81
82 The following options are available:
83
84 -a While listing, show counter values. The show command just
85 implies this option.
86
87 -b Only show the action and the comment, not the body of a rule.
88 Implies -c.
89
90 -c When entering or showing rules, print them in compact form, i.e.,
91 without the optional "ip from any to any" string when this does
92 not carry any additional information.
93
94 -d While listing, show dynamic rules in addition to static ones.
95
96 -e While listing, if the -d option was specified, also show expired
97 dynamic rules.
98
99 -f Do not ask for confirmation for commands that can cause problems
100 if misused, i.e. flush. If there is no tty associated with the
101 process, this is implied.
102
103 -i While listing a table (see the LOOKUP TABLES section below for
104 more information on lookup tables), format values as IP
105 addresses. By default, values are shown as integers.
106
107 -n Only check syntax of the command strings, without actually pass-
108 ing them to the kernel.
109
110 -N Try to resolve addresses and service names in output.
111
112 -q While adding, zeroing, resetlogging or flushing, be quiet about
113 actions (implies -f). This is useful for adjusting rules by exe-
114 cuting multiple ipfw commands in a script (e.g.,
115 `sh /etc/rc.firewall'), or by processing a file of many ipfw
116 rules across a remote login session. It also stops a table add
117 or delete from failing if the entry already exists or is not
118 present. If a flush is performed in normal (verbose) mode (with
119 the default kernel configuration), it prints a message. Because
120 all rules are flushed, the message might not be delivered to the
121 login session, causing the remote login session to be closed and
122 the remainder of the ruleset to not be processed. Access to the
123 console would then be required to recover.
124
125 -S While listing rules, show the set each rule belongs to. If this
126 flag is not specified, disabled rules will not be listed.
127
128 -s [field]
129 While listing pipes, sort according to one of the four counters
130 (total or current packets or bytes).
131
132 -t While listing, show last match timestamp (converted with
133 ctime()).
134
135 -T While listing, show last match timestamp (as seconds from the
136 epoch). This form can be more convenient for postprocessing by
137 scripts.
138
139 To ease configuration, rules can be put into a file which is processed
140 using ipfw as shown in the last synopsis line. An absolute pathname must
141 be used. The file will be read line by line and applied as arguments to
142 the ipfw utility.
143
144 Optionally, a preprocessor can be specified using -p preproc where
145 pathname is to be piped through. Useful preprocessors include cpp(1) and
146 m4(1). If preproc does not start with a slash (`/') as its first charac-
147 ter, the usual PATH name search is performed. Care should be taken with
148 this in environments where not all file systems are mounted (yet) by the
149 time ipfw is being run (e.g. when they are mounted over NFS). Once -p
150 has been specified, any additional arguments as passed on to the pre-
151 processor for interpretation. This allows for flexible configuration
152 files (like conditionalizing them on the local hostname) and the use of
153 macros to centralize frequently required arguments like IP addresses.
154
155 The ipfw pipe and queue commands are used to configure the traffic
156 shaper, as shown in the TRAFFIC SHAPER (DUMMYNET) CONFIGURATION Section
157 below.
158
159 If the world and the kernel get out of sync the ipfw ABI may break, pre-
160 venting you from being able to add any rules. This can adversely effect
161 the booting process. You can use ipfw disable firewall to temporarily
162 disable the firewall to regain access to the network, allowing you to fix
163 the problem.
164
165PACKET FLOW
166 A packet is checked against the active ruleset in multiple places in the
167 protocol stack, under control of several sysctl variables. These places
168 and variables are shown below, and it is important to have this picture
169 in mind in order to design a correct ruleset.
170
171 ^ to upper layers V
172 | |
173 +----------->-----------+
174 ^ V
175 [ip(6)_input] [ip(6)_output] net.inet(6).ip(6).fw.enable=1
176 | |
177 ^ V
178 [ether_demux] [ether_output_frame] net.link.ether.ipfw=1
179 | |
180 +-->--[bdg_forward]-->--+ net.link.bridge.ipfw=1
181 ^ V
182 | to devices |
183
184 As can be noted from the above picture, the number of times the same
185 packet goes through the firewall can vary between 0 and 4 depending on
186 packet source and destination, and system configuration.
187
188 Note that as packets flow through the stack, headers can be stripped or
189 added to it, and so they may or may not be available for inspection.
190 E.g., incoming packets will include the MAC header when ipfw is invoked
191 from ether_demux(), but the same packets will have the MAC header
192 stripped off when ipfw is invoked from ip_input() or ip6_input().
193
194 Also note that each packet is always checked against the complete rule-
195 set, irrespective of the place where the check occurs, or the source of
196 the packet. If a rule contains some match patterns or actions which are
197 not valid for the place of invocation (e.g. trying to match a MAC header
198 within ip_input or ip6_input ), the match pattern will not match, but a
199 not operator in front of such patterns will cause the pattern to always
200 match on those packets. It is thus the responsibility of the programmer,
201 if necessary, to write a suitable ruleset to differentiate among the pos-
202 sible places. skipto rules can be useful here, as an example:
203
204 # packets from ether_demux or bdg_forward
205 ipfw add 10 skipto 1000 all from any to any layer2 in
206 # packets from ip_input
207 ipfw add 10 skipto 2000 all from any to any not layer2 in
208 # packets from ip_output
209 ipfw add 10 skipto 3000 all from any to any not layer2 out
210 # packets from ether_output_frame
211 ipfw add 10 skipto 4000 all from any to any layer2 out
212
213 (yes, at the moment there is no way to differentiate between ether_demux
214 and bdg_forward).
215
216SYNTAX
217 In general, each keyword or argument must be provided as a separate com-
218 mand line argument, with no leading or trailing spaces. Keywords are
219 case-sensitive, whereas arguments may or may not be case-sensitive
220 depending on their nature (e.g. uid's are, hostnames are not).
221
222 In ipfw2 you can introduce spaces after commas ',' to make the line more
223 readable. You can also put the entire command (including flags) into a
224 single argument. E.g., the following forms are equivalent:
225
226 ipfw -q add deny src-ip 10.0.0.0/24,127.0.0.1/8
227 ipfw -q add deny src-ip 10.0.0.0/24, 127.0.0.1/8
228 ipfw "-q add deny src-ip 10.0.0.0/24, 127.0.0.1/8"
229
230RULE FORMAT
231 The format of ipfw rules is the following:
232
233 [rule_number] [set set_number] [prob match_probability] action
234 [log [logamount number]] [altq queue] [{tag | untag} number] body
235
236 where the body of the rule specifies which information is used for fil-
237 tering packets, among the following:
238
239 Layer-2 header fields When available
240 IPv4 and IPv6 Protocol TCP, UDP, ICMP, etc.
241 Source and dest. addresses and ports
242 Direction See Section PACKET FLOW
243 Transmit and receive interface By name or address
244 Misc. IP header fields Version, type of service, data-
245 gram length, identification,
246 fragment flag (non-zero IP off-
247 set), Time To Live
248 IP options
249 IPv6 Extension headers Fragmentation, Hop-by-Hop
250 options, Routing Headers, Source
251 routing rthdr0, Mobile IPv6
252 rthdr2, IPSec options.
253 IPv6 Flow-ID
254 Misc. TCP header fields TCP flags (SYN, FIN, ACK, RST,
255 etc.), sequence number, acknowl-
256 edgment number, window
257 TCP options
258 ICMP types for ICMP packets
259 ICMP6 types for ICMP6 packets
260 User/group ID When the packet can be associ-
261 ated with a local socket.
262 Divert status Whether a packet came from a
263 divert socket (e.g., natd(8)).
264 Fib annotation state Whether a packet has been tagged
265 for using a specific FIB (rout-
266 ing table) in future forwarding
267 decisions.
268
269 Note that some of the above information, e.g. source MAC or IP addresses
270 and TCP/UDP ports, could easily be spoofed, so filtering on those fields
271 alone might not guarantee the desired results.
272
273 rule_number
274 Each rule is associated with a rule_number in the range 1..65535,
275 with the latter reserved for the default rule. Rules are checked
276 sequentially by rule number. Multiple rules can have the same
277 number, in which case they are checked (and listed) according to
278 the order in which they have been added. If a rule is entered
279 without specifying a number, the kernel will assign one in such a
280 way that the rule becomes the last one before the default rule.
281 Automatic rule numbers are assigned by incrementing the last non-
282 default rule number by the value of the sysctl variable
283 net.inet.ip.fw.autoinc_step which defaults to 100. If this is
284 not possible (e.g. because we would go beyond the maximum allowed
285 rule number), the number of the last non-default value is used
286 instead.
287
288 set set_number
289 Each rule is associated with a set_number in the range 0..31.
290 Sets can be individually disabled and enabled, so this parameter
291 is of fundamental importance for atomic ruleset manipulation. It
292 can be also used to simplify deletion of groups of rules. If a
293 rule is entered without specifying a set number, set 0 will be
294 used.
295 Set 31 is special in that it cannot be disabled, and rules in set
296 31 are not deleted by the ipfw flush command (but you can delete
297 them with the ipfw delete set 31 command). Set 31 is also used
298 for the default rule.
299
300 prob match_probability
301 A match is only declared with the specified probability (floating
302 point number between 0 and 1). This can be useful for a number
303 of applications such as random packet drop or (in conjunction
304 with dummynet(4)) to simulate the effect of multiple paths lead-
305 ing to out-of-order packet delivery.
306
307 Note: this condition is checked before any other condition,
308 including ones such as keep-state or check-state which might have
309 side effects.
310
311 log [logamount number]
312 When a packet matches a rule with the log keyword, a message will
313 be logged to syslogd(8) with a LOG_SECURITY facility. The log-
314 ging only occurs if the sysctl variable net.inet.ip.fw.verbose is
315 set to 1 (which is the default when the kernel is compiled with
316 IPFIREWALL_VERBOSE) and the number of packets logged so far for
317 that particular rule does not exceed the logamount parameter. If
318 no logamount is specified, the limit is taken from the sysctl
319 variable net.inet.ip.fw.verbose_limit. In both cases, a value of
320 0 removes the logging limit.
321
322 Once the limit is reached, logging can be re-enabled by clearing
323 the logging counter or the packet counter for that entry, see the
324 resetlog command.
325
326 Note: logging is done after all other packet matching conditions
327 have been successfully verified, and before performing the final
328 action (accept, deny, etc.) on the packet.
329
330 tag number
331 When a packet matches a rule with the tag keyword, the numeric
332 tag for the given number in the range 1..65534 will be attached
333 to the packet. The tag acts as an internal marker (it is not
334 sent out over the wire) that can be used to identify these pack-
335 ets later on. This can be used, for example, to provide trust
336 between interfaces and to start doing policy-based filtering. A
337 packet can have mutiple tags at the same time. Tags are
338 "sticky", meaning once a tag is applied to a packet by a matching
339 rule it exists until explicit removal. Tags are kept with the
340 packet everywhere within the kernel, but are lost when packet
341 leaves the kernel, for example, on transmitting packet out to the
342 network or sending packet to a divert(4) socket.
343
344 To check for previously applied tags, use the tagged rule option.
345 To delete previously applied tag, use the untag keyword.
346
347 Note: since tags are kept with the packet everywhere in ker-
348 nelspace, they can be set and unset anywhere in kernel network
349 subsystem (using mbuf_tags(9) facility), not only by means of
350 ipfw(4) tag and untag keywords. For example, there can be a spe-
351 cialized netgraph(4) node doing traffic analyzing and tagging for
352 later inspecting in firewall.
353
354 untag number
355 When a packet matches a rule with the untag keyword, the tag with
356 the number number is searched among the tags attached to this
357 packet and, if found, removed from it. Other tags bound to
358 packet, if present, are left untouched.
359
360 altq queue
361 When a packet matches a rule with the altq keyword, the ALTQ
362 identifier for the given queue (see altq(4)) will be attached.
363 Note that this ALTQ tag is only meaningful for packets going
364 "out" of IPFW, and not being rejected or going to divert sockets.
365 Note that if there is insufficient memory at the time the packet
366 is processed, it will not be tagged, so it is wise to make your
367 ALTQ "default" queue policy account for this. If multiple altq
368 rules match a single packet, only the first one adds the ALTQ
369 classification tag. In doing so, traffic may be shaped by using
370 count altq queue rules for classification early in the ruleset,
371 then later applying the filtering decision. For example,
372 check-state and keep-state rules may come later and provide the
373 actual filtering decisions in addition to the fallback ALTQ tag.
374
375 You must run pfctl(8) to set up the queues before IPFW will be
376 able to look them up by name, and if the ALTQ disciplines are
377 rearranged, the rules in containing the queue identifiers in the
378 kernel will likely have gone stale and need to be reloaded.
379 Stale queue identifiers will probably result in misclassifica-
380 tion.
381
382 All system ALTQ processing can be turned on or off via ipfw
383 enable altq and ipfw disable altq. The usage of
384 net.inet.ip.fw.one_pass is irrelevant to ALTQ traffic shaping, as
385 the actual rule action is followed always after adding an ALTQ
386 tag.
387
388 RULE ACTIONS
389 A rule can be associated with one of the following actions, which will be
390 executed when the packet matches the body of the rule.
391
392 allow | accept | pass | permit
393 Allow packets that match rule. The search terminates.
394
395 check-state
396 Checks the packet against the dynamic ruleset. If a match is
397 found, execute the action associated with the rule which gener-
398 ated this dynamic rule, otherwise move to the next rule.
399 Check-state rules do not have a body. If no check-state rule is
400 found, the dynamic ruleset is checked at the first keep-state or
401 limit rule.
402
403 count Update counters for all packets that match rule. The search con-
404 tinues with the next rule.
405
406 deny | drop
407 Discard packets that match this rule. The search terminates.
408
409 divert port
410 Divert packets that match this rule to the divert(4) socket bound
411 to port port. The search terminates.
412
413 fwd | forward ipaddr | tablearg[,port]
414 Change the next-hop on matching packets to ipaddr, which can be
415 an IP address or a host name. The next hop can also be supplied
416 by the last table looked up for the packet by using the tablearg
417 keyword instead of an explicit address. The search terminates if
418 this rule matches.
419
420 If ipaddr is a local address, then matching packets will be for-
421 warded to port (or the port number in the packet if one is not
422 specified in the rule) on the local machine.
423 If ipaddr is not a local address, then the port number (if speci-
424 fied) is ignored, and the packet will be forwarded to the remote
425 address, using the route as found in the local routing table for
426 that IP.
427 A fwd rule will not match layer-2 packets (those received on
428 ether_input, ether_output, or bridged).
429 The fwd action does not change the contents of the packet at all.
430 In particular, the destination address remains unmodified, so
431 packets forwarded to another system will usually be rejected by
432 that system unless there is a matching rule on that system to
433 capture them. For packets forwarded locally, the local address
434 of the socket will be set to the original destination address of
435 the packet. This makes the netstat(1) entry look rather weird
436 but is intended for use with transparent proxy servers.
437
438 To enable fwd a custom kernel needs to be compiled with the
439 option options IPFIREWALL_FORWARD.
440
441 nat nat_nr
442 Pass packet to a nat instance (for network address translation,
443 address redirect, etc.): see the NETWORK ADDRESS TRANSLATION
444 (NAT) Section for further information.
445
446 pipe pipe_nr
447 Pass packet to a dummynet(4) ``pipe'' (for bandwidth limitation,
448 delay, etc.). See the TRAFFIC SHAPER (DUMMYNET) CONFIGURATION
449 Section for further information. The search terminates; however,
450 on exit from the pipe and if the sysctl(8) variable
451 net.inet.ip.fw.one_pass is not set, the packet is passed again to
452 the firewall code starting from the next rule.
453
454 queue queue_nr
455 Pass packet to a dummynet(4) ``queue'' (for bandwidth limitation
456 using WF2Q+).
457
458 reject (Deprecated). Synonym for unreach host.
459
460 reset Discard packets that match this rule, and if the packet is a TCP
461 packet, try to send a TCP reset (RST) notice. The search termi-
462 nates.
463
464 reset6 Discard packets that match this rule, and if the packet is a TCP
465 packet, try to send a TCP reset (RST) notice. The search termi-
466 nates.
467
468 skipto number | tablearg
469 Skip all subsequent rules numbered less than number. The search
470 continues with the first rule numbered number or higher. It is
471 possible to use the tablearg keyword with a skipto for a computed
472 skipto, but care should be used, as no destination caching is
473 possible in this case so the rules are always walked to find it,
474 starting from the skipto.
475
476 tee port
477 Send a copy of packets matching this rule to the divert(4) socket
478 bound to port port. The search continues with the next rule.
479
480 unreach code
481 Discard packets that match this rule, and try to send an ICMP
482 unreachable notice with code code, where code is a number from 0
483 to 255, or one of these aliases: net, host, protocol, port,
484 needfrag, srcfail, net-unknown, host-unknown, isolated,
485 net-prohib, host-prohib, tosnet, toshost, filter-prohib,
486 host-precedence or precedence-cutoff. The search terminates.
487
488 unreach6 code
489 Discard packets that match this rule, and try to send an ICMPv6
490 unreachable notice with code code, where code is a number from 0,
491 1, 3 or 4, or one of these aliases: no-route, admin-prohib,
492 address or port. The search terminates.
493
494 netgraph cookie
495 Divert packet into netgraph with given cookie. The search termi-
496 nates. If packet is later returned from netgraph it is either
497 accepted or continues with the next rule, depending on
498 net.inet.ip.fw.one_pass sysctl variable.
499
500 ngtee cookie
501 A copy of packet is diverted into netgraph, original packet is
502 either accepted or continues with the next rule, depending on
503 net.inet.ip.fw.one_pass sysctl variable. See ng_ipfw(4) for more
504 information on netgraph and ngtee actions.
505
506 setfib fibnum
507 The packet is tagged so as to use the FIB (routing table) fibnum
508 in any subsequent forwarding decisions. Initially this is limited
509 to the values 0 through 15. See setfib(8). Processing continues
510 at the next rule.
511
512 RULE BODY
513 The body of a rule contains zero or more patterns (such as specific
514 source and destination addresses or ports, protocol options, incoming or
515 outgoing interfaces, etc.) that the packet must match in order to be
516 recognised. In general, the patterns are connected by (implicit) and
517 operators -- i.e., all must match in order for the rule to match. Indi-
518 vidual patterns can be prefixed by the not operator to reverse the result
519 of the match, as in
520
521 ipfw add 100 allow ip from not 1.2.3.4 to any
522
523 Additionally, sets of alternative match patterns (or-blocks) can be con-
524 structed by putting the patterns in lists enclosed between parentheses (
525 ) or braces { }, and using the or operator as follows:
526
527 ipfw add 100 allow ip from { x or not y or z } to any
528
529 Only one level of parentheses is allowed. Beware that most shells have
530 special meanings for parentheses or braces, so it is advisable to put a
531 backslash \ in front of them to prevent such interpretations.
532
533 The body of a rule must in general include a source and destination
534 address specifier. The keyword any can be used in various places to
535 specify that the content of a required field is irrelevant.
536
537 The rule body has the following format:
538
539 [proto from src to dst] [options]
540
541 The first part (proto from src to dst) is for backward compatibility with
542 earlier versions of FreeBSD. In modern FreeBSD any match pattern
543 (including MAC headers, IP protocols, addresses and ports) can be speci-
544 fied in the options section.
545
546 Rule fields have the following meaning:
547
548 proto: protocol | { protocol or ... }
549
550 protocol: [not] protocol-name | protocol-number
551 An IP protocol specified by number or name (for a complete list
552 see /etc/protocols), or one of the following keywords:
553
554 ip4 | ipv4
555 Matches IPv4 packets.
556
557 ip6 | ipv6
558 Matches IPv6 packets.
559
560 ip | all
561 Matches any packet.
562
563 The ipv6 in proto option will be treated as inner protocol. And,
564 the ipv4 is not available in proto option.
565
566 The { protocol or ... } format (an or-block) is provided for con-
567 venience only but its use is deprecated.
568
569 src and dst: {addr | { addr or ... }} [[not] ports]
570 An address (or a list, see below) optionally followed by ports
571 specifiers.
572
573 The second format (or-block with multiple addresses) is provided
574 for convenience only and its use is discouraged.
575
576 addr: [not] {any | me | me6 | table(number[,value]) | addr-list |
577 addr-set}
578
579 any matches any IP address.
580
581 me matches any IP address configured on an interface in the system.
582
583 me6 matches any IPv6 address configured on an interface in the sys-
584 tem. The address list is evaluated at the time the packet is an-
585 alysed.
586
587 table(number[,value])
588 Matches any IPv4 address for which an entry exists in the lookup
589 table number. If an optional 32-bit unsigned value is also spec-
590 ified, an entry will match only if it has this value. See the
591 LOOKUP TABLES section below for more information on lookup
592 tables.
593
594 addr-list: ip-addr[,addr-list]
595
596 ip-addr:
597 A host or subnet address specified in one of the following ways:
598
599 numeric-ip | hostname
600 Matches a single IPv4 address, specified as dotted-quad
601 or a hostname. Hostnames are resolved at the time the
602 rule is added to the firewall list.
603
604 addr/masklen
605 Matches all addresses with base addr (specified as an IP
606 address, a network number, or a hostname) and mask width
607 of masklen bits. As an example, 1.2.3.4/25 or 1.2.3.0/25
608 will match all IP numbers from 1.2.3.0 to 1.2.3.127 .
609
610 addr:mask
611 Matches all addresses with base addr (specified as an IP
612 address, a network number, or a hostname) and the mask of
613 mask, specified as a dotted quad. As an example,
614 1.2.3.4:255.0.255.0 or 1.0.3.0:255.0.255.0 will match
615 1.*.3.*. This form is advised only for non-contiguous
616 masks. It is better to resort to the addr/masklen format
617 for contiguous masks, which is more compact and less
618 error-prone.
619
620 addr-set: addr[/masklen]{list}
621
622 list: {num | num-num}[,list]
623 Matches all addresses with base address addr (specified as an IP
624 address, a network number, or a hostname) and whose last byte is
625 in the list between braces { } . Note that there must be no spa-
626 ces between braces and numbers (spaces after commas are allowed).
627 Elements of the list can be specified as single entries or
628 ranges. The masklen field is used to limit the size of the set
629 of addresses, and can have any value between 24 and 32. If not
630 specified, it will be assumed as 24.
631 This format is particularly useful to handle sparse address sets
632 within a single rule. Because the matching occurs using a bit-
633 mask, it takes constant time and dramatically reduces the com-
634 plexity of rulesets.
635 As an example, an address specified as 1.2.3.4/24{128,35-55,89}
636 or 1.2.3.0/24{128,35-55,89} will match the following IP
637 addresses:
638 1.2.3.128, 1.2.3.35 to 1.2.3.55, 1.2.3.89 .
639
640 addr6-list: ip6-addr[,addr6-list]
641
642 ip6-addr:
643 A host or subnet specified one of the following ways:
644
645 numeric-ip | hostname
646 Matches a single IPv6 address as allowed by inet_pton(3)
647 or a hostname. Hostnames are resolved at the time the
648 rule is added to the firewall list.
649
650 addr/masklen
651 Matches all IPv6 addresses with base addr (specified as
652 allowed by inet_pton or a hostname) and mask width of
653 masklen bits.
654
655 No support for sets of IPv6 addresses is provided because IPv6
656 addresses are typically random past the initial prefix.
657
658 ports: {port | port-port}[,ports]
659 For protocols which support port numbers (such as TCP and UDP),
660 optional ports may be specified as one or more ports or port
661 ranges, separated by commas but no spaces, and an optional not
662 operator. The `-' notation specifies a range of ports (including
663 boundaries).
664
665 Service names (from /etc/services) may be used instead of numeric
666 port values. The length of the port list is limited to 30 ports
667 or ranges, though one can specify larger ranges by using an
668 or-block in the options section of the rule.
669
670 A backslash (`\') can be used to escape the dash (`-') character
671 in a service name (from a shell, the backslash must be typed
672 twice to avoid the shell itself interpreting it as an escape
673 character).
674
675 ipfw add count tcp from any ftp\\-data-ftp to any
676
677 Fragmented packets which have a non-zero offset (i.e., not the
678 first fragment) will never match a rule which has one or more
679 port specifications. See the frag option for details on matching
680 fragmented packets.
681
682 RULE OPTIONS (MATCH PATTERNS)
683 Additional match patterns can be used within rules. Zero or more of
684 these so-called options can be present in a rule, optionally prefixed by
685 the not operand, and possibly grouped into or-blocks.
686
687 The following match patterns can be used (listed in alphabetical order):
688
689 // this is a comment.
690 Inserts the specified text as a comment in the rule. Everything
691 following // is considered as a comment and stored in the rule.
692 You can have comment-only rules, which are listed as having a
693 count action followed by the comment.
694
695 bridged
696 Alias for layer2.
697
698 diverted
699 Matches only packets generated by a divert socket.
700
701 diverted-loopback
702 Matches only packets coming from a divert socket back into the IP
703 stack input for delivery.
704
705 diverted-output
706 Matches only packets going from a divert socket back outward to
707 the IP stack output for delivery.
708
709 dst-ip ip-address
710 Matches IPv4 packets whose destination IP is one of the
711 address(es) specified as argument.
712
713 {dst-ip6 | dst-ipv6} ip6-address
714 Matches IPv6 packets whose destination IP is one of the
715 address(es) specified as argument.
716
717 dst-port ports
718 Matches IP packets whose destination port is one of the port(s)
719 specified as argument.
720
721 established
722 Matches TCP packets that have the RST or ACK bits set.
723
724 ext6hdr header
725 Matches IPv6 packets containing the extended header given by
726 header. Supported headers are:
727
728 Fragment, (frag), Hop-to-hop options (hopopt), any type of Rout-
729 ing Header (route), Source routing Routing Header Type 0
730 (rthdr0), Mobile IPv6 Routing Header Type 2 (rthdr2), Destination
731 options (dstopt), IPSec authentication headers (ah), and IPSec
732 encapsulated security payload headers (esp).
733
734 fib fibnum
735 Matches a packet that has been tagged to use the given FIB (rout-
736 ing table) number.
737
738 flow-id labels
739 Matches IPv6 packets containing any of the flow labels given in
740 labels. labels is a comma seperate list of numeric flow labels.
741
742 frag Matches packets that are fragments and not the first fragment of
743 an IP datagram. Note that these packets will not have the next
744 protocol header (e.g. TCP, UDP) so options that look into these
745 headers cannot match.
746
747 gid group
748 Matches all TCP or UDP packets sent by or received for a group.
749 A group may be specified by name or number.
750
751 jail prisonID
752 Matches all TCP or UDP packets sent by or received for the jail
753 whos prison ID is prisonID.
754
755 icmptypes types
756 Matches ICMP packets whose ICMP type is in the list types. The
757 list may be specified as any combination of individual types
758 (numeric) separated by commas. Ranges are not allowed. The sup-
759 ported ICMP types are:
760
761 echo reply (0), destination unreachable (3), source quench (4),
762 redirect (5), echo request (8), router advertisement (9), router
763 solicitation (10), time-to-live exceeded (11), IP header bad
764 (12), timestamp request (13), timestamp reply (14), information
765 request (15), information reply (16), address mask request (17)
766 and address mask reply (18).
767
768 icmp6types types
769 Matches ICMP6 packets whose ICMP6 type is in the list of types.
770 The list may be specified as any combination of individual types
771 (numeric) separated by commas. Ranges are not allowed.
772
773 in | out
774 Matches incoming or outgoing packets, respectively. in and out
775 are mutually exclusive (in fact, out is implemented as not in).
776
777 ipid id-list
778 Matches IPv4 packets whose ip_id field has value included in
779 id-list, which is either a single value or a list of values or
780 ranges specified in the same way as ports.
781
782 iplen len-list
783 Matches IP packets whose total length, including header and data,
784 is in the set len-list, which is either a single value or a list
785 of values or ranges specified in the same way as ports.
786
787 ipoptions spec
788 Matches packets whose IPv4 header contains the comma separated
789 list of options specified in spec. The supported IP options are:
790
791 ssrr (strict source route), lsrr (loose source route), rr (record
792 packet route) and ts (timestamp). The absence of a particular
793 option may be denoted with a `!'.
794
795 ipprecedence precedence
796 Matches IPv4 packets whose precedence field is equal to
797 precedence.
798
799 ipsec Matches packets that have IPSEC history associated with them
800 (i.e., the packet comes encapsulated in IPSEC, the kernel has
801 IPSEC support and IPSEC_FILTERTUNNEL option, and can correctly
802 decapsulate it).
803
804 Note that specifying ipsec is different from specifying proto
805 ipsec as the latter will only look at the specific IP protocol
806 field, irrespective of IPSEC kernel support and the validity of
807 the IPSEC data.
808
809 Further note that this flag is silently ignored in kernels with-
810 out IPSEC support. It does not affect rule processing when given
811 and the rules are handled as if with no ipsec flag.
812
813 iptos spec
814 Matches IPv4 packets whose tos field contains the comma separated
815 list of service types specified in spec. The supported IP types
816 of service are:
817
818 lowdelay (IPTOS_LOWDELAY), throughput (IPTOS_THROUGHPUT),
819 reliability (IPTOS_RELIABILITY), mincost (IPTOS_MINCOST),
820 congestion (IPTOS_CE). The absence of a particular type may be
821 denoted with a `!'.
822
823 ipttl ttl-list
824 Matches IPv4 packets whose time to live is included in ttl-list,
825 which is either a single value or a list of values or ranges
826 specified in the same way as ports.
827
828 ipversion ver
829 Matches IP packets whose IP version field is ver.
830
831 keep-state
832 Upon a match, the firewall will create a dynamic rule, whose
833 default behaviour is to match bidirectional traffic between
834 source and destination IP/port using the same protocol. The rule
835 has a limited lifetime (controlled by a set of sysctl(8) vari-
836 ables), and the lifetime is refreshed every time a matching
837 packet is found.
838
839 layer2 Matches only layer2 packets, i.e., those passed to ipfw from
840 ether_demux() and ether_output_frame().
841
842 limit {src-addr | src-port | dst-addr | dst-port} N
843 The firewall will only allow N connections with the same set of
844 parameters as specified in the rule. One or more of source and
845 destination addresses and ports can be specified. Currently,
846 only IPv4 flows are supported.
847
848 { MAC | mac } dst-mac src-mac
849 Match packets with a given dst-mac and src-mac addresses, speci-
850 fied as the any keyword (matching any MAC address), or six groups
851 of hex digits separated by colons, and optionally followed by a
852 mask indicating the significant bits. The mask may be specified
853 using either of the following methods:
854
855 1. A slash (/) followed by the number of significant bits.
856 For example, an address with 33 significant bits could be
857 specified as:
858
859 MAC 10:20:30:40:50:60/33 any
860
861 2. An ampersand (&) followed by a bitmask specified as six
862 groups of hex digits separated by colons. For example,
863 an address in which the last 16 bits are significant
864 could be specified as:
865
866 MAC 10:20:30:40:50:60&00:00:00:00:ff:ff any
867
868 Note that the ampersand character has a special meaning
869 in many shells and should generally be escaped.
870
871 Note that the order of MAC addresses (destination first, source
872 second) is the same as on the wire, but the opposite of the one
873 used for IP addresses.
874
875 mac-type mac-type
876 Matches packets whose Ethernet Type field corresponds to one of
877 those specified as argument. mac-type is specified in the same
878 way as port numbers (i.e., one or more comma-separated single
879 values or ranges). You can use symbolic names for known values
880 such as vlan, ipv4, ipv6. Values can be entered as decimal or
881 hexadecimal (if prefixed by 0x), and they are always printed as
882 hexadecimal (unless the -N option is used, in which case symbolic
883 resolution will be attempted).
884
885 proto protocol
886 Matches packets with the corresponding IP protocol.
887
888 recv | xmit | via {ifX | if* | ipno | any}
889 Matches packets received, transmitted or going through, respec-
890 tively, the interface specified by exact name (ifX), by device
891 name (if*), by IP address, or through some interface.
892
893 The via keyword causes the interface to always be checked. If
894 recv or xmit is used instead of via, then only the receive or
895 transmit interface (respectively) is checked. By specifying
896 both, it is possible to match packets based on both receive and
897 transmit interface, e.g.:
898
899 ipfw add deny ip from any to any out recv ed0 xmit ed1
900
901 The recv interface can be tested on either incoming or outgoing
902 packets, while the xmit interface can only be tested on outgoing
903 packets. So out is required (and in is invalid) whenever xmit is
904 used.
905
906 A packet may not have a receive or transmit interface: packets
907 originating from the local host have no receive interface, while
908 packets destined for the local host have no transmit interface.
909
910 setup Matches TCP packets that have the SYN bit set but no ACK bit.
911 This is the short form of ``tcpflags syn,!ack''.
912
913 src-ip ip-address
914 Matches IPv4 packets whose source IP is one of the address(es)
915 specified as an argument.
916
917 src-ip6 ip6-address
918 Matches IPv6 packets whose source IP is one of the address(es)
919 specified as an argument.
920
921 src-port ports
922 Matches IP packets whose source port is one of the port(s) speci-
923 fied as argument.
924
925 tagged tag-list
926 Matches packets whose tags are included in tag-list, which is
927 either a single value or a list of values or ranges specified in
928 the same way as ports. Tags can be applied to the packet using
929 tag rule action parameter (see it's description for details on
930 tags).
931
932 tcpack ack
933 TCP packets only. Match if the TCP header acknowledgment number
934 field is set to ack.
935
936 tcpdatalen tcpdatalen-list
937 Matches TCP packets whose length of TCP data is tcpdatalen-list,
938 which is either a single value or a list of values or ranges
939 specified in the same way as ports.
940
941 tcpflags spec
942 TCP packets only. Match if the TCP header contains the comma
943 separated list of flags specified in spec. The supported TCP
944 flags are:
945
946 fin, syn, rst, psh, ack and urg. The absence of a particular
947 flag may be denoted with a `!'. A rule which contains a tcpflags
948 specification can never match a fragmented packet which has a
949 non-zero offset. See the frag option for details on matching
950 fragmented packets.
951
952 tcpseq seq
953 TCP packets only. Match if the TCP header sequence number field
954 is set to seq.
955
956 tcpwin win
957 TCP packets only. Match if the TCP header window field is set to
958 win.
959
960 tcpoptions spec
961 TCP packets only. Match if the TCP header contains the comma
962 separated list of options specified in spec. The supported TCP
963 options are:
964
965 mss (maximum segment size), window (tcp window advertisement),
966 sack (selective ack), ts (rfc1323 timestamp) and cc (rfc1644
967 t/tcp connection count). The absence of a particular option may
968 be denoted with a `!'.
969
970 uid user
971 Match all TCP or UDP packets sent by or received for a user. A
972 user may be matched by name or identification number.
973
974 verrevpath
975 For incoming packets, a routing table lookup is done on the
976 packet's source address. If the interface on which the packet
977 entered the system matches the outgoing interface for the route,
978 the packet matches. If the interfaces do not match up, the
979 packet does not match. All outgoing packets or packets with no
980 incoming interface match.
981
982 The name and functionality of the option is intentionally similar
983 to the Cisco IOS command:
984
985 ip verify unicast reverse-path
986
987 This option can be used to make anti-spoofing rules to reject all
988 packets with source addresses not from this interface. See also
989 the option antispoof.
990
991 versrcreach
992 For incoming packets, a routing table lookup is done on the
993 packet's source address. If a route to the source address
994 exists, but not the default route or a blackhole/reject route,
995 the packet matches. Otherwise, the packet does not match. All
996 outgoing packets match.
997
998 The name and functionality of the option is intentionally similar
999 to the Cisco IOS command:
1000
1001 ip verify unicast source reachable-via any
1002
1003 This option can be used to make anti-spoofing rules to reject all
1004 packets whose source address is unreachable.
1005
1006 antispoof
1007 For incoming packets, the packet's source address is checked if
1008 it belongs to a directly connected network. If the network is
1009 directly connected, then the interface the packet came on in is
1010 compared to the interface the network is connected to. When
1011 incoming interface and directly connected interface are not the
1012 same, the packet does not match. Otherwise, the packet does
1013 match. All outgoing packets match.
1014
1015 This option can be used to make anti-spoofing rules to reject all
1016 packets that pretend to be from a directly connected network but
1017 do not come in through that interface. This option is similar to
1018 but more restricted than verrevpath because it engages only on
1019 packets with source addresses of directly connected networks
1020 instead of all source addresses.
1021
1022LOOKUP TABLES
1023 Lookup tables are useful to handle large sparse address sets, typically
1024 from a hundred to several thousands of entries. There may be up to 128
1025 different lookup tables, numbered 0 to 127.
1026
1027 Each entry is represented by an addr[/masklen] and will match all
1028 addresses with base addr (specified as an IP address or a hostname) and
1029 mask width of masklen bits. If masklen is not specified, it defaults to
1030 32. When looking up an IP address in a table, the most specific entry
1031 will match. Associated with each entry is a 32-bit unsigned value, which
1032 can optionally be checked by a rule matching code. When adding an entry,
1033 if value is not specified, it defaults to 0.
1034
1035 An entry can be added to a table (add), removed from a table (delete), a
1036 table can be examined (list) or flushed (flush).
1037
1038 Internally, each table is stored in a Radix tree, the same way as the
1039 routing table (see route(4)).
1040
1041 Lookup tables currently support IPv4 addresses only.
1042
1043 The tablearg feature provides the ability to use a value, looked up in
1044 the table, as the argument for a rule action, action parameter or rule
1045 option. This can significantly reduce number of rules in some configura-
1046 tions. If two tables are used in a rule, the result of the second (des-
1047 tination) is used. The tablearg argument can be used with the following
1048 actions: nat, pipe, queue, divert, tee, netgraph, ngtee, fwd, skipto
1049 action parameters: tag, untag, rule options: limit, tagged.
1050
1051 When used with fwd it is possible to supply table entries with values
1052 that are in the form of IP addresses or hostnames. See the EXAMPLES Sec-
1053 tion for example usage of tables and the tablearg keyword.
1054
1055 When used with the skipto action, the user should be aware that the code
1056 will walk the ruleset up to a rule equal to, or past, the given number,
1057 and should therefore try keep the ruleset compact between the skipto and
1058 the target rules.
1059
1060SETS OF RULES
1061 Each rule belongs to one of 32 different sets , numbered 0 to 31. Set 31
1062 is reserved for the default rule.
1063
1064 By default, rules are put in set 0, unless you use the set N attribute
1065 when entering a new rule. Sets can be individually and atomically
1066 enabled or disabled, so this mechanism permits an easy way to store mul-
1067 tiple configurations of the firewall and quickly (and atomically) switch
1068 between them. The command to enable/disable sets is
1069
1070 ipfw set [disable number ...] [enable number ...]
1071
1072 where multiple enable or disable sections can be specified. Command exe-
1073 cution is atomic on all the sets specified in the command. By default,
1074 all sets are enabled.
1075
1076 When you disable a set, its rules behave as if they do not exist in the
1077 firewall configuration, with only one exception:
1078
1079 dynamic rules created from a rule before it had been disabled will
1080 still be active until they expire. In order to delete dynamic
1081 rules you have to explicitly delete the parent rule which generated
1082 them.
1083
1084 The set number of rules can be changed with the command
1085
1086 ipfw set move {rule rule-number | old-set} to new-set
1087
1088 Also, you can atomically swap two rulesets with the command
1089
1090 ipfw set swap first-set second-set
1091
1092 See the EXAMPLES Section on some possible uses of sets of rules.
1093
1094STATEFUL FIREWALL
1095 Stateful operation is a way for the firewall to dynamically create rules
1096 for specific flows when packets that match a given pattern are detected.
1097 Support for stateful operation comes through the check-state, keep-state
1098 and limit options of rules.
1099
1100 Dynamic rules are created when a packet matches a keep-state or limit
1101 rule, causing the creation of a dynamic rule which will match all and
1102 only packets with a given protocol between a src-ip/src-port
1103 dst-ip/dst-port pair of addresses (src and dst are used here only to
1104 denote the initial match addresses, but they are completely equivalent
1105 afterwards). Dynamic rules will be checked at the first check-state,
1106 keep-state or limit occurrence, and the action performed upon a match
1107 will be the same as in the parent rule.
1108
1109 Note that no additional attributes other than protocol and IP addresses
1110 and ports are checked on dynamic rules.
1111
1112 The typical use of dynamic rules is to keep a closed firewall configura-
1113 tion, but let the first TCP SYN packet from the inside network install a
1114 dynamic rule for the flow so that packets belonging to that session will
1115 be allowed through the firewall:
1116
1117 ipfw add check-state
1118 ipfw add allow tcp from my-subnet to any setup keep-state
1119 ipfw add deny tcp from any to any
1120
1121 A similar approach can be used for UDP, where an UDP packet coming from
1122 the inside will install a dynamic rule to let the response through the
1123 firewall:
1124
1125 ipfw add check-state
1126 ipfw add allow udp from my-subnet to any keep-state
1127 ipfw add deny udp from any to any
1128
1129 Dynamic rules expire after some time, which depends on the status of the
1130 flow and the setting of some sysctl variables. See Section SYSCTL
1131 VARIABLES for more details. For TCP sessions, dynamic rules can be
1132 instructed to periodically send keepalive packets to refresh the state of
1133 the rule when it is about to expire.
1134
1135 See Section EXAMPLES for more examples on how to use dynamic rules.
1136
1137TRAFFIC SHAPER (DUMMYNET) CONFIGURATION
1138 ipfw is also the user interface for the dummynet(4) traffic shaper.
1139
1140 dummynet operates by first using the firewall to classify packets and
1141 divide them into flows, using any match pattern that can be used in ipfw
1142 rules. Depending on local policies, a flow can contain packets for a
1143 single TCP connection, or from/to a given host, or entire subnet, or a
1144 protocol type, etc.
1145
1146 There are two modes of dummynet operation: normal and fast. Normal mode
1147 tries to emulate real link: dummynet scheduler ensures packet will not
1148 leave pipe faster than it would be on real link with given bandwidth.
1149 Fast mode allows certain packets to bypass dummynet scheduler (if packet
1150 flow does not exceed pipe's bandwidth). Thus fast mode requires less cpu
1151 cycles per packet (in average) but packet latency can be significantly
1152 lower comparing to real link with same bandwidth. Default is normal mode,
1153 fast mode can be enabled by setting net.inet.ip.dummynet.io_fast
1154 sysctl(8) variable to non-zero value.
1155
1156 Packets belonging to the same flow are then passed to either of two dif-
1157 ferent objects, which implement the traffic regulation:
1158
1159 pipe A pipe emulates a link with given bandwidth, propagation
1160 delay, queue size and packet loss rate. Packets are queued
1161 in front of the pipe as they come out from the classifier,
1162 and then transferred to the pipe according to the pipe's
1163 parameters.
1164
1165 queue A queue is an abstraction used to implement the WF2Q+ (Worst-
1166 case Fair Weighted Fair Queueing) policy, which is an effi-
1167 cient variant of the WFQ policy.
1168 The queue associates a weight and a reference pipe to each
1169 flow, and then all backlogged (i.e., with packets queued)
1170 flows linked to the same pipe share the pipe's bandwidth pro-
1171 portionally to their weights. Note that weights are not pri-
1172 orities; a flow with a lower weight is still guaranteed to
1173 get its fraction of the bandwidth even if a flow with a
1174 higher weight is permanently backlogged.
1175
1176 In practice, pipes can be used to set hard limits to the bandwidth that a
1177 flow can use, whereas queues can be used to determine how different flow
1178 share the available bandwidth.
1179
1180 The pipe and queue configuration commands are the following:
1181
1182 pipe number config pipe-configuration
1183
1184 queue number config queue-configuration
1185
1186 The following parameters can be configured for a pipe:
1187
1188 bw bandwidth | device
1189 Bandwidth, measured in [K|M]{bit/s|Byte/s}.
1190
1191 A value of 0 (default) means unlimited bandwidth. The unit must
1192 immediately follow the number, as in
1193
1194 ipfw pipe 1 config bw 300Kbit/s
1195
1196 If a device name is specified instead of a numeric value, as in
1197
1198 ipfw pipe 1 config bw tun0
1199
1200 then the transmit clock is supplied by the specified device. At
1201 the moment only the tun(4) device supports this functionality,
1202 for use in conjunction with ppp(8).
1203
1204 delay ms-delay
1205 Propagation delay, measured in milliseconds. The value is
1206 rounded to the next multiple of the clock tick (typically 10ms,
1207 but it is a good practice to run kernels with ``options HZ=1000''
1208 to reduce the granularity to 1ms or less). Default value is 0,
1209 meaning no delay.
1210
1211 The following parameters can be configured for a queue:
1212
1213 pipe pipe_nr
1214 Connects a queue to the specified pipe. Multiple queues (with
1215 the same or different weights) can be connected to the same pipe,
1216 which specifies the aggregate rate for the set of queues.
1217
1218 weight weight
1219 Specifies the weight to be used for flows matching this queue.
1220 The weight must be in the range 1..100, and defaults to 1.
1221
1222 Finally, the following parameters can be configured for both pipes and
1223 queues:
1224
1225 buckets hash-table-size
1226 Specifies the size of the hash table used for storing the various
1227 queues. Default value is 64 controlled by the sysctl(8) variable
1228 net.inet.ip.dummynet.hash_size, allowed range is 16 to 65536.
1229
1230 mask mask-specifier
1231 Packets sent to a given pipe or queue by an ipfw rule can be fur-
1232 ther classified into multiple flows, each of which is then sent to
1233 a different dynamic pipe or queue. A flow identifier is con-
1234 structed by masking the IP addresses, ports and protocol types as
1235 specified with the mask options in the configuration of the pipe or
1236 queue. For each different flow identifier, a new pipe or queue is
1237 created with the same parameters as the original object, and match-
1238 ing packets are sent to it.
1239
1240 Thus, when dynamic pipes are used, each flow will get the same
1241 bandwidth as defined by the pipe, whereas when dynamic queues are
1242 used, each flow will share the parent's pipe bandwidth evenly with
1243 other flows generated by the same queue (note that other queues
1244 with different weights might be connected to the same pipe).
1245 Available mask specifiers are a combination of one or more of the
1246 following:
1247
1248 dst-ip mask, dst-ip6 mask, src-ip mask, src-ip6 mask, dst-port
1249 mask, src-port mask, flow-id mask, proto mask or all,
1250
1251 where the latter means all bits in all fields are significant.
1252
1253 noerror
1254 When a packet is dropped by a dummynet queue or pipe, the error is
1255 normally reported to the caller routine in the kernel, in the same
1256 way as it happens when a device queue fills up. Setting this
1257 option reports the packet as successfully delivered, which can be
1258 needed for some experimental setups where you want to simulate loss
1259 or congestion at a remote router.
1260
1261 plr packet-loss-rate
1262 Packet loss rate. Argument packet-loss-rate is a floating-point
1263 number between 0 and 1, with 0 meaning no loss, 1 meaning 100%
1264 loss. The loss rate is internally represented on 31 bits.
1265
1266 queue {slots | sizeKbytes}
1267 Queue size, in slots or KBytes. Default value is 50 slots, which
1268 is the typical queue size for Ethernet devices. Note that for slow
1269 speed links you should keep the queue size short or your traffic
1270 might be affected by a significant queueing delay. E.g., 50 max-
1271 sized ethernet packets (1500 bytes) mean 600Kbit or 20s of queue on
1272 a 30Kbit/s pipe. Even worse effects can result if you get packets
1273 from an interface with a much larger MTU, e.g. the loopback inter-
1274 face with its 16KB packets. The sysctl(8) variables
1275 net.inet.ip.dummynet.pipe_byte_limit and
1276 net.inet.ip.dummynet.pipe_slot_limit control the maximum lengths
1277 that can be specified.
1278
1279 red | gred w_q/min_th/max_th/max_p
1280 Make use of the RED (Random Early Detection) queue management algo-
1281 rithm. w_q and max_p are floating point numbers between 0 and 1 (0
1282 not included), while min_th and max_th are integer numbers specify-
1283 ing thresholds for queue management (thresholds are computed in
1284 bytes if the queue has been defined in bytes, in slots otherwise).
1285 The dummynet(4) also supports the gentle RED variant (gred). Three
1286 sysctl(8) variables can be used to control the RED behaviour:
1287
1288 net.inet.ip.dummynet.red_lookup_depth
1289 specifies the accuracy in computing the average queue when
1290 the link is idle (defaults to 256, must be greater than
1291 zero)
1292
1293 net.inet.ip.dummynet.red_avg_pkt_size
1294 specifies the expected average packet size (defaults to
1295 512, must be greater than zero)
1296
1297 net.inet.ip.dummynet.red_max_pkt_size
1298 specifies the expected maximum packet size, only used when
1299 queue thresholds are in bytes (defaults to 1500, must be
1300 greater than zero).
1301
1302 When used with IPv6 data, dummynet currently has several limitations.
1303 Information necessary to route link-local packets to an interface is not
1304 avalable after processing by dummynet so those packets are dropped in the
1305 output path. Care should be taken to insure that link-local packets are
1306 not passed to dummynet.
1307
1308CHECKLIST
1309 Here are some important points to consider when designing your rules:
1310
1311 +o Remember that you filter both packets going in and out. Most connec-
1312 tions need packets going in both directions.
1313
1314 +o Remember to test very carefully. It is a good idea to be near the
1315 console when doing this. If you cannot be near the console, use an
1316 auto-recovery script such as the one in
1317 /usr/share/examples/ipfw/change_rules.sh.
1318
1319 +o Do not forget the loopback interface.
1320
1321FINE POINTS
1322 +o There are circumstances where fragmented datagrams are uncondition-
1323 ally dropped. TCP packets are dropped if they do not contain at
1324 least 20 bytes of TCP header, UDP packets are dropped if they do not
1325 contain a full 8 byte UDP header, and ICMP packets are dropped if
1326 they do not contain 4 bytes of ICMP header, enough to specify the
1327 ICMP type, code, and checksum. These packets are simply logged as
1328 ``pullup failed'' since there may not be enough good data in the
1329 packet to produce a meaningful log entry.
1330
1331 +o Another type of packet is unconditionally dropped, a TCP packet with
1332 a fragment offset of one. This is a valid packet, but it only has
1333 one use, to try to circumvent firewalls. When logging is enabled,
1334 these packets are reported as being dropped by rule -1.
1335
1336 +o If you are logged in over a network, loading the kld(4) version of
1337 ipfw is probably not as straightforward as you would think. I recom-
1338 mend the following command line:
1339
1340 kldload ipfw && \
1341 ipfw add 32000 allow ip from any to any
1342
1343 Along the same lines, doing an
1344
1345 ipfw flush
1346
1347 in similar surroundings is also a bad idea.
1348
1349 +o The ipfw filter list may not be modified if the system security level
1350 is set to 3 or higher (see init(8) for information on system security
1351 levels).
1352
1353PACKET DIVERSION
1354 A divert(4) socket bound to the specified port will receive all packets
1355 diverted to that port. If no socket is bound to the destination port, or
1356 if the divert module is not loaded, or if the kernel was not compiled
1357 with divert socket support, the packets are dropped.
1358
1359NETWORK ADDRESS TRANSLATION (NAT)
1360 The nat configuration command is the following:
1361
1362 nat nat_number config nat-configuration
1363
1364 The following parameters can be configured:
1365
1366 ip ip_address
1367 Define an ip address to use for aliasing.
1368
1369 if nic Use ip addres of NIC for aliasing, dynamically changing it if
1370 NIC's ip address change.
1371
1372 log Enable logging on this nat instance.
1373
1374 deny_in
1375 Deny any incoming connection from outside world.
1376
1377 same_ports
1378 Try to leave the alias port numbers unchanged from the actual
1379 local port numbers.
1380
1381 unreg_only
1382 Traffic on the local network not originating from an unregistered
1383 address spaces will be ignored.
1384
1385 reset Reset table of the packet aliasing engine on address change.
1386
1387 reverse
1388 Reverse the way libalias handles aliasing.
1389
1390 proxy_only
1391 Obey transparent proxy rules only, packet aliasing is not per-
1392 formed.
1393
1394 To let the packet continue after being (de)aliased, set the sysctl vari-
1395 able net.inet.ip.fw.one_pass to 0. For more information about aliasing
1396 modes, refer to libalias(3) See Section EXAMPLES for some examples about
1397 nat usage.
1398
1399REDIRECT AND LSNAT SUPPORT IN IPFW
1400 Redirect and LSNAT support follow closely the syntax used in natd(8) See
1401 Section EXAMPLES for some examples on how to do redirect and lsnat.
1402
1403SYSCTL VARIABLES
1404 A set of sysctl(8) variables controls the behaviour of the firewall and
1405 associated modules (dummynet, bridge). These are shown below together
1406 with their default value (but always check with the sysctl(8) command
1407 what value is actually in use) and meaning:
1408
1409 net.inet.ip.dummynet.expire: 1
1410 Lazily delete dynamic pipes/queue once they have no pending traf-
1411 fic. You can disable this by setting the variable to 0, in which
1412 case the pipes/queues will only be deleted when the threshold is
1413 reached.
1414
1415 net.inet.ip.dummynet.hash_size: 64
1416 Default size of the hash table used for dynamic pipes/queues.
1417 This value is used when no buckets option is specified when con-
1418 figuring a pipe/queue.
1419
1420 net.inet.ip.dummynet.io_fast: 0
1421 If set to non-zero value enables "fast" mode of dummynet opera-
1422 tion (see above).
1423
1424 net.inet.ip.dummynet.io_pkt
1425 Number of packets passed to by dummynet.
1426
1427 net.inet.ip.dummynet.io_pkt_drop
1428 Number of packets dropped by dummynet.
1429
1430 net.inet.ip.dummynet.io_pkt_fast
1431 Number of packets bypassed dummynet scheduler.
1432
1433 net.inet.ip.dummynet.max_chain_len: 16
1434 Target value for the maximum number of pipes/queues in a hash
1435 bucket. The product max_chain_len*hash_size is used to determine
1436 the threshold over which empty pipes/queues will be expired even
1437 when net.inet.ip.dummynet.expire=0.
1438
1439 net.inet.ip.dummynet.red_lookup_depth: 256
1440
1441 net.inet.ip.dummynet.red_avg_pkt_size: 512
1442
1443 net.inet.ip.dummynet.red_max_pkt_size: 1500
1444 Parameters used in the computations of the drop probability for
1445 the RED algorithm.
1446
1447 net.inet.ip.dummynet.pipe_byte_limit: 1048576
1448
1449 net.inet.ip.dummynet.pipe_slot_limit: 100
1450 The maximum queue size that can be specified in bytes or packets.
1451 These limits prevent accidental exhaustion of resources such as
1452 mbufs. If you raise these limits, you should make sure the sys-
1453 tem is configured so that sufficient resources are available.
1454
1455 net.inet.ip.fw.autoinc_step: 100
1456 Delta between rule numbers when auto-generating them. The value
1457 must be in the range 1..1000.
1458
1459 net.inet.ip.fw.curr_dyn_buckets: net.inet.ip.fw.dyn_buckets
1460 The current number of buckets in the hash table for dynamic rules
1461 (readonly).
1462
1463 net.inet.ip.fw.debug: 1
1464 Controls debugging messages produced by ipfw.
1465
1466 net.inet.ip.fw.dyn_buckets: 256
1467 The number of buckets in the hash table for dynamic rules. Must
1468 be a power of 2, up to 65536. It only takes effect when all
1469 dynamic rules have expired, so you are advised to use a flush
1470 command to make sure that the hash table is resized.
1471
1472 net.inet.ip.fw.dyn_count: 3
1473 Current number of dynamic rules (read-only).
1474
1475 net.inet.ip.fw.dyn_keepalive: 1
1476 Enables generation of keepalive packets for keep-state ru