1045 lines
28 KiB
Groff
1045 lines
28 KiB
Groff
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd July 20, 1996
|
|
.Dt IPFW 8
|
|
.Os FreeBSD
|
|
.Sh NAME
|
|
.Nm ipfw
|
|
.Nd controlling utility for IP firewall and traffic shaper
|
|
.Sh SYNOPSIS
|
|
.Nm ipfw
|
|
.Op Fl q
|
|
.Oo
|
|
.Fl p Ar preproc
|
|
.Op Fl D Ar macro Ns Op Ns =value
|
|
.Op Fl U Ar macro
|
|
.Oc
|
|
.Ar file
|
|
.Nm ipfw
|
|
.Oo
|
|
.Fl f
|
|
|
|
|
.Fl q
|
|
.Oc
|
|
flush
|
|
.Nm ipfw
|
|
.Oo
|
|
.Fl q
|
|
.Oc
|
|
{zero|resetlog|delete}
|
|
.Op Ar number ...
|
|
.Nm ipfw
|
|
.Op Fl s Op field
|
|
.Op Fl aftN
|
|
{list|show}
|
|
.Op Ar number ...
|
|
.Nm ipfw
|
|
.Oo
|
|
.Fl q
|
|
.Oc
|
|
add
|
|
.Op Ar number
|
|
.Ar rule-body
|
|
.Nm ipfw
|
|
pipe
|
|
.Ar number
|
|
config
|
|
.Ar pipe-config-options
|
|
.Nm ipfw
|
|
pipe {delete|list|show}
|
|
.Op Ar number ...
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is the user interface for controlling the IPFW firewall and
|
|
.Nm dummynet
|
|
traffic shaper in FreeBSD.
|
|
.Pp
|
|
Each incoming or outgoing packet is passed through the
|
|
.Nm
|
|
rules. In case a host is acting as a gateway, packets
|
|
forwarded by the gateway are processed by
|
|
.Nm
|
|
twice. In case a host is acting as a bridge, packets
|
|
forwarded by the bridge are processed by
|
|
.Nm
|
|
once.
|
|
.Pp
|
|
A firewall configuration is made of a list of numbered rules, which are
|
|
scanned for each packet until a match is
|
|
found and the relevant action is performed. Depending on the
|
|
action and certain system settings, packets can be reinjected
|
|
into the firewall at the rule after the matching one for further
|
|
processing. All rules apply to all interfaces, so it is
|
|
responsibility of the sysadmin to write the ruleset in such
|
|
a way to minimize the number of checks.
|
|
.Pp
|
|
A configuration always includes a
|
|
.Ar DEFAULT
|
|
rule (numbered 65535) which cannot be modified by the programmer
|
|
and always matches packets. The action associated with the
|
|
default rule can be either
|
|
.Ar deny
|
|
or
|
|
.Ar allow
|
|
depending on how the kernel is configured.
|
|
.Pp
|
|
If the ruleset includes one or more rules with the
|
|
.Ar keep-state
|
|
option, then
|
|
.Nm ipfw
|
|
assumes a
|
|
.Nm stateful
|
|
behaviour, i.e. upon a match
|
|
will create dynamic rules matching the exact parameters
|
|
(addresses and ports) of the matching packet.
|
|
.Pp
|
|
These dynamic rules, which have a limited lifetime,
|
|
are checked at the first occurrence of a
|
|
.Ar check-state
|
|
or
|
|
.Ar keep-state
|
|
rule, and are typically
|
|
used to open the firewall on-demand to legitimate traffic
|
|
only. See the
|
|
.Xr options
|
|
and
|
|
.Xr EXAMPLES
|
|
sections for more information on the stateful behaviour of
|
|
.Nm ipfw
|
|
.Pp
|
|
All rules (including dynamic ones)
|
|
have a few associated counters: a packet count and
|
|
a byte count, a log count, and a timestamp indicating the time
|
|
of the last match. Counters can be visualized or reset with
|
|
.Nm
|
|
commands.
|
|
.Pp
|
|
Rules can be added with the
|
|
.Ar add
|
|
command; deleted individually with the
|
|
.Ar delete
|
|
command, and globally with the
|
|
.Ar flush
|
|
command; visualized, optionally with the content of
|
|
the counters, using the
|
|
.Ar show
|
|
and
|
|
.Ar list
|
|
commands. Finally, counters can be reset with the
|
|
.Ar zero
|
|
and
|
|
.Ar resetlog
|
|
commands.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl a
|
|
While listing, show counter values. See also
|
|
.Dq show
|
|
command.
|
|
.It Fl f
|
|
Don't ask for confirmation for commands that can cause problems if misused
|
|
(i.e. flush).
|
|
.Ar Note ,
|
|
if there is no tty associated with the process, this is implied.
|
|
.It Fl q
|
|
While adding, zeroing, resetlogging or flushing, be quiet about actions (implies
|
|
.Fl f Ns ).
|
|
This is useful for adjusting rules by executing multiple
|
|
.Nm
|
|
commands in a script
|
|
.Po
|
|
e.g.,
|
|
.Sq sh /etc/rc.firewall
|
|
.Pc ,
|
|
or by processing a file of many
|
|
.Nm
|
|
rules,
|
|
across a remote login session. If a flush is performed in normal
|
|
(verbose) mode (with the default kernel configuration), it prints a message.
|
|
Because all rules are flushed, the
|
|
message cannot be delivered to the login session. This causes the
|
|
remote login session to be closed and the remainder of the ruleset is
|
|
not processed. Access to the console is required to recover.
|
|
.It Fl t
|
|
While listing, show last match timestamp.
|
|
.It Fl N
|
|
Try to resolve addresses and service names in output.
|
|
.It Fl s Op field
|
|
While listing pipes, sort according one of the four
|
|
counters (total and current packets or bytes).
|
|
.El
|
|
.Pp
|
|
To ease configuration, rules can be put into a file which is processed
|
|
using
|
|
.Nm
|
|
as shown in the first synopsis line. The
|
|
.Ar file
|
|
will be read line by line and applied as arguments to the
|
|
.Nm
|
|
command.
|
|
.Pp
|
|
Optionally, a preprocessor can be specified using
|
|
.Fl p Ar preproc
|
|
where
|
|
.Ar file
|
|
is to be piped through. Useful preprocessors include
|
|
.Xr cpp 1
|
|
and
|
|
.Xr m4 1 .
|
|
If
|
|
.Ar preproc
|
|
doesn't start with a slash as its first character, the usual
|
|
.Ev PATH
|
|
name search is performed. Care should be taken with this in environments
|
|
where not all filesystems are mounted (yet) by the time
|
|
.Nm
|
|
is being run (e. g. since they are mounted over NFS). Once
|
|
.Fl p
|
|
has been specified, optional
|
|
.Fl D
|
|
and
|
|
.Fl U
|
|
specifications can follow and will be passed on to the preprocessor.
|
|
This allows for flexible configuration files (like conditionalizing
|
|
them on the local hostname) and the use of macros to centralize
|
|
frequently required arguments like IP addresses.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
.Ar pipe
|
|
commands are used to configure the traffic shaper, as shown in
|
|
the ``TRAFFIC SHAPER CONFIGURATION'' section below.
|
|
.Pp
|
|
.Sh RULE FORMAT
|
|
The
|
|
.Nm
|
|
rule format is the following
|
|
.Pp
|
|
.Op prob Ar match_probability
|
|
.Ar action
|
|
.Op log Op Ar logamount Ar number
|
|
.Ar proto
|
|
from
|
|
.Ar src
|
|
to
|
|
.Ar dst
|
|
.Op interface-spec
|
|
.Op Ar options
|
|
.Pp
|
|
Each packet can be filtered based on the following information that is
|
|
associated with it:
|
|
.Pp
|
|
.Bl -tag -offset indent -compact -width xxxx
|
|
.It Transmit and Receive Interface (by name or address)
|
|
.It Direction (Incoming or Outgoing)
|
|
.It Source and Destination IP Address (possibly masked)
|
|
.It Protocol (TCP, UDP, ICMP, etc.)
|
|
.It Source and Destination Port (lists, ranges or masks)
|
|
.It TCP Flags
|
|
.It IP Fragment Flag
|
|
.It IP Options
|
|
.It ICMP Types
|
|
.It User/Group ID of the socket associated with the packet
|
|
.El
|
|
.Pp
|
|
Note that may be dangerous to filter on the source IP address or
|
|
source TCP/UDP port because either or both could easily be spoofed.
|
|
.Pp
|
|
.Ar prob match_probability
|
|
.Bd -ragged -offset flag
|
|
A match is only declared with the specified
|
|
probability (floating point number between 0 and 1). This can be useful for a number of applications
|
|
such as random packet drop or (in conjunction with
|
|
.Xr dummynet 4
|
|
) to simulate the effect of multiple paths leading to out-of-order
|
|
packet delivery.
|
|
.Ed
|
|
.Pp
|
|
.Ar action :
|
|
.Bl -hang -offset flag -width 1234567890123456
|
|
.It Ar allow
|
|
Allow packets that match rule.
|
|
The search terminates. Aliases are
|
|
.Ar pass ,
|
|
.Ar permit ,
|
|
and
|
|
.Ar accept .
|
|
.It Ar deny
|
|
Discard packets that match this rule.
|
|
The search terminates.
|
|
.Ar Drop
|
|
is an alias for
|
|
.Ar deny .
|
|
.It Ar reject
|
|
(Deprecated.) Discard packets that match this rule, and try to send an ICMP
|
|
host unreachable notice.
|
|
The search terminates.
|
|
.It Ar unreach code
|
|
Discard packets that match this rule, and try to send an ICMP
|
|
unreachable notice with code
|
|
.Ar code ,
|
|
where
|
|
.Ar code
|
|
is a number from zero to 255, or one of these aliases:
|
|
.Ar net ,
|
|
.Ar host ,
|
|
.Ar protocol ,
|
|
.Ar port ,
|
|
.Ar needfrag ,
|
|
.Ar srcfail ,
|
|
.Ar net-unknown ,
|
|
.Ar host-unknown ,
|
|
.Ar isolated ,
|
|
.Ar net-prohib ,
|
|
.Ar host-prohib ,
|
|
.Ar tosnet ,
|
|
.Ar toshost ,
|
|
.Ar filter-prohib ,
|
|
.Ar host-precedence ,
|
|
or
|
|
.Ar precedence-cutoff .
|
|
The search terminates.
|
|
.It Ar reset
|
|
TCP packets only. Discard packets that match this rule,
|
|
and try to send a TCP reset
|
|
.Pq RST
|
|
notice.
|
|
The search terminates.
|
|
.It Ar count
|
|
Update counters for all packets that match rule.
|
|
The search continues with the next rule.
|
|
.It Ar check-state
|
|
Checks the packet against the dynamic ruleset. If a match is
|
|
found then the search terminates, otherwise we move to the
|
|
next rule.
|
|
If no
|
|
.Ar check-state
|
|
rule is found, the dynamic ruleset is checked at the first
|
|
.Ar keep-state
|
|
rule.
|
|
.It Ar divert port
|
|
Divert packets that match this rule to the
|
|
.Xr divert 4
|
|
socket bound to port
|
|
.Ar port .
|
|
The search terminates.
|
|
.It Ar tee port
|
|
Send a copy of packets matching this rule to the
|
|
.Xr divert 4
|
|
socket bound to port
|
|
.Ar port .
|
|
The search terminates and the original packet is accepted
|
|
(but see BUGS below).
|
|
.It Ar fwd ipaddr Op ,port
|
|
Change the next-hop on matching packets to
|
|
.Ar ipaddr ,
|
|
which can be an IP address in dotted quad or a host name.
|
|
If
|
|
.Ar ipaddr
|
|
is not a directly-reachable address, the route
|
|
as found in the local routing table for that IP is used
|
|
instead.
|
|
If
|
|
.Ar ipaddr
|
|
is a local address, then on a packet entering the system from a remote
|
|
host it will be diverted to
|
|
.Ar port
|
|
on the local machine, keeping the local address of the socket set
|
|
to the original IP address the packet was destined for. This is intended
|
|
for use with transparent proxy servers. If the IP is not
|
|
a local address then the port number (if specified) is ignored and
|
|
the rule only applies to packets leaving the system. This will
|
|
also map addresses to local ports when packets are generated locally.
|
|
The search terminates if this rule matches. If the port number is not
|
|
given then the port number in the packet is used, so that a packet for
|
|
an external machine port Y would be forwarded to local port Y. The kernel
|
|
must have been compiled with options IPFIREWALL_FORWARD.
|
|
.It Ar pipe pipe_nr
|
|
Pass packet to a
|
|
.Xr dummynet 4
|
|
``pipe'' (for bandwidth limitation, delay etc.). See the
|
|
.Xr dummynet 4
|
|
manpage for further information. The search terminates; however,
|
|
on exit from the pipe and if the sysctl variable
|
|
net.inet.ip.fw.one_pass is not set, the packet is passed again to
|
|
the firewall code starting from the next rule.
|
|
.It Ar skipto number
|
|
Skip all subsequent rules numbered less than
|
|
.Ar number .
|
|
The search continues with the first rule numbered
|
|
.Ar number
|
|
or higher.
|
|
.El
|
|
.Pp
|
|
.Ar log Op Ar logamount Ar number
|
|
.Bd -ragged -offset flag
|
|
If the kernel was compiled with
|
|
.Dv IPFIREWALL_VERBOSE ,
|
|
then when a packet matches a rule with the
|
|
.Ar log
|
|
keyword a message will be printed on the console.
|
|
If the kernel was compiled with the
|
|
.Dv IPFIREWALL_VERBOSE_LIMIT
|
|
option, then by default logging will cease after the number
|
|
of packets specified by the option are received for that
|
|
particular chain entry. However, if
|
|
.Ar logamount Ar number
|
|
is used, that
|
|
.Ar number
|
|
will be the default logging limit rather than
|
|
.Dv IPFIREWALL_VERBOSE_LIMIT .
|
|
Logging may then be re-enabled by clearing the logging counter
|
|
or the packet counter for that entry.
|
|
.Pp
|
|
Console logging and the log limit are adjustable dynamically
|
|
through the
|
|
.Xr sysctl 8
|
|
interface in the MIB base of
|
|
.Dv net.inet.ip.fw .
|
|
.Ed
|
|
.Pp
|
|
.Ar proto :
|
|
.Bd -ragged -offset flag
|
|
An IP protocol specified by number or name (see
|
|
.Pa /etc/protocols
|
|
for a complete list).
|
|
The
|
|
.Ar ip
|
|
or
|
|
.Ar all
|
|
keywords mean any protocol will match.
|
|
.Ed
|
|
.Pp
|
|
.Ar src
|
|
and
|
|
.Ar dst :
|
|
.Bd -ragged -offset flag
|
|
.Ar <address/mask> Op Ar ports
|
|
.Pp
|
|
The
|
|
.Em <address/mask>
|
|
may be specified as:
|
|
.Pp
|
|
.Bl -hang -offset 0n -width 1234567890123456
|
|
.It Ar ipno
|
|
An ipnumber of the form 1.2.3.4.
|
|
Only this exact ip number match the rule.
|
|
.It Ar ipno/bits
|
|
An ipnumber with a mask width of the form 1.2.3.4/24.
|
|
In this case all ip numbers from 1.2.3.0 to 1.2.3.255 will match.
|
|
.It Ar ipno:mask
|
|
An ipnumber with a mask of the form 1.2.3.4:255.255.240.0.
|
|
In this case all ip numbers from 1.2.0.0 to 1.2.15.255 will match.
|
|
.El
|
|
.Pp
|
|
The sense of the match can be inverted by preceding an address with the
|
|
.Dq not
|
|
modifier, causing all other addresses to be matched instead. This
|
|
does not affect the selection of port numbers.
|
|
.Pp
|
|
With the TCP and UDP protocols, optional
|
|
.Em ports
|
|
may be specified as:
|
|
.Pp
|
|
.Bl -hang -offset flag
|
|
.It Ns {port|port-port|port:mask} Ns Op ,port Ns Op ,...
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ql -
|
|
notation specifies a range of ports (including boundaries).
|
|
.Pp
|
|
The
|
|
.Ql \:
|
|
notation specifies a port and a mask, a match is declared if
|
|
the port number in the packet matches the one in the rule,
|
|
limited to the bits which are set in the mask.
|
|
.Pp
|
|
Service names (from
|
|
.Pa /etc/services )
|
|
may be used instead of numeric port values.
|
|
A range may only be specified as the first value,
|
|
and the length of the port list is limited to
|
|
.Dv IP_FW_MAX_PORTS
|
|
(as defined in
|
|
.Pa /usr/src/sys/netinet/ip_fw.h )
|
|
ports.
|
|
A
|
|
.Ql \e
|
|
can be used to escape the
|
|
.Ql -
|
|
character in a service name:
|
|
.Pp
|
|
.Dl ipfw add count tcp from any ftp\e\e-data-ftp to any
|
|
.Pp
|
|
Fragmented packets which have a non-zero offset (i.e. not the first
|
|
fragment) will never match a rule which has one or more port
|
|
specifications. See the
|
|
.Ar frag
|
|
option for details on matching fragmented packets.
|
|
.Pp
|
|
.Ed
|
|
.Ar interface-spec :
|
|
.Pp
|
|
.Bd -ragged -offset flag
|
|
Some combinations of the following specifiers are allowed:
|
|
.Bl -hang -offset 0n -width 1234567890123456
|
|
.It Ar in
|
|
Only match incoming packets.
|
|
.It Ar out
|
|
Only match outgoing packets.
|
|
.It Ar via ifX
|
|
Packet must be going through interface
|
|
.Ar ifX.
|
|
.It Ar via if*
|
|
Packet must be going through interface
|
|
.Ar ifX ,
|
|
where X is any unit number.
|
|
.It Ar via any
|
|
Packet must be going through
|
|
.Em some
|
|
interface.
|
|
.It Ar via ipno
|
|
Packet must be going through the interface having IP address
|
|
.Ar ipno .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ar via
|
|
keyword causes the interface to always be checked.
|
|
If
|
|
.Ar recv
|
|
or
|
|
.Ar xmit
|
|
is used instead of
|
|
.Ar via ,
|
|
then the only receive or transmit interface (respectively) is checked.
|
|
By specifying both, it is possible to match packets based on both receive
|
|
and transmit interface, e.g.:
|
|
.Pp
|
|
.Dl "ipfw add 100 deny ip from any to any out recv ed0 xmit ed1"
|
|
.Pp
|
|
The
|
|
.Ar recv
|
|
interface can be tested on either incoming or outgoing packets, while the
|
|
.Ar xmit
|
|
interface can only be tested on outgoing packets. So
|
|
.Ar out
|
|
is required (and
|
|
.Ar in
|
|
invalid) whenever
|
|
.Ar xmit
|
|
is used. Specifying
|
|
.Ar via
|
|
together with
|
|
.Ar xmit
|
|
or
|
|
.Ar recv
|
|
is invalid.
|
|
.Pp
|
|
A packet may not have a receive or transmit interface: packets originating
|
|
from the local host have no receive interface, while packets destined for
|
|
the local host have no transmit interface.
|
|
.Ed
|
|
.Pp
|
|
.Ar options :
|
|
.Bl -hang -offset flag -width 1234567890123456
|
|
.It keep-state Op method
|
|
Upon a match, the firewall will create a dynamic rule,
|
|
whose default behaviour is to
|
|
matching bidirectional traffic between source and destination
|
|
IP/port using the same protocol. The rule has a limited lifetime
|
|
(controlled by a set of
|
|
.Nm sysctl
|
|
variables), and the lifetime is refreshed every time a matching packet
|
|
is found.
|
|
.Pp
|
|
The actual behaviour can be modified by specifying a different
|
|
.Op method ,
|
|
although at the moment only the default one is specified.
|
|
.It bridged
|
|
Matches only bridged packets. This can be useful for multicast
|
|
or broadcast traffic, which would otherwise pass through the
|
|
firewall twice: once during bridging, and a second time
|
|
when the packet is delivered to the local stack.
|
|
.Pp
|
|
Apart from a small performance penalty, this would be a problem
|
|
when using
|
|
.Ar pipes
|
|
because the same packet would be accounted for twice
|
|
in terms of bandwidth, queue occupation, and also counters.
|
|
.It frag
|
|
Match if the packet is a fragment and this is not the first fragment
|
|
of the datagram.
|
|
.Ar frag
|
|
may not be used in conjunction with either
|
|
.Ar tcpflags
|
|
or TCP/UDP port specifications.
|
|
.It ipoptions Ar spec
|
|
Match if the IP header contains the comma separated list of
|
|
options specified in
|
|
.Ar spec .
|
|
The supported IP options are:
|
|
.Pp
|
|
.Ar ssrr
|
|
(strict source route),
|
|
.Ar lsrr
|
|
(loose source route),
|
|
.Ar rr
|
|
(record packet route), and
|
|
.Ar ts
|
|
(timestamp).
|
|
The absence of a particular option may be denoted
|
|
with a
|
|
.Dq ! .
|
|
.It established
|
|
Match packets that have the RST or ACK bits set.
|
|
TCP packets only.
|
|
.It setup
|
|
Match packets that have the SYN bit set but no ACK bit.
|
|
TCP packets only.
|
|
.It tcpflags Ar spec
|
|
Match if the TCP header contains the comma separated list of
|
|
flags specified in
|
|
.Ar spec .
|
|
The supported TCP flags are:
|
|
.Pp
|
|
.Ar fin ,
|
|
.Ar syn ,
|
|
.Ar rst ,
|
|
.Ar psh ,
|
|
.Ar ack ,
|
|
and
|
|
.Ar urg .
|
|
The absence of a particular flag may be denoted
|
|
with a
|
|
.Dq ! .
|
|
A rule which contains a
|
|
.Ar tcpflags
|
|
specification can never match a fragmented packet which has
|
|
a non-zero offset. See the
|
|
.Ar frag
|
|
option for details on matching fragmented packets.
|
|
.It icmptypes Ar types
|
|
Match if the ICMP type is in the list
|
|
.Ar types .
|
|
The list may be specified as any combination of ranges
|
|
or individual types separated by commas.
|
|
The supported ICMP types are:
|
|
.Pp
|
|
echo reply
|
|
.Pq Ar 0 ,
|
|
destination unreachable
|
|
.Pq Ar 3 ,
|
|
source quench
|
|
.Pq Ar 4 ,
|
|
redirect
|
|
.Pq Ar 5 ,
|
|
echo request
|
|
.Pq Ar 8 ,
|
|
router advertisement
|
|
.Pq Ar 9 ,
|
|
router solicitation
|
|
.Pq Ar 10 ,
|
|
time-to-live exceeded
|
|
.Pq Ar 11 ,
|
|
IP header bad
|
|
.Pq Ar 12 ,
|
|
timestamp request
|
|
.Pq Ar 13 ,timestamp reply
|
|
.Pq Ar 14 ,
|
|
information request
|
|
.Pq Ar 15 ,
|
|
information reply
|
|
.Pq Ar 16 ,
|
|
address mask request
|
|
.Pq Ar 17 ,
|
|
and address mask reply
|
|
.Pq Ar 18
|
|
.It Ar uid user
|
|
Match all TCP or UDP packets sent by or received for a
|
|
.Ar user .
|
|
A
|
|
.Ar user
|
|
may be matched by name or identification number.
|
|
.It Ar gid group
|
|
Match all TCP or UDP packets sent by or received for a
|
|
.Ar group .
|
|
A
|
|
.Ar group
|
|
may be matched by name or identification number.
|
|
.El
|
|
.Sh TRAFFIC SHAPER CONFIGURATION
|
|
Ipfw is also the user interface for the
|
|
.Xr dummynet 4
|
|
traffic shaper.
|
|
The shaper operates by passing packets to objects called
|
|
.Ar pipes ,
|
|
which emulates a link with given bandwidth, propagation delay,
|
|
queue size and packet loss rate.
|
|
The
|
|
.Nm
|
|
pipe configuration format is the following
|
|
.Pp
|
|
.Ar pipe number config
|
|
.Op bw Ar bandwidth
|
|
.Op queue Ar {slots|size}
|
|
.Op delay Ar delay-ms
|
|
.Op plr Ar loss-probability
|
|
.Op mask Ar {all | {dst-ip|src-ip|dst-port|src-port|proto} bitmask}
|
|
.Op buckets Ar hash-table-size
|
|
.Pp
|
|
The following parameters can be configured for a pipe:
|
|
.Bl -hang -offset flag -width 1234567890
|
|
.It bw Ar bandwidth
|
|
Bandwidth, measured in
|
|
.Ar [K|M]{bit/s|Byte/s} .
|
|
A value of 0 (default) means unlimited bandwidth.
|
|
The unit must follow immediately the number, as in
|
|
.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes"
|
|
.It delay Ar ms-delay
|
|
propagation delay, measured in milliseconds. The value is rounded
|
|
to the next multiple of the clock tick (typically 10ms, but it is
|
|
good practice to run kernels with "options HZ=1000" to reduce
|
|
the granularity to 1ms or less). Default value is 0, meaning
|
|
no delay.
|
|
.It queue Ar {slots|size}
|
|
queue size, in slots or KBytes. Default value is 50 slots, which
|
|
is the typical queue size for Ethernet devices. Note that for
|
|
slow speed links you should keep the queue size short or your
|
|
traffic might be affected by a significant queueing delay. E.g.
|
|
50 max-sized ethernet packets (1500
|
|
bytes) mean 600Kbit or 20s of queue on a 30Kbit/s pipe.
|
|
Even worse effect can result if you get
|
|
packets from an interface with a much larger MTU e.g. the loopback
|
|
interface with its 16KB packets.
|
|
.It plr packet-loss-rate
|
|
packet loss rate. NN is a floating-point number, with 0 meaning
|
|
no loss, 1 means 100% loss. The loss rate is internally represented
|
|
on 31 bits.
|
|
.It mask Ar mask-specifier
|
|
dummynet allows you to generate per-flow queues
|
|
using a single pipe specification. A flow identifier is constructed
|
|
by masking the IP addresses, ports and protocol types as specified
|
|
in the pipe configuration. Packets with the same ID after masking fall
|
|
into the same queue. Available mask specifiers are a combination
|
|
of the following:
|
|
.Ar dst-ip mask , src-ip mask ,
|
|
.Ar dst-port mask , src-port mask ,
|
|
.Ar proto mask
|
|
or
|
|
.Ar all
|
|
where the latter means all bits in all fields are significant.
|
|
.It buckets Ar NN
|
|
Specifies the size of the hash table used for storing the various queues.
|
|
Default value is 64 controlled by the sysctl variable
|
|
.Ar net.inet.ip.dummynet.hash_size ,
|
|
allowed range is 16 to 1024.
|
|
.El
|
|
.Sh CHECKLIST
|
|
Here are some important points to consider when designing your
|
|
rules:
|
|
.Bl -bullet -hang -offset flag
|
|
.It
|
|
Remember that you filter both packets going in and out.
|
|
Most connections need packets going in both directions.
|
|
.It
|
|
Remember to test very carefully.
|
|
It is a good idea to be near the console when doing this.
|
|
.It
|
|
Don't forget the loopback interface.
|
|
.El
|
|
.Sh FINE POINTS
|
|
There is one kind of packet that the firewall will always discard,
|
|
that is an IP fragment with a fragment offset of one.
|
|
This is a valid packet, but it only has one use, to try to circumvent
|
|
firewalls.
|
|
.Pp
|
|
If you are logged in over a network, loading the KLD version of
|
|
.Nm
|
|
is probably not as straightforward as you would think.
|
|
I recommend this command line:
|
|
.Bd -literal -offset center
|
|
kldload /modules/ipfw.ko && \e
|
|
ipfw add 32000 allow all from any to any
|
|
.Ed
|
|
.Pp
|
|
Along the same lines, doing an
|
|
.Bd -literal -offset center
|
|
ipfw flush
|
|
.Ed
|
|
.Pp
|
|
in similar surroundings is also a bad idea.
|
|
.Pp
|
|
The IP filter list may not be modified if the system security level
|
|
is set to 3 or higher
|
|
.Po
|
|
see
|
|
.Xr init 8
|
|
for information on system security levels
|
|
.Pc .
|
|
.Sh PACKET DIVERSION
|
|
A divert socket bound to the specified port will receive all packets diverted
|
|
to that port; see
|
|
.Xr divert 4 .
|
|
If no socket is bound to the destination port, or if the kernel
|
|
wasn't compiled with divert socket support, the packets are dropped.
|
|
.Pp
|
|
.Sh SYSCTL VARIABLES
|
|
A set of
|
|
.Nm sysctl
|
|
variables controls the behaviour of the firewall. These are shown
|
|
below together with their default value and meaning
|
|
.Bl -tag -offset flag -width 1234567890
|
|
.It "net.inet.ip.fw.debug: 1"
|
|
Controls debugging messages produced by ipfw.
|
|
.It "net.inet.ip.fw.one_pass: 1"
|
|
When set, permits only one pass through the firewall.
|
|
Otherwise, after a
|
|
pipe or divert
|
|
action, the packet is reinjected in the firewall starting from
|
|
the next rule.
|
|
.It net.inet.ip.fw.verbose: 1
|
|
Enables verbose messages.
|
|
.It net.inet.ip.fw.enable: 1
|
|
Enables the firewall. Setting this variable to 0 lets you run your
|
|
machine without firewall even if compiled in.
|
|
.It net.inet.ip.fw.verbose_limit: 0
|
|
Limits the number of messages produced by a verbose firewall.
|
|
.It net.inet.ip.fw.dyn_buckets: 256
|
|
.It net.inet.ip.fw.curr_dyn_buckets: 256
|
|
The configured and current size of the hash table used to hold
|
|
dynamic rules. This must be a power of 2. The table can only
|
|
be resized when empty, so in order to resize it on the fly you
|
|
will probably have to
|
|
.Ar flush
|
|
and reload the ruleset.
|
|
.It net.inet.ip.fw.dyn_count: 3
|
|
(readonly) current number of dynamic rules.
|
|
.It net.inet.ip.fw.dyn_max: 1000
|
|
Maximum number of dynamic rules. When you hit this limit,
|
|
no more dynamic rules can be installed until old ones expire.
|
|
.It net.inet.ip.fw.dyn_ack_lifetime: 300
|
|
.It net.inet.ip.fw.dyn_syn_lifetime: 20
|
|
.It net.inet.ip.fw.dyn_fin_lifetime: 20
|
|
.It net.inet.ip.fw.dyn_rst_lifetime: 5
|
|
.It net.inet.ip.fw.dyn_short_lifetime: 30
|
|
These variable control the lifetime, in seconds, of dynamic rules.
|
|
Upon the initial SYN exchange the lifetime is kept short,
|
|
then increased after both SYN have been seen, then decreased
|
|
again during the final FIN exchange or when a RST
|
|
.El
|
|
.Sh EXAMPLES
|
|
This command adds an entry which denies all tcp packets from
|
|
.Em cracker.evil.org
|
|
to the telnet port of
|
|
.Em wolf.tambov.su
|
|
from being forwarded by the host:
|
|
.Pp
|
|
.Dl ipfw add deny tcp from cracker.evil.org to wolf.tambov.su 23
|
|
.Pp
|
|
This one disallows any connection from the entire crackers network to
|
|
my host:
|
|
.Pp
|
|
.Dl ipfw add deny all from 123.45.67.0/24 to my.host.org
|
|
.Pp
|
|
A first and efficient way to limit access (not using dynamic rules)
|
|
is the use of the following rules
|
|
.Pp
|
|
.Dl "ipfw add allow tcp from any to any established"
|
|
.Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup"
|
|
.Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup"
|
|
.Dl "..."
|
|
.Dl "ipfw add deny tcp from any to any"
|
|
.Pp
|
|
The first rule will be a quick match for normal TCP packets, but
|
|
it will not match the initial SYN packet, which will be
|
|
matched by the
|
|
.Ar setup
|
|
rules only for selected source/destination pairs.
|
|
All other SYN packets will be rejected by the final
|
|
.Ar deny
|
|
rule.
|
|
.Pp
|
|
In order to protect a site from flood attacks involving fake
|
|
TCP packets, it is safer to use dynamic rules:
|
|
.Pp
|
|
.Dl "ipfw add check-state"
|
|
.Dl "ipfw add deny tcp from any to any established"
|
|
.Dl "ipfw add allow tcp from my-net to any setup keep-state"
|
|
.Pp
|
|
This will let the firewall install dynamic rules only for
|
|
those connection which start with a regular SYN
|
|
packet coming from the inside of our network. Dynamic rules
|
|
are checked when encountering the first
|
|
.Ar check-state
|
|
or
|
|
.Ar keep-state
|
|
rule. A
|
|
.Ar check-state
|
|
rule should be usually placed near the beginning of the ruleset
|
|
to minimize the amount of work scanning the ruleset. Your mileage
|
|
may vary.
|
|
.Pp
|
|
BEWARE:
|
|
stateful rules can be subject to denial-of-service attacks
|
|
by a SYN-flood which opens a huge number of dynamic rules.
|
|
The effects of such attacks can be partially limited by acting on
|
|
a set of
|
|
.Nm sysctl
|
|
variables which control the operation of the firewall.
|
|
.Pp
|
|
There is a number of sysctl variables which controls the
|
|
.Pp
|
|
Here is a good usage of the
|
|
.Ar list
|
|
command to see accounting records
|
|
and timestamp information:
|
|
.Pp
|
|
.Dl ipfw -at l
|
|
.Pp
|
|
or in short form without timestamps:
|
|
.Pp
|
|
.Dl ipfw -a l
|
|
.Pp
|
|
This rule diverts all incoming packets from 192.168.2.0/24 to divert port 5000:
|
|
.Pp
|
|
.Dl ipfw divert 5000 all from 192.168.2.0/24 to any in
|
|
.Pp
|
|
The following rules show some of the applications of ipfw and
|
|
dummynet for simulations and the like.
|
|
.Pp
|
|
This rule drops random packets with a probability of 5%
|
|
.Pp
|
|
.Dl "ipfw add prob 0.05 deny ip from any to any in"
|
|
.Pp
|
|
A similar effect can be achieved making use of dummynet pipes:
|
|
.Pp
|
|
.Dl "ipfw add pipe 10 ip from any to any"
|
|
.Dl "ipfw pipe 10 config plr 0.05"
|
|
.Pp
|
|
We can use pipes to artificially limit bandwidth e.g. on a machine
|
|
acting as a router, if we want to limit traffic from local clients
|
|
on 192.168.2.0/24 we do:
|
|
.Pp
|
|
.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out"
|
|
.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes"
|
|
.Pp
|
|
note that we use the
|
|
.Ql out
|
|
specifier so that the rule is not used twice. Remember in fact
|
|
that ipfw rules are checked both on incoming and outgoing packets.
|
|
.Pp
|
|
Should we like to simulate a bidirectional link with bandwidth
|
|
limitations, the correct way is the following:
|
|
.Pp
|
|
.Dl "ipfw add pipe 1 ip from any to any out"
|
|
.Dl "ipfw add pipe 2 ip from any to any in"
|
|
.Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes"
|
|
.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes"
|
|
.Pp
|
|
The above can be very useful e.g. if you want to see how your fancy
|
|
Web page will look for a residential user which is connected only through
|
|
a slow link.
|
|
You should not use only
|
|
one pipe for both directions, unless you want to simulate a half-duplex
|
|
medium (e.g. appletalk, Ethernet, IRDA).
|
|
It is not necessary that both pipes have the same configuration,
|
|
so we can also simulate asymmetric links.
|
|
.Pp
|
|
Another typical application of the traffic shaper is to introduce some
|
|
delay in the communication. This can affect a lot applications which do
|
|
a lot of Remote Procedure Calls, and where the round-trip-time of the
|
|
connection often becomes a limiting factor much more than bandwidth:
|
|
.Pp
|
|
.Dl "ipfw add pipe 1 ip from any to any out"
|
|
.Dl "ipfw add pipe 2 ip from any to any in"
|
|
.Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s"
|
|
.Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s"
|
|
.Pp
|
|
Per-flow queueing can be useful for a variety of purposes. A very
|
|
simple one is counting traffic:
|
|
.Pp
|
|
.Dl "ipfw add pipe 1 tcp from any to any"
|
|
.Dl "ipfw add pipe 1 udp from any to any"
|
|
.Dl "ipfw add pipe 1 ip from any to any"
|
|
.Dl "ipfw pipe 1 config mask all"
|
|
.Pp
|
|
The above set of rules will create queues (and collect statistics)
|
|
for all traffic. Because the pipes have no limitations, the only
|
|
effect is collecting statistics. Note that we need 3 rules, not just
|
|
the last one, because when ipfw tries to match ip packets it will
|
|
not consider ports, so we would not see connections on separate ports
|
|
as different ones.
|
|
.Pp
|
|
A more sophisticated example is limiting the outbound traffic on a net
|
|
with per-host limits, rather than per-network limits:
|
|
.Pp
|
|
.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out"
|
|
.Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in"
|
|
.Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
|
|
.Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes"
|
|
.Sh SEE ALSO
|
|
.Xr cpp 1 ,
|
|
.Xr m4 1 ,
|
|
.Xr divert 4 ,
|
|
.Xr dummynet 4 ,
|
|
.Xr bridge 4 ,
|
|
.Xr ip 4 ,
|
|
.Xr ipfirewall 4 ,
|
|
.Xr protocols 5 ,
|
|
.Xr services 5 ,
|
|
.Xr init 8 ,
|
|
.Xr kldload 8 ,
|
|
.Xr reboot 8 ,
|
|
.Xr sysctl 8 ,
|
|
.Xr syslogd 8 .
|
|
.Sh BUGS
|
|
.Pp
|
|
The syntax has grown over the years and it is not very clean.
|
|
.Pp
|
|
.Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!
|
|
.Pp
|
|
This program can put your computer in rather unusable state. When
|
|
using it for the first time, work on the console of the computer, and
|
|
do
|
|
.Em NOT
|
|
do anything you don't understand.
|
|
.Pp
|
|
When manipulating/adding chain entries, service and protocol names are
|
|
not accepted.
|
|
.Pp
|
|
Incoming packet fragments diverted by
|
|
.Ar divert
|
|
or
|
|
.Ar tee
|
|
are reassembled before delivery to the socket.
|
|
.Pp
|
|
Packets that match a
|
|
.Ar tee
|
|
rule should not be immediately accepted, but should continue
|
|
going through the rule list. This may be fixed in a later version.
|
|
.Sh AUTHORS
|
|
.An Ugen J. S. Antsilevich ,
|
|
.An Poul-Henning Kamp ,
|
|
.An Alex Nash ,
|
|
.An Archie Cobbs ,
|
|
.An Luigi Rizzo .
|
|
.Pp
|
|
API based upon code written by
|
|
Daniel Boulet
|
|
for BSDI.
|
|
.Pp
|
|
Work on dummynet traffic shaper supported by Akamba Corp.
|
|
.Sh HISTORY
|
|
.Nm Ipfw
|
|
first appeared in
|
|
.Fx 2.0 .
|
|
.Nm dummynet
|
|
was introduced in
|
|
.Fx 2.2.8 .
|
|
Stateful extensions were introduced in
|
|
.Fx 4.0-RELEASE
|