xref: /freebsd/sbin/ipfw/ipfw.8 (revision 42c159fe388a3765f69860c84183700af37aca8a)
1.\"
2.\" $FreeBSD$
3.\"
4.Dd May 31, 2001
5.Dt IPFW 8
6.Os
7.Sh NAME
8.Nm ipfw
9.Nd IP firewall and traffic shaper control program
10.Sh SYNOPSIS
11.Nm
12.Op Fl q
13.Oo
14.Fl p Ar preproc
15.Oo Fl D
16.Ar macro Ns Op = Ns Ar value
17.Oc
18.Op Fl U Ar macro
19.Oc
20.Ar pathname
21.Nm
22.Op Fl f | q
23.Cm flush
24.Nm
25.Op Fl q
26.Brq Cm zero | resetlog | delete
27.Op Ar number ...
28.Nm
29.Op Fl s Op Ar field
30.Op Fl adeftN
31.Brq Cm list | show
32.Op Ar number ...
33.Nm
34.Op Fl q
35.Cm add
36.Op Ar number
37.Ar rule-body
38.Nm
39.Cm pipe
40.Ar number
41.Cm config
42.Ar pipe-config-options
43.Nm
44.Cm pipe
45.Brq Cm delete | list | show
46.Op Ar number ...
47.Nm
48.Cm queue
49.Ar number
50.Cm config
51.Ar queue-config-options
52.Nm
53.Cm queue
54.Brq Cm delete | list | show
55.Op Ar number ...
56.Sh DESCRIPTION
57.Nm
58is the user interface for controlling the
59.Xr ipfirewall 4
60and the
61.Xr dummynet 4
62traffic shaper in
63.Fx .
64.Pp
65A firewall configuration is made of a list of numbered rules,
66which is scanned for each incoming or outgoing IP packet
67until a match is found and
68the relevant action is performed.
69Depending on the action and certain system settings, packets
70can be reinjected into the firewall at the rule after the
71matching one for further processing.
72All rules apply to all interfaces, so it is responsibility
73of the system administrator to write the ruleset in such a
74way as to minimize the number of checks.
75.Pp
76A configuration always includes a
77.Em DEFAULT
78rule (numbered 65535) which cannot be modified,
79and matches all packets.
80The action associated with the default rule can be either
81.Cm deny
82or
83.Cm allow
84depending on how the kernel is configured.
85.Pp
86If the ruleset includes one or more rules with the
87.Cm keep-state
88or
89.Cm limit
90option, then
91.Nm
92assumes a
93.Em stateful
94behaviour, i.e. upon a match it will create dynamic rules matching
95the exact parameters (addresses and ports) of the matching packet.
96.Pp
97These dynamic rules, which have a limited lifetime, are checked
98at the first occurrence of a
99.Cm check-state
100or
101.Cm keep-state
102rule, and are typically used to open the firewall on-demand to
103legitimate traffic only.
104See the
105.Sx RULE FORMAT
106and
107.Sx EXAMPLES
108sections below for more information on the stateful behaviour of
109.Nm .
110.Pp
111All rules (including dynamic ones) have a few associated counters:
112a packet count, a byte count, a log count and a timestamp
113indicating the time of the last match.
114Counters can be displayed or reset with
115.Nm
116commands.
117.Pp
118Rules can be added with the
119.Cm add
120command; deleted individually with the
121.Cm delete
122command, and globally with the
123.Cm flush
124command; displayed, optionally with the content of the
125counters, using the
126.Cm show
127and
128.Cm list
129commands.
130Finally, counters can be reset with the
131.Cm zero
132and
133.Cm resetlog
134commands.
135.Pp
136The following options are available:
137.Bl -tag -width indent
138.It Fl a
139While listing, show counter values.
140The
141.Cm show
142command just implies this option.
143.It Fl d
144While listing, show dynamic rules in addition to static ones.
145.It Fl e
146While listing, if the
147.Fl d
148option was specified, also show expired dynamic rules.
149.It Fl f
150Don't ask for confirmation for commands that can cause problems
151if misused,
152.No i.e. Cm flush .
153.Em Note ,
154if there is no tty associated with the process, this is implied.
155.It Fl q
156While
157.Cm add Ns ing ,
158.Cm zero Ns ing ,
159.Cm resetlog Ns ging
160or
161.Cm flush Ns ing ,
162be quiet about actions
163(implies
164.Fl f ) .
165This is useful for adjusting rules by executing multiple
166.Nm
167commands in a script
168(e.g.,
169.Ql sh\ /etc/rc.firewall ) ,
170or by processing a file of many
171.Nm
172rules,
173across a remote login session.
174If a
175.Cm flush
176is performed in normal (verbose) mode (with the default kernel
177configuration), it prints a message.
178Because all rules are flushed, the message cannot be delivered
179to the login session.
180This causes the remote login session to be closed and the
181remainder of the ruleset is not processed.
182Access to the console is required to recover.
183.It Fl t
184While listing, show last match timestamp.
185.It Fl N
186Try to resolve addresses and service names in output.
187.It Fl s Op Ar field
188While listing pipes, sort according to one of the four
189counters (total and current packets or bytes).
190.El
191.Pp
192To ease configuration, rules can be put into a file which is
193processed using
194.Nm
195as shown in the first synopsis line.
196An absolute
197.Ar pathname
198must be used.
199The file
200will be read line by line and applied as arguments to the
201.Nm
202utility.
203.Pp
204Optionally, a preprocessor can be specified using
205.Fl p Ar preproc
206where
207.Ar pathname
208is to be piped through.
209Useful preprocessors include
210.Xr cpp 1
211and
212.Xr m4 1 .
213If
214.Ar preproc
215doesn't start with a slash
216.Pq Ql /
217as its first character, the usual
218.Ev PATH
219name search is performed.
220Care should be taken with this in environments where not all
221filesystems are mounted (yet) by the time
222.Nm
223is being run (e.g. when they are mounted over NFS).
224Once
225.Fl p
226has been specified, optional
227.Fl D
228and
229.Fl U
230specifications can follow and will be passed on to the preprocessor.
231This allows for flexible configuration files (like conditionalizing
232them on the local hostname) and the use of macros to centralize
233frequently required arguments like IP addresses.
234.Pp
235The
236.Nm
237.Cm pipe
238commands are used to configure the traffic shaper, as shown in the
239.Sx TRAFFIC SHAPER CONFIGURATION
240section below.
241.Sh RULE FORMAT
242The
243.Nm
244rule format is the following:
245.Bd -ragged
246.Op Cm prob Ar match_probability
247.Ar action
248.Op Cm log Op Cm logamount Ar number
249.Ar proto
250.Cm from Ar src
251.Cm to Ar dst
252.Op Ar interface-spec
253.Op Ar options
254.Ed
255.Pp
256Each packet can be filtered based on the following information that is
257associated with it:
258.Pp
259.Bl -tag -width "Source and destination IP address" -offset indent -compact
260.It Protocol
261(TCP, UDP, ICMP, etc.)
262.It Source and destination IP address
263(possibly masked)
264.It Source and destination port
265(lists, ranges or masks)
266.It Direction
267(incoming or outgoing)
268.It Transmit and receive interface
269(by name or address)
270.It IP version
271.It IP type of service
272.It IP datagram length
273.It IP identification
274.It IP fragment flag
275(non-zero IP offset)
276.It IP time to live
277.It IP options
278.It TCP sequence number
279.It TCP acknowledgment number
280.It TCP flags
281(SYN, FIN, ACK, RST, etc.)
282.It TCP window
283.It TCP options
284.It ICMP types
285(for ICMP packets)
286.It User/group ID of the socket associated with the packet
287.El
288.Pp
289Note that it may be dangerous to filter on the source IP
290address or source TCP/UDP port because either or both could
291easily be spoofed.
292.Bl -tag -width indent
293.It Cm prob Ar match_probability
294A match is only declared with the specified probability
295(floating point number between 0 and 1).
296This can be useful for a number of applications such as
297random packet drop or
298(in conjunction with
299.Xr dummynet 4 )
300to simulate the effect of multiple paths leading to out-of-order
301packet delivery.
302.It Ar action :
303.Bl -tag -width indent
304.It Cm allow
305Allow packets that match rule.
306The search terminates.
307Aliases are
308.Cm pass ,
309.Cm permit
310and
311.Cm accept .
312.It Cm deny
313Discard packets that match this rule.
314The search terminates.
315.Cm drop
316is an alias for
317.Cm deny .
318.It Cm reject
319(Deprecated).
320Discard packets that match this rule, and try to send an ICMP
321host unreachable notice.
322The search terminates.
323.It Cm unreach Ar code
324Discard packets that match this rule, and try to send an ICMP
325unreachable notice with code
326.Ar code ,
327where
328.Ar code
329is a number from 0 to 255, or one of these aliases:
330.Cm net , host , protocol , port ,
331.Cm needfrag , srcfail , net-unknown , host-unknown ,
332.Cm isolated , net-prohib , host-prohib , tosnet ,
333.Cm toshost , filter-prohib , host-precedence
334or
335.Cm precedence-cutoff .
336The search terminates.
337.It Cm reset
338TCP packets only.
339Discard packets that match this rule, and try to send a TCP
340reset (RST) notice.
341The search terminates.
342.It Cm count
343Update counters for all packets that match rule.
344The search continues with the next rule.
345.It Cm check-state
346Checks the packet against the dynamic ruleset.
347If a match is found then the search terminates, otherwise
348we move to the next rule.
349If no
350.Cm check-state
351rule is found, the dynamic ruleset is checked at the first
352.Cm keep-state
353rule.
354.It Cm divert Ar port
355Divert packets that match this rule to the
356.Xr divert 4
357socket bound to port
358.Ar port .
359The search terminates.
360.It Cm tee Ar port
361Send a copy of packets matching this rule to the
362.Xr divert 4
363socket bound to port
364.Ar port .
365The search terminates and the original packet is accepted
366(but see section
367.Sx BUGS
368below).
369.It Cm fwd Ar ipaddr Ns Op , Ns Ar port
370Change the next-hop on matching packets to
371.Ar ipaddr ,
372which can be an IP address in dotted quad or a host name.
373If
374.Ar ipaddr
375is not a directly-reachable address, the route as found in
376the local routing table for that IP is used instead.
377If
378.Ar ipaddr
379is a local address, then on a packet matching a
380.Cm fwd
381rule,
382it will be diverted to
383.Ar port
384on the local machine, keeping the local address of the socket
385set to the original IP address the packet was destined for.
386This makes the
387.Xr netstat 1
388entry look rather weird but is intended for
389use with transparent proxy servers.
390If the IP is not a local address then the port number
391(if specified) is ignored.
392This will also map addresses when packets are
393generated locally.
394The search terminates if this rule matches.
395If the port number is not given then the port number in the
396packet is used, so that a packet for an external machine port
397Y would be forwarded to local port Y.
398The kernel must have been compiled with the
399.Dv IPFIREWALL_FORWARD
400option.
401Bridging interferes with forwarding of packets not destined
402to the local system as they bypass
403.Fn ip_input
404and
405.Fn ip_output
406where forwarding is implemented.
407The
408.Cm fwd
409action does not change the contents of the packet at all so
410packets forwarded to another system will usually be rejected by that system
411unless there is a matching rule on that system to capture them.
412.It Cm pipe Ar pipe_nr
413Pass packet to a
414.Xr dummynet 4
415.Dq pipe
416(for bandwidth limitation, delay, etc.).
417See the
418.Sx TRAFFIC SHAPER CONFIGURATION
419section for further information.
420The search terminates; however, on exit from the pipe and if
421the
422.Xr sysctl 8
423variable
424.Em net.inet.ip.fw.one_pass
425is not set, the packet is passed again to the firewall code
426starting from the next rule.
427.It Cm queue Ar queue_nr
428Pass packet to a
429.Xr dummynet 4
430.Dq queue
431(for bandwidth limitation using WF2Q).
432.It Cm skipto Ar number
433Skip all subsequent rules numbered less than
434.Ar number .
435The search continues with the first rule numbered
436.Ar number
437or higher.
438.El
439.It Cm log Op Cm logamount Ar number
440If the kernel was compiled with
441.Dv IPFIREWALL_VERBOSE ,
442then when a packet matches a rule with the
443.Cm log
444keyword a message will be
445logged to
446.Xr syslogd 8
447with a
448.Dv LOG_SECURITY
449facility.
450.Em Note :
451by default, they are appended to the
452.Pa /var/log/security
453file (see
454.Xr syslog.conf 5 ) .
455If the kernel was compiled with the
456.Dv IPFIREWALL_VERBOSE_LIMIT
457option, then by default logging will cease after the number
458of packets specified by the option are received for that
459particular chain entry, and
460.Em net.inet.ip.fw.verbose_limit
461will be set to that number.
462However, if
463.Cm logamount Ar number
464is used, that
465.Ar number
466will be the logging limit rather than
467.Em net.inet.ip.fw.verbose_limit ,
468where the value
469.Dq 0
470removes the logging limit.
471Logging may then be re-enabled by clearing the logging counter
472or the packet counter for that entry.
473.Pp
474Console logging and the log limit are adjustable dynamically
475through the
476.Xr sysctl 8
477interface in the MIB base of
478.Em net.inet.ip.fw .
479.It Ar proto
480An IP protocol specified by number or name (for a complete
481list see
482.Pa /etc/protocols ) .
483The
484.Cm ip
485or
486.Cm all
487keywords mean any protocol will match.
488.It Ar src No and Ar dst :
489.Cm any | me | Op Cm not
490.Aq Ar address Ns / Ns Ar mask
491.Op Ar ports
492.Pp
493Specifying
494.Cm any
495makes the rule match any IP address.
496.Pp
497Specifying
498.Cm me
499makes the rule match any IP address configured on an interface in the system.
500.Pp
501The
502.Aq Ar address Ns / Ns Ar mask
503may be specified as:
504.Bl -tag -width "ipno/bits"
505.It Ar ipno
506An IP number of the form 1.2.3.4.
507Only this exact IP number will match the rule.
508.It Ar ipno Ns / Ns Ar bits
509An IP number with a mask width of the form 1.2.3.4/24.
510In this case all IP numbers from 1.2.3.0 to 1.2.3.255 will match.
511.It Ar ipno Ns : Ns Ar mask
512An IP number with a mask of the form 1.2.3.4:255.255.240.0.
513In this case all IP numbers from 1.2.0.0 to 1.2.15.255 will match.
514.El
515.Pp
516The sense of the match can be inverted by preceding an address with the
517.Cm not
518modifier, causing all other addresses to be matched instead.
519This does not affect the selection of port numbers.
520.Pp
521With the TCP and UDP protocols, optional
522.Em ports
523may be specified as:
524.Bd -ragged -offset indent
525.Sm off
526.Brq Ar port | port No \&- Ar port | port : mask
527.Op , Ar port Op , Ar ...
528.Sm on
529.Ed
530.Pp
531The
532.Ql \&-
533notation specifies a range of ports (including boundaries).
534.Pp
535The
536.Ql \&:
537notation specifies a port and a mask, a match is declared if
538the port number in the packet matches the one in the rule,
539limited to the bits which are set in the mask.
540.Pp
541Service names (from
542.Pa /etc/services )
543may be used instead of numeric port values.
544A range may only be specified as the first value, and the
545length of the port list is limited to
546.Dv IP_FW_MAX_PORTS
547ports (as defined in
548.Pa /usr/src/sys/netinet/ip_fw.h ) .
549A backslash
550.Pq Ql \e
551can be used to escape the dash
552.Pq Ql -
553character in a service name:
554.Pp
555.Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any"
556.Pp
557Fragmented packets which have a non-zero offset (i.e. not the first
558fragment) will never match a rule which has one or more port
559specifications.
560See the
561.Cm frag
562option for details on matching fragmented packets.
563.It Ar interface-spec
564Some combinations of the following specifiers are allowed:
565.Bl -tag -width "via ipno"
566.It Cm in
567Only match incoming packets.
568.It Cm out
569Only match outgoing packets.
570.It Cm via Ar ifX
571Packet must be going through interface
572.Ar ifX .
573.It Cm via Ar if Ns Cm *
574Packet must be going through interface
575.Ar ifX ,
576where
577.Ar X
578is any unit number.
579.It Cm via any
580Packet must be going through
581.Em some
582interface.
583.It Cm via Ar ipno
584Packet must be going through the interface having IP address
585.Ar ipno .
586.El
587.Pp
588The
589.Cm via
590keyword causes the interface to always be checked.
591If
592.Cm recv
593or
594.Cm xmit
595is used instead of
596.Cm via ,
597then only the receive or transmit interface (respectively)
598is checked.
599By specifying both, it is possible to match packets based on
600both receive and transmit interface, e.g.:
601.Pp
602.Dl "ipfw add 100 deny ip from any to any out recv ed0 xmit ed1"
603.Pp
604The
605.Cm recv
606interface can be tested on either incoming or outgoing packets,
607while the
608.Cm xmit
609interface can only be tested on outgoing packets.
610So
611.Cm out
612is required (and
613.Cm in
614is invalid) whenever
615.Cm xmit
616is used.
617Specifying
618.Cm via
619together with
620.Cm xmit
621or
622.Cm recv
623is invalid.
624.Pp
625A packet may not have a receive or transmit interface: packets
626originating from the local host have no receive interface,
627while packets destined for the local host have no transmit
628interface.
629.It Ar options :
630.Bl -tag -width indent
631.It Cm keep-state
632Upon a match, the firewall will create a dynamic rule, whose
633default behaviour is to matching bidirectional traffic between
634source and destination IP/port using the same protocol.
635The rule has a limited lifetime (controlled by a set of
636.Xr sysctl 8
637variables), and the lifetime is refreshed every time a matching
638packet is found.
639.It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N
640The firewall will only allow
641.Ar N
642connections with the same
643set of parameters as specified in the rule.
644One or more
645of source and destination addresses and ports can be
646specified.
647.It Cm bridged
648Matches only bridged packets.
649This can be useful for multicast or broadcast traffic, which
650would otherwise pass through the firewall twice: once during
651bridging, and a second time when the packet is delivered to
652the local stack.
653.Pp
654Apart from a small performance penalty, this would be a problem
655when using
656.Em pipes
657because the same packet would be accounted for twice in terms
658of bandwidth, queue occupation, and also counters.
659.It Cm ipversion Ar ver
660Match if the IP header version is
661.Ar ver .
662.It Cm ipprecedence Ar precedence
663Match if the numeric value of IP datagram's precedence is equal to
664.Ar precedence .
665.It Cm iptos Ar spec
666Match if the IP header contains the comma separated list of
667service types specified in
668.Ar spec .
669The supported IP types of service are:
670.Pp
671.Cm lowdelay
672.Pq Dv IPTOS_LOWDELAY ,
673.Cm throughput
674.Pq Dv IPTOS_THROUGHPUT ,
675.Cm reliability
676.Pq Dv IPTOS_RELIABILITY ,
677.Cm mincost
678.Pq Dv IPTOS_MINCOST ,
679.Cm congestion
680.Pq Dv IPTOS_CE .
681The absence of a particular type may be denoted
682with a
683.Ql \&! .
684.It Cm iplen Ar len
685Match if the total length of a packet, including header and data, is
686.Ar len
687bytes.
688.It Cm ipid Ar id
689Match if the identification of IP datagram is
690.Ar id .
691.It Cm frag
692Match if the packet is a fragment and this is not the first
693fragment of the datagram.
694.Cm frag
695may not be used in conjunction with either
696.Cm tcpflags
697or TCP/UDP port specifications.
698.It Cm ipttl Ar ttl
699Match if the time to live of IP datagram is
700.Ar ttl .
701.It Cm ipoptions Ar spec
702Match if the IP header contains the comma separated list of
703options specified in
704.Ar spec .
705The supported IP options are:
706.Pp
707.Cm ssrr
708(strict source route),
709.Cm lsrr
710(loose source route),
711.Cm rr
712(record packet route) and
713.Cm ts
714(timestamp).
715The absence of a particular option may be denoted
716with a
717.Ql \&! .
718.It Cm tcpseq Ar seq
719TCP packets only.
720Match if the TCP header sequence number field is set to
721.Ar seq .
722.It Cm tcpack Ar ack
723TCP packets only.
724Match if the TCP header acknowledgment number field is set to
725.Ar ack .
726.It Cm tcpflags Ar spec
727TCP packets only.
728Match if the TCP header contains the comma separated list of
729flags specified in
730.Ar spec .
731The supported TCP flags are:
732.Pp
733.Cm fin ,
734.Cm syn ,
735.Cm rst ,
736.Cm psh ,
737.Cm ack
738and
739.Cm urg .
740The absence of a particular flag may be denoted
741with a
742.Ql \&! .
743A rule which contains a
744.Cm tcpflags
745specification can never match a fragmented packet which has
746a non-zero offset.
747See the
748.Cm frag
749option for details on matching fragmented packets.
750.It Cm established
751TCP packets only.
752Match packets that have the RST or ACK bits set.
753.It Cm setup
754TCP packets only.
755Match packets that have the SYN bit set but no ACK bit.
756This is the short form of
757.Dq Li tcpflags\ syn,!ack .
758.It Cm tcpwin Ar win
759TCP packets only.
760Match if the TCP header window field is set to
761.Ar win .
762.It Cm tcpoptions Ar spec
763TCP packets only.
764Match if the TCP header contains the comma separated list of
765options specified in
766.Ar spec .
767The supported TCP options are:
768.Pp
769.Cm mss
770(maximum segment size),
771.Cm window
772(tcp window advertisement),
773.Cm sack
774(selective ack),
775.Cm ts
776(rfc1323 timestamp) and
777.Cm cc
778(rfc1644 t/tcp connection count).
779The absence of a particular option may be denoted
780with a
781.Ql \&! .
782.It Cm icmptypes Ar types
783ICMP packets only.
784Match if the ICMP type is in the list
785.Ar types .
786The list may be specified as any combination of ranges or
787individual types separated by commas.
788The supported ICMP types are:
789.Pp
790echo reply
791.Pq Cm 0 ,
792destination unreachable
793.Pq Cm 3 ,
794source quench
795.Pq Cm 4 ,
796redirect
797.Pq Cm 5 ,
798echo request
799.Pq Cm 8 ,
800router advertisement
801.Pq Cm 9 ,
802router solicitation
803.Pq Cm 10 ,
804time-to-live exceeded
805.Pq Cm 11 ,
806IP header bad
807.Pq Cm 12 ,
808timestamp request
809.Pq Cm 13 ,
810timestamp reply
811.Pq Cm 14 ,
812information request
813.Pq Cm 15 ,
814information reply
815.Pq Cm 16 ,
816address mask request
817.Pq Cm 17
818and address mask reply
819.Pq Cm 18 .
820.It Cm uid Ar user
821Match all TCP or UDP packets sent by or received for a
822.Ar user .
823A
824.Ar user
825may be matched by name or identification number.
826.It Cm gid Ar group
827Match all TCP or UDP packets sent by or received for a
828.Ar group .
829A
830.Ar group
831may be matched by name or identification number.
832.El
833.El
834.Sh TRAFFIC SHAPER CONFIGURATION
835The
836.Nm
837utility is also the user interface for the
838.Xr dummynet 4
839traffic shaper.
840The shaper operates by dividing packets into
841.Em flows
842according to a user-specified mask on different fields
843of the IP header.
844Packets belonging to the same flow are then passed to two
845different objects, named
846.Em pipe
847or
848.Em queue .
849.Pp
850A
851.Em pipe
852emulates a link with given bandwidth, propagation delay,
853queue size and packet loss rate.
854Packets transit through the pipe according to its parameters.
855.Pp
856A
857.Em queue
858is an abstraction used to implement the WF2Q+ (Worst-case Fair Weighted Fair Queueing) policy.
859The queue associates to each flow a weight and a reference pipe.
860Then, all flows linked to the same pipe are scheduled at the
861rate fixed by the pipe according to the WF2Q+ policy.
862.Pp
863The
864.Nm
865pipe configuration format is the following:
866.Bd -ragged
867.Cm pipe Ar number Cm config
868.Op Cm bw Ar bandwidth | device
869.Op Cm delay Ar ms-delay
870.Oo
871.Cm queue
872.Brq Ar slots | size
873.Oc
874.Op Cm plr Ar loss-probability
875.Op Cm mask Ar mask-specifier
876.Op Cm buckets Ar hash-table-size
877.Oo
878.Cm red | gred
879.Sm off
880.Ar w_q No / Ar min_th No / Ar max_th No / Ar max_p
881.Sm on
882.Oc
883.Ed
884.Pp
885The
886.Nm
887queue configuration format is the following:
888.Bd -ragged
889.Cm queue Ar number Cm config
890.Op Cm pipe Ar pipe_nr
891.Op Cm weight Ar weight
892.Oo
893.Cm queue
894.Brq Ar slots | size
895.Oc
896.Op Cm plr Ar loss-probability
897.Op Cm mask Ar mask-specifier
898.Op Cm buckets Ar hash-table-size
899.Oo
900.Cm red | gred
901.Sm off
902.Ar w_q No / Ar min_th No / Ar max_th No / Ar max_p
903.Sm on
904.Oc
905.Ed
906.Pp
907The following parameters can be configured for a pipe:
908.Bl -tag -width indent
909.It Cm bw Ar bandwidth | device
910Bandwidth, measured in
911.Sm off
912.Op Cm K | M
913.Brq Cm bit/s | Byte/s .
914.Sm on
915.Pp
916A value of 0 (default) means unlimited bandwidth.
917The unit must follow immediately the number, as in
918.Pp
919.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes"
920.Pp
921If a device name is specified instead of a numeric
922value, then the transmit clock is supplied by the specified
923device.
924At the moment only the
925.Xr tun 4
926device supports this
927functionality, for use in conjunction with
928.Xr ppp 8 .
929.It Cm delay Ar ms-delay
930Propagation delay, measured in milliseconds.
931The value is rounded to the next multiple of the clock tick
932(typically 10ms, but it is a good practice to run kernels
933with
934.Dq "options HZ=1000"
935to reduce
936the granularity to 1ms or less).
937Default value is 0, meaning no delay.
938.It Cm queue Brq Ar slots | size Ns Cm Kbytes
939Queue size, in
940.Ar slots
941or
942.Cm KBytes .
943Default value is 50 slots, which
944is the typical queue size for Ethernet devices.
945Note that for slow speed links you should keep the queue
946size short or your traffic might be affected by a significant
947queueing delay.
948E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit
949or 20s of queue on a 30Kbit/s pipe.
950Even worse effect can result if you get packets from an
951interface with a much larger MTU, e.g. the loopback interface
952with its 16KB packets.
953.It Cm plr Ar packet-loss-rate
954Packet loss rate.
955Argument
956.Ar packet-loss-rate
957is a floating-point number between 0 and 1, with 0 meaning no
958loss, 1 meaning 100% loss.
959The loss rate is internally represented on 31 bits.
960.It Cm mask Ar mask-specifier
961The
962.Xr dummynet 4
963lets you to create per-flow queues.
964A flow identifier is constructed by masking the IP addresses,
965ports and protocol types as specified in the pipe configuration.
966Packets with the same identifier after masking fall into the
967same queue.
968Available mask specifiers are a combination of the following:
969.Cm dst-ip Ar mask ,
970.Cm src-ip Ar mask ,
971.Cm dst-port Ar mask ,
972.Cm src-port Ar mask ,
973.Cm proto Ar mask
974or
975.Cm all ,
976where the latter means all bits in all fields are significant.
977When used within a
978.Ar pipe
979configuration, each flow is assigned a rate equal
980to the rate of the pipe.
981When used within a
982.Ar queue
983configuration, each flow is assigned a weight equal to the
984weight of the queue, and all flows insisting on the same pipe
985share bandwidth proportionally to their weight.
986.It Cm buckets Ar hash-table-size
987Specifies the size of the hash table used for storing the
988various queues.
989Default value is 64 controlled by the
990.Xr sysctl 8
991variable
992.Em net.inet.ip.dummynet.hash_size ,
993allowed range is 16 to 1024.
994.It Cm pipe Ar pipe_nr
995Connects a queue to the specified pipe.
996Multiple queues (usually
997with different weights) can be connected to the same pipe, which
998specifies the aggregate rate for the set of queues.
999.It Cm weight Ar weight
1000Specifies the weight to be used for flows matching this queue.
1001The weight must be in the range 1..100, and defaults to 1.
1002.It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p
1003Make use of the RED (Random Early Detection) queue management algorithm.
1004.Ar w_q
1005and
1006.Ar max_p
1007are floating
1008point numbers between 0 and 1 (0 not included), while
1009.Ar min_th
1010and
1011.Ar max_th
1012are integer numbers specifying thresholds for queue management
1013(thresholds are computed in bytes if the queue has been defined
1014in bytes, in slots otherwise).
1015The
1016.Xr dummynet 4
1017also supports the gentle RED variant (gred).
1018Three
1019.Xr sysctl 8
1020variables can be used to control the RED behaviour:
1021.Bl -tag -width indent
1022.It Em net.inet.ip.dummynet.red_lookup_depth
1023specifies the accuracy in computing the average queue
1024when the link is idle (defaults to 256, must be greater than zero)
1025.It Em net.inet.ip.dummynet.red_avg_pkt_size
1026specifies the expected average packet size (defaults to 512, must be
1027greater than zero)
1028.It Em net.inet.ip.dummynet.red_max_pkt_size
1029specifies the expected maximum packet size, only used when queue
1030thresholds are in bytes (defaults to 1500, must be greater than zero).
1031.El
1032.El
1033.Sh CHECKLIST
1034Here are some important points to consider when designing your
1035rules:
1036.Bl -bullet
1037.It
1038Remember that you filter both packets going
1039.Cm in
1040and
1041.Cm out .
1042Most connections need packets going in both directions.
1043.It
1044Remember to test very carefully.
1045It is a good idea to be near the console when doing this.
1046If you cannot be near the console,
1047use an auto-recovery script such as the one in
1048.Pa /usr/share/examples/ipfw/change_rules.sh .
1049.It
1050Don't forget the loopback interface.
1051.El
1052.Sh FINE POINTS
1053.Bl -bullet
1054.It
1055There is one kind of packet that the firewall will always
1056discard, that is a TCP packet's fragment with a fragment offset of
1057one.
1058This is a valid packet, but it only has one use, to try
1059to circumvent firewalls.
1060When logging is enabled, these packets are
1061reported as being dropped by rule -1.
1062.It
1063If you are logged in over a network, loading the
1064.Xr kld 4
1065version of
1066.Nm
1067is probably not as straightforward as you would think.
1068I recommend the following command line:
1069.Bd -literal -offset indent
1070kldload /modules/ipfw.ko && \e
1071ipfw add 32000 allow ip from any to any
1072.Ed
1073.Pp
1074Along the same lines, doing an
1075.Bd -literal -offset indent
1076ipfw flush
1077.Ed
1078.Pp
1079in similar surroundings is also a bad idea.
1080.It
1081The
1082.Nm
1083filter list may not be modified if the system security level
1084is set to 3 or higher
1085(see
1086.Xr init 8
1087for information on system security levels).
1088.El
1089.Sh PACKET DIVERSION
1090A
1091.Xr divert 4
1092socket bound to the specified port will receive all packets
1093diverted to that port.
1094If no socket is bound to the destination port, or if the kernel
1095wasn't compiled with divert socket support, the packets are
1096dropped.
1097.Sh SYSCTL VARIABLES
1098A set of
1099.Xr sysctl 8
1100variables controls the behaviour of the firewall.
1101These are shown below together with their default value
1102(but always check with the
1103.Xr sysctl 8
1104command what value is actually in use) and meaning:
1105.Bl -tag -width indent
1106.It Em net.inet.ip.fw.debug : No 1
1107Controls debugging messages produced by
1108.Nm .
1109.It Em net.inet.ip.fw.one_pass : No 1
1110When set, the packet exiting from the
1111.Xr dummynet 4
1112pipe is not passed though the firewall again.
1113Otherwise, after a pipe action, the packet is
1114reinjected into the firewall at the next rule.
1115.It Em net.inet.ip.fw.verbose : No 1
1116Enables verbose messages.
1117.It Em net.inet.ip.fw.enable : No 1
1118Enables the firewall.
1119Setting this variable to 0 lets you run your machine without
1120firewall even if compiled in.
1121.It Em net.inet.ip.fw.verbose_limit : No 0
1122Limits the number of messages produced by a verbose firewall.
1123.It Em net.inet.ip.fw.dyn_buckets : No 256
1124.It Em net.inet.ip.fw.curr_dyn_buckets : No 256
1125The configured and current size of the hash table used to
1126hold dynamic rules.
1127This must be a power of 2.
1128The table can only be resized when empty, so in order to
1129resize it on the fly you will probably have to
1130.Cm flush
1131and reload the ruleset.
1132.It Em net.inet.ip.fw.dyn_count : No 3
1133Current number of dynamic rules
1134(read-only).
1135.It Em net.inet.ip.fw.dyn_max : No 1000
1136Maximum number of dynamic rules.
1137When you hit this limit, no more dynamic rules can be
1138installed until old ones expire.
1139.It Em net.inet.ip.fw.dyn_ack_lifetime : No 300
1140.It Em net.inet.ip.fw.dyn_syn_lifetime : No 20
1141.It Em net.inet.ip.fw.dyn_fin_lifetime : No 1
1142.It Em net.inet.ip.fw.dyn_rst_lifetime : No 1
1143.It Em net.inet.ip.fw.dyn_udp_lifetime : No 5
1144.It Em net.inet.ip.fw.dyn_short_lifetime : No 30
1145These variables control the lifetime, in seconds, of dynamic
1146rules.
1147Upon the initial SYN exchange the lifetime is kept short,
1148then increased after both SYN have been seen, then decreased
1149again during the final FIN exchange or when a RST
1150.El
1151.Sh EXAMPLES
1152This command adds an entry which denies all tcp packets from
1153.Em cracker.evil.org
1154to the telnet port of
1155.Em wolf.tambov.su
1156from being forwarded by the host:
1157.Pp
1158.Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet"
1159.Pp
1160This one disallows any connection from the entire crackers
1161network to my host:
1162.Pp
1163.Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org"
1164.Pp
1165A first and efficient way to limit access (not using dynamic rules)
1166is the use of the following rules:
1167.Pp
1168.Dl "ipfw add allow tcp from any to any established"
1169.Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup"
1170.Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup"
1171.Dl "..."
1172.Dl "ipfw add deny tcp from any to any"
1173.Pp
1174The first rule will be a quick match for normal TCP packets,
1175but it will not match the initial SYN packet, which will be
1176matched by the
1177.Cm setup
1178rules only for selected source/destination pairs.
1179All other SYN packets will be rejected by the final
1180.Cm deny
1181rule.
1182.Pp
1183In order to protect a site from flood attacks involving fake
1184TCP packets, it is safer to use dynamic rules:
1185.Pp
1186.Dl "ipfw add check-state"
1187.Dl "ipfw add deny tcp from any to any established"
1188.Dl "ipfw add allow tcp from my-net to any setup keep-state"
1189.Pp
1190This will let the firewall install dynamic rules only for
1191those connection which start with a regular SYN packet coming
1192from the inside of our network.
1193Dynamic rules are checked when encountering the first
1194.Cm check-state
1195or
1196.Cm keep-state
1197rule.
1198A
1199.Cm check-state
1200rule should be usually placed near the beginning of the
1201ruleset to minimize the amount of work scanning the ruleset.
1202Your mileage may vary.
1203.Pp
1204To limit the number of connections a user can open
1205you can use the following type of rules:
1206.Pp
1207.Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10"
1208.Dl "ipfw add allow tcp from any to me setup limit src-addr 4"
1209.Pp
1210The former (assuming it runs on a gateway) will allow each host
1211on a /24 network to open at most 10 TCP connections.
1212The latter can be placed on a server to make sure that a single
1213client does not use more than 4 simultaneous connections.
1214.Pp
1215.Em BEWARE :
1216stateful rules can be subject to denial-of-service attacks
1217by a SYN-flood which opens a huge number of dynamic rules.
1218The effects of such attacks can be partially limited by
1219acting on a set of
1220.Xr sysctl 8
1221variables which control the operation of the firewall.
1222.Pp
1223Here is a good usage of the
1224.Cm list
1225command to see accounting records and timestamp information:
1226.Pp
1227.Dl ipfw -at list
1228.Pp
1229or in short form without timestamps:
1230.Pp
1231.Dl ipfw -a list
1232.Pp
1233which is equivalent to:
1234.Pp
1235.Dl ipfw show
1236.Pp
1237Next rule diverts all incoming packets from 192.168.2.0/24
1238to divert port 5000:
1239.Pp
1240.Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in
1241.Pp
1242The following rules show some of the applications of
1243.Nm
1244and
1245.Xr dummynet 4
1246for simulations and the like.
1247.Pp
1248This rule drops random incoming packets with a probability
1249of 5%:
1250.Pp
1251.Dl "ipfw add prob 0.05 deny ip from any to any in"
1252.Pp
1253A similar effect can be achieved making use of dummynet pipes:
1254.Pp
1255.Dl "ipfw add pipe 10 ip from any to any"
1256.Dl "ipfw pipe 10 config plr 0.05"
1257.Pp
1258We can use pipes to artificially limit bandwidth, e.g. on a
1259machine acting as a router, if we want to limit traffic from
1260local clients on 192.168.2.0/24 we do:
1261.Pp
1262.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out"
1263.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes"
1264.Pp
1265note that we use the
1266.Cm out
1267modifier so that the rule is not used twice.
1268Remember in fact that
1269.Nm
1270rules are checked both on incoming and outgoing packets.
1271.Pp
1272Should we like to simulate a bidirectional link with bandwidth
1273limitations, the correct way is the following:
1274.Pp
1275.Dl "ipfw add pipe 1 ip from any to any out"
1276.Dl "ipfw add pipe 2 ip from any to any in"
1277.Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes"
1278.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes"
1279.Pp
1280The above can be very useful, e.g. if you want to see how
1281your fancy Web page will look for a residential user which
1282is connected only through a slow link.
1283You should not use only one pipe for both directions, unless
1284you want to simulate a half-duplex medium (e.g. AppleTalk,
1285Ethernet, IRDA).
1286It is not necessary that both pipes have the same configuration,
1287so we can also simulate asymmetric links.
1288.Pp
1289Should we like to verify network performance with the RED queue
1290management algorithm:
1291.Pp
1292.Dl "ipfw add pipe 1 ip from any to any"
1293.Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1"
1294.Pp
1295Another typical application of the traffic shaper is to
1296introduce some delay in the communication.
1297This can affect a lot applications which do a lot of Remote
1298Procedure Calls, and where the round-trip-time of the
1299connection often becomes a limiting factor much more than
1300bandwidth:
1301.Pp
1302.Dl "ipfw add pipe 1 ip from any to any out"
1303.Dl "ipfw add pipe 2 ip from any to any in"
1304.Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s"
1305.Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s"
1306.Pp
1307Per-flow queueing can be useful for a variety of purposes.
1308A very simple one is counting traffic:
1309.Pp
1310.Dl "ipfw add pipe 1 tcp from any to any"
1311.Dl "ipfw add pipe 1 udp from any to any"
1312.Dl "ipfw add pipe 1 ip from any to any"
1313.Dl "ipfw pipe 1 config mask all"
1314.Pp
1315The above set of rules will create queues (and collect
1316statistics) for all traffic.
1317Because the pipes have no limitations, the only effect is
1318collecting statistics.
1319Note that we need 3 rules, not just the last one, because
1320when
1321.Nm
1322tries to match IP packets it will not consider ports, so we
1323would not see connections on separate ports as different
1324ones.
1325.Pp
1326A more sophisticated example is limiting the outbound traffic
1327on a net with per-host limits, rather than per-network limits:
1328.Pp
1329.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out"
1330.Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in"
1331.Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
1332.Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
1333.Sh IMPLEMENTATION NOTES
1334The number of times a packet is processed by
1335.Nm
1336varies \(em basically,
1337.Nm
1338is invoked every time the kernel functions
1339.Fn ip_input ,
1340.Fn ip_output
1341and
1342.Fn bdg_forward
1343are invoked.
1344This means that packets are processed once for connections having
1345only one endpoint on the local host, twice for connections with
1346both endpoints on the local host, or for packet routed by the host
1347(acting as a gateway), and once for packets bridged by the host
1348(acting as a bridge).
1349.Sh SEE ALSO
1350.Xr cpp 1 ,
1351.Xr m4 1 ,
1352.Xr bridge 4 ,
1353.Xr divert 4 ,
1354.Xr dummynet 4 ,
1355.Xr ip 4 ,
1356.Xr ipfirewall 4 ,
1357.Xr protocols 5 ,
1358.Xr services 5 ,
1359.Xr init 8 ,
1360.Xr kldload 8 ,
1361.Xr reboot 8 ,
1362.Xr sysctl 8 ,
1363.Xr syslogd 8
1364.Sh BUGS
1365The syntax has grown over the years and it is not very clean.
1366.Pp
1367.Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!
1368.Pp
1369This program can put your computer in rather unusable state.
1370When using it for the first time, work on the console of the
1371computer, and do
1372.Em NOT
1373do anything you don't understand.
1374.Pp
1375When manipulating/adding chain entries, service and protocol names
1376are not accepted.
1377.Pp
1378Incoming packet fragments diverted by
1379.Cm divert
1380or
1381.Cm tee
1382are reassembled before delivery to the socket.
1383.Pp
1384Packets that match a
1385.Cm tee
1386rule should not be immediately accepted, but should continue
1387going through the rule list.
1388This may be fixed in a later version.
1389.Pp
1390Packets diverted to userland, and then reinserted by a userland process
1391(such as
1392.Xr natd 8 )
1393will lose various packet attributes, including their source interface.
1394If a packet is reinserted in this manner, later rules may be incorrectly
1395applied, making the order of
1396.Cm divert
1397rules in the rule sequence very important.
1398.Sh AUTHORS
1399.An Ugen J. S. Antsilevich ,
1400.An Poul-Henning Kamp ,
1401.An Alex Nash ,
1402.An Archie Cobbs ,
1403.An Luigi Rizzo .
1404.Pp
1405.An -nosplit
1406API based upon code written by
1407.An Daniel Boulet
1408for BSDI.
1409.Pp
1410Work on
1411.Xr dummynet 4
1412traffic shaper supported by Akamba Corp.
1413.Sh HISTORY
1414The
1415.Nm
1416utility first appeared in
1417.Fx 2.0 .
1418.Xr dummynet 4
1419was introduced in
1420.Fx 2.2.8 .
1421Stateful extensions were introduced in
1422.Fx 4.0 .
1423