diff options
Diffstat (limited to 'share/man/man5/pf.conf.5')
| -rw-r--r-- | share/man/man5/pf.conf.5 | 1711 |
1 files changed, 854 insertions, 857 deletions
diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5 index 751afd3acd2..0f7365a1418 100644 --- a/share/man/man5/pf.conf.5 +++ b/share/man/man5/pf.conf.5 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pf.conf.5,v 1.451 2009/09/02 14:50:01 henning Exp $ +.\" $OpenBSD: pf.conf.5,v 1.452 2009/09/03 17:53:25 jmc Exp $ .\" .\" Copyright (c) 2002, Daniel Hartmeier .\" All rights reserved. @@ -27,7 +27,7 @@ .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: September 2 2009 $ +.Dd $Mdocdate: September 3 2009 $ .Dt PF.CONF 5 .Os .Sh NAME @@ -42,14 +42,12 @@ definitions specified in .Pp This is an overview of the sections in this manual page: .Bl -ohang +.It Sy Packet Filtering +Packet filtering, including network address translation (NAT). .It Sy Options Global options tune the behaviour of the packet filtering engine. .It Sy Queueing Queueing provides rule-based bandwidth control. -.It Sy Translation -Translation specifies how addresses are mapped to other addresses. -.It Sy Packet Filtering -Packet filtering provides rule-based blocking or passing of packets. .It Sy Tables Tables provide a method for dealing with large numbers of addresses. .It Sy Anchors @@ -61,7 +59,7 @@ Including scrub, fragment handling, and blocking spoofed traffic. .It Sy Operating System Fingerprinting A method for detecting a host's operating system. .It Sy Examples -Translation and filter examples. +Some example rulesets. .El .Pp Comments can be put anywhere in the file using a hash mark @@ -90,774 +88,6 @@ all_ifs = "{" $ext_if lo0 "}" pass out on $ext_if from any to any pass in on $ext_if proto tcp from any to any port 25 .Ed -.Sh OPTIONS -.Xr pf 4 -may be tuned for various situations using the -.Ar set -command. -.Bl -tag -width Ds -.It Ar set block-policy -The -.Ar block-policy -option sets the default behaviour for the packet -.Ar block -action: -.Pp -.Bl -tag -width xxxxxxxx -compact -.It Ar drop -Packet is silently dropped. -.It Ar return -A TCP RST is returned for blocked TCP packets, -an ICMP UNREACHABLE is returned for blocked UDP packets, -and all other packets are silently dropped. -.El -.It Ar set debug -Set the debug -.Ar level -to one of the following: -.Pp -.Bl -tag -width xxxxxxxx -compact -.It Ar loud -Generate debug messages for common conditions. -.It Ar misc -Generate debug messages for various errors. -.It Ar none -Don't generate debug messages. -.It Ar urgent -Generate debug messages only for serious errors. -.El -.It Ar set fingerprints -Load fingerprints of known operating systems from the given filename. -By default fingerprints of known operating systems are automatically -loaded from -.Xr pf.os 5 , -but can be overridden via this option. -Setting this option may leave a small period of time where the fingerprints -referenced by the currently active ruleset are inconsistent until the new -ruleset finishes loading. -.It Ar set hostid -The 32-bit -.Ar hostid -identifies this firewall's state table entries to other firewalls -in a -.Xr pfsync 4 -failover cluster. -By default the hostid is set to a pseudo-random value, however it may be -desirable to manually configure it, for example to more easily identify the -source of state table entries. -The hostid may be specified in either decimal or hexadecimal. -.It Ar set limit -Sets hard limits on the memory pools used by the packet filter. -See -.Xr pool 9 -for an explanation of memory pools. -.Pp -For example, -to set the maximum number of entries in the memory pool used by state table -entries (generated by -.Ar pass -rules which do not specify -.Ar no state ) -to 20000: -.Pp -.Dl set limit states 20000 -.Pp -To set the maximum number of entries in the memory pool used for fragment -reassembly to 20000: -.Pp -.Dl set limit frags 20000 -.Pp -To set the maximum number of entries in the memory pool used for tracking -source IP addresses (generated by the -.Ar sticky-address -and -.Ar src.track -options) to 2000: -.Pp -.Dl set limit src-nodes 2000 -.Pp -To set limits on the memory pools used by tables: -.Bd -literal -offset indent -set limit tables 1000 -set limit table-entries 100000 -.Ed -.Pp -The first limits the number of tables that can exist to 1000. -The second limits the overall number of addresses that can be stored -in tables to 100000. -.Pp -Various limits can be combined on a single line: -.Bd -literal -offset indent -set limit { states 20000, frags 20000, src-nodes 2000 } -.Ed -.It Ar set loginterface -Enable collection of packet and byte count statistics for the given -interface or interface group. -These statistics can be viewed using: -.Pp -.Dl # pfctl -s info -.Pp -In this example -.Xr pf 4 -collects statistics on the interface named dc0: -.Pp -.Dl set loginterface dc0 -.Pp -One can disable the loginterface using: -.Pp -.Dl set loginterface none -.It Ar set optimization -Optimize state timeouts for one of the following network environments: -.Pp -.Bl -tag -width Ds -compact -.It Ar aggressive -Aggressively expire connections. -This can greatly reduce the memory usage of the firewall at the cost of -dropping idle connections early. -.It Ar conservative -Extremely conservative settings. -Avoid dropping legitimate connections at the -expense of greater memory utilization (possibly much greater on a busy -network) and slightly increased processor utilization. -.It Ar high-latency -A high-latency environment (such as a satellite connection). -.It Ar normal -A normal network environment. -Suitable for almost all networks. -.It Ar satellite -Alias for -.Ar high-latency . -.El -.It Ar set reassemble -The -.Ar reassemble -option turns reassembly of fragmented packets on or off. -If -.Ar no-df -is given, fragments with the -.Ar dont-fragment -bit set have it cleared before entering the fragment cache, -and thus the reassembled packet doesn't have -.Ar dont-fragment -set either. -Setting this option does not affect non-fragmented packets. -Fragment reassembly is turned on by default. -.It Ar set require-order -If set to -.Ar yes , -.Xr pfctl 8 -will enforce that statement types in the ruleset are listed in the -following order, to match the operation of the underlying packet -filtering engine: -.Em options , -.Em queueing , -.Em translation , -.Em filtering . -This option is disabled by default. -.It Ar set ruleset-optimization -.Bl -tag -width xxxxxxxx -compact -.It Ar basic -Enable basic ruleset optimization. -This is the default behaviour. -Basic ruleset optimization does four things to improve the -performance of ruleset evaluations: -.Pp -.Bl -enum -compact -.It -remove duplicate rules -.It -remove rules that are a subset of another rule -.It -combine multiple rules into a table when advantageous -.It -re-order the rules to improve evaluation performance -.El -.It Ar none -Disable the ruleset optimizer. -.It Ar profile -Uses the currently loaded ruleset as a feedback profile to tailor the -ordering of quick rules to actual network traffic. -.El -.Pp -It is important to note that the ruleset optimizer will modify the ruleset -to improve performance. -A side effect of the ruleset modification is that per-rule accounting -statistics will have different meanings than before. -If per-rule accounting is important for billing purposes or whatnot, -either the ruleset optimizer should not be used or a label field should -be added to all of the accounting rules to act as optimization barriers. -.Pp -Optimization can also be set as a command-line argument to -.Xr pfctl 8 , -overriding the settings in -.Nm . -.It Ar set skip on Aq Ar 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. -.It Ar set state-defaults -The -.Ar state-defaults -option sets the state options for states created from rules -without an explicit -.Ar keep state . -For example: -.Pp -.Dl set state-defaults pflow, no-sync -.It Ar set state-policy -The -.Ar state-policy -option sets the default behaviour for states: -.Pp -.Bl -tag -width if-bound -compact -.It Ar if-bound -States are bound to interface. -.It Ar floating -States can match packets on any interfaces (the default). -.El -.It Ar set timeout -.Pp -.Bl -tag -width "src.track" -compact -.It Ar frag -Seconds before an unassembled fragment is expired. -.It Ar interval -Interval between purging expired states and fragments. -.It Ar src.track -Length of time to retain a source tracking entry after the last state -expires. -.El -.Pp -When a packet matches a stateful connection, the seconds to live for the -connection will be updated to that of the -protocol and modifier -which corresponds to the connection state. -Each packet which matches this state will reset the TTL. -Tuning these values may improve the performance of the -firewall at the risk of dropping valid idle connections. -.Pp -.Bl -tag -width Ds -compact -.It Ar tcp.closed -The state after one endpoint sends an RST. -.It Ar tcp.closing -The state after the first FIN has been sent. -.It Ar tcp.established -The fully established state. -.It Ar tcp.finwait -The state after both FINs have been exchanged and the connection is closed. -Some hosts (notably web servers on Solaris) send TCP packets even after closing -the connection. -Increasing -.Ar tcp.finwait -(and possibly -.Ar tcp.closing ) -can prevent blocking of such packets. -.It Ar tcp.first -The state after the first packet. -.It Ar tcp.opening -The state before the destination host ever sends a packet. -.El -.Pp -ICMP and UDP are handled in a fashion similar to TCP, but with a much more -limited set of states: -.Pp -.Bl -tag -width Ds -compact -.It Ar icmp.error -The state after an ICMP error came back in response to an ICMP packet. -.It Ar icmp.first -The state after the first packet. -.It Ar udp.first -The state after the first packet. -.It Ar udp.multiple -The state if both hosts have sent packets. -.It Ar udp.single -The state if the source host sends more than one packet but the destination -host has never sent one back. -.El -.Pp -Other protocols are handled similarly to UDP: -.Pp -.Bl -tag -width xxxx -compact -.It Ar other.first -.It Ar other.multiple -.It Ar other.single -.El -.Pp -Timeout values can be reduced adaptively as the number of state table -entries grows. -.Pp -.Bl -tag -width Ds -compact -.It Ar adaptive.end -When reaching this number of state entries, all timeout values become -zero, effectively purging all state entries immediately. -This value is used to define the scale factor; it should not actually -be reached (set a lower state limit, see below). -.It Ar adaptive.start -When the number of state entries exceeds this value, adaptive scaling -begins. -All timeout values are scaled linearly with factor -(adaptive.end \- number of states) / (adaptive.end \- adaptive.start). -.El -.Pp -Adaptive timeouts are enabled by default, with an adaptive.start value -equal to 60% of the state limit, and an adaptive.end value equal to -120% of the state limit. -They can be disabled by setting both adaptive.start and adaptive.end to 0. -.Pp -The adaptive timeout values can be defined both globally and for each rule. -When used on a per-rule basis, the values relate to the number of -states created by the rule, otherwise to the total number of -states. -.Pp -For example: -.Bd -literal -offset indent -set timeout tcp.first 120 -set timeout tcp.established 86400 -set timeout { adaptive.start 6000, adaptive.end 12000 } -set limit states 10000 -.Ed -.Pp -With 9000 state table entries, the timeout values are scaled to 50% -(tcp.first 60, tcp.established 43200). -.El -.Sh QUEUEING -Packets can be assigned to queues for the purpose of bandwidth -control. -At least two declarations are required to configure queues, and later -any packet filtering rule can reference the defined queues by name. -During the filtering component of -.Nm , -the last referenced -.Ar queue -name is where any packets from -.Ar pass -rules will be queued, while for -.Ar block -rules it specifies where any resulting ICMP or TCP RST -packets should be queued. -The -.Em scheduler -defines the algorithm used to decide which packets get delayed, dropped, or -sent out immediately. -There are three schedulers currently supported: -.Bl -tag -width xxxx -.It Ar cbq -Class Based Queueing. -Queues attached to an interface build a tree, -thus each queue can have further child queues. -Each queue can have a -.Ar priority -and a -.Ar bandwidth -assigned. -Priority mainly controls the time packets take to get sent out, -while 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 queue -and is assigned its share of 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 hfsc -Hierarchical Fair Service Curve. -Queues attached to an interface build a tree, -thus each queue can have further child queues. -Each queue can have a -.Ar priority -and a -.Ar bandwidth -assigned. -Priority mainly controls the time packets take to get sent out, -while bandwidth primarily affects 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 -delay and bandwidth allocation. -.It Ar priq -Priority Queueing. -Queues are flat attached to the interface, -thus queues cannot have further child queues. -Each queue has a unique -.Ar priority -assigned, ranging from 0 to 15. -Packets in the queue with the highest priority are processed first. -.El -.Pp -The interfaces on which queueing should be activated are declared using -the -.Ar altq on -declaration. -.Ar altq on -has the following keywords: -.Bl -tag -width xxxx -.It Aq Ar interface -Queueing is enabled on the named interface. -.It Aq Ar scheduler -Specifies which queueing scheduler to use. -.It Ar bandwidth Aq Ar bw -The maximum bitrate for all queues on an -interface may be specified using the -.Ar bandwidth -keyword. -The value can be specified as an absolute value or as a -percentage of the interface bandwidth. -When using an absolute value, the suffixes -.Ar b , -.Ar Kb , -.Ar Mb , -and -.Ar Gb -are used to represent bits, kilobits, megabits, and -gigabits per second, respectively. -The value must not exceed the interface bandwidth. -If -.Ar bandwidth -is not specified, the interface bandwidth is used -(but take note that some interfaces do not know their bandwidth, -or can adapt their bandwidth rates). -.It Ar qlimit Aq Ar limit -The maximum number of packets held in the queue. -The default is 50. -.It Ar tbrsize Aq Ar size -Adjusts the size, in bytes, of the token bucket regulator. -If not specified, heuristics based on the -interface bandwidth are used to determine the size. -.It Ar queue Aq Ar list -Defines a list of subqueues to create on an interface. -.El -.Pp -In the following example, the interface dc0 -should queue up to 5Mbps in four second-level queues using -Class Based Queueing. -Those four queues will be shown in a later example. -.Bd -literal -offset indent -altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh } -.Ed -.Pp -Once interfaces are activated for queueing using the -.Ar altq -directive, a sequence of -.Ar queue -directives may be defined. -The name associated with a queue -must match a queue defined in the altq -directive or, except for the -.Ar priq -scheduler, in a parent queue declaration. -The following keywords can be used: -.Bl -tag -width xxxx -.It Ar on Aq Ar interface -Specifies the interface the queue operates on. -If not given, it operates on all matching interfaces. -.It Ar bandwidth Aq Ar bw -Specifies the maximum bitrate to be processed by the queue. -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. -.It Ar priority Aq Ar level -Between queues a priority level can be set. -For -.Ar cbq -and -.Ar hfsc , -the range is 0 to 7 and for -.Ar priq , -the range is 0 to 15. -The default for all is 1. -.Ar priq -queues with a higher priority are always served first. -.Ar cbq -and -.Ar hfsc -queues with a higher priority are preferred in the case of overload. -.It Ar qlimit Aq Ar limit -The maximum number of packets held in the queue. -The default is 50. -.El -.Pp -The scheduler can specify additional parameters using the format -.Ar scheduler Ns Pq Ar parameters . -The parameters are: -.Bl -tag -width Fl -.It Ar default -Packets not matched by another queue are assigned to this one. -Exactly one default queue is required. -.It Ar ecn -Enables Explicit Congestion Notification (ECN) on this queue. -ECN implies RED. -.It Ar red -Enables Random Early Detection (RED) on this queue. -RED drops packets with a probability proportional to the average -queue length. -.\" .It Ar rio -.\" Enables RIO on this queue. -.\" RIO is RED with IN/OUT, thus running -.\" RED two times more than RIO would achieve the same effect. -.El -.Pp -The -.Ar cbq -scheduler supports an additional option: -.Pp -.Bl -tag -width "upperlimit XXXXXXX" -compact -offset 3n -.It Ar borrow -The queue can borrow bandwidth from the parent. -.El -.Pp -The -.Ar hfsc -scheduler supports some additional options: -.Pp -.Bl -tag -width "upperlimit XXXXXXX" -compact -offset 3n -.It Ar linkshare Aq Ar sc -The bandwidth share of a backlogged queue. -.It Ar realtime Aq Ar sc -The minimum required bandwidth for the queue. -.It Ar upperlimit Aq Ar sc -The maximum allowed bandwidth for the queue. -.El -.Pp -.Aq Ar sc -is an abbreviation for -.Ar service curve . -.Pp -The format for service curve specifications is -.Ar ( m1 , d , m2 ) . -.Ar m2 -controls the bandwidth assigned to the queue. -.Ar m1 -and -.Ar d -are optional and can be used to control the initial bandwidth assignment. -For the first -.Ar d -milliseconds the queue gets the bandwidth given as -.Ar m1 , -afterwards the value given in -.Ar m2 . -.Pp -Furthermore, with -.Ar cbq -and -.Ar hfsc , -child queues can be specified as in an -.Ar altq -declaration, thus building a tree of queues using a part of -their parent's bandwidth. -.Pp -Packets can be assigned to queues based on filter rules by using the -.Ar queue -keyword. -Normally only one -.Ar queue -is specified; when a second one is specified it will instead be used for -packets which have a TOS of -.Ar lowdelay -and for TCP ACKs with no data payload. -.Pp -To continue the previous example, the examples below would specify the -four referenced -queues, plus a few child queues. -Interactive -.Xr ssh 1 -sessions get priority over bulk transfers like -.Xr scp 1 -and -.Xr sftp 1 . -The queues may then be referenced by filtering rules (see -.Sx PACKET FILTERING -below). -.Bd -literal -offset 4n -queue std bandwidth 10% cbq(default) -queue http bandwidth 60% priority 2 cbq(borrow red) \e - { employees, developers } -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 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 - queue developers -pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e - queue employees -pass out on dc0 inet proto tcp from any to any port 22 \e - queue(ssh_bulk, ssh_interactive) -pass out on dc0 inet proto tcp from any to any port 25 \e - queue mail -.Ed -.Sh TRANSLATION -Translation options modify either the source or destination address of the -packets associated with a stateful connection. -A stateful connection is automatically created to track packets matching -such a rule as long as they are not blocked by the filtering section of -.Nm . -The translation engine modifies the specified address and/or port in the -packet, recalculates IP, TCP, and UDP checksums as necessary, and passes it to -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 -address and port number. -Packets that match a translation rule are only automatically passed if the -.Ar pass -modifier is given, -otherwise they are still subject to -.Ar block -and -.Ar pass -rules. -.Pp -The state entry created permits -.Xr pf 4 -to keep track of the original address for traffic associated with that state -and correctly direct return traffic for that connection. -.Pp -Two types of translation are possible with pf: -.Bl -tag -width xxxxxxxx -.It Ar nat-to -A -.Ar nat-to -option specifies that IP addresses are to be changed as the packet -traverses the given interface. -This technique allows one or more IP addresses -on the translating host to support network traffic for a larger range of -machines on an "inside" network. -Although in theory any IP address can be used on the inside, it is strongly -recommended that one of the address ranges defined by RFC 1918 be used. -Those netblocks are: -.Bd -literal -offset indent -10.0.0.0 \(en 10.255.255.255 (all of net 10, i.e. 10/8) -172.16.0.0 \(en 172.31.255.255 (i.e. 172.16/12) -192.168.0.0 \(en 192.168.255.255 (i.e. 192.168/16) -.Ed -.It Pa rdr-to -The packet is redirected to another destination and possibly a -different port. -.Ar rdr-to -can optionally specify port ranges instead of single ports. -For instance: -.Bl -tag -width Ds -.It match in ... port 2000:2999 rdr-to ... port 4000 -redirects ports 2000 to 2999 (inclusive) to port 4000. -.Pp -.It match in ... port 2000:2999 rdr-to ... port 4000:* -redirects port 2000 to 4000, port 2001 to 4001, ..., port 2999 to 4999. -.El -.El -.Pp -In addition to modifying the address, some translation rules may modify -source or destination ports for TCP or UDP connections; -implicitly in the case of -.Ar nat-to -options and explicitly in the case of -.Ar rdr-to -ones. -.Pp -Translation options apply only to packets that pass through the specified -interface, and if no interface is specified, translation is applied -to packets on all interfaces. -For instance, redirecting port 80 on an external interface to an internal -web server will only work for connections originating from the outside. -Connections to the address of the external interface from local hosts will -not be redirected, since such packets do not actually pass through the -external interface. -Redirections cannot reflect packets back through the interface they arrive -on, they can only be redirected to hosts connected to different interfaces -or to the firewall itself. -.Pp -Note that redirecting external incoming connections to the loopback address -will effectively allow an external host to connect to daemons -bound solely to the loopback address, circumventing the traditional -blocking of such connections on a real interface. -For example: -.Bd -literal -offset indent -match in on ne3 inet proto tcp to port smtp rdr-to 127.0.0.1 \e - port spamd -.Ed -.Pp -Unless this effect is desired, any of the local non-loopback addresses -should be used instead as the redirection target, which allows external -connections only to daemons bound to this address or not bound to -any address. -.Pp -For -.Ar nat-to -and -.Ar rdr-to -options for which there is a single redirection address which has a -subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP -address), a variety of different methods for assigning this address can be -used: -.Bl -tag -width xxxx -.It Ar bitmask -The -.Ar bitmask -option applies the network portion of the redirection address to the address -to be modified (source with -.Ar nat-to , -destination with -.Ar rdr-to ) . -.It Ar random Op Ar sticky-address -The -.Ar random -option selects an address at random within the defined block of addresses. -.Pp -.Ar sticky-address -can be specified to ensure that multiple connections from the -same source are mapped to the same redirection address. -Associations are destroyed as soon as there are -no longer states which refer to them; -in order to make the mappings last -beyond the lifetime of the states, -increase the global options with -.Ar set timeout src.track . -.It Ar round-robin Op Ar sticky-address -The -.Ar round-robin -option loops through the redirection address(es). -.Ar sticky-address -is as described above. -.Pp -When more than one redirection address is specified, -.Ar round-robin -is the only permitted pool type. -.It Ar source-hash Op Ar key -The -.Ar source-hash -option uses a hash of the source address to determine the redirection address, -ensuring that the redirection address is always the same for a given source. -An optional -.Ar key -can be specified after this keyword either in hex or as a string; -by default -.Xr pfctl 8 -randomly generates a key for source-hash every time the -ruleset is reloaded. -.It Ar static-port -With -.Ar nat -rules, the -.Ar static-port -option prevents -.Xr pf 4 -from modifying the source port on TCP and UDP packets. -.El .Sh PACKET FILTERING .Xr pf 4 has the ability to @@ -1493,6 +723,165 @@ block out proto { tcp, udp } all pass out proto { tcp, udp } all user { \*(Lt 1000, dhartmei } .Ed .El +.Ss Translation +Translation options modify either the source or destination address of the +packets associated with a stateful connection. +A stateful connection is automatically created to track packets matching +such a rule as long as they are not blocked by the filtering section of +.Nm . +The translation engine modifies the specified address and/or port in the +packet, recalculates IP, TCP, and UDP checksums as necessary, and passes it to +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 +address and port number. +Packets that match a translation rule are only automatically passed if the +.Ar pass +modifier is given, +otherwise they are still subject to +.Ar block +and +.Ar pass +rules. +.Pp +The state entry created permits +.Xr pf 4 +to keep track of the original address for traffic associated with that state +and correctly direct return traffic for that connection. +.Pp +Different types of translation are possible with pf: +.Bl -tag -width xxxxxxxx +.It Ar nat-to +A +.Ar nat-to +option specifies that IP addresses are to be changed as the packet +traverses the given interface. +This technique allows one or more IP addresses +on the translating host to support network traffic for a larger range of +machines on an "inside" network. +Although in theory any IP address can be used on the inside, it is strongly +recommended that one of the address ranges defined by RFC 1918 be used. +Those netblocks are: +.Bd -literal -offset indent +10.0.0.0 \(en 10.255.255.255 (all of net 10, i.e. 10/8) +172.16.0.0 \(en 172.31.255.255 (i.e. 172.16/12) +192.168.0.0 \(en 192.168.255.255 (i.e. 192.168/16) +.Ed +.It Pa rdr-to +The packet is redirected to another destination and possibly a +different port. +.Ar rdr-to +can optionally specify port ranges instead of single ports. +For instance: +.Bl -tag -width Ds +.It match in ... port 2000:2999 rdr-to ... port 4000 +redirects ports 2000 to 2999 (inclusive) to port 4000. +.Pp +.It match in ... port 2000:2999 rdr-to ... port 4000:* +redirects port 2000 to 4000, port 2001 to 4001, ..., port 2999 to 4999. +.El +.El +.Pp +In addition to modifying the address, some translation rules may modify +source or destination ports for TCP or UDP connections; +implicitly in the case of +.Ar nat-to +options and explicitly in the case of +.Ar rdr-to +ones. +.Pp +Translation options apply only to packets that pass through the specified +interface, and if no interface is specified, translation is applied +to packets on all interfaces. +For instance, redirecting port 80 on an external interface to an internal +web server will only work for connections originating from the outside. +Connections to the address of the external interface from local hosts will +not be redirected, since such packets do not actually pass through the +external interface. +Redirections cannot reflect packets back through the interface they arrive +on, they can only be redirected to hosts connected to different interfaces +or to the firewall itself. +.Pp +Note that redirecting external incoming connections to the loopback address +will effectively allow an external host to connect to daemons +bound solely to the loopback address, circumventing the traditional +blocking of such connections on a real interface. +For example: +.Bd -literal -offset indent +pass on egress proto tcp from any to any port smtp \e + rdr-to 127.0.0.1 port spamd +.Ed +.Pp +Unless this effect is desired, any of the local non-loopback addresses +should be used instead as the redirection target, which allows external +connections only to daemons bound to this address or not bound to +any address. +.Pp +For +.Ar nat-to +and +.Ar rdr-to +options for which there is a single redirection address which has a +subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP +address), a variety of different methods for assigning this address can be +used: +.Bl -tag -width xxxx +.It Ar bitmask +The +.Ar bitmask +option applies the network portion of the redirection address to the address +to be modified (source with +.Ar nat-to , +destination with +.Ar rdr-to ) . +.It Ar random Op Ar sticky-address +The +.Ar random +option selects an address at random within the defined block of addresses. +.Pp +.Ar sticky-address +can be specified to ensure that multiple connections from the +same source are mapped to the same redirection address. +Associations are destroyed as soon as there are +no longer states which refer to them; +in order to make the mappings last +beyond the lifetime of the states, +increase the global options with +.Ar set timeout src.track . +.It Ar round-robin Op Ar sticky-address +The +.Ar round-robin +option loops through the redirection address(es). +.Ar sticky-address +is as described above. +.Pp +When more than one redirection address is specified, +.Ar round-robin +is the only permitted pool type. +.It Ar source-hash Op Ar key +The +.Ar source-hash +option uses a hash of the source address to determine the redirection address, +ensuring that the redirection address is always the same for a given source. +An optional +.Ar key +can be specified after this keyword either in hex or as a string; +by default +.Xr pfctl 8 +randomly generates a key for source-hash every time the +ruleset is reloaded. +.It Ar static-port +With +.Ar nat +rules, the +.Ar static-port +option prevents +.Xr pf 4 +from modifying the source port on TCP and UDP packets. +.El .Ss Routing If a packet matches a rule with one of the following route options set, the packet filter will route the packet according to the type of route option. @@ -1549,9 +938,617 @@ the methods .Ar round-robin , and .Ar source-hash , -as described above in -.Sx TRANSLATION , +as described above, can be used. +.Sh OPTIONS +.Xr pf 4 +may be tuned for various situations using the +.Ar set +command. +.Bl -tag -width Ds +.It Ar set block-policy +The +.Ar block-policy +option sets the default behaviour for the packet +.Ar block +action: +.Pp +.Bl -tag -width xxxxxxxx -compact +.It Ar drop +Packet is silently dropped. +.It Ar return +A TCP RST is returned for blocked TCP packets, +an ICMP UNREACHABLE is returned for blocked UDP packets, +and all other packets are silently dropped. +.El +.It Ar set debug +Set the debug +.Ar level +to one of the following: +.Pp +.Bl -tag -width xxxxxxxx -compact +.It Ar loud +Generate debug messages for common conditions. +.It Ar misc +Generate debug messages for various errors. +.It Ar none +Don't generate debug messages. +.It Ar urgent +Generate debug messages only for serious errors. +.El +.It Ar set fingerprints +Load fingerprints of known operating systems from the given filename. +By default fingerprints of known operating systems are automatically +loaded from +.Xr pf.os 5 , +but can be overridden via this option. +Setting this option may leave a small period of time where the fingerprints +referenced by the currently active ruleset are inconsistent until the new +ruleset finishes loading. +.It Ar set hostid +The 32-bit +.Ar hostid +identifies this firewall's state table entries to other firewalls +in a +.Xr pfsync 4 +failover cluster. +By default the hostid is set to a pseudo-random value, however it may be +desirable to manually configure it, for example to more easily identify the +source of state table entries. +The hostid may be specified in either decimal or hexadecimal. +.It Ar set limit +Sets hard limits on the memory pools used by the packet filter. +See +.Xr pool 9 +for an explanation of memory pools. +.Pp +For example, +to set the maximum number of entries in the memory pool used by state table +entries (generated by +.Ar pass +rules which do not specify +.Ar no state ) +to 20000: +.Pp +.Dl set limit states 20000 +.Pp +To set the maximum number of entries in the memory pool used for fragment +reassembly to 20000: +.Pp +.Dl set limit frags 20000 +.Pp +To set the maximum number of entries in the memory pool used for tracking +source IP addresses (generated by the +.Ar sticky-address +and +.Ar src.track +options) to 2000: +.Pp +.Dl set limit src-nodes 2000 +.Pp +To set limits on the memory pools used by tables: +.Bd -literal -offset indent +set limit tables 1000 +set limit table-entries 100000 +.Ed +.Pp +The first limits the number of tables that can exist to 1000. +The second limits the overall number of addresses that can be stored +in tables to 100000. +.Pp +Various limits can be combined on a single line: +.Bd -literal -offset indent +set limit { states 20000, frags 20000, src-nodes 2000 } +.Ed +.It Ar set loginterface +Enable collection of packet and byte count statistics for the given +interface or interface group. +These statistics can be viewed using: +.Pp +.Dl # pfctl -s info +.Pp +In this example +.Xr pf 4 +collects statistics on the interface named dc0: +.Pp +.Dl set loginterface dc0 +.Pp +One can disable the loginterface using: +.Pp +.Dl set loginterface none +.It Ar set optimization +Optimize state timeouts for one of the following network environments: +.Pp +.Bl -tag -width Ds -compact +.It Ar aggressive +Aggressively expire connections. +This can greatly reduce the memory usage of the firewall at the cost of +dropping idle connections early. +.It Ar conservative +Extremely conservative settings. +Avoid dropping legitimate connections at the +expense of greater memory utilization (possibly much greater on a busy +network) and slightly increased processor utilization. +.It Ar high-latency +A high-latency environment (such as a satellite connection). +.It Ar normal +A normal network environment. +Suitable for almost all networks. +.It Ar satellite +Alias for +.Ar high-latency . +.El +.It Ar set reassemble +The +.Ar reassemble +option turns reassembly of fragmented packets on or off. +If +.Ar no-df +is given, fragments with the +.Ar dont-fragment +bit set have it cleared before entering the fragment cache, +and thus the reassembled packet doesn't have +.Ar dont-fragment +set either. +Setting this option does not affect non-fragmented packets. +Fragment reassembly is turned on by default. +.It Ar set require-order +If set to +.Ar yes , +.Xr pfctl 8 +will enforce that statement types in the ruleset are listed in the +following order, to match the operation of the underlying packet +filtering engine: +.Em options , +.Em queueing , +.Em translation , +.Em filtering . +This option is disabled by default. +.It Ar set ruleset-optimization +.Bl -tag -width xxxxxxxx -compact +.It Ar basic +Enable basic ruleset optimization. +This is the default behaviour. +Basic ruleset optimization does four things to improve the +performance of ruleset evaluations: +.Pp +.Bl -enum -compact +.It +remove duplicate rules +.It +remove rules that are a subset of another rule +.It +combine multiple rules into a table when advantageous +.It +re-order the rules to improve evaluation performance +.El +.It Ar none +Disable the ruleset optimizer. +.It Ar profile +Uses the currently loaded ruleset as a feedback profile to tailor the +ordering of quick rules to actual network traffic. +.El +.Pp +It is important to note that the ruleset optimizer will modify the ruleset +to improve performance. +A side effect of the ruleset modification is that per-rule accounting +statistics will have different meanings than before. +If per-rule accounting is important for billing purposes or whatnot, +either the ruleset optimizer should not be used or a label field should +be added to all of the accounting rules to act as optimization barriers. +.Pp +Optimization can also be set as a command-line argument to +.Xr pfctl 8 , +overriding the settings in +.Nm . +.It Ar set skip on Aq Ar 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. +.It Ar set state-defaults +The +.Ar state-defaults +option sets the state options for states created from rules +without an explicit +.Ar keep state . +For example: +.Pp +.Dl set state-defaults pflow, no-sync +.It Ar set state-policy +The +.Ar state-policy +option sets the default behaviour for states: +.Pp +.Bl -tag -width if-bound -compact +.It Ar if-bound +States are bound to interface. +.It Ar floating +States can match packets on any interfaces (the default). +.El +.It Ar set timeout +.Pp +.Bl -tag -width "src.track" -compact +.It Ar frag +Seconds before an unassembled fragment is expired. +.It Ar interval +Interval between purging expired states and fragments. +.It Ar src.track +Length of time to retain a source tracking entry after the last state +expires. +.El +.Pp +When a packet matches a stateful connection, the seconds to live for the +connection will be updated to that of the +protocol and modifier +which corresponds to the connection state. +Each packet which matches this state will reset the TTL. +Tuning these values may improve the performance of the +firewall at the risk of dropping valid idle connections. +.Pp +.Bl -tag -width Ds -compact +.It Ar tcp.closed +The state after one endpoint sends an RST. +.It Ar tcp.closing +The state after the first FIN has been sent. +.It Ar tcp.established +The fully established state. +.It Ar tcp.finwait +The state after both FINs have been exchanged and the connection is closed. +Some hosts (notably web servers on Solaris) send TCP packets even after closing +the connection. +Increasing +.Ar tcp.finwait +(and possibly +.Ar tcp.closing ) +can prevent blocking of such packets. +.It Ar tcp.first +The state after the first packet. +.It Ar tcp.opening +The state before the destination host ever sends a packet. +.El +.Pp +ICMP and UDP are handled in a fashion similar to TCP, but with a much more +limited set of states: +.Pp +.Bl -tag -width Ds -compact +.It Ar icmp.error +The state after an ICMP error came back in response to an ICMP packet. +.It Ar icmp.first +The state after the first packet. +.It Ar udp.first +The state after the first packet. +.It Ar udp.multiple +The state if both hosts have sent packets. +.It Ar udp.single +The state if the source host sends more than one packet but the destination +host has never sent one back. +.El +.Pp +Other protocols are handled similarly to UDP: +.Pp +.Bl -tag -width xxxx -compact +.It Ar other.first +.It Ar other.multiple +.It Ar other.single +.El +.Pp +Timeout values can be reduced adaptively as the number of state table +entries grows. +.Pp +.Bl -tag -width Ds -compact +.It Ar adaptive.end +When reaching this number of state entries, all timeout values become +zero, effectively purging all state entries immediately. +This value is used to define the scale factor; it should not actually +be reached (set a lower state limit, see below). +.It Ar adaptive.start +When the number of state entries exceeds this value, adaptive scaling +begins. +All timeout values are scaled linearly with factor +(adaptive.end \- number of states) / (adaptive.end \- adaptive.start). +.El +.Pp +Adaptive timeouts are enabled by default, with an adaptive.start value +equal to 60% of the state limit, and an adaptive.end value equal to +120% of the state limit. +They can be disabled by setting both adaptive.start and adaptive.end to 0. +.Pp +The adaptive timeout values can be defined both globally and for each rule. +When used on a per-rule basis, the values relate to the number of +states created by the rule, otherwise to the total number of +states. +.Pp +For example: +.Bd -literal -offset indent +set timeout tcp.first 120 +set timeout tcp.established 86400 +set timeout { adaptive.start 6000, adaptive.end 12000 } +set limit states 10000 +.Ed +.Pp +With 9000 state table entries, the timeout values are scaled to 50% +(tcp.first 60, tcp.established 43200). +.El +.Sh QUEUEING +Packets can be assigned to queues for the purpose of bandwidth +control. +At least two declarations are required to configure queues, and later +any packet filtering rule can reference the defined queues by name. +During the filtering component of +.Nm , +the last referenced +.Ar queue +name is where any packets from +.Ar pass +rules will be queued, while for +.Ar block +rules it specifies where any resulting ICMP or TCP RST +packets should be queued. +The +.Em scheduler +defines the algorithm used to decide which packets get delayed, dropped, or +sent out immediately. +There are three schedulers currently supported: +.Bl -tag -width xxxx +.It Ar cbq +Class Based Queueing. +Queues attached to an interface build a tree, +thus each queue can have further child queues. +Each queue can have a +.Ar priority +and a +.Ar bandwidth +assigned. +Priority mainly controls the time packets take to get sent out, +while 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 queue +and is assigned its share of 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 hfsc +Hierarchical Fair Service Curve. +Queues attached to an interface build a tree, +thus each queue can have further child queues. +Each queue can have a +.Ar priority +and a +.Ar bandwidth +assigned. +Priority mainly controls the time packets take to get sent out, +while bandwidth primarily affects 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 +delay and bandwidth allocation. +.It Ar priq +Priority Queueing. +Queues are flat attached to the interface, +thus queues cannot have further child queues. +Each queue has a unique +.Ar priority +assigned, ranging from 0 to 15. +Packets in the queue with the highest priority are processed first. +.El +.Pp +The interfaces on which queueing should be activated are declared using +the +.Ar altq on +declaration. +.Ar altq on +has the following keywords: +.Bl -tag -width xxxx +.It Aq Ar interface +Queueing is enabled on the named interface. +.It Aq Ar scheduler +Specifies which queueing scheduler to use. +.It Ar bandwidth Aq Ar bw +The maximum bitrate for all queues on an +interface may be specified using the +.Ar bandwidth +keyword. +The value can be specified as an absolute value or as a +percentage of the interface bandwidth. +When using an absolute value, the suffixes +.Ar b , +.Ar Kb , +.Ar Mb , +and +.Ar Gb +are used to represent bits, kilobits, megabits, and +gigabits per second, respectively. +The value must not exceed the interface bandwidth. +If +.Ar bandwidth +is not specified, the interface bandwidth is used +(but take note that some interfaces do not know their bandwidth, +or can adapt their bandwidth rates). +.It Ar qlimit Aq Ar limit +The maximum number of packets held in the queue. +The default is 50. +.It Ar tbrsize Aq Ar size +Adjusts the size, in bytes, of the token bucket regulator. +If not specified, heuristics based on the +interface bandwidth are used to determine the size. +.It Ar queue Aq Ar list +Defines a list of subqueues to create on an interface. +.El +.Pp +In the following example, the interface dc0 +should queue up to 5Mbps in four second-level queues using +Class Based Queueing. +Those four queues will be shown in a later example. +.Bd -literal -offset indent +altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh } +.Ed +.Pp +Once interfaces are activated for queueing using the +.Ar altq +directive, a sequence of +.Ar queue +directives may be defined. +The name associated with a queue +must match a queue defined in the altq +directive or, except for the +.Ar priq +scheduler, in a parent queue declaration. +The following keywords can be used: +.Bl -tag -width xxxx +.It Ar on Aq Ar interface +Specifies the interface the queue operates on. +If not given, it operates on all matching interfaces. +.It Ar bandwidth Aq Ar bw +Specifies the maximum bitrate to be processed by the queue. +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. +.It Ar priority Aq Ar level +Between queues a priority level can be set. +For +.Ar cbq +and +.Ar hfsc , +the range is 0 to 7 and for +.Ar priq , +the range is 0 to 15. +The default for all is 1. +.Ar priq +queues with a higher priority are always served first. +.Ar cbq +and +.Ar hfsc +queues with a higher priority are preferred in the case of overload. +.It Ar qlimit Aq Ar limit +The maximum number of packets held in the queue. +The default is 50. +.El +.Pp +The scheduler can specify additional parameters using the format +.Ar scheduler Ns Pq Ar parameters . +The parameters are: +.Bl -tag -width Fl +.It Ar default +Packets not matched by another queue are assigned to this one. +Exactly one default queue is required. +.It Ar ecn +Enables Explicit Congestion Notification (ECN) on this queue. +ECN implies RED. +.It Ar red +Enables Random Early Detection (RED) on this queue. +RED drops packets with a probability proportional to the average +queue length. +.\" .It Ar rio +.\" Enables RIO on this queue. +.\" RIO is RED with IN/OUT, thus running +.\" RED two times more than RIO would achieve the same effect. +.El +.Pp +The +.Ar cbq +scheduler supports an additional option: +.Pp +.Bl -tag -width "upperlimit XXXXXXX" -compact -offset 3n +.It Ar borrow +The queue can borrow bandwidth from the parent. +.El +.Pp +The +.Ar hfsc +scheduler supports some additional options: +.Pp +.Bl -tag -width "upperlimit XXXXXXX" -compact -offset 3n +.It Ar linkshare Aq Ar sc +The bandwidth share of a backlogged queue. +.It Ar realtime Aq Ar sc +The minimum required bandwidth for the queue. +.It Ar upperlimit Aq Ar sc +The maximum allowed bandwidth for the queue. +.El +.Pp +.Aq Ar sc +is an abbreviation for +.Ar service curve . +.Pp +The format for service curve specifications is +.Ar ( m1 , d , m2 ) . +.Ar m2 +controls the bandwidth assigned to the queue. +.Ar m1 +and +.Ar d +are optional and can be used to control the initial bandwidth assignment. +For the first +.Ar d +milliseconds the queue gets the bandwidth given as +.Ar m1 , +afterwards the value given in +.Ar m2 . +.Pp +Furthermore, with +.Ar cbq +and +.Ar hfsc , +child queues can be specified as in an +.Ar altq +declaration, thus building a tree of queues using a part of +their parent's bandwidth. +.Pp +Packets can be assigned to queues based on filter rules by using the +.Ar queue +keyword. +Normally only one +.Ar queue +is specified; when a second one is specified it will instead be used for +packets which have a TOS of +.Ar lowdelay +and for TCP ACKs with no data payload. +.Pp +To continue the previous example, the examples below would specify the +four referenced +queues, plus a few child queues. +Interactive +.Xr ssh 1 +sessions get priority over bulk transfers like +.Xr scp 1 +and +.Xr sftp 1 . +The queues may then be referenced by filtering rules (see +.Sx PACKET FILTERING , +above). +.Bd -literal -offset 4n +queue std bandwidth 10% cbq(default) +queue http bandwidth 60% priority 2 cbq(borrow red) \e + { employees, developers } +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 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 + queue developers +pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e + queue employees +pass out on dc0 inet proto tcp from any to any port 22 \e + queue(ssh_bulk, ssh_interactive) +pass out on dc0 inet proto tcp from any to any port 25 \e + queue mail +.Ed .Sh TABLES Tables are named structures which can hold a collection of addresses and networks. @@ -2386,84 +2383,7 @@ appear as any operating system he chooses; an operating system patch could change the stack behavior and no fingerprints will match it until the database is updated; and multiple operating systems may have the same fingerprint. -.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, -and therefore lacks permission to bind to port 80). -.Bd -literal -offset 4n -match in on $ext_if proto tcp from any to any port 80 \e - rdr-to 127.0.0.1 port 8080 -.Ed -.Pp -If the -.Ar pass -modifier is given, packets matching the translation rule are passed without -inspecting the filter rules. -.Bd -literal -offset 4n -match in on $ext_if proto tcp from any to any port 80 \e - rdr-to 127.0.0.1 port 8080 -.Ed -.Pp -In the example below, vlan12 is configured as 192.168.168.1; -the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111 -when they are going out any interface except vlan12. -This has the net effect of making traffic from the 192.168.168.0/24 -network appear as though it is the Internet routable address -204.92.77.111 to nodes behind any interface on the router except -for the nodes on vlan12. -Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes. -.Bd -literal -offset 4n -match out on ! vlan12 from 192.168.168.0/24 to any nat-to 204.92.77.111 -.Ed -.Pp -In the example below, the machine sits between a fake internal -144.19.74.* network, and a routable external IP of 204.92.77.100. -The last rule excludes protocol AH from being translated. -.Bd -literal -offset 4n -pass out on $ext_if from 144.19.74.0/24 nat-to 204.92.77.100 -pass out on $ext_if proto ah from 144.19.74.0/24 -.Ed -.Pp -In the example below, packets bound for one specific server, as well as those -generated by the sysadmins are not proxied; all other connections are. -.Bd -literal -offset 4n -match in on $int_if proto { tcp, udp } from any to any port 80 \e - rdr-to 127.0.0.1 port 80 -pass in on $int_if proto { tcp, udp } from any to $server port 80 -pass in on $int_if proto { tcp, udp } from $sysadmins to any port 80 -.Ed -.Pp -This example maps outgoing packets' source port -to an assigned proxy port instead of an arbitrary port. -In this case, proxy outgoing isakmp with port 500 on the gateway. -.Bd -literal -offset 4n -match out on $ext_if inet proto udp from any port isakmp to any \e - nat-to ($ext_if) port 500 -.Ed -.Pp -One more example uses -.Ar rdr-to -to redirect a TCP and UDP port to an internal machine. -.Bd -literal -offset 4n -match in on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e - rdr-to 10.1.2.151 port 22 -match in on $ext_if inet proto udp from any to ($ext_if) port 8080 \e - rdr-to 10.1.2.151 port 53 -.Ed -.Pp -In this example, a NAT gateway is set up to translate internal addresses -using a pool of public addresses (192.0.2.16/28). -A given source address is always translated to the same pool address by -using the source-hash keyword. -The gateway also translates incoming web server connections -to a group of web servers on the internal network. -.Bd -literal -offset 4n -match out on $ext_if inet from any to any nat-to 192.0.2.16/28 \e - source-hash -match in on $ext_if proto tcp from any to any port 80 \e - rdr-to { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin -.Ed -.Sh FILTER EXAMPLES +.Sh EXAMPLES In this example, the external interface is kue0. We use a macro for the interface name, so it can be changed easily. @@ -2556,6 +2476,83 @@ match in on $ext_if inet proto tcp from \*(Ltspammers\*(Gt to port smtp \e block in on $ext_if pass in on $ext_if inet proto tcp tagged SPAMD .Ed +.Pp +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, +and therefore lacks permission to bind to port 80). +.Bd -literal -offset 4n +match in on $ext_if proto tcp from any to any port 80 \e + rdr-to 127.0.0.1 port 8080 +.Ed +.Pp +If the +.Ar pass +modifier is given, packets matching the translation rule are passed without +inspecting the filter rules. +.Bd -literal -offset 4n +match in on $ext_if proto tcp from any to any port 80 \e + rdr-to 127.0.0.1 port 8080 +.Ed +.Pp +In the example below, vlan12 is configured as 192.168.168.1; +the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111 +when they are going out any interface except vlan12. +This has the net effect of making traffic from the 192.168.168.0/24 +network appear as though it is the Internet routable address +204.92.77.111 to nodes behind any interface on the router except +for the nodes on vlan12. +Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes. +.Bd -literal -offset 4n +match out on ! vlan12 from 192.168.168.0/24 to any nat-to 204.92.77.111 +.Ed +.Pp +In the example below, the machine sits between a fake internal +144.19.74.* network, and a routable external IP of 204.92.77.100. +The last rule excludes protocol AH from being translated. +.Bd -literal -offset 4n +pass out on $ext_if from 144.19.74.0/24 nat-to 204.92.77.100 +pass out on $ext_if proto ah from 144.19.74.0/24 +.Ed +.Pp +In the example below, packets bound for one specific server, as well as those +generated by the sysadmins are not proxied; all other connections are. +.Bd -literal -offset 4n +match in on $int_if proto { tcp, udp } from any to any port 80 \e + rdr-to 127.0.0.1 port 80 +pass in on $int_if proto { tcp, udp } from any to $server port 80 +pass in on $int_if proto { tcp, udp } from $sysadmins to any port 80 +.Ed +.Pp +This example maps outgoing packets' source port +to an assigned proxy port instead of an arbitrary port. +In this case, proxy outgoing isakmp with port 500 on the gateway. +.Bd -literal -offset 4n +match out on $ext_if inet proto udp from any port isakmp to any \e + nat-to ($ext_if) port 500 +.Ed +.Pp +One more example uses +.Ar rdr-to +to redirect a TCP and UDP port to an internal machine. +.Bd -literal -offset 4n +match in on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e + rdr-to 10.1.2.151 port 22 +match in on $ext_if inet proto udp from any to ($ext_if) port 8080 \e + rdr-to 10.1.2.151 port 53 +.Ed +.Pp +In this example, a NAT gateway is set up to translate internal addresses +using a pool of public addresses (192.0.2.16/28). +A given source address is always translated to the same pool address by +using the source-hash keyword. +The gateway also translates incoming web server connections +to a group of web servers on the internal network. +.Bd -literal -offset 4n +match out on $ext_if inet from any to any nat-to 192.0.2.16/28 \e + source-hash +match in on $ext_if proto tcp from any to any port 80 \e + rdr-to { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin +.Ed .Sh GRAMMAR Syntax for .Nm @@ -2601,8 +2598,8 @@ filteropt = user | group | flags | icmp-type | icmp6-type | "rdr-to" ( redirhost | "{" redirhost-list "}" ) [ portspec ] [ pooltype ] | "nat-to" ( redirhost | "{" redirhost-list "}" ) - [ portspec ] [ pooltype ] [ "static-port" ] - [ "fastroute" | route ] + [ portspec ] [ pooltype ] [ "static-port" ] + [ "fastroute" | route ] scrubopts = scrubopt [ [ "," ] scrubopts ] scrubopt = "no-df" | "min-ttl" number | "max-mss" number | |