2 .\" $FreeBSD: src/sbin/ipfw/ipfw.8,v 1.63.2.33 2003/02/04 01:36:02 brueffer Exp $
3 .\" $DragonFly: src/sbin/ipfw/ipfw.8,v 1.20 2008/11/23 21:55:52 swildner Exp $
10 .Nd IP firewall and traffic shaper control program
25 .Brq Cm delete | zero | resetlog
30 .Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ...
34 .Ar number Cm to Ar number
36 .Cm set swap Ar number number
41 .Cm state show Oo Ar rulenum Oc
43 .Cm state add rule Ar rulenum proto src:port dst:port Oo state-options Oc
45 .Cm state delete Ar rulenum
55 .Brq Cm delete | list | show
63 .Ar macro Ns Op = Ns Ar value
71 utility is the user interface for controlling the
77 .Bd -ragged -offset XXXX
79 ipfw is a controlling utility for ipfw/ipacct facilities for FreeBSD 2.0 which
80 released in November, 1994. This manual page documentation is for the ipfw3 of
81 DragonflyBSD since Feb 2015. This version of
83 is rewrited for DragonflyBSD and it is not fully compatible with ipfw in
84 FreeBSD. The differences between the two are listed in Section
85 .Sx IPFW3 ENHANCEMENTS ,
86 which you are encouraged to read to revise older rulesets and possibly
87 write them more efficiently.
96 numbered from 1 to 65535.
99 from a number of different places in the protocol stack
100 (depending on the source and destination of the packet,
103 is invoked multiple times on the same packet).
104 The packet passed to the firewall is compared
105 against each of the rules in the firewall
107 When a match is found, the action corresponding to the
108 matching rule is performed.
110 Depending on the action and certain system settings, packets
111 can be reinjected into the firewall at some rule after the
112 matching one for further processing.
116 ruleset always includes a
118 rule (numbered 65535) which cannot be modified,
119 and matches all packets.
120 The action associated with the
126 depending on how the kernel is configured.
128 If the ruleset includes one or more rules with the
136 behaviour, i.e. upon a match it will create dynamic rules matching
137 the exact parameters (addresses and ports) of the matching packet.
139 These dynamic rules, which have a limited lifetime, are checked
140 at the first occurrence of a
145 rule, and are typically used to open the firewall on-demand to
146 legitimate traffic only.
148 .Sx STATEFUL FIREWALL
151 Sections below for more information on the stateful behaviour of
154 All rules (including dynamic ones) have a few associated counters:
155 a packet count, a byte count, a log count and a timestamp
156 indicating the time of the last match.
157 Counters can be displayed or reset with
161 Rules can be added with the
163 command; deleted individually or in groups with the
165 command, and globally with the
167 command; displayed, optionally with the content of the
173 Finally, counters can be reset with the
179 Also, each rule belongs to one of 32 different
183 commands to atomically manipulate sets, such as enable,
184 disable, swap sets, move all rules in a set to another
185 one, delete all rules in a set. These can be useful to
186 install temporary configurations, or to test them.
189 for more information on
192 The following options are available:
193 .Bl -tag -width indent
195 While listing, show counter values.
198 command just implies this option.
200 When entering or showing rules, print them in compact form,
201 i.e. without the optional "ip " string
202 when this does not carry any additional information.
204 While listing, show states in addition to static ones.
206 While listing, show states only without static ones.
208 While listing, if the
210 option was specified, also show expired dynamic rules.
212 Don't ask for confirmation for commands that can cause problems
215 If there is no tty associated with the process, this is implied.
217 Try to resolve addresses and service names in output.
219 While listing rules, show the
221 each rule belongs to.
222 If this flag is not specified, disabled rules will not be
225 While listing pipes, sort according to one of the four
226 counters (total or current packets or bytes).
228 While listing, show last match timestamp.
230 While listing, show last match timestamp in unix format.
232 With verbose information, it will like the ipfw in FreeBSD.
235 To ease configuration, rules can be put into a file which is
238 as shown in the last synopsis line.
242 The file will be read line by line and applied as arguments to the
246 Optionally, a preprocessor can be specified using
250 is to be piped through.
251 Useful preprocessors include
257 doesn't start with a slash
259 as its first character, the usual
261 name search is performed.
262 Care should be taken with this in environments where not all
263 file systems are mounted (yet) by the time
265 is being run (e.g. when they are mounted over NFS).
268 has been specified, optional
272 specifications can follow and will be passed on to the preprocessor.
273 This allows for flexible configuration files (like conditionalizing
274 them on the local hostname) and the use of macros to centralize
275 frequently required arguments like IP addresses.
282 commands are used to configure the traffic shaper, as shown in the
283 .Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION
286 If the world and the kernel get out of sync the
288 ABI may break, preventing you from being able to add any rules. This can
289 adversely affect the booting process. You can use
293 to temporarily disable the firewall to regain access to the network,
294 allowing you to fix the problem.
296 A packet is checked against the active ruleset in multiple places
297 in the protocol stack, under control of several sysctl variables.
298 These places and variables are shown below, and it is important to
299 have this picture in mind in order to design a correct ruleset.
300 .Bd -literal -offset indent
303 +------------>------------+
305 [ip_input] [ip_output] net.inet.ip.fw.enable=1
308 [ether_demux_oncpu] [ether_output_frame] net.link.ether.ipfw=1
313 As can be noted from the above picture, the number of
314 times the same packet goes through the firewall can
315 vary between 0 and 4 depending on packet source and
316 destination, and system configuration.
318 Note that as packets flow through the stack, headers can be
319 stripped or added to it, and so they may or may not be available
321 E.g., incoming packets will include the MAC header when
324 .Fn ether_demux_oncpu ,
325 but the same packets will have the MAC header stripped off when
330 Also note that each packet is always checked against the complete ruleset,
331 irrespective of the place where the check occurs, or the source of the packet.
332 If a rule contains some match patterns or actions which are not valid
333 for the place of invocation (e.g. trying to match a MAC header within
335 the match pattern will not match, but a
337 operator in front of such patterns
341 match on those packets.
342 It is thus the responsibility of
343 the programmer, if necessary, to write a suitable ruleset to
344 differentiate among the possible places.
346 rules can be useful here, as an example:
347 .Bd -literal -offset indent
348 # packets from ether_demux_oncpu
349 ipfw add 10 skipto 1000 all layer2 in
350 # packets from ip_input
351 ipfw add 10 skipto 2000 all not layer2 in
352 # packets from ip_output
353 ipfw add 10 skipto 3000 all not layer2 out
354 # packets from ether_output_frame
355 ipfw add 10 skipto 4000 all layer2 out
360 rules is the following:
361 .Bd -ragged -offset indent
363 .Op Cm set Ar set_number
364 .Op Cm prob Ar match_probability
367 .Op Cm log Op Cm logamount Ar number
371 where the body of the rule specifies which information is used
372 for filtering packets, among the following:
374 .Bl -tag -width "Source and dest. addresses and ports" -offset XXX -compact
375 .It Layer-2 header fields
379 .It Source and dest. addresses and ports
383 .It Transmit and receive interface
385 .It Misc. IP header fields
386 Version, type of service, datagram length, identification,
387 fragment flag (non-zero IP offset),
390 .It Misc. TCP header fields
391 TCP flags (SYN, FIN, ACK, RST, etc.),
392 sequence number, acknowledgment number,
398 When the packet can be associated with a local socket.
401 Note that some of the above information, e.g. source MAC or IP addresses and
402 TCP/UDP ports, could easily be spoofed, so filtering on those fields
403 alone might not guarantee the desired results.
404 .Bl -tag -width indent
406 Each rule is associated with a
408 in the range 1..65535, with the latter reserved for the
411 Rules are checked sequentially by rule number.
412 Multiple rules can have the same number, in which case they are
413 checked (and listed) according to the order in which they have
415 If a rule is entered without specifying a number, the kernel will
416 assign one in such a way that the rule becomes the last one
420 Automatic rule numbers are assigned by incrementing the last
421 non-default rule number by the value of the sysctl variable
422 .Ar net.inet.ip.fw.autoinc_step
423 which defaults to 100.
424 If this is not possible (e.g. because we would go beyond the
425 maximum allowed rule number), the number of the last
426 non-default value is used instead.
427 .It Cm set Ar set_number
428 Each rule is associated with a
430 in the range 0..31, with the latter reserved for the
433 Sets can be individually disabled and enabled, so this parameter
434 is of fundamental importance for atomic ruleset manipulation.
435 It can be also used to simplify deletion of groups of rules.
436 If a rule is entered without specifying a set number,
438 .It Cm prob Ar match_probability
439 A match is only declared with the specified probability
440 (floating point number between 0 and 100).
441 This can be useful for a number of applications such as
442 random packet drop or
445 to simulate the effect of multiple paths leading to out-of-order
447 .It Cm log Op Cm logamount Ar number
448 When a packet matches a rule with the
450 keyword, a message will be
456 The logging only occurs if the sysctl variable
457 .Em net.inet.ip.fw.verbose
459 (which is the default when the kernel is compiled with
460 .Dv IPFIREWALL_VERBOSE )
461 and the number of packets logged so far for that
462 particular rule does not exceed the
467 is specified, the limit is taken from the sysctl variable
468 .Em net.inet.ip.fw.verbose_limit .
469 In both cases, a value of 0 removes the logging limit.
471 Once the limit is reached, logging can be re-enabled by
472 clearing the logging counter or the packet counter for that entry, see the
477 A rule can be associated with one of the following actions, which
478 will be executed when the packet matches the body of the rule.
479 .Bl -tag -width indent
481 Allow packets that match rule.
482 The search terminates.
484 Checks the packet against the dynamic ruleset.
485 If a match is found, execute the action associated with
486 the rule which generated this dynamic rule, otherwise
487 move to the next rule.
490 rules do not have a body.
493 rule is found, the dynamic ruleset is checked at the first
499 Update counters for all packets that match rule.
500 The search continues with the next rule.
502 Discard packets that match this rule.
503 The search terminates.
504 .It Cm forward Ar ipaddr Oo Ar :port Oc Oo Ar forward-option Oc
505 Change the next-hop on matching packets to
507 which can be an IP address in dotted quad format or a host name.
508 The search terminates if this rule matches.
512 it can be is a local addresses, then matching packets will be forwarded to
514 (or the port number in the packet if one is not specified in the rule)
515 on the local machine.
519 is not a local address, then the port number
520 (if specified) is ignored, and the packet will be
521 forwarded to the remote address, using the route as found in
522 the local routing table for that IP. and use comma to separate
523 multiple ip addresses.
525 forward-option can be 'round-robin' or 'sticky'. 'sticky' is calculated based on
526 the src ip addresses, and if no forward-option, by default it will be 'random'.
530 rule will not match layer-2 packets (those received
538 action does not change the contents of the packet at all.
539 In particular, the destination address remains unmodified, so
540 packets forwarded to another system will usually be rejected by that system
541 unless there is a matching rule on that system to capture them.
542 For packets forwarded locally,
543 the local address of the socket will be
544 set to the original destination address of the packet.
547 entry look rather weird but is intended for
548 use with transparent proxy servers.
549 .It Cm pipe Ar pipe_nr
553 (for bandwidth limitation, delay, etc.).
555 .Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION
556 Section for further information.
557 The search terminates; however, on exit from the pipe and if
561 .Em net.inet.ip.fw.one_pass
562 is not set, the packet is passed again to the firewall code
563 starting from the next rule.
564 .It Cm queue Ar queue_nr
568 (for bandwidth limitation using WF2Q+).
570 Discard packets that match this rule, and if the
571 packet is a TCP packet, try to send a TCP reset (RST) notice.
572 The search terminates.
573 .It Cm skipto Ar number
574 Skip all subsequent rules numbered less than
576 The search continues with the first rule numbered
580 Send a copy of packets matching this rule to the
584 The search terminates and the original packet is accepted
588 .It Cm unreach Ar code
589 Discard packets that match this rule, and try to send an ICMP
590 unreachable notice with code
594 is a number from 0 to 255, or one of these aliases:
595 .Cm net , host , protocol , port ,
596 .Cm needfrag , srcfail , net-unknown , host-unknown ,
597 .Cm isolated , net-prohib , host-prohib , tosnet ,
598 .Cm toshost , filter-prohib , host-precedence
600 .Cm precedence-cutoff .
601 The search terminates.
604 The body of a rule contains zero or more patterns (such as
605 specific source and destination addresses or ports,
606 protocol options, incoming or outgoing interfaces, etc.)
607 that the packet must match in order to be recognised.
608 In general, the patterns are connected by (implicit)
610 operators -- i.e. all must match in order for the
612 Individual patterns can be prefixed by the
614 operator to reverse the result of the match, as in
616 .Dl "ipfw add 100 allow ip from not 1.2.3.4"
618 Additionally, sets of alternative match patterns
620 can be constructed by putting the patterns in
621 lists enclosed between parentheses ( ) or braces { }, and
626 .Dl "ipfw add 100 allow ip from { x or not y or z } to any"
628 Only one level of parentheses is allowed.
629 Beware that most shells have special meanings for parentheses
630 or braces, so it is advisable to put a backslash \\ in front of them
631 to prevent such interpretations.
633 The body of a rule must in general include a source and destination
637 can be used in various places to specify that the content of
638 a required field is irrelevant.
640 The rule body has the following format:
641 .Bd -ragged -offset indent
642 .Op Ar proto Cm from Ar src Cm to Ar dst
646 The first part (protocol from src to dst) is for backward
651 any match pattern (including MAC headers, IPv4 protocols,
652 addresses and ports) can be specified in the
656 Rule fields have the following meaning:
657 .Bl -tag -width indent
658 .It Ar proto : protocol | Cm { Ar protocol Cm or ... }
659 An IPv4 protocol (or an
661 with multiple protocols) specified by number or name
662 (for a complete list see
663 .Pa /etc/protocols ) .
668 keywords mean any protocol will match.
669 .It Ar src No and Ar dst : ip-address | Cm { Ar ip-address Cm or ... } Op Ar ports
674 containing one or more of them,
675 optionally followed by
679 An address (or set of addresses) specified in one of the following
680 ways, optionally preceded by a
683 .Bl -tag -width indent
685 matches any IP address.
687 matches any IP address configured on an interface in the system.
688 The address list is evaluated at the time the packet is
690 .It Ar numeric-ip | hostname
691 Matches a single IPv4 address, specified as dotted-quad or a hostname.
692 Hostnames are resolved at the time the rule is added to the firewall list.
693 .It Ar addr Ns / Ns Ar masklen
694 Matches all addresses with base
696 (specified as a dotted quad or a hostname)
700 As an example, 1.2.3.4/25 will match
701 all IP numbers from 1.2.3.0 to 1.2.3.127 .
702 .It Ar addr Ns / Ns Ar masklen Ns Cm { Ns Ar num,num,... Ns Cm }
703 Matches all addresses with base address
705 (specified as a dotted quad or a hostname)
706 and whose last byte is in the list between braces { } .
707 Note that there must be no spaces between braces, commas and
711 field is used to limit the size of the set of addresses,
712 and can have any value between 24 and 32.
714 As an example, an address specified as 1.2.3.4/24{128,35,55,89}
715 will match the following IP addresses:
717 1.2.3.128 1.2.3.35 1.2.3.55 1.2.3.89 .
719 This format is particularly useful to handle sparse address sets
720 within a single rule. Because the matching occurs using a
721 bitmask, it takes constant time and dramatically reduces
722 the complexity of rulesets.
723 .It Ar addr Ns : Ns Ar mask
724 Matches all addresses with base
726 (specified as a dotted quad or a hostname)
729 specified as a dotted quad.
730 As an example, 1.2.3.4/255.0.255.0 will match
732 We suggest to use this form only for non-contiguous
733 masks, and resort to the
734 .Ar addr Ns / Ns Ar masklen
735 format for contiguous masks, which is more compact and less
738 .It Ar ports : Oo Cm not Oc Bro Ar port | port Ns \&- Ns Ar port Ns Brc Op , Ns Ar ...
739 For protocols which support port numbers (such as TCP and UDP), optional
741 may be specified as one or more ports or port ranges, separated
742 by commas but no spaces, and an optional
747 notation specifies a range of ports (including boundaries).
751 may be used instead of numeric port values.
752 The length of the port list is limited to 30 ports or ranges,
753 though one can specify larger ranges by using an
761 can be used to escape the dash
763 character in a service name (from a shell, the backslash must be
764 typed twice to avoid the shell itself interpreting it as an escape
767 .Dl "ipfw add count tcp ftp\e\e-data-ftp to any"
769 Fragmented packets which have a non-zero offset (i.e. not the first
770 fragment) will never match a rule which has one or more port
774 option for details on matching fragmented packets.
776 .Ss RULE OPTIONS (MATCH PATTERNS)
777 Additional match patterns can be used within
778 rules. Zero or more of these so-called
780 can be present in a rule, optionally prefixed by the
782 operand, and possibly grouped into
785 The following match patterns can be used (listed in alphabetical order):
786 .Bl -tag -width indent
787 .It Cm dst-ip Ar ip address
788 Matches IP packets whose destination IP is one of the address(es)
789 specified as argument.
790 .It Cm dst-port Ar source ports
791 Matches IP packets whose destination port is one of the port(s)
792 specified as argument.
794 Matches TCP packets that have the RST or ACK bits set.
796 Matches packets that are fragments and not the first
797 fragment of an IP datagram. Note that these packets will not have
798 the next protocol header (e.g. TCP, UDP) so options that look into
799 these headers cannot match.
801 Matches all TCP or UDP packets sent by or received for a
805 may be specified by name or number.
806 .It Cm icmptypes Ar types
807 Matches ICMP packets whose ICMP type is in the list
809 The list may be specified as any combination of ranges or
810 individual types separated by commas.
811 The supported ICMP types are:
815 destination unreachable
827 time-to-live exceeded
841 and address mask reply
844 Matches incoming or outgoing packets, respectively.
848 are mutually exclusive (in fact,
853 Matches IP packets whose
858 Matches IP packets whose total length, including header and data, is
861 .It Cm ipoptions Ar spec
862 Matches packets whose IP header contains the comma separated list of
865 The supported IP options are:
868 (strict source route),
870 (loose source route),
872 (record packet route) and
875 The absence of a particular option may be denoted
878 .It Cm ipprecedence Ar precedence
879 Matches IP packets whose precedence field is equal to
882 Matches IP packets whose
884 field contains the comma separated list of
885 service types specified in
887 The supported IP types of service are:
890 .Pq Dv IPTOS_LOWDELAY ,
892 .Pq Dv IPTOS_THROUGHPUT ,
894 .Pq Dv IPTOS_RELIABILITY ,
896 .Pq Dv IPTOS_MINCOST ,
899 The absence of a particular type may be denoted
903 Matches IP packets whose time to live is
905 .It Cm ipversion Ar ver
906 Matches IP packets whose IP version field is
909 Upon a match, the firewall will create a state, whose
910 default behaviour is to match bidirectional traffic between
911 source and destination IP/port using the same protocol.
912 The rule has a limited lifetime (controlled by a set of
914 variables), and the lifetime is refreshed every time a matching
916 the state can be manually created/deleted using the ipfw3 utility.
918 Matches only layer2 packets, i.e. those passed to
921 .Fn ether_demux_oncpu
923 .Fn ether_output_frame .
924 .It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N
925 The firewall will only allow
927 connections with the same
928 set of parameters as specified in the rule.
930 of source and destination addresses and ports can be
932 .It Cm { MAC | mac } Ar dst-mac src-mac
933 Match packets with a given
937 addresses, specified as the
939 keyword (matching any MAC address), or six groups of hex digits
941 and optionally followed by a mask indicating how many bits are
944 .Dl "MAC 10:20:30:40:50:60/33 any"
946 Note that the order of MAC addresses (destination first,
948 the same as on the wire, but the opposite of the one used for
950 .It Cm mac-type Ar mac-type
951 Matches packets whose Ethernet Type field
952 corresponds to one of those specified as argument.
954 is specified in the same way as
956 (i.e. one or more comma-separated single values or ranges).
957 You can use symbolic names for known values such as
958 .Em vlan , ipv4, ipv6 .
959 Values can be entered as decimal or hexadecimal (if prefixed by 0x),
960 and they are always printed as hexadecimal (unless the
962 option is used, in which case symbolic resolution will be attempted).
963 .It Cm proto Ar protocol
964 Matches packets with the corresponding IPv4 protocol.
965 .It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar ipno | Ar any
966 Matches packets received, transmitted or going through,
967 respectively, the interface specified by exact name
971 by IP address, or through some interface.
975 keyword causes the interface to always be checked.
982 then only the receive or transmit interface (respectively)
984 By specifying both, it is possible to match packets based on
985 both receive and transmit interface, e.g.:
987 .Dl "ipfw add deny ip out recv ed0 xmit ed1"
991 interface can be tested on either incoming or outgoing packets,
994 interface can only be tested on outgoing packets.
1003 A packet may not have a receive or transmit interface: packets
1004 originating from the local host have no receive interface,
1005 while packets destined for the local host have no transmit
1008 Matches TCP packets that have the SYN bit set but no ACK bit.
1009 This is the short form of
1010 .Dq Li tcpflags\ syn,!ack .
1011 .It Cm src-ip Ar ip-address
1012 Matches IP packets whose source IP is one of the address(es)
1013 specified as argument.
1014 .It Cm src-port Ar ports
1015 Matches IP packets whose source port is one of the port(s)
1016 specified as argument.
1017 .It Cm tcpack Ar ack
1019 Match if the TCP header acknowledgment number field is set to
1021 .It Cm tcpflags Ar spec
1023 Match if the TCP header contains the comma separated list of
1026 The supported TCP flags are:
1035 The absence of a particular flag may be denoted
1038 A rule which contains a
1040 specification can never match a fragmented packet which has
1044 option for details on matching fragmented packets.
1045 .It Cm tcpseq Ar seq
1047 Match if the TCP header sequence number field is set to
1049 .It Cm tcpwin Ar win
1051 Match if the TCP header window field is set to
1053 .It Cm tcpoptions Ar spec
1055 Match if the TCP header contains the comma separated list of
1056 options specified in
1058 The supported TCP options are:
1061 (maximum segment size),
1063 (tcp window advertisement),
1067 (rfc1323 timestamp) and
1069 (rfc1644 t/tcp connection count).
1070 The absence of a particular option may be denoted
1074 Match all TCP or UDP packets sent by or received for a
1078 may be matched by name or identification number.
1081 Each rule belongs to one of 32 different
1084 Set 31 is reserved for the default rule.
1086 By default, rules are put in set 0, unless you use the
1088 attribute when entering a new rule.
1089 Sets can be individually and atomically enabled or disabled,
1090 so this mechanism permits an easy way to store multiple configurations
1091 of the firewall and quickly (and atomically) switch between them.
1092 The command to enable/disable sets is
1093 .Bd -ragged -offset indent
1095 .Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ...
1102 sections can be specified.
1103 Command execution is atomic on all the sets specified in the command.
1104 By default, all sets are enabled.
1106 When you disable a set, its rules behave as if they do not exist
1107 in the firewall configuration, with only one exception:
1108 .Bd -ragged -offset indent
1109 dynamic rules created from a rule before it had been disabled
1110 will still be active until they expire. In order to delete
1111 dynamic rules you have to explicitly delete the parent rule
1112 which generated them.
1115 The set number of rules can be changed with the command
1116 .Bd -ragged -offset indent
1119 .Brq Cm rule Ar rule-number | old-set
1123 Also, you can atomically swap two rulesets with the command
1124 .Bd -ragged -offset indent
1126 .Cm set swap Ar first-set second-set
1131 Section on some possible uses of sets of rules.
1132 .Sh STATEFUL FIREWALL
1133 Stateful operation is a way for the firewall to dynamically
1134 create rules for specific flows when packets that
1135 match a given pattern are detected. Support for stateful
1136 operation comes through the
1137 .Cm check-state , keep-state
1144 Dynamic rules are created when a packet matches a
1148 rule, causing the creation of a
1150 rule which will match all and only packets with
1154 .Em src-ip/src-port dst-ip/dst-port
1159 are used here only to denote the initial match addresses, but they
1160 are completely equivalent afterwards).
1161 Dynamic rules will be checked at the first
1162 .Cm check-state, keep-state
1165 occurrence, and the action performed upon a match will be the same
1166 as in the parent rule.
1168 Note that no additional attributes other than protocol and IP addresses
1169 and ports are checked on dynamic rules.
1171 The typical use of dynamic rules is to keep a closed firewall configuration,
1172 but let the first TCP SYN packet from the inside network install a
1173 dynamic rule for the flow so that packets belonging to that session
1174 will be allowed through the firewall:
1176 .Dl "ipfw add check-state"
1177 .Dl "ipfw add allow tcp from my-subnet to any keep-state"
1178 .Dl "ipfw add deny tcp "
1180 A similar approach can be used for UDP, where an UDP packet coming
1181 from the inside will install a dynamic rule to let the response through
1184 .Dl "ipfw add check-state"
1185 .Dl "ipfw add allow udp from my-subnet keep-state"
1186 .Dl "ipfw add deny udp "
1188 Dynamic rules expire after some time, which depends on the status
1189 of the flow and the setting of some
1193 .Sx SYSCTL VARIABLES
1195 For TCP sessions, dynamic rules can be instructed to periodically
1196 send keepalive packets to refresh the state of the rule when it is
1201 for more examples on how to use dynamic rules.
1202 .Sh TRAFFIC SHAPER (DUMMYNET) CONFIGURATION
1204 is also the user interface for the
1209 operates by first using the firewall to classify packets and divide them into
1211 using any match pattern that can be used in
1214 Depending on local policies, a flow can contain packets for a single
1215 TCP connection, or from/to a given host, or entire subnet, or a
1218 Packets belonging to the same flow are then passed to either of two
1219 different objects, which implement the traffic regulation:
1220 .Bl -hang -offset XXXX
1222 A pipe emulates a link with given bandwidth, propagation delay,
1223 queue size and packet loss rate.
1224 Packets are queued in front of the pipe as they come out from the classifier,
1225 and then transferred to the pipe according to the pipe's parameters.
1228 is an abstraction used to implement the WF2Q+
1229 (Worst-case Fair Weighted Fair Queueing) policy, which is
1230 an efficient variant of the WFQ policy.
1232 The queue associates a
1234 and a reference pipe to each flow, and then all backlogged (i.e.,
1235 with packets queued) flows linked to the same pipe share the pipe's
1236 bandwidth proportionally to their weights.
1237 Note that weights are not priorities; a flow with a lower weight
1238 is still guaranteed to get its fraction of the bandwidth even if a
1239 flow with a higher weight is permanently backlogged.
1243 can be used to set hard limits to the bandwidth that a flow can use, whereas
1245 can be used to determine how different flow share the available bandwidth.
1251 configuration commands are the following:
1252 .Bd -ragged -offset indent
1253 .Cm pipe Ar number Cm config Ar pipe-configuration
1255 .Cm queue Ar number Cm config Ar queue-configuration
1258 The following parameters can be configured for a pipe:
1260 .Bl -tag -width indent -compact
1261 .It Cm bw Ar bandwidth
1262 Bandwidth, measured in
1265 .Brq Cm bit/s | Byte/s .
1268 A value of 0 (default) means unlimited bandwidth.
1269 The unit must immediately follow the number, as in
1271 .Dl "ipfw pipe 1 config bw 300Kbit/s"
1273 .It Cm delay Ar ms-delay
1274 Propagation delay, measured in milliseconds.
1275 The value is rounded to the next multiple of the clock tick
1276 (typically 10ms, but it is a good practice to run kernels
1278 .Cd "options HZ=1000"
1280 the granularity to 1ms or less).
1281 Default value is 0, meaning no delay.
1284 The following parameters can be configured for a queue:
1286 .Bl -tag -width indent -compact
1287 .It Cm pipe Ar pipe_nr
1288 Connects a queue to the specified pipe.
1289 Multiple queues (with the same or different weights) can be connected to
1290 the same pipe, which specifies the aggregate rate for the set of queues.
1292 .It Cm weight Ar weight
1293 Specifies the weight to be used for flows matching this queue.
1294 The weight must be in the range 1..100, and defaults to 1.
1297 Finally, the following parameters can be configured for both
1300 .Bl -tag -width XXXX -compact
1301 .It Cm buckets Ar hash-table-size
1302 Specifies the size of the hash table used for storing the
1304 Default value is 64 controlled by the
1307 .Em net.inet.ip.dummynet.hash_size ,
1308 allowed range is 16 to 65536.
1310 .It Cm mask Ar mask-specifier
1311 Packets sent to a given pipe or queue by an
1313 rule can be further classified into multiple flows, each of which is then
1317 A flow identifier is constructed by masking the IP addresses,
1318 ports and protocol types as specified with the
1320 options in the configuration of the pipe or queue.
1321 For each different flow identifier, a new pipe or queue is created
1322 with the same parameters as the original object, and matching packets
1327 are used, each flow will get the same bandwidth as defined by the pipe,
1330 are used, each flow will share the parent's pipe bandwidth evenly
1331 with other flows generated by the same queue (note that other queues
1332 with different weights might be connected to the same pipe).
1334 Available mask specifiers are a combination of one or more of the following:
1336 .Cm dst-ip Ar mask ,
1337 .Cm src-ip Ar mask ,
1338 .Cm dst-port Ar mask ,
1339 .Cm src-port Ar mask ,
1344 where the latter means all bits in all fields are significant.
1347 When a packet is dropped by a dummynet queue or pipe, the error
1348 is normally reported to the caller routine in the kernel, in the
1349 same way as it happens when a device queue fills up. Setting this
1350 option reports the packet as successfully delivered, which can be
1351 needed for some experimental setups where you want to simulate
1352 loss or congestion at a remote router.
1355 This option is always on,
1359 .It Cm plr Ar packet-loss-rate
1362 .Ar packet-loss-rate
1363 is a floating-point number between 0 and 1, with 0 meaning no
1364 loss, 1 meaning 100% loss.
1365 The loss rate is internally represented on 31 bits.
1367 .It Cm queue Brq Ar slots | size Ns Cm Kbytes
1372 Default value is 50 slots, which
1373 is the typical queue size for Ethernet devices.
1374 Note that for slow speed links you should keep the queue
1375 size short or your traffic might be affected by a significant
1377 E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit
1378 or 20s of queue on a 30Kbit/s pipe.
1379 Even worse effect can result if you get packets from an
1380 interface with a much larger MTU, e.g. the loopback interface
1381 with its 16KB packets.
1383 .It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p
1384 Make use of the RED (Random Early Detection) queue management algorithm.
1389 point numbers between 0 and 1 (0 not included), while
1393 are integer numbers specifying thresholds for queue management
1394 (thresholds are computed in bytes if the queue has been defined
1395 in bytes, in slots otherwise).
1398 also supports the gentle RED variant (gred).
1401 variables can be used to control the RED behaviour:
1402 .Bl -tag -width indent
1403 .It Em net.inet.ip.dummynet.red_lookup_depth
1404 specifies the accuracy in computing the average queue
1405 when the link is idle (defaults to 256, must be greater than zero)
1406 .It Em net.inet.ip.dummynet.red_avg_pkt_size
1407 specifies the expected average packet size (defaults to 512, must be
1409 .It Em net.inet.ip.dummynet.red_max_pkt_size
1410 specifies the expected maximum packet size, only used when queue
1411 thresholds are in bytes (defaults to 1500, must be greater than zero).
1415 Here are some important points to consider when designing your
1419 Remember that you filter both packets going
1423 Most connections need packets going in both directions.
1425 Remember to test very carefully.
1426 It is a good idea to be near the console when doing this.
1427 If you cannot be near the console,
1428 use an auto-recovery script such as the one in
1429 .Pa /usr/share/examples/ipfw/change_rules.sh .
1431 Don't forget the loopback interface.
1436 There are circumstances where fragmented datagrams are unconditionally
1438 TCP packets are dropped if they do not contain at least 20 bytes of
1439 TCP header, UDP packets are dropped if they do not contain a full 8
1440 byte UDP header, and ICMP packets are dropped if they do not contain
1441 4 bytes of ICMP header, enough to specify the ICMP type, code, and
1443 These packets are simply logged as
1445 since there may not be enough good data in the packet to produce a
1446 meaningful log entry.
1448 Another type of packet is unconditionally dropped, a TCP packet with a
1449 fragment offset of one.
1450 This is a valid packet, but it only has one use, to try
1451 to circumvent firewalls.
1452 When logging is enabled, these packets are
1453 reported as being dropped by rule -1.
1455 If you are logged in over a network, loading the
1459 is probably not as straightforward as you would think.
1460 I recommend the following command line:
1461 .Bd -literal -offset indent
1462 kldload /boot/modules/ipfw3.ko && \e
1463 ipfw add 32000 allow ip
1466 Along the same lines, doing an
1467 .Bd -literal -offset indent
1471 in similar surroundings is also a bad idea.
1475 filter list may not be modified if the system security level
1476 is set to 3 or higher
1479 for information on system security levels).
1481 .Sh PACKET DIVERSION
1484 socket bound to the specified port will receive all packets
1485 diverted to that port.
1486 If no socket is bound to the destination port, or if the kernel
1487 wasn't compiled with divert socket support, the packets are
1489 .Sh SYSCTL VARIABLES
1492 variables controls the behaviour of the firewall and
1495 These are shown below together with their default value
1496 (but always check with the
1498 command what value is actually in use) and meaning:
1499 .Bl -tag -width indent
1500 .It Em net.filters_default_to_accept : No 0
1501 If set prior to loading the
1503 kernel module, the filter will default to allowing all packets through.
1504 If not set the filter will likely default to not allowing any packets through.
1505 .It Em net.inet.ip.dummynet.expire : No 1
1506 Lazily delete dynamic pipes/queue once they have no pending traffic.
1507 You can disable this by setting the variable to 0, in which case
1508 the pipes/queues will only be deleted when the threshold is reached.
1509 .It Em net.inet.ip.dummynet.hash_size : No 64
1510 Default size of the hash table used for dynamic pipes/queues.
1511 This value is used when no
1513 option is specified when configuring a pipe/queue.
1514 .It Em net.inet.ip.dummynet.max_chain_len : No 16
1515 Target value for the maximum number of pipes/queues in a hash bucket.
1517 .Cm max_chain_len*hash_size
1518 is used to determine the threshold over which empty pipes/queues
1519 will be expired even when
1520 .Cm net.inet.ip.dummynet.expire=0 .
1521 .It Em net.inet.ip.dummynet.red_lookup_depth : No 256
1522 .It Em net.inet.ip.dummynet.red_avg_pkt_size : No 512
1523 .It Em net.inet.ip.dummynet.red_max_pkt_size : No 1500
1524 Parameters used in the computations of the drop probability
1525 for the RED algorithm.
1526 .It Em net.inet.ip.fw.autoinc_step : No 100
1527 Delta between rule numbers when auto-generating them.
1528 The value must be in the range 1..1000.
1529 .It Em net.inet.ip.fw.curr_dyn_buckets : Em net.inet.ip.fw.dyn_buckets
1530 The current number of buckets in the hash table for dynamic rules
1532 .It Em net.inet.ip.fw.debug : No 1
1533 Controls debugging messages produced by
1535 .It Em net.inet.ip.fw.dyn_buckets : No 256
1536 The number of buckets in the hash table for dynamic rules.
1537 Must be a power of 2, up to 65536.
1538 It only takes effect when all dynamic rules have expired, so you
1539 are advised to use a
1541 command to make sure that the hash table is resized.
1542 .It Em net.inet.ip.fw.dyn_count : No 3
1543 Current number of dynamic rules
1545 .It Em net.inet.ip.fw.dyn_keepalive : No 1
1546 Enables generation of keepalive packets for
1548 rules on TCP sessions. A keepalive is generated to both
1549 sides of the connection every 5 seconds for the last 20
1550 seconds of the lifetime of the rule.
1551 .It Em net.inet.ip.fw.dyn_max : No 8192
1552 Maximum number of dynamic rules.
1553 When you hit this limit, no more dynamic rules can be
1554 installed until old ones expire.
1555 .It Em net.inet.ip.fw.dyn_ack_lifetime : No 300
1556 .It Em net.inet.ip.fw.dyn_syn_lifetime : No 20
1557 .It Em net.inet.ip.fw.dyn_fin_lifetime : No 1
1558 .It Em net.inet.ip.fw.dyn_rst_lifetime : No 1
1559 .It Em net.inet.ip.fw.dyn_udp_lifetime : No 5
1560 .It Em net.inet.ip.fw.dyn_short_lifetime : No 30
1561 These variables control the lifetime, in seconds, of dynamic
1563 Upon the initial SYN exchange the lifetime is kept short,
1564 then increased after both SYN have been seen, then decreased
1565 again during the final FIN exchange or when a RST is received.
1567 .Em dyn_fin_lifetime
1569 .Em dyn_rst_lifetime
1570 must be strictly lower than 5 seconds, the period of
1571 repetition of keepalives. The firewall enforces that.
1572 .It Em net.inet.ip.fw.enable : No 1
1573 Enables the firewall.
1574 Setting this variable to 0 lets you run your machine without
1575 firewall even if compiled in.
1576 .It Em net.inet.ip.fw.one_pass : No 1
1577 When set, the packet exiting from the
1579 pipe is not passed though the firewall again.
1580 Otherwise, after a pipe action, the packet is
1581 reinjected into the firewall at the next rule.
1583 Note: layer 2 packets coming out of a pipe
1584 are never reinjected in the firewall irrespective of the
1585 value of this variable.
1586 .It Em net.inet.ip.fw.verbose : No 1
1587 Enables verbose messages.
1588 .It Em net.inet.ip.fw.verbose_limit : No 0
1589 Limits the number of messages produced by a verbose firewall.
1590 .It Em net.link.ether.ipfw : No 0
1591 Controls whether layer-2 packets are passed to
1595 .Sh IPFW3 ENHANCEMENTS
1596 This Section lists the features that have been introduced in
1597 .Nm ipfw3 of DragonflyBSD
1598 which were not present in
1599 .Nm ipfw of FreeBSD.
1600 We list them in order of the potential impact that they can
1601 have in writing your rulesets.
1602 You might want to consider using these features in order to
1603 write your rulesets in a more efficient way.
1604 .Bl -tag -width indent
1610 In ipfw of DragonflyBSD, the state links to the rule which created it.
1611 all packets will be filtered during the action 'check-state'.
1612 And states can be manipulated by using the ipfw utility.
1614 .Dl "ipfw state add rule 1000 udp 192.168.1.100:0 8.8.8.8:53 expiry 600"
1618 There are far too many possible uses of
1620 so this Section will only give a small set of examples.
1621 .Ss BASIC PACKET FILTERING
1622 This command adds an entry which denies all tcp packets from
1623 .Em cracker.evil.org
1624 to the telnet port of
1626 from being forwarded by the host:
1628 .Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet"
1630 This one disallows any connection from the entire cracker's
1633 .Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org"
1635 A first and efficient way to limit access (not using dynamic rules)
1636 is the use of the following rules:
1638 .Dl "ipfw add allow tcp established"
1639 .Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup"
1640 .Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup"
1642 .Dl "ipfw add deny tcp "
1644 The first rule will be a quick match for normal TCP packets,
1645 but it will not match the initial SYN packet, which will be
1648 rules only for selected source/destination pairs.
1649 All other SYN packets will be rejected by the final
1653 If you administer one or more subnets, you can take advantage of the
1655 syntax to specify address sets and or-blocks and write extremely
1656 compact rulesets which selectively enable services to blocks
1657 of clients, as below:
1659 .Dl "goodguys=\*q{ 10.1.2.0/24{20,35,66,18} or 10.2.3.0/28{6,3,11} }\*q"
1660 .Dl "badguys=\*q10.1.2.0/24{8,38,60}\*q"
1662 .Dl "ipfw add allow ip from ${goodguys} to any"
1663 .Dl "ipfw add deny ip from ${badguys} to any"
1664 .Dl "... normal policies ..."
1668 syntax would require a separate rule for each IP in the above
1671 In order to protect a site from flood attacks involving fake
1672 TCP packets, it is safer to use dynamic rules:
1674 .Dl "ipfw add check-state"
1675 .Dl "ipfw add deny tcp established"
1676 .Dl "ipfw add allow tcp from my-net to any setup keep-state"
1678 This will let the firewall install dynamic rules only for
1679 those connection which start with a regular SYN packet coming
1680 from the inside of our network.
1681 Dynamic rules are checked when encountering the first
1688 rule should usually be placed near the beginning of the
1689 ruleset to minimize the amount of work scanning the ruleset.
1690 Your mileage may vary.
1692 To limit the number of connections a user can open
1693 you can use the following type of rules:
1695 .Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10"
1696 .Dl "ipfw add allow tcp to me setup limit src-addr 4"
1698 The former (assuming it runs on a gateway) will allow each host
1699 on a /24 network to open at most 10 TCP connections.
1700 The latter can be placed on a server to make sure that a single
1701 client does not use more than 4 simultaneous connections.
1704 stateful rules can be subject to denial-of-service attacks
1705 by a SYN-flood which opens a huge number of dynamic rules.
1706 The effects of such attacks can be partially limited by
1709 variables which control the operation of the firewall.
1711 Here is a good usage of the
1713 command to see accounting records and timestamp information:
1717 or in short form without timestamps:
1721 which is equivalent to:
1725 Next rule diverts all incoming packets from 192.168.2.0/24
1726 to divert port 5000:
1728 .Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in
1730 The following rules show some of the applications of
1734 for simulations and the like.
1736 This rule drops random incoming packets with a probability
1739 .Dl "ipfw add prob 0.05 deny ip in"
1741 A similar effect can be achieved making use of dummynet pipes:
1743 .Dl "ipfw add pipe 10 ip "
1744 .Dl "ipfw pipe 10 config plr 0.05"
1746 We can use pipes to artificially limit bandwidth, e.g. on a
1747 machine acting as a router, if we want to limit traffic from
1748 local clients on 192.168.2.0/24 we do:
1750 .Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out"
1751 .Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes"
1753 note that we use the
1755 modifier so that the rule is not used twice.
1756 Remember in fact that
1758 rules are checked both on incoming and outgoing packets.
1760 Should we want to simulate a bidirectional link with bandwidth
1761 limitations, the correct way is the following:
1763 .Dl "ipfw add pipe 1 ip out"
1764 .Dl "ipfw add pipe 2 ip "
1765 .Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes"
1766 .Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes"
1768 The above can be very useful, e.g. if you want to see how
1769 your fancy Web page will look for a residential user who
1770 is connected only through a slow link.
1771 You should not use only one pipe for both directions, unless
1772 you want to simulate a half-duplex medium (e.g. AppleTalk,
1774 It is not necessary that both pipes have the same configuration,
1775 so we can also simulate asymmetric links.
1777 Should we want to verify network performance with the RED queue
1778 management algorithm:
1780 .Dl "ipfw add pipe 1 ip "
1781 .Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1"
1783 Another typical application of the traffic shaper is to
1784 introduce some delay in the communication.
1785 This can significantly affect applications which do a lot of Remote
1786 Procedure Calls, and where the round-trip-time of the
1787 connection often becomes a limiting factor much more than
1790 .Dl "ipfw add pipe 1 ip "
1791 .Dl "ipfw add pipe 2 ip "
1792 .Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s"
1793 .Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s"
1795 Per-flow queueing can be useful for a variety of purposes.
1796 A very simple one is counting traffic:
1798 .Dl "ipfw add pipe 1 tcp "
1799 .Dl "ipfw add pipe 1 udp "
1800 .Dl "ipfw add pipe 1 ip "
1801 .Dl "ipfw pipe 1 config mask all"
1803 The above set of rules will create queues (and collect
1804 statistics) for all traffic.
1805 Because the pipes have no limitations, the only effect is
1806 collecting statistics.
1807 Note that we need 3 rules, not just the last one, because
1810 tries to match IP packets it will not consider ports, so we
1811 would not see connections on separate ports as different
1814 A more sophisticated example is limiting the outbound traffic
1815 on a net with per-host limits, rather than per-network limits:
1817 .Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out"
1818 .Dl "ipfw add pipe 2 ip to 192.168.2.0/24 in"
1819 .Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
1820 .Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
1822 To add a set of rules atomically, e.g. set 18:
1824 .Dl "ipfw disable set 18"
1825 .Dl "ipfw add NN set 18 ... # repeat as needed"
1826 .Dl "ipfw enable set 18"
1828 To delete a set of rules atomically the command is simply:
1830 .Dl "ipfw delete set 18"
1832 To test a ruleset and disable it and regain control if something goes wrong:
1834 .Dl "ipfw disable set 18"
1835 .Dl "ipfw add NN set 18 ... # repeat as needed"
1836 .Dl "ipfw enable set 18 ; echo done; sleep 30 && ipfw disable set 18"
1838 Here if everything goes well, you press control-C before the "sleep"
1839 terminates, and your ruleset will be left active. Otherwise, e.g. if
1840 you cannot access your box, the ruleset will be disabled after
1841 the sleep terminates thus restoring the previous situation.
1859 utility first appeared in
1864 Stateful extensions were introduced in
1867 was introduced in Summer 2002.
1869 .An Ugen J. S. Antsilevich ,
1870 .An Poul-Henning Kamp ,
1876 API based upon code written by
1882 traffic shaper supported by Akamba Corp.
1884 The syntax has grown over the years and sometimes it might be confusing.
1885 Unfortunately, backward compatibility prevents cleaning up mistakes
1886 made in the definition of the syntax.
1890 Misconfiguring the firewall can put your computer in an unusable state,
1891 possibly shutting down network services and requiring console access to
1892 regain control of it.
1894 Incoming packet fragments diverted by
1898 are reassembled before delivery to the socket.
1899 The action used on those packet is the one from the
1900 rule which matches the first fragment of the packet.
1902 Packets that match a
1904 rule should not be immediately accepted, but should continue
1905 going through the rule list.
1906 This may be fixed in a later version.
1908 Packets diverted to userland, and then reinserted by a userland process
1911 will lose various packet attributes, including their source interface.
1912 If a packet is reinserted in this manner, later rules may be incorrectly
1913 applied, making the order of
1915 rules in the rule sequence very important.