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