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