32.Dt PF.CONF 5 33.Os 34.Sh NAME 35.Nm pf.conf 36.Nd packet filter configuration file 37.Sh DESCRIPTION 38The 39.Xr pf 4 40packet filter modifies, drops or passes packets according to rules or 41definitions specified in 42.Nm pf.conf . 43.Sh STATEMENT ORDER 44There are seven types of statements in 45.Nm pf.conf : 46.Bl -tag -width xxxx 47.It Cm Macros 48User-defined variables may be defined and used later, simplifying 49the configuration file. 50Macros must be defined before they are referenced in 51.Nm pf.conf . 52.It Cm Tables 53Tables provide a mechanism for increasing the performance and flexibility of 54rules with large numbers of source or destination addresses. 55.It Cm Options 56Options tune the behaviour of the packet filtering engine. 57.It Cm Traffic Normalization Li (e.g. Em scrub ) 58Traffic normalization protects internal machines against inconsistencies 59in Internet protocols and implementations. 60.It Cm Queueing 61Queueing provides rule-based bandwidth control. 62.It Cm Translation Li (Various forms of NAT) 63Translation rules specify how addresses are to be mapped or redirected to 64other addresses. 65.It Cm Packet Filtering 66Stateful and stateless packet filtering provides rule-based blocking or 67passing of packets. 68.El 69.Pp 70With the exception of 71.Cm macros 72and 73.Cm tables , 74the types of statements should be grouped and appear in 75.Nm pf.conf 76in the order shown above, as this matches the operation of the underlying 77packet filtering engine. 78By default 79.Xr pfctl 8 80enforces this order (see 81.Ar set require-order 82below). 83.Sh MACROS 84Much like 85.Xr cpp 1 86or 87.Xr m4 1 , 88macros can be defined that will later be expanded in context. 89Macro names must start with a letter, and may contain letters, digits 90and underscores. 91Macro names may not be reserved words (for example 92.Ar pass , 93.Ar in , 94.Ar out ) . 95Macros are not expanded inside quotes. 96.Pp 97For example, 98.Bd -literal -offset indent 99ext_if = \&"kue0\&" 100all_ifs = \&"{\&" $ext_if lo0 \&"}\&" 101pass out on $ext_if from any to any keep state 102pass in on $ext_if proto tcp from any to any port 25 keep state 103.Ed 104.Sh TABLES 105Tables are named structures which can hold a collection of addresses and 106networks. 107Lookups against tables in 108.Xr pf 4 109are relatively fast, making a single rule with tables much more efficient, 110in terms of 111processor usage and memory consumption, than a large number of rules which 112differ only in IP address (either created explicitly or automatically by rule 113expansion). 114.Pp 115Tables can be used as the source or destination of filter rules, 116.Ar scrub 117rules 118or 119translation rules such as 120.Ar nat 121or 122.Ar rdr 123(see below for details on the various rule types). 124Tables can also be used for the redirect address of 125.Ar nat 126and 127.Ar rdr 128rules and in the routing options of filter rules, but only for 129.Ar round-robin 130pools. 131.Pp 132Tables can be defined with any of the following 133.Xr pfctl 8 134mechanisms. 135As with macros, reserved words may not be used as table names. 136.Bl -tag -width "manually" 137.It Ar manually 138Persistent tables can be manually created with the 139.Ar add 140or 141.Ar replace 142option of 143.Xr pfctl 8 , 144before or after the ruleset has been loaded. 145.It Pa pf.conf 146Table definitions can be placed directly in this file, and loaded at the 147same time as other rules are loaded, atomically. 148Table definitions inside 149.Nm pf.conf 150use the 151.Ar table 152statement, and are especially useful to define non-persistent tables. 153The contents of a pre-existing table defined without a list of addresses 154to initialize it is not altered when 155.Nm pf.conf 156is loaded. 157A table initialized with the empty list, 158.Li { } , 159will be cleared on load. 160.El 161.Pp 162Tables may be defined with the following two attributes: 163.Bl -tag -width persist 164.It Ar persist 165The 166.Ar persist 167flag forces the kernel to keep the table even when no rules refer to it. 168If the flag is not set, the kernel will automatically remove the table 169when the last rule referring to it is flushed. 170.It Ar const 171The 172.Ar const 173flag prevents the user from altering the contents of the table once it 174has been created. 175Without that flag, 176.Xr pfctl 8 177can be used to add or remove addresses from the table at any time, even 178when running with 179.Xr securelevel 7 180= 2. 181.El 182.Pp 183For example, 184.Bd -literal -offset indent 185table <private> const { 10/8, 172.16/12, 192.168/16 } 186table <badhosts> persist 187block on fxp0 from { <private>, <badhosts> } to any 188.Ed 189.Pp 190creates a table called private, to hold RFC 1918 private network 191blocks, and a table called badhosts, which is initially empty. 192A filter rule is set up to block all traffic coming from addresses listed in 193either table. 194The private table cannot have its contents changed and the badhosts table 195will exist even when no active filter rules reference it. 196Addresses may later be added to the badhosts table, so that traffic from 197these hosts can be blocked by using 198.Bd -literal -offset indent 199# pfctl -t badhosts -Tadd 204.92.77.111 200.Ed 201.Pp 202A table can also be initialized with an address list specified in one or more 203external files, using the following syntax: 204.Bd -literal -offset indent 205table <spam> persist file \&"/etc/spammers\&" file \&"/etc/openrelays\&" 206block on fxp0 from <spam> to any 207.Ed 208.Pp 209The files 210.Pa /etc/spammers 211and 212.Pa /etc/openrelays 213list IP addresses, one per line. 214Any lines beginning with a # are treated as comments and ignored. 215In addition to being specified by IP address, hosts may also be 216specified by their hostname. 217When the resolver is called to add a hostname to a table, 218.Em all 219resulting IPv4 and IPv6 addresses are placed into the table. 220IP addresses can also be entered in a table by specifying a valid interface 221name or the 222.Em self 223keyword, in which case all addresses assigned to the interface(s) will be 224added to the table. 225.Sh OPTIONS 226.Xr pf 4 227may be tuned for various situations using the 228.Ar set 229command. 230.Bl -tag -width xxxx 231.It Ar set timeout 232.Pp 233.Bl -tag -width interval -compact 234.It Ar interval 235Interval between purging expired states and fragments. 236.It Ar frag 237Seconds before an unassembled fragment is expired. 238.It Ar src.track 239Length of time to retain a source tracking entry after the last state 240expires. 241.El 242.Pp 243When a packet matches a stateful connection, the seconds to live for the 244connection will be updated to that of the 245.Ar proto.modifier 246which corresponds to the connection state. 247Each packet which matches this state will reset the TTL. 248Tuning these values may improve the performance of the 249firewall at the risk of dropping valid idle connections. 250.Pp 251.Bl -tag -width xxxx -compact 252.It Ar tcp.first 253The state after the first packet. 254.It Ar tcp.opening 255The state before the destination host ever sends a packet. 256.It Ar tcp.established 257The fully established state. 258.It Ar tcp.closing 259The state after the first FIN has been sent. 260.It Ar tcp.finwait 261The state after both FINs have been exchanged and the connection is closed. 262Some hosts (notably web servers on Solaris) send TCP packets even after closing 263the connection. 264Increasing 265.Ar tcp.finwait 266(and possibly 267.Ar tcp.closing ) 268can prevent blocking of such packets. 269.It Ar tcp.closed 270The state after one endpoint sends an RST. 271.El 272.Pp 273ICMP and UDP are handled in a fashion similar to TCP, but with a much more 274limited set of states: 275.Pp 276.Bl -tag -width xxxx -compact 277.It Ar udp.first 278The state after the first packet. 279.It Ar udp.single 280The state if the source host sends more than one packet but the destination 281host has never sent one back. 282.It Ar udp.multiple 283The state if both hosts have sent packets. 284.It Ar icmp.first 285The state after the first packet. 286.It Ar icmp.error 287The state after an ICMP error came back in response to an ICMP packet. 288.El 289.Pp 290Other protocols are handled similarly to UDP: 291.Pp 292.Bl -tag -width xxxx -compact 293.It Ar other.first 294.It Ar other.single 295.It Ar other.multiple 296.El 297.Pp 298Timeout values can be reduced adaptively as the number of state table 299entries grows. 300.Pp 301.Bl -tag -width xxxx -compact 302.It Ar adaptive.start 303When the number of state entries exceeds this value, adaptive scaling 304begins. 305All timeout values are scaled linearly with factor 306(adaptive.end - number of states) / (adaptive.end - adaptive.start). 307.It Ar adaptive.end 308When reaching this number of state entries, all timeout values become 309zero, effectively purging all state entries immediately. 310This value is used to define the scale factor, it should not actually 311be reached (set a lower state limit, see below). 312.El 313.Pp 314These values can be defined both globally and for each rule. 315When used on a per-rule basis, the values relate to the number of 316states created by the rule, otherwise to the total number of 317states. 318.Pp 319For example: 320.Bd -literal -offset indent 321set timeout tcp.first 120 322set timeout tcp.established 86400 323set timeout { adaptive.start 6000, adaptive.end 12000 } 324set limit states 10000 325.Ed 326.Pp 327With 9000 state table entries, the timeout values are scaled to 50% 328(tcp.first 60, tcp.established 43200). 329.Pp 330.It Ar set loginterface 331Enable collection of packet and byte count statistics for the given interface. 332These statistics can be viewed using 333.Bd -literal -offset indent 334# pfctl -s info 335.Ed 336.Pp 337In this example 338.Xr pf 4 339collects statistics on the interface named dc0: 340.Bd -literal -offset indent 341set loginterface dc0 342.Ed 343.Pp 344One can disable the loginterface using: 345.Bd -literal -offset indent 346set loginterface none 347.Ed 348.Pp 349.It Ar set limit 350Sets hard limits on the memory pools used by the packet filter. 351See 352.Xr pool 9 353for an explanation of memory pools. 354.Pp 355For example, 356.Bd -literal -offset indent 357set limit states 20000 358.Ed 359.Pp 360sets the maximum number of entries in the memory pool used by state table 361entries (generated by 362.Ar keep state 363rules) to 20000. 364Using 365.Bd -literal -offset indent 366set limit frags 20000 367.Ed 368.Pp 369sets the maximum number of entries in the memory pool used for fragment 370reassembly (generated by 371.Ar scrub 372rules) to 20000. 373Finally, 374.Bd -literal -offset indent 375set limit src-nodes 2000 376.Ed 377.Pp 378sets the maximum number of entries in the memory pool used for tracking 379source IP addresses (generated by the 380.Ar sticky-address 381and 382.Ar source-track 383options) to 2000. 384.Pp 385These can be combined: 386.Bd -literal -offset indent 387set limit { states 20000, frags 20000, src-nodes 2000 } 388.Ed 389.Pp 390.It Ar set optimization 391Optimize the engine for one of the following network environments: 392.Pp 393.Bl -tag -width xxxx -compact 394.It Ar normal 395A normal network environment. 396Suitable for almost all networks. 397.It Ar high-latency 398A high-latency environment (such as a satellite connection). 399.It Ar satellite 400Alias for 401.Ar high-latency . 402.It Ar aggressive 403Aggressively expire connections. 404This can greatly reduce the memory usage of the firewall at the cost of 405dropping idle connections early. 406.It Ar conservative 407Extremely conservative settings. 408Avoid dropping legitimate connections at the 409expense of greater memory utilization (possibly much greater on a busy 410network) and slightly increased processor utilization. 411.El 412.Pp 413For example: 414.Bd -literal -offset indent 415set optimization aggressive 416.Ed 417.Pp 418.It Ar set block-policy 419The 420.Ar block-policy 421option sets the default behaviour for the packet 422.Ar block 423action: 424.Pp 425.Bl -tag -width xxxxxxxx -compact 426.It Ar drop 427Packet is silently dropped. 428.It Ar return 429A TCP RST is returned for blocked TCP packets, 430an ICMP UNREACHABLE is returned for blocked UDP packets, 431and all other packets are silently dropped. 432.El 433.Pp 434For example: 435.Bd -literal -offset indent 436set block-policy return 437.Ed 438.It Ar set state-policy 439The 440.Ar state-policy 441option sets the default behaviour for states: 442.Pp 443.Bl -tag -width group-bound -compact 444.It Ar if-bound 445States are bound to interface. 446.It Ar group-bound 447States are bound to interface group (i.e. ppp) 448.It Ar floating 449States can match packets on any interfaces (the default). 450.El 451.Pp 452For example: 453.Bd -literal -offset indent 454set state-policy if-bound 455.Ed 456.It Ar set require-order 457By default 458.Xr pfctl 8 459enforces an ordering of the statement types in the ruleset to: 460.Em options , 461.Em normalization , 462.Em queueing , 463.Em translation , 464.Em filtering . 465Setting this option to 466.Ar no 467disables this enforcement. 468There may be non-trivial and non-obvious implications to an out of 469order ruleset. 470Consider carefully before disabling the order enforcement. 471.It Ar set fingerprints 472Load fingerprints of known operating systems from the given filename. 473By default fingerprints of known operating systems are automatically 474loaded from 475.Xr pf.os 5 476in 477.Pa /etc 478but can be overridden via this option. 479Setting this option may leave a small period of time where the fingerprints 480referenced by the currently active ruleset are inconsistent until the new 481ruleset finishes loading. 482.Pp 483For example: 484.Pp 485.Dl set fingerprints \&"/etc/pf.os.devel\&" 486.Pp 487.It Ar set debug 488Set the debug 489.Ar level 490to one of the following: 491.Pp 492.Bl -tag -width xxxxxxxxxxxx -compact 493.It Ar none 494Don't generate debug messages. 495.It Ar urgent 496Generate debug messages only for serious errors. 497.It Ar misc 498Generate debug messages for various errors. 499.It Ar loud 500Generate debug messages for common conditions. 501.El 502.El 503.Sh TRAFFIC NORMALIZATION 504Traffic normalization is used to sanitize packet content in such 505a way that there are no ambiguities in packet interpretation on 506the receiving side. 507The normalizer does IP fragment reassembly to prevent attacks 508that confuse intrusion detection systems by sending overlapping 509IP fragments. 510Packet normalization is invoked with the 511.Ar scrub 512directive. 513.Pp 514.Ar scrub 515has the following options: 516.Bl -tag -width xxxx 517.It Ar no-df 518Clears the 519.Ar dont-fragment 520bit from a matching IP packet. 521Some operating systems are known to generate fragmented packets with the 522.Ar dont-fragment 523bit set. 524This is particularly true with NFS. 525.Ar Scrub 526will drop such fragmented 527.Ar dont-fragment 528packets unless 529.Ar no-df 530is specified. 531.Pp 532Unfortunately some operating systems also generate their 533.Ar dont-fragment 534packets with a zero IP identification field. 535Clearing the 536.Ar dont-fragment 537bit on packets with a zero IP ID may cause deleterious results if an 538upstream router later fragments the packet. 539Using the 540.Ar random-id 541modifier (see below) is recommended in combination with the 542.Ar no-df 543modifier to ensure unique IP identifiers. 544.It Ar min-ttl <number> 545Enforces a minimum TTL for matching IP packets. 546.It Ar max-mss <number> 547Enforces a maximum MSS for matching TCP packets. 548.It Ar random-id 549Replaces the IP identification field with random values to compensate 550for predictable values generated by many hosts. 551This option only applies to outgoing packets that are not fragmented 552after the optional fragment reassembly. 553.It Ar fragment reassemble 554Using 555.Ar scrub 556rules, fragments can be reassembled by normalization. 557In this case, fragments are buffered until they form a complete 558packet, and only the completed packet is passed on to the filter. 559The advantage is that filter rules have to deal only with complete 560packets, and can ignore fragments. 561The drawback of caching fragments is the additional memory cost. 562But the full reassembly method is the only method that currently works 563with NAT. 564This is the default behavior of a 565.Ar scrub 566rule if no fragmentation modifier is supplied. 567.It Ar fragment crop 568The default fragment reassembly method is expensive, hence the option 569to crop is provided. 570In this case, 571.Xr pf 4 572will track the fragments and cache a small range descriptor. 573Duplicate fragments are dropped and overlaps are cropped. 574Thus data will only occur once on the wire with ambiguities resolving to 575the first occurrence. 576Unlike the 577.Ar fragment reassemble 578modifier, fragments are not buffered, they are passed as soon as they 579are received. 580The 581.Ar fragment crop 582reassembly mechanism does not yet work with NAT. 583.Pp 584.It Ar fragment drop-ovl 585This option is similar to the 586.Ar fragment crop 587modifier except that all overlapping or duplicate fragments will be 588dropped, and all further corresponding fragments will be 589dropped as well. 590.It Ar reassemble tcp 591Statefully normalizes TCP connections. 592.Ar scrub reassemble tcp 593rules may not have the direction (in/out) specified. 594.Ar reassemble tcp 595performs the following normalizations: 596.Pp 597.Bl -tag -width timeout -compact 598.It ttl 599Neither side of the connection is allowed to reduce their IP TTL. 600An attacker may send a packet such that it reaches the firewall, affects 601the firewall state, and expires before reaching the destination host. 602.Ar reassemble tcp 603will raise the TTL of all packets back up to the highest value seen on 604the connection. 605.It timeout modulation 606Modern TCP stacks will send a timestamp on every TCP packet and echo 607the other endpoint's timestamp back to them. 608Many operating systems will merely start the timestamp at zero when 609first booted, and increment it several times a second. 610The uptime of the host can be deduced by reading the timestamp and multiplying 611by a constant. 612Also observing several different timestamps can be used to count hosts 613behind a NAT device. 614And spoofing TCP packets into a connection requires knowing or guessing 615valid timestamps. 616Timestamps merely need to be monotonically increasing and not derived off a 617guessable base time. 618.Ar reassemble tcp 619will cause 620.Ar scrub 621to modulate the TCP timestamps with a random number. 622.El 623.El 624.Pp 625For example, 626.Bd -literal -offset indent 627scrub in on $ext_if all fragment reassemble 628.Ed 629.Sh QUEUEING 630Packets can be assigned to queues for the purpose of bandwidth 631control. 632At least two declarations are required to configure queues, and later 633any packet filtering rule can reference the defined queues by name. 634During the filtering component of 635.Nm pf.conf , 636the last referenced 637.Ar queue 638name is where any packets from 639.Ar pass 640rules will be queued, while for 641.Ar block 642rules it specifies where any resulting ICMP or TCP RST 643packets should be queued. 644The 645.Ar scheduler 646defines the algorithm used to decide which packets get delayed, dropped, or 647sent out immediately. 648There are three 649.Ar schedulers 650currently supported. 651.Bl -tag -width xxxx 652.It Ar cbq 653Class Based Queueing. 654.Ar Queues 655attached to an interface build a tree, thus each 656.Ar queue 657can have further child 658.Ar queues . 659Each queue can have a 660.Ar priority 661and a 662.Ar bandwidth 663assigned. 664.Ar Priority 665mainly controls the time packets take to get sent out, while 666.Ar bandwidth 667has primarily effects on throughput. 668.It Ar priq 669Priority Queueing. 670.Ar Queues 671are flat attached to the interface, thus, 672.Ar queues 673cannot have further child 674.Ar queues . 675Each 676.Ar queue 677has a unique 678.Ar priority 679assigned, ranging from 0 to 15. 680Packets in the 681.Ar queue 682with the highest 683.Ar priority 684are processed first. 685.It Ar hfsc 686Hierarchical Fair Service Curve. 687.Ar Queues 688attached to an interface build a tree, thus each 689.Ar queue 690can have further child 691.Ar queues . 692Each queue can have a 693.Ar priority 694and a 695.Ar bandwidth 696assigned. 697.Ar Priority 698mainly controls the time packets take to get sent out, while 699.Ar bandwidth 700has primarily effects on throughput. 701.El 702.Pp 703The interfaces on which queueing should be activated are declared using 704the 705.Ar altq on 706declaration. 707.Ar altq on 708has the following keywords: 709.Bl -tag -width xxxx 710.It Ar <interface> 711Queueing is enabled on the named interface. 712.It Ar <scheduler> 713Specifies which queueing scheduler to use. 714Currently supported values 715are 716.Ar cbq 717for Class Based Queueing, 718.Ar priq 719for Priority Queueing and 720.Ar hfsc 721for the Hierarchical Fair Service Curve scheduler. 722.It Ar bandwidth <bw> 723The maximum bitrate for all queues on an 724interface may be specified using the 725.Ar bandwidth 726keyword. 727The value can be specified as an absolute value or as a 728percentage of the interface bandwidth. 729When using an absolute value, the suffixes 730.Ar b , 731.Ar Kb , 732.Ar Mb , 733and 734.Ar Gb 735are used to represent bits, kilobits, megabits, and 736gigabits per second, respectively. 737The value must not exceed the interface bandwidth. 738If 739.Ar bandwidth 740is not specified, the interface bandwidth is used. 741.It Ar qlimit <limit> 742The maximum number of packets held in the queue. 743The default is 50. 744.It Ar tbrsize <size> 745Adjusts the size, in bytes, of the token bucket regulator. 746If not specified, heuristics based on the 747interface bandwidth are used to determine the size. 748.It Ar queue <list> 749Defines a list of subqueues to create on an interface. 750.El 751.Pp 752In the following example, the interface dc0 753should queue up to 5 Mbit/s in four second-level queues using 754Class Based Queueing. 755Those four queues will be shown in a later example. 756.Bd -literal -offset indent 757altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh } 758.Ed 759.Pp 760Once interfaces are activated for queueing using the 761.Ar altq 762directive, a sequence of 763.Ar queue 764directives may be defined. 765The name associated with a 766.Ar queue 767must match a queue defined in the 768.Ar altq 769directive (e.g. mail), or, except for the 770.Ar priq 771.Ar scheduler , 772in a parent 773.Ar queue 774declaration. 775The following keywords can be used: 776.Bl -tag -width xxxx 777.It Ar on <interface> 778Specifies the interface the queue operates on. 779If not given, it operates on all matching interfaces. 780.It Ar bandwidth <bw> 781Specifies the maximum bitrate to be processed by the queue. 782This value must not exceed the value of the parent 783.Ar queue 784and can be specified as an absolute value or a percentage of the parent 785queue's bandwidth. 786The 787.Ar priq 788scheduler does not support bandwidth specification. 789.It Ar priority <level> 790Between queues a priority level can be set. 791For 792.Ar cbq 793and 794.Ar hfsc , 795the range is 0 to 7 and for 796.Ar priq , 797the range is 0 to 15. 798The default for all is 1. 799.Ar Priq 800queues with a higher priority are always served first. 801.Ar Cbq 802and 803.Ar Hfsc 804queues with a higher priority are preferred in the case of overload. 805.It Ar qlimit <limit> 806The maximum number of packets held in the queue. 807The default is 50. 808.El 809.Pp 810The 811.Ar scheduler 812can get additional parameters with 813.Ar <scheduler> Ns Li (\& Ar <parameters> No ) . 814Parameters are as follows: 815.Bl -tag -width Fl 816.It Ar default 817Packets not matched by another queue are assigned to this one. 818Exactly one default queue is required. 819.It Ar red 820Enable RED (Random Early Detection) on this queue. 821RED drops packets with a probability proportional to the average 822queue length. 823.It Ar rio 824Enables RIO on this queue. 825RIO is RED with IN/OUT, thus running 826RED two times more than RIO would achieve the same effect. 827RIO is currently not supported in the GENERIC kernel. 828.It Ar ecn 829Enables ECN (Explicit Congestion Notification) on this queue. 830ECN implies RED. 831.El 832.Pp 833The 834.Ar cbq 835.Ar scheduler 836supports an additional option: 837.Bl -tag -width Fl 838.It Ar borrow 839The queue can borrow bandwidth from the parent. 840.El 841.Pp 842The 843.Ar hfsc 844.Ar scheduler 845supports some additional options: 846.Bl -tag -width Fl 847.It Ar realtime <sc> 848The minimum required bandwidth for the queue. 849.It Ar upperlimit <sc> 850The maximum allowed bandwidth for the queue. 851.It Ar linkshare <sc> 852The bandwidth share of a backlogged queue. 853.El 854.Pp 855<sc> is an acronym for 856.Ar service curve . 857.Pp 858The format for service curve specifications is 859.Ar ( m1 , d , m2 ) . 860.Ar m2 861controls the bandwidth assigned to the queue. 862.Ar m1 863and 864.Ar d 865are optional and can be used to control the initial bandwidth assignment. 866For the first 867.Ar d 868milliseconds the queue gets the bandwidth given as 869.Ar m1 , 870afterwards the value given in 871.Ar m2 . 872.Pp 873Furthermore, with 874.Ar cbq 875and 876.Ar hfsc , 877child queues can be specified as in an 878.Ar altq 879declaration, thus building a tree of queues using a part of 880their parent's bandwidth. 881.Pp 882Packets can be assigned to queues based on filter rules by using the 883.Ar queue 884keyword. 885Normally only one 886.Ar queue 887is specified; when a second one is specified it will instead be used for 888packets which have a 889.Em TOS 890of 891.Em lowdelay 892and for TCP ACKs with no data payload. 893.Pp 894To continue the previous example, the examples below would specify the 895four referenced 896queues, plus a few child queues. 897Interactive 898.Xr ssh 1 899sessions get priority over bulk transfers like 900.Xr scp 1 901and 902.Xr sftp 1 . 903The queues may then be referenced by filtering rules (see 904.Sx PACKET FILTERING 905below). 906.Bd -literal 907queue std bandwidth 10% cbq(default) 908queue http bandwidth 60% priority 2 cbq(borrow red) \e 909 { employees, developers } 910queue developers bandwidth 75% cbq(borrow) 911queue employees bandwidth 15% 912queue mail bandwidth 10% priority 0 cbq(borrow ecn) 913queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk } 914queue ssh_interactive priority 7 915queue ssh_bulk priority 0 916 917block return out on dc0 inet all queue std 918pass out on dc0 inet proto tcp from $developerhosts to any port 80 \e 919 keep state queue developers 920pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e 921 keep state queue employees 922pass out on dc0 inet proto tcp from any to any port 22 \e 923 keep state queue(ssh_bulk, ssh_interactive) 924pass out on dc0 inet proto tcp from any to any port 25 \e 925 keep state queue mail 926.Ed 927.Sh TRANSLATION 928Translation rules modify either the source or destination address of the 929packets associated with a stateful connection. 930A stateful connection is automatically created to track packets matching 931such a rule as long as they are not blocked by the filtering section of 932.Nm pf.conf . 933The translation engine modifies the specified address and/or port in the 934packet, recalculates IP, TCP and UDP checksums as necessary, and passes it to 935the packet filter for evaluation. 936.Pp 937Since translation occurs before filtering the filter 938engine will see packets as they look after any 939addresses and ports have been translated. Filter rules 940will therefore have to filter based on the translated 941address and port number. 942Packets that match a translation rule are only automatically passed if 943the 944.Ar pass 945modifier is given, otherwise they are 946still subject to 947.Ar block 948and 949.Ar pass 950rules. 951.Pp 952The state entry created permits 953.Xr pf 4 954to keep track of the original address for traffic associated with that state 955and correctly direct return traffic for that connection. 956.Pp 957Various types of translation are possible with pf: 958.Bl -tag -width xxxx 959.It Ar binat 960A 961.Ar binat 962rule specifies a bidirectional mapping between an external IP netblock 963and an internal IP netblock. 964.It Ar nat 965A 966.Ar nat 967rule specifies that IP addresses are to be changed as the packet 968traverses the given interface. 969This technique allows one or more IP addresses 970on the translating host to support network traffic for a larger range of 971machines on an "inside" network. 972Although in theory any IP address can be used on the inside, it is strongly 973recommended that one of the address ranges defined by RFC 1918 be used. 974These netblocks are: 975.Bd -literal 97610.0.0.0 - 10.255.255.255 (all of net 10, i.e., 10/8) 977172.16.0.0 - 172.31.255.255 (i.e., 172.16/12) 978192.168.0.0 - 192.168.255.255 (i.e., 192.168/16) 979.Ed 980.It Pa rdr 981The packet is redirected to another destination and possibly a 982different port. 983.Ar rdr 984rules can optionally specify port ranges instead of single ports. 985rdr ... port 2000:2999 -> ... port 4000 986redirects ports 2000 to 2999 (inclusive) to port 4000. 987rdr ... port 2000:2999 -> ... port 4000:* 988redirects port 2000 to 4000, 2001 to 4001, ..., 2999 to 4999. 989.El 990.Pp 991In addition to modifying the address, some translation rules may modify 992source or destination ports for 993.Xr tcp 4 994or 995.Xr udp 4 996connections; implicitly in the case of 997.Ar nat 998rules and explicitly in the case of 999.Ar rdr 1000rules. 1001Port numbers are never translated with a 1002.Ar binat 1003rule. 1004.Pp 1005For each packet processed by the translator, the translation rules are 1006evaluated in sequential order, from first to last. 1007The first matching rule decides what action is taken. 1008.Pp 1009The 1010.Ar no 1011option prefixed to a translation rule causes packets to remain untranslated, 1012much in the same way as 1013.Ar drop quick 1014works in the packet filter (see below). 1015If no rule matches the packet it is passed to the filter engine unmodified. 1016.Pp 1017Translation rules apply only to packets that pass through 1018the specified interface, and if no interface is specified, 1019translation is applied to packets on all interfaces. 1020For instance, redirecting port 80 on an external interface to an internal 1021web server will only work for connections originating from the outside. 1022Connections to the address of the external interface from local hosts will 1023not be redirected, since such packets do not actually pass through the 1024external interface. 1025Redirections cannot reflect packets back through the interface they arrive 1026on, they can only be redirected to hosts connected to different interfaces 1027or to the firewall itself. 1028.Pp 1029Note that redirecting external incoming connections to the loopback 1030address, as in 1031.Bd -literal -offset indent 1032rdr on ne3 inet proto tcp to port 8025 -> 127.0.0.1 port 25 1033.Ed 1034.Pp 1035will effectively allow an external host to connect to daemons 1036bound solely to the loopback address, circumventing the traditional 1037blocking of such connections on a real interface. 1038Unless this effect is desired, any of the local non-loopback addresses 1039should be used as redirection target instead, which allows external 1040connections only to daemons bound to this address or not bound to 1041any address. 1042.Pp 1043See 1044.Sx TRANSLATION EXAMPLES 1045below. 1046.Sh PACKET FILTERING 1047.Xr pf 4 1048has the ability to 1049.Ar block 1050and 1051.Ar pass 1052packets based on attributes of their layer 3 (see 1053.Xr ip 4 1054and 1055.Xr ip6 4 ) 1056and layer 4 (see 1057.Xr icmp 4 , 1058.Xr icmp6 4 , 1059.Xr tcp 4 , 1060.Xr udp 4 ) 1061headers. 1062In addition, packets may also be 1063assigned to queues for the purpose of bandwidth control. 1064.Pp 1065For each packet processed by the packet filter, the filter rules are 1066evaluated in sequential order, from first to last. 1067The last matching rule decides what action is taken. 1068.Pp 1069The following actions can be used in the filter: 1070.Bl -tag -width xxxx 1071.It Ar block 1072The packet is blocked. 1073There are a number of ways in which a 1074.Ar block 1075rule can behave when blocking a packet. 1076The default behaviour is to 1077.Ar drop 1078packets silently, however this can be overridden or made 1079explicit either globally, by setting the 1080.Ar block-policy 1081option, or on a per-rule basis with one of the following options: 1082.Pp 1083.Bl -tag -width xxxx -compact 1084.It Ar drop 1085The packet is silently dropped. 1086.It Ar return-rst 1087This applies only to 1088.Xr tcp 4 1089packets, and issues a TCP RST which closes the 1090connection. 1091.It Ar return-icmp 1092.It Ar return-icmp6 1093This causes ICMP messages to be returned for packets which match the rule. 1094By default this is an ICMP UNREACHABLE message, however this 1095can be overridden by specifying a message as a code or number. 1096.It Ar return 1097This causes a TCP RST to be returned for 1098.Xr tcp 4 1099packets and an ICMP UNREACHABLE for UDP and other packets. 1100.El 1101.Pp 1102Options returning packets have no effect if 1103.Xr pf 4 1104operates on a 1105.Xr bridge 4 . 1106.It Ar pass 1107The packet is passed. 1108.El 1109.Pp 1110If no rule matches the packet, the default action is 1111.Ar pass . 1112.Pp 1113To block everything by default and only pass packets 1114that match explicit rules, one uses 1115.Bd -literal -offset indent 1116block all 1117.Ed 1118.Pp 1119as the first filter rule. 1120.Pp 1121See 1122.Sx FILTER EXAMPLES 1123below. 1124.Sh PARAMETERS 1125The rule parameters specify the packets to which a rule applies. 1126A packet always comes in on, or goes out through, one interface. 1127Most parameters are optional. 1128If a parameter is specified, the rule only applies to packets with 1129matching attributes. 1130Certain parameters can be expressed as lists, in which case 1131.Xr pfctl 8 1132generates all needed rule combinations. 1133.Bl -tag -width xxxx 1134.It Ar in No or Ar out 1135This rule applies to incoming or outgoing packets. 1136If neither 1137.Ar in 1138nor 1139.Ar out 1140are specified, the rule will match packets in both directions. 1141.It Ar log 1142In addition to the action specified, a log message is generated. 1143All packets for that connection are logged, unless the 1144.Ar keep state , 1145.Ar modulate state 1146or 1147.Ar synproxy state 1148options are specified, in which case only the 1149packet that establishes the state is logged. 1150(See 1151.Ar keep state , 1152.Ar modulate state 1153and 1154.Ar synproxy state 1155below). 1156The logged packets are sent to the 1157.Xr pflog 4 1158interface. 1159This interface is monitored by the 1160.Xr pflogd 8 1161logging daemon, which dumps the logged packets to the file 1162.Pa /var/log/pflog 1163in 1164.Xr pcap 3 1165binary format. 1166.It Ar log-all 1167Used with 1168.Ar keep state , 1169.Ar modulate state 1170or 1171.Ar synproxy state 1172rules to force logging of all packets for a connection. 1173As with 1174.Ar log , 1175packets are logged to 1176.Xr pflog 4 . 1177.It Ar quick 1178If a packet matches a rule which has the 1179.Ar quick 1180option set, this rule 1181is considered the last matching rule, and evaluation of subsequent rules 1182is skipped. 1183.It Ar on <interface> 1184This rule applies only to packets coming in on, or going out through, this 1185particular interface. 1186It is also possible to simply give the interface driver name, like ppp or fxp, 1187to make the rule match packets flowing through a group of interfaces. 1188.It Ar <af> 1189This rule applies only to packets of this address family. 1190Supported values are 1191.Ar inet 1192and 1193.Ar inet6 . 1194.It Ar proto <protocol> 1195This rule applies only to packets of this protocol. 1196Common protocols are 1197.Xr icmp 4 , 1198.Xr icmp6 4 , 1199.Xr tcp 4 , 1200and 1201.Xr udp 4 . 1202For a list of all the protocol name to number mappings used by 1203.Xr pfctl 8 , 1204see the file 1205.Em /etc/protocols . 1206.It Xo 1207.Ar from <source> port <source> os <source> 1208.Ar to <dest> port <dest> 1209.Xc 1210This rule applies only to packets with the specified source and destination 1211addresses and ports. 1212.Pp 1213Addresses can be specified in CIDR notation (matching netblocks), as 1214symbolic host names or interface names, or as any of the following keywords: 1215.Pp 1216.Bl -tag -width xxxxxxxxxxxx -compact 1217.It Ar any 1218Any address. 1219.It Ar no-route 1220Any address which is not currently routable. 1221.It Ar <table> 1222Any address that matches the given table. 1223.El 1224.Pp 1225Interface names can have modifiers appended: 1226.Pp 1227.Bl -tag -width xxxxxxxxxxxx -compact 1228.It Ar :network 1229Translates to the network(s) attached to the interface. 1230.It Ar :broadcast 1231Translates to the interface's broadcast address(es). 1232.It Ar :peer 1233Translates to the point to point interface's peer address(es). 1234.It Ar :0 1235Do not include interface aliases. 1236.El 1237.Pp 1238Host names may also have the 1239.Ar :0 1240option appended to restrict the name resolution to the first of each 1241v4 and v6 address found. 1242.Pp 1243Host name resolution and interface to address translation are done at 1244ruleset load-time. 1245When the address of an interface (or host name) changes (under DHCP or PPP, 1246for instance), the ruleset must be reloaded for the change to be reflected 1247in the kernel. 1248Surrounding the interface name (and optional modifiers) in parentheses 1249changes this behaviour. 1250When the interface name is surrounded by parentheses, the rule is 1251automatically updated whenever the interface changes its address. 1252The ruleset does not need to be reloaded. 1253This is especially useful with 1254.Ar nat . 1255.Pp 1256Ports can be specified either by number or by name. 1257For example, port 80 can be specified as 1258.Em www . 1259For a list of all port name to number mappings used by 1260.Xr pfctl 8 , 1261see the file 1262.Pa /etc/services . 1263.Pp 1264Ports and ranges of ports are specified by using these operators: 1265.Bd -literal -offset indent 1266= (equal) 1267!= (unequal) 1268< (less than) 1269<= (less than or equal) 1270> (greater than) 1271>= (greater than or equal) 1272: (range including boundaries) 1273>< (range excluding boundaries) 1274<> (except range) 1275.Ed 1276.Pp 1277><, <> and : 1278are binary operators (they take two arguments). 1279For instance: 1280.Bl -tag -width Fl 1281.It Ar port 2000:2004 1282means 1283.Sq all ports >= 2000 and <= 2004 , 1284hence ports 2000, 2001, 2002, 2003 and 2004. 1285.It Ar port 2000 >< 2004 1286means 1287.Sq all ports > 2000 and < 2004 , 1288hence ports 2001, 2002 and 2003. 1289.It Ar port 2000 <> 2004 1290means 1291.Sq all ports < 2000 or > 2004 , 1292hence ports 1-1999 and 2005-65535. 1293.El 1294.Pp 1295The operating system of the source host can be specified in the case of TCP 1296rules with the 1297.Ar OS 1298modifier. 1299See the 1300.Sx OPERATING SYSTEM FINGERPRINTING 1301section for more information. 1302.Pp 1303The host, port and OS specifications are optional, as in the following examples: 1304.Bd -literal -offset indent 1305pass in all 1306pass in from any to any 1307pass in proto tcp from any port <= 1024 to any 1308pass in proto tcp from any to any port 25 1309pass in proto tcp from 10.0.0.0/8 port > 1024 \e 1310 to ! 10.1.2.3 port != ssh 1311pass in proto tcp from any os "OpenBSD" flags S/SA 1312.Ed 1313.It Ar all 1314This is equivalent to "from any to any". 1315.It Ar group <group> 1316Similar to 1317.Ar user , 1318this rule only applies to packets of sockets owned by the specified group. 1319.It Ar user <user> 1320This rule only applies to packets of sockets owned by the specified user. 1321For outgoing connections initiated from the firewall, this is the user 1322that opened the connection. 1323For incoming connections to the firewall itself, this is the user that 1324listens on the destination port. 1325For forwarded connections, where the firewall is not a connection endpoint, 1326the user and group are 1327.Em unknown . 1328.Pp 1329All packets, both outgoing and incoming, of one connection are associated 1330with the same user and group. 1331Only TCP and UDP packets can be associated with users; for other protocols 1332these parameters are ignored. 1333.Pp 1334User and group refer to the effective (as opposed to the real) IDs, in 1335case the socket is created by a setuid/setgid process. 1336User and group IDs are stored when a socket is created; 1337when a process creates a listening socket as root (for instance, by 1338binding to a privileged port) and subsequently changes to another 1339user ID (to drop privileges), the credentials will remain root. 1340.Pp 1341User and group IDs can be specified as either numbers or names. 1342The syntax is similar to the one for ports. 1343The value 1344.Em unknown 1345matches packets of forwarded connections. 1346.Em unknown 1347can only be used with the operators 1348.Cm = 1349and 1350.Cm != . 1351Other constructs like 1352.Cm user >= unknown 1353are invalid. 1354Forwarded packets with unknown user and group ID match only rules 1355that explicitly compare against 1356.Em unknown 1357with the operators 1358.Cm = 1359or 1360.Cm != . 1361For instance 1362.Cm user >= 0 1363does not match forwarded packets. 1364The following example allows only selected users to open outgoing 1365connections: 1366.Bd -literal -offset indent 1367block out proto { tcp, udp } all 1368pass out proto { tcp, udp } all \e 1369 user { < 1000, dhartmei } keep state 1370.Ed 1371.It Ar flags <a>/<b> | /<b> 1372This rule only applies to TCP packets that have the flags 1373.Ar <a> 1374set out of set 1375.Ar <b> . 1376Flags not specified in 1377.Ar <b> 1378are ignored. 1379The flags are: (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, (E)CE, and C(W)R. 1380.Bl -tag -width Fl 1381.It Ar flags S/S 1382Flag SYN is set. 1383The other flags are ignored. 1384.It Ar flags S/SA 1385Out of SYN and ACK, exactly SYN may be set. 1386SYN, SYN+PSH and SYN+RST match, but SYN+ACK, ACK and ACK+RST do not. 1387This is more restrictive than the previous example. 1388.It Ar flags /SFRA 1389If the first set is not specified, it defaults to none. 1390All of SYN, FIN, RST and ACK must be unset. 1391.El 1392.It Ar icmp-type <type> code <code> 1393.It Ar icmp6-type <type> code <code> 1394This rule only applies to ICMP or ICMPv6 packets with the specified type 1395and code. 1396This parameter is only valid for rules that cover protocols ICMP or 1397ICMP6. 1398The protocol and the ICMP type indicator (icmp-type or icmp6-type) 1399must match. 1400.It Ar allow-opts 1401By default, packets which contain IP options are blocked. 1402When 1403.Ar allow-opts 1404is specified for a 1405.Ar pass 1406rule, packets that pass the filter based on that rule (last matching) 1407do so even if they contain IP options. 1408For packets that match state, the rule that initially created the 1409state is used. 1410The implicit 1411.Ar pass 1412rule that is used when a packet does not match any rules does not 1413allow IP options. 1414.It Ar label <string> 1415Adds a label (name) to the rule, which can be used to identify the rule. 1416For instance, 1417pfctl -s labels 1418shows per-rule statistics for rules that have labels. 1419.Pp 1420The following macros can be used in labels: 1421.Pp 1422.Bl -tag -width $srcaddr -compact -offset indent 1423.It Ar $if 1424The interface. 1425.It Ar $srcaddr 1426The source IP address. 1427.It Ar $dstaddr 1428The destination IP address. 1429.It Ar $srcport 1430The source port specification. 1431.It Ar $dstport 1432The destination port specification. 1433.It Ar $proto 1434The protocol name. 1435.It Ar $nr 1436The rule number. 1437.El 1438.Pp 1439For example: 1440.Bd -literal -offset indent 1441ips = \&"{ 1.2.3.4, 1.2.3.5 }\&" 1442pass in proto tcp from any to $ips \e 1443 port > 1023 label \&"$dstaddr:$dstport\&" 1444.Ed 1445.Pp 1446expands to 1447.Bd -literal -offset indent 1448pass in inet proto tcp from any to 1.2.3.4 \e 1449 port > 1023 label \&"1.2.3.4:>1023\&" 1450pass in inet proto tcp from any to 1.2.3.5 \e 1451 port > 1023 label \&"1.2.3.5:>1023\&" 1452.Ed 1453.Pp 1454The macro expansion for the 1455.Ar label 1456directive occurs only at configuration file parse time, not during runtime. 1457.It Ar queue <queue> | ( <queue> , <queue> ) 1458Packets matching this rule will be assigned to the specified queue. 1459If two queues are given, packets which have a 1460.Em tos 1461of 1462.Em lowdelay 1463and TCP ACKs with no data payload will be assigned to the second one. 1464See 1465.Sx QUEUEING 1466for setup details. 1467.Pp 1468For example: 1469.Bd -literal -offset indent 1470pass in proto tcp to port 25 queue mail 1471pass in proto tcp to port 22 queue(ssh_bulk, ssh_prio) 1472.Ed 1473.It Ar tag <string> 1474Packets matching this rule will be tagged with the 1475specified string. 1476The tag acts as an internal marker that can be used to 1477identify these packets later on. 1478This can be used, for example, to provide trust between 1479interfaces and to determine if packets have been 1480processed by translation rules. 1481Tags are 1482.Qq sticky , 1483meaning that the packet will be tagged even if the rule 1484is not the last matching rule. 1485Further matching rules can replace the tag with a 1486new one but will not remove a previously applied tag. 1487A packet is only ever assigned one tag at a time. 1488.Ar pass 1489rules that use the 1490.Ar tag 1491keyword must also use 1492.Ar keep state , 1493.Ar modulate state 1494or 1495.Ar synproxy state . 1496Packet tagging can be done during 1497.Ar nat , 1498.Ar rdr , 1499or 1500.Ar binat 1501rules in addition to filter rules. 1502Tags take the same macros as labels (see above). 1503.It Ar tagged <string> 1504Used with filter rules to specify that packets must already 1505be tagged with the given tag in order to match the rule. 1506Inverse tag matching can also be done 1507by specifying the 1508.Cm !\& 1509operator before the 1510.Ar tagged 1511keyword. 1512.El 1513.Sh ROUTING 1514If a packet matches a rule with a route option set, the packet filter will 1515route the packet according to the type of route option. 1516When such a rule creates state, the route option is also applied to all 1517packets matching the same connection. 1518.Bl -tag -width xxxx 1519.It Ar fastroute 1520The 1521.Ar fastroute 1522option does a normal route lookup to find the next hop for the packet. 1523.It Ar route-to 1524The 1525.Ar route-to 1526option routes the packet to the specified interface with an optional address 1527for the next hop. 1528When a 1529.Ar route-to 1530rule creates state, only packets that pass in the same direction as the 1531filter rule specifies will be routed in this way. 1532Packets passing in the opposite direction (replies) are not affected 1533and are routed normally. 1534.It Ar reply-to 1535The 1536.Ar reply-to 1537option is similar to 1538.Ar route-to , 1539but routes packets that pass in the opposite direction (replies) to the 1540specified interface. 1541Opposite direction is only defined in the context of a state entry, and 1542.Ar route-to 1543is useful only in rules that create state. 1544It can be used on systems with multiple external connections to 1545route all outgoing packets of a connection through the interface 1546the incoming connection arrived through (symmetric routing enforcement). 1547.It Ar dup-to 1548The 1549.Ar dup-to 1550option creates a duplicate of the packet and routes it like 1551.Ar route-to . 1552The original packet gets routed as it normally would. 1553.El 1554.Sh POOL OPTIONS 1555For 1556.Ar nat 1557and 1558.Ar rdr 1559rules, (as well as for the 1560.Ar route-to , 1561.Ar reply-to 1562and 1563.Ar dup-to 1564rule options) for which there is a single redirection address which has a 1565subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP 1566address), a variety of different methods for assigning this address can be 1567used: 1568.Bl -tag -width xxxx 1569.It Ar bitmask 1570The 1571.Ar bitmask 1572option applies the network portion of the redirection address to the address 1573to be modified (source with 1574.Ar nat , 1575destination with 1576.Ar rdr ) . 1577.It Ar random 1578The 1579.Ar random 1580option selects an address at random within the defined block of addresses. 1581.It Ar source-hash 1582The 1583.Ar source-hash 1584option uses a hash of the source address to determine the redirection address, 1585ensuring that the redirection address is always the same for a given source. 1586An optional key can be specified after this keyword either in hex or as a 1587string; by default 1588.Xr pfctl 8 1589randomly generates a key for source-hash every time the 1590ruleset is reloaded. 1591.It Ar round-robin 1592The 1593.Ar round-robin 1594option loops through the redirection address(es). 1595.Pp 1596When more than one redirection address is specified, 1597.Ar round-robin 1598is the only permitted pool type. 1599.It Ar static-port 1600With 1601.Ar nat 1602rules, the 1603.Ar static-port 1604option prevents 1605.Xr pf 4 1606from modifying the source port on TCP and UDP packets. 1607.El 1608.Pp 1609Additionally, the 1610.Ar sticky-address 1611option can be specified to help ensure that multiple connections from the 1612same source are mapped to the same redirection address. 1613This option can be used with the 1614.Ar random 1615and 1616.Ar round-robin 1617pool options. 1618Note that by default these associations are destroyed as soon as there are 1619no longer states which refer to them; in order to make the mappings last 1620beyond the lifetime of the states, increase the global options with 1621.Ar set timeout source-track 1622See 1623.Sx STATEFUL TRACKING OPTIONS 1624for more ways to control the source tracking. 1625.Sh STATEFUL INSPECTION 1626.Xr pf 4 1627is a stateful packet filter, which means it can track the state of 1628a connection. 1629Instead of passing all traffic to port 25, for instance, it is possible 1630to pass only the initial packet, and then begin to keep state. 1631Subsequent traffic will flow because the filter is aware of the connection. 1632.Pp 1633If a packet matches a 1634.Ar pass ... keep state 1635rule, the filter creates a state for this connection and automatically 1636lets pass all subsequent packets of that connection. 1637.Pp 1638Before any rules are evaluated, the filter checks whether the packet 1639matches any state. 1640If it does, the packet is passed without evaluation of any rules. 1641.Pp 1642States are removed after the connection is closed or has timed out. 1643.Pp 1644This has several advantages. 1645Comparing a packet to a state involves checking its sequence numbers. 1646If the sequence numbers are outside the narrow windows of expected 1647values, the packet is dropped. 1648This prevents spoofing attacks, such as when an attacker sends packets with 1649a fake source address/port but does not know the connection's sequence 1650numbers. 1651.Pp 1652Also, looking up states is usually faster than evaluating rules. 1653If there are 50 rules, all of them are evaluated sequentially in O(n). 1654Even with 50000 states, only 16 comparisons are needed to match a 1655state, since states are stored in a binary search tree that allows 1656searches in O(log2 n). 1657.Pp 1658For instance: 1659.Bd -literal -offset indent 1660block all 1661pass out proto tcp from any to any flags S/SA keep state 1662pass in proto tcp from any to any port 25 flags S/SA keep state 1663.Ed 1664.Pp 1665This ruleset blocks everything by default. 1666Only outgoing connections and incoming connections to port 25 are allowed. 1667The initial packet of each connection has the SYN 1668flag set, will be passed and creates state. 1669All further packets of these connections are passed if they match a state. 1670.Pp 1671By default, packets coming in and out of any interface can match a state, 1672but it is also possible to change that behaviour by assigning states to a 1673single interface or a group of interfaces. 1674.Pp 1675The default policy is specified by the 1676.Ar state-policy 1677global option, but this can be adjusted on a per-rule basis by adding one 1678of the 1679.Ar if-bound , 1680.Ar group-bound 1681or 1682.Ar floating 1683keywords to the 1684.Ar keep state 1685option. 1686For example, if a rule is defined as: 1687.Bd -literal -offset indent 1688pass out on ppp from any to 10.12/16 keep state (group-bound) 1689.Ed 1690.Pp 1691A state created on ppp0 would match packets an all PPP interfaces, 1692but not packets flowing through fxp0 or any other interface. 1693.Pp 1694Keeping rules 1695.Ar floating 1696is the more flexible option when the firewall is in a dynamic routing 1697environment. 1698However, this has some security implications since a state created by one 1699trusted network could allow potentially hostile packets coming in from other 1700interfaces. 1701.Pp 1702Specifying 1703.Ar flags S/SA 1704restricts state creation to the initial SYN 1705packet of the TCP handshake. 1706One can also be less restrictive, and allow state creation from 1707intermediate 1708.Pq non-SYN 1709packets. 1710This will cause 1711.Xr pf 4 1712to synchronize to existing connections, for instance 1713if one flushes the state table. 1714.Pp 1715For UDP, which is stateless by nature, 1716.Ar keep state 1717will create state as well. 1718UDP packets are matched to states using only host addresses and ports. 1719.Pp 1720ICMP messages fall into two categories: ICMP error messages, which always 1721refer to a TCP or UDP packet, are matched against the referred to connection. 1722If one keeps state on a TCP connection, and an ICMP source quench message 1723referring to this TCP connection arrives, it will be matched to the right 1724state and get passed. 1725.Pp 1726For ICMP queries, 1727.Ar keep state 1728creates an ICMP state, and 1729.Xr pf 4 1730knows how to match ICMP replies to states. 1731For example, 1732.Bd -literal -offset indent 1733pass out inet proto icmp all icmp-type echoreq keep state 1734.Ed 1735.Pp 1736allows echo requests (such as those created by 1737.Xr ping 8 ) 1738out, creates state, and matches incoming echo replies correctly to states. 1739.Pp 1740Note: 1741.Ar nat , binat No and Ar rdr 1742rules implicitly create state for connections. 1743.Sh STATE MODULATION 1744Much of the security derived from TCP is attributable to how well the 1745initial sequence numbers (ISNs) are chosen. 1746Some popular stack implementations choose 1747.Em very 1748poor ISNs and thus are normally susceptible to ISN prediction exploits. 1749By applying a 1750.Ar modulate state 1751rule to a TCP connection, 1752.Xr pf 4 1753will create a high quality random sequence number for each connection 1754endpoint. 1755.Pp 1756The 1757.Ar modulate state 1758directive implicitly keeps state on the rule and is 1759only applicable to TCP connections. 1760.Pp 1761For instance: 1762.Bd -literal -offset indent 1763block all 1764pass out proto tcp from any to any modulate state 1765pass in proto tcp from any to any port 25 flags S/SA modulate state 1766.Ed 1767.Pp 1768There are two caveats associated with state modulation: 1769A 1770.Ar modulate state 1771rule can not be applied to a pre-existing but unmodulated connection. 1772Such an application would desynchronize TCP's strict 1773sequencing between the two endpoints. 1774Instead, 1775.Xr pf 4 1776will treat the 1777.Ar modulate state 1778modifier as a 1779.Ar keep state 1780modifier and the pre-existing connection will be inferred without 1781the protection conferred by modulation. 1782.Pp 1783The other caveat affects currently modulated states when the state table 1784is lost (firewall reboot, flushing the state table, etc...). 1785.Xr pf 4 1786will not be able to infer a connection again after the state table flushes 1787the connection's modulator. 1788When the state is lost, the connection may be left dangling until the 1789respective endpoints time out the connection. 1790It is possible on a fast local network for the endpoints to start an ACK 1791storm while trying to resynchronize after the loss of the modulator. 1792Using a 1793.Ar flags S/SA 1794modifier on 1795.Ar modulate state 1796rules between fast networks is suggested to prevent ACK storms. 1797.Sh SYN PROXY 1798By default, 1799.Xr pf 4 1800passes packets that are part of a 1801.Xr tcp 4 1802handshake between the endpoints. 1803The 1804.Ar synproxy state 1805option can be used to cause 1806.Xr pf 4 1807itself to complete the handshake with the active endpoint, perform a handshake 1808with the passive endpoint, and then forward packets between the endpoints. 1809.Pp 1810No packets are sent to the passive endpoint before the active endpoint has 1811completed the handshake, hence so-called SYN floods with spoofed source 1812addresses will not reach the passive endpoint, as the sender can't complete the 1813handshake. 1814.Pp 1815The proxy is transparent to both endpoints, they each see a single 1816connection from/to the other endpoint. 1817.Xr pf 4 1818chooses random initial sequence numbers for both handshakes. 1819Once the handshakes are completed, the sequence number modulators 1820(see previous section) are used to translate further packets of the 1821connection. 1822Hence, 1823.Ar synproxy state 1824includes 1825.Ar modulate state 1826and 1827.Ar keep state . 1828.Pp 1829Rules with 1830.Ar synproxy 1831will not work if 1832.Xr pf 4 1833operates on a 1834.Xr bridge 4 . 1835.Pp 1836Example: 1837.Bd -literal -offset indent 1838pass in proto tcp from any to any port www flags S/SA synproxy state 1839.Ed 1840.Sh STATEFUL TRACKING OPTIONS 1841All three of 1842.Ar keep state , 1843.Ar modulate state 1844and 1845.Ar synproxy state 1846support the following options: 1847.Pp 1848.Bl -tag -width xxxx -compact 1849.It Ar max <number> 1850Limits the number of concurrent states the rule may create. 1851When this limit is reached, further packets matching the rule that would 1852create state are dropped, until existing states time out. 1853.It Ar no-sync 1854Prevent state changes for states created by this rule from appearing on the 1855.Xr pfsync 4 1856interface. 1857.It Ar <timeout> <seconds> 1858Changes the timeout values used for states created by this rule. 1859.Pp 1860When the 1861.Ar source-track 1862keyword is specified, the number of states per source IP is tracked. 1863The following limits can be set: 1864.Pp 1865.Bl -tag -width xxxx -compact 1866.It Ar max-src-nodes 1867Limits the maximum number of source addresses which can simultaneously 1868have state table entries. 1869.It Ar max-src-states 1870Limits the maximum number of simultaneous state entries that a single 1871source address can create with this rule. 1872.El 1873For a list of all valid timeout names, see 1874.Sx OPTIONS 1875above. 1876.Pp 1877Multiple options can be specified, separated by commas: 1878.Bd -literal 1879pass in proto tcp from any to any \e 1880 port www flags S/SA keep state \e 1881 (max 100, source-track rule, max-src-nodes 75, \e 1882 max-src-states 3, tcp.established 60, tcp.closing 5) 1883.Ed 1884.El 1885.Sh OPERATING SYSTEM FINGERPRINTING 1886Passive OS Fingerprinting is a mechanism to inspect nuances of a TCP 1887connection's initial SYN packet and guess at the host's operating system. 1888Unfortunately these nuances are easily spoofed by an attacker so the 1889fingerprint is not useful in making security decisions. 1890But the fingerprint is typically accurate enough to make policy decisions 1891upon. 1892.Pp 1893The fingerprints may be specified by operating system class, by 1894version, or by subtype/patchlevel. 1895The class of an operating system is typically the vender or genre 1896and would be OpenBSD for the 1897.Xr pf 4 1898firewall itself. 1899The version of the oldest available OpenBSD release on the main ftp site 1900would be 2.6 and the fingerprint would be written 1901.Pp 1902.Dl \&"OpenBSD 2.6\&" 1903.Pp 1904The subtype of an operating system is typically used to describe the 1905patchlevel if that patch led to changes in the TCP stack behavior. 1906In the case of OpenBSD, the only subtype is for a fingerprint that was 1907normalized by the 1908.Ar no-df 1909scrub option and would be specified as 1910.Pp 1911.Dl \&"OpenBSD 3.3 no-df\&" 1912.Pp 1913Fingerprints for most popular operating systems are provided by 1914.Xr pf.os 5 . 1915Once 1916.Xr pf 4 1917is running, a complete list of known operating system fingerprints may 1918be listed by running: 1919.Pp 1920.Dl # pfctl -so 1921.Pp 1922Filter rules can enforce policy at any level of operating system specification 1923assuming a fingerprint is present. 1924Policy could limit traffic to approved operating systems or even ban traffic 1925from hosts that aren't at the latest service pack. 1926.Pp 1927The 1928.Ar unknown 1929class can also be used as the fingerprint which will match packets for 1930which no operating system fingerprint is known. 1931.Pp 1932Examples: 1933.Bd -literal -offset indent 1934pass out proto tcp from any os OpenBSD keep state 1935block out proto tcp from any os Doors 1936block out proto tcp from any os "Doors PT" 1937block out proto tcp from any os "Doors PT SP3" 1938block out from any os "unknown" 1939pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0" keep state 1940.Ed 1941.Pp 1942Operating system fingerprinting is limited only to the TCP SYN packet. 1943This means that it will not work on other protocols and will not match 1944a currently established connection. 1945.Pp 1946Caveat: operating system fingerprints are occasionally wrong. 1947There are three problems: an attacker can trivially craft his packets to 1948appear as any operating system he chooses; 1949an operating system patch could change the stack behavior and no fingerprints 1950will match it until the database is updated; 1951and multiple operating systems may have the same fingerprint. 1952.Sh BLOCKING SPOOFED TRAFFIC 1953"Spoofing" is the faking of IP addresses, typically for malicious 1954purposes. 1955The 1956.Ar antispoof 1957directive expands to a set of filter rules which will block all 1958traffic with a source IP from the network(s) directly connected 1959to the specified interface(s) from entering the system through 1960any other interface. 1961.Pp 1962For example, the line 1963.Bd -literal -offset indent 1964antispoof for lo0 1965.Ed 1966.Pp 1967expands to 1968.Bd -literal -offset indent 1969block drop in on ! lo0 inet from 127.0.0.1/8 to any 1970block drop in on ! lo0 inet6 from ::1 to any 1971.Ed 1972.Pp 1973For non-loopback interfaces, there are additional rules to block incoming 1974packets with a source IP address identical to the interface's IP(s). 1975For example, assuming the interface wi0 had an IP address of 10.0.0.1 and a 1976netmask of 255.255.255.0, 1977the line 1978.Bd -literal -offset indent 1979antispoof for wi0 inet 1980.Ed 1981.Pp 1982expands to 1983.Bd -literal -offset indent 1984block drop in on ! wi0 inet from 10.0.0.0/24 to any 1985block drop in inet from 10.0.0.1 to any 1986.Ed 1987.Pp 1988Caveat: Rules created by the 1989.Ar antispoof 1990directive interfere with packets sent over loopback interfaces 1991to local addresses. 1992One should pass these explicitly. 1993.Sh FRAGMENT HANDLING 1994The size of IP datagrams (packets) can be significantly larger than the 1995maximum transmission unit (MTU) of the network. 1996In cases when it is necessary or more efficient to send such large packets, 1997the large packet will be fragmented into many smaller packets that will each 1998fit onto the wire. 1999Unfortunately for a firewalling device, only the first logical fragment will 2000contain the necessary header information for the subprotocol that allows 2001.Xr pf 4 2002to filter on things such as TCP ports or to perform NAT. 2003.Pp 2004Besides the use of 2005.Ar scrub 2006rules as described in 2007.Sx TRAFFIC NORMALIZATION 2008above, there are three options for handling fragments in the packet filter. 2009.Pp 2010One alternative is to filter individual fragments with filter rules. 2011If no 2012.Ar scrub 2013rule applies to a fragment, it is passed to the filter. 2014Filter rules with matching IP header parameters decide whether the 2015fragment is passed or blocked, in the same way as complete packets 2016are filtered. 2017Without reassembly, fragments can only be filtered based on IP header 2018fields (source/destination address, protocol), since subprotocol header 2019fields are not available (TCP/UDP port numbers, ICMP code/type). 2020The 2021.Ar fragment 2022option can be used to restrict filter rules to apply only to 2023fragments, but not complete packets. 2024Filter rules without the 2025.Ar fragment 2026option still apply to fragments, if they only specify IP header fields. 2027For instance, the rule 2028.Bd -literal -offset indent 2029pass in proto tcp from any to any port 80 2030.Ed 2031.Pp 2032never applies to a fragment, even if the fragment is part of a TCP 2033packet with destination port 80, because without reassembly this information 2034is not available for each fragment. 2035This also means that fragments cannot create new or match existing 2036state table entries, which makes stateful filtering and address 2037translation (NAT, redirection) for fragments impossible. 2038.Pp 2039It's also possible to reassemble only certain fragments by specifying 2040source or destination addresses or protocols as parameters in 2041.Ar scrub 2042rules. 2043.Pp 2044In most cases, the benefits of reassembly outweigh the additional 2045memory cost, and it's recommended to use 2046.Ar scrub 2047rules to reassemble 2048all fragments via the 2049.Ar fragment reassemble 2050modifier. 2051.Pp 2052The memory allocated for fragment caching can be limited using 2053.Xr pfctl 8 . 2054Once this limit is reached, fragments that would have to be cached 2055are dropped until other entries time out. 2056The timeout value can also be adjusted. 2057.Pp 2058Currently, only IPv4 fragments are supported and IPv6 fragments 2059are blocked unconditionally. 2060.Sh ANCHORS AND NAMED RULESETS 2061Besides the main ruleset, 2062.Xr pfctl 8 2063can load named rulesets into 2064.Ar anchor 2065attachment points. 2066An 2067.Ar anchor 2068contains a list of named rulesets. 2069An 2070.Ar anchor 2071has a name which specifies where 2072.Xr pfctl 8 2073can be used to attach sub-rulesets. 2074A named ruleset contains filter and translation rules, like the 2075main ruleset. 2076The main ruleset can reference 2077.Ar anchor 2078attachment points 2079using the following kinds 2080of rules: 2081.Bl -tag -width xxxx 2082.It Ar nat-anchor <name> 2083Evaluates the 2084.Ar nat 2085rules of all named rulesets in the specified 2086.Ar anchor . 2087.It Ar rdr-anchor <name> 2088Evaluates the 2089.Ar rdr 2090rules of all named rulesets in the specified 2091.Ar anchor . 2092.It Ar binat-anchor <name> 2093Evaluates the 2094.Ar binat 2095rules of all named rulesets in the specified 2096.Ar anchor . 2097.It Ar anchor <name> 2098Evaluates the filter rules of all named rulesets in the specified 2099.Ar anchor . 2100.It Ar load anchor <name>:<ruleset> from <file> 2101Loads the rules from the specified file into the named 2102ruleset 2103.Ar <ruleset> 2104attached to the anchor 2105.Ar <name> . 2106.El 2107.Pp 2108When evaluation of the main ruleset reaches an 2109.Ar anchor 2110rule, 2111.Xr pf 4 2112will proceed to evaluate all rules specified in the 2113named rulesets attached to that 2114.Ar anchor . 2115.Pp 2116Matching filter rules in named rulesets with the 2117.Ar quick 2118option and matching translation rules are final and abort the 2119evaluation of both the rules in the 2120.Ar anchor 2121and the main ruleset. 2122.Pp 2123Only the main ruleset can contain 2124.Ar anchor 2125rules. 2126.Pp 2127When an 2128.Ar anchor 2129contains more than one named ruleset, they are evaluated 2130in the alphabetical order of their names. 2131.Pp 2132Rules may contain 2133.Ar anchor 2134attachment points which do not contain any rules when the main ruleset 2135is loaded, and later such named rulesets can be manipulated through 2136.Xr pfctl 8 2137without reloading the main ruleset. 2138For example, 2139.Bd -literal -offset indent 2140ext_if = \&"kue0\&" 2141block on $ext_if all 2142anchor spam 2143pass out on $ext_if all keep state 2144pass in on $ext_if proto tcp from any \e 2145 to $ext_if port smtp keep state 2146.Ed 2147.Pp 2148blocks all packets on the external interface by default, then evaluates 2149all rulesets in the 2150.Ar anchor 2151named "spam", and finally passes all outgoing connections and 2152incoming connections to port 25. 2153.Bd -literal -offset indent 2154# echo \&"block in quick from 1.2.3.4 to any\&" \&| \e 2155 pfctl -a spam:manual -f - 2156.Ed 2157.Pp 2158loads a single ruleset containing a single rule into the 2159.Ar anchor , 2160which blocks all packets from a specific address. 2161.Pp 2162The named ruleset can also be populated by adding a 2163.Ar load anchor 2164rule after the 2165.Ar anchor 2166rule: 2167.Bd -literal -offset indent 2168anchor spam 2169load anchor spam:manual from "/etc/pf-spam.conf" 2170.Ed 2171.Pp 2172When 2173.Xr pfctl 8 2174loads 2175.Nm pf.conf , 2176it will also load all the rules from the file 2177.Pa /etc/pf-spam.conf 2178into the named ruleset. 2179.Pp 2180Optionally, 2181.Ar anchor 2182rules can specify the parameter's 2183direction, interface, address family, protocol and source/destination 2184address/port 2185using the same syntax as filter rules. 2186When parameters are used, the 2187.Ar anchor 2188rule is only evaluated for matching packets. 2189This allows conditional evaluation of named rulesets, like: 2190.Bd -literal -offset indent 2191block on $ext_if all 2192anchor spam proto tcp from any to any port smtp 2193pass out on $ext_if all keep state 2194pass in on $ext_if proto tcp from any to $ext_if port smtp keep state 2195.Ed 2196.Pp 2197The rules inside 2198.Ar anchor 2199spam are only evaluated for 2200.Ar tcp 2201packets with destination port 25. 2202Hence, 2203.Bd -literal -offset indent 2204# echo \&"block in quick from 1.2.3.4 to any" \&| \e 2205 pfctl -a spam:manual -f - 2206.Ed 2207.Pp 2208will only block connections from 1.2.3.4 to port 25. 2209.Sh TRANSLATION EXAMPLES 2210This example maps incoming requests on port 80 to port 8080, on 2211which a daemon is running (because, for example, it is not run as root, 2212and therefore lacks permission to bind to port 80). 2213.Bd -literal 2214# use a macro for the interface name, so it can be changed easily 2215ext_if = \&"ne3\&" 2216 2217# map daemon on 8080 to appear to be on 80 2218rdr on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 port 8080 2219.Ed 2220.Pp 2221If the 2222.Ar pass 2223modifier is given, packets matching the translation rule are passed without 2224inspecting the filter rules: 2225.Bd -literal 2226rdr pass on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 \e 2227 port 8080 2228.Ed 2229.Pp 2230In the example below, vlan12 is configured as 192.168.168.1; 2231the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111 2232when they are going out any interface except vlan12. 2233This has the net effect of making traffic from the 192.168.168.0/24 2234network appear as though it is the Internet routable address 2235204.92.77.111 to nodes behind any interface on the router except 2236for the nodes on vlan12. 2237(Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.) 2238.Bd -literal 2239nat on ! vlan12 from 192.168.168.0/24 to any -> 204.92.77.111 2240.Ed 2241.Pp 2242In the example below, the machine sits between a fake internal 144.19.74.* 2243network, and a routable external IP of 204.92.77.100. 2244The 2245.Ar no nat 2246rule excludes protocol AH from being translated. 2247.Bd -literal 2248# NO NAT 2249no nat on $ext_if proto ah from 144.19.74.0/24 to any 2250nat on $ext_if from 144.19.74.0/24 to any -> 204.92.77.100 2251.Ed 2252.Pp 2253In the example below, packets bound for one specific server, as well as those 2254generated by the sysadmins are not proxied; all other connections are. 2255.Bd -literal 2256# NO RDR 2257no rdr on $int_if proto { tcp, udp } from any to $server port 80 2258no rdr on $int_if proto { tcp, udp } from $sysadmins to any port 80 2259rdr on $int_if proto { tcp, udp } from any to any port 80 -> 127.0.0.1 \e 2260 port 80 2261.Ed 2262.Pp 2263This longer example uses both a NAT and a redirection. 2264The external interface has the address 157.161.48.183. 2265On the internal interface, we are running 2266.Xr ftp-proxy 8 , 2267listening for outbound ftp sessions captured to port 8021. 2268.Bd -literal 2269# NAT 2270# Translate outgoing packets' source addresses (any protocol). 2271# In this case, any address but the gateway's external address is mapped. 2272nat on $ext_if inet from ! ($ext_if) to any -> ($ext_if) 2273 2274# NAT PROXYING 2275# Map outgoing packets' source port to an assigned proxy port instead of 2276# an arbitrary port. 2277# In this case, proxy outgoing isakmp with port 500 on the gateway. 2278nat on $ext_if inet proto udp from any port = isakmp to any -> ($ext_if) \e 2279 port 500 2280 2281# BINAT 2282# Translate outgoing packets' source address (any protocol). 2283# Translate incoming packets' destination address to an internal machine 2284# (bidirectional). 2285binat on $ext_if from 10.1.2.150 to any -> ($ext_if) 2286 2287# RDR 2288# Translate incoming packets' destination addresses. 2289# As an example, redirect a TCP and UDP port to an internal machine. 2290rdr on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e 2291 -> 10.1.2.151 port 22 2292rdr on $ext_if inet proto udp from any to ($ext_if) port 8080 \e 2293 -> 10.1.2.151 port 53 2294 2295# RDR 2296# Translate outgoing ftp control connections to send them to localhost 2297# for proxying with ftp-proxy(8) running on port 8021. 2298rdr on $int_if proto tcp from any to any port 21 -> 127.0.0.1 port 8021 2299.Ed 2300.Pp 2301In this example, a NAT gateway is set up to translate internal addresses 2302using a pool of public addresses (192.0.2.16/28) and to redirect 2303incoming web server connections to a group of web servers on the internal 2304network. 2305.Bd -literal 2306# NAT LOAD BALANCE 2307# Translate outgoing packets' source addresses using an address pool. 2308# A given source address is always translated to the same pool address by 2309# using the source-hash keyword. 2310nat on $ext_if inet from any to any -> 192.0.2.16/28 source-hash 2311 2312# RDR ROUND ROBIN 2313# Translate incoming web server connections to a group of web servers on 2314# the internal network. 2315rdr on $ext_if proto tcp from any to any port 80 \e 2316 -> { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin 2317.Ed 2318.Sh FILTER EXAMPLES 2319.Bd -literal 2320# The external interface is kue0 2321# (157.161.48.183, the only routable address) 2322# and the private network is 10.0.0.0/8, for which we are doing NAT. 2323 2324# use a macro for the interface name, so it can be changed easily 2325ext_if = \&"kue0\&" 2326 2327# normalize all incoming traffic 2328scrub in on $ext_if all fragment reassemble 2329 2330# block and log everything by default 2331block return log on $ext_if all 2332 2333# block anything coming from source we have no back routes for 2334block in from no-route to any 2335 2336# block and log outgoing packets that do not have our address as source, 2337# they are either spoofed or something is misconfigured (NAT disabled, 2338# for instance), we want to be nice and do not send out garbage. 2339block out log quick on $ext_if from ! 157.161.48.183 to any 2340 2341# silently drop broadcasts (cable modem noise) 2342block in quick on $ext_if from any to 255.255.255.255 2343 2344# block and log incoming packets from reserved address space and invalid 2345# addresses, they are either spoofed or misconfigured, we cannot reply to 2346# them anyway (hence, no return-rst). 2347block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e 2348 192.168.0.0/16, 255.255.255.255/32 } to any 2349 2350# ICMP 2351 2352# pass out/in certain ICMP queries and keep state (ping) 2353# state matching is done on host addresses and ICMP id (not type/code), 2354# so replies (like 0/0 for 8/0) will match queries 2355# ICMP error messages (which always refer to a TCP/UDP packet) are 2356# handled by the TCP/UDP states 2357pass on $ext_if inet proto icmp all icmp-type 8 code 0 keep state 2358 2359# UDP 2360 2361# pass out all UDP connections and keep state 2362pass out on $ext_if proto udp all keep state 2363 2364# pass in certain UDP connections and keep state (DNS) 2365pass in on $ext_if proto udp from any to any port domain keep state 2366 2367# TCP 2368 2369# pass out all TCP connections and modulate state 2370pass out on $ext_if proto tcp all modulate state 2371 2372# pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT) 2373pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e 2374 auth } flags S/SA keep state 2375 2376# pass in data mode connections for ftp-proxy running on this host. 2377# (see ftp-proxy(8) for details) 2378pass in on $ext_if proto tcp from any to 157.161.48.183 port >= 49152 \e 2379 flags S/SA keep state 2380 2381# Do not allow Windows 9x SMTP connections since they are typically 2382# a viral worm. Alternately we could limit these OSes to 1 connection each. 2383block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e 2384 to any port smtp 2385 2386# Packet Tagging 2387 2388# three interfaces: $int_if, $ext_if, and $wifi_if (wireless). NAT is 2389# being done on $ext_if for all outgoing packets. tag packets in on 2390# $int_if and pass those tagged packets out on $ext_if. all other 2391# outgoing packets (i.e., packets from the wireless network) are only 2392# permitted to access port 80. 2393 2394pass in on $int_if from any to any tag INTNET keep state 2395pass in on $wifi_if from any to any keep state 2396 2397block out on $ext_if from any to any 2398pass out quick on $ext_if tagged INTNET keep state 2399pass out on $ext_if from any to any port 80 keep state 2400 2401# tag incoming packets as they are redirected to spamd(8). use the tag 2402# to pass those packets through the packet filter. 2403 2404rdr on $ext_if inet proto tcp from <spammers> to port smtp \e 2405 tag SPAMD -> 127.0.0.1 port spamd 2406 2407block in on $ext_if 2408pass in on $ext_if inet proto tcp tagged SPAMD keep state 2409.Ed 2410.Sh GRAMMAR 2411Syntax for 2412.Nm 2413in BNF: 2414.Bd -literal 2415line = ( option | pf-rule | nat-rule | binat-rule | rdr-rule | 2416 antispoof-rule | altq-rule | queue-rule | anchor-rule | 2417 trans-anchors | load-anchors | table-rule ) 2418 2419option = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] | 2420 [ "optimization" [ "default" | "normal" | 2421 "high-latency" | "satellite" | 2422 "aggressive" | "conservative" ] ] 2423 [ "limit" ( limit-item | "{" limit-list "}" ) ] | 2424 [ "loginterface" ( interface-name | "none" ) ] | 2425 [ "block-policy" ( "drop" | "return" ) ] | 2426 [ "state-policy" ( "if-bound" | "group-bound" | 2427 "floating" ) ] 2428 [ "require-order" ( "yes" | "no" ) ] 2429 [ "fingerprints" filename ] | 2430 [ "debug" ( "none" | "urgent" | "misc" | "loud" ) ] ) 2431 2432pf-rule = action [ ( "in" | "out" ) ] 2433 [ "log" | "log-all" ] [ "quick" ] 2434 [ "on" ifspec ] [ route ] [ af ] [ protospec ] 2435 hosts [ filteropt-list ] 2436 2437filteropt-list = filteropt-list filteropt | filteropt 2438filteropt = user | group | flags | icmp-type | icmp6-type | tos | 2439 ( "keep" | "modulate" | "synproxy" ) "state" 2440 [ "(" state-opts ")" ] | 2441 "fragment" | "no-df" | "min-ttl" number | 2442 "max-mss" number | "random-id" | "reassemble tcp" | 2443 fragmentation | "allow-opts" | 2444 "label" string | "tag" string | [ ! ] "tagged" string 2445 "queue" ( string | "(" string [ [ "," ] string ] ")" ) 2446 2447nat-rule = [ "no" ] "nat" [ "pass" ] [ "on" ifspec ] [ af ] 2448 [ protospec ] hosts [ "tag" string ] 2449 [ "->" ( redirhost | "{" redirhost-list "}" ) 2450 [ portspec ] [ pooltype ] [ "static-port" ] ] 2451 2452binat-rule = [ "no" ] "binat" [ "pass" ] [ "on" interface-name ] 2453 [ af ] [ "proto" ( proto-name | proto-number ) ] 2454 "from" address [ "/" mask-bits ] "to" ipspec 2455 [ "tag" string ] 2456 [ "->" address [ "/" mask-bits ] ] 2457 2458rdr-rule = [ "no" ] "rdr" [ "pass" ] [ "on" ifspec ] [ af ] 2459 [ protospec ] hosts [ "tag" string ] 2460 [ "->" ( redirhost | "{" redirhost-list "}" ) 2461 [ portspec ] [ pooltype ] ] 2462 2463antispoof-rule = "antispoof" [ "log" ] [ "quick" ] 2464 "for" ( interface-name | "{" interface-list "}" ) 2465 [ af ] [ "label" string ] 2466 2467table-rule = "table" "<" string ">" [ tableopts-list ] 2468tableopts-list = tableopts-list tableopts | tableopts 2469tableopts = "persist" | "const" | "file" string | 2470 "{" [ tableaddr-list ] "}" 2471tableaddr-list = tableaddr-list [ "," ] tableaddr-spec | tableaddr-spec 2472tableaddr-spec = [ "!" ] tableaddr [ "/" mask-bits ] 2473tableaddr = hostname | ipv4-dotted-quad | ipv6-coloned-hex | 2474 interface-name | "self" 2475 2476altq-rule = "altq on" interface-name queueopts-list 2477 "queue" subqueue 2478queue-rule = "queue" string [ "on" interface-name ] queueopts-list 2479 subqueue 2480 2481anchor-rule = "anchor" string [ ( "in" | "out" ) ] [ "on" ifspec ] 2482 [ af ] [ "proto" ] [ protospec ] [ hosts ] 2483 2484trans-anchors = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string 2485 [ "on" ifspec ] [ af ] [ "proto" ] [ protospec ] [ hosts ] 2486 2487load-anchor = "load anchor" anchorname:rulesetname "from" filename 2488 2489queueopts-list = queueopts-list queueopts | queueopts 2490queueopts = [ "bandwidth" bandwidth-spec ] | 2491 [ "qlimit" number ] | [ "tbrsize" number ] | 2492 [ "priority" number ] | [ schedulers ] 2493schedulers = ( cbq-def | priq-def | hfsc-def ) 2494bandwidth-spec = "number" ( "b" | "Kb" | "Mb" | "Gb" | "%" ) 2495 2496action = "pass" | "block" [ return ] | "scrub" 2497return = "drop" | "return" | "return-rst" [ "( ttl" number ")" ] | 2498 "return-icmp" [ "(" icmpcode ["," icmp6code ] ")" ] | 2499 "return-icmp6" [ "(" icmp6code ")" ] 2500icmpcode = ( icmp-code-name | icmp-code-number ) 2501icmp6code = ( icmp6-code-name | icmp6-code-number ) 2502 2503ifspec = ( [ "!" ] interface-name ) | "{" interface-list "}" 2504interface-list = [ "!" ] interface-name [ [ "," ] interface-list ] 2505route = "fastroute" | 2506 ( "route-to" | "reply-to" | "dup-to" ) 2507 ( routehost | "{" routehost-list "}" ) 2508 [ pooltype ] 2509af = "inet" | "inet6" 2510 2511protospec = "proto" ( proto-name | proto-number | 2512 "{" proto-list "}" ) 2513proto-list = ( proto-name | proto-number ) [ [ "," ] proto-list ] 2514 2515hosts = "all" | 2516 "from" ( "any" | "no-route" | "self" | host | 2517 "{" host-list "}" ) [ port ] [ os ] 2518 "to" ( "any" | "no-route" | "self" | host | 2519 "{" host-list "}" ) [ port ] 2520 2521ipspec = "any" | host | "{" host-list "}" 2522host = [ "!" ] ( address [ "/" mask-bits ] | "<" string ">" ) 2523redirhost = address [ "/" mask-bits ] 2524routehost = ( interface-name [ address [ "/" mask-bits ] ] ) 2525address = ( interface-name | "(" interface-name ")" | hostname | 2526 ipv4-dotted-quad | ipv6-coloned-hex ) 2527host-list = host [ [ "," ] host-list ] 2528redirhost-list = redirhost [ [ "," ] redirhost-list ] 2529routehost-list = routehost [ [ "," ] routehost-list ] 2530 2531port = "port" ( unary-op | binary-op | "{" op-list "}" ) 2532portspec = "port" ( number | name ) [ ":" ( "*" | number | name ) ] 2533os = "os" ( os-name | "{" os-list "}" ) 2534user = "user" ( unary-op | binary-op | "{" op-list "}" ) 2535group = "group" ( unary-op | binary-op | "{" op-list "}" ) 2536 2537unary-op = [ "=" | "!=" | "<" | "<=" | ">" | ">=" ] 2538 ( name | number ) 2539binary-op = number ( "<>" | "><" | ":" ) number 2540op-list = ( unary-op | binary-op ) [ [ "," ] op-list ] 2541 2542os-name = operating-system-name 2543os-list = os-name [ [ "," ] os-list ] 2544 2545flags = "flags" [ flag-set ] "/" flag-set 2546flag-set = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ] 2547 [ "W" ] 2548 2549icmp-type = "icmp-type" ( icmp-type-code | "{" icmp-list "}" ) 2550icmp6-type = "icmp6-type" ( icmp-type-code | "{" icmp-list "}" ) 2551icmp-type-code = ( icmp-type-name | icmp-type-number ) 2552 [ "code" ( icmp-code-name | icmp-code-number ) ] 2553icmp-list = icmp-type-code [ [ "," ] icmp-list ] 2554 2555tos = "tos" ( "lowdelay" | "throughput" | "reliability" | 2556 [ "0x" ] number ) 2557 2558state-opts = state-opt [ [ "," ] state-opts ] 2559state-opt = ( "max" number | "no-sync" | timeout | 2560 "source-track" [ ( "rule" | "global" ) ] | 2561 "max-src-nodes" number | "max-src-states" number | 2562 "if-bound" | "group-bound" | "floating" ) 2563 2564fragmentation = [ "fragment reassemble" | "fragment crop" | 2565 "fragment drop-ovl" ] 2566 2567timeout-list = timeout [ [ "," ] timeout-list ] 2568timeout = ( "tcp.first" | "tcp.opening" | "tcp.established" | 2569 "tcp.closing" | "tcp.finwait" | "tcp.closed" | 2570 "udp.first" | "udp.single" | "udp.multiple" | 2571 "icmp.first" | "icmp.error" | 2572 "other.first" | "other.single" | "other.multiple" | 2573 "frag" | "interval" | "src.track" | 2574 "adaptive.start" | "adaptive.end" ) number 2575 2576limit-list = limit-item [ [ "," ] limit-list ] 2577limit-item = ( "states" | "frags" | "src-nodes" ) number 2578 2579pooltype = ( "bitmask" | "random" | 2580 "source-hash" [ ( hex-key | string-key ) ] | 2581 "round-robin" ) [ sticky-address ] 2582 2583subqueue = string | "{" queue-list "}" 2584queue-list = string [ [ "," ] string ] 2585cbq-def = "cbq" [ "(" cbq-opt [ [ "," ] cbq-opt ] ")" ] 2586priq-def = "priq" [ "(" priq-opt [ [ "," ] priq-opt ] ")" ] 2587hfsc-def = "hfsc" [ "(" hfsc-opt [ [ "," ] hfsc-opt ] ")" ] 2588cbq-opt = ( "default" | "borrow" | "red" | "ecn" | "rio" ) 2589priq-opt = ( "default" | "red" | "ecn" | "rio" ) 2590hfsc-opt = ( "default" | "red" | "ecn" | "rio" | 2591 linkshare-sc | realtime-sc | upperlimit-sc ) 2592linkshare-sc = "linkshare" sc-spec 2593realtime-sc = "realtime" sc-spec 2594upperlimit-sc = "upperlimit" sc-spec 2595sc-spec = ( bandwidth-spec | 2596 "(" bandwidth-spec number bandwidth-spec ")" ) 2597.Ed 2598.Sh FILES
|