1.\" $FreeBSD: head/contrib/ipfilter/man/ipf.5 153881 2005-12-30 11:52:26Z guido $
| 1.\" $FreeBSD: head/contrib/ipfilter/man/ipf.5 255332 2013-09-06 23:11:19Z cy $
|
2.TH IPF 5
3.SH NAME
| 2.TH IPF 5
3.SH NAME
|
4ipf, ipf.conf, ipf6.conf \- IP packet filter rule syntax
| 4ipf, ipf.conf \- IPFilter firewall rules file format
|
5.SH DESCRIPTION
6.PP
| 5.SH DESCRIPTION
6.PP
|
7A rule file for \fBipf\fP may have any name or even be stdin. As
8\fBipfstat\fP produces parsable rules as output when displaying the internal
9kernel filter lists, it is quite plausible to use its output to feed back
10into \fBipf\fP. Thus, to remove all filters on input packets, the following
11could be done:
| 7The ipf.conf file is used to specify rules for the firewall, packet
8authentication and packet accounting components of IPFilter. To load rules
9specified in the ipf.conf file, the ipf(8) program is used.
10.PP
11For use as a firewall, there are two important rule types: those that block
12and drop packets (block rules) and those that allow packets through (pass
13rules.) Accompanying the decision to apply is a collection of statements
14that specify under what conditions the result is to be applied and how.
15.PP
16The simplest rules that can be used in ipf.conf are expressed like this:
17.PP
|
12.nf
| 18.nf
|
13
14\fC# ipfstat \-i | ipf \-rf \-\fP
| 19block in all
20pass out all
|
15.fi
| 21.fi
|
16.SH GRAMMAR
| |
17.PP
| 22.PP
|
18The format used by \fBipf\fP for construction of filtering rules can be
19described using the following grammar in BNF:
20\fC
| 23Each rule must contain at least the following three components
24.RS
25.IP *
26a decision keyword (pass, block, etc.)
27.IP *
28the direction of the packet (in or out)
29.IP *
30address patterns or "all" to match any address information
31.RE
32.SS Long lines
33.PP
34For rules lines that are particularly long, it is possible to split
35them over multiple lines implicity like this:
36.PP
|
21.nf
| 37.nf
|
22filter-rule = [ insert ] action in-out [ options ] [ tos ] [ ttl ]
23 [ proto ] ip [ group ].
24
25insert = "@" decnumber .
26action = block | "pass" | log | "count" | skip | auth | call .
27in-out = "in" | "out" .
28options = [ log ] [ tag ] [ "quick" ] [ "on" interface-name [ dup ]
29 [ froute ] [ replyto ] ] .
30tos = "tos" decnumber | "tos" hexnumber .
31ttl = "ttl" decnumber .
32proto = "proto" protocol .
33ip = srcdst [ flags ] [ with withopt ] [ icmp ] [ keep ] .
34group = [ "head" decnumber ] [ "group" decnumber ] .
35
36block = "block" [ return-icmp[return-code] | "return-rst" ] .
37log = "log" [ "body" ] [ "first" ] [ "or-block" ] [ "level" loglevel ] .
38tag = "tag" tagid .
39skip = "skip" decnumber .
40auth = "auth" | "preauth" .
41call = "call" [ "now" ] function-name .
42dup = "dup-to" interface-name [ ":" ipaddr ] .
43froute = "fastroute" | "to" interface-name [ ":" ipaddr ] .
44replyto = "reply-to" interface-name [ ":" ipaddr ] .
45protocol = "tcp/udp" | "udp" | "tcp" | "icmp" | decnumber .
46srcdst = "all" | fromto .
47fromto = "from" [ "!" ] object "to" [ "!" ] object .
48
49return-icmp = "return-icmp" | "return-icmp-as-dest" .
50return-code = "(" icmp-code ")" .
51object = addr [ port-comp | port-range ] .
52addr = "any" | nummask | host-name [ "mask" ipaddr | "mask" hexnumber ] .
53addr = "any" | "<thishost>" | nummask |
54 host-name [ "mask" ipaddr | "mask" hexnumber ] .
55port-comp = "port" compare port-num .
56port-range = "port" port-num range port-num .
57flags = "flags" flag { flag } [ "/" flag { flag } ] .
58with = "with" | "and" .
59icmp = "icmp-type" icmp-type [ "code" decnumber ] .
60return-code = "(" icmp-code ")" .
61keep = "keep" "state" [ "(" state-options ")" ] | "keep" "frags" .
62loglevel = facility"."priority | priority .
63
64nummask = host-name [ "/" decnumber ] .
65host-name = ipaddr | hostname | "any" .
66ipaddr = host-num "." host-num "." host-num "." host-num .
67host-num = digit [ digit [ digit ] ] .
68port-num = service-name | decnumber .
69state-options = state-opts [ "," state-options ] .
70
71state-opts = "age" decnumber [ "/" decnumber ] | "strict" |
72 "no-icmp-err" | "limit" decnumber | "newisn" | "sync" .
73withopt = [ "not" | "no" ] opttype [ withopt ] .
74opttype = "ipopts" | "short" | "frag" | "opt" optname .
75optname = ipopts [ "," optname ] .
76ipopts = optlist | "sec-class" [ secname ] .
77secname = seclvl [ "," secname ] .
78seclvl = "unclass" | "confid" | "reserv-1" | "reserv-2" | "reserv-3" |
79 "reserv-4" | "secret" | "topsecret" .
80icmp-type = "unreach" | "echo" | "echorep" | "squench" | "redir" |
81 "timex" | "paramprob" | "timest" | "timestrep" | "inforeq" |
82 "inforep" | "maskreq" | "maskrep" | decnumber .
83icmp-code = decumber | "net-unr" | "host-unr" | "proto-unr" | "port-unr" |
84 "needfrag" | "srcfail" | "net-unk" | "host-unk" | "isolate" |
85 "net-prohib" | "host-prohib" | "net-tos" | "host-tos" |
86 "filter-prohib" | "host-preced" | "cutoff-preced" .
87optlist = "nop" | "rr" | "zsu" | "mtup" | "mtur" | "encode" | "ts" |
88 "tr" | "sec" | "lsrr" | "e-sec" | "cipso" | "satid" | "ssrr" |
89 "addext" | "visa" | "imitd" | "eip" | "finn" .
90facility = "kern" | "user" | "mail" | "daemon" | "auth" | "syslog" |
91 "lpr" | "news" | "uucp" | "cron" | "ftp" | "authpriv" |
92 "audit" | "logalert" | "local0" | "local1" | "local2" |
93 "local3" | "local4" | "local5" | "local6" | "local7" .
94priority = "emerg" | "alert" | "crit" | "err" | "warn" | "notice" |
95 "info" | "debug" .
96
97hexnumber = "0" "x" hexstring .
98hexstring = hexdigit [ hexstring ] .
99decnumber = digit [ decnumber ] .
100
101compare = "=" | "!=" | "<" | ">" | "<=" | ">=" | "eq" | "ne" | "lt" |
102 "gt" | "le" | "ge" .
103range = "<>" | "><" .
104hexdigit = digit | "a" | "b" | "c" | "d" | "e" | "f" .
105digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" .
106flag = "F" | "S" | "R" | "P" | "A" | "U" .
| 38pass in on bgeo proto tcp from 1.1.1.1 port > 1000
39 to 2.2.2.2 port < 5000 flags S keep state
|
107.fi
108.PP
| 40.fi
41.PP
|
109This syntax is somewhat simplified for readability, some combinations
110that match this grammar are disallowed by the software because they do
111not make sense (such as tcp \fBflags\fP for non-TCP packets).
112.SH FILTER RULES
| 42or explicitly using the backslash ('\\') character:
|
113.PP
| 43.PP
|
114The "briefest" valid rules are (currently) no-ops and are of the form:
| |
115.nf
| 44.nf
|
116 block in all
117 pass in all
118 log out all
119 count in all
| 45pass in on bgeo proto tcp from 1.1.1.1 port > 1000 \\
46 to 2.2.2.2 port < 5000 flags S keep state
|
120.fi
| 47.fi
|
| 48.SS Comments
|
121.PP
| 49.PP
|
122Filter rules are checked in order, with the last matching rule
123determining the fate of the packet (but see the \fBquick\fP option,
124below).
| 50Comments in the ipf.conf file are indicated by the use of the '#' character.
51This can either be at the start of the line, like this:
|
125.PP
| 52.PP
|
126Filters are installed by default at the end of the kernel's filter
127lists, prepending the rule with \fB@n\fP will cause it to be inserted
128as the n'th entry in the current list. This is especially useful when
129modifying and testing active filter rulesets. See ipf(8) for more
130information.
131.SH ACTIONS
| 53.nf
54# Allow all ICMP packets in
55pass in proto icmp from any to any
56.fi
|
132.PP
| 57.PP
|
133The action indicates what to do with the packet if it matches the rest
134of the filter rule. Each rule MUST have an action. The following
135actions are recognised:
136.TP
137.B block
138indicates that the packet should be flagged to be dropped. In response
139to blocking a packet, the filter may be instructed to send a reply
140packet, either an ICMP packet (\fBreturn-icmp\fP), an ICMP packet
141masquerading as being from the original packet's destination
142(\fBreturn-icmp-as-dest\fP), or a TCP "reset" (\fBreturn-rst\fP). An
143ICMP packet may be generated in response to any IP packet, and its
144type may optionally be specified, but a TCP reset may only be used
145with a rule which is being applied to TCP packets. When using
146\fBreturn-icmp\fP or \fBreturn-icmp-as-dest\fP, it is possible to specify
147the actual unreachable `type'. That is, whether it is a network
148unreachable, port unreachable or even administratively
149prohibited. This is done by enclosing the ICMP code associated with
150it in parenthesis directly following \fBreturn-icmp\fP or
151\fBreturn-icmp-as-dest\fP as follows:
| 58Or at the end of a like, like this:
59.PP
|
152.nf
| 60.nf
|
153 block return-icmp(11) ...
| 61pass in proto icmp from any to any # Allow all ICMP packets in
|
154.fi
| 62.fi
|
| 63.SH Firewall rules
|
155.PP
| 64.PP
|
156Would return a Type-Of-Service (TOS) ICMP unreachable error.
157.TP
158.B pass
159will flag the packet to be let through the filter.
160.TP
161.B log
162causes the packet to be logged (as described in the LOGGING section
163below) and has no effect on whether the packet will be allowed through
164the filter.
165.TP
166.B count
167causes the packet to be included in the accounting statistics kept by
168the filter, and has no effect on whether the packet will be allowed through
169the filter. These statistics are viewable with ipfstat(8).
170.TP
171.B call
172this action is used to invoke the named function in the kernel, which
173must conform to a specific calling interface. Customised actions and
174semantics can thus be implemented to supplement those available. This
175feature is for use by knowledgeable hackers, and is not currently
176documented.
177.TP
178.B "skip <n>"
179causes the filter to skip over the next \fIn\fP filter rules. If a rule is
180inserted or deleted inside the region being skipped over, then the value of
181\fIn\fP is adjusted appropriately.
182.TP
183.B auth
184this allows authentication to be performed by a user-space program running
185and waiting for packet information to validate. The packet is held for a
186period of time in an internal buffer whilst it waits for the program to return
187to the kernel the \fIreal\fP flags for whether it should be allowed through
188or not. Such a program might look at the source address and request some sort
189of authentication from the user (such as a password) before allowing the
190packet through or telling the kernel to drop it if from an unrecognised source.
191.TP
192.B preauth
193tells the filter that for packets of this class, it should look in the
194pre-authenticated list for further clarification. If no further matching
195rule is found, the packet will be dropped (the FR_PREAUTH is not the same
196as FR_PASS). If a further matching rule is found, the result from that is
197used in its instead. This might be used in a situation where a person
198\fIlogs in\fP to the firewall and it sets up some temporary rules defining
199the access for that person.
| 65This section goes into detail on how to construct firewall rules that
66are placed in the ipf.conf file.
|
200.PP
| 67.PP
|
201The next word must be either \fBin\fP or \fBout\fP. Each packet
202moving through the kernel is either inbound (just been received on an
203interface, and moving towards the kernel's protocol processing) or
204outbound (transmitted or forwarded by the stack, and on its way to an
205interface). There is a requirement that each filter rule explicitly
206state which side of the I/O it is to be used on.
207.SH OPTIONS
| 68It is beyond the scope of this document to describe what makes a good
69firewall rule set or which packets should be blocked or allowed in.
70Some suggestions will be provided but further reading is expected to
71fully understand what is safe and unsafe to allow in/out.
72.SS Filter rule keywords
|
208.PP
| 73.PP
|
209The list of options is brief, and all are indeed optional. Where
210options are used, they must be present in the order shown here. These
211are the currently supported options:
212.TP
213.B log
214indicates that, should this be the last matching rule, the packet
215header will be written to the \fBipl\fP log (as described in the
216LOGGING section below).
217.TP
218.B tag tagid
219indicates that, if this rule causes the packet to be logged or entered
220in the state table, the tagid will be logged as part of the log entry.
221This can be used to quickly match "similar" rules in scripts that post
222process the log files for e.g. generation of security reports or accounting
223purposes. The tagid is a 32 bit unsigned integer.
224.TP
225.B quick
226allows "short-cut" rules in order to speed up the filter or override
227later rules. If a packet matches a filter rule which is marked as
228\fBquick\fP, this rule will be the last rule checked, allowing a
229"short-circuit" path to avoid processing later rules for this
230packet. The current status of the packet (after any effects of the
231current rule) will determine whether it is passed or blocked.
| 74The first word found in any filter rule describes what the eventual outcome
75of a packet that matches it will be. Descriptions of the many and various
76sections that can be used to match on the contents of packet headers will
77follow on below.
78.PP
79The complete list of keywords, along with what they do is as follows:
80.RS
81.HP
82pass
83rules that match a packet indicate to ipfilter that it should be
84allowed to continue on in the direction it is flowing.
85.HP
86block
87rules are used when it is desirable to prevent a packet from going
88any further. Packets that are blocked on the "in" side are never seen by
89TCP/IP and those that are blocked going "out" are never seen on the wire.
90.HP
91log
92when IPFilter successfully matches a packet against a log rule a log
93record is generated and made available for ipmon(8) to read. These rules
94have no impact on whether or not a packet is allowed through or not.
95So if a packet first matched a block rule and then matched a log rule,
96the status of the packet after the log rule is that it will still be
97blocked.
98.HP
99count
100rules provide the administrator with the ability to count packets and
101bytes that match the criteria laid out in the configuration file.
102The count rules are applied after NAT and filter rules on the inbound
103path. For outbound packets, count rules are applied before NAT and
104before the packet is dropped. Thus the count rule cannot be used as
105a true indicator of link layer
106.HP
107auth
108rules cause the matching packet to be queued up for processing by a
109user space program. The user space program is responsible for making
110an ioctl system call to collect the information about the queued
111packet and another ioctl system call to return the verdict (block,
112pass, etc) on what to do with the packet. In the event that the queue
113becomes full, the packets will end up being dropped.
114.HP
115call
116provides access to functions built into IPFilter that allow for more
117complex actions to be taken as part of the decision making that goes
118with the rule.
119.HP
120decapsulate
121rules instruct ipfilter to remove any
122other headers (IP, UDP, AH) and then process what is inside as a new packet.
123For non-UDP packets, there are builtin checks that are applied in addition
124to whatever is specified in the rule, to only allow decapsulation of
125recognised protocols. After decapsulating the inner packet, any filtering
126result that is applied to the inner packet is also applied to the other
127packet.
128.PP
129The default way in which filter rules are applied is for the last
130matching rule to be used as the decision maker. So even if the first
131rule to match a packet is a pass, if there is a later matching rule
132that is a block and no further rules match the packet, then it will
133be blocked.
134.SS Matching Network Interfaces
135.PP
136On systems with more than one network interface, it is necessary
137to be able to specify different filter rules for each of them.
138In the first instance, this is because different networks will send us
139packets via each network interface but it is also because of the hosts,
140the role and the resulting security policy that we need to be able to
141distinguish which network interface a packet is on.
142.PP
143To accomodate systems where the presence of a network interface is
144dynamic, it is not necessary for the network interface named in a
145filter rule to be present in the system when the rule is loaded.
146This can lead to silent errors being introduced and unexpected
147behaviour with the simplest of keyboard mistakes - for example,
148typing in hem0 instead of hme0 or hme2 instead of hme3.
149.PP
150On Solaris systems prior to Solaris 10 Update 4, it is not possible
151to filter packets on the loopback interface (lo0) so filter rules
152that specify it will have no impact on the corresponding flow of
153packets. See below for Solaris specific tips on how to enable this.
154.PP
155Some examples of including the network interface in filter rules are:
156.PP
157.nf
158block in on bge0 all
159pass out on bge0 all
160.fi
161.SS Address matching (basic)
162.PP
163The first and most basic part of matching for filtering rules is to
164specify IP addresses and TCP/UDP port numbers. The source address
165information is matched by the "from" information in a filter rule
166and the destination address information is matched with the "to"
167information in a filter rule.
168.PP
169The typical format used for IP addresses is CIDR notation, where an
170IP address (or network) is followed by a '/' and a number representing
171the size of the netmask in bits. This notation is used for specifying
172address matching in both IPv4 and IPv6. If the '/' and bitmask size
173are excluded from the matching string, it is assumed that the address
174specified is a host address and that the netmask applied should be
175all 1's.
176.PP
177Some examples of this are:
178.PP
179.nf
180pass in from 10.1.0.0/24 to any
181block out from any to 10.1.1.1
182.fi
183.PP
184It is not possible to specify a range of addresses that does not
185have a boundary that can be defined by a standard subnet mask.
|
232.IP
| 186.IP
|
233If this option is missing, the rule is taken to be a "fall-through"
234rule, meaning that the result of the match (block/pass) is saved and
235that processing will continue to see if there are any more matches.
236.TP
237.B on
238allows an interface name to be incorporated into the matching
239procedure. Interface names are as printed by "netstat \-i". If this
240option is used, the rule will only match if the packet is going
241through that interface in the specified direction (in/out). If this
242option is absent, the rule is taken to be applied to a packet
243regardless of the interface it is present on (i.e. on all interfaces).
244Filter rulesets are common to all interfaces, rather than having a
245filter list for each interface.
| 187.B Names instead of addresses
188.RS
189.PP
190Hostnames, resolved either via DNS or /etc/hosts, or network names,
191resolved via /etc/networks, may be used in place of actual addresses
192in the filter rules. WARNING: if a hostname expands to more than one
193address, only the *first* is used in building the filter rule.
194.PP
195Caution should be exercised when relying on DNS for filter rules in
196case the sending and receiving of DNS packets is blocked when ipf(8)
197is processing that part of the configuration file, leading to long
198delays, if not errors, in loading the filter rules.
199.RE
200.SS Protocol Matching
201.PP
202To match packets based on TCP/UDP port information, it is first necessary
203to indicate which protocol the packet must be. This is done using the
204"proto" keyword, followed by either the protocol number or a name which
205is mapped to the protocol number, usually through the /etc/protocols file.
206.PP
207.nf
208pass in proto tcp from 10.1.0.0/24 to any
209block out proto udp from any to 10.1.1.1
210pass in proto icmp from any to 192.168.0.0/16
211.fi
212.SS Sending back error packets
213.PP
214When a packet is just discarded using a block rule, there is no feedback given
215to the host that sent the packet. This is both good and bad. If this is the
216desired behaviour and it is not desirable to send any feedback about packets
217that are to be denied. The catch is that often a host trying to connect to a
218TCP port or with a UDP based application will send more than one packet
219because it assumes that just one packet may be discarded so a retry is
220required. The end result being logs can become cluttered with duplicate
221entries due to the retries.
222.PP
223To address this problem, a block rule can be qualified in two ways.
224The first of these is specific to TCP and instructs IPFilter to send back
225a reset (RST) packet. This packet indicates to the remote system that the
226packet it sent has been rejected and that it shouldn't make any further
227attempts to send packets to that port. Telling IPFilter to return a TCP
228RST packet in response to something that has been received is achieved
229with the return-rst keyword like this:
230.PP
231.nf
232block return-rst in proto tcp from 10.0.0.0/8 to any
233.fi
234.PP
235When sending back a TCP RST packet, IPFilter must construct a new packet
236that has the source address of the intended target, not the source address
237of the system it is running on (if they are different.)
238.PP
239For all of the other protocols handled by the IP protocol suite, to send
240back an error indicating that the received packet was dropped requires
241sending back an ICMP error packet. Whilst these can also be used for TCP,
242the sending host may not treat the received ICMP error as a hard error
243in the same way as it does the TCP RST packet. To return an ICMP error
244it is necessary to place return-icmp after the block keyword like this:
245.PP
246.nf
247block return-icmp in proto udp from any to 192.168.0.1/24
248.fi
249.PP
250When electing to return an ICMP error packet, it is also possible to
251select what type of ICMP error is returned. Whilst the full compliment
252of ICMP unreachable codes can be used by specifying a number instead of
253the string below, only the following should be used in conjunction with
254return-icmp. Which return code to use is a choice to be made when
255weighing up the pro's and con's. Using some of the codes may make it
256more obvious that a firewall is being used rather than just the host
257not responding.
258.RS
259.HP
260filter-prohib
261(prohibited by filter)
262sending packets to the destination given in the received packet is
263prohibited due to the application of a packet filter
264.HP
265net-prohib
266(prohibited network)
267sending packets to the destination given in the received packet is
268administratively prohibited.
269.HP
270host-unk
271(host unknown)
272the destination host address is not known by the system receiving
273the packet and therefore cannot be reached.
274.HP
275host-unr
276(host unreachable)
277it is not possible to reach the host as given by the destination address
278in the packet header.
279.HP
280net-unk
281(network unknown)
282the destination network address is not known by the system receiving
283the packet and therefore cannot be reached.
284.HP
285net-unr
286(network unreachable)
287it is not possible to forward the packet on to its final destination
288as given by the destination address
289.HP
290port-unr
291(port unreachable)
292there is no application using the given destination port and therefore
293it is not possible to reach that port.
294.HP
295proto-unr
296(protocol unreachable)
297the IP protocol specified in the packet is not available to receive
298packets.
299.DE
300.PP
301An example that shows how to send back a port unreachable packet for
302UDP packets to 192.168.1.0/24 is as follows:
303.PP
304.nf
305block return-icmp(port-unr) in proto udp from any to 192.168.1.0/24
306.fi
307.PP
308In the above examples, when sending the ICMP packet, IPFilter will construct
309a new ICMP packet with a source address of the network interface used to
310send the packet back to the original source. This can give away that there
311is an intermediate system blocking packets. To have IPFilter send back
312ICMP packets where the source address is the original destination, regardless
313of whether or not it is on the local host, return-icmp-as-dest is used like
314this:
315.PP
316.nf
317block return-icmp-as-dest(port-unr) in proto udp \\
318 from any to 192.168.1.0/24
319.fi
320.SS TCP/UDP Port Matching
321.PP
322Having specified which protocol is being matched, it is then possible to
323indicate which port numbers a packet must have in order to match the rule.
324Due to port numbers being used differently to addresses, it is therefore
325possible to match on them in different ways. IPFilter allows you to use
326the following logical operations:
327.IP "< x"
328is true if the port number is greater than or equal to x and less than or
329equal to y
330is true if the port number in the packet is less than x
331.IP "<= x"
332is true if the port number in the packet is less than or equal to x
333.IP "> x"
334is true if the port number in the packet is greater than x
335.IP ">= x"
336is true if the port number in the packet is greater or equal to x
337.IP "= x"
338is true if the port number in the packet is equal to x
339.IP "!= x"
340is true if the port number in the packet is not equal to x
341.PP
342Additionally, there are a number of ways to specify a range of ports:
343.IP "x <> y"
344is true if the port number is less than a and greater than y
345.IP "x >< y"
346is true if the port number is greater than x and less than y
347.IP "x:y"
348is true if the port number is greater than or equal to x and less than or
349equal to y
350.PP
351Some examples of this are:
352.PP
353.nf
354block in proto tcp from any port >= 1024 to any port < 1024
355pass in proto tcp from 10.1.0.0/24 to any port = 22
356block out proto udp from any to 10.1.1.1 port = 135
357pass in proto udp from 1.1.1.1 port = 123 to 10.1.1.1 port = 123
358pass in proto tcp from 127.0.0.0/8 to any port = 6000:6009
359.fi
360.PP
361If there is no desire to mention any specific source or destintion
362information in a filter rule then the word "all" can be used to
363indicate that all addresses are considered to match the rule.
364.SS IPv4 or IPv6
365.PP
366If a filter rule is constructed without any addresses then IPFilter
367will attempt to match both IPv4 and IPv6 packets with it. In the
368next list of rules, each one can be applied to either network protocol
369because there is no address specified from which IPFilter can derive
370with network protocol to expect.
371.PP
372.nf
373pass in proto udp from any to any port = 53
374block in proto tcp from any port < 1024 to any
375.fi
376.PP
377To explicitly match a particular network address family with a specific
378rule, the family must be added to the rule. For IPv4 it is necessary to
379add family inet and for IPv6, family inet6. Thus the next rule will
380block all packets (both IPv4 and IPv6:
381.PP
382.nf
383block in all
384.fi
385.PP
386but in the following example, we block all IPv4 packets and only allow
387in IPv6 packets:
388.PP
389.nf
390block in family inet all
391pass in family inet6 all
392.fi
393.PP
394To continue on from the example where we allowed either IPv4 or IPv6
395packets to port 53 in, to change that such that only IPv6 packets to
396port 53 need to allowed blocked then it is possible to add in a
397protocol family qualifier:
398.PP
399.nf
400pass in family inet6 proto udp from any to any port = 53
401.fi
402.SS First match vs last match
403.PP
404To change the default behaviour from being the last matched rule decides
405the outcome to being the first matched rule, the word "quick" is inserted
406to the rule.
407.SH Extended Packet Matching
408.SS Beyond using plain addresses
409.PP
410On firewalls that are working with large numbers of hosts and networks
411or simply trying to filter discretely against various hosts, it can
412be an easier administration task to define a pool of addresses and have
413a filter rule reference that address pool rather than have a rule for
414each address.
415.PP
416In addition to being able to use address pools, it is possible to use
417the interface name(s) in the from/to address fields of a rule. If the
418name being used in the address section can be matched to any of the
419interface names mentioned in the rule's "on" or "via" fields then it
420can be used with one of the following keywords for extended effect:
421.HP
422broadcast
423use the primary broadcast address of the network interface for matching
424packets with this filter rule;
|
246.IP
| 425.IP
|
247This option is especially useful for simple IP-spoofing protection:
248packets should only be allowed to pass inbound on the interface from
249which the specified source address would be expected, others may be
250logged and/or dropped.
251.TP
252.B dup-to
253causes the packet to be copied, and the duplicate packet to be sent
254outbound on the specified interface, optionally with the destination
255IP address changed to that specified. This is useful for off-host
256logging, using a network sniffer.
257.TP
258.B to
259causes the packet to be moved to the outbound queue on the
260specified interface. This can be used to circumvent kernel routing
261decisions, and even to bypass the rest of the kernel processing of the
262packet (if applied to an inbound rule). It is thus possible to
263construct a firewall that behaves transparently, like a filtering hub
264or switch, rather than a router. The \fBfastroute\fP keyword is a
265synonym for this option.
266.SH MATCHING PARAMETERS
267.PP
268The keywords described in this section are used to describe attributes
269of the packet to be used when determining whether rules match or don't
270match. The following general-purpose attributes are provided for
271matching, and must be used in this order:
272.TP
273.B tos
274packets with different Type-Of-Service values can be filtered.
275Individual service levels or combinations can be filtered upon. The
276value for the TOS mask can either be represented as a hex number or a
277decimal integer value.
278.TP
279.B ttl
280packets may also be selected by their Time-To-Live value. The value given in
281the filter rule must exactly match that in the packet for a match to occur.
282This value can only be given as a decimal integer value.
283.TP
284.B proto
285allows a specific protocol to be matched against. All protocol names
286found in \fB/etc/protocols\fP are recognised and may be used.
287However, the protocol may also be given as a DECIMAL number, allowing
288for rules to match your own protocols, or new ones which would
289out-date any attempted listing.
| 426.nf
427pass in on fxp0 proto udp from any to fxp0/broadcast port = 123
428.fi
429.HP
430peer
431use the peer address on point to point network interfaces for matching
432packets with this filter rule. This option typically only has meaningful
433use with link protocols such as SLIP and PPP.
434For example, this rule allows ICMP packets from the remote peer of ppp0
435to be received if they're destined for the address assigned to the link
436at the firewall end.
|
290.IP
| 437.IP
|
291The special protocol keyword \fBtcp/udp\fP may be used to match either
292a TCP or a UDP packet, and has been added as a convenience to save
293duplication of otherwise-identical rules.
294.\" XXX grammar should reflect this (/etc/protocols)
| 438.nf
439pass in on ppp0 proto icmp from ppp0/peer to ppp0/32
440.fi
441.HP
442netmasked
443use the primary network address, with its netmask, of the network interface
444for matching packets with this filter rule. If a network interface had an
445IP address of 192.168.1.1 and its netmask was 255.255.255.0 (/24), then
446using the word "netmasked" after the interface name would match any
447addresses that would match 192.168.1.0/24. If we assume that bge0 has
448this IP address and netmask then the following two rules both serve
449to produce the same effect:
450.IP
451.nf
452pass in on bge0 proto icmp from any to 192.168.1.0/24
453pass in on bge0 proto icmp from any to bge0/netmasked
454.fi
455.HP
456network
457using the primary network address, and its netmask, of the network interface,
458construct an address for exact matching. If a network interface has an
459address of 192.168.1.1 and its netmask is 255.255.255.0, using this
460option would only match packets to 192.168.1.0.
461.IP
462.nf
463pass in on bge0 proto icmp from any to bge0/network
464.fi
|
295.PP
| 465.PP
|
296The \fBfrom\fP and \fBto\fP keywords are used to match against IP
297addresses (and optionally port numbers). Rules must specify BOTH
298source and destination parameters.
299.PP
300IP addresses may be specified in one of two ways: as a numerical
301address\fB/\fPmask, or as a hostname \fBmask\fP netmask. The hostname
302may either be a valid hostname, from either the hosts file or DNS
303(depending on your configuration and library) or of the dotted numeric
304form. There is no special designation for networks but network names
305are recognised. Note that having your filter rules depend on DNS
306results can introduce an avenue of attack, and is discouraged.
| 466Another way to use the name of a network interface to get the address
467is to wrap the name in ()'s. In the above method, IPFilter
468looks at the interface names in use and to decide whether or not
469the name given is a hostname or network interface name. With the
470use of ()'s, it is possible to tell IPFilter that the name should
471be treated as a network interface name even though it doesn't
472appear in the list of network interface that the rule ias associated
473with.
474.IP
475.nf
476pass in proto icmp from any to (bge0)/32
477.fi
478.SS Using address pools
|
307.PP
| 479.PP
|
308There is a special case for the hostname \fBany\fP which is taken to
309be 0.0.0.0/0 (see below for mask syntax) and matches all IP addresses.
310Only the presence of "any" has an implied mask, in all other
311situations, a hostname MUST be accompanied by a mask. It is possible
312to give "any" a hostmask, but in the context of this language, it is
313non-sensical.
| 480Rather than list out multiple rules that either allow or deny specific
481addresses, it is possible to create a single object, call an address
482pool, that contains all of those addresses and reference that in the
483filter rule. For documentation on how to write the configuration file
484for those pools and load them, see ippool.conf(5) and ippool(8).
485There are two types of address pools that can be defined in ippool.conf(5):
486trees and hash tables. To refer to a tree defined in ippool.conf(5),
487use this syntax:
|
314.PP
| 488.PP
|
315The numerical format "x\fB/\fPy" indicates that a mask of y
316consecutive 1 bits set is generated, starting with the MSB, so a y value
317of 16 would give 0xffff0000. The symbolic "x \fBmask\fP y" indicates
318that the mask y is in dotted IP notation or a hexadecimal number of
319the form 0x12345678. Note that all the bits of the IP address
320indicated by the bitmask must match the address on the packet exactly;
321there isn't currently a way to invert the sense of the match, or to
322match ranges of IP addresses which do not express themselves easily as
323bitmasks (anthropomorphization; it's not just for breakfast anymore).
| 489.nf
490pass in from pool/trusted to any
491.fi
|
324.PP
| 492.PP
|
325If a \fBport\fP match is included, for either or both of source and
326destination, then it is only applied to
327.\" XXX - "may only be" ? how does this apply to other protocols? will it not match, or will it be ignored?
328TCP and UDP packets. If there is no \fBproto\fP match parameter,
329packets from both protocols are compared. This is equivalent to "proto
330tcp/udp". When composing \fBport\fP comparisons, either the service
331name or an integer port number may be used. Port comparisons may be
332done in a number of forms, with a number of comparison operators, or
333port ranges may be specified. When the port appears as part of the
334\fBfrom\fP object, it matches the source port number, when it appears
335as part of the \fBto\fP object, it matches the destination port number.
336See the examples for more information.
| 493Either a name or number can be used after the '/', just so long as it
494matches up with something that has already been defined in ipool.conf(5)
495and loaded in with ippool(8). Loading a filter rule that references a
496pool that does not exist will result in an error.
|
337.PP
| 497.PP
|
338The \fBall\fP keyword is essentially a synonym for "from any to any"
339with no other match parameters.
| 498If hash tables have been used in ippool.conf(5) to store the addresses
499in instead of a tree, then replace the word pool with hash:
500.IP
501.nf
502pass in from any to hash/webservers
503.fi
|
340.PP
| 504.PP
|
341Following the source and destination matching parameters, the
342following additional parameters may be used:
343.TP
344.B with
345is used to match irregular attributes that some packets may have
346associated with them. To match the presence of IP options in general,
347use \fBwith ipopts\fP. To match packets that are too short to contain
348a complete header, use \fBwith short\fP. To match fragmented packets,
349use \fBwith frag\fP. For more specific filtering on IP options,
350individual options can be listed.
| 505There are different operational characteristics with each, so there
506may be some situations where a pool works better than hash and vice
507versa.
508.SS Matching TCP flags
509.PP
510The TCP header contains a field of flags that is used to decide if the
511packet is a connection request, connection termination, data, etc.
512By matching on the flags in conjunction with port numbers, it is
513possible to restrict the way in which IPFilter allows connections to
514be created. A quick overview of the TCP
515flags is below. Each is listed with the letter used in IPFilter
516rules, followed by its three or four letter pneumonic.
517.HP
518S
519SYN - this bit is set when a host is setting up a connection.
520The initiator typically sends a packet with the SYN bit and the
521responder sends back SYN plus ACK.
522.HP
523A
524ACK - this bit is set when the sender wishes to acknowledge the receipt
525of a packet from another host
526.HP
527P
528PUSH - this bit is set when a sending host has send some data that
529is yet to be acknowledged and a reply is sought
530.HP
531F
532FIN - this bit is set when one end of a connection starts to close
533the connection down
534.HP
535U
536URG - this bit is set to indicate that the packet contains urgent data
537.HP
538R
539RST - this bit is set only in packets that are a reply to another
540that has been received but is not targetted at any open port
541.HP
542C
543CWN
544.HP
545E
546ECN
547.PP
548When matching TCP flags, it is normal to just list the flag that you
549wish to be set. By default the set of flags it is compared against
550is "FSRPAU". Rules that say "flags S" will be displayed by ipfstat(8)
551as having "flags S/FSRPAU". This is normal.
552The last two flags, "C" and "E", are optional - they
553may or may not be used by an end host and have no bearing on either
554the acceptance of data nor control of the connection. Masking them
555out with "flags S/FSRPAUCE" may cause problems for remote hosts
556making a successful connection.
557.PP
558.nf
559pass in quick proto tcp from any to any port = 22 flags S/SAFR
560pass out quick proto tcp from any port = 22 to any flags SA
561.fi
562.PP
563By itself, filtering based on the TCP flags becomes more work but when
564combined with stateful filtering (see below), the situation changes.
565.SS Matching on ICMP header information
566.PP
567The TCP and UDP are not the only protocols for which filtering beyond
568just the IP header is possible, extended matching on ICMP packets is
569also available. The list of valid ICMP types is different for IPv4
570vs IPv6.
571.PP
572As a practical example, to allow the ping command to work
573against a specific target requires allowing two different types of
574ICMP packets, like this:
575.PP
576.nf
577pass in proto icmp from any to webserver icmp-type echo
578pass out proto icmp from webserver to any icmp-type echorep
579.fi
580.PP
581The ICMP header has two fields that are of interest for filtering:
582the ICMP type and code. Filter rules can accept either a name or
583number for both the type and code. The list of names supported for
584ICMP types is listed below, however only ICMP unreachable errors
585have named codes (see above.)
586.PP
587The list of ICMP types that are available for matching an IPv4 packet
588are as follows:
589.PP
590echo (echo request),
591echorep (echo reply),
592inforeq (information request),
593inforep (information reply),
594maskreq (mask request),
595maskrep (mask reply),
596paramprob (parameter problem),
597redir (redirect),
598routerad (router advertisement),
599routersol (router solicit),
600squence (source quence),
601timest (timestamp),
602timestreq (timestamp reply),
603timex (time exceeded),
604unreach (unreachable).
605.PP
606The list of ICMP types that are available for matching an IPv6 packet
607are as follows:
608.PP
609echo (echo request),
610echorep (echo reply),
611fqdnquery (FQDN query),
612fqdnreply (FQDN reply),
613inforeq (information request),
614inforep (information reply),
615listendone (MLD listener done),
616listendqry (MLD listener query),
617listendrep (MLD listener reply),
618neighadvert (neighbour advert),
619neighborsol (neighbour solicit),
620paramprob (parameter problem),
621redir (redirect),
622renumber (router renumbering),
623routerad (router advertisement),
624routersol (router solicit),
625timex (time exceeded),
626toobig (packet too big),
627unreach (unreachable,
628whoreq (WRU request),
629whorep (WRU reply).
630.SH Stateful Packet Filtering
631.PP
632Stateful packet filtering is where IPFilter remembers some information from
633one or more packets that it has seen and is able to apply it to future
634packets that it receives from the network.
635.PP
636What this means for each transport layer protocol is different.
637For TCP it means that if IPFilter
638sees the very first packet of an attempt to make a connection, it has enough
639information to allow all other subsequent packets without there needing to
640be any explicit rules to match them. IPFilter uses the TCP port numbers,
641TCP flags, window size and sequence numbers to determine which packets
642should be matched. For UDP, only the UDP port numbers are available.
643For ICMP, the ICMP types can be combined with the ICMP id field to
644determine which reply packets match a request/query that has already
645been seen. For all other protocols, only matching on IP address and
646protocol number is available for determining if a packet received is a mate
647to one that has already been let through.
648.PP
649The difference this makes is a reduction in the number of rules from
6502 or 4 to 1. For example, these 4 rules:
651.PP
652.nf
653pass in on bge0 proto tcp from any to any port = 22
654pass out on bge1 proto tcp from any to any port = 22
655pass in on bge1 proto tcp from any port = 22 to any
656pass out on bge0 proto tcp from any port = 22 to any
657.fi
658.PP
659can be replaced with this single rule:
660.PP
661.nf
662pass in on bge0 proto tcp from any to any port = 22 flags S keep state
663.fi
664.PP
665Similar rules for UDP and ICMP might be:
666.PP
667.nf
668pass in on bge0 proto udp from any to any port = 53 keep state
669pass in on bge0 proto icmp all icmp-type echo keep state
670.fi
671.PP
672When using stateful filtering with TCP it is best to add "flags S" to the
673rule to ensure that state is only created when a packet is seen that is
674an indication of a new connection. Although IPFilter can gather some
675information from packets in the middle of a TCP connection to do stateful
676filtering, there are some options that are only sent at the start of the
677connection which alter the valid window of what TCP accepts. The end result
678of trying to pickup TCP state in mid connection is that some later packets
679that are part of the connection may not match the known state information
680and be dropped or blocked, causing problems. If a TCP packet matches IP
681addresses and port numbers but does not fit into the recognised window,
682it will not be automatically allowed and will be flagged inside of
683IPFitler as "out of window" (oow). See below, "Extra packet attributes",
684for how to match on this attribute.
685.PP
686Once a TCP connection has reached the established state, the default
687timeout allows for it to be idle for 5 days before it is removed from
688the state table. The timeouts for the other TCP connection states
689vary from 240 seconds to 30 seconds.
690Both UDP and ICMP state entries have asymetric timeouts where the timeout
691set upon seeing packets in the forward direction is much larger than
692for the reverse direction. For UDP the default timeouts are 120 and
69312 seconds, for ICMP 60 and 6 seconds. This is a reflection of the
694use of these protocols being more for query-response than for ongoing
695connections. For all other protocols the
696timeout is 60 seconds in both directions.
697.SS Stateful filtering options
698.PP
699The following options can be used with stateful filtering:
700.HP
701limit
702limit the number of state table entries that this rule can create to
703the number given after limit. A rule that has a limit specified is
704always permitted that many state table entries, even if creating an
705additional entry would cause the table to have more entries than the
706otherwise global limit.
|
351.IP
| 707.IP
|
352Before any parameter used after the \fBwith\fP keyword, the word
353\fBnot\fP or \fBno\fP may be inserted to cause the filter rule to only
354match if the option(s) is not present.
| 708.nf
709pass ... keep state(limit 100)
710.fi
711.HP
712age
713sets the timeout for the state entry when it sees packets going through
714it. Additionally it is possible to set the tieout for the reply packets
715that come back through the firewall to a different value than for the
716forward path. allowing a short timeout to be set after the reply has
717been seen and the state no longer required.
718.RS
719.PP
720.nf
721pass in quick proto icmp all icmp-type echo \\
722 keep state (age 3)
723pass in quick proto udp from any \\
724 to any port = 53 keep state (age 30/1)
725.fi
726.RE
727.HP
728strict
729only has an impact when used with TCP. It forces all packets that are
730allowed through the firewall to be sequential: no out of order delivery
731of packets is allowed. This can cause significant slowdown for some
732connections and may stall others. Use with caution.
|
355.IP
| 733.IP
|
356Multiple consecutive \fBwith\fP clauses are allowed. Alternatively,
357the keyword \fBand\fP may be used in place of \fBwith\fP, this is
358provided purely to make the rules more readable ("with ... and ...").
359When multiple clauses are listed, all those must match to cause a
360match of the rule.
361.\" XXX describe the options more specifically in a separate section
362.TP
363.B flags
364is only effective for TCP filtering. Each of the letters possible
365represents one of the possible flags that can be set in the TCP
366header. The association is as follows:
367.LP
| |
368.nf
| 734.nf
|
369 F - FIN
370 S - SYN
371 R - RST
372 P - PUSH
373 A - ACK
374 U - URG
| 735pass in proto tcp ... keep state(strict)
|
375.fi
| 736.fi
|
| 737.HP
738noicmperr
739prevents ICMP error packets from being able to match state table entries
740created with this flag using the contents of the original packet included.
|
376.IP
| 741.IP
|
377The various flag symbols may be used in combination, so that "SA"
378would represent a SYN-ACK combination present in a packet. There is
379nothing preventing the specification of combinations, such as "SFR",
380that would not normally be generated by law-abiding TCP
381implementations. However, to guard against weird aberrations, it is
382necessary to state which flags you are filtering against. To allow
383this, it is possible to set a mask indicating which TCP flags you wish
384to compare (i.e., those you deem significant). This is done by
385appending "/<flags>" to the set of TCP flags you wish to match
386against, e.g.:
387.LP
| |
388.nf
| 742.nf
|
389 ... flags S
390 # becomes "flags S/AUPRFS" and will match
391 # packets with ONLY the SYN flag set.
| 743pass ... keep state(noicmperr)
744.fi
745.HP
746sync
747indicates to IPFilter that it needs to provide information to the user
748land daemons responsible for syncing other machines state tables up
749with this one.
750.IP
751.nf
752pass ... keep state(sync)
753.fi
754.HP
755nolog
756do not generate any log records for the creation or deletion of state
757table entries.
758.IP
759.nf
760pass ... keep state(nolog)
761.fi
762.HP
763icmp-head
764rather than just precent ICMP error packets from being able to match
765state table entries, allow an ACL to be processed that can filter in or
766out ICMP error packets based as you would with normal firewall rules.
767The icmp-head option requires a filter rule group number or name to
768be present, just as you would use with head.
769.RS
770.PP
771.nf
772pass in quick proto tcp ... keep state(icmp-head 101)
773block in proto icmp from 10.0.0.0/8 to any group 101
774.fi
775.RE
776.HP
777max-srcs
778allows the number of distinct hosts that can create a state entry to
779be defined.
780.IP
781.nf
782pass ... keep state(max-srcs 100)
783pass ... keep state(limit 1000, max-srcs 100)
784.fi
785.HP
786max-per-src
787whilst max-srcs limits the number of individual hosts that may cause
788the creation of a state table entry, each one of those hosts is still
789table to fill up the state table with new entries until the global
790maximum is reached. This option allows the number of state table entries
791per address to be limited.
792.IP
793.nf
794pass ... keep state(max-srcs 100, max-per-src 1)
795pass ... keep state(limit 100, max-srcs 100, max-per-src 1)
796.fi
797.IP
798Whilst these two rules might seem identical, in that they both
799ultimately limit the number of hosts and state table entries created
800from the rule to 100, there is a subtle difference: the second will
801always allow up to 100 state table entries to be created whereas the
802first may not if the state table fills up from other rules.
803.IP
804Further, it is possible to specify a netmask size after the per-host
805limit that enables the per-host limit to become a per-subnet or
806per-network limit.
807.IP
808.nf
809pass ... keep state(max-srcs 100, max-per-src 1/24)
810.fi
811.IP
812If there is no IP protocol implied by addresses or other features of
813the rule, IPFilter will assume that no netmask is an all ones netmask
814for both IPv4 and IPv6.
815.SS Tieing down a connection
816.PP
817For any connection that transits a firewall, each packet will be seen
818twice: once going in and once going out. Thus a connection has 4 flows
819of packets:
820.HP
821forward
822inbound packets
823.HP
824forward
825outbound packets
826.HP
827reverse
828inbound packets
829.HP
830reverse
831outbound packets
832.PP
833IPFilter allows you to define the network interface to be used at all
834four points in the flow of packets. For rules that match inbound packets,
835out-via is used to specify which interfaces the packets go out, For rules
836that match outbound packets, in-via is used to match the inbound packets.
837In each case, the syntax generalises to this:
838.PP
839.nf
840pass ... in on forward-in,reverse-in \\
841 out-via forward-out,reverse-out ...
|
392
| 842
|
393 ... flags SA
394 # becomes "flags SA/AUPRFS" and will match any
395 # packet with only the SYN and ACK flags set.
396
397 ... flags S/SA
398 # will match any packet with just the SYN flag set
399 # out of the SYN-ACK pair; the common "establish"
400 # keyword action. "S/SA" will NOT match a packet
401 # with BOTH SYN and ACK set, but WILL match "SFP".
| 843pass ... out on forward-out,reverse-out \\
844 in-via forward-in,reverse-in ...
|
402.fi
| 845.fi
|
403.TP
404.B icmp-type
405is only effective when used with \fBproto icmp\fP and must NOT be used
406in conjunction with \fBflags\fP. There are a number of types, which can be
407referred to by an abbreviation recognised by this language, or the numbers
408with which they are associated can be used. The most important from
409a security point of view is the ICMP redirect.
410.SH KEEP HISTORY
| |
411.PP
| 846.PP
|
412The second last parameter which can be set for a filter rule is whether or not
413to record historical information for that packet, and what sort to keep. The
414following information can be kept:
415.TP
416.B state
417keeps information about the flow of a communication session. State can
418be kept for TCP, UDP, and ICMP packets.
419.TP
420.B frags
421keeps information on fragmented packets, to be applied to later
422fragments.
| 847An example that pins down all 4 network interfaces used by an ssh
848connection might look something like this:
|
423.PP
| 849.PP
|
424allowing packets which match these to flow straight through, rather
425than going through the access control list.
426.SH GROUPS
427The last pair of parameters control filter rule "grouping". By default, all
428filter rules are placed in group 0 if no other group is specified. To add a
429rule to a non-default group, the group must first be started by creating a
430group \fIhead\fP. If a packet matches a rule which is the \fIhead\fP of a
431group, the filter processing then switches to the group, using that rule as
432the default for the group. If \fBquick\fP is used with a \fBhead\fP rule, rule
433processing isn't stopped until it has returned from processing the group.
| 850.nf
851pass in on bge0,bge1 out-via bge1,bge0 proto tcp \\
852 from any to any port = 22 flags S keep state
853.fi
854.SS Working with packet fragments
|
434.PP
| 855.PP
|
435A rule may be both the head for a new group and a member of a non-default
436group (\fBhead\fP and \fBgroup\fP may be used together in a rule).
437.TP
438.B "head <n>"
439indicates that a new group (number n) should be created.
440.TP
441.B "group <n>"
442indicates that the rule should be put in group (number n) rather than group 0.
443.SH LOGGING
| 856Fragmented packets result in 1 packet containing all of the layer 3 and 4
857header information whilst the data is split across a number of other packets.
|
444.PP
| 858.PP
|
445When a packet is logged, with either the \fBlog\fP action or option,
446the headers of the packet are written to the \fBipl\fP packet logging
447pseudo-device. Immediately following the \fBlog\fP keyword, the
448following qualifiers may be used (in order):
449.TP
450.B body
451indicates that the first 128 bytes of the packet contents will be
452logged after the headers.
453.TP
454.B first
455If log is being used in conjunction with a "keep" option, it is recommended
456that this option is also applied so that only the triggering packet is logged
457and not every packet which thereafter matches state information.
458.TP
459.B or-block
460indicates that, if for some reason the filter is unable to log the
461packet (such as the log reader being too slow) then the rule should be
462interpreted as if the action was \fBblock\fP for this packet.
463.TP
464.B "level <loglevel>"
465indicates what logging facility and priority, or just priority with
466the default facility being used, will be used to log information about
467this packet using ipmon's -s option.
| 859To enforce access control on fragmented packets, one of two approaches
860can be taken. The first is to allow through all of the data fragments
861(those that made up the body of the original packet) and rely on matching
862the header information in the "first" fragment, when it is seen. The
863reception of body fragments without the first will result in the receiving
864host being unable to completely reassemble the packet and discarding all
865of the fragments. The following three rules deny all fragmented packets
866from being received except those that are UDP and even then only allows
867those destined for port 2049 to be completed.
|
468.PP
| 868.PP
|
469See ipl(4) for the format of records written
470to this device. The ipmon(8) program can be used to read and format
471this log.
472.SH EXAMPLES
| 869.nf
870block in all with frags
871pass in proto udp from any to any with frag-body
872pass in proto udp from any to any port = 2049 with frags
873.fi
|
473.PP
| 874.PP
|
474The \fBquick\fP option is good for rules such as:
475\fC
| 875Another mechanism that is available is to track "fragment state".
876This relies on the first fragment of a packet that arrives to be
877the fragment that contains all of the layer 3 and layer 4 header
878information. With the receipt of that fragment before any other,
879it is possible to determine which other fragments are to be allowed
880through without needing to explicitly allow all fragment body packets.
881An example of how this is done is as follows:
882.PP
|
476.nf
| 883.nf
|
477block in quick from any to any with ipopts
| 884pass in proto udp from any prot = 2049 to any with frags keep fags
|
478.fi
| 885.fi
|
| 886.SH Building a tree of rules
|
479.PP
| 887.PP
|
480which will match any packet with a non-standard header length (IP
481options present) and abort further processing of later rules,
482recording a match and also that the packet should be blocked.
| 888Writing your filter rules as one long list of rules can be both inefficient
889in terms of processing the rules and difficult to understand. To make the
890construction of filter rules easier, it is possible to place them in groups.
891A rule can be both a member of a group and the head of a new group.
|
483.PP
| 892.PP
|
484The "fall-through" rule parsing allows for effects such as this:
485.LP
| 893Using filter groups requires at least two rules: one to be in the group
894one one to send matchign packets to the group. If a packet matches a
895filtre rule that is a group head but does not match any of the rules
896in that group, then the packet is considered to have matched the head
897rule.
898.PP
899Rules that are a member of a group contain the word group followed by
900either a name or number that defines which group they're in. Rules that
901form the branch point or starting point for the group must use the
902word head, followed by either a group name or number. If rules are
903loaded in that define a group but there is no matching head then they
904will effectively be orphaned rules. It is possible to have more than
905one head rule point to the same group, allowing groups to be used
906like subroutines to implement specific common policies.
907.PP
908A common use of filter groups is to define head rules that exist in the
909filter "main line" for each direction with the interfaces in use. For
910example:
911.PP
|
486.nf
| 912.nf
|
487 block in from any to any port < 6000
488 pass in from any to any port >= 6000
489 block in from any to any port > 6003
| 913block in quick on bge0 all head 100
914block out quick on bge0 all head 101
915block in quick on fxp0 all head internal-in
916block out quick on fxp0 all head internal-out
917pass in quick proto icmp all icmp-type echo group 100
|
490.fi
491.PP
| 918.fi
919.PP
|
492which sets up the range 6000-6003 as being permitted and all others being
493denied. Note that the effect of the first rule is overridden by subsequent
494rules. Another (easier) way to do the same is:
495.LP
| 920In the above set of rules, there are four groups defined but only one
921of them has a member rule. The only packets that would be allowed
922through the above ruleset would be ICMP echo packets that are
923received on bge0.
924.PP
925Rules can be both a member of a group and the head of a new group,
926allowing groups to specialise.
927.PP
|
496.nf
| 928.nf
|
497 block in from any to any port 6000 <> 6003
498 pass in from any to any port 5999 >< 6004
| 929block in quick on bge0 all head 100
930block in quick proto tcp all head 1006 group 100
|
499.fi
500.PP
| 931.fi
932.PP
|
501Note that both the "block" and "pass" are needed here to effect a
502result as a failed match on the "block" action does not imply a pass,
503only that the rule hasn't taken effect. To then allow ports < 1024, a
504rule such as:
505.LP
| 933Another use of filter rule groups is to provide a place for rules to
934be dynamically added without needing to worry about their specific
935ordering amongst the entire ruleset. For example, if I was using this
936simple ruleset:
937.PP
|
506.nf
| 938.nf
|
507 pass in quick from any to any port < 1024
| 939block in quick all with bad
940block in proto tcp from any to any port = smtp head spammers
941pass in quick proto tcp from any to any port = smtp flags S keep state
|
508.fi
509.PP
| 942.fi
943.PP
|
510would be needed before the first block. To create a new group for
511processing all inbound packets on le0/le1/lo0, with the default being to block
512all inbound packets, we would do something like:
513.LP
| 944and I was getting lots of connections to my email server from 10.1.1.1
945to deliver spam, I could load the following rule to complement the above:
946.IP
|
514.nf
| 947.nf
|
515 block in all
516 block in quick on le0 all head 100
517 block in quick on le1 all head 200
518 block in quick on lo0 all head 300
| 948block in quick from 10.1.1.1 to any group spammers
|
519.fi
| 949.fi
|
| 950.SS Decapsulation
|
520.PP
| 951.PP
|
| 952Rule groups also form a different but vital role for decapsulation rules.
953With the following simple rule, if IPFilter receives an IP packet that has
954an AH header as its layer 4 payload, IPFilter would adjust its view of the
955packet internally and then jump to group 1001 using the data beyond the
956AH header as the new transport header.
957.PP
958.nf
959decapsulate in proto ah all head 1001
960.fi
961.PP
962For protocols that
963are recognised as being used with tunnelling or otherwise encapsulating
964IP protocols, IPFilter is able to decide what it has on the inside
965without any assistance. Some tunnelling protocols use UDP as the
966transport mechanism. In this case, it is necessary to instruct IPFilter
967as to what protocol is inside UDP.
968.PP
969.nf
970decapsulate l5-as(ip) in proto udp from any \\
971 to any port = 1520 head 1001
972.fi
973.PP
974Currently IPFilter only supports finding IPv4 and IPv6 headers
975directly after the UDP header.
976.PP
977If a packet matches a decapsulate rule but fails to match any of the rules
978that are within the specified group, processing of the packet continues
979to the next rule after the decapsulate and IPFilter's internal view of the
980packet is returned to what it was prior to the decapsulate rule.
981.PP
982It is possible to construct a decapsulate rule without the group
983head at the end that ipf(8) will accept but such rules will not
984result in anything happening.
985.SS Policy Based Routing
986.PP
987With firewalls being in the position they often are, at the boundary
988of different networks connecting together and multiple connections that
989have different properties, it is often desirable to have packets flow
990in a direction different to what the routing table instructs the kernel.
991These decisions can often be extended to changing the route based on
992both source and destination address or even port numbers.
993.PP
994To support this kind of configuration, IPFilter allows the next hop
995destination to be specified with a filter rule. The next hop is given
996with the interface name to use for output. The syntax for this is
997interface:ip.address. It is expected that the address given as the next
998hop is directly connected to the network to which the interface is.
999.PP
1000.nf
1001pass in on bge0 to bge1:1.1.1.1 proto tcp \\
1002 from 1.1.2.3 to any port = 80 flags S keep state
1003.fi
1004.PP
1005When this feature is combined with stateful filtering, it becomes
1006possible to influence the network interface used to transmit packets
1007in both directions because we now have a sense for what its reverse
1008flow of packets is.
1009.PP
1010.nf
1011pass in on bge0 to bge1:1.1.1.1 reply-to hme1:2.1.1.2 \\
1012 proto tcp from 1.1.2.3 to any port = 80 flags S keep state
1013.fi
1014.PP
1015If the actions of the routing table are perfectly acceptable, but
1016you would like to mask the presence of the firewall by not changing
1017the TTL in IP packets as they transit it, IPFilter can be instructed
1018to do a "fastroute" action like this:
1019.PP
1020.nf
1021pass in on bge0 fastroute proto icmp all
1022.fi
1023.PP
1024This should be used with caution as it can lead to endless packet
1025loops. Additionally, policy based routing does not change the IP
1026header's TTL value.
1027.PP
1028A variation on this type of rule supports a duplicate of the original
1029packet being created and sent out a different network. This can be
1030useful for monitoring traffic and other purposes.
1031.PP
1032.nf
1033pass in on bge0 to bge1:1.1.1.1 reply-to hme1:2.1.1.2 \\
1034 dup-to fxp0:10.0.0.1 proto tcp from 1.1.2.3 \\
1035 to any port = 80 flags S keep state
1036.fi
1037.SS Matching IPv4 options
1038.PP
1039The design for IPv4 allows for the header to be upto 64 bytes long,
1040however most traffic only uses the basic header which is 20 bytes long.
1041The other 44 bytes can be uesd to store IP options. These options are
1042generally not necessary for proper interaction and function on the
1043Internet today. For most people it is sufficient to block and drop
1044all packets that have any options set. This can be achieved with this
1045rule:
1046.PP
1047.nf
1048block in quick all with ipopts
1049.fi
1050.PP
1051This rule is usually placed towards the top of the configuration
1052so that all incoming packets are blocked.
1053.PP
1054If you wanted to allow in a specific IP option type, the syntax
1055changes slightly:
1056.PP
1057.nf
1058pass in quick proto igmp all with opt rtralrt
1059.fi
1060.PP
1061The following is a list of IP options that most people encounter and
1062what their use/threat is.
1063.HP
1064lsrr
1065(loose source route) the sender of the packet includes a list of addresses
1066that they wish the packet to be routed through to on the way to the
1067destination. Because replies to such packets are expected to use the
1068list of addresses in reverse, hackers are able to very effectively use
1069this header option in address spoofing attacks.
1070.HP
1071rr
1072(record route) the sender allocates some buffer space for recording the
1073IP address of each router that the packet goes through. This is most often
1074used with ping, where the ping response contains a copy of all addresses
1075from the original packet, telling the sender what route the packet took
1076to get there. Due to performance and security issues with IP header
1077options, this is almost no longer used.
1078.HP
1079rtralrt
1080(router alert) this option is often used in IGMP messages as a flag to
1081routers that the packet needs to be handled differently. It is unlikely
1082to ever be received from an unknown sender. It may be found on LANs or
1083otherwise controlled networks where the RSVP protocol and multicast
1084traffic is in heavy use.
1085.HP
1086ssrr
1087(strict source route) the sender of the packet includes a list of addresses
1088that they wish the packet to be routed through to on the way to the
1089destination. Where the lsrr option allows the sender to specify only
1090some of the nodes the packet must go through, with the ssrr option,
1091every next hop router must be specified.
1092.PP
1093The complete list of IPv4 options that can be matched on is:
1094addext (Address Extention),
1095cipso (Classical IP Security Option),
1096dps (Dynamic Packet State),
1097e-sec (Extended Security),
1098eip (Extended Internet Protocol),
1099encode (ENCODE),
1100finn (Experimental Flow Control),
1101imitd (IMI Traffic Descriptor),
1102lsrr (Loose Source Route),
1103mtup (MTU Probe - obsolete),
1104mtur (MTU response - obsolete),
1105nop (No Operation),
1106nsapa (NSAP Address),
1107rr (Record Route),
1108rtralrt (Router Alert),
1109satid (Stream Identifier),
1110sdb (Selective Directed Broadcast),
1111sec (Security),
1112ssrr (Strict Source Route),
1113tr (Tracerote),
1114ts (Timestamp),
1115ump (Upstream Multicast Packet),
1116visa (Experimental Access Control)
1117and zsu (Experimental Measurement).
1118.SS Security with CIPSO and IPSO
1119.PP
1120IPFilter supports filtering on IPv4 packets using security attributes embedded
1121in the IP options part of the packet. These options are usually only used on
1122networks and systems that are using lablled security. Unless you know that
1123you are using labelled security and your networking is also labelled, it
1124is highly unlikely that this section will be relevant to you.
1125.PP
1126With the traditional IP Security Options (IPSO), packets can be tagged with
1127a security level. The following keywords are recognised and match with the
1128relevant RFC with respect to the bit patterns matched:
1129confid (confidential),
1130rserve-1 (1st reserved value),
1131rserve-2 (2nd reserved value),
1132rserve-3 (3rd reserved value),
1133rserve-4 (4th reserved value),
1134secret (secret),
1135topsecret (top secret),
1136unclass (unclassified).
1137.PP
1138.nf
1139block in quick all with opt sec-class unclass
1140pass in all with opt sec-class secret
1141.fi
1142.SS Matching IPv6 extension headers
1143.PP
1144Just as it is possible to filter on the various IPv4 header options,
1145so too it is possible to filter on the IPv6 extension headers that are
1146placed between the IPv6 header and the transport protocol header.
1147.PP
1148dstopts (destination options),
1149esp (encrypted, secure, payload),
1150frag (fragment),
1151hopopts (hop-by-hop options),
1152ipv6 (IPv6 header),
1153mobility (IP mobility),
1154none,
1155routing.
1156.SS Logging
1157.PP
1158There are two ways in which packets can be logged with IPFilter. The
1159first is with a rule that specifically says log these types of packets
1160and the second is a qualifier to one of the other keywords. Thus it is
1161possible to both log and allow or deny a packet with a single rule.
1162.PP
1163.nf
1164pass in log quick proto tcp from any to any port = 22
1165.fi
1166.PP
1167When using stateful filtering, the log action becomes part of the result
1168that is remembered about a packet. Thus if the above rule was qualified
1169with keep state, every packet in the connection would be logged. To only
1170log the first packet from every packet flow tracked with keep state, it
1171is necessary to indicate to IPFilter that you only wish to log the first
1172packet.
1173.PP
1174.nf
1175pass in log first quick proto tcp from any to any port = 22 \\
1176 flags S keep state
1177.fi
1178.PP
1179If it is a requirement that the logging provide an accurate representation
1180of which connections are allowed, the log action can be qualified with the
1181option or-block. This allows the administrator to instruct IPFilter to
1182block the packet if the attempt to record the packet in IPFilter's kernel
1183log records (which have an upper bound on size) failed. Unless the system
1184shuts down or reboots, once a log record is written into the kernel buffer,
1185it is there until ipmon(8) reads it.
1186.PP
1187.nf
1188block in log proto tcp from any to any port = smtp
1189pass in log or-block first quick proto tcp from any \\
1190 to any port = 22 flags S keep state
1191.fi
1192.PP
1193By default, IPFilter will only log the header portion of a packet received
1194on the network. A portion of the body of a packet, upto 128 bytes, can also
1195be logged with the body keyword. ipmon(8) will display the contents of the
1196portion of the body logged in hex.
1197.PP
1198.nf
1199block in log body proto icmp all
1200.fi
1201.PP
1202When logging packets from ipmon(8) to syslog, by default ipmon(8) will
1203control what syslog facility and priority a packet will be logged with.
1204This can be tuned on a per rule basis like this:
1205.PP
1206.nf
1207block in quick log level err all with bad
1208pass in log level local1.info proto tcp \\
1209 from any to any port = 22 flags S keep state
1210.fi
1211.PP
1212ipfstat(8) reports how many packets have been successfully logged and how
1213many failed attempts to log a packet there were.
1214.SS Filter rule comments
1215.PP
1216If there is a desire to associate a text string, be it an administrative
1217comment or otherwise, with an IPFilter rule, this can be achieved by giving
1218the filter rule a comment. The comment is loaded with the rule into the
1219kernel and can be seen when the rules are listed with ipfstat.
1220.PP
1221.nf
1222pass in quick proto tcp from any \\
1223 to port = 80 comment "all web server traffic is ok"
1224pass out quick proto tcp from any port = 80 \\
1225 to any comment "all web server traffic is ok"
1226.fi
1227.SS Tags
1228.PP
1229To enable filtering and NAT to correctly match up packets with rules,
1230tags can be added at with NAT (for inbound packets) and filtering (for
1231outbound packets.) This allows a filter to be correctly mated with its
1232NAT rule in the event that the NAT rule changed the packet in a way
1233that would mean it is not obvious what it was.
1234.PP
1235For inbound packets, IPFilter can match the tag used in the filter
1236rules with that set by NAT. For outbound rules, it is the reverse,
1237the filter sets the tag and the NAT rule matches up with it.
1238.PP
1239.nf
1240pass in ... match-tag(nat=proxy)
1241pass out ... set-tag(nat=proxy)
1242.fi
1243.PP
1244Another use of tags is to supply a number that is only used with logging.
1245When packets match these rules, the log tag is carried over into the
1246log file records generated by ipmon(8). With the correct use of tools
1247such as grep, extracting log records of interest is simplified.
1248.PP
1249.nf
1250block in quick log ... set-tag(log=33)
1251.fi
1252.SH Filter Rule Expiration
1253.PP
1254IPFilter allows rules to be added into the kernel that it will remove after
1255a specific period of time by specifying rule-ttl at the end of a rule.
1256When listing rules in the kernel using ipfstat(8), rules that are going
1257to expire will NOT display "rule-ttl" with the timeout, rather what will
1258be seen is a comment with how many ipfilter ticks left the rule has to
1259live.
1260.PP
1261The time to live is specified in seconds.
1262.PP
1263.nf
1264pass in on fxp0 proto tcp from any \\
1265 to port = 22 flags S keep state rule-ttl 30
1266.fi
1267.SH Internal packet attributes
1268.PP
1269In addition to being able to filter on very specific network and transport
1270header fields, it is possible to filter on other attributes that IPFilter
1271attaches to a packet. These attributes are placed in a rule after the
1272keyword "with", as can be seen with frags and frag-body above. The
1273following is a list of the other attributes available:
1274.HP
1275oow
1276the packet's IP addresses and TCP ports match an existing entry in the
1277state table but the sequence numbers indicate that it is outside of the
1278accepted window.
1279.IP
1280.nf
1281block return-rst in quick proto tcp from any to any with not oow
1282.fi
1283.HP
1284bcast
1285this is set by IPFilter when it receives notification that the link
1286layer packet was a broadcast packet. No checking of the IP addresses
1287is performned to determine if it is a broadcast destination or not.
1288.IP
1289.nf
1290block in quick proto udp all with bcast
1291.fi
1292.HP
1293mcast
1294this is set by IPFilter when it receives notification that the link
1295layer packet was a multicast packet. No checking of the IP addresses
1296is performned to determine if it is a multicast destination or not.
1297.IP
1298.nf
1299pass in quick proto udp from any to any port = dns with mcast
1300.fi
1301.HP
1302mbcast
1303can be used to match a packet that is either a multicast or broadcast
1304packet at the link layer, as indicated by the operating system.
1305.IP
1306.nf
1307pass in quick proto udp from any to any port = ntp with mbcast
1308.fi
1309.HP
1310nat
1311the packet positively matched a NAT table entry.
1312.HP
1313bad
1314sanity checking of the packet failed. This could indicate that the
1315layer 3/4 headers are not properly formed.
1316.HP
1317bad-src
1318when reverse path verification is enabled, this flag will be set when
1319the interface the packet is received on does not match that which would
1320be used to send a packet out of to the source address in the received
1321packet.
1322.HP
1323bad-nat
1324an attempt to perform NAT on the packet failed.
1325.HP
1326not
1327each one of the attributes matched using the "with" keyword can also be
1328looked for to not be present. For example, to only allow in good packets,
1329I can do this:
1330.PP
1331.nf
1332block in all
1333pass in all with not bad
1334.fi
1335.SH Tuning IPFilter
1336.PP
1337The ipf.conf file can also be used to tune the behaviour of IPFilter,
1338allowing, for example, timeouts for the NAT/state table(s) to be set
1339along with their sizes. The presence and names of tunables may change
1340from one release of IPFilter to the next. The tunables that can be
1341changed via ipf.conf is the same as those that can be seen and modified
1342using the -T command line option to ipf(8).
1343.PP
1344NOTE: When parsing ipf.conf, ipf(8) will apply the settings before
1345loading any rules. Thus if your settings are at the top, these may
1346be applied whilst the rules not applied if there is an error further
1347down in the configuration file.
1348.PP
1349To set one of the values below, the syntax is simple: "set", followed
1350by the name of the tuneable to set and then the value to set it to.
1351.PP
1352.nf
1353set state_max 9999;
1354set state_size 10101;
1355.fi
1356.PP
1357A list of the currently available variables inside IPFilter that may
1358be tuned from ipf.conf are as follows:
1359.HP
1360active
1361set through -s command line switch of ipf(8). See ipf(8) for detals.
1362.HP
1363chksrc
1364when set, enables reverse path verification on source addresses and
1365for filters to match packets with bad-src attribute.
1366.HP
1367control_forwarding
1368when set turns off kernel forwarding when IPFilter is disabled or unloaded.
1369.HP
1370default_pass
1371the default policy - whether packets are blocked or passed, etc - is
1372represented by the value of this variable. It is a bit field and the
1373bits that can be set are found in <netinet/ip_fil.h>. It is not
1374recommended to tune this value directly.
1375.HP
1376ftp_debug
1377set the debugging level of the in-kernel FTP proxy.
1378Debug messages will be printed to the system console.
1379.HP
1380ftp_forcepasv
1381when set the FTP proxy must see a PASV/EPSV command before creating
1382the state/NAT entries for the 227 response.
1383.HP
1384ftp_insecure
1385when set the FTP proxy will not wait for a user to login before allowing
1386data connections to be created.
1387.HP
1388ftp_pasvonly
1389when set the proxy will not create state/NAT entries for when it
1390sees either the PORT or EPRT command.
1391.HP
1392ftp_pasvrdr
1393when enabled causes the FTP proxy to create very insecure NAT/state
1394entries that will allow any connection between the client and server
1395hosts when a 227 reply is seen. Use with extreme caution.
1396.HP
1397ftp_single_xfer
1398when set the FTP proxy will only allow one data connection at a time.
1399.HP
1400hostmap_size
1401sets the size of the hostmap table used by NAT to store address mappings
1402for use with sticky rules.
1403.HP
1404icmp_ack_timeout
1405default timeout used for ICMP NAT/state when a reply packet is seen for
1406an ICMP state that already exists
1407.HP
1408icmp_minfragmtu
1409sets the minimum MTU that is considered acceptable in an ICMP error
1410before deciding it is a bad packet.
1411.HP
1412icmp_timeout
1413default timeout used for ICMP NAT/state when the packet matches the rule
1414.HP
1415ip_timeout
1416default timeout used for NAT/state entries that are not TCP/UDP/ICMP.
1417.HP
1418ipf_flags
1419.HP
1420ips_proxy_debug
1421this sets the debugging level for the proxy support code.
1422When enabled, debugging messages will be printed to the system console.
1423.HP
1424log_all
1425when set it changes the behaviour of "log body" to log the entire packet
1426rather than just the first 128 bytes.
1427.HP
1428log_size
1429sets the size of the in-kernel log buffer in bytes.
1430.HP
1431log_suppress
1432when set, IPFilter will check to see if the packet it is logging is
1433similar to the one it previously logged and if so, increases
1434the occurance count for that packet. The previously logged packet
1435must not have yet been read by ipmon(8).
1436.HP
1437min_ttl
1438is used to set the TTL value that packets below will be marked with
1439the low-ttl attribute.
1440.HP
1441nat_doflush
1442if set it will cause the NAT code to do a more aggressive flush of the
1443NAT table at the next opportunity. Once the flush has been done, the
1444value is reset to 0.
1445.HP
1446nat_lock
1447this should only be changed using ipfs(8)
1448.HP
1449nat_logging
1450when set, NAT will create log records that can be read from /dev/ipnat.
1451.HP
1452nat_maxbucket
1453maximum number of entries allowed to exist in each NAT hash bucket.
1454This prevents an attacker trying to load up the hash table with
1455entries in a single bucket, reducing performance.
1456.HP
1457nat_rules_size
1458size of the hash table to store map rules.
1459.HP
1460nat_table_max
1461maximum number of entries allowed into the NAT table
1462.HP
1463nat_table_size
1464size of the hash table used for NAT
1465.HP
1466nat_table_wm_high
1467when the fill percentage of the NAT table exceeds this mark, more
1468aggressive flushing is enabled.
1469.HP
1470nat_table_wm_low
1471this sets the percentage at which the NAT table's agressive flushing
1472will turn itself off at.
1473.HP
1474rdr_rules_size
1475size of the hash table to store rdr rules.
1476.HP
1477state_lock
1478this should only be changed using ipfs(8)
1479.HP
1480state_logging
1481when set, the stateful filtering will create log records
1482that can be read from /dev/ipstate.
1483.HP
1484state_max
1485maximum number of entries allowed into the state table
1486.HP
1487state_maxbucket
1488maximum number of entries allowed to exist in each state hash bucket.
1489This prevents an attacker trying to load up the hash table with
1490entries in a single bucket, reducing performance.
1491.HP
1492state_size
1493size of the hash table used for stateful filtering
1494.HP
1495state_wm_freq
1496this controls how often the agressive flushing should be run once the
1497state table exceeds state_wm_high in percentage full.
1498.HP
1499state_wm_high
1500when the fill percentage of the state table exceeds this mark, more
1501aggressive flushing is enabled.
1502.HP
1503state_wm_low
1504this sets the percentage at which the state table's agressive flushing
1505will turn itself off at.
1506.HP
1507tcp_close_wait
1508timeout used when a TCP state entry reaches the FIN_WAIT_2 state.
1509.HP
1510tcp_closed
1511timeout used when a TCP state entry is ready to be removed after either
1512a RST packet is seen.
1513.HP
1514tcp_half_closed
1515timeout used when a TCP state entry reaches the CLOSE_WAIT state.
1516.HP
1517tcp_idle_timeout
1518timeout used when a TCP state entry reaches the ESTABLISHED state.
1519.HP
1520tcp_last_ack
1521timeout used when a TCP NAT/state entry reaches the LAST_ACK state.
1522.HP
1523tcp_syn_received
1524timeout applied to a TCP NAT/state entry after SYN-ACK packet has been seen.
1525.HP
1526tcp_syn_sent
1527timeout applied to a TCP NAT/state entry after SYN packet has been seen.
1528.HP
1529tcp_time_wait
1530timeout used when a TCP NAT/state entry reaches the TIME_WAIT state.
1531.HP
1532tcp_timeout
1533timeout used when a TCP NAT/state entry reaches either the half established
1534state (one ack is seen after a SYN-ACK) or one side is in FIN_WAIT_1.
1535.HP
1536udp_ack_timeout
1537default timeout used for UDP NAT/state when a reply packet is seen for
1538a UDP state that already exists
1539.HP
1540udp_timeout
1541default timeout used for UDP NAT/state when the packet matches the rule
1542.HP
1543update_ipid
1544when set, turns on changing the IP id field in NAT'd packets to a random
1545number.
1546.SS Table of visible variables
1547.PP
1548A list of all of the tunables, their minimum, maximum and current
1549values is as follows.
1550.PP
1551.nf
1552Name Min Max Current
1553active 0 0 0
1554chksrc 0 1 0
1555control_forwarding 0 1 0
1556default_pass 0 MAXUINT 134217730
1557ftp_debug 0 10 0
1558ftp_forcepasv 0 1 1
1559ftp_insecure 0 1 0
1560ftp_pasvonly 0 1 0
1561ftp_pasvrdr 0 1 0
1562ftp_single_xfer 0 1 0
1563hostmap_size 1 MAXINT 2047
1564icmp_ack_timeout 1 MAXINT 12
1565icmp_minfragmtu 0 1 68
1566icmp_timeout 1 MAXINT 120
1567ip_timeout 1 MAXINT 120
1568ipf_flags 0 MAXUINT 0
1569ips_proxy_debug 0 10 0
1570log_all 0 1 0
1571log_size 0 524288 32768
1572log_suppress 0 1 1
1573min_ttl 0 1 4
1574nat_doflush 0 1 0
1575nat_lock 0 1 0
1576nat_logging 0 1 1
1577nat_maxbucket 1 MAXINT 22
1578nat_rules_size 1 MAXINT 127
1579nat_table_max 1 MAXINT 30000
1580nat_table_size 1 MAXINT 2047
1581nat_table_wm_high 2 100 99
1582nat_table_wm_low 1 99 90
1583rdr_rules_size 1 MAXINT 127
1584state_lock 0 1 0
1585state_logging 0 1 1
1586state_max 1 MAXINT 4013
1587state_maxbucket 1 MAXINT 26
1588state_size 1 MAXINT 5737
1589state_wm_freq 2 999999 20
1590state_wm_high 2 100 99
1591state_wm_low 1 99 90
1592tcp_close_wait 1 MAXINT 480
1593tcp_closed 1 MAXINT 60
1594tcp_half_closed 1 MAXINT 14400
1595tcp_idle_timeout 1 MAXINT 864000
1596tcp_last_ack 1 MAXINT 60
1597tcp_syn_received 1 MAXINT 480
1598tcp_syn_sent 1 MAXINT 480
1599tcp_time_wait 1 MAXINT 480
1600tcp_timeout 1 MAXINT 480
1601udp_ack_timeout 1 MAXINT 24
1602udp_timeout 1 MAXINT 240
1603update_ipid 0 1 0
1604.fi
1605.SH Calling out to internal functions
1606.PP
1607IPFilter provides a pair of functions that can be called from a rule
1608that allow for a single rule to jump out to a group rather than walk
1609through a list of rules to find the group. If you've got multiple
1610networks, each with its own group of rules, this feature may help
1611provide better filtering performance.
1612.PP
1613The lookup to find which rule group to jump to is done on either the
1614source address or the destination address but not both.
1615.PP
1616In this example below, we are blocking all packets by default but then
1617doing a lookup on the source address from group 1010. The two rules in
1618the ipf.conf section are lone members of their group. For an incoming
1619packet that is from 1.1.1.1, it will go through three rules: (1) the
1620block rule, (2) the call rule and (3) the pass rule for group 1020.
1621For a packet that is from 3.3.2.2, it will also go through three rules:
1622(1) the block rule, (2) the call rule and (3) the pass rule for group
16231030. Should a packet from 3.1.1.1 arrive, it will be blocked as it
1624does not match any of the entries in group 1010, leaving it to only
1625match the first rule.
1626.PP
1627.nf
1628from ipf.conf
1629-------------
1630block in all
1631call now srcgrpmap/1010 in all
1632pass in proto tcp from any to any port = 80 group 1020
1633pass in proto icmp all icmp-type echo group 1030
|
521
| 1634
|
522and to then allow ICMP packets in on le0, only, we would do:
523.LP
| 1635from ippool.conf
1636----------------
1637group-map in role=ipf number=1010
1638 { 1.1.1.1 group = 1020, 3.3.0.0/16 group = 1030; };
1639.fi
1640.SS IPFilter matching expressions
1641.PP
1642An experimental feature that has been added to filter rules is to use
1643the same expression matching that is available with various commands
1644to flush and list state/NAT table entries. The use of such an expression
1645precludes the filter rule from using the normal IP header matching.
1646.PP
|
524.nf
| 1647.nf
|
525 pass in proto icmp all group 100
| 1648pass in exp { "tcp.sport 23 or tcp.sport 50" } keep state
|
526.fi
| 1649.fi
|
| 1650.SS Filter rules with BPF
|
527.PP
| 1651.PP
|
528Note that because only inbound packets on le0 are used processed by group 100,
529there is no need to respecify the interface name. Likewise, we could further
530breakup processing of TCP, etc, as follows:
531.LP
| 1652On platforms that have the BPF built into the kernel, IPFilter can be
1653built to allow BPF expressions in filter rules. This allows for packet
1654matching to be on arbitrary data in the packt. The use of a BPF expression
1655replaces all of the other protocol header matching done by IPFilter.
1656.PP
|
532.nf
| 1657.nf
|
533 block in proto tcp all head 110 group 100
534 pass in from any to any port = 23 group 110
| 1658pass in bpf-v4 { "tcp and (src port 23 or src port 50)" } \\
1659 keep state
|
535.fi
536.PP
| 1660.fi
1661.PP
|
537and so on. The last line, if written without the groups would be:
538.LP
| 1662These rules tend to be
1663write-only because the act of compiling the filter expression into the
1664BPF instructions loaded into the kernel can make it difficut to
1665accurately reconstruct the original text filter. The end result is that
1666while ipf.conf() can be easy to read, understanding the output from
1667ipfstat might not be.
1668.SH VARIABLES
1669.PP
1670This configuration file, like all others used with IPFilter, supports the
1671use of variable substitution throughout the text.
1672.PP
|
539.nf
| 1673.nf
|
540 pass in on le0 proto tcp from any to any port = telnet
| 1674nif="ppp0";
1675pass in on $nif from any to any
|
541.fi
542.PP
| 1676.fi
1677.PP
|
543Note, that if we wanted to say "port = telnet", "proto tcp" would
544need to be specified as the parser interprets each rule on its own and
545qualifies all service/port names with the protocol specified.
| 1678would become
1679.PP
1680.nf
1681pass in on ppp0 from any to any
1682.fi
1683.PP
1684Variables can be used recursively, such as 'foo="$bar baz";', so long as
1685$bar exists when the parser reaches the assignment for foo.
1686.PP
1687See
1688.B ipf(8)
1689for instructions on how to define variables to be used from a shell
1690environment.
1691.DT
|
546.SH FILES
| 1692.SH FILES
|
547/dev/ipauth
| 1693/dev/ipf
1694/etc/ipf.conf
|
548.br
| 1695.br
|
549/dev/ipl
550.br
551/dev/ipstate
552.br
553/etc/hosts
554.br
555/etc/services
| 1696/usr/share/examples/ipf Directory with examples.
|
556.SH SEE ALSO
| 1697.SH SEE ALSO
|
557ipftest(1), iptest(1), mkfilters(1), ipf(4), ipnat(5), ipf(8), ipfstat(8)
| 1698ipf(8), ipfstat(8), ippool.conf(5), ippool(8)
|
| |