b805452cc8
standards and to clean up some of the English. The job is nowhere complete. This man page would be a good project for someone who knows something about the firewall software, and would like to contribute to the documentation effort. Many of the things in this man page are out of date and do not reflect reality.
208 lines
8.4 KiB
Groff
208 lines
8.4 KiB
Groff
.Dd November 16, 1994
|
|
.Dt IPFIREWALL 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ipfirewall,
|
|
.Nm ipfw ,
|
|
.Nm ipaccounting ,
|
|
.Nm ipacct
|
|
.Nd IP packet filter and traffic accounting.
|
|
.Sh SYNOPSIS
|
|
.Fd #include <netinet/ip_fw.h>
|
|
.Ft int
|
|
.Fn setsockopt raw_socket IPPROTO_IP "ipfw/ipacct option" "struct ip | struct ipfw" size
|
|
|
|
Ipfw options:
|
|
IP_FW_ADD_BLK - add entry to blocking chain.
|
|
IP_FW_ADD_FWD - add entry to forwarding chain.
|
|
IP_FW_CHK_BLK - check ip packet against blocking chain.
|
|
IP_FW_CHK_FWD - check ip packet against forwarding chain.
|
|
IP_FW_DEL_BLK - delete entry from blocking chain.
|
|
IP_FW_DEL_FWD - delete entry from forwarding chain.
|
|
IP_FW_FLUSH - flush all blocking & forwarding chain entries.
|
|
IP_FW_POLICY - define default ipfw policy.
|
|
|
|
Ipacct options:
|
|
IP_ACCT_ADD - add entry to accounting chain.
|
|
IP_ACCT_DEL - delete entry from accounting chain.
|
|
IP_ACCT_FLUSH - flush all accounting chain entries.
|
|
IP_ACCT_ZERO - zero all accounting chain entries.
|
|
|
|
Ipfw/ipacct entry structure:
|
|
#define IP_FW_MAX_PORTS 10
|
|
|
|
struct ip_fw {
|
|
struct ip_fw *next;
|
|
struct in_addr src, dst;
|
|
struct in_addr src_mask, dst_mask;
|
|
u_short flags;
|
|
u_short n_src_p, n_dst_p;
|
|
u_short ports[IP_FW_MAX_PORTS];
|
|
u_long p_cnt,b_cnt;
|
|
}
|
|
|
|
Flags values for "flags" field:
|
|
IP_FW_F_ALL - The entry should match all IP packets.
|
|
IP_FW_F_TCP - The entry should match TCP packets.
|
|
IP_FW_F_UDP - The entry should match UDP packets.
|
|
IP_FW_F_ICMP - The entry should match ICMP packets.
|
|
IP_FW_F_KIND - Mask value to separate protocol kind.
|
|
IP_FW_F_ACCEPT - This entry is accepting ( see below )
|
|
IP_FW_F_SRNG - Source ports are range ( see below )
|
|
IP_FW_F_DRNG - Destination ports are range ( see below )
|
|
IP_FW_F_PRN - Print this entry ( see below )
|
|
IP_FW_F_BIDIR - This acct entry is bidirectional ( see below )
|
|
IP_FW_F_MASK - Mask to match all valid flag bits.
|
|
|
|
Kernel symbols to kvm_nlist():
|
|
struct ip_fw *ip_fw_blk_chain - chain of forwarding entries.
|
|
struct ip_fw *ip_fw_fwd_chain - chain of blocking entries.
|
|
int ip_fw_policy - default policy.
|
|
struct ip_fw *ip_acct_chain - chain of accounting entries.
|
|
|
|
Options in the kernel configuration file:
|
|
IPFIREWALL - enable ipfirewall.
|
|
IPFIREWALL_VERBOSE - enable firewall output ( see below )
|
|
DEBUG_IPFIREWALL - enable extensive debugging output.
|
|
IPACCT - enable ipaccounting.
|
|
|
|
.Sh DESCRIPTION
|
|
Ipfirewall (later ipfw) is a system facility,which allows filtering
|
|
of incoming and/or forwarding packets on the protocol+source/destination
|
|
address/ports base.
|
|
Ipaccounting (later ipacct) is a system facility,which allows counting
|
|
of incoming,outgoing and forwarding traffic by packet/byte count.
|
|
.Pp
|
|
Basic idea is that every packet checked against number of entries
|
|
in several chains. There are 3 chains:
|
|
Blocking - this chain defines whenever packet should be accepted
|
|
ever for local delivery or for forwarding.
|
|
Forwarding - this chain defines whenever packet should be accepted
|
|
for forwarding only.
|
|
Accounting - this chain defines types of packets , which should be
|
|
|
|
.Pp
|
|
Options to add/remove specific entries or to flush all entries described
|
|
above. Value passed to
|
|
.Fn setsockopt
|
|
is a value of struct ip_fw for
|
|
entry. If an entry is added, it checked by such rules that when we start
|
|
searching chain for matching entry the first matching is the best match,
|
|
[ or at least one of them :^) ].
|
|
That means:
|
|
* First in chain entries with specific protocol and small ranges
|
|
of src/dst addresses and ports.
|
|
* Later go entries with wider ranges of ports and addresses.
|
|
* Later entries matching every port for some address range.
|
|
* Later universal entries matching any protocol.
|
|
.Pp
|
|
While deleting entry, every entry which is equal to that passed to
|
|
.Fn setsockopt
|
|
will be removed. Flush removes all entries.
|
|
Each entry has several fields by which packets are matched:
|
|
|
|
|
|
struct ip_fw *next - next entry in chain.(Set internally)
|
|
|
|
struct in_addr src - source address to be matched.
|
|
struct in_addr src_mask - source address mask.
|
|
To match whole networks/subnets or address groups
|
|
mask bits should be zeroed here and also
|
|
in src_mask field. Valuable bits should be set
|
|
in src_mask field.
|
|
struct in_addr dst - destination address to be matched.
|
|
struct in_addr dst_mask - destination address mask.
|
|
|
|
u_short flags - flags field.See exact description of flags meaning
|
|
in description later.
|
|
|
|
u_short n_src_p - number of source ports in "ports" array.
|
|
u_short n_dst_p - number of destination ports in "ports" array.
|
|
u_short ports[] - ports array.Overall length currently defined
|
|
to reasonable maximum - 10,and could be changed.
|
|
The packet's src port can ever match one of
|
|
ports[0] ... ports[--n_src_p] numbers,or if
|
|
flag IP_FW_F_SRNG set take port[0] as bottom
|
|
range value and ports[1] as top one.n_src_p should
|
|
be set to 2 then.If n_src_p equal to 0 , every port
|
|
match. The same rules apply to packet's dst port,
|
|
except that it matched against ports[n_src_p] ...
|
|
... ports[n_src_p+n_dst_p--],or if IP_FW_F_DRNG set,
|
|
range is ports[n_src_p] to ports[n_srcp++].
|
|
|
|
u_long p_cnt - packets count for ipacct entries.
|
|
u_long b_cnt - bytes count for ipacct entries.
|
|
|
|
Packet matching proceeds in the following manner:
|
|
|
|
a) If packet entry protocol set to ALL, see c).
|
|
|
|
b) If entry protocol set to TCP/UDP/ICMP and packet protocol
|
|
different - no match, if packet protocol and entry protocol
|
|
same - continue.
|
|
|
|
c) If source address pattern does not equal to packets sources address
|
|
masked with src_mask, or destination pattern not equal to packets
|
|
destination address masked with dst_mask - no match.
|
|
If they does and protocol set to ALL/ICMP - got match.
|
|
If they does and protocol set to TCP/UDP - continue.
|
|
|
|
d) If src port doesn't match or dst port doesn't match - all
|
|
packet don't match. If they do - got match.
|
|
.Pp
|
|
In ipfw packet matched consequently against every chain entry.
|
|
Search continues untill first matching entry found.If IP_FW_F_ACCEPT
|
|
flag set - packet accepted. If it is not set - packet denied.
|
|
If no matching entry found, all unmatched packets ever accepted or
|
|
denied depending on global policy value. It can be set with
|
|
IP_FW_POLICY raw socket option. The value for deny is 0,
|
|
and 1 for accept.
|
|
.Pp
|
|
Entries can be added with IP_FW_F_PRN flag set.If kernel compiled
|
|
with IPFIREWALL_VERBOSE option,packets matching this entries will
|
|
be printed by kernel printf's.
|
|
.Pp
|
|
If some chain is empty,every packet accepted by this chain no
|
|
matter what default policy is.
|
|
.Pp
|
|
To check whenever or not packet denied by some chain , checking
|
|
options to setsockopt() can be issued. Then the argument is
|
|
a buffer representing ip packet,thus it has to be
|
|
struct ip + struct tcphdr .
|
|
Then setsockopt() return value 0 on accept or another on deny.
|
|
.Pp
|
|
Ipaccounting entries added the same way as ipfw ones.Packet checked
|
|
against all entries in chain and values of p_cnt and b_cnt in matching
|
|
entries rised.p_cnt rises by 1 and b_cnt by ip_len value of ip packet.
|
|
Thus all traffic size counted including IP headers.
|
|
.Pp
|
|
If IP_FW_F_BIDIR flag is set in accounting entry,packets counted are
|
|
those which match entry in standard way along with packets which match
|
|
entry while their source and destination addr/port pairs swapped.
|
|
.Pp
|
|
Zero option allows all accounting to be cleared.
|
|
.Sh DIAGNOSTICS
|
|
|
|
[EINVAL] The IP option field was improperly formed; an option
|
|
field was shorter than the minimum value or longer than
|
|
the option buffer provided.An structural error in
|
|
ip_fw structure occurred (n_src_p+n_dst_p too big,
|
|
ports set for ALL/ICMP protocols etc.)
|
|
.Sh SEE ALSO
|
|
.Xr setsockopt 2 ,
|
|
.Xr kvm_nlist 3 ,
|
|
.Xr kvm_read 3 ,
|
|
.Xr ip 4
|
|
.Sh BUGS
|
|
The ipfw/ipacct facilities are new and, although serious bugs have
|
|
been tracked, some less important ones are expected.
|
|
.Pp
|
|
This man page is mostly out of date and should be rewritten.
|
|
.Sh HISTORY
|
|
Ipfw facility has been initially written as package to BSDI
|
|
by Daniel Boulet <danny@BouletFermat.ab.ca>.
|
|
It has been heavily modified and ported to FreeBSD 2.0
|
|
by Ugen J.S.Antsilevich <ugen@NetVision.net.il>
|
|
Ipacct facility written for FreeBSD 2.0
|
|
by Ugen J.S.Antsilevich <ugen@NetVision.net.il>
|