e4f8706cc88a21fffa028afdc47072f79bf3994d
[dragonfly.git] / sbin / ipfw / ipfw.8
1 .\"
2 .\" $FreeBSD: src/sbin/ipfw/ipfw.8,v 1.63.2.33 2003/02/04 01:36:02 brueffer Exp $
3 .\" $DragonFly: src/sbin/ipfw/ipfw.8,v 1.20 2008/11/23 21:55:52 swildner Exp $
4 .\"
5 .Dd October 3, 2008
6 .Dt IPFW 8
7 .Os
8 .Sh NAME
9 .Nm ipfw
10 .Nd IP firewall and traffic shaper control program
11 .Sh SYNOPSIS
12 .Nm
13 .Op Fl cq
14 .Cm add
15 .Ar rule
16 .Nm
17 .Op Fl acdeftNS
18 .Brq Cm list | show
19 .Op Ar number ...
20 .Nm
21 .Op Fl f | q
22 .Cm flush
23 .Nm
24 .Op Fl q
25 .Brq Cm delete | zero | resetlog
26 .Op Cm set
27 .Op Ar number ...
28 .Nm
29 .Cm enable
30 .Brq Cm firewall | one_pass | debug | verbose | dyn_keepalive
31 .Nm
32 .Cm disable
33 .Brq Cm firewall | one_pass | debug | verbose | dyn_keepalive
34 .Pp
35 .Nm
36 .Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ...
37 .Nm
38 .Cm set move
39 .Op Cm rule
40 .Ar number Cm to Ar number
41 .Nm
42 .Cm set swap Ar number number
43 .Nm
44 .Cm set show
45 .Pp
46 .Nm
47 .Brq Cm pipe | queue
48 .Ar number
49 .Cm config
50 .Ar config-options
51 .Nm
52 .Op Fl s Op Ar field
53 .Brq Cm pipe | queue
54 .Brq Cm delete | list | show
55 .Op Ar number ...
56 .Pp
57 .Nm
58 .Op Fl q
59 .Oo
60 .Fl p Ar preproc
61 .Oo Fl D
62 .Ar macro Ns Op = Ns Ar value
63 .Oc
64 .Op Fl U Ar macro
65 .Oc
66 .Ar pathname
67 .Sh DESCRIPTION
68 The
69 .Nm
70 utility is the user interface for controlling the
71 .Xr ipfw 4
72 firewall and the
73 .Xr dummynet 4
74 traffic shaper in
75 .Dx .
76 .Bd -ragged -offset XXXX
77 .Em NOTE:
78 this manual page documents the newer version of
79 .Nm
80 introduced in
81 .Fx
82 CURRENT in July 2002, also known as
83 .Nm ipfw2 .
84 .Nm ipfw2
85 is a superset of the old firewall,
86 .Nm ipfw1 .
87 The differences between the two are listed in Section
88 .Sx IPFW2 ENHANCEMENTS ,
89 which you are encouraged to read to revise older rulesets and possibly
90 write them more efficiently.
91 .Ed
92 .Pp
93 An
94 .Nm
95 configuration, or
96 .Em ruleset ,
97 is made of a list of
98 .Em rules
99 numbered from 1 to 65535.
100 Packets are passed to
101 .Nm
102 from a number of different places in the protocol stack
103 (depending on the source and destination of the packet,
104 it is possible that
105 .Nm
106 is invoked multiple times on the same packet).
107 The packet passed to the firewall is compared
108 against each of the rules in the firewall
109 .Em ruleset .
110 When a match is found, the action corresponding to the
111 matching rule is performed.
112 .Pp
113 Depending on the action and certain system settings, packets
114 can be reinjected into the firewall at some rule after the
115 matching one for further processing.
116 .Pp
117 An
118 .Nm
119 ruleset always includes a
120 .Em default
121 rule (numbered 65535) which cannot be modified,
122 and matches all packets.
123 The action associated with the
124 .Em default
125 rule can be either
126 .Cm deny
127 or
128 .Cm allow
129 depending on how the kernel is configured.
130 .Pp
131 If the ruleset includes one or more rules with the
132 .Cm keep-state
133 or
134 .Cm limit
135 option, then
136 .Nm
137 assumes a
138 .Em stateful
139 behaviour, i.e. upon a match it will create dynamic rules matching
140 the exact parameters (addresses and ports) of the matching packet.
141 .Pp
142 These dynamic rules, which have a limited lifetime, are checked
143 at the first occurrence of a
144 .Cm check-state ,
145 .Cm keep-state
146 or
147 .Cm limit
148 rule, and are typically used to open the firewall on-demand to
149 legitimate traffic only.
150 See the
151 .Sx STATEFUL FIREWALL
152 and
153 .Sx EXAMPLES
154 Sections below for more information on the stateful behaviour of
155 .Nm .
156 .Pp
157 All rules (including dynamic ones) have a few associated counters:
158 a packet count, a byte count, a log count and a timestamp
159 indicating the time of the last match.
160 Counters can be displayed or reset with
161 .Nm
162 commands.
163 .Pp
164 Rules can be added with the
165 .Cm add
166 command; deleted individually or in groups with the
167 .Cm delete
168 command, and globally with the
169 .Cm flush
170 command; displayed, optionally with the content of the
171 counters, using the
172 .Cm show
173 and
174 .Cm list
175 commands.
176 Finally, counters can be reset with the
177 .Cm zero
178 and
179 .Cm resetlog
180 commands.
181 .Pp
182 Also, each rule belongs to one of 32 different
183 .Em sets
184 , and there are
185 .Nm
186 commands to atomically manipulate sets, such as enable,
187 disable, swap sets, move all rules in a set to another
188 one, delete all rules in a set. These can be useful to
189 install temporary configurations, or to test them.
190 See Section
191 .Sx SETS OF RULES
192 for more information on
193 .Em sets .
194 .Pp
195 The following options are available:
196 .Bl -tag -width indent
197 .It Fl a
198 While listing, show counter values.
199 The
200 .Cm show
201 command just implies this option.
202 .It Fl c
203 When entering or showing rules, print them in compact form,
204 i.e. without the optional "ip from any to any" string
205 when this does not carry any additional information.
206 .It Fl d
207 While listing, show dynamic rules in addition to static ones.
208 .It Fl e
209 While listing, if the
210 .Fl d
211 option was specified, also show expired dynamic rules.
212 .It Fl f
213 Don't ask for confirmation for commands that can cause problems
214 if misused,
215 .No i.e. Cm flush .
216 If there is no tty associated with the process, this is implied.
217 .It Fl N
218 Try to resolve addresses and service names in output.
219 .It Fl q
220 While
221 .Cm add Ns ing ,
222 .Cm zero Ns ing ,
223 .Cm resetlog Ns ging
224 or
225 .Cm flush Ns ing ,
226 be quiet about actions
227 (implies
228 .Fl f ) .
229 This is useful for adjusting rules by executing multiple
230 .Nm
231 commands in a script
232 (e.g.,
233 .Ql sh\ /etc/rc.firewall ) ,
234 or by processing a file of many
235 .Nm
236 rules across a remote login session.
237 If a
238 .Cm flush
239 is performed in normal (verbose) mode (with the default kernel
240 configuration), it prints a message.
241 Because all rules are flushed, the message might not be delivered
242 to the login session, causing the remote login session to be closed
243 and the remainder of the ruleset to not be processed.
244 Access to the console would then be required to recover.
245 .It Fl S
246 While listing rules, show the
247 .Em set
248 each rule belongs to.
249 If this flag is not specified, disabled rules will not be
250 listed.
251 .It Fl s Op Ar field
252 While listing pipes, sort according to one of the four
253 counters (total or current packets or bytes).
254 .It Fl t
255 While listing, show last match timestamp.
256 .El
257 .Pp
258 To ease configuration, rules can be put into a file which is
259 processed using
260 .Nm
261 as shown in the last synopsis line.
262 An absolute
263 .Ar pathname
264 must be used.
265 The file will be read line by line and applied as arguments to the
266 .Nm
267 utility.
268 .Pp
269 Optionally, a preprocessor can be specified using
270 .Fl p Ar preproc
271 where
272 .Ar pathname
273 is to be piped through.
274 Useful preprocessors include
275 .Xr cpp 1
276 and
277 .Xr m4 1 .
278 If
279 .Ar preproc
280 doesn't start with a slash
281 .Pq Ql /
282 as its first character, the usual
283 .Ev PATH
284 name search is performed.
285 Care should be taken with this in environments where not all
286 file systems are mounted (yet) by the time
287 .Nm
288 is being run (e.g. when they are mounted over NFS).
289 Once
290 .Fl p
291 has been specified, optional
292 .Fl D
293 and
294 .Fl U
295 specifications can follow and will be passed on to the preprocessor.
296 This allows for flexible configuration files (like conditionalizing
297 them on the local hostname) and the use of macros to centralize
298 frequently required arguments like IP addresses.
299 .Pp
300 The
301 .Nm
302 .Cm pipe
303 and
304 .Cm queue
305 commands are used to configure the traffic shaper, as shown in the
306 .Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION
307 Section below.
308 .Pp
309 If the world and the kernel get out of sync the
310 .Nm
311 ABI may break, preventing you from being able to add any rules.  This can
312 adversely affect the booting process.  You can use
313 .Nm
314 .Cm disable
315 .Cm firewall
316 to temporarily disable the firewall to regain access to the network,
317 allowing you to fix the problem.
318 .Sh PACKET FLOW
319 A packet is checked against the active ruleset in multiple places
320 in the protocol stack, under control of several sysctl variables.
321 These places and variables are shown below, and it is important to
322 have this picture in mind in order to design a correct ruleset.
323 .Bd -literal -offset indent
324          ^     to upper layers     V
325          |                         |
326          +------------>------------+
327          ^                         V
328     [ip_input]                [ip_output]   net.inet.ip.fw.enable=1
329          |                         |
330          ^                         V
331 [ether_demux_oncpu]   [ether_output_frame]  net.link.ether.ipfw=1
332          ^                         V
333          |       to devices        |
334 .Ed
335 .Pp
336 As can be noted from the above picture, the number of
337 times the same packet goes through the firewall can
338 vary between 0 and 4 depending on packet source and
339 destination, and system configuration.
340 .Pp
341 Note that as packets flow through the stack, headers can be
342 stripped or added to it, and so they may or may not be available
343 for inspection.
344 E.g., incoming packets will include the MAC header when
345 .Nm
346 is invoked from
347 .Fn ether_demux_oncpu ,
348 but the same packets will have the MAC header stripped off when
349 .Nm
350 is invoked from
351 .Fn ip_input .
352 .Pp
353 Also note that each packet is always checked against the complete ruleset,
354 irrespective of the place where the check occurs, or the source of the packet.
355 If a rule contains some match patterns or actions which are not valid
356 for the place of invocation (e.g. trying to match a MAC header within
357 .Fn ip_input ) ,
358 the match pattern will not match, but a
359 .Cm not
360 operator in front of such patterns
361 .Em will
362 cause the pattern to
363 .Em always
364 match on those packets.
365 It is thus the responsibility of
366 the programmer, if necessary, to write a suitable ruleset to
367 differentiate among the possible places.
368 .Cm skipto
369 rules can be useful here, as an example:
370 .Bd -literal -offset indent
371 # packets from ether_demux_oncpu
372 ipfw add 10 skipto 1000 all from any to any layer2 in
373 # packets from ip_input
374 ipfw add 10 skipto 2000 all from any to any not layer2 in
375 # packets from ip_output
376 ipfw add 10 skipto 3000 all from any to any not layer2 out
377 # packets from ether_output_frame
378 ipfw add 10 skipto 4000 all from any to any layer2 out
379 .Ed
380 .Sh RULE FORMAT
381 The format of
382 .Nm
383 rules is the following:
384 .Bd -ragged -offset indent
385 .Op Ar rule_number
386 .Op Cm set Ar set_number
387 .Op Cm prob Ar match_probability
388 .br
389 .Ar "   " action
390 .Op Cm log Op Cm logamount Ar number
391 .Ar body
392 .Ed
393 .Pp
394 where the body of the rule specifies which information is used
395 for filtering packets, among the following:
396 .Pp
397 .Bl -tag -width "Source and dest. addresses and ports" -offset XXX -compact
398 .It Layer-2 header fields
399 When available
400 .It IPv4 Protocol
401 TCP, UDP, ICMP, etc.
402 .It Source and dest. addresses and ports
403 .It Direction
404 See Section
405 .Sx PACKET FLOW
406 .It Transmit and receive interface
407 By name or address
408 .It Misc. IP header fields
409 Version, type of service, datagram length, identification,
410 fragment flag (non-zero IP offset),
411 Time To Live
412 .It IP options
413 .It Misc. TCP header fields
414 TCP flags (SYN, FIN, ACK, RST, etc.),
415 sequence number, acknowledgment number,
416 window
417 .It TCP options
418 .It ICMP types
419 for ICMP packets
420 .It User/group ID
421 When the packet can be associated with a local socket.
422 .El
423 .Pp
424 Note that some of the above information, e.g. source MAC or IP addresses and
425 TCP/UDP ports, could easily be spoofed, so filtering on those fields
426 alone might not guarantee the desired results.
427 .Bl -tag -width indent
428 .It Ar rule_number
429 Each rule is associated with a
430 .Ar rule_number
431 in the range 1..65535, with the latter reserved for the
432 .Em default
433 rule.
434 Rules are checked sequentially by rule number.
435 Multiple rules can have the same number, in which case they are
436 checked (and listed) according to the order in which they have
437 been added.
438 If a rule is entered without specifying a number, the kernel will
439 assign one in such a way that the rule becomes the last one
440 before the
441 .Em default
442 rule.
443 Automatic rule numbers are assigned by incrementing the last
444 non-default rule number by the value of the sysctl variable
445 .Ar net.inet.ip.fw.autoinc_step
446 which defaults to 100.
447 If this is not possible (e.g. because we would go beyond the
448 maximum allowed rule number), the number of the last
449 non-default value is used instead.
450 .It Cm set Ar set_number
451 Each rule is associated with a
452 .Ar set_number
453 in the range 0..31, with the latter reserved for the
454 .Em default
455 rule.
456 Sets can be individually disabled and enabled, so this parameter
457 is of fundamental importance for atomic ruleset manipulation.
458 It can be also used to simplify deletion of groups of rules.
459 If a rule is entered without specifying a set number,
460 set 0 will be used.
461 .It Cm prob Ar match_probability
462 A match is only declared with the specified probability
463 (floating point number between 0 and 1).
464 This can be useful for a number of applications such as
465 random packet drop or
466 (in conjunction with
467 .Xr dummynet 4 )
468 to simulate the effect of multiple paths leading to out-of-order
469 packet delivery.
470 .It Cm log Op Cm logamount Ar number
471 When a packet matches a rule with the
472 .Cm log
473 keyword, a message will be
474 logged to
475 .Xr syslogd 8
476 with a
477 .Dv LOG_SECURITY
478 facility.
479 The logging only occurs if the sysctl variable
480 .Em net.inet.ip.fw.verbose
481 is set to 1
482 (which is the default when the kernel is compiled with
483 .Dv IPFIREWALL_VERBOSE )
484 and the number of packets logged so far for that
485 particular rule does not exceed the
486 .Cm logamount
487 parameter.
488 If no
489 .Cm logamount
490 is specified, the limit is taken from the sysctl variable
491 .Em net.inet.ip.fw.verbose_limit .
492 In both cases, a value of 0 removes the logging limit.
493 .Pp
494 Once the limit is reached, logging can be re-enabled by
495 clearing the logging counter or the packet counter for that entry, see the
496 .Cm resetlog
497 command.
498 .El
499 .Ss RULE ACTIONS
500 A rule can be associated with one of the following actions, which
501 will be executed when the packet matches the body of the rule.
502 .Bl -tag -width indent
503 .It Cm allow | accept | pass | permit
504 Allow packets that match rule.
505 The search terminates.
506 .It Cm check-state
507 Checks the packet against the dynamic ruleset.
508 If a match is found, execute the action associated with
509 the rule which generated this dynamic rule, otherwise
510 move to the next rule.
511 .br
512 .Cm Check-state
513 rules do not have a body.
514 If no
515 .Cm check-state
516 rule is found, the dynamic ruleset is checked at the first
517 .Cm keep-state
518 or
519 .Cm limit
520 rule.
521 .It Cm count
522 Update counters for all packets that match rule.
523 The search continues with the next rule.
524 .It Cm deny | drop
525 Discard packets that match this rule.
526 The search terminates.
527 .It Cm divert Ar port
528 Divert packets that match this rule to the
529 .Xr divert 4
530 socket bound to port
531 .Ar port .
532 The search terminates.
533 .It Cm fwd | forward Ar ipaddr Ns Op , Ns Ar port
534 Change the next-hop on matching packets to
535 .Ar ipaddr ,
536 which can be an IP address in dotted quad format or a host name.
537 The search terminates if this rule matches.
538 .Pp
539 If
540 .Ar ipaddr
541 is a local address, then matching packets will be forwarded to
542 .Ar port
543 (or the port number in the packet if one is not specified in the rule)
544 on the local machine.
545 .br
546 If
547 .Ar ipaddr
548 is not a local address, then the port number
549 (if specified) is ignored, and the packet will be
550 forwarded to the remote address, using the route as found in
551 the local routing table for that IP.
552 .br
553 A
554 .Ar fwd
555 rule will not match layer-2 packets (those received
556 on
557 .Fn ether_input
558 or
559 .Fn ether_output ) .
560 .br
561 The
562 .Cm fwd
563 action does not change the contents of the packet at all.
564 In particular, the destination address remains unmodified, so
565 packets forwarded to another system will usually be rejected by that system
566 unless there is a matching rule on that system to capture them.
567 For packets forwarded locally,
568 the local address of the socket will be
569 set to the original destination address of the packet.
570 This makes the
571 .Xr netstat 1
572 entry look rather weird but is intended for
573 use with transparent proxy servers.
574 .It Cm pipe Ar pipe_nr
575 Pass packet to a
576 .Xr dummynet 4
577 .Dq pipe
578 (for bandwidth limitation, delay, etc.).
579 See the
580 .Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION
581 Section for further information.
582 The search terminates; however, on exit from the pipe and if
583 the
584 .Xr sysctl 8
585 variable
586 .Em net.inet.ip.fw.one_pass
587 is not set, the packet is passed again to the firewall code
588 starting from the next rule.
589 .It Cm queue Ar queue_nr
590 Pass packet to a
591 .Xr dummynet 4
592 .Dq queue
593 (for bandwidth limitation using WF2Q+).
594 .It Cm reject
595 (Deprecated).
596 Synonym for
597 .Cm unreach host .
598 .It Cm reset
599 Discard packets that match this rule, and if the
600 packet is a TCP packet, try to send a TCP reset (RST) notice.
601 The search terminates.
602 .It Cm skipto Ar number
603 Skip all subsequent rules numbered less than
604 .Ar number .
605 The search continues with the first rule numbered
606 .Ar number
607 or higher.
608 .It Cm tee Ar port
609 Send a copy of packets matching this rule to the
610 .Xr divert 4
611 socket bound to port
612 .Ar port .
613 The search terminates and the original packet is accepted
614 (but see Section
615 .Sx BUGS
616 below).
617 .It Cm unreach Ar code
618 Discard packets that match this rule, and try to send an ICMP
619 unreachable notice with code
620 .Ar code ,
621 where
622 .Ar code
623 is a number from 0 to 255, or one of these aliases:
624 .Cm net , host , protocol , port ,
625 .Cm needfrag , srcfail , net-unknown , host-unknown ,
626 .Cm isolated , net-prohib , host-prohib , tosnet ,
627 .Cm toshost , filter-prohib , host-precedence
628 or
629 .Cm precedence-cutoff .
630 The search terminates.
631 .El
632 .Ss RULE BODY
633 The body of a rule contains zero or more patterns (such as
634 specific source and destination addresses or ports,
635 protocol options, incoming or outgoing interfaces, etc.)
636 that the packet must match in order to be recognised.
637 In general, the patterns are connected by (implicit)
638 .Cm and
639 operators -- i.e. all must match in order for the
640 rule to match.
641 Individual patterns can be prefixed by the
642 .Cm not
643 operator to reverse the result of the match, as in
644 .Pp
645 .Dl "ipfw add 100 allow ip from not 1.2.3.4 to any"
646 .Pp
647 Additionally, sets of alternative match patterns
648 .Em ( or-blocks )
649 can be constructed by putting the patterns in
650 lists enclosed between parentheses ( ) or braces { }, and
651 using the
652 .Cm or
653 operator as follows:
654 .Pp
655 .Dl "ipfw add 100 allow ip from { x or not y or z } to any"
656 .Pp
657 Only one level of parentheses is allowed.
658 Beware that most shells have special meanings for parentheses
659 or braces, so it is advisable to put a backslash \\ in front of them
660 to prevent such interpretations.
661 .Pp
662 The body of a rule must in general include a source and destination
663 address specifier.
664 The keyword
665 .Ar any
666 can be used in various places to specify that the content of
667 a required field is irrelevant.
668 .Pp
669 The rule body has the following format:
670 .Bd -ragged -offset indent
671 .Op Ar proto Cm from Ar src Cm to Ar dst
672 .Op Ar options
673 .Ed
674 .Pp
675 The first part (protocol from src to dst) is for backward
676 compatibility with
677 .Nm ipfw1 .
678 In
679 .Nm ipfw2
680 any match pattern (including MAC headers, IPv4 protocols,
681 addresses and ports) can be specified in the
682 .Ar options
683 section.
684 .Pp
685 Rule fields have the following meaning:
686 .Bl -tag -width indent
687 .It Ar proto : protocol | Cm { Ar protocol Cm or ... }
688 An IPv4 protocol (or an
689 .Em or-block
690 with multiple protocols) specified by number or name
691 (for a complete list see
692 .Pa /etc/protocols ) .
693 The
694 .Cm ip
695 or
696 .Cm all
697 keywords mean any protocol will match.
698 .It Ar src No and Ar dst : ip-address | Cm { Ar ip-address Cm or ... } Op Ar ports
699 A single
700 .Ar ip-address
701 , or an
702 .Em or-block
703 containing one or more of them,
704 optionally followed by
705 .Ar ports
706 specifiers.
707 .It Ar ip-address :
708 An address (or set of addresses) specified in one of the following
709 ways, optionally preceded by a
710 .Cm not
711 operator:
712 .Bl -tag -width indent
713 .It Cm any
714 matches any IP address.
715 .It Cm me
716 matches any IP address configured on an interface in the system.
717 The address list is evaluated at the time the packet is
718 analysed.
719 .It Ar numeric-ip | hostname
720 Matches a single IPv4 address, specified as dotted-quad or a hostname.
721 Hostnames are resolved at the time the rule is added to the firewall list.
722 .It Ar addr Ns / Ns Ar masklen
723 Matches all addresses with base
724 .Ar addr
725 (specified as a dotted quad or a hostname)
726 and mask width of
727 .Cm masklen
728 bits.
729 As an example, 1.2.3.4/25 will match
730 all IP numbers from 1.2.3.0 to 1.2.3.127 .
731 .It Ar addr Ns / Ns Ar masklen Ns Cm { Ns Ar num,num,... Ns Cm }
732 Matches all addresses with base address
733 .Ar addr
734 (specified as a dotted quad or a hostname)
735 and whose last byte is in the list between braces { } .
736 Note that there must be no spaces between braces, commas and
737 numbers.
738 The
739 .Ar masklen
740 field is used to limit the size of the set of addresses,
741 and can have any value between 24 and 32.
742 .br
743 As an example, an address specified as 1.2.3.4/24{128,35,55,89}
744 will match the following IP addresses:
745 .br
746 1.2.3.128 1.2.3.35 1.2.3.55 1.2.3.89 .
747 .br
748 This format is particularly useful to handle sparse address sets
749 within a single rule. Because the matching occurs using a
750 bitmask, it takes constant time and dramatically reduces
751 the complexity of rulesets.
752 .It Ar addr Ns : Ns Ar mask
753 Matches all addresses with base
754 .Ar addr
755 (specified as a dotted quad or a hostname)
756 and the mask of
757 .Ar mask ,
758 specified as a dotted quad.
759 As an example, 1.2.3.4/255.0.255.0 will match
760 1.*.3.*.
761 We suggest to use this form only for non-contiguous
762 masks, and resort to the
763 .Ar addr Ns / Ns Ar masklen
764 format for contiguous masks, which is more compact and less
765 error-prone.
766 .El
767 .It Ar ports : Oo Cm not Oc Bro Ar port | port Ns \&- Ns Ar port Ns Brc Op , Ns Ar ...
768 For protocols which support port numbers (such as TCP and UDP), optional
769 .Cm ports
770 may be specified as one or more ports or port ranges, separated
771 by commas but no spaces, and an optional
772 .Cm not
773 operator.
774 The
775 .Ql \&-
776 notation specifies a range of ports (including boundaries).
777 .Pp
778 Service names (from
779 .Pa /etc/services )
780 may be used instead of numeric port values.
781 The length of the port list is limited to 30 ports or ranges,
782 though one can specify larger ranges by using an
783 .Em or-block
784 in the
785 .Cm options
786 section of the rule.
787 .Pp
788 A backslash
789 .Pq Ql \e
790 can be used to escape the dash
791 .Pq Ql -
792 character in a service name (from a shell, the backslash must be
793 typed twice to avoid the shell itself interpreting it as an escape
794 character).
795 .Pp
796 .Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any"
797 .Pp
798 Fragmented packets which have a non-zero offset (i.e. not the first
799 fragment) will never match a rule which has one or more port
800 specifications.
801 See the
802 .Cm frag
803 option for details on matching fragmented packets.
804 .El
805 .Ss RULE OPTIONS (MATCH PATTERNS)
806 Additional match patterns can be used within
807 rules. Zero or more of these so-called
808 .Em options
809 can be present in a rule, optionally prefixed by the
810 .Cm not
811 operand, and possibly grouped into
812 .Em or-blocks .
813 .Pp
814 The following match patterns can be used (listed in alphabetical order):
815 .Bl -tag -width indent
816 .It Cm dst-ip Ar ip address
817 Matches IP packets whose destination IP is one of the address(es)
818 specified as argument.
819 .It Cm dst-port Ar source ports
820 Matches IP packets whose destination port is one of the port(s)
821 specified as argument.
822 .It Cm established
823 Matches TCP packets that have the RST or ACK bits set.
824 .It Cm frag
825 Matches packets that are fragments and not the first
826 fragment of an IP datagram. Note that these packets will not have
827 the next protocol header (e.g. TCP, UDP) so options that look into
828 these headers cannot match.
829 .It Cm gid Ar group
830 Matches all TCP or UDP packets sent by or received for a
831 .Ar group .
832 A
833 .Ar group
834 may be specified by name or number.
835 .It Cm icmptypes Ar types
836 Matches ICMP packets whose ICMP type is in the list
837 .Ar types .
838 The list may be specified as any combination of ranges or
839 individual types separated by commas.
840 The supported ICMP types are:
841 .Pp
842 echo reply
843 .Pq Cm 0 ,
844 destination unreachable
845 .Pq Cm 3 ,
846 source quench
847 .Pq Cm 4 ,
848 redirect
849 .Pq Cm 5 ,
850 echo request
851 .Pq Cm 8 ,
852 router advertisement
853 .Pq Cm 9 ,
854 router solicitation
855 .Pq Cm 10 ,
856 time-to-live exceeded
857 .Pq Cm 11 ,
858 IP header bad
859 .Pq Cm 12 ,
860 timestamp request
861 .Pq Cm 13 ,
862 timestamp reply
863 .Pq Cm 14 ,
864 information request
865 .Pq Cm 15 ,
866 information reply
867 .Pq Cm 16 ,
868 address mask request
869 .Pq Cm 17
870 and address mask reply
871 .Pq Cm 18 .
872 .It Cm in | out
873 Matches incoming or outgoing packets, respectively.
874 .Cm in
875 and
876 .Cm out
877 are mutually exclusive (in fact,
878 .Cm out
879 is implemented as
880 .Cm not in Ns No ).
881 .It Cm ipid Ar id
882 Matches IP packets whose
883 .Cm ip_id
884 field has value
885 .Ar id .
886 .It Cm iplen Ar len
887 Matches IP packets whose total length, including header and data, is
888 .Ar len
889 bytes.
890 .It Cm ipoptions Ar spec
891 Matches packets whose IP header contains the comma separated list of
892 options specified in
893 .Ar spec .
894 The supported IP options are:
895 .Pp
896 .Cm ssrr
897 (strict source route),
898 .Cm lsrr
899 (loose source route),
900 .Cm rr
901 (record packet route) and
902 .Cm ts
903 (timestamp).
904 The absence of a particular option may be denoted
905 with a
906 .Ql \&! .
907 .It Cm ipprecedence Ar precedence
908 Matches IP packets whose precedence field is equal to
909 .Ar precedence .
910 .It Cm iptos Ar spec
911 Matches IP packets whose
912 .Cm tos
913 field contains the comma separated list of
914 service types specified in
915 .Ar spec .
916 The supported IP types of service are:
917 .Pp
918 .Cm lowdelay
919 .Pq Dv IPTOS_LOWDELAY ,
920 .Cm throughput
921 .Pq Dv IPTOS_THROUGHPUT ,
922 .Cm reliability
923 .Pq Dv IPTOS_RELIABILITY ,
924 .Cm mincost
925 .Pq Dv IPTOS_MINCOST ,
926 .Cm congestion
927 .Pq Dv IPTOS_CE .
928 The absence of a particular type may be denoted
929 with a
930 .Ql \&! .
931 .It Cm ipttl Ar ttl
932 Matches IP packets whose time to live is
933 .Ar ttl .
934 .It Cm ipversion Ar ver
935 Matches IP packets whose IP version field is
936 .Ar ver .
937 .It Cm keep-state
938 Upon a match, the firewall will create a dynamic rule, whose
939 default behaviour is to match bidirectional traffic between
940 source and destination IP/port using the same protocol.
941 The rule has a limited lifetime (controlled by a set of
942 .Xr sysctl 8
943 variables), and the lifetime is refreshed every time a matching
944 packet is found.
945 .It Cm layer2
946 Matches only layer2 packets, i.e. those passed to
947 .Nm
948 from
949 .Fn ether_demux_oncpu
950 and
951 .Fn ether_output_frame .
952 .It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N
953 The firewall will only allow
954 .Ar N
955 connections with the same
956 set of parameters as specified in the rule.
957 One or more
958 of source and destination addresses and ports can be
959 specified.
960 .It Cm { MAC | mac } Ar dst-mac src-mac
961 Match packets with a given
962 .Ar dst-mac
963 and
964 .Ar src-mac
965 addresses, specified as the
966 .Cm any
967 keyword (matching any MAC address), or six groups of hex digits
968 separated by colons,
969 and optionally followed by a mask indicating how many bits are
970 significant, as in
971 .Pp
972 .Dl "MAC 10:20:30:40:50:60/33 any"
973 .Pp
974 Note that the order of MAC addresses (destination first,
975 source second) is
976 the same as on the wire, but the opposite of the one used for
977 IP addresses.
978 .It Cm mac-type Ar mac-type
979 Matches packets whose Ethernet Type field
980 corresponds to one of those specified as argument.
981 .Ar mac-type
982 is specified in the same way as
983 .Cm port numbers
984 (i.e. one or more comma-separated single values or ranges).
985 You can use symbolic names for known values such as
986 .Em vlan , ipv4, ipv6 .
987 Values can be entered as decimal or hexadecimal (if prefixed by 0x),
988 and they are always printed as hexadecimal (unless the
989 .Cm -N
990 option is used, in which case symbolic resolution will be attempted).
991 .It Cm proto Ar protocol
992 Matches packets with the corresponding IPv4 protocol.
993 .It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar ipno | Ar any
994 Matches packets received, transmitted or going through,
995 respectively, the interface specified by exact name
996 .Ns No ( Ar ifX Ns No ),
997 by device name
998 .Ns No ( Ar if Ns Ar * Ns No ),
999 by IP address, or through some interface.
1000 .Pp
1001 The
1002 .Cm via
1003 keyword causes the interface to always be checked.
1004 If
1005 .Cm recv
1006 or
1007 .Cm xmit
1008 is used instead of
1009 .Cm via ,
1010 then only the receive or transmit interface (respectively)
1011 is checked.
1012 By specifying both, it is possible to match packets based on
1013 both receive and transmit interface, e.g.:
1014 .Pp
1015 .Dl "ipfw add deny ip from any to any out recv ed0 xmit ed1"
1016 .Pp
1017 The
1018 .Cm recv
1019 interface can be tested on either incoming or outgoing packets,
1020 while the
1021 .Cm xmit
1022 interface can only be tested on outgoing packets.
1023 So
1024 .Cm out
1025 is required (and
1026 .Cm in
1027 is invalid) whenever
1028 .Cm xmit
1029 is used.
1030 .Pp
1031 A packet may not have a receive or transmit interface: packets
1032 originating from the local host have no receive interface,
1033 while packets destined for the local host have no transmit
1034 interface.
1035 .It Cm setup
1036 Matches TCP packets that have the SYN bit set but no ACK bit.
1037 This is the short form of
1038 .Dq Li tcpflags\ syn,!ack .
1039 .It Cm src-ip Ar ip-address
1040 Matches IP packets whose source IP is one of the address(es)
1041 specified as argument.
1042 .It Cm src-port Ar ports
1043 Matches IP packets whose source port is one of the port(s)
1044 specified as argument.
1045 .It Cm tcpack Ar ack
1046 TCP packets only.
1047 Match if the TCP header acknowledgment number field is set to
1048 .Ar ack .
1049 .It Cm tcpflags Ar spec
1050 TCP packets only.
1051 Match if the TCP header contains the comma separated list of
1052 flags specified in
1053 .Ar spec .
1054 The supported TCP flags are:
1055 .Pp
1056 .Cm fin ,
1057 .Cm syn ,
1058 .Cm rst ,
1059 .Cm psh ,
1060 .Cm ack
1061 and
1062 .Cm urg .
1063 The absence of a particular flag may be denoted
1064 with a
1065 .Ql \&! .
1066 A rule which contains a
1067 .Cm tcpflags
1068 specification can never match a fragmented packet which has
1069 a non-zero offset.
1070 See the
1071 .Cm frag
1072 option for details on matching fragmented packets.
1073 .It Cm tcpseq Ar seq
1074 TCP packets only.
1075 Match if the TCP header sequence number field is set to
1076 .Ar seq .
1077 .It Cm tcpwin Ar win
1078 TCP packets only.
1079 Match if the TCP header window field is set to
1080 .Ar win .
1081 .It Cm tcpoptions Ar spec
1082 TCP packets only.
1083 Match if the TCP header contains the comma separated list of
1084 options specified in
1085 .Ar spec .
1086 The supported TCP options are:
1087 .Pp
1088 .Cm mss
1089 (maximum segment size),
1090 .Cm window
1091 (tcp window advertisement),
1092 .Cm sack
1093 (selective ack),
1094 .Cm ts
1095 (rfc1323 timestamp) and
1096 .Cm cc
1097 (rfc1644 t/tcp connection count).
1098 The absence of a particular option may be denoted
1099 with a
1100 .Ql \&! .
1101 .It Cm uid Ar user
1102 Match all TCP or UDP packets sent by or received for a
1103 .Ar user .
1104 A
1105 .Ar user
1106 may be matched by name or identification number.
1107 .El
1108 .Sh SETS OF RULES
1109 Each rule belongs to one of 32 different
1110 .Em sets
1111 , numbered 0 to 31.
1112 Set 31 is reserved for the default rule.
1113 .Pp
1114 By default, rules are put in set 0, unless you use the
1115 .Cm set N
1116 attribute when entering a new rule.
1117 Sets can be individually and atomically enabled or disabled,
1118 so this mechanism permits an easy way to store multiple configurations
1119 of the firewall and quickly (and atomically) switch between them.
1120 The command to enable/disable sets is
1121 .Bd -ragged -offset indent
1122 .Nm
1123 .Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ...
1124 .Ed
1125 .Pp
1126 where multiple
1127 .Cm enable
1128 or
1129 .Cm disable
1130 sections can be specified.
1131 Command execution is atomic on all the sets specified in the command.
1132 By default, all sets are enabled.
1133 .Pp
1134 When you disable a set, its rules behave as if they do not exist
1135 in the firewall configuration, with only one exception:
1136 .Bd -ragged -offset indent
1137 dynamic rules created from a rule before it had been disabled
1138 will still be active until they expire. In order to delete
1139 dynamic rules you have to explicitly delete the parent rule
1140 which generated them.
1141 .Ed
1142 .Pp
1143 The set number of rules can be changed with the command
1144 .Bd -ragged -offset indent
1145 .Nm
1146 .Cm set move
1147 .Brq Cm rule Ar rule-number | old-set
1148 .Cm to Ar new-set
1149 .Ed
1150 .Pp
1151 Also, you can atomically swap two rulesets with the command
1152 .Bd -ragged -offset indent
1153 .Nm
1154 .Cm set swap Ar first-set second-set
1155 .Ed
1156 .Pp
1157 See the
1158 .Sx EXAMPLES
1159 Section on some possible uses of sets of rules.
1160 .Sh STATEFUL FIREWALL
1161 Stateful operation is a way for the firewall to dynamically
1162 create rules for specific flows when packets that
1163 match a given pattern are detected. Support for stateful
1164 operation comes through the
1165 .Cm check-state , keep-state
1166 and
1167 .Cm limit
1168 options of
1169 .Nm
1170 rules.
1171 .Pp
1172 Dynamic rules are created when a packet matches a
1173 .Cm keep-state
1174 or
1175 .Cm limit
1176 rule, causing the creation of a
1177 .Em dynamic
1178 rule which will match all and only packets with
1179 a given
1180 .Em protocol
1181 between a
1182 .Em src-ip/src-port dst-ip/dst-port
1183 pair of addresses (
1184 .Em src
1185 and
1186 .Em dst
1187 are used here only to denote the initial match addresses, but they
1188 are completely equivalent afterwards).
1189 Dynamic rules will be checked at the first
1190 .Cm check-state, keep-state
1191 or
1192 .Cm limit
1193 occurrence, and the action performed upon a match will be the same
1194 as in the parent rule.
1195 .Pp
1196 Note that no additional attributes other than protocol and IP addresses
1197 and ports are checked on dynamic rules.
1198 .Pp
1199 The typical use of dynamic rules is to keep a closed firewall configuration,
1200 but let the first TCP SYN packet from the inside network install a
1201 dynamic rule for the flow so that packets belonging to that session
1202 will be allowed through the firewall:
1203 .Pp
1204 .Dl "ipfw add check-state"
1205 .Dl "ipfw add allow tcp from my-subnet to any setup keep-state"
1206 .Dl "ipfw add deny tcp from any to any"
1207 .Pp
1208 A similar approach can be used for UDP, where an UDP packet coming
1209 from the inside will install a dynamic rule to let the response through
1210 the firewall:
1211 .Pp
1212 .Dl "ipfw add check-state"
1213 .Dl "ipfw add allow udp from my-subnet to any keep-state"
1214 .Dl "ipfw add deny udp from any to any"
1215 .Pp
1216 Dynamic rules expire after some time, which depends on the status
1217 of the flow and the setting of some
1218 .Cm sysctl
1219 variables.
1220 See Section
1221 .Sx SYSCTL VARIABLES
1222 for more details.
1223 For TCP sessions, dynamic rules can be instructed to periodically
1224 send keepalive packets to refresh the state of the rule when it is
1225 about to expire.
1226 .Pp
1227 See Section
1228 .Sx EXAMPLES
1229 for more examples on how to use dynamic rules.
1230 .Sh TRAFFIC SHAPER (DUMMYNET) CONFIGURATION
1231 .Nm
1232 is also the user interface for the
1233 .Xr dummynet 4
1234 traffic shaper.
1235 .Pp
1236 .Nm dummynet
1237 operates by first using the firewall to classify packets and divide them into
1238 .Em flows ,
1239 using any match pattern that can be used in
1240 .Nm
1241 rules.
1242 Depending on local policies, a flow can contain packets for a single
1243 TCP connection, or from/to a given host, or entire subnet, or a
1244 protocol type, etc.
1245 .Pp
1246 Packets belonging to the same flow are then passed to either of two
1247 different objects, which implement the traffic regulation:
1248 .Bl -hang -offset XXXX
1249 .It Em pipe
1250 A pipe emulates a link with given bandwidth, propagation delay,
1251 queue size and packet loss rate.
1252 Packets are queued in front of the pipe as they come out from the classifier,
1253 and then transferred to the pipe according to the pipe's parameters.
1254 .Pp
1255 .It Em queue
1256 A queue
1257 is an abstraction used to implement the WF2Q+
1258 (Worst-case Fair Weighted Fair Queueing) policy, which is
1259 an efficient variant of the WFQ policy.
1260 .br
1261 The queue associates a
1262 .Em weight
1263 and a reference pipe to each flow, and then all backlogged (i.e.,
1264 with packets queued) flows linked to the same pipe share the pipe's
1265 bandwidth proportionally to their weights.
1266 Note that weights are not priorities; a flow with a lower weight
1267 is still guaranteed to get its fraction of the bandwidth even if a
1268 flow with a higher weight is permanently backlogged.
1269 .El
1270 In practice,
1271 .Em pipes
1272 can be used to set hard limits to the bandwidth that a flow can use, whereas
1273 .Em queues
1274 can be used to determine how different flow share the available bandwidth.
1275 .Pp
1276 The
1277 .Em pipe
1278 and
1279 .Em queue
1280 configuration commands are the following:
1281 .Bd -ragged -offset indent
1282 .Cm pipe Ar number Cm config Ar pipe-configuration
1283 .Pp
1284 .Cm queue Ar number Cm config Ar queue-configuration
1285 .Ed
1286 .Pp
1287 The following parameters can be configured for a pipe:
1288 .Pp
1289 .Bl -tag -width indent -compact
1290 .It Cm bw Ar bandwidth
1291 Bandwidth, measured in
1292 .Sm off
1293 .Op Cm K | M
1294 .Brq Cm bit/s | Byte/s .
1295 .Sm on
1296 .Pp
1297 A value of 0 (default) means unlimited bandwidth.
1298 The unit must immediately follow the number, as in
1299 .Pp
1300 .Dl "ipfw pipe 1 config bw 300Kbit/s"
1301 .Pp
1302 .It Cm delay Ar ms-delay
1303 Propagation delay, measured in milliseconds.
1304 The value is rounded to the next multiple of the clock tick
1305 (typically 10ms, but it is a good practice to run kernels
1306 with
1307 .Cd "options HZ=1000"
1308 to reduce
1309 the granularity to 1ms or less).
1310 Default value is 0, meaning no delay.
1311 .El
1312 .Pp
1313 The following parameters can be configured for a queue:
1314 .Pp
1315 .Bl -tag -width indent -compact
1316 .It Cm pipe Ar pipe_nr
1317 Connects a queue to the specified pipe.
1318 Multiple queues (with the same or different weights) can be connected to
1319 the same pipe, which specifies the aggregate rate for the set of queues.
1320 .Pp
1321 .It Cm weight Ar weight
1322 Specifies the weight to be used for flows matching this queue.
1323 The weight must be in the range 1..100, and defaults to 1.
1324 .El
1325 .Pp
1326 Finally, the following parameters can be configured for both
1327 pipes and queues:
1328 .Pp
1329 .Bl -tag -width XXXX -compact
1330 .It Cm buckets Ar hash-table-size
1331 Specifies the size of the hash table used for storing the
1332 various queues.
1333 Default value is 64 controlled by the
1334 .Xr sysctl 8
1335 variable
1336 .Em net.inet.ip.dummynet.hash_size ,
1337 allowed range is 16 to 65536.
1338 .Pp
1339 .It Cm mask Ar mask-specifier
1340 Packets sent to a given pipe or queue by an
1341 .Nm
1342 rule can be further classified into multiple flows, each of which is then
1343 sent to a different
1344 .Em dynamic
1345 pipe or queue.
1346 A flow identifier is constructed by masking the IP addresses,
1347 ports and protocol types as specified with the
1348 .Cm mask
1349 options in the configuration of the pipe or queue.
1350 For each different flow identifier, a new pipe or queue is created
1351 with the same parameters as the original object, and matching packets
1352 are sent to it.
1353 .Pp
1354 Thus, when
1355 .Em dynamic pipes
1356 are used, each flow will get the same bandwidth as defined by the pipe,
1357 whereas when
1358 .Em dynamic queues
1359 are used, each flow will share the parent's pipe bandwidth evenly
1360 with other flows generated by the same queue (note that other queues
1361 with different weights might be connected to the same pipe).
1362 .br
1363 Available mask specifiers are a combination of one or more of the following:
1364 .Pp
1365 .Cm dst-ip Ar mask ,
1366 .Cm src-ip Ar mask ,
1367 .Cm dst-port Ar mask ,
1368 .Cm src-port Ar mask ,
1369 .Cm proto Ar mask
1370 or
1371 .Cm all ,
1372 .Pp
1373 where the latter means all bits in all fields are significant.
1374 .Pp
1375 .It Cm noerror
1376 When a packet is dropped by a dummynet queue or pipe, the error
1377 is normally reported to the caller routine in the kernel, in the
1378 same way as it happens when a device queue fills up. Setting this
1379 option reports the packet as successfully delivered, which can be
1380 needed for some experimental setups where you want to simulate
1381 loss or congestion at a remote router.
1382 .Pp
1383 .Em NOTE:
1384 This option is always on,
1385 since
1386 .Dx 1.11 .
1387 .Pp
1388 .It Cm plr Ar packet-loss-rate
1389 Packet loss rate.
1390 Argument
1391 .Ar packet-loss-rate
1392 is a floating-point number between 0 and 1, with 0 meaning no
1393 loss, 1 meaning 100% loss.
1394 The loss rate is internally represented on 31 bits.
1395 .Pp
1396 .It Cm queue Brq Ar slots | size Ns Cm Kbytes
1397 Queue size, in
1398 .Ar slots
1399 or
1400 .Cm KBytes .
1401 Default value is 50 slots, which
1402 is the typical queue size for Ethernet devices.
1403 Note that for slow speed links you should keep the queue
1404 size short or your traffic might be affected by a significant
1405 queueing delay.
1406 E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit
1407 or 20s of queue on a 30Kbit/s pipe.
1408 Even worse effect can result if you get packets from an
1409 interface with a much larger MTU, e.g. the loopback interface
1410 with its 16KB packets.
1411 .Pp
1412 .It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p
1413 Make use of the RED (Random Early Detection) queue management algorithm.
1414 .Ar w_q
1415 and
1416 .Ar max_p
1417 are floating
1418 point numbers between 0 and 1 (0 not included), while
1419 .Ar min_th
1420 and
1421 .Ar max_th
1422 are integer numbers specifying thresholds for queue management
1423 (thresholds are computed in bytes if the queue has been defined
1424 in bytes, in slots otherwise).
1425 The
1426 .Xr dummynet 4
1427 also supports the gentle RED variant (gred).
1428 Three
1429 .Xr sysctl 8
1430 variables can be used to control the RED behaviour:
1431 .Bl -tag -width indent
1432 .It Em net.inet.ip.dummynet.red_lookup_depth
1433 specifies the accuracy in computing the average queue
1434 when the link is idle (defaults to 256, must be greater than zero)
1435 .It Em net.inet.ip.dummynet.red_avg_pkt_size
1436 specifies the expected average packet size (defaults to 512, must be
1437 greater than zero)
1438 .It Em net.inet.ip.dummynet.red_max_pkt_size
1439 specifies the expected maximum packet size, only used when queue
1440 thresholds are in bytes (defaults to 1500, must be greater than zero).
1441 .El
1442 .El
1443 .Sh CHECKLIST
1444 Here are some important points to consider when designing your
1445 rules:
1446 .Bl -bullet
1447 .It
1448 Remember that you filter both packets going
1449 .Cm in
1450 and
1451 .Cm out .
1452 Most connections need packets going in both directions.
1453 .It
1454 Remember to test very carefully.
1455 It is a good idea to be near the console when doing this.
1456 If you cannot be near the console,
1457 use an auto-recovery script such as the one in
1458 .Pa /usr/share/examples/ipfw/change_rules.sh .
1459 .It
1460 Don't forget the loopback interface.
1461 .El
1462 .Sh FINE POINTS
1463 .Bl -bullet
1464 .It
1465 There are circumstances where fragmented datagrams are unconditionally
1466 dropped.
1467 TCP packets are dropped if they do not contain at least 20 bytes of
1468 TCP header, UDP packets are dropped if they do not contain a full 8
1469 byte UDP header, and ICMP packets are dropped if they do not contain
1470 4 bytes of ICMP header, enough to specify the ICMP type, code, and
1471 checksum.
1472 These packets are simply logged as
1473 .Dq pullup failed
1474 since there may not be enough good data in the packet to produce a
1475 meaningful log entry.
1476 .It
1477 Another type of packet is unconditionally dropped, a TCP packet with a
1478 fragment offset of one.
1479 This is a valid packet, but it only has one use, to try
1480 to circumvent firewalls.
1481 When logging is enabled, these packets are
1482 reported as being dropped by rule -1.
1483 .It
1484 If you are logged in over a network, loading the
1485 .Xr kld 4
1486 version of
1487 .Nm
1488 is probably not as straightforward as you would think.
1489 I recommend the following command line:
1490 .Bd -literal -offset indent
1491 kldload /boot/modules/ipfw.ko && \e
1492 ipfw add 32000 allow ip from any to any
1493 .Ed
1494 .Pp
1495 Along the same lines, doing an
1496 .Bd -literal -offset indent
1497 ipfw flush
1498 .Ed
1499 .Pp
1500 in similar surroundings is also a bad idea.
1501 .It
1502 The
1503 .Nm
1504 filter list may not be modified if the system security level
1505 is set to 3 or higher
1506 (see
1507 .Xr init 8
1508 for information on system security levels).
1509 .El
1510 .Sh PACKET DIVERSION
1511 A
1512 .Xr divert 4
1513 socket bound to the specified port will receive all packets
1514 diverted to that port.
1515 If no socket is bound to the destination port, or if the kernel
1516 wasn't compiled with divert socket support, the packets are
1517 dropped.
1518 .Sh SYSCTL VARIABLES
1519 A set of
1520 .Xr sysctl 8
1521 variables controls the behaviour of the firewall and
1522 associated modules
1523 .Nm ( dummynet ) .
1524 These are shown below together with their default value
1525 (but always check with the
1526 .Xr sysctl 8
1527 command what value is actually in use) and meaning:
1528 .Bl -tag -width indent
1529 .It Em net.inet.ip.dummynet.expire : No 1
1530 Lazily delete dynamic pipes/queue once they have no pending traffic.
1531 You can disable this by setting the variable to 0, in which case
1532 the pipes/queues will only be deleted when the threshold is reached.
1533 .It Em net.inet.ip.dummynet.hash_size : No 64
1534 Default size of the hash table used for dynamic pipes/queues.
1535 This value is used when no
1536 .Cm buckets
1537 option is specified when configuring a pipe/queue.
1538 .It Em net.inet.ip.dummynet.max_chain_len : No 16
1539 Target value for the maximum number of pipes/queues in a hash bucket.
1540 The product
1541 .Cm max_chain_len*hash_size
1542 is used to determine the threshold over which empty pipes/queues
1543 will be expired even when
1544 .Cm net.inet.ip.dummynet.expire=0 .
1545 .It Em net.inet.ip.dummynet.red_lookup_depth : No 256
1546 .It Em net.inet.ip.dummynet.red_avg_pkt_size : No 512
1547 .It Em net.inet.ip.dummynet.red_max_pkt_size : No 1500
1548 Parameters used in the computations of the drop probability
1549 for the RED algorithm.
1550 .It Em net.inet.ip.fw.autoinc_step : No 100
1551 Delta between rule numbers when auto-generating them.
1552 The value must be in the range 1..1000.
1553 .It Em net.inet.ip.fw.curr_dyn_buckets : Em net.inet.ip.fw.dyn_buckets
1554 The current number of buckets in the hash table for dynamic rules
1555 (readonly).
1556 .It Em net.inet.ip.fw.debug : No 1
1557 Controls debugging messages produced by
1558 .Nm .
1559 .It Em net.inet.ip.fw.dyn_buckets : No 256
1560 The number of buckets in the hash table for dynamic rules.
1561 Must be a power of 2, up to 65536.
1562 It only takes effect when all dynamic rules have expired, so you
1563 are advised to use a
1564 .Cm flush
1565 command to make sure that the hash table is resized.
1566 .It Em net.inet.ip.fw.dyn_count : No 3
1567 Current number of dynamic rules
1568 (read-only).
1569 .It Em net.inet.ip.fw.dyn_keepalive : No 1
1570 Enables generation of keepalive packets for
1571 .Cm keep-state
1572 rules on TCP sessions. A keepalive is generated to both
1573 sides of the connection every 5 seconds for the last 20
1574 seconds of the lifetime of the rule.
1575 .It Em net.inet.ip.fw.dyn_max : No 8192
1576 Maximum number of dynamic rules.
1577 When you hit this limit, no more dynamic rules can be
1578 installed until old ones expire.
1579 .It Em net.inet.ip.fw.dyn_ack_lifetime : No 300
1580 .It Em net.inet.ip.fw.dyn_syn_lifetime : No 20
1581 .It Em net.inet.ip.fw.dyn_fin_lifetime : No 1
1582 .It Em net.inet.ip.fw.dyn_rst_lifetime : No 1
1583 .It Em net.inet.ip.fw.dyn_udp_lifetime : No 5
1584 .It Em net.inet.ip.fw.dyn_short_lifetime : No 30
1585 These variables control the lifetime, in seconds, of dynamic
1586 rules.
1587 Upon the initial SYN exchange the lifetime is kept short,
1588 then increased after both SYN have been seen, then decreased
1589 again during the final FIN exchange or when a RST is received.
1590 Both
1591 .Em dyn_fin_lifetime
1592 and
1593 .Em dyn_rst_lifetime
1594 must be strictly lower than 5 seconds, the period of
1595 repetition of keepalives. The firewall enforces that.
1596 .It Em net.inet.ip.fw.enable : No 1
1597 Enables the firewall.
1598 Setting this variable to 0 lets you run your machine without
1599 firewall even if compiled in.
1600 .It Em net.inet.ip.fw.one_pass : No 1
1601 When set, the packet exiting from the
1602 .Xr dummynet 4
1603 pipe is not passed though the firewall again.
1604 Otherwise, after a pipe action, the packet is
1605 reinjected into the firewall at the next rule.
1606 .Pp
1607 Note: layer 2 packets coming out of a pipe
1608 are never reinjected in the firewall irrespective of the
1609 value of this variable.
1610 .It Em net.inet.ip.fw.verbose : No 1
1611 Enables verbose messages.
1612 .It Em net.inet.ip.fw.verbose_limit : No 0
1613 Limits the number of messages produced by a verbose firewall.
1614 .It Em net.link.ether.ipfw : No 0
1615 Controls whether layer-2 packets are passed to
1616 .Nm .
1617 Default is no.
1618 .El
1619 .Sh IPFW2 ENHANCEMENTS
1620 This Section lists the features that have been introduced in
1621 .Nm ipfw2
1622 which were not present in
1623 .Nm ipfw1 .
1624 We list them in order of the potential impact that they can
1625 have in writing your rulesets.
1626 You might want to consider using these features in order to
1627 write your rulesets in a more efficient way.
1628 .Bl -tag -width indent
1629 .It Handling of non-IPv4 packets
1630 .Nm ipfw1
1631 will silently accept all non-IPv4 packets.
1632 .Nm ipfw2
1633 will filter all packets (including non-IPv4 ones) according to the ruleset.
1634 To achieve the same behaviour as
1635 .Nm ipfw1
1636 you can use the following as the very first rule in your ruleset:
1637 .Pp
1638 .Dl "ipfw add 1 allow layer2 not mac-type ip"
1639 .Pp
1640 The
1641 .Cm layer2
1642 option might seem redundant, but it is necessary -- packets
1643 passed to the firewall from layer3 will not have a MAC header,
1644 so the
1645 .Cm mac-type ip
1646 pattern will always fail on them, and the
1647 .Cm not
1648 operator will make this rule into a pass-all.
1649 .It Address sets
1650 .Nm ipfw1
1651 does not supports address sets (those in the form
1652 .Ar addr/masklen{num,num,...} ) .
1653 .Pp
1654 .It Port specifications
1655 .Nm ipfw1
1656 only allows one port range when specifying TCP and UDP ports, and
1657 is limited to 10 entries instead of the 15 allowed by
1658 .Nm ipfw2 .
1659 Also, in
1660 .Nm ipfw1
1661 you can only specify ports when the rule is requesting
1662 .Cm tcp
1663 or
1664 .Cm udp
1665 packets. With
1666 .Nm ipfw2
1667 you can put port specifications in rules matching all packets,
1668 and the match will be attempted only on those packets carrying
1669 protocols which include port identifiers.
1670 .Pp
1671 Finally,
1672 .Nm ipfw1
1673 allowed the first port entry to be specified as
1674 .Ar port:mask
1675 where
1676 .Ar mask
1677 can be an arbitrary 16-bit mask.
1678 This syntax is of questionable usefulness and it is not
1679 supported anymore in
1680 .Nm ipfw2 .
1681 .It Or-blocks
1682 .Nm ipfw1
1683 does not support Or-blocks.
1684 .It keepalives
1685 .Nm ipfw1
1686 does not generate keepalives for stateful sessions.
1687 As a consequence, it might cause idle sessions to drop because
1688 the lifetime of the dynamic rules expires.
1689 .It Sets of rules
1690 .Nm ipfw1
1691 does not implement sets of rules.
1692 .It MAC header filtering and Layer-2 firewalling.
1693 .Nm ipfw1
1694 does not implement filtering on MAC header fields, nor is it
1695 invoked on packets from
1696 .Fn ether_demux_oncpu
1697 and
1698 .Fn ether_output_frame .
1699 The sysctl variable
1700 .Em net.link.ether.ipfw
1701 has no effect there.
1702 .It Options
1703 The following options are not supported in
1704 .Nm ipfw1
1705 .Pp
1706 .Cm dst-ip, dst-port, layer2, mac, mac-type, src-ip, src-port.
1707 .Pp
1708 Additionally, the following options are not supported in
1709 .Nm ipfw1
1710 (RELENG_4)
1711 rules:
1712 .Pp
1713 .Cm ipid, iplen, ipprecedence, iptos, ipttl,
1714 .Cm ipversion, tcpack, tcpseq, tcpwin .
1715 .It Dummynet options
1716 The following option for
1717 .Nm dummynet
1718 pipes/queues is not supported:
1719 .Cm noerror .
1720 .El
1721 .Sh EXAMPLES
1722 There are far too many possible uses of
1723 .Nm
1724 so this Section will only give a small set of examples.
1725 .Ss BASIC PACKET FILTERING
1726 This command adds an entry which denies all tcp packets from
1727 .Em cracker.evil.org
1728 to the telnet port of
1729 .Em wolf.tambov.su
1730 from being forwarded by the host:
1731 .Pp
1732 .Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet"
1733 .Pp
1734 This one disallows any connection from the entire cracker's
1735 network to my host:
1736 .Pp
1737 .Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org"
1738 .Pp
1739 A first and efficient way to limit access (not using dynamic rules)
1740 is the use of the following rules:
1741 .Pp
1742 .Dl "ipfw add allow tcp from any to any established"
1743 .Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup"
1744 .Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup"
1745 .Dl "..."
1746 .Dl "ipfw add deny tcp from any to any"
1747 .Pp
1748 The first rule will be a quick match for normal TCP packets,
1749 but it will not match the initial SYN packet, which will be
1750 matched by the
1751 .Cm setup
1752 rules only for selected source/destination pairs.
1753 All other SYN packets will be rejected by the final
1754 .Cm deny
1755 rule.
1756 .Pp
1757 If you administer one or more subnets, you can take advantage of the
1758 .Nm ipfw2
1759 syntax to specify address sets and or-blocks and write extremely
1760 compact rulesets which selectively enable services to blocks
1761 of clients, as below:
1762 .Pp
1763 .Dl "goodguys=\*q{ 10.1.2.0/24{20,35,66,18} or 10.2.3.0/28{6,3,11} }\*q"
1764 .Dl "badguys=\*q10.1.2.0/24{8,38,60}\*q"
1765 .Dl ""
1766 .Dl "ipfw add allow ip from ${goodguys} to any"
1767 .Dl "ipfw add deny ip from ${badguys} to any"
1768 .Dl "... normal policies ..."
1769 .Pp
1770 The
1771 .Nm ipfw1
1772 syntax would require a separate rule for each IP in the above
1773 example.
1774 .Ss DYNAMIC RULES
1775 In order to protect a site from flood attacks involving fake
1776 TCP packets, it is safer to use dynamic rules:
1777 .Pp
1778 .Dl "ipfw add check-state"
1779 .Dl "ipfw add deny tcp from any to any established"
1780 .Dl "ipfw add allow tcp from my-net to any setup keep-state"
1781 .Pp
1782 This will let the firewall install dynamic rules only for
1783 those connection which start with a regular SYN packet coming
1784 from the inside of our network.
1785 Dynamic rules are checked when encountering the first
1786 .Cm check-state
1787 or
1788 .Cm keep-state
1789 rule.
1790 A
1791 .Cm check-state
1792 rule should usually be placed near the beginning of the
1793 ruleset to minimize the amount of work scanning the ruleset.
1794 Your mileage may vary.
1795 .Pp
1796 To limit the number of connections a user can open
1797 you can use the following type of rules:
1798 .Pp
1799 .Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10"
1800 .Dl "ipfw add allow tcp from any to me setup limit src-addr 4"
1801 .Pp
1802 The former (assuming it runs on a gateway) will allow each host
1803 on a /24 network to open at most 10 TCP connections.
1804 The latter can be placed on a server to make sure that a single
1805 client does not use more than 4 simultaneous connections.
1806 .Pp
1807 .Em BEWARE :
1808 stateful rules can be subject to denial-of-service attacks
1809 by a SYN-flood which opens a huge number of dynamic rules.
1810 The effects of such attacks can be partially limited by
1811 acting on a set of
1812 .Xr sysctl 8
1813 variables which control the operation of the firewall.
1814 .Pp
1815 Here is a good usage of the
1816 .Cm list
1817 command to see accounting records and timestamp information:
1818 .Pp
1819 .Dl ipfw -at list
1820 .Pp
1821 or in short form without timestamps:
1822 .Pp
1823 .Dl ipfw -a list
1824 .Pp
1825 which is equivalent to:
1826 .Pp
1827 .Dl ipfw show
1828 .Pp
1829 Next rule diverts all incoming packets from 192.168.2.0/24
1830 to divert port 5000:
1831 .Pp
1832 .Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in
1833 .Ss TRAFFIC SHAPING
1834 The following rules show some of the applications of
1835 .Nm
1836 and
1837 .Xr dummynet 4
1838 for simulations and the like.
1839 .Pp
1840 This rule drops random incoming packets with a probability
1841 of 5%:
1842 .Pp
1843 .Dl "ipfw add prob 0.05 deny ip from any to any in"
1844 .Pp
1845 A similar effect can be achieved making use of dummynet pipes:
1846 .Pp
1847 .Dl "ipfw add pipe 10 ip from any to any"
1848 .Dl "ipfw pipe 10 config plr 0.05"
1849 .Pp
1850 We can use pipes to artificially limit bandwidth, e.g. on a
1851 machine acting as a router, if we want to limit traffic from
1852 local clients on 192.168.2.0/24 we do:
1853 .Pp
1854 .Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out"
1855 .Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes"
1856 .Pp
1857 note that we use the
1858 .Cm out
1859 modifier so that the rule is not used twice.
1860 Remember in fact that
1861 .Nm
1862 rules are checked both on incoming and outgoing packets.
1863 .Pp
1864 Should we want to simulate a bidirectional link with bandwidth
1865 limitations, the correct way is the following:
1866 .Pp
1867 .Dl "ipfw add pipe 1 ip from any to any out"
1868 .Dl "ipfw add pipe 2 ip from any to any in"
1869 .Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes"
1870 .Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes"
1871 .Pp
1872 The above can be very useful, e.g. if you want to see how
1873 your fancy Web page will look for a residential user who
1874 is connected only through a slow link.
1875 You should not use only one pipe for both directions, unless
1876 you want to simulate a half-duplex medium (e.g. AppleTalk,
1877 Ethernet, IRDA).
1878 It is not necessary that both pipes have the same configuration,
1879 so we can also simulate asymmetric links.
1880 .Pp
1881 Should we want to verify network performance with the RED queue
1882 management algorithm:
1883 .Pp
1884 .Dl "ipfw add pipe 1 ip from any to any"
1885 .Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1"
1886 .Pp
1887 Another typical application of the traffic shaper is to
1888 introduce some delay in the communication.
1889 This can significantly affect applications which do a lot of Remote
1890 Procedure Calls, and where the round-trip-time of the
1891 connection often becomes a limiting factor much more than
1892 bandwidth:
1893 .Pp
1894 .Dl "ipfw add pipe 1 ip from any to any out"
1895 .Dl "ipfw add pipe 2 ip from any to any in"
1896 .Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s"
1897 .Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s"
1898 .Pp
1899 Per-flow queueing can be useful for a variety of purposes.
1900 A very simple one is counting traffic:
1901 .Pp
1902 .Dl "ipfw add pipe 1 tcp from any to any"
1903 .Dl "ipfw add pipe 1 udp from any to any"
1904 .Dl "ipfw add pipe 1 ip from any to any"
1905 .Dl "ipfw pipe 1 config mask all"
1906 .Pp
1907 The above set of rules will create queues (and collect
1908 statistics) for all traffic.
1909 Because the pipes have no limitations, the only effect is
1910 collecting statistics.
1911 Note that we need 3 rules, not just the last one, because
1912 when
1913 .Nm
1914 tries to match IP packets it will not consider ports, so we
1915 would not see connections on separate ports as different
1916 ones.
1917 .Pp
1918 A more sophisticated example is limiting the outbound traffic
1919 on a net with per-host limits, rather than per-network limits:
1920 .Pp
1921 .Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out"
1922 .Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in"
1923 .Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
1924 .Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
1925 .Ss SETS OF RULES
1926 To add a set of rules atomically, e.g. set 18:
1927 .Pp
1928 .Dl "ipfw disable set 18"
1929 .Dl "ipfw add NN set 18 ...         # repeat as needed"
1930 .Dl "ipfw enable set 18"
1931 .Pp
1932 To delete a set of rules atomically the command is simply:
1933 .Pp
1934 .Dl "ipfw delete set 18"
1935 .Pp
1936 To test a ruleset and disable it and regain control if something goes wrong:
1937 .Pp
1938 .Dl "ipfw disable set 18"
1939 .Dl "ipfw add NN set 18 ...         # repeat as needed"
1940 .Dl "ipfw enable set 18 ; echo done; sleep 30 && ipfw disable set 18"
1941 .Pp
1942 Here if everything goes well, you press control-C before the "sleep"
1943 terminates, and your ruleset will be left active. Otherwise, e.g. if
1944 you cannot access your box, the ruleset will be disabled after
1945 the sleep terminates thus restoring the previous situation.
1946 .Sh SEE ALSO
1947 .Xr cpp 1 ,
1948 .Xr m4 1 ,
1949 .Xr divert 4 ,
1950 .Xr dummynet 4 ,
1951 .Xr ip 4 ,
1952 .Xr ipfirewall 4 ,
1953 .Xr protocols 5 ,
1954 .Xr services 5 ,
1955 .Xr init 8 ,
1956 .Xr kldload 8 ,
1957 .Xr reboot 8 ,
1958 .Xr sysctl 8 ,
1959 .Xr syslogd 8
1960 .Sh HISTORY
1961 The
1962 .Nm
1963 utility first appeared in
1964 .Fx 2.0 .
1965 .Xr dummynet 4
1966 was introduced in
1967 .Fx 2.2.8 .
1968 Stateful extensions were introduced in
1969 .Fx 4.0 .
1970 .Nm ipfw2
1971 was introduced in Summer 2002.
1972 .Sh AUTHORS
1973 .An Ugen J. S. Antsilevich ,
1974 .An Poul-Henning Kamp ,
1975 .An Alex Nash ,
1976 .An Archie Cobbs ,
1977 .An Luigi Rizzo .
1978 .Pp
1979 .An -nosplit
1980 API based upon code written by
1981 .An Daniel Boulet
1982 for BSDI.
1983 .Pp
1984 Work on
1985 .Xr dummynet 4
1986 traffic shaper supported by Akamba Corp.
1987 .Sh BUGS
1988 The syntax has grown over the years and sometimes it might be confusing.
1989 Unfortunately, backward compatibility prevents cleaning up mistakes
1990 made in the definition of the syntax.
1991 .Pp
1992 .Em !!! WARNING !!!
1993 .Pp
1994 Misconfiguring the firewall can put your computer in an unusable state,
1995 possibly shutting down network services and requiring console access to
1996 regain control of it.
1997 .Pp
1998 Incoming packet fragments diverted by
1999 .Cm divert
2000 or
2001 .Cm tee
2002 are reassembled before delivery to the socket.
2003 The action used on those packet is the one from the
2004 rule which matches the first fragment of the packet.
2005 .Pp
2006 Packets that match a
2007 .Cm tee
2008 rule should not be immediately accepted, but should continue
2009 going through the rule list.
2010 This may be fixed in a later version.
2011 .Pp
2012 Packets diverted to userland, and then reinserted by a userland process
2013 (such as
2014 .Xr natd 8 )
2015 will lose various packet attributes, including their source interface.
2016 If a packet is reinserted in this manner, later rules may be incorrectly
2017 applied, making the order of
2018 .Cm divert
2019 rules in the rule sequence very important.