diff options
Diffstat (limited to 'contrib/pf/man/pf.conf.5')
| -rw-r--r-- | contrib/pf/man/pf.conf.5 | 370 |
1 files changed, 287 insertions, 83 deletions
diff --git a/contrib/pf/man/pf.conf.5 b/contrib/pf/man/pf.conf.5 index cbe3b52..d7d5d82 100644 --- a/contrib/pf/man/pf.conf.5 +++ b/contrib/pf/man/pf.conf.5 @@ -230,7 +230,7 @@ command. .Bl -tag -width xxxx .It Ar set timeout .Pp -.Bl -tag -width interval -compact +.Bl -tag -width "src.track" -compact .It Ar interval Interval between purging expired states and fragments. .It Ar frag @@ -484,6 +484,16 @@ For example: .Pp .Dl set fingerprints \&"/etc/pf.os.devel\&" .Pp +.It Ar set skip on <ifspec> +List interfaces for which packets should not be filtered. +Packets passing in or out on such interfaces are passed as if pf was +disabled, i.e. pf does not process them in any way. +This can be useful on loopback and other virtual interfaces, when +packet filtering is not desired and can have unexpected effects. +For example: +.Pp +.Dl set skip on lo0 +.Pp .It Ar set debug Set the debug .Ar level @@ -548,7 +558,7 @@ Enforces a maximum MSS for matching TCP packets. .It Ar random-id Replaces the IP identification field with random values to compensate for predictable values generated by many hosts. -This option only applies to outgoing packets that are not fragmented +This option only applies to packets that are not fragmented after the optional fragment reassembly. .It Ar fragment reassemble Using @@ -602,7 +612,7 @@ the firewall state, and expires before reaching the destination host. .Ar reassemble tcp will raise the TTL of all packets back up to the highest value seen on the connection. -.It timeout modulation +.It timestamp modulation Modern TCP stacks will send a timestamp on every TCP packet and echo the other endpoint's timestamp back to them. Many operating systems will merely start the timestamp at zero when @@ -619,6 +629,24 @@ guessable base time. will cause .Ar scrub to modulate the TCP timestamps with a random number. +.It extended PAWS checks +There is a problem with TCP on long fat pipes, in that a packet might get +delayed for longer than it takes the connection to wrap its 32-bit sequence +space. +In such an occurrence, the old packet would be indistinguishable from a +new packet and would be accepted as such. +The solution to this is called PAWS: Protection Against Wrapped Sequence +numbers. +It protects against it by making sure the timestamp on each packet does +not go backwards. +.Ar reassemble tcp +also makes sure the timestamp on the packet does not go forward more +than the RFC allows. +By doing this, +.Xr pf 4 +artificially extends the security of TCP sequence numbers by 10 to 18 +bits when the host uses appropriately randomized timestamps, since a +blind attacker would have to guess the timestamp as well. .El .El .Pp @@ -626,6 +654,15 @@ For example, .Bd -literal -offset indent scrub in on $ext_if all fragment reassemble .Ed +.Pp +The +.Ar no +option prefixed to a scrub rule causes matching packets to remain unscrubbed, +much in the same way as +.Ar drop quick +works in the packet filter (see below). +This mechanism should be used when it is necessary to exclude specific packets +from broader scrub rules. .Sh QUEUEING/ALTQ The ALTQ system is currently not available in the GENERIC kernel nor as loadable modules. @@ -673,6 +710,18 @@ assigned. mainly controls the time packets take to get sent out, while .Ar bandwidth has primarily effects on throughput. +.Ar cbq +achieves both partitioning and sharing of link bandwidth +by hierarchically structured classes. +Each class has its own +.Ar queue +and is assigned its share of +.Ar bandwidth . +A child class can borrow bandwidth from its parent class +as long as excess bandwidth is available +(see the option +.Ar borrow , +below). .It Ar priq Priority Queueing. .Ar Queues @@ -706,6 +755,14 @@ assigned. mainly controls the time packets take to get sent out, while .Ar bandwidth has primarily effects on throughput. +.Ar hfsc +supports both link-sharing and guaranteed real-time services. +It employs a service curve based QoS model, +and its unique feature is an ability to decouple +.Ar delay +and +.Ar bandwidth +allocation. .El .Pp The interfaces on which queueing should be activated are declared using @@ -791,6 +848,7 @@ This value must not exceed the value of the parent .Ar queue and can be specified as an absolute value or a percentage of the parent queue's bandwidth. +If not specified, defaults to 100% of the parent queue's bandwidth. The .Ar priq scheduler does not support bandwidth specification. @@ -919,8 +977,8 @@ queue developers bandwidth 75% cbq(borrow) queue employees bandwidth 15% queue mail bandwidth 10% priority 0 cbq(borrow ecn) queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk } -queue ssh_interactive priority 7 -queue ssh_bulk priority 0 +queue ssh_interactive bandwidth 50% priority 7 cbq(borrow) +queue ssh_bulk bandwidth 50% priority 0 cbq(borrow) block return out on dc0 inet all queue std pass out on dc0 inet proto tcp from $developerhosts to any port 80 \e @@ -944,8 +1002,8 @@ the packet filter for evaluation. .Pp Since translation occurs before filtering the filter engine will see packets as they look after any -addresses and ports have been translated. Filter rules -will therefore have to filter based on the translated +addresses and ports have been translated. +Filter rules will therefore have to filter based on the translated address and port number. Packets that match a translation rule are only automatically passed if the @@ -1107,10 +1165,11 @@ This causes a TCP RST to be returned for packets and an ICMP UNREACHABLE for UDP and other packets. .El .Pp -Options returning packets have no effect if +Options returning ICMP packets currently have no effect if .Xr pf 4 operates on a -.Xr bridge 4 . +.Xr bridge 4 , +as the code to support this feature has not yet been implemented. .It Ar pass The packet is passed. .El @@ -1221,9 +1280,16 @@ addresses and ports. Addresses can be specified in CIDR notation (matching netblocks), as symbolic host names or interface names, or as any of the following keywords: .Pp -.Bl -tag -width xxxxxxxxxxxx -compact +.Bl -tag -width xxxxxxxxxxxxxx -compact .It Ar any Any address. +.It Ar route <label> +Any address whose associated route has label +.Ar <label> . +See +.Xr route 4 +and +.Xr route 8 . .It Ar no-route Any address which is not currently routable. .It Ar <table> @@ -1317,6 +1383,7 @@ pass in proto tcp from any to any port 25 pass in proto tcp from 10.0.0.0/8 port > 1024 \e to ! 10.1.2.3 port != ssh pass in proto tcp from any os "OpenBSD" flags S/SA +pass in proto tcp from route "DTAG" .Ed .It Ar all This is equivalent to "from any to any". @@ -1412,9 +1479,18 @@ All of SYN, FIN, RST and ACK must be unset. .It Ar icmp6-type <type> code <code> This rule only applies to ICMP or ICMPv6 packets with the specified type and code. +Text names for ICMP types and codes are listed in +.Xr icmp 4 +and +.Xr icmp6 4 . This parameter is only valid for rules that cover protocols ICMP or ICMP6. -The protocol and the ICMP type indicator (icmp-type or icmp6-type) +The protocol and the ICMP type indicator +.Po +.Ar icmp-type +or +.Ar icmp6-type +.Pc must match. .It Ar allow-opts By default, packets which contain IP options are blocked. @@ -1520,7 +1596,7 @@ or rules in addition to filter rules. Tags take the same macros as labels (see above). .It Ar tagged <string> -Used with filter rules to specify that packets must already +Used with filter or translation rules to specify that packets must already be tagged with the given tag in order to match the rule. Inverse tag matching can also be done by specifying the @@ -1528,6 +1604,15 @@ by specifying the operator before the .Ar tagged keyword. +.It Ar probability <number> +A probability attribute can be attached to a rule, with a value set between +0 and 1, bounds not included. +In that case, the rule will be honoured using the given probability value +only. +For example, the following rule will drop 20% of incoming ICMP packets: +.Bd -literal -offset indent +block in proto icmp probability 20% +.Ed .El .Sh ROUTING If a packet matches a rule with a route option set, the packet filter will @@ -1558,7 +1643,7 @@ option is similar to but routes packets that pass in the opposite direction (replies) to the specified interface. Opposite direction is only defined in the context of a state entry, and -.Ar route-to +.Ar reply-to is useful only in rules that create state. It can be used on systems with multiple external connections to route all outgoing packets of a connection through the interface @@ -1875,32 +1960,96 @@ Prevent state changes for states created by this rule from appearing on the interface. .It Ar <timeout> <seconds> Changes the timeout values used for states created by this rule. +For a list of all valid timeout names, see +.Sx OPTIONS +above. +.El +.Pp +Multiple options can be specified, separated by commas: +.Bd -literal -offset indent +pass in proto tcp from any to any \e + port www flags S/SA keep state \e + (max 100, source-track rule, max-src-nodes 75, \e + max-src-states 3, tcp.established 60, tcp.closing 5) +.Ed .Pp When the .Ar source-track keyword is specified, the number of states per source IP is tracked. +.Pp +.Bl -tag -width xxxx -compact +.It Ar source-track rule +The maximum number of states created by this rule is limited by the rule's +.Ar max-src-nodes +and +.Ar max-src-state +options. +Only state entries created by this particular rule count toward the rule's +limits. +.It Ar source-track global +The number of states created by all rules that use this option is limited. +Each rule can specify different +.Ar max-src-nodes +and +.Ar max-src-states +options, however state entries created by any participating rule count towards +each individual rule's limits. +.El +.Pp The following limits can be set: .Pp -.Bl -tag -width xxxx -compact -.It Ar max-src-nodes +.Bl -tag -width xxxx -compact +.It Ar max-src-nodes <number> Limits the maximum number of source addresses which can simultaneously have state table entries. -.It Ar max-src-states +.It Ar max-src-states <number> Limits the maximum number of simultaneous state entries that a single source address can create with this rule. .El -For a list of all valid timeout names, see -.Sx OPTIONS -above. .Pp -Multiple options can be specified, separated by commas: -.Bd -literal -pass in proto tcp from any to any \e - port www flags S/SA keep state \e - (max 100, source-track rule, max-src-nodes 75, \e - max-src-states 3, tcp.established 60, tcp.closing 5) -.Ed +For stateful TCP connections, limits on established connections (connections +which have completed the TCP 3-way handshake) can also be enforced +per source IP. +.Pp +.Bl -tag -width xxxx -compact +.It Ar max-src-conn <number> +Limits the maximum number of simultaneous TCP connections which have +completed the 3-way handshake that a single host can make. +.It Ar max-src-conn-rate <number> / <seconds> +Limit the rate of new connections over a time interval. +The connection rate is an approximation calculated as a moving average. .El +.Pp +Because the 3-way handshake ensures that the source address is not being +spoofed, more aggressive action can be taken based on these limits. +With the +.Ar overload <table> +state option, source IP addresses which hit either of the limits on +established connections will be added to the named table. +This table can be used in the ruleset to block further activity from +the offending host, redirect it to a tarpit process, or restrict its +bandwidth. +.Pp +The optional +.Ar flush +keyword kills all states created by the matching rule which originate +from the host which exceeds these limits. +The +.Ar global +modifier to the flush command kills all states originating from the +offending host, regardless of which rule created the state. +.Pp +For example, the following rules will protect the webserver against +hosts making more than 100 connections in 10 seconds. +Any host which connects faster than this rate will have its address added +to the <bad_hosts> table and have all states originating from it flushed. +Any new packets arriving from this host will be dropped unconditionally +by the block rule. +.Bd -literal -offset indent +block quick from <bad_hosts> +pass in on $ext_if proto tcp to $webserver port www flags S/SA keep state \e + (max-src-conn-rate 100/10, overload <bad_hosts> flush global) +.Ed .Sh OPERATING SYSTEM FINGERPRINTING Passive OS Fingerprinting is a mechanism to inspect nuances of a TCP connection's initial SYN packet and guess at the host's operating system. @@ -1911,7 +2060,7 @@ upon. .Pp The fingerprints may be specified by operating system class, by version, or by subtype/patchlevel. -The class of an operating system is typically the vender or genre +The class of an operating system is typically the vendor or genre and would be OpenBSD for the .Xr pf 4 firewall itself. @@ -2076,84 +2225,87 @@ The timeout value can also be adjusted. .Pp Currently, only IPv4 fragments are supported and IPv6 fragments are blocked unconditionally. -.Sh ANCHORS AND NAMED RULESETS +.Sh ANCHORS Besides the main ruleset, .Xr pfctl 8 -can load named rulesets into +can load rulesets into .Ar anchor attachment points. An .Ar anchor -contains a list of named rulesets. +is a container that can hold rules, address tables, and other anchors. +.Pp An .Ar anchor -has a name which specifies where +has a name which specifies the path where .Xr pfctl 8 -can be used to attach sub-rulesets. -A named ruleset contains filter and translation rules, like the -main ruleset. -The main ruleset can reference +can be used to access the anchor to perform operations on it, such as +attaching child anchors to it or loading rules into it. +Anchors may be nested, with components separated by +.Sq / +characters, similar to how file system hierarchies are laid out. +The main ruleset is actually the default anchor, so filter and +translation rules, for example, may also be contained in any anchor. +.Pp +An anchor can reference another .Ar anchor -attachment points +attachment point using the following kinds of rules: .Bl -tag -width xxxx .It Ar nat-anchor <name> Evaluates the .Ar nat -rules of all named rulesets in the specified +rules in the specified .Ar anchor . .It Ar rdr-anchor <name> Evaluates the .Ar rdr -rules of all named rulesets in the specified +rules in the specified .Ar anchor . .It Ar binat-anchor <name> Evaluates the .Ar binat -rules of all named rulesets in the specified +rules in the specified .Ar anchor . .It Ar anchor <name> -Evaluates the filter rules of all named rulesets in the specified +Evaluates the filter rules in the specified .Ar anchor . -.It Ar load anchor <name>:<ruleset> from <file> -Loads the rules from the specified file into the named -ruleset -.Ar <ruleset> -attached to the anchor -.Ar <name> . +.It Ar load anchor <name> from <file> +Loads the rules from the specified file into the +anchor +.Ar name . .El .Pp When evaluation of the main ruleset reaches an .Ar anchor rule, .Xr pf 4 -will proceed to evaluate all rules specified in the -named rulesets attached to that -.Ar anchor . +will proceed to evaluate all rules specified in that anchor. .Pp -Matching filter rules in named rulesets with the +Matching filter and translation rules in anchors with the .Ar quick -option and matching translation rules are final and abort the -evaluation of both the rules in the -.Ar anchor +option are final and abort the evaluation of the rules in other +anchors and the main ruleset. .Pp -Only the main ruleset can contain .Ar anchor -rules. -.Pp -When an +rules are evaluated relative to the anchor in which they are contained. +For example, all +.Ar anchor +rules specified in the main ruleset will reference anchor +attachment points underneath the main ruleset, and .Ar anchor -contains more than one named ruleset, they are evaluated -in the alphabetical order of their names. +rules specified in a file loaded from a +.Ar load anchor +rule will be attached under that anchor point. .Pp -Rules may contain +Rules may be contained in .Ar anchor attachment points which do not contain any rules when the main ruleset -is loaded, and later such named rulesets can be manipulated through +is loaded, and later such anchors can be manipulated through .Xr pfctl 8 -without reloading the main ruleset. +without reloading the main ruleset or other anchors. For example, .Bd -literal -offset indent ext_if = \&"kue0\&" @@ -2165,27 +2317,27 @@ pass in on $ext_if proto tcp from any \e .Ed .Pp blocks all packets on the external interface by default, then evaluates -all rulesets in the +all rules in the .Ar anchor named "spam", and finally passes all outgoing connections and incoming connections to port 25. .Bd -literal -offset indent # echo \&"block in quick from 1.2.3.4 to any\&" \&| \e - pfctl -a spam:manual -f - + pfctl -a spam -f - .Ed .Pp -loads a single ruleset containing a single rule into the +This loads a single rule into the .Ar anchor , which blocks all packets from a specific address. .Pp -The named ruleset can also be populated by adding a +The anchor can also be populated by adding a .Ar load anchor rule after the .Ar anchor rule: .Bd -literal -offset indent anchor spam -load anchor spam:manual from "/etc/pf-spam.conf" +load anchor spam from "/etc/pf-spam.conf" .Ed .Pp When @@ -2194,7 +2346,7 @@ loads .Nm pf.conf , it will also load all the rules from the file .Pa /etc/pf-spam.conf -into the named ruleset. +into the anchor. .Pp Optionally, .Ar anchor @@ -2205,7 +2357,7 @@ using the same syntax as filter rules. When parameters are used, the .Ar anchor rule is only evaluated for matching packets. -This allows conditional evaluation of named rulesets, like: +This allows conditional evaluation of anchors, like: .Bd -literal -offset indent block on $ext_if all anchor spam proto tcp from any to any port smtp @@ -2221,10 +2373,56 @@ packets with destination port 25. Hence, .Bd -literal -offset indent # echo \&"block in quick from 1.2.3.4 to any" \&| \e - pfctl -a spam:manual -f - + pfctl -a spam -f - .Ed .Pp will only block connections from 1.2.3.4 to port 25. +.Pp +Anchors may end with the asterisk +.Pq Sq * +character, which signifies that all anchors attached at that point +should be evaluated in the alphabetical ordering of their anchor name. +For example, +.Bd -literal -offset indent +anchor "spam/*" +.Ed +.Pp +will evaluate each rule in each anchor attached to the +.Li spam +anchor. +Note that it will only evaluate anchors that are directly attached to the +.Li spam +anchor, and will not descend to evaluate anchors recursively. +.Pp +Since anchors are evaluated relative to the anchor in which they are +contained, there is a mechanism for accessing the parent and ancestor +anchors of a given anchor. +Similar to file system path name resolution, if the sequence +.Dq .. +appears as an anchor path component, the parent anchor of the current +anchor in the path evaluation at that point will become the new current +anchor. +As an example, consider the following: +.Bd -literal -offset indent +# echo ' anchor "spam/allowed" ' | pfctl -f - +# echo -e ' anchor "../banned" \en pass' | \e + pfctl -a spam/allowed -f - +.Ed +.Pp +Evaluation of the main ruleset will lead into the +.Li spam/allowed +anchor, which will evaluate the rules in the +.Li spam/banned +anchor, if any, before finally evaluating the +.Ar pass +rule. +.Pp +Since the parser specification for anchor names is a string, any +reference to an anchor name containing solidus +.Pq Sq / +characters will require double quote +.Pq Sq \&" +characters around the anchor name. .Sh TRANSLATION EXAMPLES This example maps incoming requests on port 80 to port 8080, on which a daemon is running (because, for example, it is not run as root, @@ -2301,7 +2499,7 @@ nat on $ext_if inet proto udp from any port = isakmp to any -> ($ext_if) \e # Translate outgoing packets' source address (any protocol). # Translate incoming packets' destination address to an internal machine # (bidirectional). -binat on $ext_if from 10.1.2.150 to any -> ($ext_if) +binat on $ext_if from 10.1.2.150 to any -> $ext_if # RDR # Translate incoming packets' destination addresses. @@ -2415,7 +2613,7 @@ pass in on $wifi_if from any to any keep state block out on $ext_if from any to any pass out quick on $ext_if tagged INTNET keep state -pass out on $ext_if from any to any port 80 keep state +pass out on $ext_if proto tcp from any to any port 80 keep state # tag incoming packets as they are redirected to spamd(8). use the tag # to pass those packets through the packet filter. @@ -2442,7 +2640,7 @@ option = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] | [ "limit" ( limit-item | "{" limit-list "}" ) ] | [ "loginterface" ( interface-name | "none" ) ] | [ "block-policy" ( "drop" | "return" ) ] | - [ "state-policy" ( "if-bound" | "group-bound" | + [ "state-policy" ( "if-bound" | "group-bound" | "floating" ) ] [ "require-order" ( "yes" | "no" ) ] [ "fingerprints" filename ] | @@ -2461,21 +2659,22 @@ filteropt = user | group | flags | icmp-type | icmp6-type | tos | "max-mss" number | "random-id" | "reassemble tcp" | fragmentation | "allow-opts" | "label" string | "tag" string | [ ! ] "tagged" string - "queue" ( string | "(" string [ [ "," ] string ] ")" ) + "queue" ( string | "(" string [ [ "," ] string ] ")" ) | + "probability" number"%" nat-rule = [ "no" ] "nat" [ "pass" ] [ "on" ifspec ] [ af ] - [ protospec ] hosts [ "tag" string ] + [ protospec ] hosts [ "tag" string ] [ "tagged" string ] [ "->" ( redirhost | "{" redirhost-list "}" ) [ portspec ] [ pooltype ] [ "static-port" ] ] binat-rule = [ "no" ] "binat" [ "pass" ] [ "on" interface-name ] [ af ] [ "proto" ( proto-name | proto-number ) ] "from" address [ "/" mask-bits ] "to" ipspec - [ "tag" string ] + [ "tag" string ] [ "tagged" string ] [ "->" address [ "/" mask-bits ] ] rdr-rule = [ "no" ] "rdr" [ "pass" ] [ "on" ifspec ] [ af ] - [ protospec ] hosts [ "tag" string ] + [ protospec ] hosts [ "tag" string ] [ "tagged" string ] [ "->" ( redirhost | "{" redirhost-list "}" ) [ portspec ] [ pooltype ] ] @@ -2503,7 +2702,7 @@ anchor-rule = "anchor" string [ ( "in" | "out" ) ] [ "on" ifspec ] trans-anchors = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string [ "on" ifspec ] [ af ] [ "proto" ] [ protospec ] [ hosts ] -load-anchor = "load anchor" anchorname:rulesetname "from" filename +load-anchor = "load anchor" string "from" filename queueopts-list = queueopts-list queueopts | queueopts queueopts = [ "bandwidth" bandwidth-spec ] | @@ -2512,7 +2711,7 @@ queueopts = [ "bandwidth" bandwidth-spec ] | schedulers = ( cbq-def | priq-def | hfsc-def ) bandwidth-spec = "number" ( "b" | "Kb" | "Mb" | "Gb" | "%" ) -action = "pass" | "block" [ return ] | "scrub" +action = "pass" | "block" [ return ] | [ "no" ] "scrub" return = "drop" | "return" | "return-rst" [ "( ttl" number ")" ] | "return-icmp" [ "(" icmpcode ["," icmp6code ] ")" ] | "return-icmp6" [ "(" icmp6code ")" ] @@ -2533,9 +2732,9 @@ proto-list = ( proto-name | proto-number ) [ [ "," ] proto-list ] hosts = "all" | "from" ( "any" | "no-route" | "self" | host | - "{" host-list "}" ) [ port ] [ os ] + "{" host-list "}" | "route" string ) [ port ] [ os ] "to" ( "any" | "no-route" | "self" | host | - "{" host-list "}" ) [ port ] + "{" host-list "}" | "route" string ) [ port ] ipspec = "any" | host | "{" host-list "}" host = [ "!" ] ( address [ "/" mask-bits ] | "<" string ">" ) @@ -2577,7 +2776,10 @@ tos = "tos" ( "lowdelay" | "throughput" | "reliability" | state-opts = state-opt [ [ "," ] state-opts ] state-opt = ( "max" number | "no-sync" | timeout | "source-track" [ ( "rule" | "global" ) ] | - "max-src-nodes" number | "max-src-states" number | + "max-src-nodes" number | "max-src-states" number | + "max-src-conn" number | + "max-src-conn-rate" number "/" number | + "overload" "<" string ">" [ "flush" ] | "if-bound" | "group-bound" | "floating" ) fragmentation = [ "fragment reassemble" | "fragment crop" | @@ -2657,6 +2859,7 @@ deadlock. .Xr ip6 4 , .Xr pf 4 , .Xr pfsync 4 , +.Xr route 4 , .Xr tcp 4 , .Xr udp 4 , .Xr hosts 5 , @@ -2665,7 +2868,8 @@ deadlock. .Xr services 5 , .Xr ftp-proxy 8 , .Xr pfctl 8 , -.Xr pflogd 8 +.Xr pflogd 8 , +.Xr route 8 .Sh HISTORY The .Nm |
