xref: /freebsd/sbin/ipfw/ipfw.8 (revision a0ee8cc636cd5c2374ec44ca71226564ea0bca95)
1.\"
2.\" $FreeBSD$
3.\"
4.Dd March 13, 2015
5.Dt IPFW 8
6.Os
7.Sh NAME
8.Nm ipfw
9.Nd User interface for firewall, traffic shaper, packet scheduler,
10in-kernel NAT.
11.Sh SYNOPSIS
12.Ss FIREWALL CONFIGURATION
13.Nm
14.Op Fl cq
15.Cm add
16.Ar rule
17.Nm
18.Op Fl acdefnNStT
19.Op Cm set Ar N
20.Brq Cm list | show
21.Op Ar rule | first-last ...
22.Nm
23.Op Fl f | q
24.Op Cm set Ar N
25.Cm flush
26.Nm
27.Op Fl q
28.Op Cm set Ar N
29.Brq Cm delete | zero | resetlog
30.Op Ar number ...
31.Pp
32.Nm
33.Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ...
34.Nm
35.Cm set move
36.Op Cm rule
37.Ar number Cm to Ar number
38.Nm
39.Cm set swap Ar number number
40.Nm
41.Cm set show
42.Ss SYSCTL SHORTCUTS
43.Nm
44.Cm enable
45.Brq Cm firewall | altq | one_pass | debug | verbose | dyn_keepalive
46.Nm
47.Cm disable
48.Brq Cm firewall | altq | one_pass | debug | verbose | dyn_keepalive
49.Ss LOOKUP TABLES
50.Nm
51.Oo Cm set Ar N Oc Cm table Ar name Cm create Ar create-options
52.Nm
53.Oo Cm set Ar N Oc Cm table Ar name Cm destroy
54.Nm
55.Oo Cm set Ar N Oc Cm table Ar name Cm modify Ar modify-options
56.Nm
57.Oo Cm set Ar N Oc Cm table Ar name Cm swap Ar name
58.Nm
59.Oo Cm set Ar N Oc Cm table Ar name Cm add Ar table-key Op Ar value
60.Nm
61.Oo Cm set Ar N Oc Cm table Ar name Cm add Op Ar table-key Ar value ...
62.Nm
63.Oo Cm set Ar N Oc Cm table Ar name Cm atomic add Op Ar table-key Ar value ...
64.Nm
65.Oo Cm set Ar N Oc Cm table Ar name Cm delete Op Ar table-key ...
66.Nm
67.Oo Cm set Ar N Oc Cm table Ar name Cm lookup Ar addr
68.Nm
69.Oo Cm set Ar N Oc Cm table Ar name Cm lock
70.Nm
71.Oo Cm set Ar N Oc Cm table Ar name Cm unlock
72.Nm
73.Oo Cm set Ar N Oc Cm table
74.Brq Ar name | all
75.Cm list
76.Nm
77.Oo Cm set Ar N Oc Cm table
78.Brq Ar name | all
79.Cm info
80.Nm
81.Oo Cm set Ar N Oc Cm table
82.Brq Ar name | all
83.Cm detail
84.Nm
85.Oo Cm set Ar N Oc Cm table
86.Brq Ar name | all
87.Cm flush
88.Ss DUMMYNET CONFIGURATION (TRAFFIC SHAPER AND PACKET SCHEDULER)
89.Nm
90.Brq Cm pipe | queue | sched
91.Ar number
92.Cm config
93.Ar config-options
94.Nm
95.Op Fl s Op Ar field
96.Brq Cm pipe | queue | sched
97.Brq Cm delete | list | show
98.Op Ar number ...
99.Ss IN-KERNEL NAT
100.Nm
101.Op Fl q
102.Cm nat
103.Ar number
104.Cm config
105.Ar config-options
106.Pp
107.Nm
108.Op Fl cfnNqS
109.Oo
110.Fl p Ar preproc
111.Oo
112.Ar preproc-flags
113.Oc
114.Oc
115.Ar pathname
116.Ss INTERNAL DIAGNOSTICS
117.Nm
118.Cm internal iflist
119.Nm
120.Cm internal talist
121.Nm
122.Cm internal vlist
123.Sh DESCRIPTION
124The
125.Nm
126utility is the user interface for controlling the
127.Xr ipfw 4
128firewall, the
129.Xr dummynet 4
130traffic shaper/packet scheduler, and the
131in-kernel NAT services.
132.Pp
133A firewall configuration, or
134.Em ruleset ,
135is made of a list of
136.Em rules
137numbered from 1 to 65535.
138Packets are passed to the firewall
139from a number of different places in the protocol stack
140(depending on the source and destination of the packet,
141it is possible for the firewall to be
142invoked multiple times on the same packet).
143The packet passed to the firewall is compared
144against each of the rules in the
145.Em ruleset ,
146in rule-number order
147(multiple rules with the same number are permitted, in which case
148they are processed in order of insertion).
149When a match is found, the action corresponding to the
150matching rule is performed.
151.Pp
152Depending on the action and certain system settings, packets
153can be reinjected into the firewall at some rule after the
154matching one for further processing.
155.Pp
156A ruleset always includes a
157.Em default
158rule (numbered 65535) which cannot be modified or deleted,
159and matches all packets.
160The action associated with the
161.Em default
162rule can be either
163.Cm deny
164or
165.Cm allow
166depending on how the kernel is configured.
167.Pp
168If the ruleset includes one or more rules with the
169.Cm keep-state
170or
171.Cm limit
172option,
173the firewall will have a
174.Em stateful
175behaviour, i.e., upon a match it will create
176.Em dynamic rules ,
177i.e., rules that match packets with the same 5-tuple
178(protocol, source and destination addresses and ports)
179as the packet which caused their creation.
180Dynamic rules, which have a limited lifetime, are checked
181at the first occurrence of a
182.Cm check-state ,
183.Cm keep-state
184or
185.Cm limit
186rule, and are typically used to open the firewall on-demand to
187legitimate traffic only.
188See the
189.Sx STATEFUL FIREWALL
190and
191.Sx EXAMPLES
192Sections below for more information on the stateful behaviour of
193.Nm .
194.Pp
195All rules (including dynamic ones) have a few associated counters:
196a packet count, a byte count, a log count and a timestamp
197indicating the time of the last match.
198Counters can be displayed or reset with
199.Nm
200commands.
201.Pp
202Each rule belongs to one of 32 different
203.Em sets
204, and there are
205.Nm
206commands to atomically manipulate sets, such as enable,
207disable, swap sets, move all rules in a set to another
208one, delete all rules in a set.
209These can be useful to
210install temporary configurations, or to test them.
211See Section
212.Sx SETS OF RULES
213for more information on
214.Em sets .
215.Pp
216Rules can be added with the
217.Cm add
218command; deleted individually or in groups with the
219.Cm delete
220command, and globally (except those in set 31) with the
221.Cm flush
222command; displayed, optionally with the content of the
223counters, using the
224.Cm show
225and
226.Cm list
227commands.
228Finally, counters can be reset with the
229.Cm zero
230and
231.Cm resetlog
232commands.
233.Pp
234.Ss COMMAND OPTIONS
235The following general options are available when invoking
236.Nm :
237.Bl -tag -width indent
238.It Fl a
239Show counter values when listing rules.
240The
241.Cm show
242command implies this option.
243.It Fl b
244Only show the action and the comment, not the body of a rule.
245Implies
246.Fl c .
247.It Fl c
248When entering or showing rules, print them in compact form,
249i.e., omitting the "ip from any to any" string
250when this does not carry any additional information.
251.It Fl d
252When listing, show dynamic rules in addition to static ones.
253.It Fl e
254When listing and
255.Fl d
256is specified, also show expired dynamic rules.
257.It Fl f
258Do not ask for confirmation for commands that can cause problems
259if misused, i.e.,
260.Cm flush .
261If there is no tty associated with the process, this is implied.
262.It Fl i
263When listing a table (see the
264.Sx LOOKUP TABLES
265section below for more information on lookup tables), format values
266as IP addresses.
267By default, values are shown as integers.
268.It Fl n
269Only check syntax of the command strings, without actually passing
270them to the kernel.
271.It Fl N
272Try to resolve addresses and service names in output.
273.It Fl q
274Be quiet when executing the
275.Cm add ,
276.Cm nat ,
277.Cm zero ,
278.Cm resetlog
279or
280.Cm flush
281commands;
282(implies
283.Fl f ) .
284This is useful when updating rulesets by executing multiple
285.Nm
286commands in a script
287(e.g.,
288.Ql sh\ /etc/rc.firewall ) ,
289or by processing a file with many
290.Nm
291rules across a remote login session.
292It also stops a table add or delete
293from failing if the entry already exists or is not present.
294.Pp
295The reason why this option may be important is that
296for some of these actions,
297.Nm
298may print a message; if the action results in blocking the
299traffic to the remote client,
300the remote login session will be closed
301and the rest of the ruleset will not be processed.
302Access to the console would then be required to recover.
303.It Fl S
304When listing rules, show the
305.Em set
306each rule belongs to.
307If this flag is not specified, disabled rules will not be
308listed.
309.It Fl s Op Ar field
310When listing pipes, sort according to one of the four
311counters (total or current packets or bytes).
312.It Fl t
313When listing, show last match timestamp converted with ctime().
314.It Fl T
315When listing, show last match timestamp as seconds from the epoch.
316This form can be more convenient for postprocessing by scripts.
317.El
318.Ss LIST OF RULES AND PREPROCESSING
319To ease configuration, rules can be put into a file which is
320processed using
321.Nm
322as shown in the last synopsis line.
323An absolute
324.Ar pathname
325must be used.
326The file will be read line by line and applied as arguments to the
327.Nm
328utility.
329.Pp
330Optionally, a preprocessor can be specified using
331.Fl p Ar preproc
332where
333.Ar pathname
334is to be piped through.
335Useful preprocessors include
336.Xr cpp 1
337and
338.Xr m4 1 .
339If
340.Ar preproc
341does not start with a slash
342.Pq Ql /
343as its first character, the usual
344.Ev PATH
345name search is performed.
346Care should be taken with this in environments where not all
347file systems are mounted (yet) by the time
348.Nm
349is being run (e.g.\& when they are mounted over NFS).
350Once
351.Fl p
352has been specified, any additional arguments are passed on to the preprocessor
353for interpretation.
354This allows for flexible configuration files (like conditionalizing
355them on the local hostname) and the use of macros to centralize
356frequently required arguments like IP addresses.
357.Ss TRAFFIC SHAPER CONFIGURATION
358The
359.Nm
360.Cm pipe , queue
361and
362.Cm sched
363commands are used to configure the traffic shaper and packet scheduler.
364See the
365.Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION
366Section below for details.
367.Pp
368If the world and the kernel get out of sync the
369.Nm
370ABI may break, preventing you from being able to add any rules.
371This can adversely affect the booting process.
372You can use
373.Nm
374.Cm disable
375.Cm firewall
376to temporarily disable the firewall to regain access to the network,
377allowing you to fix the problem.
378.Sh PACKET FLOW
379A packet is checked against the active ruleset in multiple places
380in the protocol stack, under control of several sysctl variables.
381These places and variables are shown below, and it is important to
382have this picture in mind in order to design a correct ruleset.
383.Bd -literal -offset indent
384       ^    to upper layers    V
385       |                       |
386       +----------->-----------+
387       ^                       V
388 [ip(6)_input]           [ip(6)_output]     net.inet(6).ip(6).fw.enable=1
389       |                       |
390       ^                       V
391 [ether_demux]        [ether_output_frame]  net.link.ether.ipfw=1
392       |                       |
393       +-->--[bdg_forward]-->--+            net.link.bridge.ipfw=1
394       ^                       V
395       |      to devices       |
396.Ed
397.Pp
398The number of
399times the same packet goes through the firewall can
400vary between 0 and 4 depending on packet source and
401destination, and system configuration.
402.Pp
403Note that as packets flow through the stack, headers can be
404stripped or added to it, and so they may or may not be available
405for inspection.
406E.g., incoming packets will include the MAC header when
407.Nm
408is invoked from
409.Cm ether_demux() ,
410but the same packets will have the MAC header stripped off when
411.Nm
412is invoked from
413.Cm ip_input()
414or
415.Cm ip6_input() .
416.Pp
417Also note that each packet is always checked against the complete ruleset,
418irrespective of the place where the check occurs, or the source of the packet.
419If a rule contains some match patterns or actions which are not valid
420for the place of invocation (e.g.\& trying to match a MAC header within
421.Cm ip_input
422or
423.Cm ip6_input ),
424the match pattern will not match, but a
425.Cm not
426operator in front of such patterns
427.Em will
428cause the pattern to
429.Em always
430match on those packets.
431It is thus the responsibility of
432the programmer, if necessary, to write a suitable ruleset to
433differentiate among the possible places.
434.Cm skipto
435rules can be useful here, as an example:
436.Bd -literal -offset indent
437# packets from ether_demux or bdg_forward
438ipfw add 10 skipto 1000 all from any to any layer2 in
439# packets from ip_input
440ipfw add 10 skipto 2000 all from any to any not layer2 in
441# packets from ip_output
442ipfw add 10 skipto 3000 all from any to any not layer2 out
443# packets from ether_output_frame
444ipfw add 10 skipto 4000 all from any to any layer2 out
445.Ed
446.Pp
447(yes, at the moment there is no way to differentiate between
448ether_demux and bdg_forward).
449.Sh SYNTAX
450In general, each keyword or argument must be provided as
451a separate command line argument, with no leading or trailing
452spaces.
453Keywords are case-sensitive, whereas arguments may
454or may not be case-sensitive depending on their nature
455(e.g.\& uid's are, hostnames are not).
456.Pp
457Some arguments (e.g., port or address lists) are comma-separated
458lists of values.
459In this case, spaces after commas ',' are allowed to make
460the line more readable.
461You can also put the entire
462command (including flags) into a single argument.
463E.g., the following forms are equivalent:
464.Bd -literal -offset indent
465ipfw -q add deny src-ip 10.0.0.0/24,127.0.0.1/8
466ipfw -q add deny src-ip 10.0.0.0/24, 127.0.0.1/8
467ipfw "-q add deny src-ip 10.0.0.0/24, 127.0.0.1/8"
468.Ed
469.Sh RULE FORMAT
470The format of firewall rules is the following:
471.Bd -ragged -offset indent
472.Bk -words
473.Op Ar rule_number
474.Op Cm set Ar set_number
475.Op Cm prob Ar match_probability
476.Ar action
477.Op Cm log Op Cm logamount Ar number
478.Op Cm altq Ar queue
479.Oo
480.Bro Cm tag | untag
481.Brc Ar number
482.Oc
483.Ar body
484.Ek
485.Ed
486.Pp
487where the body of the rule specifies which information is used
488for filtering packets, among the following:
489.Pp
490.Bl -tag -width "Source and dest. addresses and ports" -offset XXX -compact
491.It Layer-2 header fields
492When available
493.It IPv4 and IPv6 Protocol
494TCP, UDP, ICMP, etc.
495.It Source and dest. addresses and ports
496.It Direction
497See Section
498.Sx PACKET FLOW
499.It Transmit and receive interface
500By name or address
501.It Misc. IP header fields
502Version, type of service, datagram length, identification,
503fragment flag (non-zero IP offset),
504Time To Live
505.It IP options
506.It IPv6 Extension headers
507Fragmentation, Hop-by-Hop options,
508Routing Headers, Source routing rthdr0, Mobile IPv6 rthdr2, IPSec options.
509.It IPv6 Flow-ID
510.It Misc. TCP header fields
511TCP flags (SYN, FIN, ACK, RST, etc.),
512sequence number, acknowledgment number,
513window
514.It TCP options
515.It ICMP types
516for ICMP packets
517.It ICMP6 types
518for ICMP6 packets
519.It User/group ID
520When the packet can be associated with a local socket.
521.It Divert status
522Whether a packet came from a divert socket (e.g.,
523.Xr natd 8 ) .
524.It Fib annotation state
525Whether a packet has been tagged for using a specific FIB (routing table)
526in future forwarding decisions.
527.El
528.Pp
529Note that some of the above information, e.g.\& source MAC or IP addresses and
530TCP/UDP ports, can be easily spoofed, so filtering on those fields
531alone might not guarantee the desired results.
532.Bl -tag -width indent
533.It Ar rule_number
534Each rule is associated with a
535.Ar rule_number
536in the range 1..65535, with the latter reserved for the
537.Em default
538rule.
539Rules are checked sequentially by rule number.
540Multiple rules can have the same number, in which case they are
541checked (and listed) according to the order in which they have
542been added.
543If a rule is entered without specifying a number, the kernel will
544assign one in such a way that the rule becomes the last one
545before the
546.Em default
547rule.
548Automatic rule numbers are assigned by incrementing the last
549non-default rule number by the value of the sysctl variable
550.Ar net.inet.ip.fw.autoinc_step
551which defaults to 100.
552If this is not possible (e.g.\& because we would go beyond the
553maximum allowed rule number), the number of the last
554non-default value is used instead.
555.It Cm set Ar set_number
556Each rule is associated with a
557.Ar set_number
558in the range 0..31.
559Sets can be individually disabled and enabled, so this parameter
560is of fundamental importance for atomic ruleset manipulation.
561It can be also used to simplify deletion of groups of rules.
562If a rule is entered without specifying a set number,
563set 0 will be used.
564.br
565Set 31 is special in that it cannot be disabled,
566and rules in set 31 are not deleted by the
567.Nm ipfw flush
568command (but you can delete them with the
569.Nm ipfw delete set 31
570command).
571Set 31 is also used for the
572.Em default
573rule.
574.It Cm prob Ar match_probability
575A match is only declared with the specified probability
576(floating point number between 0 and 1).
577This can be useful for a number of applications such as
578random packet drop or
579(in conjunction with
580.Nm dummynet )
581to simulate the effect of multiple paths leading to out-of-order
582packet delivery.
583.Pp
584Note: this condition is checked before any other condition, including
585ones such as keep-state or check-state which might have side effects.
586.It Cm log Op Cm logamount Ar number
587Packets matching a rule with the
588.Cm log
589keyword will be made available for logging in two ways:
590if the sysctl variable
591.Va net.inet.ip.fw.verbose
592is set to 0 (default), one can use
593.Xr bpf 4
594attached to the
595.Li ipfw0
596pseudo interface.
597This pseudo interface can be created after a boot
598manually by using the following command:
599.Bd -literal -offset indent
600# ifconfig ipfw0 create
601.Ed
602.Pp
603Or, automatically at boot time by adding the following
604line to the
605.Xr rc.conf 5
606file:
607.Bd -literal -offset indent
608firewall_logif="YES"
609.Ed
610.Pp
611There is no overhead if no
612.Xr bpf 4
613is attached to the pseudo interface.
614.Pp
615If
616.Va net.inet.ip.fw.verbose
617is set to 1, packets will be logged to
618.Xr syslogd 8
619with a
620.Dv LOG_SECURITY
621facility up to a maximum of
622.Cm logamount
623packets.
624If no
625.Cm logamount
626is specified, the limit is taken from the sysctl variable
627.Va net.inet.ip.fw.verbose_limit .
628In both cases, a value of 0 means unlimited logging.
629.Pp
630Once the limit is reached, logging can be re-enabled by
631clearing the logging counter or the packet counter for that entry, see the
632.Cm resetlog
633command.
634.Pp
635Note: logging is done after all other packet matching conditions
636have been successfully verified, and before performing the final
637action (accept, deny, etc.) on the packet.
638.It Cm tag Ar number
639When a packet matches a rule with the
640.Cm tag
641keyword, the numeric tag for the given
642.Ar number
643in the range 1..65534 will be attached to the packet.
644The tag acts as an internal marker (it is not sent out over
645the wire) that can be used to identify these packets later on.
646This can be used, for example, to provide trust between interfaces
647and to start doing policy-based filtering.
648A packet can have multiple tags at the same time.
649Tags are "sticky", meaning once a tag is applied to a packet by a
650matching rule it exists until explicit removal.
651Tags are kept with the packet everywhere within the kernel, but are
652lost when packet leaves the kernel, for example, on transmitting
653packet out to the network or sending packet to a
654.Xr divert 4
655socket.
656.Pp
657To check for previously applied tags, use the
658.Cm tagged
659rule option.
660To delete previously applied tag, use the
661.Cm untag
662keyword.
663.Pp
664Note: since tags are kept with the packet everywhere in kernelspace,
665they can be set and unset anywhere in the kernel network subsystem
666(using the
667.Xr mbuf_tags 9
668facility), not only by means of the
669.Xr ipfw 4
670.Cm tag
671and
672.Cm untag
673keywords.
674For example, there can be a specialized
675.Xr netgraph 4
676node doing traffic analyzing and tagging for later inspecting
677in firewall.
678.It Cm untag Ar number
679When a packet matches a rule with the
680.Cm untag
681keyword, the tag with the number
682.Ar number
683is searched among the tags attached to this packet and,
684if found, removed from it.
685Other tags bound to packet, if present, are left untouched.
686.It Cm altq Ar queue
687When a packet matches a rule with the
688.Cm altq
689keyword, the ALTQ identifier for the given
690.Ar queue
691(see
692.Xr altq 4 )
693will be attached.
694Note that this ALTQ tag is only meaningful for packets going "out" of IPFW,
695and not being rejected or going to divert sockets.
696Note that if there is insufficient memory at the time the packet is
697processed, it will not be tagged, so it is wise to make your ALTQ
698"default" queue policy account for this.
699If multiple
700.Cm altq
701rules match a single packet, only the first one adds the ALTQ classification
702tag.
703In doing so, traffic may be shaped by using
704.Cm count Cm altq Ar queue
705rules for classification early in the ruleset, then later applying
706the filtering decision.
707For example,
708.Cm check-state
709and
710.Cm keep-state
711rules may come later and provide the actual filtering decisions in
712addition to the fallback ALTQ tag.
713.Pp
714You must run
715.Xr pfctl 8
716to set up the queues before IPFW will be able to look them up by name,
717and if the ALTQ disciplines are rearranged, the rules in containing the
718queue identifiers in the kernel will likely have gone stale and need
719to be reloaded.
720Stale queue identifiers will probably result in misclassification.
721.Pp
722All system ALTQ processing can be turned on or off via
723.Nm
724.Cm enable Ar altq
725and
726.Nm
727.Cm disable Ar altq .
728The usage of
729.Va net.inet.ip.fw.one_pass
730is irrelevant to ALTQ traffic shaping, as the actual rule action is followed
731always after adding an ALTQ tag.
732.El
733.Ss RULE ACTIONS
734A rule can be associated with one of the following actions, which
735will be executed when the packet matches the body of the rule.
736.Bl -tag -width indent
737.It Cm allow | accept | pass | permit
738Allow packets that match rule.
739The search terminates.
740.It Cm check-state
741Checks the packet against the dynamic ruleset.
742If a match is found, execute the action associated with
743the rule which generated this dynamic rule, otherwise
744move to the next rule.
745.br
746.Cm Check-state
747rules do not have a body.
748If no
749.Cm check-state
750rule is found, the dynamic ruleset is checked at the first
751.Cm keep-state
752or
753.Cm limit
754rule.
755.It Cm count
756Update counters for all packets that match rule.
757The search continues with the next rule.
758.It Cm deny | drop
759Discard packets that match this rule.
760The search terminates.
761.It Cm divert Ar port
762Divert packets that match this rule to the
763.Xr divert 4
764socket bound to port
765.Ar port .
766The search terminates.
767.It Cm fwd | forward Ar ipaddr | tablearg Ns Op , Ns Ar port
768Change the next-hop on matching packets to
769.Ar ipaddr ,
770which can be an IP address or a host name.
771For IPv4, the next hop can also be supplied by the last table
772looked up for the packet by using the
773.Cm tablearg
774keyword instead of an explicit address.
775The search terminates if this rule matches.
776.Pp
777If
778.Ar ipaddr
779is a local address, then matching packets will be forwarded to
780.Ar port
781(or the port number in the packet if one is not specified in the rule)
782on the local machine.
783.br
784If
785.Ar ipaddr
786is not a local address, then the port number
787(if specified) is ignored, and the packet will be
788forwarded to the remote address, using the route as found in
789the local routing table for that IP.
790.br
791A
792.Ar fwd
793rule will not match layer-2 packets (those received
794on ether_input, ether_output, or bridged).
795.br
796The
797.Cm fwd
798action does not change the contents of the packet at all.
799In particular, the destination address remains unmodified, so
800packets forwarded to another system will usually be rejected by that system
801unless there is a matching rule on that system to capture them.
802For packets forwarded locally,
803the local address of the socket will be
804set to the original destination address of the packet.
805This makes the
806.Xr netstat 1
807entry look rather weird but is intended for
808use with transparent proxy servers.
809.It Cm nat Ar nat_nr | tablearg
810Pass packet to a
811nat instance
812(for network address translation, address redirect, etc.):
813see the
814.Sx NETWORK ADDRESS TRANSLATION (NAT)
815Section for further information.
816.It Cm pipe Ar pipe_nr
817Pass packet to a
818.Nm dummynet
819.Dq pipe
820(for bandwidth limitation, delay, etc.).
821See the
822.Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION
823Section for further information.
824The search terminates; however, on exit from the pipe and if
825the
826.Xr sysctl 8
827variable
828.Va net.inet.ip.fw.one_pass
829is not set, the packet is passed again to the firewall code
830starting from the next rule.
831.It Cm queue Ar queue_nr
832Pass packet to a
833.Nm dummynet
834.Dq queue
835(for bandwidth limitation using WF2Q+).
836.It Cm reject
837(Deprecated).
838Synonym for
839.Cm unreach host .
840.It Cm reset
841Discard packets that match this rule, and if the
842packet is a TCP packet, try to send a TCP reset (RST) notice.
843The search terminates.
844.It Cm reset6
845Discard packets that match this rule, and if the
846packet is a TCP packet, try to send a TCP reset (RST) notice.
847The search terminates.
848.It Cm skipto Ar number | tablearg
849Skip all subsequent rules numbered less than
850.Ar number .
851The search continues with the first rule numbered
852.Ar number
853or higher.
854It is possible to use the
855.Cm tablearg
856keyword with a skipto for a
857.Em computed
858skipto. Skipto may work either in O(log(N)) or in O(1) depending
859on amount of memory and/or sysctl variables.
860See the
861.Sx SYSCTL VARIABLES
862section for more details.
863.It Cm call Ar number | tablearg
864The current rule number is saved in the internal stack and
865ruleset processing continues with the first rule numbered
866.Ar number
867or higher.
868If later a rule with the
869.Cm return
870action is encountered, the processing returns to the first rule
871with number of this
872.Cm call
873rule plus one or higher
874(the same behaviour as with packets returning from
875.Xr divert 4
876socket after a
877.Cm divert
878action).
879This could be used to make somewhat like an assembly language
880.Dq subroutine
881calls to rules with common checks for different interfaces, etc.
882.Pp
883Rule with any number could be called, not just forward jumps as with
884.Cm skipto .
885So, to prevent endless loops in case of mistakes, both
886.Cm call
887and
888.Cm return
889actions don't do any jumps and simply go to the next rule if memory
890cannot be allocated or stack overflowed/underflowed.
891.Pp
892Internally stack for rule numbers is implemented using
893.Xr mbuf_tags 9
894facility and currently has size of 16 entries.
895As mbuf tags are lost when packet leaves the kernel,
896.Cm divert
897should not be used in subroutines to avoid endless loops
898and other undesired effects.
899.It Cm return
900Takes rule number saved to internal stack by the last
901.Cm call
902action and returns ruleset processing to the first rule
903with number greater than number of corresponding
904.Cm call
905rule.
906See description of the
907.Cm call
908action for more details.
909.Pp
910Note that
911.Cm return
912rules usually end a
913.Dq subroutine
914and thus are unconditional, but
915.Nm
916command-line utility currently requires every action except
917.Cm check-state
918to have body.
919While it is sometimes useful to return only on some packets,
920usually you want to print just
921.Dq return
922for readability.
923A workaround for this is to use new syntax and
924.Fl c
925switch:
926.Bd -literal -offset indent
927# Add a rule without actual body
928ipfw add 2999 return via any
929
930# List rules without "from any to any" part
931ipfw -c list
932.Ed
933.Pp
934This cosmetic annoyance may be fixed in future releases.
935.It Cm tee Ar port
936Send a copy of packets matching this rule to the
937.Xr divert 4
938socket bound to port
939.Ar port .
940The search continues with the next rule.
941.It Cm unreach Ar code
942Discard packets that match this rule, and try to send an ICMP
943unreachable notice with code
944.Ar code ,
945where
946.Ar code
947is a number from 0 to 255, or one of these aliases:
948.Cm net , host , protocol , port ,
949.Cm needfrag , srcfail , net-unknown , host-unknown ,
950.Cm isolated , net-prohib , host-prohib , tosnet ,
951.Cm toshost , filter-prohib , host-precedence
952or
953.Cm precedence-cutoff .
954The search terminates.
955.It Cm unreach6 Ar code
956Discard packets that match this rule, and try to send an ICMPv6
957unreachable notice with code
958.Ar code ,
959where
960.Ar code
961is a number from 0, 1, 3 or 4, or one of these aliases:
962.Cm no-route, admin-prohib, address
963or
964.Cm port .
965The search terminates.
966.It Cm netgraph Ar cookie
967Divert packet into netgraph with given
968.Ar cookie .
969The search terminates.
970If packet is later returned from netgraph it is either
971accepted or continues with the next rule, depending on
972.Va net.inet.ip.fw.one_pass
973sysctl variable.
974.It Cm ngtee Ar cookie
975A copy of packet is diverted into netgraph, original
976packet continues with the next rule.
977See
978.Xr ng_ipfw 4
979for more information on
980.Cm netgraph
981and
982.Cm ngtee
983actions.
984.It Cm setfib Ar fibnum | tablearg
985The packet is tagged so as to use the FIB (routing table)
986.Ar fibnum
987in any subsequent forwarding decisions.
988In the current implementation, this is limited to the values 0 through 15, see
989.Xr setfib 2 .
990Processing continues at the next rule.
991It is possible to use the
992.Cm tablearg
993keyword with setfib.
994If the tablearg value is not within the compiled range of fibs,
995the packet's fib is set to 0.
996.It Cm setdscp Ar DSCP | number | tablearg
997Set specified DiffServ codepoint for an IPv4/IPv6 packet.
998Processing continues at the next rule.
999Supported values are:
1000.Pp
1001.Cm CS0
1002.Pq Dv 000000 ,
1003.Cm CS1
1004.Pq Dv 001000 ,
1005.Cm CS2
1006.Pq Dv 010000 ,
1007.Cm CS3
1008.Pq Dv 011000 ,
1009.Cm CS4
1010.Pq Dv 100000 ,
1011.Cm CS5
1012.Pq Dv 101000 ,
1013.Cm CS6
1014.Pq Dv 110000 ,
1015.Cm CS7
1016.Pq Dv 111000 ,
1017.Cm AF11
1018.Pq Dv 001010 ,
1019.Cm AF12
1020.Pq Dv 001100 ,
1021.Cm AF13
1022.Pq Dv 001110 ,
1023.Cm AF21
1024.Pq Dv 010010 ,
1025.Cm AF22
1026.Pq Dv 010100 ,
1027.Cm AF23
1028.Pq Dv 010110 ,
1029.Cm AF31
1030.Pq Dv 011010 ,
1031.Cm AF32
1032.Pq Dv 011100 ,
1033.Cm AF33
1034.Pq Dv 011110 ,
1035.Cm AF41
1036.Pq Dv 100010 ,
1037.Cm AF42
1038.Pq Dv 100100 ,
1039.Cm AF43
1040.Pq Dv 100110 ,
1041.Cm EF
1042.Pq Dv 101110 ,
1043.Cm BE
1044.Pq Dv 000000 .
1045Additionally, DSCP value can be specified by number (0..64).
1046It is also possible to use the
1047.Cm tablearg
1048keyword with setdscp.
1049If the tablearg value is not within the 0..64 range, lower 6 bits of supplied
1050value are used.
1051.It Cm reass
1052Queue and reassemble IP fragments.
1053If the packet is not fragmented, counters are updated and
1054processing continues with the next rule.
1055If the packet is the last logical fragment, the packet is reassembled and, if
1056.Va net.inet.ip.fw.one_pass
1057is set to 0, processing continues with the next rule.
1058Otherwise, the packet is allowed to pass and the search terminates.
1059If the packet is a fragment in the middle of a logical group of fragments,
1060it is consumed and
1061processing stops immediately.
1062.Pp
1063Fragment handling can be tuned via
1064.Va net.inet.ip.maxfragpackets
1065and
1066.Va net.inet.ip.maxfragsperpacket
1067which limit, respectively, the maximum number of processable
1068fragments (default: 800) and
1069the maximum number of fragments per packet (default: 16).
1070.Pp
1071NOTA BENE: since fragments do not contain port numbers,
1072they should be avoided with the
1073.Nm reass
1074rule.
1075Alternatively, direction-based (like
1076.Nm in
1077/
1078.Nm out
1079) and source-based (like
1080.Nm via
1081) match patterns can be used to select fragments.
1082.Pp
1083Usually a simple rule like:
1084.Bd -literal -offset indent
1085# reassemble incoming fragments
1086ipfw add reass all from any to any in
1087.Ed
1088.Pp
1089is all you need at the beginning of your ruleset.
1090.El
1091.Ss RULE BODY
1092The body of a rule contains zero or more patterns (such as
1093specific source and destination addresses or ports,
1094protocol options, incoming or outgoing interfaces, etc.)
1095that the packet must match in order to be recognised.
1096In general, the patterns are connected by (implicit)
1097.Cm and
1098operators -- i.e., all must match in order for the
1099rule to match.
1100Individual patterns can be prefixed by the
1101.Cm not
1102operator to reverse the result of the match, as in
1103.Pp
1104.Dl "ipfw add 100 allow ip from not 1.2.3.4 to any"
1105.Pp
1106Additionally, sets of alternative match patterns
1107.Pq Em or-blocks
1108can be constructed by putting the patterns in
1109lists enclosed between parentheses ( ) or braces { }, and
1110using the
1111.Cm or
1112operator as follows:
1113.Pp
1114.Dl "ipfw add 100 allow ip from { x or not y or z } to any"
1115.Pp
1116Only one level of parentheses is allowed.
1117Beware that most shells have special meanings for parentheses
1118or braces, so it is advisable to put a backslash \\ in front of them
1119to prevent such interpretations.
1120.Pp
1121The body of a rule must in general include a source and destination
1122address specifier.
1123The keyword
1124.Ar any
1125can be used in various places to specify that the content of
1126a required field is irrelevant.
1127.Pp
1128The rule body has the following format:
1129.Bd -ragged -offset indent
1130.Op Ar proto Cm from Ar src Cm to Ar dst
1131.Op Ar options
1132.Ed
1133.Pp
1134The first part (proto from src to dst) is for backward
1135compatibility with earlier versions of
1136.Fx .
1137In modern
1138.Fx
1139any match pattern (including MAC headers, IP protocols,
1140addresses and ports) can be specified in the
1141.Ar options
1142section.
1143.Pp
1144Rule fields have the following meaning:
1145.Bl -tag -width indent
1146.It Ar proto : protocol | Cm { Ar protocol Cm or ... }
1147.It Ar protocol : Oo Cm not Oc Ar protocol-name | protocol-number
1148An IP protocol specified by number or name
1149(for a complete list see
1150.Pa /etc/protocols ) ,
1151or one of the following keywords:
1152.Bl -tag -width indent
1153.It Cm ip4 | ipv4
1154Matches IPv4 packets.
1155.It Cm ip6 | ipv6
1156Matches IPv6 packets.
1157.It Cm ip | all
1158Matches any packet.
1159.El
1160.Pp
1161The
1162.Cm ipv6
1163in
1164.Cm proto
1165option will be treated as inner protocol.
1166And, the
1167.Cm ipv4
1168is not available in
1169.Cm proto
1170option.
1171.Pp
1172The
1173.Cm { Ar protocol Cm or ... }
1174format (an
1175.Em or-block )
1176is provided for convenience only but its use is deprecated.
1177.It Ar src No and Ar dst : Bro Cm addr | Cm { Ar addr Cm or ... } Brc Op Oo Cm not Oc Ar ports
1178An address (or a list, see below)
1179optionally followed by
1180.Ar ports
1181specifiers.
1182.Pp
1183The second format
1184.Em ( or-block
1185with multiple addresses) is provided for convenience only and
1186its use is discouraged.
1187.It Ar addr : Oo Cm not Oc Bro
1188.Cm any | me | me6 |
1189.Cm table Ns Pq Ar name Ns Op , Ns Ar value
1190.Ar | addr-list | addr-set
1191.Brc
1192.Bl -tag -width indent
1193.It Cm any
1194matches any IP address.
1195.It Cm me
1196matches any IP address configured on an interface in the system.
1197.It Cm me6
1198matches any IPv6 address configured on an interface in the system.
1199The address list is evaluated at the time the packet is
1200analysed.
1201.It Cm table Ns Pq Ar name Ns Op , Ns Ar value
1202Matches any IPv4 or IPv6 address for which an entry exists in the lookup table
1203.Ar number .
1204If an optional 32-bit unsigned
1205.Ar value
1206is also specified, an entry will match only if it has this value.
1207See the
1208.Sx LOOKUP TABLES
1209section below for more information on lookup tables.
1210.El
1211.It Ar addr-list : ip-addr Ns Op Ns , Ns Ar addr-list
1212.It Ar ip-addr :
1213A host or subnet address specified in one of the following ways:
1214.Bl -tag -width indent
1215.It Ar numeric-ip | hostname
1216Matches a single IPv4 address, specified as dotted-quad or a hostname.
1217Hostnames are resolved at the time the rule is added to the firewall list.
1218.It Ar addr Ns / Ns Ar masklen
1219Matches all addresses with base
1220.Ar addr
1221(specified as an IP address, a network number, or a hostname)
1222and mask width of
1223.Cm masklen
1224bits.
1225As an example, 1.2.3.4/25 or 1.2.3.0/25 will match
1226all IP numbers from 1.2.3.0 to 1.2.3.127 .
1227.It Ar addr Ns : Ns Ar mask
1228Matches all addresses with base
1229.Ar addr
1230(specified as an IP address, a network number, or a hostname)
1231and the mask of
1232.Ar mask ,
1233specified as a dotted quad.
1234As an example, 1.2.3.4:255.0.255.0 or 1.0.3.0:255.0.255.0 will match
12351.*.3.*.
1236This form is advised only for non-contiguous
1237masks.
1238It is better to resort to the
1239.Ar addr Ns / Ns Ar masklen
1240format for contiguous masks, which is more compact and less
1241error-prone.
1242.El
1243.It Ar addr-set : addr Ns Oo Ns / Ns Ar masklen Oc Ns Cm { Ns Ar list Ns Cm }
1244.It Ar list : Bro Ar num | num-num Brc Ns Op Ns , Ns Ar list
1245Matches all addresses with base address
1246.Ar addr
1247(specified as an IP address, a network number, or a hostname)
1248and whose last byte is in the list between braces { } .
1249Note that there must be no spaces between braces and
1250numbers (spaces after commas are allowed).
1251Elements of the list can be specified as single entries
1252or ranges.
1253The
1254.Ar masklen
1255field is used to limit the size of the set of addresses,
1256and can have any value between 24 and 32.
1257If not specified,
1258it will be assumed as 24.
1259.br
1260This format is particularly useful to handle sparse address sets
1261within a single rule.
1262Because the matching occurs using a
1263bitmask, it takes constant time and dramatically reduces
1264the complexity of rulesets.
1265.br
1266As an example, an address specified as 1.2.3.4/24{128,35-55,89}
1267or 1.2.3.0/24{128,35-55,89}
1268will match the following IP addresses:
1269.br
12701.2.3.128, 1.2.3.35 to 1.2.3.55, 1.2.3.89 .
1271.It Ar addr6-list : ip6-addr Ns Op Ns , Ns Ar addr6-list
1272.It Ar ip6-addr :
1273A host or subnet specified one of the following ways:
1274.Bl -tag -width indent
1275.It Ar numeric-ip | hostname
1276Matches a single IPv6 address as allowed by
1277.Xr inet_pton 3
1278or a hostname.
1279Hostnames are resolved at the time the rule is added to the firewall
1280list.
1281.It Ar addr Ns / Ns Ar masklen
1282Matches all IPv6 addresses with base
1283.Ar addr
1284(specified as allowed by
1285.Xr inet_pton
1286or a hostname)
1287and mask width of
1288.Cm masklen
1289bits.
1290.El
1291.Pp
1292No support for sets of IPv6 addresses is provided because IPv6 addresses
1293are typically random past the initial prefix.
1294.It Ar ports : Bro Ar port | port Ns \&- Ns Ar port Ns Brc Ns Op , Ns Ar ports
1295For protocols which support port numbers (such as TCP and UDP), optional
1296.Cm ports
1297may be specified as one or more ports or port ranges, separated
1298by commas but no spaces, and an optional
1299.Cm not
1300operator.
1301The
1302.Ql \&-
1303notation specifies a range of ports (including boundaries).
1304.Pp
1305Service names (from
1306.Pa /etc/services )
1307may be used instead of numeric port values.
1308The length of the port list is limited to 30 ports or ranges,
1309though one can specify larger ranges by using an
1310.Em or-block
1311in the
1312.Cm options
1313section of the rule.
1314.Pp
1315A backslash
1316.Pq Ql \e
1317can be used to escape the dash
1318.Pq Ql -
1319character in a service name (from a shell, the backslash must be
1320typed twice to avoid the shell itself interpreting it as an escape
1321character).
1322.Pp
1323.Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any"
1324.Pp
1325Fragmented packets which have a non-zero offset (i.e., not the first
1326fragment) will never match a rule which has one or more port
1327specifications.
1328See the
1329.Cm frag
1330option for details on matching fragmented packets.
1331.El
1332.Ss RULE OPTIONS (MATCH PATTERNS)
1333Additional match patterns can be used within
1334rules.
1335Zero or more of these so-called
1336.Em options
1337can be present in a rule, optionally prefixed by the
1338.Cm not
1339operand, and possibly grouped into
1340.Em or-blocks .
1341.Pp
1342The following match patterns can be used (listed in alphabetical order):
1343.Bl -tag -width indent
1344.It Cm // this is a comment.
1345Inserts the specified text as a comment in the rule.
1346Everything following // is considered as a comment and stored in the rule.
1347You can have comment-only rules, which are listed as having a
1348.Cm count
1349action followed by the comment.
1350.It Cm bridged
1351Alias for
1352.Cm layer2 .
1353.It Cm diverted
1354Matches only packets generated by a divert socket.
1355.It Cm diverted-loopback
1356Matches only packets coming from a divert socket back into the IP stack
1357input for delivery.
1358.It Cm diverted-output
1359Matches only packets going from a divert socket back outward to the IP
1360stack output for delivery.
1361.It Cm dst-ip Ar ip-address
1362Matches IPv4 packets whose destination IP is one of the address(es)
1363specified as argument.
1364.It Bro Cm dst-ip6 | dst-ipv6 Brc Ar ip6-address
1365Matches IPv6 packets whose destination IP is one of the address(es)
1366specified as argument.
1367.It Cm dst-port Ar ports
1368Matches IP packets whose destination port is one of the port(s)
1369specified as argument.
1370.It Cm established
1371Matches TCP packets that have the RST or ACK bits set.
1372.It Cm ext6hdr Ar header
1373Matches IPv6 packets containing the extended header given by
1374.Ar header .
1375Supported headers are:
1376.Pp
1377Fragment,
1378.Pq Cm frag ,
1379Hop-to-hop options
1380.Pq Cm hopopt ,
1381any type of Routing Header
1382.Pq Cm route ,
1383Source routing Routing Header Type 0
1384.Pq Cm rthdr0 ,
1385Mobile IPv6 Routing Header Type 2
1386.Pq Cm rthdr2 ,
1387Destination options
1388.Pq Cm dstopt ,
1389IPSec authentication headers
1390.Pq Cm ah ,
1391and IPsec encapsulated security payload headers
1392.Pq Cm esp .
1393.It Cm fib Ar fibnum
1394Matches a packet that has been tagged to use
1395the given FIB (routing table) number.
1396.It Cm flow Ar table Ns Pq Ar name Ns Op , Ns Ar value
1397Search for the flow entry in lookup table
1398.Ar name .
1399If not found, the match fails.
1400Otherwise, the match succeeds and
1401.Cm tablearg
1402is set to the value extracted from the table.
1403.Pp
1404This option can be useful to quickly dispatch traffic based on
1405certain packet fields.
1406See the
1407.Sx LOOKUP TABLES
1408section below for more information on lookup tables.
1409.It Cm flow-id Ar labels
1410Matches IPv6 packets containing any of the flow labels given in
1411.Ar labels .
1412.Ar labels
1413is a comma separated list of numeric flow labels.
1414.It Cm frag
1415Matches packets that are fragments and not the first
1416fragment of an IP datagram.
1417Note that these packets will not have
1418the next protocol header (e.g.\& TCP, UDP) so options that look into
1419these headers cannot match.
1420.It Cm gid Ar group
1421Matches all TCP or UDP packets sent by or received for a
1422.Ar group .
1423A
1424.Ar group
1425may be specified by name or number.
1426.It Cm jail Ar prisonID
1427Matches all TCP or UDP packets sent by or received for the
1428jail whos prison ID is
1429.Ar prisonID .
1430.It Cm icmptypes Ar types
1431Matches ICMP packets whose ICMP type is in the list
1432.Ar types .
1433The list may be specified as any combination of
1434individual types (numeric) separated by commas.
1435.Em Ranges are not allowed .
1436The supported ICMP types are:
1437.Pp
1438echo reply
1439.Pq Cm 0 ,
1440destination unreachable
1441.Pq Cm 3 ,
1442source quench
1443.Pq Cm 4 ,
1444redirect
1445.Pq Cm 5 ,
1446echo request
1447.Pq Cm 8 ,
1448router advertisement
1449.Pq Cm 9 ,
1450router solicitation
1451.Pq Cm 10 ,
1452time-to-live exceeded
1453.Pq Cm 11 ,
1454IP header bad
1455.Pq Cm 12 ,
1456timestamp request
1457.Pq Cm 13 ,
1458timestamp reply
1459.Pq Cm 14 ,
1460information request
1461.Pq Cm 15 ,
1462information reply
1463.Pq Cm 16 ,
1464address mask request
1465.Pq Cm 17
1466and address mask reply
1467.Pq Cm 18 .
1468.It Cm icmp6types Ar types
1469Matches ICMP6 packets whose ICMP6 type is in the list of
1470.Ar types .
1471The list may be specified as any combination of
1472individual types (numeric) separated by commas.
1473.Em Ranges are not allowed .
1474.It Cm in | out
1475Matches incoming or outgoing packets, respectively.
1476.Cm in
1477and
1478.Cm out
1479are mutually exclusive (in fact,
1480.Cm out
1481is implemented as
1482.Cm not in Ns No ).
1483.It Cm ipid Ar id-list
1484Matches IPv4 packets whose
1485.Cm ip_id
1486field has value included in
1487.Ar id-list ,
1488which is either a single value or a list of values or ranges
1489specified in the same way as
1490.Ar ports .
1491.It Cm iplen Ar len-list
1492Matches IP packets whose total length, including header and data, is
1493in the set
1494.Ar len-list ,
1495which is either a single value or a list of values or ranges
1496specified in the same way as
1497.Ar ports .
1498.It Cm ipoptions Ar spec
1499Matches packets whose IPv4 header contains the comma separated list of
1500options specified in
1501.Ar spec .
1502The supported IP options are:
1503.Pp
1504.Cm ssrr
1505(strict source route),
1506.Cm lsrr
1507(loose source route),
1508.Cm rr
1509(record packet route) and
1510.Cm ts
1511(timestamp).
1512The absence of a particular option may be denoted
1513with a
1514.Ql \&! .
1515.It Cm ipprecedence Ar precedence
1516Matches IPv4 packets whose precedence field is equal to
1517.Ar precedence .
1518.It Cm ipsec
1519Matches packets that have IPSEC history associated with them
1520(i.e., the packet comes encapsulated in IPSEC, the kernel
1521has IPSEC support and IPSEC_FILTERTUNNEL option, and can correctly
1522decapsulate it).
1523.Pp
1524Note that specifying
1525.Cm ipsec
1526is different from specifying
1527.Cm proto Ar ipsec
1528as the latter will only look at the specific IP protocol field,
1529irrespective of IPSEC kernel support and the validity of the IPSEC data.
1530.Pp
1531Further note that this flag is silently ignored in kernels without
1532IPSEC support.
1533It does not affect rule processing when given and the
1534rules are handled as if with no
1535.Cm ipsec
1536flag.
1537.It Cm iptos Ar spec
1538Matches IPv4 packets whose
1539.Cm tos
1540field contains the comma separated list of
1541service types specified in
1542.Ar spec .
1543The supported IP types of service are:
1544.Pp
1545.Cm lowdelay
1546.Pq Dv IPTOS_LOWDELAY ,
1547.Cm throughput
1548.Pq Dv IPTOS_THROUGHPUT ,
1549.Cm reliability
1550.Pq Dv IPTOS_RELIABILITY ,
1551.Cm mincost
1552.Pq Dv IPTOS_MINCOST ,
1553.Cm congestion
1554.Pq Dv IPTOS_ECN_CE .
1555The absence of a particular type may be denoted
1556with a
1557.Ql \&! .
1558.It Cm dscp spec Ns Op , Ns Ar spec
1559Matches IPv4/IPv6 packets whose
1560.Cm DS
1561field value is contained in
1562.Ar spec
1563mask.
1564Multiple values can be specified via
1565the comma separated list.
1566Value can be one of keywords used in
1567.Cm setdscp
1568action or exact number.
1569.It Cm ipttl Ar ttl-list
1570Matches IPv4 packets whose time to live is included in
1571.Ar ttl-list ,
1572which is either a single value or a list of values or ranges
1573specified in the same way as
1574.Ar ports .
1575.It Cm ipversion Ar ver
1576Matches IP packets whose IP version field is
1577.Ar ver .
1578.It Cm keep-state
1579Upon a match, the firewall will create a dynamic rule, whose
1580default behaviour is to match bidirectional traffic between
1581source and destination IP/port using the same protocol.
1582The rule has a limited lifetime (controlled by a set of
1583.Xr sysctl 8
1584variables), and the lifetime is refreshed every time a matching
1585packet is found.
1586.It Cm layer2
1587Matches only layer2 packets, i.e., those passed to
1588.Nm
1589from ether_demux() and ether_output_frame().
1590.It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N
1591The firewall will only allow
1592.Ar N
1593connections with the same
1594set of parameters as specified in the rule.
1595One or more
1596of source and destination addresses and ports can be
1597specified.
1598Currently,
1599only IPv4 flows are supported.
1600.It Cm lookup Bro Cm dst-ip | dst-port | src-ip | src-port | uid | jail Brc Ar name
1601Search an entry in lookup table
1602.Ar name
1603that matches the field specified as argument.
1604If not found, the match fails.
1605Otherwise, the match succeeds and
1606.Cm tablearg
1607is set to the value extracted from the table.
1608.Pp
1609This option can be useful to quickly dispatch traffic based on
1610certain packet fields.
1611See the
1612.Sx LOOKUP TABLES
1613section below for more information on lookup tables.
1614.It Cm { MAC | mac } Ar dst-mac src-mac
1615Match packets with a given
1616.Ar dst-mac
1617and
1618.Ar src-mac
1619addresses, specified as the
1620.Cm any
1621keyword (matching any MAC address), or six groups of hex digits
1622separated by colons,
1623and optionally followed by a mask indicating the significant bits.
1624The mask may be specified using either of the following methods:
1625.Bl -enum -width indent
1626.It
1627A slash
1628.Pq /
1629followed by the number of significant bits.
1630For example, an address with 33 significant bits could be specified as:
1631.Pp
1632.Dl "MAC 10:20:30:40:50:60/33 any"
1633.It
1634An ampersand
1635.Pq &
1636followed by a bitmask specified as six groups of hex digits separated
1637by colons.
1638For example, an address in which the last 16 bits are significant could
1639be specified as:
1640.Pp
1641.Dl "MAC 10:20:30:40:50:60&00:00:00:00:ff:ff any"
1642.Pp
1643Note that the ampersand character has a special meaning in many shells
1644and should generally be escaped.
1645.El
1646Note that the order of MAC addresses (destination first,
1647source second) is
1648the same as on the wire, but the opposite of the one used for
1649IP addresses.
1650.It Cm mac-type Ar mac-type
1651Matches packets whose Ethernet Type field
1652corresponds to one of those specified as argument.
1653.Ar mac-type
1654is specified in the same way as
1655.Cm port numbers
1656(i.e., one or more comma-separated single values or ranges).
1657You can use symbolic names for known values such as
1658.Em vlan , ipv4, ipv6 .
1659Values can be entered as decimal or hexadecimal (if prefixed by 0x),
1660and they are always printed as hexadecimal (unless the
1661.Cm -N
1662option is used, in which case symbolic resolution will be attempted).
1663.It Cm proto Ar protocol
1664Matches packets with the corresponding IP protocol.
1665.It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar table Ns Po Ar name Ns Oo , Ns Ar value Oc Pc | Ar ipno | Ar any
1666Matches packets received, transmitted or going through,
1667respectively, the interface specified by exact name
1668.Po Ar ifX Pc ,
1669by device name
1670.Po Ar if* Pc ,
1671by IP address, or through some interface.
1672Table
1673.Ar name
1674may be used to match interface by its kernel ifindex.
1675See the
1676.Sx LOOKUP TABLES
1677section below for more information on lookup tables.
1678.Pp
1679The
1680.Cm via
1681keyword causes the interface to always be checked.
1682If
1683.Cm recv
1684or
1685.Cm xmit
1686is used instead of
1687.Cm via ,
1688then only the receive or transmit interface (respectively)
1689is checked.
1690By specifying both, it is possible to match packets based on
1691both receive and transmit interface, e.g.:
1692.Pp
1693.Dl "ipfw add deny ip from any to any out recv ed0 xmit ed1"
1694.Pp
1695The
1696.Cm recv
1697interface can be tested on either incoming or outgoing packets,
1698while the
1699.Cm xmit
1700interface can only be tested on outgoing packets.
1701So
1702.Cm out
1703is required (and
1704.Cm in
1705is invalid) whenever
1706.Cm xmit
1707is used.
1708.Pp
1709A packet might not have a receive or transmit interface: packets
1710originating from the local host have no receive interface,
1711while packets destined for the local host have no transmit
1712interface.
1713.It Cm setup
1714Matches TCP packets that have the SYN bit set but no ACK bit.
1715This is the short form of
1716.Dq Li tcpflags\ syn,!ack .
1717.It Cm sockarg
1718Matches packets that are associated to a local socket and
1719for which the SO_USER_COOKIE socket option has been set
1720to a non-zero value.
1721As a side effect, the value of the
1722option is made available as
1723.Cm tablearg
1724value, which in turn can be used as
1725.Cm skipto
1726or
1727.Cm pipe
1728number.
1729.It Cm src-ip Ar ip-address
1730Matches IPv4 packets whose source IP is one of the address(es)
1731specified as an argument.
1732.It Cm src-ip6 Ar ip6-address
1733Matches IPv6 packets whose source IP is one of the address(es)
1734specified as an argument.
1735.It Cm src-port Ar ports
1736Matches IP packets whose source port is one of the port(s)
1737specified as argument.
1738.It Cm tagged Ar tag-list
1739Matches packets whose tags are included in
1740.Ar tag-list ,
1741which is either a single value or a list of values or ranges
1742specified in the same way as
1743.Ar ports .
1744Tags can be applied to the packet using
1745.Cm tag
1746rule action parameter (see it's description for details on tags).
1747.It Cm tcpack Ar ack
1748TCP packets only.
1749Match if the TCP header acknowledgment number field is set to
1750.Ar ack .
1751.It Cm tcpdatalen Ar tcpdatalen-list
1752Matches TCP packets whose length of TCP data is
1753.Ar tcpdatalen-list ,
1754which is either a single value or a list of values or ranges
1755specified in the same way as
1756.Ar ports .
1757.It Cm tcpflags Ar spec
1758TCP packets only.
1759Match if the TCP header contains the comma separated list of
1760flags specified in
1761.Ar spec .
1762The supported TCP flags are:
1763.Pp
1764.Cm fin ,
1765.Cm syn ,
1766.Cm rst ,
1767.Cm psh ,
1768.Cm ack
1769and
1770.Cm urg .
1771The absence of a particular flag may be denoted
1772with a
1773.Ql \&! .
1774A rule which contains a
1775.Cm tcpflags
1776specification can never match a fragmented packet which has
1777a non-zero offset.
1778See the
1779.Cm frag
1780option for details on matching fragmented packets.
1781.It Cm tcpseq Ar seq
1782TCP packets only.
1783Match if the TCP header sequence number field is set to
1784.Ar seq .
1785.It Cm tcpwin Ar tcpwin-list
1786Matches TCP packets whose  header window field is set to
1787.Ar tcpwin-list ,
1788which is either a single value or a list of values or ranges
1789specified in the same way as
1790.Ar ports .
1791.It Cm tcpoptions Ar spec
1792TCP packets only.
1793Match if the TCP header contains the comma separated list of
1794options specified in
1795.Ar spec .
1796The supported TCP options are:
1797.Pp
1798.Cm mss
1799(maximum segment size),
1800.Cm window
1801(tcp window advertisement),
1802.Cm sack
1803(selective ack),
1804.Cm ts
1805(rfc1323 timestamp) and
1806.Cm cc
1807(rfc1644 t/tcp connection count).
1808The absence of a particular option may be denoted
1809with a
1810.Ql \&! .
1811.It Cm uid Ar user
1812Match all TCP or UDP packets sent by or received for a
1813.Ar user .
1814A
1815.Ar user
1816may be matched by name or identification number.
1817.It Cm verrevpath
1818For incoming packets,
1819a routing table lookup is done on the packet's source address.
1820If the interface on which the packet entered the system matches the
1821outgoing interface for the route,
1822the packet matches.
1823If the interfaces do not match up,
1824the packet does not match.
1825All outgoing packets or packets with no incoming interface match.
1826.Pp
1827The name and functionality of the option is intentionally similar to
1828the Cisco IOS command:
1829.Pp
1830.Dl ip verify unicast reverse-path
1831.Pp
1832This option can be used to make anti-spoofing rules to reject all
1833packets with source addresses not from this interface.
1834See also the option
1835.Cm antispoof .
1836.It Cm versrcreach
1837For incoming packets,
1838a routing table lookup is done on the packet's source address.
1839If a route to the source address exists, but not the default route
1840or a blackhole/reject route, the packet matches.
1841Otherwise, the packet does not match.
1842All outgoing packets match.
1843.Pp
1844The name and functionality of the option is intentionally similar to
1845the Cisco IOS command:
1846.Pp
1847.Dl ip verify unicast source reachable-via any
1848.Pp
1849This option can be used to make anti-spoofing rules to reject all
1850packets whose source address is unreachable.
1851.It Cm antispoof
1852For incoming packets, the packet's source address is checked if it
1853belongs to a directly connected network.
1854If the network is directly connected, then the interface the packet
1855came on in is compared to the interface the network is connected to.
1856When incoming interface and directly connected interface are not the
1857same, the packet does not match.
1858Otherwise, the packet does match.
1859All outgoing packets match.
1860.Pp
1861This option can be used to make anti-spoofing rules to reject all
1862packets that pretend to be from a directly connected network but do
1863not come in through that interface.
1864This option is similar to but more restricted than
1865.Cm verrevpath
1866because it engages only on packets with source addresses of directly
1867connected networks instead of all source addresses.
1868.El
1869.Sh LOOKUP TABLES
1870Lookup tables are useful to handle large sparse sets of
1871addresses or other search keys (e.g., ports, jail IDs, interface names).
1872In the rest of this section we will use the term ``key''.
1873Table name needs to match the following spec:
1874.Ar table-name .
1875Tables with the same name can be created in different
1876.Ar sets .
1877However, rule links to the tables in
1878.Ar set 0
1879by default.
1880This behavior can be controlled by
1881.Va net.inet.ip.fw.tables_sets
1882variable.
1883See the
1884.Sx SETS OF RULES
1885section for more information.
1886There may be up to 65535 different lookup tables.
1887.Pp
1888The following table types are supported:
1889.Bl -tag -width indent
1890.It Ar table-type : Ar addr | iface | number | flow
1891.It Ar table-key : Ar addr Ns Oo / Ns Ar masklen Oc | iface-name | number | flow-spec
1892.It Ar flow-spec : Ar flow-field Ns Op , Ns Ar flow-spec
1893.It Ar flow-field : src-ip | proto | src-port | dst-ip | dst-port
1894.It Cm addr
1895matches IPv4 or IPv6 address.
1896Each entry is represented by an
1897.Ar addr Ns Op / Ns Ar masklen
1898and will match all addresses with base
1899.Ar addr
1900(specified as an IPv4/IPv6 address, or a hostname) and mask width of
1901.Ar masklen
1902bits.
1903If
1904.Ar masklen
1905is not specified, it defaults to 32 for IPv4 and 128 for IPv6.
1906When looking up an IP address in a table, the most specific
1907entry will match.
1908.It Cm iface
1909matches interface names.
1910Each entry is represented by string treated as interface name.
1911Wildcards are not supported.
1912.It Cm number
1913maches protocol ports, uids/gids or jail IDs.
1914Each entry is represented by 32-bit unsigned integer.
1915Ranges are not supported.
1916.It Cm flow
1917Matches packet fields specified by
1918.Ar flow
1919type suboptions with table entries.
1920.El
1921.Pp
1922Tables require explicit creation via
1923.Cm create
1924before use.
1925.Pp
1926The following creation options are supported:
1927.Bl -tag -width indent
1928.It Ar create-options : Ar create-option | create-options
1929.It Ar create-option : Cm type Ar table-type | Cm valtype Ar value-mask | Cm algo Ar algo-desc |
1930.Cm limit Ar number | Cm locked
1931.It Cm type
1932Table key type.
1933.It Cm valtype
1934Table value mask.
1935.It Cm algo
1936Table algorithm to use (see below).
1937.It Cm limit
1938Maximum number of items that may be inserted into table.
1939.It Cm locked
1940Restrict any table modifications.
1941.El
1942.Pp
1943Some of these options may be modified later via
1944.Cm modify
1945keyword.
1946The following options can be changed:
1947.Bl -tag -width indent
1948.It Ar modify-options : Ar modify-option | modify-options
1949.It Ar modify-option : Cm limit Ar number
1950.It Cm limit
1951Alter maximum number of items that may be inserted into table.
1952.El
1953.Pp
1954Additionally, table can be locked or unlocked using
1955.Cm lock
1956or
1957.Cm unlock
1958commands.
1959.Pp
1960Tables of the same
1961.Ar type
1962can be swapped with each other using
1963.Cm swap Ar name
1964command.
1965Swap may fail if tables limits are set and data exchange
1966would result in limits hit.
1967Operation is performed atomically.
1968.Pp
1969One or more entries can be added to a table at once using
1970.Cm add
1971command.
1972Addition of all items are performed atomically.
1973By default, error in addition of one entry does not influence
1974addition of other entries. However, non-zero error code is returned
1975in that case.
1976Special
1977.Cm atomic
1978keyword may be specified before
1979.Cm add
1980to indicate all-or-none add request.
1981.Pp
1982One or more entries can be removed from a table at once using
1983.Cm delete
1984command.
1985By default, error in removal of one entry does not influence
1986removing of other entries. However, non-zero error code is returned
1987in that case.
1988.Pp
1989It may be possible to check what entry will be found on particular
1990.Ar table-key
1991using
1992.Cm lookup
1993.Ar table-key
1994command.
1995This functionality is optional and may be unsupported in some algorithms.
1996.Pp
1997The following operations can be performed on
1998.Ar one
1999or
2000.Cm all
2001tables:
2002.Bl -tag -width indent
2003.It Cm list
2004List all entries.
2005.It Cm flush
2006Removes all entries.
2007.It Cm info
2008Shows generic table information.
2009.It Cm detail
2010Shows generic table information and algo-specific data.
2011.El
2012.Pp
2013The following lookup algorithms are supported:
2014.Bl -tag -width indent
2015.It Ar algo-desc : algo-name | "algo-name algo-data"
2016.It Ar algo-name: Ar addr:radix | addr:hash | iface:array | number:array | flow:hash
2017.It Cm addr:radix
2018Separate Radix trees for IPv4 and IPv6, the same way as the routing table (see
2019.Xr route 4 ) .
2020Default choice for
2021.Ar addr
2022type.
2023.It Cm addr:hash
2024Separate auto-growing hashes for IPv4 and IPv6.
2025Accepts entries with the same mask length specified initially via
2026.Cm "addr:hash masks=/v4,/v6"
2027algorithm creation options.
2028Assume /32 and /128 masks by default.
2029Search removes host bits (according to mask) from supplied address and checks
2030resulting key in appropriate hash.
2031Mostly optimized for /64 and byte-ranged IPv6 masks.
2032.It Cm iface:array
2033Array storing sorted indexes for entries which are presented in the system.
2034Optimized for very fast lookup.
2035.It Cm number:array
2036Array storing sorted u32 numbers.
2037.It Cm flow:hash
2038Auto-growing hash storing flow entries.
2039Search calculates hash on required packet fields and searches for matching
2040entries in selected bucket.
2041.El
2042.Pp
2043The
2044.Cm tablearg
2045feature provides the ability to use a value, looked up in the table, as
2046the argument for a rule action, action parameter or rule option.
2047This can significantly reduce number of rules in some configurations.
2048If two tables are used in a rule, the result of the second (destination)
2049is used.
2050.Pp
2051Each record may hold one or more values according to
2052.Ar value-mask .
2053This mask is set on table creation via
2054.Cm valtype
2055option.
2056The following value types are supported:
2057.Bl -tag -width indent
2058.It Ar value-mask : Ar value-type Ns Op , Ns Ar value-mask
2059.It Ar value-type : Ar skipto | pipe | fib | nat | dscp | tag | divert |
2060.Ar netgraph | limit | ipv4
2061.It Cm skipto
2062rule number to jump to.
2063.It Cm pipe
2064Pipe number to use.
2065.It Cm fib
2066fib number to match/set.
2067.It Cm nat
2068nat number to jump to.
2069.It Cm dscp
2070dscp value to match/set.
2071.It Cm tag
2072tag number to match/set.
2073.It Cm divert
2074port number to divert traffic to.
2075.It Cm netgraph
2076hook number to move packet to.
2077.It Cm limit
2078maximum number of connections.
2079.It Cm ipv4
2080IPv4 nexthop to fwd packets to.
2081.It Cm ipv6
2082IPv6 nexthop to fwd packets to.
2083.El
2084.Pp
2085The
2086.Cm tablearg
2087argument can be used with the following actions:
2088.Cm nat, pipe , queue, divert, tee, netgraph, ngtee, fwd, skipto, setfib,
2089action parameters:
2090.Cm tag, untag,
2091rule options:
2092.Cm limit, tagged.
2093.Pp
2094When used with the
2095.Cm skipto
2096action, the user should be aware that the code will walk the ruleset
2097up to a rule equal to, or past, the given number.
2098.Pp
2099See the
2100.Sx EXAMPLES
2101Section for example usage of tables and the tablearg keyword.
2102.Sh SETS OF RULES
2103Each rule or table belongs to one of 32 different
2104.Em sets
2105, numbered 0 to 31.
2106Set 31 is reserved for the default rule.
2107.Pp
2108By default, rules or tables are put in set 0, unless you use the
2109.Cm set N
2110attribute when adding a new rule or table.
2111Sets can be individually and atomically enabled or disabled,
2112so this mechanism permits an easy way to store multiple configurations
2113of the firewall and quickly (and atomically) switch between them.
2114.Pp
2115By default, tables from set 0 are referenced when adding rule with
2116table opcodes regardless of rule set.
2117This behavior can be changed by setting
2118.Va net.inet.ip.fw.tables_set
2119variable to 1.
2120Rule's set will then be used for table references.
2121.Pp
2122The command to enable/disable sets is
2123.Bd -ragged -offset indent
2124.Nm
2125.Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ...
2126.Ed
2127.Pp
2128where multiple
2129.Cm enable
2130or
2131.Cm disable
2132sections can be specified.
2133Command execution is atomic on all the sets specified in the command.
2134By default, all sets are enabled.
2135.Pp
2136When you disable a set, its rules behave as if they do not exist
2137in the firewall configuration, with only one exception:
2138.Bd -ragged -offset indent
2139dynamic rules created from a rule before it had been disabled
2140will still be active until they expire.
2141In order to delete
2142dynamic rules you have to explicitly delete the parent rule
2143which generated them.
2144.Ed
2145.Pp
2146The set number of rules can be changed with the command
2147.Bd -ragged -offset indent
2148.Nm
2149.Cm set move
2150.Brq Cm rule Ar rule-number | old-set
2151.Cm to Ar new-set
2152.Ed
2153.Pp
2154Also, you can atomically swap two rulesets with the command
2155.Bd -ragged -offset indent
2156.Nm
2157.Cm set swap Ar first-set second-set
2158.Ed
2159.Pp
2160See the
2161.Sx EXAMPLES
2162Section on some possible uses of sets of rules.
2163.Sh STATEFUL FIREWALL
2164Stateful operation is a way for the firewall to dynamically
2165create rules for specific flows when packets that
2166match a given pattern are detected.
2167Support for stateful
2168operation comes through the
2169.Cm check-state , keep-state
2170and
2171.Cm limit
2172options of
2173.Nm rules .
2174.Pp
2175Dynamic rules are created when a packet matches a
2176.Cm keep-state
2177or
2178.Cm limit
2179rule, causing the creation of a
2180.Em dynamic
2181rule which will match all and only packets with
2182a given
2183.Em protocol
2184between a
2185.Em src-ip/src-port dst-ip/dst-port
2186pair of addresses
2187.Em ( src
2188and
2189.Em dst
2190are used here only to denote the initial match addresses, but they
2191are completely equivalent afterwards).
2192Dynamic rules will be checked at the first
2193.Cm check-state, keep-state
2194or
2195.Cm limit
2196occurrence, and the action performed upon a match will be the same
2197as in the parent rule.
2198.Pp
2199Note that no additional attributes other than protocol and IP addresses
2200and ports are checked on dynamic rules.
2201.Pp
2202The typical use of dynamic rules is to keep a closed firewall configuration,
2203but let the first TCP SYN packet from the inside network install a
2204dynamic rule for the flow so that packets belonging to that session
2205will be allowed through the firewall:
2206.Pp
2207.Dl "ipfw add check-state"
2208.Dl "ipfw add allow tcp from my-subnet to any setup keep-state"
2209.Dl "ipfw add deny tcp from any to any"
2210.Pp
2211A similar approach can be used for UDP, where an UDP packet coming
2212from the inside will install a dynamic rule to let the response through
2213the firewall:
2214.Pp
2215.Dl "ipfw add check-state"
2216.Dl "ipfw add allow udp from my-subnet to any keep-state"
2217.Dl "ipfw add deny udp from any to any"
2218.Pp
2219Dynamic rules expire after some time, which depends on the status
2220of the flow and the setting of some
2221.Cm sysctl
2222variables.
2223See Section
2224.Sx SYSCTL VARIABLES
2225for more details.
2226For TCP sessions, dynamic rules can be instructed to periodically
2227send keepalive packets to refresh the state of the rule when it is
2228about to expire.
2229.Pp
2230See Section
2231.Sx EXAMPLES
2232for more examples on how to use dynamic rules.
2233.Sh TRAFFIC SHAPER (DUMMYNET) CONFIGURATION
2234.Nm
2235is also the user interface for the
2236.Nm dummynet
2237traffic shaper, packet scheduler and network emulator, a subsystem that
2238can artificially queue, delay or drop packets
2239emulating the behaviour of certain network links
2240or queueing systems.
2241.Pp
2242.Nm dummynet
2243operates by first using the firewall to select packets
2244using any match pattern that can be used in
2245.Nm
2246rules.
2247Matching packets are then passed to either of two
2248different objects, which implement the traffic regulation:
2249.Bl -hang -offset XXXX
2250.It Em pipe
2251A
2252.Em pipe
2253emulates a
2254.Em link
2255with given bandwidth and propagation delay,
2256driven by a FIFO scheduler and a single queue with programmable
2257queue size and packet loss rate.
2258Packets are appended to the queue as they come out from
2259.Nm ipfw ,
2260and then transferred in FIFO order to the link at the desired rate.
2261.It Em queue
2262A
2263.Em queue
2264is an abstraction used to implement packet scheduling
2265using one of several packet scheduling algorithms.
2266Packets sent to a
2267.Em queue
2268are first grouped into flows according to a mask on the 5-tuple.
2269Flows are then passed to the scheduler associated to the
2270.Em queue ,
2271and each flow uses scheduling parameters (weight and others)
2272as configured in the
2273.Em queue
2274itself.
2275A scheduler in turn is connected to an emulated link,
2276and arbitrates the link's bandwidth among backlogged flows according to
2277weights and to the features of the scheduling algorithm in use.
2278.El
2279.Pp
2280In practice,
2281.Em pipes
2282can be used to set hard limits to the bandwidth that a flow can use, whereas
2283.Em queues
2284can be used to determine how different flows share the available bandwidth.
2285.Pp
2286A graphical representation of the binding of queues,
2287flows, schedulers and links is below.
2288.Bd -literal -offset indent
2289                 (flow_mask|sched_mask)  sched_mask
2290         +---------+   weight Wx  +-------------+
2291         |         |->-[flow]-->--|             |-+
2292    -->--| QUEUE x |   ...        |             | |
2293         |         |->-[flow]-->--| SCHEDuler N | |
2294         +---------+              |             | |
2295             ...                  |             +--[LINK N]-->--
2296         +---------+   weight Wy  |             | +--[LINK N]-->--
2297         |         |->-[flow]-->--|             | |
2298    -->--| QUEUE y |   ...        |             | |
2299         |         |->-[flow]-->--|             | |
2300         +---------+              +-------------+ |
2301                                    +-------------+
2302.Ed
2303It is important to understand the role of the SCHED_MASK
2304and FLOW_MASK, which are configured through the commands
2305.Dl "ipfw sched N config mask SCHED_MASK ..."
2306and
2307.Dl "ipfw queue X config mask FLOW_MASK ..." .
2308.Pp
2309The SCHED_MASK is used to assign flows to one or more
2310scheduler instances, one for each
2311value of the packet's 5-tuple after applying SCHED_MASK.
2312As an example, using ``src-ip 0xffffff00'' creates one instance
2313for each /24 destination subnet.
2314.Pp
2315The FLOW_MASK, together with the SCHED_MASK, is used to split
2316packets into flows.
2317As an example, using
2318``src-ip 0x000000ff''
2319together with the previous SCHED_MASK makes a flow for
2320each individual source address.
2321In turn, flows for each /24
2322subnet will be sent to the same scheduler instance.
2323.Pp
2324The above diagram holds even for the
2325.Em pipe
2326case, with the only restriction that a
2327.Em pipe
2328only supports a SCHED_MASK, and forces the use of a FIFO
2329scheduler (these are for backward compatibility reasons;
2330in fact, internally, a
2331.Nm dummynet's
2332pipe is implemented exactly as above).
2333.Pp
2334There are two modes of
2335.Nm dummynet
2336operation:
2337.Dq normal
2338and
2339.Dq fast .
2340The
2341.Dq normal
2342mode tries to emulate a real link: the
2343.Nm dummynet
2344scheduler ensures that the packet will not leave the pipe faster than it
2345would on the real link with a given bandwidth.
2346The
2347.Dq fast
2348mode allows certain packets to bypass the
2349.Nm dummynet
2350scheduler (if packet flow does not exceed pipe's bandwidth).
2351This is the reason why the
2352.Dq fast
2353mode requires less CPU cycles per packet (on average) and packet latency
2354can be significantly lower in comparison to a real link with the same
2355bandwidth.
2356The default mode is
2357.Dq normal .
2358The
2359.Dq fast
2360mode can be enabled by setting the
2361.Va net.inet.ip.dummynet.io_fast
2362.Xr sysctl 8
2363variable to a non-zero value.
2364.Pp
2365.Ss PIPE, QUEUE AND SCHEDULER CONFIGURATION
2366The
2367.Em pipe ,
2368.Em queue
2369and
2370.Em scheduler
2371configuration commands are the following:
2372.Bd -ragged -offset indent
2373.Cm pipe Ar number Cm config Ar pipe-configuration
2374.Pp
2375.Cm queue Ar number Cm config Ar queue-configuration
2376.Pp
2377.Cm sched Ar number Cm config Ar sched-configuration
2378.Ed
2379.Pp
2380The following parameters can be configured for a pipe:
2381.Pp
2382.Bl -tag -width indent -compact
2383.It Cm bw Ar bandwidth | device
2384Bandwidth, measured in
2385.Sm off
2386.Op Cm K | M
2387.Brq Cm bit/s | Byte/s .
2388.Sm on
2389.Pp
2390A value of 0 (default) means unlimited bandwidth.
2391The unit must immediately follow the number, as in
2392.Pp
2393.Dl "ipfw pipe 1 config bw 300Kbit/s"
2394.Pp
2395If a device name is specified instead of a numeric value, as in
2396.Pp
2397.Dl "ipfw pipe 1 config bw tun0"
2398.Pp
2399then the transmit clock is supplied by the specified device.
2400At the moment only the
2401.Xr tun 4
2402device supports this
2403functionality, for use in conjunction with
2404.Xr ppp 8 .
2405.Pp
2406.It Cm delay Ar ms-delay
2407Propagation delay, measured in milliseconds.
2408The value is rounded to the next multiple of the clock tick
2409(typically 10ms, but it is a good practice to run kernels
2410with
2411.Dq "options HZ=1000"
2412to reduce
2413the granularity to 1ms or less).
2414The default value is 0, meaning no delay.
2415.Pp
2416.It Cm burst Ar size
2417If the data to be sent exceeds the pipe's bandwidth limit
2418(and the pipe was previously idle), up to
2419.Ar size
2420bytes of data are allowed to bypass the
2421.Nm dummynet
2422scheduler, and will be sent as fast as the physical link allows.
2423Any additional data will be transmitted at the rate specified
2424by the
2425.Nm pipe
2426bandwidth.
2427The burst size depends on how long the pipe has been idle;
2428the effective burst size is calculated as follows:
2429MAX(
2430.Ar size
2431,
2432.Nm bw
2433* pipe_idle_time).
2434.Pp
2435.It Cm profile Ar filename
2436A file specifying the additional overhead incurred in the transmission
2437of a packet on the link.
2438.Pp
2439Some link types introduce extra delays in the transmission
2440of a packet, e.g., because of MAC level framing, contention on
2441the use of the channel, MAC level retransmissions and so on.
2442From our point of view, the channel is effectively unavailable
2443for this extra time, which is constant or variable depending
2444on the link type.
2445Additionally, packets may be dropped after this
2446time (e.g., on a wireless link after too many retransmissions).
2447We can model the additional delay with an empirical curve
2448that represents its distribution.
2449.Bd -literal -offset indent
2450      cumulative probability
2451      1.0 ^
2452          |
2453      L   +-- loss-level          x
2454          |                 ******
2455          |                *
2456          |           *****
2457          |          *
2458          |        **
2459          |       *
2460          +-------*------------------->
2461                      delay
2462.Ed
2463The empirical curve may have both vertical and horizontal lines.
2464Vertical lines represent constant delay for a range of
2465probabilities.
2466Horizontal lines correspond to a discontinuity in the delay
2467distribution: the pipe will use the largest delay for a
2468given probability.
2469.Pp
2470The file format is the following, with whitespace acting as
2471a separator and '#' indicating the beginning a comment:
2472.Bl -tag -width indent
2473.It Cm name Ar identifier
2474optional name (listed by "ipfw pipe show")
2475to identify the delay distribution;
2476.It Cm bw Ar value
2477the bandwidth used for the pipe.
2478If not specified here, it must be present
2479explicitly as a configuration parameter for the pipe;
2480.It Cm loss-level Ar L
2481the probability above which packets are lost.
2482(0.0 <= L <= 1.0, default 1.0 i.e., no loss);
2483.It Cm samples Ar N
2484the number of samples used in the internal
2485representation of the curve (2..1024; default 100);
2486.It Cm "delay prob" | "prob delay"
2487One of these two lines is mandatory and defines
2488the format of the following lines with data points.
2489.It Ar XXX Ar YYY
24902 or more lines representing points in the curve,
2491with either delay or probability first, according
2492to the chosen format.
2493The unit for delay is milliseconds.
2494Data points do not need to be sorted.
2495Also, the number of actual lines can be different
2496from the value of the "samples" parameter:
2497.Nm
2498utility will sort and interpolate
2499the curve as needed.
2500.El
2501.Pp
2502Example of a profile file:
2503.Bd -literal -offset indent
2504name    bla_bla_bla
2505samples 100
2506loss-level    0.86
2507prob    delay
25080       200	# minimum overhead is 200ms
25090.5     200
25100.5     300
25110.8     1000
25120.9     1300
25131       1300
2514#configuration file end
2515.Ed
2516.El
2517.Pp
2518The following parameters can be configured for a queue:
2519.Pp
2520.Bl -tag -width indent -compact
2521.It Cm pipe Ar pipe_nr
2522Connects a queue to the specified pipe.
2523Multiple queues (with the same or different weights) can be connected to
2524the same pipe, which specifies the aggregate rate for the set of queues.
2525.Pp
2526.It Cm weight Ar weight
2527Specifies the weight to be used for flows matching this queue.
2528The weight must be in the range 1..100, and defaults to 1.
2529.El
2530.Pp
2531The following case-insensitive parameters can be configured for a
2532scheduler:
2533.Pp
2534.Bl -tag -width indent -compact
2535.It Cm type Ar {fifo | wf2q+ | rr | qfq}
2536specifies the scheduling algorithm to use.
2537.Bl -tag -width indent -compact
2538.It Cm fifo
2539is just a FIFO scheduler (which means that all packets
2540are stored in the same queue as they arrive to the scheduler).
2541FIFO has O(1) per-packet time complexity, with very low
2542constants (estimate 60-80ns on a 2GHz desktop machine)
2543but gives no service guarantees.
2544.It Cm wf2q+
2545implements the WF2Q+ algorithm, which is a Weighted Fair Queueing
2546algorithm which permits flows to share bandwidth according to
2547their weights.
2548Note that weights are not priorities; even a flow
2549with a minuscule weight will never starve.
2550WF2Q+ has O(log N) per-packet processing cost, where N is the number
2551of flows, and is the default algorithm used by previous versions
2552dummynet's queues.
2553.It Cm rr
2554implements the Deficit Round Robin algorithm, which has O(1) processing
2555costs (roughly, 100-150ns per packet)
2556and permits bandwidth allocation according to weights, but
2557with poor service guarantees.
2558.It Cm qfq
2559implements the QFQ algorithm, which is a very fast variant of
2560WF2Q+, with similar service guarantees and O(1) processing
2561costs (roughly, 200-250ns per packet).
2562.El
2563.El
2564.Pp
2565In addition to the type, all parameters allowed for a pipe can also
2566be specified for a scheduler.
2567.Pp
2568Finally, the following parameters can be configured for both
2569pipes and queues:
2570.Pp
2571.Bl -tag -width XXXX -compact
2572.It Cm buckets Ar hash-table-size
2573Specifies the size of the hash table used for storing the
2574various queues.
2575Default value is 64 controlled by the
2576.Xr sysctl 8
2577variable
2578.Va net.inet.ip.dummynet.hash_size ,
2579allowed range is 16 to 65536.
2580.Pp
2581.It Cm mask Ar mask-specifier
2582Packets sent to a given pipe or queue by an
2583.Nm
2584rule can be further classified into multiple flows, each of which is then
2585sent to a different
2586.Em dynamic
2587pipe or queue.
2588A flow identifier is constructed by masking the IP addresses,
2589ports and protocol types as specified with the
2590.Cm mask
2591options in the configuration of the pipe or queue.
2592For each different flow identifier, a new pipe or queue is created
2593with the same parameters as the original object, and matching packets
2594are sent to it.
2595.Pp
2596Thus, when
2597.Em dynamic pipes
2598are used, each flow will get the same bandwidth as defined by the pipe,
2599whereas when
2600.Em dynamic queues
2601are used, each flow will share the parent's pipe bandwidth evenly
2602with other flows generated by the same queue (note that other queues
2603with different weights might be connected to the same pipe).
2604.br
2605Available mask specifiers are a combination of one or more of the following:
2606.Pp
2607.Cm dst-ip Ar mask ,
2608.Cm dst-ip6 Ar mask ,
2609.Cm src-ip Ar mask ,
2610.Cm src-ip6 Ar mask ,
2611.Cm dst-port Ar mask ,
2612.Cm src-port Ar mask ,
2613.Cm flow-id Ar mask ,
2614.Cm proto Ar mask
2615or
2616.Cm all ,
2617.Pp
2618where the latter means all bits in all fields are significant.
2619.Pp
2620.It Cm noerror
2621When a packet is dropped by a
2622.Nm dummynet
2623queue or pipe, the error
2624is normally reported to the caller routine in the kernel, in the
2625same way as it happens when a device queue fills up.
2626Setting this
2627option reports the packet as successfully delivered, which can be
2628needed for some experimental setups where you want to simulate
2629loss or congestion at a remote router.
2630.Pp
2631.It Cm plr Ar packet-loss-rate
2632Packet loss rate.
2633Argument
2634.Ar packet-loss-rate
2635is a floating-point number between 0 and 1, with 0 meaning no
2636loss, 1 meaning 100% loss.
2637The loss rate is internally represented on 31 bits.
2638.Pp
2639.It Cm queue Brq Ar slots | size Ns Cm Kbytes
2640Queue size, in
2641.Ar slots
2642or
2643.Cm KBytes .
2644Default value is 50 slots, which
2645is the typical queue size for Ethernet devices.
2646Note that for slow speed links you should keep the queue
2647size short or your traffic might be affected by a significant
2648queueing delay.
2649E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit
2650or 20s of queue on a 30Kbit/s pipe.
2651Even worse effects can result if you get packets from an
2652interface with a much larger MTU, e.g.\& the loopback interface
2653with its 16KB packets.
2654The
2655.Xr sysctl 8
2656variables
2657.Em net.inet.ip.dummynet.pipe_byte_limit
2658and
2659.Em net.inet.ip.dummynet.pipe_slot_limit
2660control the maximum lengths that can be specified.
2661.Pp
2662.It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p
2663[ecn]
2664Make use of the RED (Random Early Detection) queue management algorithm.
2665.Ar w_q
2666and
2667.Ar max_p
2668are floating
2669point numbers between 0 and 1 (inclusive), while
2670.Ar min_th
2671and
2672.Ar max_th
2673are integer numbers specifying thresholds for queue management
2674(thresholds are computed in bytes if the queue has been defined
2675in bytes, in slots otherwise).
2676The two parameters can also be of the same value if needed. The
2677.Nm dummynet
2678also supports the gentle RED variant (gred) and ECN (Explicit Congestion
2679Notification) as optional. Three
2680.Xr sysctl 8
2681variables can be used to control the RED behaviour:
2682.Bl -tag -width indent
2683.It Va net.inet.ip.dummynet.red_lookup_depth
2684specifies the accuracy in computing the average queue
2685when the link is idle (defaults to 256, must be greater than zero)
2686.It Va net.inet.ip.dummynet.red_avg_pkt_size
2687specifies the expected average packet size (defaults to 512, must be
2688greater than zero)
2689.It Va net.inet.ip.dummynet.red_max_pkt_size
2690specifies the expected maximum packet size, only used when queue
2691thresholds are in bytes (defaults to 1500, must be greater than zero).
2692.El
2693.El
2694.Pp
2695When used with IPv6 data,
2696.Nm dummynet
2697currently has several limitations.
2698Information necessary to route link-local packets to an
2699interface is not available after processing by
2700.Nm dummynet
2701so those packets are dropped in the output path.
2702Care should be taken to ensure that link-local packets are not passed to
2703.Nm dummynet .
2704.Sh CHECKLIST
2705Here are some important points to consider when designing your
2706rules:
2707.Bl -bullet
2708.It
2709Remember that you filter both packets going
2710.Cm in
2711and
2712.Cm out .
2713Most connections need packets going in both directions.
2714.It
2715Remember to test very carefully.
2716It is a good idea to be near the console when doing this.
2717If you cannot be near the console,
2718use an auto-recovery script such as the one in
2719.Pa /usr/share/examples/ipfw/change_rules.sh .
2720.It
2721Do not forget the loopback interface.
2722.El
2723.Sh FINE POINTS
2724.Bl -bullet
2725.It
2726There are circumstances where fragmented datagrams are unconditionally
2727dropped.
2728TCP packets are dropped if they do not contain at least 20 bytes of
2729TCP header, UDP packets are dropped if they do not contain a full 8
2730byte UDP header, and ICMP packets are dropped if they do not contain
27314 bytes of ICMP header, enough to specify the ICMP type, code, and
2732checksum.
2733These packets are simply logged as
2734.Dq pullup failed
2735since there may not be enough good data in the packet to produce a
2736meaningful log entry.
2737.It
2738Another type of packet is unconditionally dropped, a TCP packet with a
2739fragment offset of one.
2740This is a valid packet, but it only has one use, to try
2741to circumvent firewalls.
2742When logging is enabled, these packets are
2743reported as being dropped by rule -1.
2744.It
2745If you are logged in over a network, loading the
2746.Xr kld 4
2747version of
2748.Nm
2749is probably not as straightforward as you would think.
2750The following command line is recommended:
2751.Bd -literal -offset indent
2752kldload ipfw && \e
2753ipfw add 32000 allow ip from any to any
2754.Ed
2755.Pp
2756Along the same lines, doing an
2757.Bd -literal -offset indent
2758ipfw flush
2759.Ed
2760.Pp
2761in similar surroundings is also a bad idea.
2762.It
2763The
2764.Nm
2765filter list may not be modified if the system security level
2766is set to 3 or higher
2767(see
2768.Xr init 8
2769for information on system security levels).
2770.El
2771.Sh PACKET DIVERSION
2772A
2773.Xr divert 4
2774socket bound to the specified port will receive all packets
2775diverted to that port.
2776If no socket is bound to the destination port, or if the divert module is
2777not loaded, or if the kernel was not compiled with divert socket support,
2778the packets are dropped.
2779.Sh NETWORK ADDRESS TRANSLATION (NAT)
2780.Nm
2781support in-kernel NAT using the kernel version of
2782.Xr libalias 3 .
2783.Pp
2784The nat configuration command is the following:
2785.Bd -ragged -offset indent
2786.Bk -words
2787.Cm nat
2788.Ar nat_number
2789.Cm config
2790.Ar nat-configuration
2791.Ek
2792.Ed
2793.Pp
2794The following parameters can be configured:
2795.Bl -tag -width indent
2796.It Cm ip Ar ip_address
2797Define an ip address to use for aliasing.
2798.It Cm if Ar nic
2799Use ip address of NIC for aliasing, dynamically changing
2800it if NIC's ip address changes.
2801.It Cm log
2802Enable logging on this nat instance.
2803.It Cm deny_in
2804Deny any incoming connection from outside world.
2805.It Cm same_ports
2806Try to leave the alias port numbers unchanged from
2807the actual local port numbers.
2808.It Cm unreg_only
2809Traffic on the local network not originating from an
2810unregistered address spaces will be ignored.
2811.It Cm reset
2812Reset table of the packet aliasing engine on address change.
2813.It Cm reverse
2814Reverse the way libalias handles aliasing.
2815.It Cm proxy_only
2816Obey transparent proxy rules only, packet aliasing is not performed.
2817.It Cm skip_global
2818Skip instance in case of global state lookup (see below).
2819.El
2820.Pp
2821Some specials value can be supplied instead of
2822.Va nat_number:
2823.Bl -tag -width indent
2824.It Cm global
2825Looks up translation state in all configured nat instances.
2826If an entry is found, packet is aliased according to that entry.
2827If no entry was found in any of the instances, packet is passed unchanged,
2828and no new entry will be created.
2829See section
2830.Sx MULTIPLE INSTANCES
2831in
2832.Xr natd 8
2833for more information.
2834.It Cm tablearg
2835Uses argument supplied in lookup table.
2836See
2837.Sx LOOKUP TABLES
2838section below for more information on lookup tables.
2839.El
2840.Pp
2841To let the packet continue after being (de)aliased, set the sysctl variable
2842.Va net.inet.ip.fw.one_pass
2843to 0.
2844For more information about aliasing modes, refer to
2845.Xr libalias 3 .
2846See Section
2847.Sx EXAMPLES
2848for some examples about nat usage.
2849.Ss REDIRECT AND LSNAT SUPPORT IN IPFW
2850Redirect and LSNAT support follow closely the syntax used in
2851.Xr natd 8 .
2852See Section
2853.Sx EXAMPLES
2854for some examples on how to do redirect and lsnat.
2855.Ss SCTP NAT SUPPORT
2856SCTP nat can be configured in a similar manner to TCP through the
2857.Nm
2858command line tool.
2859The main difference is that
2860.Nm sctp nat
2861does not do port translation.
2862Since the local and global side ports will be the same,
2863there is no need to specify both.
2864Ports are redirected as follows:
2865.Bd -ragged -offset indent
2866.Bk -words
2867.Cm nat
2868.Ar nat_number
2869.Cm config if
2870.Ar nic
2871.Cm redirect_port sctp
2872.Ar ip_address [,addr_list] {[port | port-port] [,ports]}
2873.Ek
2874.Ed
2875.Pp
2876Most
2877.Nm sctp nat
2878configuration can be done in real-time through the
2879.Xr sysctl 8
2880interface.
2881All may be changed dynamically, though the hash_table size will only
2882change for new
2883.Nm nat
2884instances.
2885See
2886.Sx SYSCTL VARIABLES
2887for more info.
2888.Sh LOADER TUNABLES
2889Tunables can be set in
2890.Xr loader 8
2891prompt,
2892.Xr loader.conf 5
2893or
2894.Xr kenv 1
2895before ipfw module gets loaded.
2896.Bl -tag -width indent
2897.It Va net.inet.ip.fw.default_to_accept: No 0
2898Defines ipfw last rule behavior.
2899This value overrides
2900.Cd "options IPFW_DEFAULT_TO_(ACCEPT|DENY)"
2901from kernel configuration file.
2902.It Va net.inet.ip.fw.tables_max: No 128
2903Defines number of tables available in ipfw.
2904Number cannot exceed 65534.
2905.El
2906.Sh SYSCTL VARIABLES
2907A set of
2908.Xr sysctl 8
2909variables controls the behaviour of the firewall and
2910associated modules
2911.Pq Nm dummynet , bridge , sctp nat .
2912These are shown below together with their default value
2913(but always check with the
2914.Xr sysctl 8
2915command what value is actually in use) and meaning:
2916.Bl -tag -width indent
2917.It Va net.inet.ip.alias.sctp.accept_global_ootb_addip: No 0
2918Defines how the
2919.Nm nat
2920responds to receipt of global OOTB ASCONF-AddIP:
2921.Bl -tag -width indent
2922.It Cm 0
2923No response (unless a partially matching association exists -
2924ports and vtags match but global address does not)
2925.It Cm 1
2926.Nm nat
2927will accept and process all OOTB global AddIP messages.
2928.El
2929.Pp
2930Option 1 should never be selected as this forms a security risk.
2931An attacker can
2932establish multiple fake associations by sending AddIP messages.
2933.It Va net.inet.ip.alias.sctp.chunk_proc_limit: No 5
2934Defines the maximum number of chunks in an SCTP packet that will be
2935parsed for a
2936packet that matches an existing association.
2937This value is enforced to be greater or equal than
2938.Cm net.inet.ip.alias.sctp.initialising_chunk_proc_limit .
2939A high value is
2940a DoS risk yet setting too low a value may result in
2941important control chunks in
2942the packet not being located and parsed.
2943.It Va net.inet.ip.alias.sctp.error_on_ootb: No 1
2944Defines when the
2945.Nm nat
2946responds to any Out-of-the-Blue (OOTB) packets with ErrorM packets.
2947An OOTB packet is a packet that arrives with no existing association
2948registered in the
2949.Nm nat
2950and is not an INIT or ASCONF-AddIP packet:
2951.Bl -tag -width indent
2952.It Cm 0
2953ErrorM is never sent in response to OOTB packets.
2954.It Cm 1
2955ErrorM is only sent to OOTB packets received on the local side.
2956.It Cm 2
2957ErrorM is sent to the local side and on the global side ONLY if there is a
2958partial match (ports and vtags match but the source global IP does not).
2959This value is only useful if the
2960.Nm nat
2961is tracking global IP addresses.
2962.It Cm 3
2963ErrorM is sent in response to all OOTB packets on both
2964the local and global side
2965(DoS risk).
2966.El
2967.Pp
2968At the moment the default is 0, since the ErrorM packet is not yet
2969supported by most SCTP stacks.
2970When it is supported, and if not tracking
2971global addresses, we recommend setting this value to 1 to allow
2972multi-homed local hosts to function with the
2973.Nm nat .
2974To track global addresses, we recommend setting this value to 2 to
2975allow global hosts to be informed when they need to (re)send an
2976ASCONF-AddIP.
2977Value 3 should never be chosen (except for debugging) as the
2978.Nm nat
2979will respond to all OOTB global packets (a DoS risk).
2980.It Va net.inet.ip.alias.sctp.hashtable_size: No 2003
2981Size of hash tables used for
2982.Nm nat
2983lookups (100 < prime_number > 1000001).
2984This value sets the
2985.Nm hash table
2986size for any future created
2987.Nm nat
2988instance and therefore must be set prior to creating a
2989.Nm nat
2990instance.
2991The table sizes may be changed to suit specific needs.
2992If there will be few
2993concurrent associations, and memory is scarce, you may make these smaller.
2994If there will be many thousands (or millions) of concurrent associations, you
2995should make these larger.
2996A prime number is best for the table size.
2997The sysctl
2998update function will adjust your input value to the next highest prime number.
2999.It Va net.inet.ip.alias.sctp.holddown_time:  No 0
3000Hold association in table for this many seconds after receiving a
3001SHUTDOWN-COMPLETE.
3002This allows endpoints to correct shutdown gracefully if a
3003shutdown_complete is lost and retransmissions are required.
3004.It Va net.inet.ip.alias.sctp.init_timer: No 15
3005Timeout value while waiting for (INIT-ACK|AddIP-ACK).
3006This value cannot be 0.
3007.It Va net.inet.ip.alias.sctp.initialising_chunk_proc_limit: No 2
3008Defines the maximum number of chunks in an SCTP packet that will be parsed when
3009no existing association exists that matches that packet.
3010Ideally this packet
3011will only be an INIT or ASCONF-AddIP packet.
3012A higher value may become a DoS
3013risk as malformed packets can consume processing resources.
3014.It Va net.inet.ip.alias.sctp.param_proc_limit: No 25
3015Defines the maximum number of parameters within a chunk that will be
3016parsed in a
3017packet.
3018As for other similar sysctl variables, larger values pose a DoS risk.
3019.It Va net.inet.ip.alias.sctp.log_level: No 0
3020Level of detail in the system log messages (0 \- minimal, 1 \- event,
30212 \- info, 3 \- detail, 4 \- debug, 5 \- max debug).
3022May be a good
3023option in high loss environments.
3024.It Va net.inet.ip.alias.sctp.shutdown_time: No 15
3025Timeout value while waiting for SHUTDOWN-COMPLETE.
3026This value cannot be 0.
3027.It Va net.inet.ip.alias.sctp.track_global_addresses: No 0
3028Enables/disables global IP address tracking within the
3029.Nm nat
3030and places an
3031upper limit on the number of addresses tracked for each association:
3032.Bl -tag -width indent
3033.It Cm 0
3034Global tracking is disabled
3035.It Cm >1
3036Enables tracking, the maximum number of addresses tracked for each
3037association is limited to this value
3038.El
3039.Pp
3040This variable is fully dynamic, the new value will be adopted for all newly
3041arriving associations, existing associations are treated
3042as they were previously.
3043Global tracking will decrease the number of collisions within the
3044.Nm nat
3045at a cost
3046of increased processing load, memory usage, complexity, and possible
3047.Nm nat
3048state
3049problems in complex networks with multiple
3050.Nm nats .
3051We recommend not tracking
3052global IP addresses, this will still result in a fully functional
3053.Nm nat .
3054.It Va net.inet.ip.alias.sctp.up_timer: No 300
3055Timeout value to keep an association up with no traffic.
3056This value cannot be 0.
3057.It Va net.inet.ip.dummynet.expire : No 1
3058Lazily delete dynamic pipes/queue once they have no pending traffic.
3059You can disable this by setting the variable to 0, in which case
3060the pipes/queues will only be deleted when the threshold is reached.
3061.It Va net.inet.ip.dummynet.hash_size : No 64
3062Default size of the hash table used for dynamic pipes/queues.
3063This value is used when no
3064.Cm buckets
3065option is specified when configuring a pipe/queue.
3066.It Va net.inet.ip.dummynet.io_fast : No 0
3067If set to a non-zero value,
3068the
3069.Dq fast
3070mode of
3071.Nm dummynet
3072operation (see above) is enabled.
3073.It Va net.inet.ip.dummynet.io_pkt
3074Number of packets passed to
3075.Nm dummynet .
3076.It Va net.inet.ip.dummynet.io_pkt_drop
3077Number of packets dropped by
3078.Nm dummynet .
3079.It Va net.inet.ip.dummynet.io_pkt_fast
3080Number of packets bypassed by the
3081.Nm dummynet
3082scheduler.
3083.It Va net.inet.ip.dummynet.max_chain_len : No 16
3084Target value for the maximum number of pipes/queues in a hash bucket.
3085The product
3086.Cm max_chain_len*hash_size
3087is used to determine the threshold over which empty pipes/queues
3088will be expired even when
3089.Cm net.inet.ip.dummynet.expire=0 .
3090.It Va net.inet.ip.dummynet.red_lookup_depth : No 256
3091.It Va net.inet.ip.dummynet.red_avg_pkt_size : No 512
3092.It Va net.inet.ip.dummynet.red_max_pkt_size : No 1500
3093Parameters used in the computations of the drop probability
3094for the RED algorithm.
3095.It Va net.inet.ip.dummynet.pipe_byte_limit : No 1048576
3096.It Va net.inet.ip.dummynet.pipe_slot_limit : No 100
3097The maximum queue size that can be specified in bytes or packets.
3098These limits prevent accidental exhaustion of resources such as mbufs.
3099If you raise these limits,
3100you should make sure the system is configured so that sufficient resources
3101are available.
3102.It Va net.inet.ip.fw.autoinc_step : No 100
3103Delta between rule numbers when auto-generating them.
3104The value must be in the range 1..1000.
3105.It Va net.inet.ip.fw.curr_dyn_buckets : Va net.inet.ip.fw.dyn_buckets
3106The current number of buckets in the hash table for dynamic rules
3107(readonly).
3108.It Va net.inet.ip.fw.debug : No 1
3109Controls debugging messages produced by
3110.Nm .
3111.It Va net.inet.ip.fw.default_rule : No 65535
3112The default rule number (read-only).
3113By the design of
3114.Nm , the default rule is the last one, so its number
3115can also serve as the highest number allowed for a rule.
3116.It Va net.inet.ip.fw.dyn_buckets : No 256
3117The number of buckets in the hash table for dynamic rules.
3118Must be a power of 2, up to 65536.
3119It only takes effect when all dynamic rules have expired, so you
3120are advised to use a
3121.Cm flush
3122command to make sure that the hash table is resized.
3123.It Va net.inet.ip.fw.dyn_count : No 3
3124Current number of dynamic rules
3125(read-only).
3126.It Va net.inet.ip.fw.dyn_keepalive : No 1
3127Enables generation of keepalive packets for
3128.Cm keep-state
3129rules on TCP sessions.
3130A keepalive is generated to both
3131sides of the connection every 5 seconds for the last 20
3132seconds of the lifetime of the rule.
3133.It Va net.inet.ip.fw.dyn_max : No 8192
3134Maximum number of dynamic rules.
3135When you hit this limit, no more dynamic rules can be
3136installed until old ones expire.
3137.It Va net.inet.ip.fw.dyn_ack_lifetime : No 300
3138.It Va net.inet.ip.fw.dyn_syn_lifetime : No 20
3139.It Va net.inet.ip.fw.dyn_fin_lifetime : No 1
3140.It Va net.inet.ip.fw.dyn_rst_lifetime : No 1
3141.It Va net.inet.ip.fw.dyn_udp_lifetime : No 5
3142.It Va net.inet.ip.fw.dyn_short_lifetime : No 30
3143These variables control the lifetime, in seconds, of dynamic
3144rules.
3145Upon the initial SYN exchange the lifetime is kept short,
3146then increased after both SYN have been seen, then decreased
3147again during the final FIN exchange or when a RST is received.
3148Both
3149.Em dyn_fin_lifetime
3150and
3151.Em dyn_rst_lifetime
3152must be strictly lower than 5 seconds, the period of
3153repetition of keepalives.
3154The firewall enforces that.
3155.It Va net.inet.ip.fw.dyn_keep_states: No 0
3156Keep dynamic states on rule/set deletion.
3157States are relinked to default rule (65535).
3158This can be handly for ruleset reload.
3159Turned off by default.
3160.It Va net.inet.ip.fw.enable : No 1
3161Enables the firewall.
3162Setting this variable to 0 lets you run your machine without
3163firewall even if compiled in.
3164.It Va net.inet6.ip6.fw.enable : No 1
3165provides the same functionality as above for the IPv6 case.
3166.It Va net.inet.ip.fw.one_pass : No 1
3167When set, the packet exiting from the
3168.Nm dummynet
3169pipe or from
3170.Xr ng_ipfw 4
3171node is not passed though the firewall again.
3172Otherwise, after an action, the packet is
3173reinjected into the firewall at the next rule.
3174.It Va net.inet.ip.fw.tables_max : No 128
3175Maximum number of tables.
3176.It Va net.inet.ip.fw.verbose : No 1
3177Enables verbose messages.
3178.It Va net.inet.ip.fw.verbose_limit : No 0
3179Limits the number of messages produced by a verbose firewall.
3180.It Va net.inet6.ip6.fw.deny_unknown_exthdrs : No 1
3181If enabled packets with unknown IPv6 Extension Headers will be denied.
3182.It Va net.link.ether.ipfw : No 0
3183Controls whether layer-2 packets are passed to
3184.Nm .
3185Default is no.
3186.It Va net.link.bridge.ipfw : No 0
3187Controls whether bridged packets are passed to
3188.Nm .
3189Default is no.
3190.El
3191.Sh INTERNAL DIAGNOSTICS
3192There are some commands that may be useful to understand current state
3193of certain subsystems inside kernel module.
3194These commands provide debugging output which may change without notice.
3195.Pp
3196Currently the following commands are available as
3197.Cm internal
3198sub-options:
3199.Bl -tag -width indent
3200.It Cm iflist
3201Lists all interface which are currently tracked by
3202.Nm
3203with their in-kernel status.
3204.It Cm talist
3205List all table lookup algorithms currently available.
3206.El
3207.Sh EXAMPLES
3208There are far too many possible uses of
3209.Nm
3210so this Section will only give a small set of examples.
3211.Pp
3212.Ss BASIC PACKET FILTERING
3213This command adds an entry which denies all tcp packets from
3214.Em cracker.evil.org
3215to the telnet port of
3216.Em wolf.tambov.su
3217from being forwarded by the host:
3218.Pp
3219.Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet"
3220.Pp
3221This one disallows any connection from the entire cracker's
3222network to my host:
3223.Pp
3224.Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org"
3225.Pp
3226A first and efficient way to limit access (not using dynamic rules)
3227is the use of the following rules:
3228.Pp
3229.Dl "ipfw add allow tcp from any to any established"
3230.Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup"
3231.Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup"
3232.Dl "..."
3233.Dl "ipfw add deny tcp from any to any"
3234.Pp
3235The first rule will be a quick match for normal TCP packets,
3236but it will not match the initial SYN packet, which will be
3237matched by the
3238.Cm setup
3239rules only for selected source/destination pairs.
3240All other SYN packets will be rejected by the final
3241.Cm deny
3242rule.
3243.Pp
3244If you administer one or more subnets, you can take advantage
3245of the address sets and or-blocks and write extremely
3246compact rulesets which selectively enable services to blocks
3247of clients, as below:
3248.Pp
3249.Dl "goodguys=\*q{ 10.1.2.0/24{20,35,66,18} or 10.2.3.0/28{6,3,11} }\*q"
3250.Dl "badguys=\*q10.1.2.0/24{8,38,60}\*q"
3251.Dl ""
3252.Dl "ipfw add allow ip from ${goodguys} to any"
3253.Dl "ipfw add deny ip from ${badguys} to any"
3254.Dl "... normal policies ..."
3255.Pp
3256The
3257.Cm verrevpath
3258option could be used to do automated anti-spoofing by adding the
3259following to the top of a ruleset:
3260.Pp
3261.Dl "ipfw add deny ip from any to any not verrevpath in"
3262.Pp
3263This rule drops all incoming packets that appear to be coming to the
3264system on the wrong interface.
3265For example, a packet with a source
3266address belonging to a host on a protected internal network would be
3267dropped if it tried to enter the system from an external interface.
3268.Pp
3269The
3270.Cm antispoof
3271option could be used to do similar but more restricted anti-spoofing
3272by adding the following to the top of a ruleset:
3273.Pp
3274.Dl "ipfw add deny ip from any to any not antispoof in"
3275.Pp
3276This rule drops all incoming packets that appear to be coming from another
3277directly connected system but on the wrong interface.
3278For example, a packet with a source address of
3279.Li 192.168.0.0/24 ,
3280configured on
3281.Li fxp0 ,
3282but coming in on
3283.Li fxp1
3284would be dropped.
3285.Pp
3286The
3287.Cm setdscp
3288option could be used to (re)mark user traffic,
3289by adding the following to the appropriate place in ruleset:
3290.Pp
3291.Dl "ipfw add setdscp be ip from any to any dscp af11,af21"
3292.Ss DYNAMIC RULES
3293In order to protect a site from flood attacks involving fake
3294TCP packets, it is safer to use dynamic rules:
3295.Pp
3296.Dl "ipfw add check-state"
3297.Dl "ipfw add deny tcp from any to any established"
3298.Dl "ipfw add allow tcp from my-net to any setup keep-state"
3299.Pp
3300This will let the firewall install dynamic rules only for
3301those connection which start with a regular SYN packet coming
3302from the inside of our network.
3303Dynamic rules are checked when encountering the first
3304occurrence of a
3305.Cm check-state ,
3306.Cm keep-state
3307or
3308.Cm limit
3309rule.
3310A
3311.Cm check-state
3312rule should usually be placed near the beginning of the
3313ruleset to minimize the amount of work scanning the ruleset.
3314Your mileage may vary.
3315.Pp
3316To limit the number of connections a user can open
3317you can use the following type of rules:
3318.Pp
3319.Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10"
3320.Dl "ipfw add allow tcp from any to me setup limit src-addr 4"
3321.Pp
3322The former (assuming it runs on a gateway) will allow each host
3323on a /24 network to open at most 10 TCP connections.
3324The latter can be placed on a server to make sure that a single
3325client does not use more than 4 simultaneous connections.
3326.Pp
3327.Em BEWARE :
3328stateful rules can be subject to denial-of-service attacks
3329by a SYN-flood which opens a huge number of dynamic rules.
3330The effects of such attacks can be partially limited by
3331acting on a set of
3332.Xr sysctl 8
3333variables which control the operation of the firewall.
3334.Pp
3335Here is a good usage of the
3336.Cm list
3337command to see accounting records and timestamp information:
3338.Pp
3339.Dl ipfw -at list
3340.Pp
3341or in short form without timestamps:
3342.Pp
3343.Dl ipfw -a list
3344.Pp
3345which is equivalent to:
3346.Pp
3347.Dl ipfw show
3348.Pp
3349Next rule diverts all incoming packets from 192.168.2.0/24
3350to divert port 5000:
3351.Pp
3352.Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in
3353.Ss TRAFFIC SHAPING
3354The following rules show some of the applications of
3355.Nm
3356and
3357.Nm dummynet
3358for simulations and the like.
3359.Pp
3360This rule drops random incoming packets with a probability
3361of 5%:
3362.Pp
3363.Dl "ipfw add prob 0.05 deny ip from any to any in"
3364.Pp
3365A similar effect can be achieved making use of
3366.Nm dummynet
3367pipes:
3368.Pp
3369.Dl "ipfw add pipe 10 ip from any to any"
3370.Dl "ipfw pipe 10 config plr 0.05"
3371.Pp
3372We can use pipes to artificially limit bandwidth, e.g.\& on a
3373machine acting as a router, if we want to limit traffic from
3374local clients on 192.168.2.0/24 we do:
3375.Pp
3376.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out"
3377.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes"
3378.Pp
3379note that we use the
3380.Cm out
3381modifier so that the rule is not used twice.
3382Remember in fact that
3383.Nm
3384rules are checked both on incoming and outgoing packets.
3385.Pp
3386Should we want to simulate a bidirectional link with bandwidth
3387limitations, the correct way is the following:
3388.Pp
3389.Dl "ipfw add pipe 1 ip from any to any out"
3390.Dl "ipfw add pipe 2 ip from any to any in"
3391.Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes"
3392.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes"
3393.Pp
3394The above can be very useful, e.g.\& if you want to see how
3395your fancy Web page will look for a residential user who
3396is connected only through a slow link.
3397You should not use only one pipe for both directions, unless
3398you want to simulate a half-duplex medium (e.g.\& AppleTalk,
3399Ethernet, IRDA).
3400It is not necessary that both pipes have the same configuration,
3401so we can also simulate asymmetric links.
3402.Pp
3403Should we want to verify network performance with the RED queue
3404management algorithm:
3405.Pp
3406.Dl "ipfw add pipe 1 ip from any to any"
3407.Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1"
3408.Pp
3409Another typical application of the traffic shaper is to
3410introduce some delay in the communication.
3411This can significantly affect applications which do a lot of Remote
3412Procedure Calls, and where the round-trip-time of the
3413connection often becomes a limiting factor much more than
3414bandwidth:
3415.Pp
3416.Dl "ipfw add pipe 1 ip from any to any out"
3417.Dl "ipfw add pipe 2 ip from any to any in"
3418.Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s"
3419.Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s"
3420.Pp
3421Per-flow queueing can be useful for a variety of purposes.
3422A very simple one is counting traffic:
3423.Pp
3424.Dl "ipfw add pipe 1 tcp from any to any"
3425.Dl "ipfw add pipe 1 udp from any to any"
3426.Dl "ipfw add pipe 1 ip from any to any"
3427.Dl "ipfw pipe 1 config mask all"
3428.Pp
3429The above set of rules will create queues (and collect
3430statistics) for all traffic.
3431Because the pipes have no limitations, the only effect is
3432collecting statistics.
3433Note that we need 3 rules, not just the last one, because
3434when
3435.Nm
3436tries to match IP packets it will not consider ports, so we
3437would not see connections on separate ports as different
3438ones.
3439.Pp
3440A more sophisticated example is limiting the outbound traffic
3441on a net with per-host limits, rather than per-network limits:
3442.Pp
3443.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out"
3444.Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in"
3445.Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
3446.Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
3447.Ss LOOKUP TABLES
3448In the following example, we need to create several traffic bandwidth
3449classes and we need different hosts/networks to fall into different classes.
3450We create one pipe for each class and configure them accordingly.
3451Then we create a single table and fill it with IP subnets and addresses.
3452For each subnet/host we set the argument equal to the number of the pipe
3453that it should use.
3454Then we classify traffic using a single rule:
3455.Pp
3456.Dl "ipfw pipe 1 config bw 1000Kbyte/s"
3457.Dl "ipfw pipe 4 config bw 4000Kbyte/s"
3458.Dl "..."
3459.Dl "ipfw table T1 create type addr"
3460.Dl "ipfw table T1 add 192.168.2.0/24 1"
3461.Dl "ipfw table T1 add 192.168.0.0/27 4"
3462.Dl "ipfw table T1 add 192.168.0.2 1"
3463.Dl "..."
3464.Dl "ipfw add pipe tablearg ip from 'table(T1)' to any"
3465.Pp
3466Using the
3467.Cm fwd
3468action, the table entries may include hostnames and IP addresses.
3469.Pp
3470.Dl "ipfw table T2 create type addr ftype ip"
3471.Dl "ipfw table T2 add 192.168.2.0/24 10.23.2.1"
3472.Dl "ipfw table T21 add 192.168.0.0/27 router1.dmz"
3473.Dl "..."
3474.Dl "ipfw add 100 fwd tablearg ip from any to table(1)"
3475.Pp
3476In the following example per-interface firewall is created:
3477.Pp
3478.Dl "ipfw table IN create type iface valtype skipto,fib"
3479.Dl "ipfw table IN add vlan20 12000,12"
3480.Dl "ipfw table IN add vlan30 13000,13"
3481.Dl "ipfw table OUT create type iface valtype skipto"
3482.Dl "ipfw table OUT add vlan20 22000"
3483.Dl "ipfw table OUT add vlan30 23000"
3484.Dl ".."
3485.Dl "ipfw add 100 ipfw setfib tablearg ip from any to any recv 'table(IN)' in"
3486.Dl "ipfw add 200 ipfw skipto tablearg ip from any to any recv 'table(IN)' in"
3487.Dl "ipfw add 300 ipfw skipto tablearg ip from any to any xmit 'table(OUT)' out"
3488.Pp
3489The following example illustrate usage of flow tables:
3490.Pp
3491.Dl "ipfw table fl create type flow:flow:src-ip,proto,dst-ip,dst-port"
3492.Dl "ipfw table fl add 2a02:6b8:77::88,tcp,2a02:6b8:77::99,80 11"
3493.Dl "ipfw table fl add 10.0.0.1,udp,10.0.0.2,53 12"
3494.Dl ".."
3495.Dl "ipfw add 100 allow ip from any to any flow 'table(fl,11)' recv ix0"
3496.Ss SETS OF RULES
3497To add a set of rules atomically, e.g.\& set 18:
3498.Pp
3499.Dl "ipfw set disable 18"
3500.Dl "ipfw add NN set 18 ...         # repeat as needed"
3501.Dl "ipfw set enable 18"
3502.Pp
3503To delete a set of rules atomically the command is simply:
3504.Pp
3505.Dl "ipfw delete set 18"
3506.Pp
3507To test a ruleset and disable it and regain control if something goes wrong:
3508.Pp
3509.Dl "ipfw set disable 18"
3510.Dl "ipfw add NN set 18 ...         # repeat as needed"
3511.Dl "ipfw set enable 18; echo done; sleep 30 && ipfw set disable 18"
3512.Pp
3513Here if everything goes well, you press control-C before the "sleep"
3514terminates, and your ruleset will be left active.
3515Otherwise, e.g.\& if
3516you cannot access your box, the ruleset will be disabled after
3517the sleep terminates thus restoring the previous situation.
3518.Pp
3519To show rules of the specific set:
3520.Pp
3521.Dl "ipfw set 18 show"
3522.Pp
3523To show rules of the disabled set:
3524.Pp
3525.Dl "ipfw -S set 18 show"
3526.Pp
3527To clear a specific rule counters of the specific set:
3528.Pp
3529.Dl "ipfw set 18 zero NN"
3530.Pp
3531To delete a specific rule of the specific set:
3532.Pp
3533.Dl "ipfw set 18 delete NN"
3534.Ss NAT, REDIRECT AND LSNAT
3535First redirect all the traffic to nat instance 123:
3536.Pp
3537.Dl "ipfw add nat 123 all from any to any"
3538.Pp
3539Then to configure nat instance 123 to alias all the outgoing traffic with ip
3540192.168.0.123, blocking all incoming connections, trying to keep
3541same ports on both sides, clearing aliasing table on address change
3542and keeping a log of traffic/link statistics:
3543.Pp
3544.Dl "ipfw nat 123 config ip 192.168.0.123 log deny_in reset same_ports"
3545.Pp
3546Or to change address of instance 123, aliasing table will be cleared (see
3547reset option):
3548.Pp
3549.Dl "ipfw nat 123 config ip 10.0.0.1"
3550.Pp
3551To see configuration of nat instance 123:
3552.Pp
3553.Dl "ipfw nat 123 show config"
3554.Pp
3555To show logs of all the instances in range 111-999:
3556.Pp
3557.Dl "ipfw nat 111-999 show"
3558.Pp
3559To see configurations of all instances:
3560.Pp
3561.Dl "ipfw nat show config"
3562.Pp
3563Or a redirect rule with mixed modes could looks like:
3564.Pp
3565.Dl "ipfw nat 123 config redirect_addr 10.0.0.1 10.0.0.66"
3566.Dl "			 redirect_port tcp 192.168.0.1:80 500"
3567.Dl "			 redirect_proto udp 192.168.1.43 192.168.1.1"
3568.Dl "			 redirect_addr 192.168.0.10,192.168.0.11"
3569.Dl "			 	    10.0.0.100	# LSNAT"
3570.Dl "			 redirect_port tcp 192.168.0.1:80,192.168.0.10:22"
3571.Dl "			 	    500		# LSNAT"
3572.Pp
3573or it could be split in:
3574.Pp
3575.Dl "ipfw nat 1 config redirect_addr 10.0.0.1 10.0.0.66"
3576.Dl "ipfw nat 2 config redirect_port tcp 192.168.0.1:80 500"
3577.Dl "ipfw nat 3 config redirect_proto udp 192.168.1.43 192.168.1.1"
3578.Dl "ipfw nat 4 config redirect_addr 192.168.0.10,192.168.0.11,192.168.0.12"
3579.Dl "				         10.0.0.100"
3580.Dl "ipfw nat 5 config redirect_port tcp"
3581.Dl "			192.168.0.1:80,192.168.0.10:22,192.168.0.20:25 500"
3582.Sh SEE ALSO
3583.Xr cpp 1 ,
3584.Xr m4 1 ,
3585.Xr altq 4 ,
3586.Xr divert 4 ,
3587.Xr dummynet 4 ,
3588.Xr if_bridge 4 ,
3589.Xr ip 4 ,
3590.Xr ipfirewall 4 ,
3591.Xr ng_ipfw 4 ,
3592.Xr protocols 5 ,
3593.Xr services 5 ,
3594.Xr init 8 ,
3595.Xr kldload 8 ,
3596.Xr reboot 8 ,
3597.Xr sysctl 8 ,
3598.Xr syslogd 8
3599.Sh HISTORY
3600The
3601.Nm
3602utility first appeared in
3603.Fx 2.0 .
3604.Nm dummynet
3605was introduced in
3606.Fx 2.2.8 .
3607Stateful extensions were introduced in
3608.Fx 4.0 .
3609.Nm ipfw2
3610was introduced in Summer 2002.
3611.Sh AUTHORS
3612.An Ugen J. S. Antsilevich ,
3613.An Poul-Henning Kamp ,
3614.An Alex Nash ,
3615.An Archie Cobbs ,
3616.An Luigi Rizzo .
3617.Pp
3618.An -nosplit
3619API based upon code written by
3620.An Daniel Boulet
3621for BSDI.
3622.Pp
3623Dummynet has been introduced by Luigi Rizzo in 1997-1998.
3624.Pp
3625Some early work (1999-2000) on the
3626.Nm dummynet
3627traffic shaper supported by Akamba Corp.
3628.Pp
3629The ipfw core (ipfw2) has been completely redesigned and
3630reimplemented by Luigi Rizzo in summer 2002.
3631Further
3632actions and
3633options have been added by various developer over the years.
3634.Pp
3635.An -nosplit
3636In-kernel NAT support written by
3637.An Paolo Pisati Aq Mt piso@FreeBSD.org
3638as part of a Summer of Code 2005 project.
3639.Pp
3640SCTP
3641.Nm nat
3642support has been developed by
3643.An The Centre for Advanced Internet Architectures (CAIA) Aq http://www.caia.swin.edu.au .
3644The primary developers and maintainers are David Hayes and Jason But.
3645For further information visit:
3646.Aq http://www.caia.swin.edu.au/urp/SONATA
3647.Pp
3648Delay profiles have been developed by Alessandro Cerri and
3649Luigi Rizzo, supported by the
3650European Commission within Projects Onelab and Onelab2.
3651.Sh BUGS
3652The syntax has grown over the years and sometimes it might be confusing.
3653Unfortunately, backward compatibility prevents cleaning up mistakes
3654made in the definition of the syntax.
3655.Pp
3656.Em !!! WARNING !!!
3657.Pp
3658Misconfiguring the firewall can put your computer in an unusable state,
3659possibly shutting down network services and requiring console access to
3660regain control of it.
3661.Pp
3662Incoming packet fragments diverted by
3663.Cm divert
3664are reassembled before delivery to the socket.
3665The action used on those packet is the one from the
3666rule which matches the first fragment of the packet.
3667.Pp
3668Packets diverted to userland, and then reinserted by a userland process
3669may lose various packet attributes.
3670The packet source interface name
3671will be preserved if it is shorter than 8 bytes and the userland process
3672saves and reuses the sockaddr_in
3673(as does
3674.Xr natd 8 ) ;
3675otherwise, it may be lost.
3676If a packet is reinserted in this manner, later rules may be incorrectly
3677applied, making the order of
3678.Cm divert
3679rules in the rule sequence very important.
3680.Pp
3681Dummynet drops all packets with IPv6 link-local addresses.
3682.Pp
3683Rules using
3684.Cm uid
3685or
3686.Cm gid
3687may not behave as expected.
3688In particular, incoming SYN packets may
3689have no uid or gid associated with them since they do not yet belong
3690to a TCP connection, and the uid/gid associated with a packet may not
3691be as expected if the associated process calls
3692.Xr setuid 2
3693or similar system calls.
3694.Pp
3695Rule syntax is subject to the command line environment and some patterns
3696may need to be escaped with the backslash character
3697or quoted appropriately.
3698.Pp
3699Due to the architecture of
3700.Xr libalias 3 ,
3701ipfw nat is not compatible with the TCP segmentation offloading (TSO).
3702Thus, to reliably nat your network traffic, please disable TSO
3703on your NICs using
3704.Xr ifconfig 8 .
3705.Pp
3706ICMP error messages are not implicitly matched by dynamic rules
3707for the respective conversations.
3708To avoid failures of network error detection and path MTU discovery,
3709ICMP error messages may need to be allowed explicitly through static
3710rules.
3711.Pp
3712Rules using
3713.Cm call
3714and
3715.Cm return
3716actions may lead to confusing behaviour if ruleset has mistakes,
3717and/or interaction with other subsystems (netgraph, dummynet, etc.) is used.
3718One possible case for this is packet leaving
3719.Nm
3720in subroutine on the input pass, while later on output encountering unpaired
3721.Cm return
3722first.
3723As the call stack is kept intact after input pass, packet will suddenly
3724return to the rule number used on input pass, not on output one.
3725Order of processing should be checked carefully to avoid such mistakes.
3726