6 .Nd IP firewall and traffic shaper control program
13 .Ar macro Ns Op = Ns Ar value
24 .En Cm zero | resetlog | delete
39 is the user interface for controlling the
43 Each incoming or outgoing packet is passed through the
46 If the host is acting as a gateway, packets forwarded by
47 the gateway are processed by
50 When the host is acting as a bridge, packets forwarded by
51 the bridge are processed by
55 A firewall configuration is made of a list of numbered rules,
56 which is scanned for each packet until a match is found and
57 the relevant action is performed.
58 Depending on the action and certain system settings, packets
59 can be reinjected into the firewall at the rule after the
60 matching one for further processing.
61 All rules apply to all interfaces, so it is responsibility
62 of the system administrator to write the ruleset in such a
63 way as to minimize the number of checks.
65 A configuration always includes a
67 rule (numbered 65535) which cannot be modified by the programmer
68 and always matches packets.
69 The action associated with the default rule can be either
73 depending on how the kernel is configured.
75 If the ruleset includes one or more rules with the
81 behaviour, i.e. upon a match will create dynamic rules matching
82 the exact parameters (addresses and ports) of the matching packet.
84 These dynamic rules, which have a limited lifetime, are checked
85 at the first occurrence of a
89 rule, and are typically used to open the firewall on-demand to
90 legitimate traffic only.
95 sections below for more information on the stateful behaviour of
98 All rules (including dynamic ones) have a few associated counters:
99 a packet count, a byte count, a log count and a timestamp
100 indicating the time of the last match.
101 Counters can be displayed or reset with
105 Rules can be added with the
107 command; deleted individually with the
109 command, and globally with the
111 command; displayed, optionally with the content of the
117 Finally, counters can be reset with the
123 The following options are available:
124 .Bl -tag -width indent
126 While listing, show counter values.
131 Don't ask for confirmation for commands that can cause problems
135 if there is no tty associated with the process, this is implied.
143 be quiet about actions
146 This is useful for adjusting rules by executing multiple
150 .Ql sh\ /etc/rc.firewall ) ,
151 or by processing a file of many
154 across a remote login session.
157 is performed in normal (verbose) mode (with the default kernel
158 configuration), it prints a message.
159 Because all rules are flushed, the message cannot be delivered
160 to the login session.
161 This causes the remote login session to be closed and the
162 remainder of the ruleset is not processed.
163 Access to the console is required to recover.
165 While listing, show last match timestamp.
167 Try to resolve addresses and service names in output.
170 To ease configuration, rules can be put into a file which is
173 as shown in the first synopsis line.
178 will be read line by line and applied as arguments to the
182 Optionally, a preprocessor can be specified using
186 is to be piped through.
187 Useful preprocessors include
193 doesn't start with a slash
195 as its first character, the usual
197 name search is performed.
198 Care should be taken with this in environments where not all
199 filesystems are mounted (yet) by the time
201 is being run (e.g. when they are mounted over NFS).
204 has been specified, optional
208 specifications can follow and will be passed on to the preprocessor.
209 This allows for flexible configuration files (like conditionalizing
210 them on the local hostname) and the use of macros to centralize
211 frequently required arguments like IP addresses.
215 rule format is the following:
217 .Op Cm prob Ar match_probability
219 .Op Cm log Op Cm logamount Ar number
223 .Op Ar interface-spec
227 Each packet can be filtered based on the following information that is
230 .Bl -tag -width "Source and destination IP address" -offset indent -compact
231 .It Transmit and receive interface
234 (incoming or outgoing)
235 .It Source and destination IP address
238 (TCP, UDP, ICMP, etc.)
239 .It Source and destination port
240 (lists, ranges or masks)
245 .It User ID of the socket associated with the packet
248 Note that it may be dangerous to filter on the source IP
249 address or source TCP/UDP port because either or both could
251 .Bl -tag -width indent
252 .It Cm prob Ar match_probability
253 A match is only declared with the specified probability
254 (floating point number between 0 and 1).
255 This can be useful for a number of applications such as
258 .Bl -tag -width indent
260 Allow packets that match rule.
261 The search terminates.
268 Discard packets that match this rule.
269 The search terminates.
275 Discard packets that match this rule, and try to send an ICMP
276 host unreachable notice.
277 The search terminates.
278 .It Cm unreach Ar code
279 Discard packets that match this rule, and try to send an ICMP
280 unreachable notice with code
284 is a number from 0 to 255, or one of these aliases:
285 .Cm net , host , protocol , port ,
286 .Cm needfrag , srcfail , net-unknown , host-unknown ,
287 .Cm isolated , net-prohib , host-prohib , tosnet ,
288 .Cm toshost , filter-prohib , host-precedence
290 .Cm precedence-cutoff .
291 The search terminates.
294 Discard packets that match this rule, and try to send a TCP
296 The search terminates.
298 Update counters for all packets that match rule.
299 The search continues with the next rule.
301 Checks the packet against the dynamic ruleset.
302 If a match is found then the search terminates, otherwise
303 we move to the next rule.
306 rule is found, the dynamic ruleset is checked at the first
309 .It Cm divert Ar port
310 Divert packets that match this rule to the
314 The search terminates.
316 Send a copy of packets matching this rule to the
320 The search terminates and the original packet is accepted
324 .It Cm fwd Ar ipaddr Ns Xo
327 Change the next-hop on matching packets to
329 which can be an IP address in dotted quad or a host name.
332 is not a directly-reachable address, the route as found in
333 the local routing table for that IP is used instead.
336 is a local address, then on a packet entering the system
337 from a remote host it will be diverted to
339 on the local machine, keeping the local address of the socket
340 set to the original IP address the packet was destined for.
341 This is intended for use with transparent proxy servers.
342 If the IP is not a local address then the port number
343 (if specified) is ignored and the rule only applies to packets
345 This will also map addresses to local ports when packets are
347 The search terminates if this rule matches.
348 If the port number is not given then the port number in the
349 packet is used, so that a packet for an external machine port
350 Y would be forwarded to local port Y.
351 The kernel must have been compiled with the
352 .Dv IPFIREWALL_FORWARD
354 .It Cm skipto Ar number
355 Skip all subsequent rules numbered less than
357 The search continues with the first rule numbered
361 .It Cm log Op Cm logamount Ar number
362 If the kernel was compiled with
363 .Dv IPFIREWALL_VERBOSE ,
364 then when a packet matches a rule with the
366 keyword a message will be
373 by default, they are appended to the
374 .Pa /var/log/system.log
376 .Xr syslog.conf 5 ) .
377 If the kernel was compiled with the
378 .Dv IPFIREWALL_VERBOSE_LIMIT
379 option, then by default logging will cease after the number
380 of packets specified by the option are received for that
381 particular chain entry, and
382 .Em net.inet.ip.fw.verbose_limit
383 will be set to that number.
385 .Cm logamount Ar number
388 will be the logging limit rather than
389 .Em net.inet.ip.fw.verbose_limit ,
392 removes the logging limit.
393 Logging may then be re-enabled by clearing the logging counter
394 or the packet counter for that entry.
396 Console logging and the log limit are adjustable dynamically
399 interface in the MIB base of
402 An IP protocol specified by number or name (for a complete
404 .Pa /etc/protocols ) .
409 keywords mean any protocol will match.
410 .It Ar src No and Ar dst :
411 .Cm any | me | Op Cm not
412 .Aq Ar address Ns / Ns Ar mask
417 makes the rule match any IP number.
421 makes the rule match any IP number configured on an interface in the system.
422 This is a computationally semi-expensive check which should be used with care.
425 .Aq Ar address Ns / Ns Ar mask
427 .Bl -tag -width "ipno/bits"
429 An IP number of the form 1.2.3.4.
430 Only this exact IP number will match the rule.
431 .It Ar ipno Ns / Ns Ar bits
432 An IP number with a mask width of the form 1.2.3.4/24.
433 In this case all IP numbers from 1.2.3.0 to 1.2.3.255 will match.
434 .It Ar ipno Ns : Ns Ar mask
435 An IP number with a mask of the form 1.2.3.4:255.255.240.0.
436 In this case all IP numbers from 1.2.0.0 to 1.2.15.255 will match.
439 The sense of the match can be inverted by preceding an address with the
441 modifier, causing all other addresses to be matched instead.
442 This does not affect the selection of port numbers.
444 With the TCP and UDP protocols, optional
447 .Bd -ragged -offset indent
451 .Ar port No \&- Ar port |
453 .Ec \&} Op , Ar port Op , Ar ...
459 notation specifies a range of ports (including boundaries).
463 notation specifies a port and a mask, a match is declared if
464 the port number in the packet matches the one in the rule,
465 limited to the bits which are set in the mask.
469 may be used instead of numeric port values.
470 A range may only be specified as the first value, and the
471 length of the port list is limited to
474 .Pa /usr/src/sys/netinet/ip_fw.h ) .
477 can be used to escape the dash
479 character in a service name:
481 .Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any"
483 Fragmented packets which have a non-zero offset (i.e. not the first
484 fragment) will never match a rule which has one or more port
488 option for details on matching fragmented packets.
489 .It Ar interface-spec
490 Some combinations of the following specifiers are allowed:
491 .Bl -tag -width "via ipno"
493 Only match incoming packets.
495 Only match outgoing packets.
497 Packet must be going through interface
499 .It Cm via Ar if Ns Cm *
500 Packet must be going through interface
506 Packet must be going through
510 Packet must be going through the interface having IP address
516 keyword causes the interface to always be checked.
523 then the only receive or transmit interface (respectively)
525 By specifying both, it is possible to match packets based on
526 both receive and transmit interface, e.g.:
528 .Dl "ipfw add 100 deny ip from any to any out recv ed0 xmit ed1"
532 interface can be tested on either incoming or outgoing packets,
535 interface can only be tested on outgoing packets.
551 A packet may not have a receive or transmit interface: packets
552 originating from the local host have no receive interface,
553 while packets destined for the local host have no transmit
556 .Bl -tag -width indent
557 .It Cm keep-state Op Ar method
558 Upon a match, the firewall will create a dynamic rule, whose
559 default behaviour is to matching bidirectional traffic between
560 source and destination IP/port using the same protocol.
561 The rule has a limited lifetime (controlled by a set of
563 variables), and the lifetime is refreshed every time a matching
566 The actual behaviour can be modified by specifying a different
568 although at the moment only the default one is specified.
570 Matches only bridged packets.
571 This can be useful for multicast or broadcast traffic, which
572 would otherwise pass through the firewall twice: once during
573 bridging, and a second time when the packet is delivered to
576 Match if the packet is a fragment and this is not the first
577 fragment of the datagram.
579 may not be used in conjunction with either
581 or TCP/UDP port specifications.
582 .It Cm ipoptions Ar spec
583 Match if the IP header contains the comma separated list of
586 The supported IP options are:
589 (strict source route),
591 (loose source route),
593 (record packet route) and
596 The absence of a particular option may be denoted
599 .It Cm tcpoptions Ar spec
600 Match if the TCP header contains the comma separated list of
603 The supported TCP options are:
606 (maximum segment size),
608 (tcp window advertisement),
612 (rfc1323 timestamp) and
614 (rfc1644 t/tcp connection count).
615 The absence of a particular option may be denoted
620 Match packets that have the RST or ACK bits set.
623 Match packets that have the SYN bit set but no ACK bit.
624 .It Cm tcpflags Ar spec
626 Match if the TCP header contains the comma separated list of
629 The supported TCP flags are:
638 The absence of a particular flag may be denoted
641 A rule which contains a
643 specification can never match a fragmented packet which has
647 option for details on matching fragmented packets.
648 .It Cm icmptypes Ar types
650 Match if the ICMP type is in the list
652 The list may be specified as any combination of ranges or
653 individual types separated by commas.
654 The supported ICMP types are:
658 destination unreachable
670 time-to-live exceeded
684 and address mask reply
687 Match all TCP or UDP packets sent by or received for a
691 may be matched by name or identification number.
695 Here are some important points to consider when designing your
699 Remember that you filter both packets going
703 Most connections need packets going in both directions.
705 Remember to test very carefully.
706 It is a good idea to be near the console when doing this.
707 If you cannot be near the console,
708 use an auto-recovery script.
710 Don't forget the loopback interface.
715 There is one kind of packet that the firewall will always
716 discard, that is a TCP packet's fragment with a fragment offset of
718 This is a valid packet, but it only has one use, to try
719 to circumvent firewalls.
720 When logging is enabled, these packets are
721 reported as being dropped by rule -1.
725 filter list may not be modified if the system security level
726 is set to 3 or higher
729 for information on system security levels).
734 socket bound to the specified port will receive all packets
735 diverted to that port.
736 If no socket is bound to the destination port, or if the kernel
737 wasn't compiled with divert socket support, the packets are
742 variables controls the behaviour of the firewall.
743 These are shown below together with their default value and
745 .Bl -tag -width indent
746 .It Em net.inet.ip.fw.debug : No 1
747 Controls debugging messages produced by
749 .It Em net.inet.ip.fw.verbose : No 1
750 Enables verbose messages.
751 .It Em net.inet.ip.fw.enable : No 1
752 Enables the firewall.
753 Setting this variable to 0 lets you run your machine without
754 firewall even if compiled in.
755 .It Em net.inet.ip.fw.verbose_limit : No 0
756 Limits the number of messages produced by a verbose firewall.
757 .It Em net.inet.ip.fw.dyn_buckets : No 256
758 .It Em net.inet.ip.fw.curr_dyn_buckets : No 256
759 The configured and current size of the hash table used to
761 This must be a power of 2.
762 The table can only be resized when empty, so in order to
763 resize it on the fly you will probably have to
765 and reload the ruleset.
766 .It Em net.inet.ip.fw.dyn_count : No 3
767 Current number of dynamic rules
769 .It Em net.inet.ip.fw.dyn_max : No 1000
770 Maximum number of dynamic rules.
771 When you hit this limit, no more dynamic rules can be
772 installed until old ones expire.
773 .It Em net.inet.ip.fw.dyn_ack_lifetime : No 300
774 .It Em net.inet.ip.fw.dyn_syn_lifetime : No 20
775 .It Em net.inet.ip.fw.dyn_fin_lifetime : No 20
776 .It Em net.inet.ip.fw.dyn_rst_lifetime : No 5
777 .It Em net.inet.ip.fw.dyn_short_lifetime : No 30
778 These variables control the lifetime, in seconds, of dynamic
780 Upon the initial SYN exchange the lifetime is kept short,
781 then increased after both SYN have been seen, then decreased
782 again during the final FIN exchange or when a RST
785 This command adds an entry which denies all tcp packets from
787 to the telnet port of
789 from being forwarded by the host:
791 .Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet"
793 This one disallows any connection from the entire crackers
796 .Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org"
798 A fast and efficient way to limit access (not using dynamic rules)
799 is the use of the following rules:
801 .Dl "ipfw add allow tcp from any to any established"
802 .Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup"
803 .Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup"
805 .Dl "ipfw add deny tcp from any to any"
807 The first rule will be a quick match for normal TCP packets,
808 but it will not match the initial SYN packet, which will be
811 rules only for selected source/destination pairs.
812 All other SYN packets will be rejected by the final
816 In order to protect a site from flood attacks involving fake
817 TCP packets, it is safer to use dynamic rules:
819 .Dl "ipfw add check-state"
820 .Dl "ipfw add deny tcp from any to any established"
821 .Dl "ipfw add allow tcp from my-net to any setup keep-state"
823 This will let the firewall install dynamic rules only for
824 those connection which start with a regular SYN packet coming
825 from the inside of our network.
826 Dynamic rules are checked when encountering the first
833 rule should be usually placed near the beginning of the
834 ruleset to minimize the amount of work scanning the ruleset.
835 Your mileage may vary.
838 stateful rules can be subject to denial-of-service attacks
839 by a SYN-flood which opens a huge number of dynamic rules.
840 The effects of such attacks can be partially limited by
843 variables which control the operation of the firewall.
845 Here is a good usage of the
847 command to see accounting records and timestamp information:
851 or in short form without timestamps:
855 Next rule diverts all incoming packets from 192.168.2.0/24
858 .Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in
873 The syntax has grown over the years and it is not very clean.
875 .Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!
877 This program can put your computer in rather unusable state.
878 When using it for the first time, work on the console of the
881 do anything you don't understand.
883 When manipulating/adding chain entries, service and protocol names
886 Incoming packet fragments diverted by
890 are reassembled before delivery to the socket.
894 rule should not be immediately accepted, but should continue
895 going through the rule list.
896 This may be fixed in a later version.
898 .An Ugen J. S. Antsilevich ,
899 .An Poul-Henning Kamp ,
905 API based upon code written by
911 utility first appeared in
913 Stateful extensions were introduced in
projects / apple / network_cmds.git / blob