Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
IPF(5)									IPF(5)

NAME
       ipf, ipf.conf - IPFilter	firewall rules file format

DESCRIPTION
       The  ipf.conf  file  is	used to	specify	rules for the firewall,	packet
       authentication and packet accounting components of  IPFilter.  To  load
       rules specified in the ipf.conf file, the ipf(8)	program	is used.

       For  use	 as a firewall,	there are two important	rule types: those that
       block and drop packets (block  rules)  and  those  that	allow  packets
       through	(pass  rules.) Accompanying the	decision to apply is a collec-
       tion of statements that specify under what conditions the result	is  to
       be applied and how.

       The  simplest  rules  that  can	be used	in ipf.conf are	expressed like
       this:

       block in	all
       pass out	all

       Each rule must contain at least the following three components

	      *	     a decision	keyword	(pass, block, etc.)

	      *	     the direction of the packet (in or	out)

	      *	     address patterns or "all" to match	any  address  informa-
		     tion

   Long	lines
       For  rules  lines  that	are particularly long, it is possible to split
       them over multiple lines	implicity like this:

       pass in on bgeo proto tcp from 1.1.1.1 port > 1000
	   to 2.2.2.2 port < 5000 flags	S keep state

       or explicitly using the backslash ('\') character:

       pass in on bgeo proto tcp from 1.1.1.1 port > 1000 \
	   to 2.2.2.2 port < 5000 flags	S keep state

   Comments
       Comments	in the ipf.conf	file are indicated by the use of the '#' char-
       acter.  This can	either be at the start of the line, like this:

       # Allow all ICMP	packets	in
       pass in proto icmp from any to any

       Or at the end of	a like,	like this:

       pass in proto icmp from any to any # Allow all ICMP packets in

Firewall rules
       This  section  goes into	detail on how to construct firewall rules that
       are placed in the ipf.conf file.

       It is beyond the	scope of this document to describe what	makes  a  good
       firewall	 rule  set  or	which packets should be	blocked	or allowed in.
       Some suggestions	will be	provided but further reading  is  expected  to
       fully understand	what is	safe and unsafe	to allow in/out.

   Filter rule keywords
       The  first  word	 found	in any filter rule describes what the eventual
       outcome of a packet that	matches	it will	be. Descriptions of  the  many
       and  various  sections  that  can  be  used to match on the contents of
       packet headers will follow on below.

       The complete list of keywords, along with what they do is as follows:

	      pass rules that match a packet  indicate	to  ipfilter  that  it
		     should  be	 allowed to continue on	in the direction it is
		     flowing.

	      block rules are used when	it is desirable	to  prevent  a	packet
		     from  going  any further. Packets that are	blocked	on the
		     "in" side are never seen by TCP/IP	 and  those  that  are
		     blocked going "out" are never seen	on the wire.

	      log  when	 IPFilter  successfully	matches	a packet against a log
		     rule a log	record is generated  and  made	available  for
		     ipmon(8)  to  read. These rules have no impact on whether
		     or	not a packet is	allowed	 through  or  not.   So	 if  a
		     packet  first matched a block rule	and then matched a log
		     rule, the status of the packet after the log rule is that
		     it	will still be blocked.

	      count  rules provide the administrator with the ability to count
		     packets and bytes that match the criteria laid out	in the
		     configuration  file.   The	 count rules are applied after
		     NAT and filter rules on the inbound  path.	 For  outbound
		     packets,  count  rules  are applied before	NAT and	before
		     the packet	is dropped. Thus the count rule	cannot be used
		     as	a true indicator of link layer

	      auth  rules  cause  the matching packet to be queued up for pro-
		     cessing by	a user space program. The user	space  program
		     is	responsible for	making an ioctl	system call to collect
		     the information about the queued packet and another ioctl
		     system  call  to return the verdict (block, pass, etc) on
		     what to do	with the packet. In the	event that  the	 queue
		     becomes full, the packets will end	up being dropped.

	      call provides access to functions	built into IPFilter that allow
		     for more complex actions to be taken as part of the deci-
		     sion making that goes with	the rule.

	      decapsulate  rules instruct ipfilter to remove any other headers
		     (IP, UDP, AH) and then process what is inside  as	a  new
		     packet.   For  non-UDP  packets, there are	builtin	checks
		     that are applied in addition to whatever is specified  in
		     the  rule,	to only	allow decapsulation of recognised pro-
		     tocols. After decapsulating the inner packet, any filter-
		     ing  result  that	is applied to the inner	packet is also
		     applied to	the other packet.

	      The default way in which filter rules are	 applied  is  for  the
	      last  matching rule to be	used as	the decision maker. So even if
	      the first	rule to	match a	packet is a pass, if there is a	 later
	      matching	rule  that  is	a block	and no further rules match the
	      packet, then it will be blocked.

   Matching Network Interfaces
       On systems with more than one network interface,	it is necessary	to  be
       able  to	specify	different filter rules for each	of them.  In the first
       instance, this is because different networks will send us  packets  via
       each  network  interface	 but it	is also	because	of the hosts, the role
       and the resulting security policy that we need to be  able  to  distin-
       guish which network interface a packet is on.

       To  accomodate  systems	where  the  presence of	a network interface is
       dynamic,	it is not necessary for	the network interface named in a  fil-
       ter rule	to be present in the system when the rule is loaded.  This can
       lead to silent errors being introduced and  unexpected  behaviour  with
       the simplest of keyboard	mistakes - for example,	typing in hem0 instead
       of hme0 or hme2 instead of hme3.

       On Solaris systems prior	to Solaris 10 Update 4,	it is not possible  to
       filter  packets	on  the	 loopback interface (lo0) so filter rules that
       specify it will have no impact on the corresponding  flow  of  packets.
       See below for Solaris specific tips on how to enable this.

       Some examples of	including the network interface	in filter rules	are:

       block in	on bge0	all
       pass out	on bge0	all

   Address matching (basic)
       The  first  and	most  basic part of matching for filtering rules is to
       specify IP addresses and	 TCP/UDP  port	numbers.  The  source  address
       information  is	matched	by the "from" information in a filter rule and
       the destination address information is matched with the	"to"  informa-
       tion in a filter	rule.

       The  typical format used	for IP addresses is CIDR notation, where an IP
       address (or network) is followed	by a '/' and a number representing the
       size  of	 the  netmask  in  bits.  This notation	is used	for specifying
       address matching	in both	IPv4 and IPv6. If the '/' and bitmask size are
       excluded	from the matching string, it is	assumed	that the address spec-
       ified is	a host address and that	the netmask applied should be all 1's.

       Some examples of	this are:

       pass in from 10.1.0.0/24	to any
       block out from any to 10.1.1.1

       It is not possible to specify a range of	addresses that does not	have a
       boundary	that can be defined by a standard subnet mask.

	      Names instead of addresses

	      Hostnames, resolved either via DNS  or  /etc/hosts,  or  network
	      names,  resolved	via  /etc/networks,  may  be  used in place of
	      actual addresses in the filter rules.  WARNING:  if  a  hostname
	      expands  to  more	 than one address, only	the *first* is used in
	      building the filter rule.

	      Caution should be	exercised when relying on DNS for filter rules
	      in case the sending and receiving	of DNS packets is blocked when
	      ipf(8) is	processing that	part of	the configuration file,	 lead-
	      ing  to long delays, if not errors, in loading the filter	rules.

   Protocol Matching
       To match	packets	based on TCP/UDP port information, it is first	neces-
       sary  to	indicate which protocol	the packet must	be. This is done using
       the "proto" keyword, followed by	either the protocol number or  a  name
       which is	mapped to the protocol number, usually through the /etc/proto-
       cols file.

       pass in proto tcp from 10.1.0.0/24 to any
       block out proto udp from	any to 10.1.1.1
       pass in proto icmp from any to 192.168.0.0/16

   Sending back	error packets
       When a packet is	just discarded using a block rule, there is  no	 feed-
       back given to the host that sent	the packet. This is both good and bad.
       If this is the desired behaviour	and it is not desirable	 to  send  any
       feedback	about packets that are to be denied. The catch is that often a
       host trying to connect to a TCP port or with a  UDP  based  application
       will  send more than one	packet because it assumes that just one	packet
       may be discarded	so a retry is required.	The end	result being logs  can
       become cluttered	with duplicate entries due to the retries.

       To  address  this  problem,  a block rule can be	qualified in two ways.
       The first of these is specific to TCP and instructs  IPFilter  to  send
       back  a	reset (RST) packet. This packet	indicates to the remote	system
       that the	packet it sent has been	rejected and that  it  shouldn't  make
       any  further attempts to	send packets to	that port. Telling IPFilter to
       return a	TCP RST	packet in response to something	that has been received
       is achieved with	the return-rst keyword like this:

       block return-rst	in proto tcp from 10.0.0.0/8 to	any

       When  sending  back  a  TCP  RST	 packet, IPFilter must construct a new
       packet that has the source address of  the  intended  target,  not  the
       source  address of the system it	is running on (if they are different.)

       For all of the other protocols handled by the  IP  protocol  suite,  to
       send  back  an  error  indicating  that the received packet was dropped
       requires	sending	back an	ICMP error packet. Whilst these	 can  also  be
       used for	TCP, the sending host may not treat the	received ICMP error as
       a hard error in the same	way as it does the TCP RST packet.  To	return
       an ICMP error it	is necessary to	place return-icmp after	the block key-
       word like this:

       block return-icmp in proto udp from any to 192.168.0.1/24

       When electing to	return an ICMP error packet, it	is  also  possible  to
       select  what type of ICMP error is returned. Whilst the full compliment
       of ICMP unreachable codes can be	used by	specifying a number instead of
       the string below, only the following should be used in conjunction with
       return-icmp. Which return code to use is	 a  choice  to	be  made  when
       weighing	 up  the  pro's	and con's. Using some of the codes may make it
       more obvious that a firewall is being used rather than  just  the  host
       not responding.

	      filter-prohib (prohibited	by filter) sending packets to the des-
		     tination given in the received packet is  prohibited  due
		     to	the application	of a packet filter

	      net-prohib  (prohibited network) sending packets to the destina-
		     tion given	in the	received  packet  is  administratively
		     prohibited.

	      host-unk	(host  unknown)	 the  destination  host	address	is not
		     known by the system receiving the	packet	and  therefore
		     cannot be reached.

	      host-unr (host unreachable) it is	not possible to	reach the host
		     as	given by the destination address in the	packet header.

	      net-unk (network unknown)	the destination	network	address	is not
		     known by the system receiving the	packet	and  therefore
		     cannot be reached.

	      net-unr  (network	unreachable) it	is not possible	to forward the
		     packet on to its final destination	as given by the	desti-
		     nation address

	      port-unr	(port  unreachable)  there is no application using the
		     given destination port and	therefore it is	 not  possible
		     to	reach that port.

	      proto-unr	 (protocol  unreachable)  the IP protocol specified in
		     the packet	is not available to receive packets.

	      An example that shows how	to send	back a port unreachable	packet
	      for UDP packets to 192.168.1.0/24	is as follows:

	      block return-icmp(port-unr) in proto udp from any	to 192.168.1.0/24

	      In  the  above  examples,	when sending the ICMP packet, IPFilter
	      will construct a new ICMP	packet with a source  address  of  the
	      network  interface  used to send the packet back to the original
	      source. This can give away that there is an intermediate	system
	      blocking	packets. To have IPFilter send back ICMP packets where
	      the source address is the	original  destination,	regardless  of
	      whether  or  not it is on	the local host,	return-icmp-as-dest is
	      used like	this:

	      block return-icmp-as-dest(port-unr) in proto udp \
		  from any to 192.168.1.0/24

   TCP/UDP Port	Matching
       Having specified	which protocol is being	matched, it is	then  possible
       to indicate which port numbers a	packet must have in order to match the
       rule.  Due to port numbers being	used differently to addresses,	it  is
       therefore  possible to match on them in different ways. IPFilter	allows
       you to use the following	logical	operations:

       < x    is true if the port number is greater than or  equal  to	x  and
	      less than	or equal to y is true if the port number in the	packet
	      is less than x

       <= x   is true if the port number in the	packet is less than  or	 equal
	      to x

       > x    is true if the port number in the	packet is greater than x

       >= x   is  true if the port number in the packet	is greater or equal to
	      x

       = x    is true if the port number in the	packet is equal	to x

       != x   is true if the port number in the	packet is not equal to x

       Additionally, there are a number	of ways	to specify a range of ports:

       x <> y is true if the port number is less than a	and greater than y

       x >< y is true if the port number is greater than x and less than y

       x:y    is true if the port number is greater than or  equal  to	x  and
	      less than	or equal to y

       Some examples of	this are:

       block in	proto tcp from any port	>= 1024	to any port < 1024
       pass in proto tcp from 10.1.0.0/24 to any port =	22
       block out proto udp from	any to 10.1.1.1	port = 135
       pass in proto udp from 1.1.1.1 port = 123 to 10.1.1.1 port = 123
       pass in proto tcp from 127.0.0.0/8 to any port =	6000:6009

       If  there  is  no  desire  to mention any specific source or destintion
       information in a	filter rule then the word "all"	can be used  to	 indi-
       cate that all addresses are considered to match the rule.

   IPv4	or IPv6
       If  a  filter  rule  is constructed without any addresses then IPFilter
       will attempt to match both IPv4 and IPv6	packets	with it. In  the  next
       list  of	 rules,	 each  one  can	 be applied to either network protocol
       because there is	no address specified from which	 IPFilter  can	derive
       with network protocol to	expect.

       pass in proto udp from any to any port =	53
       block in	proto tcp from any port	< 1024 to any

       To explicitly match a particular	network	address	family with a specific
       rule, the family	must be	added to the rule. For IPv4 it is necessary to
       add  family  inet  and  for IPv6, family	inet6. Thus the	next rule will
       block all packets (both IPv4 and	IPv6:

       block in	all

       but in the following example, we	block all IPv4 packets and only	 allow
       in IPv6 packets:

       block in	family inet all
       pass in family inet6 all

       To  continue  on	 from the example where	we allowed either IPv4 or IPv6
       packets to port 53 in, to change	that such that only  IPv6  packets  to
       port  53	need to	allowed	blocked	then it	is possible to add in a	proto-
       col family qualifier:

       pass in family inet6 proto udp from any to any port = 53

   First match vs last match
       To change the default  behaviour	 from  being  the  last	 matched  rule
       decides	the  outcome to	being the first	matched	rule, the word "quick"
       is inserted to the rule.

Extended Packet	Matching
   Beyond using	plain addresses
       On firewalls that are working with large	numbers	of hosts and  networks
       or  simply trying to filter discretely against various hosts, it	can be
       an easier administration	task to	define a pool of addresses and have  a
       filter  rule  reference	that  address pool rather than have a rule for
       each address.

       In addition to being able to use	address	pools, it is possible  to  use
       the  interface  name(s) in the from/to address fields of	a rule.	If the
       name being used in the address section can be matched  to  any  of  the
       interface  names	 mentioned  in the rule's "on" or "via"	fields then it
       can be used with	one of the following keywords for extended effect:

       broadcast use the primary broadcast address of  the  network  interface
	      for matching packets with	this filter rule;

	      pass in on fxp0 proto udp	from any to fxp0/broadcast port	= 123

       peer  use  the  peer  address  on point to point	network	interfaces for
	      matching packets with this filter	rule.  This  option  typically
	      only  has	 meaningful  use  with link protocols such as SLIP and
	      PPP.  For	example, this rule allows ICMP packets from the	remote
	      peer  of ppp0 to be received if they're destined for the address
	      assigned to the link at the firewall end.

	      pass in on ppp0 proto icmp from ppp0/peer	to ppp0/32

       netmasked use the primary network address, with	its  netmask,  of  the
	      network interface	for matching packets with this filter rule. If
	      a	network	interface had an IP address  of	 192.168.1.1  and  its
	      netmask was 255.255.255.0	(/24), then using the word "netmasked"
	      after the	interface name would match any	addresses  that	 would
	      match 192.168.1.0/24. If we assume that bge0 has this IP address
	      and netmask then the following two rules both serve  to  produce
	      the same effect:

	      pass in on bge0 proto icmp from any to 192.168.1.0/24
	      pass in on bge0 proto icmp from any to bge0/netmasked

       network using the primary network address, and its netmask, of the net-
	      work interface, construct	an address for exact  matching.	 If  a
	      network  interface has an	address	of 192.168.1.1 and its netmask
	      is 255.255.255.0,	using this option would	only match packets  to
	      192.168.1.0.

	      pass in on bge0 proto icmp from any to bge0/network

       Another	way  to	use the	name of	a network interface to get the address
       is to wrap the name in ()'s. In the above method, IPFilter looks	at the
       interface names in use and to decide whether or not the name given is a
       hostname	or network interface name. With	the use	of ()'s, it is	possi-
       ble  to	tell  IPFilter	that  the  name	should be treated as a network
       interface name even though it doesn't appear in	the  list  of  network
       interface that the rule ias associated with.

	      pass in proto icmp from any to (bge0)/32

   Using address pools
       Rather  than list out multiple rules that either	allow or deny specific
       addresses, it is	possible to create a single object,  call  an  address
       pool,  that  contains  all of those addresses and reference that	in the
       filter rule. For	documentation on how to	write the  configuration  file
       for those pools and load	them, see ippool.conf(5) and ippool(8).	 There
       are two types of	address	pools that can be defined  in  ippool.conf(5):
       trees  and  hash	 tables. To refer to a tree defined in ippool.conf(5),
       use this	syntax:

       pass in from pool/trusted to any

       Either a	name or	number can be used after the '/', just so long	as  it
       matches	 up   with   something	 that  has  already  been  defined  in
       ipool.conf(5) and loaded	in with	ippool(8). Loading a filter rule  that
       references a pool that does not exist will result in an error.

       If  hash	tables have been used in ippool.conf(5)	to store the addresses
       in instead of a tree, then replace the word pool	with hash:

	      pass in from any to hash/webservers

       There are different operational characteristics with each, so there may
       be  some	situations where a pool	works better than hash and vice	versa.

   Matching TCP	flags
       The TCP header contains a field of flags	that is	used to	decide if  the
       packet  is a connection request,	connection termination,	data, etc.  By
       matching	on the flags in	conjunction with port numbers, it is  possible
       to restrict the way in which IPFilter allows connections	to be created.
       A quick overview	of the TCP flags is below. Each	 is  listed  with  the
       letter  used  in	 IPFilter  rules, followed by its three	or four	letter
       pneumonic.

       S SYN - this bit	is set when a host is setting up  a  connection.   The
	      initiator	 typically  sends  a  packet  with the SYN bit and the
	      responder	sends back SYN plus ACK.

       A ACK - this bit	is set when  the  sender  wishes  to  acknowledge  the
	      receipt of a packet from another host

       P PUSH -	this bit is set	when a sending host has	send some data that is
	      yet to be	acknowledged and a reply is sought

       F FIN - this bit	is set when one	end of a connection  starts  to	 close
	      the connection down

       U  URG  -  this	bit is set to indicate that the	packet contains	urgent
	      data

       R RST - this bit	is set only in packets that are	 a  reply  to  another
	      that has been received but is not	targetted at any open port

       C CWN

       E ECN

       When  matching  TCP  flags, it is normal	to just	list the flag that you
       wish to be set. By default the set of flags it is compared  against  is
       "FSRPAU".  Rules	 that say "flags S" will be displayed by ipfstat(8) as
       having "flags S/FSRPAU".	This is	normal.	 The last two flags,  "C"  and
       "E", are	optional - they	may or may not be used by an end host and have
       no bearing on either the	acceptance of data nor control of the  connec-
       tion.  Masking  them out	with "flags S/FSRPAUCE"	may cause problems for
       remote hosts making a successful	connection.

       pass in quick proto tcp from any	to any port = 22 flags S/SAFR
       pass out	quick proto tcp	from any port =	22 to any flags	SA

       By itself, filtering based on the TCP flags becomes more	work but  when
       combined	with stateful filtering	(see below), the situation changes.

   Matching on ICMP header information
       The  TCP	 and UDP are not the only protocols for	which filtering	beyond
       just the	IP header is possible, extended	matching on  ICMP  packets  is
       also  available.	 The list of valid ICMP	types is different for IPv4 vs
       IPv6.

       As a practical example, to allow	the ping command  to  work  against  a
       specific	 target	requires allowing two different	types of ICMP packets,
       like this:

       pass in proto icmp from any to webserver	icmp-type echo
       pass out	proto icmp from	webserver to any icmp-type echorep

       The ICMP	header has two fields that are of interest for filtering:  the
       ICMP type and code. Filter rules	can accept either a name or number for
       both the	type and code. The list	of names supported for ICMP  types  is
       listed  below,  however	only  ICMP unreachable errors have named codes
       (see above.)

       The list	of ICMP	types that are available for matching an  IPv4	packet
       are as follows:

       echo   (echo  request),	echorep	 (echo	reply),	 inforeq  (information
       request), inforep (information reply), maskreq (mask request),  maskrep
       (mask reply), paramprob (parameter problem), redir (redirect), routerad
       (router advertisement), routersol  (router  solicit),  squence  (source
       quence),	 timest	 (timestamp), timestreq	(timestamp reply), timex (time
       exceeded), unreach (unreachable).

       The list	of ICMP	types that are available for matching an  IPv6	packet
       are as follows:

       echo (echo request), echorep (echo reply), fqdnquery (FQDN query), fqd-
       nreply (FQDN reply), inforeq (information request),  inforep  (informa-
       tion  reply),  listendone (MLD listener done), listendqry (MLD listener
       query),	listendrep  (MLD  listener  reply),   neighadvert   (neighbour
       advert),	 neighborsol  (neighbour  solicit), paramprob (parameter prob-
       lem), redir (redirect), renumber	(router	renumbering), routerad (router
       advertisement),	routersol  (router  solicit),  timex  (time exceeded),
       toobig (packet too big),	unreach	(unreachable,  whoreq  (WRU  request),
       whorep (WRU reply).

Stateful Packet	Filtering
       Stateful	 packet	filtering is where IPFilter remembers some information
       from one	or more	packets	that it	has seen and is	able to	 apply	it  to
       future packets that it receives from the	network.

       What  this  means  for each transport layer protocol is different.  For
       TCP it means that if IPFilter sees the very first packet	of an  attempt
       to make a connection, it	has enough information to allow	all other sub-
       sequent packets without there needing to	be any explicit	rules to match
       them.  IPFilter	uses  the TCP port numbers, TCP	flags, window size and
       sequence	numbers	to determine which packets should be matched. For UDP,
       only  the UDP port numbers are available.  For ICMP, the	ICMP types can
       be combined with	the ICMP id field to  determine	 which	reply  packets
       match  a	request/query that has already been seen. For all other	proto-
       cols, only matching on IP address and protocol number is	available  for
       determining if a	packet received	is a mate to one that has already been
       let through.

       The difference this makes is a reduction	in the number of rules from  2
       or 4 to 1. For example, these 4 rules:

       pass in on bge0 proto tcp from any to any port =	22
       pass out	on bge1	proto tcp from any to any port = 22
       pass in on bge1 proto tcp from any port = 22 to any
       pass out	on bge0	proto tcp from any port	= 22 to	any

       can be replaced with this single	rule:

       pass in on bge0 proto tcp from any to any port =	22 flags S keep	state

       Similar rules for UDP and ICMP might be:

       pass in on bge0 proto udp from any to any port =	53 keep	state
       pass in on bge0 proto icmp all icmp-type	echo keep state

       When  using  stateful filtering with TCP	it is best to add "flags S" to
       the rule	to ensure that state is	only created when  a  packet  is  seen
       that is an indication of	a new connection. Although IPFilter can	gather
       some information	from packets in	the middle of a	TCP connection	to  do
       stateful	 filtering,  there  are	some options that are only sent	at the
       start of	the connection which  alter  the  valid	 window	 of  what  TCP
       accepts.	The end	result of trying to pickup TCP state in	mid connection
       is that some later packets that are part	 of  the  connection  may  not
       match  the  known  state	information and	be dropped or blocked, causing
       problems. If a TCP packet matches IP addresses  and  port  numbers  but
       does  not  fit into the recognised window, it will not be automatically
       allowed and will	be flagged inside  of  IPFitler	 as  "out  of  window"
       (oow).  See  below, "Extra packet attributes", for how to match on this
       attribute.

       Once a TCP connection has reached the established  state,  the  default
       timeout	allows	for it to be idle for 5	days before it is removed from
       the state table.	The timeouts for the other TCP connection states  vary
       from  240  seconds to 30	seconds.  Both UDP and ICMP state entries have
       asymetric timeouts where	the timeout set	upon  seeing  packets  in  the
       forward	direction  is  much larger than	for the	reverse	direction. For
       UDP the default timeouts	are 120	and 12 seconds,	for ICMP 60 and	6 sec-
       onds. This is a reflection of the use of	these protocols	being more for
       query-response than for ongoing connections.  For all  other  protocols
       the timeout is 60 seconds in both directions.

   Stateful filtering options
       The following options can be used with stateful filtering:

       limit limit the number of state table entries that this rule can	create
	      to the number given after	limit. A rule that has a limit	speci-
	      fied  is always permitted	that many state	table entries, even if
	      creating an additional entry would cause the table to have  more
	      entries than the otherwise global	limit.

	      pass ... keep state(limit	100)

       age  sets  the  timeout	for the	state entry when it sees packets going
	      through it. Additionally it is possible to set  the  tieout  for
	      the  reply packets that come back	through	the firewall to	a dif-
	      ferent value than	for the	forward	path. allowing a short timeout
	      to  be set after the reply has been seen and the state no	longer
	      required.

	      pass in quick proto icmp all icmp-type echo \
		  keep state (age 3)
	      pass in quick proto udp from any \
		  to any port =	53 keep	state (age 30/1)

       strict only has an impact when used with	TCP.  It  forces  all  packets
	      that  are	 allowed through the firewall to be sequential:	no out
	      of order delivery	of packets is allowed. This can	cause signifi-
	      cant  slowdown  for  some	 connections and may stall others. Use
	      with caution.

	      pass in proto tcp	... keep state(strict)

       noicmperr prevents ICMP error packets from being	able  to  match	 state
	      table  entries  created with this	flag using the contents	of the
	      original packet included.

	      pass ... keep state(noicmperr)

       sync indicates to IPFilter that it needs	to provide information to  the
	      user  land  daemons responsible for syncing other	machines state
	      tables up	with this one.

	      pass ... keep state(sync)

       nolog do	not generate any log records for the creation or  deletion  of
	      state table entries.

	      pass ... keep state(nolog)

       icmp-head  rather  than just precent ICMP error packets from being able
	      to match state table entries, allow an ACL to be processed  that
	      can  filter in or	out ICMP error packets based as	you would with
	      normal firewall rules.  The icmp-head option requires  a	filter
	      rule  group  number or name to be	present, just as you would use
	      with head.

	      pass in quick proto tcp ... keep state(icmp-head 101)
	      block in proto icmp from 10.0.0.0/8 to any group 101

       max-srcs	allows the number of distinct hosts that can  create  a	 state
	      entry to be defined.

	      pass ... keep state(max-srcs 100)
	      pass ... keep state(limit	1000, max-srcs 100)

       max-per-src  whilst max-srcs limits the number of individual hosts that
	      may cause	the creation of	a state	table entry, each one of those
	      hosts is still table to fill up the state	table with new entries
	      until the	global maximum is reached. This	option allows the num-
	      ber of state table entries per address to	be limited.

	      pass ... keep state(max-srcs 100,	max-per-src 1)
	      pass ... keep state(limit	100, max-srcs 100, max-per-src 1)

	      Whilst  these  two rules might seem identical, in	that they both
	      ultimately limit the number of hosts  and	 state	table  entries
	      created  from the	rule to	100, there is a	subtle difference: the
	      second will always allow up to 100 state	table  entries	to  be
	      created  whereas	the  first may not if the state	table fills up
	      from other rules.

	      Further, it is possible to specify a netmask size	after the per-
	      host  limit that enables the per-host limit to become a per-sub-
	      net or per-network limit.

	      pass ... keep state(max-srcs 100,	max-per-src 1/24)

	      If there is no IP	protocol implied by addresses  or  other  fea-
	      tures  of	 the  rule, IPFilter will assume that no netmask is an
	      all ones netmask for both	IPv4 and IPv6.

   Tieing down a connection
       For any connection that transits	a firewall, each packet	will  be  seen
       twice:  once going in and once going out. Thus a	connection has 4 flows
       of packets:

       forward inbound packets

       forward outbound	packets

       reverse inbound packets

       reverse outbound	packets

       IPFilter	allows you to define the network interface to be used  at  all
       four  points in the flow	of packets. For	rules that match inbound pack-
       ets, out-via is used to specify which interfaces	the  packets  go  out,
       For  rules  that	 match	outbound  packets, in-via is used to match the
       inbound packets.	 In each case, the syntax generalises to this:

       pass ...	in on forward-in,reverse-in \
	      out-via forward-out,reverse-out ...

       pass ...	out on forward-out,reverse-out \
		in-via forward-in,reverse-in ...

       An example that pins down all 4 network interfaces used by an ssh  con-
       nection might look something like this:

       pass in on bge0,bge1 out-via bge1,bge0 proto tcp	\
	   from	any to any port	= 22 flags S keep state

   Working with	packet fragments
       Fragmented packets result in 1 packet containing	all of the layer 3 and
       4 header	information whilst the data is split across a number of	 other
       packets.

       To  enforce access control on fragmented	packets, one of	two approaches
       can be taken. The first is to allow through all of the  data  fragments
       (those that made	up the body of the original packet) and	rely on	match-
       ing the header information in the "first" fragment, when	 it  is	 seen.
       The  reception  of  body	fragments without the first will result	in the
       receiving host being unable to completely  reassemble  the  packet  and
       discarding  all	of  the	 fragments. The	following three	rules deny all
       fragmented packets from being received except those that	 are  UDP  and
       even then only allows those destined for	port 2049 to be	completed.

       block in	all with frags
       pass in proto udp from any to any with frag-body
       pass in proto udp from any to any port =	2049 with frags

       Another mechanism that is available is to track "fragment state".  This
       relies on the first fragment of a packet	that arrives to	be  the	 frag-
       ment  that  contains all	of the layer 3 and layer 4 header information.
       With the	receipt	of that	fragment before	any other, it is  possible  to
       determine which other fragments are to be allowed through without need-
       ing to explicitly allow all fragment body packets.  An example  of  how
       this is done is as follows:

       pass in proto udp from any prot = 2049 to any with frags	keep fags

Building a tree	of rules
       Writing your filter rules as one	long list of rules can be both ineffi-
       cient in	terms of processing the	rules and difficult to understand.  To
       make  the  construction of filter rules easier, it is possible to place
       them in groups.	A rule can be both a member of a group and the head of
       a new group.

       Using filter groups requires at least two rules:	one to be in the group
       one one to send matchign	packets	to the group. If a  packet  matches  a
       filtre rule that	is a group head	but does not match any of the rules in
       that group, then	the packet is considered  to  have  matched  the  head
       rule.

       Rules  that  are	a member of a group contain the	word group followed by
       either a	name or	number that defines which group	they're	in. Rules that
       form the	branch point or	starting point for the group must use the word
       head, followed by either	a group	name or	number.	If rules are loaded in
       that define a group but there is	no matching head then they will	effec-
       tively be orphaned rules. It is possible	to have	 more  than  one  head
       rule  point  to the same	group, allowing	groups to be used like subrou-
       tines to	implement specific common policies.

       A common	use of filter groups is	to define head rules that exist	in the
       filter  "main  line" for	each direction with the	interfaces in use. For
       example:

       block in	quick on bge0 all head 100
       block out quick on bge0 all head	101
       block in	quick on fxp0 all head internal-in
       block out quick on fxp0 all head	internal-out
       pass in quick proto icmp	all icmp-type echo group 100

       In the above set	of rules, there	are four groups	defined	but  only  one
       of  them	 has  a	 member	 rule.	The only packets that would be allowed
       through the above ruleset would be ICMP echo packets that are  received
       on bge0.

       Rules  can  be  both  a	member of a group and the head of a new	group,
       allowing	groups to specialise.

       block in	quick on bge0 all head 100
       block in	quick proto tcp	all head 1006 group 100

       Another use of filter rule groups is to provide a place for rules to be
       dynamically  added without needing to worry about their specific	order-
       ing amongst the entire ruleset. For example, if I was using this	simple
       ruleset:

       block in	quick all with bad
       block in	proto tcp from any to any port = smtp head spammers
       pass in quick proto tcp from any	to any port = smtp flags S keep	state

       and  I was getting lots of connections to my email server from 10.1.1.1
       to deliver spam,	I could	load the  following  rule  to  complement  the
       above:

	      block in quick from 10.1.1.1 to any group	spammers

   Decapsulation
       Rule  groups  also  form	 a  different but vital	role for decapsulation
       rules.  With the	following simple rule,	if  IPFilter  receives	an  IP
       packet  that  has  an  AH header	as its layer 4 payload,	IPFilter would
       adjust its view of the packet internally	and then jump  to  group  1001
       using the data beyond the AH header as the new transport	header.

       decapsulate in proto ah all head	1001

       For protocols that are recognised as being used with tunnelling or oth-
       erwise encapsulating IP protocols, IPFilter is able to decide  what  it
       has on the inside without any assistance. Some tunnelling protocols use
       UDP as the transport mechanism.	In  this  case,	 it  is	 necessary  to
       instruct	IPFilter as to what protocol is	inside UDP.

       decapsulate l5-as(ip) in	proto udp from any \
	   to any port = 1520 head 1001

       Currently IPFilter only supports	finding	IPv4 and IPv6 headers directly
       after the UDP header.

       If a packet matches a decapsulate rule but fails	to match  any  of  the
       rules  that  are	 within	 the specified group, processing of the	packet
       continues to the	next rule after	the decapsulate	and IPFilter's	inter-
       nal view	of the packet is returned to what it was prior to the decapsu-
       late rule.

       It is possible to construct a decapsulate rule without the  group  head
       at  the	end  that ipf(8) will accept but such rules will not result in
       anything	happening.

   Policy Based	Routing
       With firewalls being in the position they often are, at the boundary of
       different  networks  connecting	together and multiple connections that
       have different properties, it is	often desirable	to have	 packets  flow
       in  a  direction	different to what the routing table instructs the ker-
       nel.  These decisions can often be extended to changing the route based
       on both source and destination address or even port numbers.

       To  support  this  kind	of configuration, IPFilter allows the next hop
       destination to be specified with	a filter rule. The next	hop  is	 given
       with  the  interface  name  to  use  for	output.	The syntax for this is
       interface:ip.address. It	is expected that the address given as the next
       hop is directly connected to the	network	to which the interface is.

       pass in on bge0 to bge1:1.1.1.1 proto tcp \
	   from	1.1.2.3	to any port = 80 flags S keep state

       When  this feature is combined with stateful filtering, it becomes pos-
       sible to	influence the network interface	used to	 transmit  packets  in
       both  directions	 because we now	have a sense for what its reverse flow
       of packets is.

       pass in on bge0 to bge1:1.1.1.1 reply-to	hme1:2.1.1.2 \
	   proto tcp from 1.1.2.3 to any port =	80 flags S keep	state

       If the actions of the routing table are perfectly acceptable,  but  you
       would like to mask the presence of the firewall by not changing the TTL
       in IP packets as	they transit it, IPFilter can be instructed  to	 do  a
       "fastroute" action like this:

       pass in on bge0 fastroute proto icmp all

       This  should  be	 used  with  caution  as it can	lead to	endless	packet
       loops. Additionally, policy  based  routing  does  not  change  the  IP
       header's	TTL value.

       A  variation  on	this type of rule supports a duplicate of the original
       packet being created and	sent out a different network. This can be use-
       ful for monitoring traffic and other purposes.

       pass in on bge0 to bge1:1.1.1.1 reply-to	hme1:2.1.1.2 \
	   dup-to fxp0:10.0.0.1	proto tcp from 1.1.2.3 \
	   to any port = 80 flags S keep state

   Matching IPv4 options
       The  design  for	 IPv4  allows for the header to	be upto	64 bytes long,
       however most traffic only uses the basic	header which is	20 bytes long.
       The  other  44 bytes can	be uesd	to store IP options. These options are
       generally not necessary for proper  interaction	and  function  on  the
       Internet	 today.	For most people	it is sufficient to block and drop all
       packets that have any options set. This can be achieved with this rule:

       block in	quick all with ipopts

       This  rule  is  usually	placed towards the top of the configuration so
       that all	incoming packets are blocked.

       If you wanted to	allow in a specific IP option type, the	syntax changes
       slightly:

       pass in quick proto igmp	all with opt rtralrt

       The  following  is  a list of IP	options	that most people encounter and
       what their use/threat is.

       lsrr (loose source route) the sender of the packet includes a  list  of
	      addresses	 that  they wish the packet to be routed through to on
	      the way to the destination. Because replies to such packets  are
	      expected	to  use	 the list of addresses in reverse, hackers are
	      able to very effectively	use  this  header  option  in  address
	      spoofing attacks.

       rr  (record route) the sender allocates some buffer space for recording
	      the IP address of	each router that the packet goes through. This
	      is most often used with ping, where the ping response contains a
	      copy of all addresses from  the  original	 packet,  telling  the
	      sender  what  route the packet took to get there.	Due to perfor-
	      mance and	security issues	with IP	header options,	this is	almost
	      no longer	used.

       rtralrt	(router	alert) this option is often used in IGMP messages as a
	      flag to routers that the packet needs to be handled differently.
	      It  is  unlikely	to ever	be received from an unknown sender. It
	      may be found on LANs or otherwise	controlled networks where  the
	      RSVP protocol and	multicast traffic is in	heavy use.

       ssrr  (strict source route) the sender of the packet includes a list of
	      addresses	that they wish the packet to be	routed through	to  on
	      the  way	to  the	 destination. Where the	lsrr option allows the
	      sender to	specify	only some of the  nodes	 the  packet  must  go
	      through,	with  the  ssrr	 option, every next hop	router must be
	      specified.

       The complete list of IPv4 options that can be  matched  on  is:	addext
       (Address	Extention), cipso (Classical IP	Security Option), dps (Dynamic
       Packet State), e-sec (Extended Security), eip (Extended Internet	Proto-
       col),  encode  (ENCODE),	 finn  (Experimental Flow Control), imitd (IMI
       Traffic Descriptor), lsrr (Loose	Source Route), mtup (MTU Probe - obso-
       lete),  mtur (MTU response - obsolete), nop (No Operation), nsapa (NSAP
       Address), rr (Record Route),  rtralrt  (Router  Alert),	satid  (Stream
       Identifier),  sdb  (Selective Directed Broadcast), sec (Security), ssrr
       (Strict Source Route), tr (Tracerote), ts  (Timestamp),	ump  (Upstream
       Multicast  Packet), visa	(Experimental Access Control) and zsu (Experi-
       mental Measurement).

   Security with CIPSO and IPSO
       IPFilter	supports filtering on IPv4 packets using  security  attributes
       embedded	 in  the IP options part of the	packet.	These options are usu-
       ally only used on networks and systems that are using lablled security.
       Unless  you know	that you are using labelled security and your network-
       ing is also labelled, it	is highly unlikely that	this section  will  be
       relevant	to you.

       With  the traditional IP	Security Options (IPSO), packets can be	tagged
       with a security level. The following keywords are recognised and	 match
       with  the relevant RFC with respect to the bit patterns matched:	confid
       (confidential), rserve-1	(1st reserved value), rserve-2	(2nd  reserved
       value),	rserve-3  (3rd reserved	value),	rserve-4 (4th reserved value),
       secret (secret),	topsecret (top secret),	unclass	(unclassified).

       block in	quick all with opt sec-class unclass
       pass in all with	opt sec-class secret

   Matching IPv6 extension headers
       Just as it is possible to filter	on the various IPv4 header options, so
       too  it	is  possible  to filter	on the IPv6 extension headers that are
       placed between the IPv6 header and the transport	protocol header.

       dstopts (destination options), esp (encrypted, secure,  payload),  frag
       (fragment),  hopopts (hop-by-hop	options), ipv6 (IPv6 header), mobility
       (IP mobility), none, routing.

   Logging
       There are two ways in which packets can be logged  with	IPFilter.  The
       first  is with a	rule that specifically says log	these types of packets
       and the second is a qualifier to	one of the other keywords. Thus	it  is
       possible	to both	log and	allow or deny a	packet with a single rule.

       pass in log quick proto tcp from	any to any port	= 22

       When  using  stateful  filtering,  the  log  action becomes part	of the
       result that is remembered about a packet. Thus if the  above  rule  was
       qualified  with	keep  state,  every  packet in the connection would be
       logged. To only log the first packet from  every	 packet	 flow  tracked
       with  keep state, it is necessary to indicate to	IPFilter that you only
       wish to log the first packet.

       pass in log first quick proto tcp from any to any port =	22 \
	   flags S keep	state

       If it is	a requirement that the logging provide an accurate representa-
       tion  of	which connections are allowed, the log action can be qualified
       with the	option or-block. This allows  the  administrator  to  instruct
       IPFilter	 to  block  the	 packet	if the attempt to record the packet in
       IPFilter's kernel log records (which  have  an  upper  bound  on	 size)
       failed.	Unless	the system shuts down or reboots, once a log record is
       written into the	kernel buffer, it is there until ipmon(8) reads	it.

       block in	log proto tcp from any to any port = smtp
       pass in log or-block first quick	proto tcp from any \
	   to any port = 22 flags S keep state

       By default, IPFilter will only log  the	header	portion	 of  a	packet
       received	 on  the  network. A portion of	the body of a packet, upto 128
       bytes, can also be logged with the body keyword.	ipmon(8) will  display
       the contents of the portion of the body logged in hex.

       block in	log body proto icmp all

       When  logging packets from ipmon(8) to syslog, by default ipmon(8) will
       control what syslog facility and	priority a packet will be logged with.
       This can	be tuned on a per rule basis like this:

       block in	quick log level	err all	with bad
       pass in log level local1.info proto tcp \
	   from	any to any port	= 22 flags S keep state

       ipfstat(8)  reports  how	many packets have been successfully logged and
       how many	failed attempts	to log a packet	there were.

   Filter rule comments
       If there	is a desire to associate a text	string,	be it  an  administra-
       tive  comment or	otherwise, with	an IPFilter rule, this can be achieved
       by giving the filter rule a comment.  The comment is  loaded  with  the
       rule  into  the	kernel	and can	be seen	when the rules are listed with
       ipfstat.

       pass in quick proto tcp from any	\
	   to port = 80	comment	"all web server	traffic	is ok"
       pass out	quick proto tcp	from any port =	80 \
	   to any comment "all web server traffic is ok"

   Tags
       To enable filtering and NAT to correctly	match up packets  with	rules,
       tags  can be added at with NAT (for inbound packets) and	filtering (for
       outbound	packets.) This allows a	filter to be correctly mated with  its
       NAT  rule  in  the  event that the NAT rule changed the packet in a way
       that would mean it is not obvious what it was.

       For inbound packets, IPFilter can match the  tag	 used  in  the	filter
       rules  with that	set by NAT. For	outbound rules,	it is the reverse, the
       filter sets the tag and the NAT rule matches up with it.

       pass in ... match-tag(nat=proxy)
       pass out	... set-tag(nat=proxy)

       Another use of tags is to supply	a number that is only used  with  log-
       ging.  When packets match these rules, the log tag is carried over into
       the log file records generated by ipmon(8). With	 the  correct  use  of
       tools such as grep, extracting log records of interest is simplified.

       block in	quick log ... set-tag(log=33)

Filter Rule Expiration
       IPFilter	 allows	 rules to be added into	the kernel that	it will	remove
       after a specific	period of time by specifying rule-ttl at the end of  a
       rule.   When  listing  rules in the kernel using	ipfstat(8), rules that
       are going to expire will	 NOT  display  "rule-ttl"  with	 the  timeout,
       rather what will	be seen	is a comment with how many ipfilter ticks left
       the rule	has to live.

       The time	to live	is specified in	seconds.

       pass in on fxp0 proto tcp from any \
	   to port = 22	flags S	keep state rule-ttl 30

Internal packet	attributes
       In addition to being able to filter on very specific network and	trans-
       port  header  fields, it	is possible to filter on other attributes that
       IPFilter	attaches to a packet. These attributes are placed  in  a  rule
       after  the  keyword  "with",  as	 can  be seen with frags and frag-body
       above. The following is a list of the other attributes available:

       oow the packet's	IP addresses and TCP ports match an existing entry  in
	      the  state  table	 but  the sequence numbers indicate that it is
	      outside of the accepted window.

	      block return-rst in quick	proto tcp from any to any with not oow

       bcast this is set by IPFilter when it receives  notification  that  the
	      link  layer packet was a broadcast packet. No checking of	the IP
	      addresses	is performned to determine if it is a broadcast	desti-
	      nation or	not.

	      block in quick proto udp all with	bcast

       mcast  this  is	set by IPFilter	when it	receives notification that the
	      link layer packet	was a multicast	packet.	No checking of the  IP
	      addresses	is performned to determine if it is a multicast	desti-
	      nation or	not.

	      pass in quick proto udp from any to any port = dns with mcast

       mbcast can be used to match a packet that  is  either  a	 multicast  or
	      broadcast	 packet	at the link layer, as indicated	by the operat-
	      ing system.

	      pass in quick proto udp from any to any port = ntp with mbcast

       nat the packet positively matched a NAT table entry.

       bad sanity checking of the packet failed. This could indicate that  the
	      layer 3/4	headers	are not	properly formed.

       bad-src	when  reverse  path verification is enabled, this flag will be
	      set when the interface the packet	is received on does not	 match
	      that  which  would be used to send a packet out of to the	source
	      address in the received packet.

       bad-nat an attempt to perform NAT on the	packet failed.

       not each	one of the attributes matched using  the  "with"  keyword  can
	      also be looked for to not	be present. For	example, to only allow
	      in good packets, I can do	this:

       block in	all
       pass in all with	not bad

Tuning IPFilter
       The ipf.conf file can also be used to tune the behaviour	 of  IPFilter,
       allowing,  for  example,	 timeouts for the NAT/state table(s) to	be set
       along with their	sizes. The presence and	names of tunables  may	change
       from  one  release  of  IPFilter	 to the	next. The tunables that	can be
       changed via ipf.conf is the same	as those that can be seen and modified
       using the -T command line option	to ipf(8).

       NOTE:  When  parsing  ipf.conf,	ipf(8)	will apply the settings	before
       loading any rules. Thus if your settings	are at the top,	these  may  be
       applied	whilst the rules not applied if	there is an error further down
       in the configuration file.

       To set one of the values	below, the syntax is simple:  "set",  followed
       by the name of the tuneable to set and then the value to	set it to.

       set state_max 9999;
       set state_size 10101;

       A list of the currently available variables inside IPFilter that	may be
       tuned from ipf.conf are as follows:

       active set through -s command line switch of  ipf(8).  See  ipf(8)  for
	      detals.

       chksrc  when set, enables reverse path verification on source addresses
	      and for filters to match packets with bad-src attribute.

       control_forwarding when set turns off kernel forwarding	when  IPFilter
	      is disabled or unloaded.

       default_pass  the  default  policy  -  whether  packets	are blocked or
	      passed, etc - is represented by the value	of this	 variable.  It
	      is  a  bit  field	 and  the  bits	 that  can be set are found in
	      <netinet/ip_fil.h>. It is	not recommended	 to  tune  this	 value
	      directly.

       ftp_debug  set  the  debugging level of the in-kernel FTP proxy.	 Debug
	      messages will be printed to the system console.

       ftp_forcepasv when set the FTP  proxy  must  see	 a  PASV/EPSV  command
	      before creating the state/NAT entries for	the 227	response.

       ftp_insecure  when  set the FTP proxy will not wait for a user to login
	      before allowing data connections to be created.

       ftp_pasvonly when set the proxy will not	create state/NAT  entries  for
	      when it sees either the PORT or EPRT command.

       ftp_pasvrdr  when  enabled causes the FTP proxy to create very insecure
	      NAT/state	entries	that will allow	 any  connection  between  the
	      client  and  server  hosts  when	a 227 reply is seen.  Use with
	      extreme caution.

       ftp_single_xfer when set	the FTP	proxy will only	allow one data connec-
	      tion at a	time.

       hostmap_size  sets  the	size of	the hostmap table used by NAT to store
	      address mappings for use with sticky rules.

       icmp_ack_timeout	default	timeout	used for ICMP NAT/state	when  a	 reply
	      packet is	seen for an ICMP state that already exists

       icmp_minfragmtu	sets  the minimum MTU that is considered acceptable in
	      an ICMP error before deciding it is a bad	packet.

       icmp_timeout default timeout used for ICMP NAT/state  when  the	packet
	      matches the rule

       ip_timeout  default  timeout  used  for	NAT/state entries that are not
	      TCP/UDP/ICMP.

       ipf_flags

       ips_proxy_debug this sets the debugging level  for  the	proxy  support
	      code.   When  enabled, debugging messages	will be	printed	to the
	      system console.

       log_all when set	it changes the behaviour of  "log  body"  to  log  the
	      entire packet rather than	just the first 128 bytes.

       log_size	sets the size of the in-kernel log buffer in bytes.

       log_suppress  when  set,	IPFilter will check to see if the packet it is
	      logging is similar to the	one it previously logged  and  if  so,
	      increases	 the  occurance	 count for that	packet.	The previously
	      logged packet must not have yet been read	by ipmon(8).

       min_ttl is used to set the TTL value that packets below will be	marked
	      with the low-ttl attribute.

       nat_doflush  if	set it will cause the NAT code to do a more aggressive
	      flush of the NAT table at	the next opportunity. Once  the	 flush
	      has been done, the value is reset	to 0.

       nat_lock	this should only be changed using ipfs(8)

       nat_logging when	set, NAT will create log records that can be read from
	      /dev/ipnat.

       nat_maxbucket maximum number of entries allowed to exist	 in  each  NAT
	      hash  bucket.   This  prevents an	attacker trying	to load	up the
	      hash table with entries in a  single  bucket,  reducing  perfor-
	      mance.

       nat_rules_size size of the hash table to	store map rules.

       nat_table_max maximum number of entries allowed into the	NAT table

       nat_table_size size of the hash table used for NAT

       nat_table_wm_high  when	the  fill  percentage of the NAT table exceeds
	      this mark, more aggressive flushing is enabled.

       nat_table_wm_low	this sets the percentage  at  which  the  NAT  table's
	      agressive	flushing will turn itself off at.

       rdr_rules_size size of the hash table to	store rdr rules.

       state_lock this should only be changed using ipfs(8)

       state_logging  when set,	the stateful filtering will create log records
	      that can be read from /dev/ipstate.

       state_max maximum number	of entries allowed into	the state table

       state_maxbucket maximum number of entries  allowed  to  exist  in  each
	      state  hash bucket.  This	prevents an attacker trying to load up
	      the hash table with entries in a single bucket, reducing perfor-
	      mance.

       state_size size of the hash table used for stateful filtering

       state_wm_freq  this controls how	often the agressive flushing should be
	      run once the state table	exceeds	 state_wm_high	in  percentage
	      full.

       state_wm_high  when the fill percentage of the state table exceeds this
	      mark, more aggressive flushing is	enabled.

       state_wm_low this sets the percentage at	which the state	table's	agres-
	      sive flushing will turn itself off at.

       tcp_close_wait  timeout	used  when  a  TCP  state  entry  reaches  the
	      FIN_WAIT_2 state.

       tcp_closed timeout used when a TCP state	entry is ready to  be  removed
	      after either a RST packet	is seen.

       tcp_half_closed	timeout	 used  when  a	TCP  state  entry  reaches the
	      CLOSE_WAIT state.

       tcp_idle_timeout	timeout	used when a TCP	state entry reaches the	ESTAB-
	      LISHED state.

       tcp_last_ack  timeout  used  when  a  TCP  NAT/state  entry reaches the
	      LAST_ACK state.

       tcp_syn_received	timeout	applied	to a TCP NAT/state entry after SYN-ACK
	      packet has been seen.

       tcp_syn_sent  timeout applied to	a TCP NAT/state	entry after SYN	packet
	      has been seen.

       tcp_time_wait timeout used when	a  TCP	NAT/state  entry  reaches  the
	      TIME_WAIT	state.

       tcp_timeout  timeout used when a	TCP NAT/state entry reaches either the
	      half established state (one ack is seen after a SYN-ACK) or  one
	      side is in FIN_WAIT_1.

       udp_ack_timeout	default	 timeout  used	for UDP	NAT/state when a reply
	      packet is	seen for a UDP state that already exists

       udp_timeout default timeout used	for  UDP  NAT/state  when  the	packet
	      matches the rule

       update_ipid  when set, turns on changing	the IP id field	in NAT'd pack-
	      ets to a random number.

   Table of visible variables
       A list of all of	the tunables, their minimum, maximum and current  val-
       ues is as follows.

       Name		   Min	Max  Current
       active		   0	0    0
       chksrc		   0	1    0
       control_forwarding  0	1    0
       default_pass	   0	MAXUINT	  134217730
       ftp_debug	   0	10   0
       ftp_forcepasv	   0	1    1
       ftp_insecure	   0	1    0
       ftp_pasvonly	   0	1    0
       ftp_pasvrdr	   0	1    0
       ftp_single_xfer	   0	1    0
       hostmap_size	   1	MAXINT	  2047
       icmp_ack_timeout	   1	MAXINT	  12
       icmp_minfragmtu	   0	1    68
       icmp_timeout	   1	MAXINT	  120
       ip_timeout	   1	MAXINT	  120
       ipf_flags	   0	MAXUINT	  0
       ips_proxy_debug	   0	10   0
       log_all		   0	1    0
       log_size		   0	524288	  32768
       log_suppress	   0	1    1
       min_ttl		   0	1    4
       nat_doflush	   0	1    0
       nat_lock		   0	1    0
       nat_logging	   0	1    1
       nat_maxbucket	   1	MAXINT	  22
       nat_rules_size	   1	MAXINT	  127
       nat_table_max	   1	MAXINT	  30000
       nat_table_size	   1	MAXINT	  2047
       nat_table_wm_high   2	100  99
       nat_table_wm_low	   1	99   90
       rdr_rules_size	   1	MAXINT	  127
       state_lock	   0	1    0
       state_logging	   0	1    1
       state_max	   1	MAXINT	  4013
       state_maxbucket	   1	MAXINT	  26
       state_size	   1	MAXINT	  5737
       state_wm_freq	   2	999999	  20
       state_wm_high	   2	100  99
       state_wm_low	   1	99   90
       tcp_close_wait	   1	MAXINT	  480
       tcp_closed	   1	MAXINT	  60
       tcp_half_closed	   1	MAXINT	  14400
       tcp_idle_timeout	   1	MAXINT	  864000
       tcp_last_ack	   1	MAXINT	  60
       tcp_syn_received	   1	MAXINT	  480
       tcp_syn_sent	   1	MAXINT	  480
       tcp_time_wait	   1	MAXINT	  480
       tcp_timeout	   1	MAXINT	  480
       udp_ack_timeout	   1	MAXINT	  24
       udp_timeout	   1	MAXINT	  240
       update_ipid	   0	1    0

Calling	out to internal	functions
       IPFilter	 provides  a  pair of functions	that can be called from	a rule
       that allow for a	single rule to jump out	to a group  rather  than  walk
       through	a list of rules	to find	the group. If you've got multiple net-
       works, each with	its own	group of rules,	this feature may help  provide
       better filtering	performance.

       The  lookup  to	find which rule	group to jump to is done on either the
       source address or the destination address but not both.

       In this example below, we are blocking all packets by default but  then
       doing  a	lookup on the source address from group	1010. The two rules in
       the ipf.conf section are	lone members of	their group. For  an  incoming
       packet  that  is	 from 1.1.1.1, it will go through three	rules: (1) the
       block rule, (2) the call	rule and (3) the pass  rule  for  group	 1020.
       For a packet that is from 3.3.2.2, it will also go through three	rules:
       (1) the block rule, (2) the call	rule and (3) the pass rule  for	 group
       1030.  Should  a	 packet	 from 3.1.1.1 arrive, it will be blocked as it
       does not	match any of the entries in group 1010,	 leaving  it  to  only
       match the first rule.

       from ipf.conf
       -------------
       block in	all
       call now	srcgrpmap/1010 in all
       pass in proto tcp from any to any port =	80 group 1020
       pass in proto icmp all icmp-type	echo group 1030

       from ippool.conf
       ----------------
       group-map in role=ipf number=1010
	   { 1.1.1.1 group = 1020, 3.3.0.0/16 group = 1030; };

   IPFilter matching expressions
       An  experimental	 feature that has been added to	filter rules is	to use
       the same	expression matching that is available with various commands to
       flush  and  list	state/NAT table	entries. The use of such an expression
       precludes the filter rule from using the	normal IP header matching.

       pass in exp { "tcp.sport	23 or tcp.sport	50" } keep state

   Filter rules	with BPF
       On platforms that have the BPF built into the kernel, IPFilter  can  be
       built  to allow BPF expressions in filter rules.	This allows for	packet
       matching	to be on arbitrary data	in the packt. The use of a BPF expres-
       sion  replaces all of the other protocol	header matching	done by	IPFil-
       ter.

       pass in bpf-v4 {	"tcp and (src port 23 or src port 50)" } \
	   keep	state

       These rules tend	to be write-only because the act of compiling the fil-
       ter  expression	into  the  BPF instructions loaded into	the kernel can
       make it difficut	to accurately reconstruct the  original	 text  filter.
       The  end	 result	 is  that while	ipf.conf() can be easy to read,	under-
       standing	the output from	ipfstat	might not be.

VARIABLES
       This configuration file,	like all others	used with  IPFilter,  supports
       the use of variable substitution	throughout the text.

       nif="ppp0";
       pass in on $nif from any	to any

       would become

       pass in on ppp0 from any	to any

       Variables  can  be used recursively, such as 'foo="$bar baz";', so long
       as $bar exists when the parser reaches the assignment for foo.

       See ipf(8) for instructions on how to define variables to be used  from
       a shell environment.

FILES
       /dev/ipf	/etc/ipf.conf
       /usr/share/examples/ipf	Directory with examples.

SEE ALSO
       ipf(8), ipfstat(8), ippool.conf(5), ippool(8)

									IPF(5)

NAME | DESCRIPTION | Firewall rules | Extended Packet Matching | Stateful Packet Filtering | Building a tree of rules | Filter Rule Expiration | Internal packet attributes | Tuning IPFilter | Calling out to internal functions | VARIABLES | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ipf.conf&sektion=5&manpath=FreeBSD+10.0-RELEASE>

home | help