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