hint that the tcp timeout values can be adjusted collectively via
"set optimization"; from jesper wallin

ok bluhm

document tcp.tsdiff; from jesper wallin
ok bluhm

Improve "once" bits

- use imperative tense in the pf.conf(5) "once" part
- leave printing implementation details to pfctl(8)'s "-s rules" part
- use more markup
- debug mode also prints expired rules

OK jmc sashan

tweak the "once" text; ok sashan

simplify expiration of 'once' rules.
let packet to mark 'once' rule as expired. The rule
will be removed by pfctl(8) when rules are updated.

OK kn@

document limit-item "anchors"; from martin vahlensieck

while here, rework the "set limit" section:

- use a simple list
- add some missing defaults and limit-item

mbuhl helped fill in some of the blanks
ok kn

rework the text on mtu and mss, according to some notes from sthen;
ok sthen

Mention in the "proto icmp" section that standard stateful rules (i.e. the
default type of PF rule) don't allow ICMP responses unless they match an
existing state - tweak "keep state (sloppy)" to suggest from the first
sentence of the paragraph that it affects more than TCP. ok sashan@ bluhm@

pf.conf(5) should mention impact of sloppy state handling on ICMP

OK @bluhm

man pages: add missing commas between subordinate and main clauses

jmc@ dislikes a comma before "then" in a conditional, so leave those
untouched.

ok jmc@

better help for getting addresses for dgrams received with divert-to.

getsockname is for connected sockets, not all sockets. dgrams need
to use some setsockopt stuff and cmsgs to get packet info like that.

suggested by K R on bugs@

Avoid gendered language in man pages when not referring to a specific
person. Rewrite or use singular they.

ok thfr@ sthen@ daniel@ ian@ job@ kmos@ jcs@ ratchov@ phessler@ and
others I'm likely missing on an earlier version.
feedback tj@, feedback and ok jmc@

make 'set skip on ...' in pf.conf dynamic

This is an old issue in pf(4): whenever new interface appears
in IP stack, we must reload pf.conf to apply 'set skip on ...'
to newly plumbed network interfaces. Time has come to fix it.
The idea is to also create pfi_kif for interfaces, which are
referred by 'set skip on ...'. Such pfi_kif instances are
created/destroyed by pfi_set_flags()/pfi_clear_flags().

claudio@ dragged my attention to this in Gouveia. Also his
feedback helped me to put change into shape.

OK claudio@

Multiply the number of states in the example adaptive timeout calculation
by 10 so it works with the numbers in the config, which were previously
multiplied.

ok dlg@

pf.conf.5: improve reply-to documentation

reply-to uses addresses, not interfaces anymore since
https://marc.info/?l=openbsd-cvs&m=161213948819452&w=2

make it clearer that reply-to allows for symmetric routing enforcement,
eg replying via a specific gateway when having multiple paths.

wording from sthen@, vastly improving my initial suggestion.
ok jmc@ dlg@

Markup optional ICMP/ICMP6 codes as such

Only icmp(4)/icmp6(4) types are required for `icmp-type'/`icmp6-type' rules
while codes are optional.

From Martin Vahlensieck < openbsd at academicsolutions dot ch >, thanks!

change route-to so it sends packets to IPs instead of interfaces.

this is a significant (and breaking) reworking of the policy based
routing that pf can do. the intention is to make it as easy as
nat/rdr to use, and more robust when it's operating.

the main reasons for this change are:

- route-to, reply-to, and dup-to do not work with pfsync

this is because the information about where to route-to is stored in
rules, and it is hard to have a ruleset synced between firewalls,
and impossible to have them synced 100% of the time.

- i can make my boxes panic in certain situations using route-to

yeah...

- the configuration and syntax for route-to rules are confusing.

the argument to route-to and co is an interace name with an optional
ip address. there are several problems with this. one is that people
tend to think about routing as sending packets to peers by their
address, not by the interface they're reachable on. another is that
we currently have no way to synchronise interface topology information
between firewalls, so using an interface to say where packets go
means we can't do failover of these states with pfsync. another
is that a change in routing topology means a host may become
reachable over a different interface. tying routing policy to
interfaces gets in the way of failover and load balancing.

this change does the following:

- stores the route info in the state instead of the pf rule

this allows route-to to keep working when the ruleset changes, and
allows route-to info to be sent over pfsync. there's enough spare bits
in pfsync messages that the protocol doesnt break.

the caveat is that route-to becomes tied to pass rules that create
state, like rdr-to and nat-to.

- the argument to route-to etc is a destination ip address

it's not limited to a next-hop address (thought a next-hop can be a
destination address). this allows for the failover and load balancing
referred to above.

- deprecates the address@interface host syntax in pfctl

because routing is done entirely by IPs, the interface is derived from
the route lookup, not pf. any attempt to use the @interface syntax
will fail now in all contexts.

there's enthusiasm from proctor@ jmatthew@ and others
ok sashan@ bluhm@

synproxy should be processing incoming SYN packets only.
issue noticed by sthen@. fix discussed with bluhm@ and procter@

OK bluhm@, kn@, procter@

briefly mention /etc/examples/ in the FILES section of all the
manual pages that document the corresponding configuration files;
OK jmc@, and general direction discussed with many

- pf.conf(5) should clearly state range match operator ':'
does not work for uid/gid.

OK @kn, OK @sthen

Fix swapped default values of adaptive.start and adaptive.end timeouts

While here, enlist start before end to restore intuitive order.

Spotted by someone on IRC who's name I cannot recall, sorry.
OK sashan

mop up for the pcap.3 rename;
help/ok deraadt

use proper crossreferences

update to PF pfctl(8) and pf.conf(5) manpages
great input by Ingo, Jason and Klemens

OK schwarze@, OK kn@, OK jmc@

sticky-address is working with source-hash.

ok deraadt

syncookies never is the default; from paul de weerd
ok henning

where we were showing "set limit states 10000" make that 100k as well,
and adjust adaptive.start/end as well (just like in the code)

document set delay

a little more adjustment, after discussing with henning;

tweak previous; ok henning

give jmc another chance to "fix previous" - document syncookies
(thanks jmc!)

tweak previous;

add a generic packet rate matching filter. allows things like
pass in proto icmp max-pkt-rate 100/10
all packets matching the rule in the direction the state was created are
taken into consideration (typically: requests, but not replies).
Just like with the other max-*, the rule stops matching if the maximum is
reached, so in typical scenarios the default block rule would kick in then.
with input from Holger Mikolon
ok mikeb

tweak previous;

Integrate the description of flow queues into the main body of text

* Clarify that filter rules are evaluated once per packet and interface,
not only once per packet.
* Clarify that the syntax anchor "name" { ... } both loads and
evaluates the anchor, rather than merely loading it.
Triggered by questions from Benedikt Neuffer <bene at usta dot de>.
OK mikeb@

clarify set prio: the second prio given applies to
1) TCP ACKs
2) packets with ToS=lowdelay
and not TCP ACKs that have ToS=lowdelay
confusion discovered during bsdcan pf tutorial

clarify that translations happen immediately on match rules, not generally
Tony Gong <tony.y.gong at gmail>

Block IPv6 packets in pf(4) that have hop-by-hop options header or
destination options header. Such packets can be passed by adding
"allow-opts" to the rule. So IPv6 options are handled like their
counterpart in IPv4 now.
tested by benno@; OK henning@

some tweaks to the QUEUEING section;
from mikeb and myself

replace tabs with spaces, for consistency, in the BNF display;
from michal mazurek

better describe "!";
from michal mazurek, tweaked a bit by myself

tweak the bandwidth description; help/ok mikeb

tweak previous; ok mikeb

Document the new flow queue specification

With input and OK sthen

"hosts" is optional; from matthew martin
ok henning

modfier -> modifier

From Dimitris Papastamos.

diff from jesper wallin to remove commas in one of the queue examples;
since the comma is optional i chose to remove them because:

- within the block it looks more consistent
- less to type
- the bnf doesn;t even appear to show the commas (not that i can read bnf)
- i prefer it without commas

Specify "to" addresses in one of the examples that shows use of af-to for
inet6->inet. Without this, local network traffic (including neighbour
discovery etc) will also get translated. From Peter J. Philipp, with a
tweak to break long lines.

make it clearer that log options require ();
requested by janne johansson

ok henning

unhphenate the world: re-order -> reorder
sthen does not object

remove long deprecated "set debug "none|urgent|misc|loud" levels in
pf.conf. Change this before upgrade or pf.conf won't load.
florian@ henning@ phessler@ jung@

we need an unbreakable space in O(log2 n).

ok jmc@

adjust macro usage to the usual conventions

improve indentation in list block.

ok jmc@

fix some spelling messes.

ok jmc@

Avoid .Ns right after .Pf, it's pointless.
In some cases, do additional cleanup in the immediate vicinity.

after some discussion with henning, document the various log options as
one section; some text was altered to make it read better;

ok henning

Don't use greater-equal/less-equal symbols where "<="/">=" are intended.

Also, clean up some usage of predefined strings (which are discouraged by
mandoc_char(7) for portability reasons) and improve spacing in
hostapd.conf(5).

ok schwarze@

a shot at documenting the changed log(matches) semantics

document matching on prio

properly handle opening parentheses, correctly quote vertical bars,
and do not use the legacy predefined string \*(Ba

Support source-hash and random with tables and dynifs; not just pools.
This finally allows to use source-hash for dynamic loadbalancing, eg.
"rdr-to <hosts> source-hash", instead of just round-robin and least-states.

An older pre-siphash version of this diff was tested by many people.

OK tedu@ benno@

Add GRAMMAR to list of sections.

ok jmc@, deraadt@ (begrudgingly)

tweak previous;

prio is meaningless when bandwidth shaping is in use, fix example
noticed by Marko Cupa�� <marko.cupac at mimar dot rs>

obvious .Pa fixes; found with mandocdb(8)

document how any matches any non-loopback interface, ok benno

document !received-on, ok dlg benno

Using random-id is recommended in combination with no-df to ensure
unique IP identifiers.

ok henning@

Document that the "user" socket check is not reliable with wildcard
listeners. Update the example to reflect this.

Deprecate usage of user "unknown" too, same reason.

Noted by Maxim Khitrov on bugs

ok henning, jmc

document better how priorities work, and fix an example;
diff originally from timo myyra, but tweaked according to henning
(equal prio packets are fifo, not round-robin);

ok henning

i. e. -> i.e.

explicitely->explicitly

document new queueing. with lots of help from jmc. glanced over by many,
ok phessler sthen

fix range for assigned ports managed by the IANA (see RFC 1700).

ok sthen@

Make it clear that the default implicit 'pass' rule does not create state,
make sense to deraadt@, ok/wording tweak from mikeb.

move the "set queue" block a bit down so that
a) things are in alphabetical order again
b) the "described below" in the set prio section actually refers to a block
of text below and not above it... ok jsing

for consistency with prio etc, the queue assignment really belongs
into the set block. so make pfctl accept, print and the manpage document
. match set queue foo
instead of
. match queue foo
but keep accepting the old way without the explicit set.
ok bob, man jmc

Disallow tables and interface address pools for rdr-to, nat-to and
route-to with any other scheduling algorithms than round-robin or
least-states. Before this change, pfctl accepted and loaded invalid
address pools, eg. "rdr-to <table> source-hash", but it is not
supported by the kernel and was silently ignored in operation.

Also clarify the manpage a bit by mentioning that tables are only
valid with round-robin or least-states.

ok zinke@

remove unneccessary macro;

Lower pf frags limit to not risk running out of mbuf clusters
when dealing with lots of IP fragments.

This sets the default to 25% of the mbuf cluster maximum (hint
from beck). And the example in the manpage is sane now.

ok mikeb henning beck deraadt

it seems previous was wrong, so move prio/tos out of OPTIONS,
and put them into the main filtering section, at least for now;

ok henning

move set prio/tos into OPTIONS; ok henning

one more prio -> set prio; ok henning

Enable support for the 'weight' keyword in the 'least-states'
load balancing case, this allows Weighted Least States (WLS).
Everything prepared on c2k11 with help from mcbride@.

This finally makes PF ready for the cloud.

ok henning@ mikeb@ pyr@

fix some of the confusion we have in pf regarding filter criteria vs
options that "write" to the packet by putting the latter in a set { } block.
for now prio and tos, maintain set-tos backwards compat for the moment.
"match set { prio 6, tos lowdelay }"
"match set prio 6"
from a discussion with ryan in tokyo a while ago, ok ryan phessler

tcp/udp mandatory for "user"; from ti zed
ok henning

take a stab at documenting when arguments need quoted, and valid macro
characters;

prompted by a diff from robert peichaer org

thanks gilles and henning for feedback
ok deraadt zinke

tweak previous;

document af-to (aka nat64)

the patch was started by todd about a year ago and have been
finally finished by phessler and myself today; discussed with
and tweaks from jmc, ok sthen, henning

Fix description for tcp.opening timeout in pf.conf(5).
Issue reported by Felix Rust; ok jmc@

make "self" a bit more visible
from Sebastian Benoit <benoit-lists at fb12.de>, ok/input jmc, reminder/input
deraadt and too much of a trail to mention all of it, thx everybody involved

Manpage bits for the recent changes in vlan(4) prio handling.

ok jmc henning sthen claudio

Document a "once" filter option used to create one shot rules.

ok henning, mcbride, jmc

fix overload table BNF
From: william dunand <william.dunand at gmail.com>

Sync documentation with code on the matter of max state limit behavior.
When one of the state limits is reached, further packets that would
create state are dropped, until existing states time out. Discussed
with mcbride, ok henning, jmc

sync 'set-tos' with 'tos' keyword (DiffServ is supported by both)

ok deraadt

Remove requirement to quote 'debug' loglevel for the 'debug' option.

ok henning

- new sentence, new line
- zap trailing whitespace

Add support for weighted round-robin in load balancing pools and tables.
Diff from zinke@ with a some minor cleanup.
ok henning claudio deraadt

zap trailing whitespace;

Initial description of 'prio' keyword.

ok henning

jmc found a few more mentions of RIO here

tweak previous;

bye bye require-order.
i added that button many many many years ago since the order (options, scrub,
nat, filter) was enforced back then, which I hated. now we had that turned
off for ages, and with the scrub and nat rulesets being gone, there is very
little reason to enforce an order at all. so let's get rid of it.
introducing this button was one of my very early commits to openbsd... feels
a bit strange to remove it now :)
ok ryan dlg theo

bring in least-states load balancing algorithm

ok mcbride@ henning@

Use a common text explaining how the various configuration parsers using
the standard OpenBSD-style parse.y handle continuing lines with backslashes,
paying particular attention to how comments are handled (which can cause
nasty side-effects if you're not expecting it).

Most wording from jmc@, with suggestions from fgsch@, marc@, Richard Toohey,
patrick keshishian and Florian Obser, ok jmc@.

Point out that the 'set skip' interfaces are currently only evaluated at
config load time. This may change in future but for now it's better to
document it.

update BNF for "set limit"; from Lawrence Teo
ok henning

Documentation for "on rdomain <number>". OK henning@

remove mention of fastroute here as well
'you are not allowed to speak until you commit' mikeb@

Pf can reassemble IPv6 fragments now.
ok jmc@

- remove an ambiguity regarding the state description. i used part of a
diff from patrick keshishian on misc for this

- document that packets passed by default, matching neither block nor
pass rules, are effectively created with "no state"; as discovered by tedu

...after much discussion on misc and with henning

bit more on reflection, From: James Jerkins <jjerkins at una.edu>
with tweaks from jmc

Fix an example using rdr-to where a couple of hosts were exempted from
the redirect; the sample rule used "match" for the general case which
negated the exemptions. From Harald Dunkel.

According to pf_scrub_ip6() pf does not support the scrub options
no-df, random-id, set-tos for IPv6 rules. Check this in pfctl and
document it in pf.conf(5).
ok henning@ jmc@

fix my last (sloppy) fix; from Thomas Pfaff
ok henning

fix sloppy paste in;

adjust set debug description to reality
From: Thomas Pfaff <tpfaff@tp76.info>

- clarify the "probability" text; based on a diff from Thomas Pfaff
ok henning

- while here, knock out a bad .Pp

oups. the notes i just added looked like shit because i'm too smart too
actually look at the manpage when changing it. ok jmc

tweak previous;

for rdr-to and nat-to, mention in which direction they are usually used
and mention the constraints for use in the "unnatural" direction
ok claudio ryan dlg

document hwo to play with matches

sync divert-packet documentation with reality
PR 6448 pjp at centroid dot eu

redo the list of "sticky" parameters for match rules;

- include translation options
- include "scrub"
- don't include max-mss etc, which aren't used directly rather they
are written like 'match ... scrub (max-mss xxx)'

ok jmc@ henning@

Don't mention translation in the require-order blurb as it is now
part of filtering.

ok henning@

add divert-* to bnf; from Dave Anderson
ok henning

missing "
From: Aivar Jaakson <aivar@cirt.pri.ee>

missing `]'; from Aivar Jaakson

Add missing 'in' in sample rdr-to rule. Noted by Steve Williams.

better word MSS in pf.conf.5, from Lars Nooden;
the changes in pppoe.4 are just to keep things consistent...

First pass at removing the 'pf_pool' mechanism for translation and routing
actions. Allow interfaces to be specified in special table entries for
the routing actions. Lists of addresses can now only be done using tables,
which pfctl will generate automatically from the existing syntax.

Functionally, this deprecates the use of multiple tables or dynamic
interfaces in a single nat or rdr rule.

ok henning dlg claudio

correct the text for received-on; ok dlg

tweak previous;

try to document received-on.

It doesn't make sense to talk about doing packet tagging "during
nat-to or rdr-to in addition to filter rules".

adjust one of the examples/descriptions for nat-to; it used to be
'nat pass' and nearest equivalent now is to use 'pass quick...nat-to'
not just 'pass...nat-to'. ok henning@ jmc@

correct values for set reassemble

ok henning@ pyr@

Adjust the description of network translation to match the code
following the nat-to changes. Reworked slightly from a diff from eric@.
ok henning jmc

Second example discussing the pass modifier with rdr-to
should actually use the pass modifier.

ok henning jmc

Add (again) support for divert sockets. They allow you to:

- queue packets from pf(4) to a userspace application
- reinject packets from the application into the kernel stack.

The divert socket can be bound to a special "divert port" and will
receive every packet diverted to that port by pf(4).

The pf syntax is pretty simple, e.g.:

pass on em0 inet proto tcp from any to any port 80 divert-packet port 1

A lot of discussion have happened since my last commit that resulted
in many changes and improvements.
I would *really* like to thank everyone who took part in the discussion
especially canacar@ who spotted out which are the limitations of this approach.

OpenBSD divert(4) is meant to be compatible with software running on
top of FreeBSD's divert sockets even though they are pretty different and will
become even more with time.

discusses with many, but mainly reyk@ canacar@ deraadt@ dlg@ claudio@ beck@
tested by reyk@ and myself
ok reyk@ claudio@ beck@
manpage help and ok by jmc@

some clarification of "set reassemble" and "no-df"; help/ok henning

floating/if-bound may be used per-rule; ok henning

I had not enough oks to commit this diff.
Sorry.

Add support for divert sockets. They allow you to:

- queue packets from pf(4) to a userspace application
- reinject packets from the application into the kernel stack.

The divert socket can be bound to a special "divert port" and will
receive every packet diverted to that port by pf(4).

The pf syntax is pretty simple, e.g.:

pass on em0 inet proto tcp from any to any port 80 divert-packet port 8000

test, bugfix and ok by reyk@
manpage help and ok by jmc@
no objections from many others.

implement binat-to as a macro-like rule: a rule using the new binat-to
syntax will be expanded by the parser to a nat-to+rdr-to combination
to be loaded into the kernel. this simplifies the migration from old
binat rules and is less error-prone.

feedback from many, manpage bits from jmc@
ok henning@

remove the trans-anchors bnf entry too; ok sthen henning

remove *-anchor bits from BNF; ok sthen

the recent changes to translation make the ordering of this document
slightly redundant: move the packet filtering section to the top,
and make translation a subsection;

ok henning

match in pass is bullshit (conversion error from nat pass), spotted by phessler

all the new *-to options are part of the "filteropts" section at the
end of a pf rule (nat-to, divert-to, rdr-to, ...). take the
historical chance to upgrade the grammar and move the route options to
the filteropts section as well.

for example,
pass in on em0 route-to (em1 192.168.1.1) from 10.1.1.1
becomes
pass in on em0 from 10.1.1.1 route-to (em1 192.168.1.1)

many people like this including pyr@ mk@ kettenis@ todd@ and others
ok henning@

document new pf. mostly from igor, input and bnf by me

Recommit rev. 1.446 it is again possible to use DSCP names in tos and settos
statements.

Please don't commit documentation for changes which don't compile in
the tree. Surely you were involved and noticed that the tree was being
broken.

List the additional TOS values and DiffServ Code Points now recognised
by pfctl(8).

take out a few .Ar macros from the examples.

pointed out by jmc@

use a better layout to improve readability.

ok henning@

correct the bnf for return-rst, and describe the optional ttl parameter
for it;

started by a mail from Laurent Ghigonis
ok fgsch henning

use printf instead of echo for one of the anchor examples - this allows it
to work for users of csh and /bin/echo;

now that require-order is no longer on by default, we can relax the ordering
of this page a little; instead of talking about statement types, just provide
a brief overview of the page;

- use .Dl for short displays
- .Nm does not require args

- restructure the ANCHORS section
- no need to escape quotes within displays

switch the require-order default to "no". regression tests still pass.
ok henning@ deraadt@

tweak ANCHORS;

reduce the verbosity of the two examples sections, and provide some
indent;

ok henning

rearrange/merge the various sections to impose some structure on this page;
ok henning

tweaks for the final sections;

final sort;

tweak NORMALIZATION;

simplify "log (user)"; help/ok henning

tweak PARAMETERS;

sort PARAMETERS; also split the list in two, to make it more manageable;
ok henning deraadt

Don't talk about a "scrub reassemble tcp" rule, talk about "reassemble
tcp" parameter. ok henning@

tweak PACKET FILTERING;

tweak TRANSLATION;

comment out the RIO stuff until such a time as it is enabled; ok henning

code and Backus-Naur Form specification rules must fit on 80-column displays;
while here, remove a few superfluous line breaks in examples.

ok henning@, jmc@

tweak QUEUEING;

sort QUEUEING, and a little list tweaking;

tweak TABLES;

tweak OPTIONS; also there is no need to given an example of every "set"
argument, so remove any examples that were not particularly illustrative;

ok henning

sort OPTIONS;

tweak TABLES;

some improvements for the PACKET FILTERING section;
feedback (i.e. much tearing of hair) and ok henning

bnf-tweaks

don't we all love BNF? make it lie less

nits

catch up with recent changes (scrub, match, ...); still a ways to go
ok henning

fragment reassembly on by default

bit more precise

rewrite the description for the recently added "match" action.

ok henning@

no more normalization statements, remove it from require-order description.
ok henning

documentation changes related with the monster pf diff from basel;
we are mostly documenting that fragment reassembly has nothing to do
with scrubbing anymore; there is room for a lot of improvements yet.

"commit it and we work on it in-tree. it is certainly well,
better than what there is now" henning@

1) scrub rules are completely gone.
2) packet reassembly: only one method remains, full reassembly. crop
and drop-ovl are gone.
. set reassemble yes|no [no-df]
if no-df is given fragments (and only fragments!) with the df bit set
have it cleared before entering the fragment cache, and thus the
reassembled packet doesn't have df set either. it does NOT touch
non-fragmented packets.
3) regular rules can have scrub options.
. pass scrub(no-df, min-ttl 64, max-mss 1400, set-tos lowdelay)
. match scrub(reassemble tcp, random-id)
of course all options are optional. the individual options still do
what they used to do on scrub rules, but everything is stateful now.
4) match rules
"match" is a new action, just like pass and block are, and can be used
like they do. opposed to pass or block, they do NOT change the
pass/block state of a packet. i. e.
. pass
. match
passes the packet, and
. block
. match
blocks it.
Every time (!) a match rule matches, i. e. not only when it is the
last matching rule, the following actions are set:
-queue assignment. can be overwritten later, the last rule that set a
queue wins. note how this is different from the last matching rule
wins, if the last matching rule has no queue assignments and the
second last matching rule was a match rule with queue assignments,
these assignments are taken.
-rtable assignments. works the same as queue assignments.
-set-tos, min-ttl, max-mss, no-df, random-id, reassemble tcp, all work
like the above
-logging. every matching rule causes the packet to be logged. this
means a single packet can get logged more than once (think multiple log
interfaces with different receivers, like pflogd and spamlogd)
.
almost entirely hacked at n2k9 in basel, could not be committed close to
release. this really should have been multiple diffs, but splitting them
now is not feasible any more. input from mcbride and dlg, and frantzen
about the fragment handling.
speedup around 7% for the common case, the more the more scrub rules
were in use.
manpage not up to date, being worked on.

write point-to-point in a consistent way.

jmc@ has provided a complete list of manual pages to be fixed,
and suggested using uppercase (i.e., Point-to-Point) when discussing
the protocol, and lowercase (point-to-point) otherwise.

ok jmc@

document state-defaults option

Mbit/s -> Mbps

pointed out by jmc@

pflow related stuff, reminded by jmc

tweak previous;

Make counters on table addresses optional and disabled by default.
Use the 'counters' table option in pf.conf if you actually need them.
If enabled, memory is not allocated until packets match an address.

This saves about 40% memory if counters are not being used, and paves the way
for some more significant cleanups coming soon.

ok henning mpf deraadt

another wee correction; ok henning

tweak previous;

theo and ryan and I like to scare people

add divert-to/divert-reply; ok henning, pyr

scrub allows tagged, too

allow setting TOS with scrub; ok mcbride, claudio

demonstrate "include" in the bnf; weerd@weirdnet.nl

do not describe `/' as solidus; from Allen (freebsd pr120484);

no more /usr/share/pf;

Document the ability to use filteropts on anchors.

Fix grammar, pointed out by Jim Razmus and RW.

OK jmc.

when "max <number>" is exceeded, packets are not dropped - rather they
fail to match;

from Doichin Dokov
diff from henning and myself

include in bnf, wanted by jmc

support an include directive; file of course must also be "secure" like
the main configuration file; ok henning

while rdr'ing port spamd to portsmtpis perfectly valid, it is at least
a bit confuzzling, so swap.
From: Olli Hauer <ohauer@gmx.de>

Mention "set loginterface <ifgroup>"

document address ranges, with help from jmc@

typo; from Stephan A. Rickauer

checkd -> checked; from Nicholas Marriott

make it clearer where ifgroups can be used
From: Stuart Henderson <stu@spacehopper.org>

convert to new .Dd format;

Document the fact that 'allow-opts' applies to IPv6 now as well.

ok jmc@ dhartmei@ henning@ deraadt@ claudio@

set timeout source-track -> set timeout src.track; from Jason Testart
and a missing full stop...

Basic ruleset optimization is now the default.

Use 'set ruleset-optimization none' or the -o none argument
to prevent pfctl from optimizing the ruleset before loading it.

Correct the explanation of NAT evaluation order. binat is always first,
then rdr on inbound packets or nat on outbound packets. This is _not_
necessarily the same order in which the rules are defined in the ruleset.

ok jmc dhartmei henning

stateles -> stateless; from stuart henderson

bad space;

mention rtable shitz now that it is enabled in the forwarding path

desireable -> desirable;

tweaks;

Document set ruleset-optimization [ none | basic | profile ].

Document inline anchor loading with { } delimited blocks.

tweak;

tweaks; ok henning

eep! unbreak.

Document hostid.

pointed out by Pierre-Yves Ritschard.

document how ot send logs to alternate pflog interfaces

remove trailing space;

Move the stateful content up to the FILTERING section and flesh it out
somewhat to reflect the default 'keep state' behaviour of pf.conf.

prodding by theo, ok jmc@

fix mark up mistake;

Document 'anchor "foo" quick'.

these fixes got lost somehow;

missing fixes for STATEFUL INSPECTION;

kill trailing whitespace;

Document the fact that 'flags S/SA keep state' is now the implicit default,
as well as 'no state' and 'flags any' options.

ok jmc@

for apps which use interface groups, point to the section of
ifconfig(8) where they are explained;

ok mcbride mpf henning

knock out the cpp/m4 stuff from MACROS; after discussion with many...

back out -r1.497 (support for "tagged {}" lists), it broke "tagged" support
for nat rules. sorry, existing functionality trumps syntactic sugar. feel
free to resubmit a complete patch. closes PR 5207.

in the BNF section, note that a comma is optional, closes PR 5191

document "tos": pointed out by maxim bourmistrov
diff from jared r r spiegel

ok dhartmei

The timeout value is called src.track, not source-track.

typo: queu -> queue

ok claudio@

put previous in the correct place; ok mcbride

Adaptive timeouts are now on by default.

interface bandwidths can change; ok henning

update the "tagged" line; ok dhartmei

add support for "tagged {}" lists, from Pierre-Yves Ritschard

- replace <> with .Aq
- replace OpenBSD with .Ox

from wiz@netbsd

implement a Unicast Reverse Path Forwarding (uRPF) check for pf(4)
which optionally verifies that a packet is received on the interface
that holds the route back to the packet's source address. This makes
it an automatic ingress filter, but only when routing is fully
symmetric.

bugfix feedback claudio@; ok claudio@ and dhartmei@

new ftp-proxy

ok jmc markus

Document the "tables" and "table-entries" limit options.

ok jmc@ mcbride@

document "log (user)"

wording help and ok jmc@

in the bnf section, clarify that "fastroute" takes no arguments. also fix
the literal parentheses around the "route/reply/dup-to" arguments.
from Karl O. Pinc, discussed with jmc@ and otto@

replace port number 8025 w/ symbolic `spamd';
ok krw@ deraadt@

diff from ray lai;

document "set skip on" in the BNF grammar, from David Krause

the need to use stateful rules for tagging is gone

(lightly) document carp(4) in reference to state table;

suggested by alexey e. suslikov;
better wording + ok joel@

add an ipv6 example;

from alex kirk;
ok dhartmei@, unless i have badly misunderstood him;

In the BNF section, remove one spurious "proto" and add one missing |.
Found by Magne Andreassen.

s/log-all/log (all)/

support 'log' and 'log-all' in 'nat/rdr/binat pass' rules. original patch
from camield@. use #defines PF_LOG, PF_LOGALL instead of magic constants.
ok frantzen@, camield@

sync with reality

the BNF production is called "load-anchor", found by Magne Andreassen

max-src-states typo; ok henning@

occurance -> occurrence;

support 'tagged' in translation rules, non-delayed tag lookup
ok henning@, deraadt@

Mention that if a cbq/hfsc queue definition doesn't specify 'bandwidth'
that it defauls to 100% of the parent queue. Fix examples to match.

ok dhartmei@

Document the 'source-track' stateful tracking option. Heavy influence
from dhartmei and henning.

ok dhartmei@ henning@ jmc@ jaredy@

Fix some parse errors in example rules

ok henning@ dhartmei@

document icmp type/code text abbreviations recognized by pfctl

prodded by John Ladwig <jladwig@mango.lioness.net>

ok deraadt jmc

Introduce 'set skip on <ifspec>' to support a list of interfaces where no
packet filtering should occur (like loopback, for instance).
Code from Max Laier, with minor improvements based on feedback from
deraadt@. ok mcbride@, henning@

spacing

update to indicate that return-rst generates packets
on bridges. Spotted by Simon Kirby.
proper caps from jmc@

ok dhartmei@

route <label> rewording from otto@;
ok dhartmei@;

Better wording.

Michael Knudsen <e@molioner.dk> says:
"I think you messed something up when you committed this."
and he is right, I lost a word. Dang! And Thanks :)

grammar and a little whitespace;

document matching on route labels
From: Michael Knudsen <e@molioner.dk>
jaredy ok

and the example needs 'proto tcp' if it specifies a port, also from mpech@

overload (not overflow) <table>, at least that's what the parser knows.
found by mpech@

and don't lose the documentation for 'flush global'

tree does not compile, spotted by dlg (not obvious how to fix)
----
Change the default for 'overload <table> flush' to flush only states from the
offending source created by the rule. 'flush global' flushes all states
originating from the offending source. ABI change, requires kernel and pfctl
to be in sync.

ok deraadt@ henning@ dhartmei@

Change the default for 'overload <table> flush' to flush only states from the
offending source created by the rule. 'flush global' flushes all states
originating from the offending source. ABI change, requires kernel and pfctl
to be in sync.

ok deraadt@ henning@ dhartmei@

Cleanup and remove a cut-n-pasto. From jmc@

Document 'max-src-conn', 'max-src-conn-rate', 'overflow <bad> flush'.

Add "probability" to BNF
ok henning, markus

Document "no scrub"; from jmc@, tweaked by me. dhartmei@ ok

s/timeout modulation/timestamp modulation/

ok frantzen@

'random-id' no longer applies only to outgoing packets.

Implement "no scrub" to allow exclusion of specific traffic from scrub rules.
First match wins, just like "no {binat,nat,rdr}". henning@, dhartmei@ ok

mention parent (..) anchors,
mention wildcard (*) anchors,
and mention quotes around anchor names.

ok dhartmei henning jmc

update w.r.t. recursive anchors
and fix an mdoc list display (from jmc)

ok dhartmei henning jmc

differentiate between cbq and hfsc;

problem found by marc@; this diff based on a patch from sven at
sandcat dot nl; ok henning@;

route-to -> reply-to in one case where it was swapped, from
Christopher Pascoe

Use RFC1323 PAWS timestamps as a logical extension to the conventional TCP
sequence numbers by taking advantage of the maximum 1KHz clock as an upperbound
on the timestamp. Typically gains 10 to 18 bits of additional security against
blind data insertion attacks. More if the TS Echo wasn't optional :-(
Enabled with: scrub on !lo0 all reassemble tcp
ok dhartmei@. documentation help from jmc@

Add "probability xxx" rule modifier. ok deraadt@

- fix an .El in the wrong place
- add a .Pp
- kill a stray space
- new sentence, new line

from Joel Knight;

vender -> vendor, from John Bajana-Bacalle

'source-track' not 'source-tracking'

upper case ip;

Document 'set limit src-nodes'

group-locked -> group-bound, from J. Knight

typos;

Many improvements to the handling of interfaces in PF.

1) PF should do the right thing when unplugging/replugging or cloning/
destroying NICs.

2) Rules can be loaded in the kernel for not-yet-existing devices
(USB, PCMCIA, Cardbus). For example, it is valid to write:
"pass in on kue0" before kue USB is plugged in.

3) It is possible to write rules that apply to group of interfaces
(drivers), like "pass in on ppp all"

4) There is a new ":peer" modifier that completes the ":broadcast"
and ":network" modifiers.

5) There is a new ":0" modifier that will filter out interface aliases.
Can also be applied to DNS names to restore original PF behaviour.

6) The dynamic interface syntax (foo) has been vastly improved, and
now support multiple addresses, v4 and v6 addresses, and all userland
modifiers, like "pass in from (fxp0:network)"

7) Scrub rules now support the !if syntax.

8) States can be bound to the specific interface that created them or
to a group of interfaces for example:

- pass all keep state (if-bound)
- pass all keep state (group-bound)
- pass all keep state (floating)

9) The default value when only keep state is given can be selected by
using the "set state-policy" statement.

10) "pfctl -ss" will now print the interface scope of the state.

This diff change the pf_state structure slighltly, so you should
recompile your userland tools (pfctl, authpf, pflogd, tcpdump...)

Tested on i386, sparc, sparc64 by Ryan
Tested on macppc, sparc64 by Daniel

ok deraadt@ mcbride@

- kill whitespace at EOL
- new sentence, new line
- kill blank line
- missing .El
- missing escape
- ip -> IP
- greate -> create

Add support to track stateful connections by source ip. This allows us
to:
- Ensure that clients get a consistent IP mapping with load-balanced
translation/routing rules
- Limit the number of simultaneous connections a client can make
- Limit the number of clients which can connect through a rule

ok dhartmei@ deraadt@

allow ':' (range including boundaries) to be used whereever '><' (range
excluding boundaries) is legal. already supported by kernel, requires only
removal of three error messages. ok henning@

fix load anchor BNF.
from Joel Knight

more literal confusion, "(" ")" vs. ( )
the parentheses are required when using two queue arguments, and
optional when using one.

un-quote "return" where it's meant to reference a bnf production
and not a literal.

update BNF for set debug too, again catched by mpech@

document "set debug"

ok jmc@ cedric@

Add 'no-sync' state option to prevent state transition messages for states
created by this rule from appearing on the pfsync(4) interface. e.g.

pass in proto tcp to self flags S/SA keep state (no-sync)

ok cedric@ henning@ dhartmei@

Add some missing mentions of 'synproxy state'

ok jmc@

document that label macros can now be used in tags as well
with help from and ok jmc@

double word, from Tom Cosgrove;

consistently use $ext_if / $int_if in the examples
from jared r r spiegel <jrrs@ice-nine.org>
ok canacar@ jmc@

typo; ish

filename needs to be quoted...
ok mcbride@ jmc@

escape punctuation;
ok deraadt@

tweak;
ok frantzen@

mention that synproxy state takes the same options as keep/modulate state,
add synproxy to BNF. from mpech@. ok mpech@, henning@

Tables can now be used in round-robin pools.
ok henning@

pf spelling police
ok dhartmei@ jmc@

- roff indent fix from Max Laier. thanks!
- fix an example that became wrong when I switched from p0f v1 fingerprints
to p0f v2

spelling

document passive OS fingerprinting

fix a macro and remove a whitespace at EOL;
ok henning@

clarification in nat pass, pointed out by theo

I'm pretty sure the formatting cleanup & clarifications here that Joel Knight
did in negotiation with jmc@ included some dancing with dead chicken ritual

from Joel Knight
ok jmc@

nat pass
ok jmc@

add adaptive, interval, and frag timeouts to pf.conf and BNF
ok henning@ dhartmei@

qlimit referenced twice from queueopts, PR 3312

ref table-rule from line, PR 3311

document that is is unsupported to use return-rst/icmp or synproxy
on bridging firewalls

henning@ ok, spelling fixes from jmc@

fix grammer regarding queues; noted by jlouis@mongers.org

update BNF to show that tagging is also possible on rdr/nat/binat

second part of the diff from Joel Knight that was sitting in my inbox for
far too long:
better tag documentation.

help and ok jmc@

update BNF to include "! tagged"

document "load anchor from file"
mostly from Joel Knight
help and ok jmc@

make crystal clear that NAT happens before filtering and what that
means for the filter rules.
from Joel Knight again

ok cedric@, silence everybody else

revert to previous BNF formatting; requested by deraadt@
ok deraadt@ dhartmei@
CVSt e---------------------------------------------------------------------

the secgtion is called QUEUEING, not QUEUE RULES, so point people to
QUEUEING and not QUEUE RULES...

found by Joel Knight

consistently uppercase abbreviations;
ok henning@

tweak; 10x jmc

tweak
ok dhartmei@

spelling fix

tweak

document tags
ok henning@

tweak;
ok dhartmei@

TCP SYN proxy. Instead of 'keep state' or 'modulate state', one can use
'synproxy state' for TCP connections. pf will complete the TCP handshake
with the active endpoint before passing any packets to the passive end-
point, preventing spoofed SYN floods from reaching the passive endpoint.

No additional memory requirements, no cookies needed, random initial
sequence numbers, uses the existing sequence number modulators to translate
packets after the handshakes.

ok frantzen@

removed unnecessary macros:
- don't need .Pp before/after .Sh
- don't need .Ns before punctuation

ok krw@ millert@ david@

tweak;
ok frantzen@

document scrub opt "reassemble tcp"

Use an example that acutally makes some sense.

Adaptive timeout value scaling. Allows to reduce timeout values as the
number of state table entries grows, so entries time out faster before
the table fills up. Works both globally and per-rule. ok frantzen@

document the dynamic min-ttl TCP scrub behavior

'return' now causes an ICMP unreachable for non-TCP/UDP/ICMP protocols.

uppercase all non-literals in BNF.. might make some stuff more clear ;)

commitski henning@

quote non-alphabetic literals

'over the desk' oks..

BNF for load anchor stuff

fix formatting in the BNF

BNF update for label on antispoof

document hfsc
mostly from Berk D. Demir <bdd at ieee.org> with tweaks by me
some nits and ok jmc@

port 8081 -> 8021 for ftp-proxy in the examples, so it matches pf.conf
and inetd.conf defaults

added two missing .El macros;

ok henning@

BNF update for hfsc

mention hfsc.
this needs more work.

document queue .. on $interface

ok jmc@

'flags X' is not valid (BNF lied)

henning@ ok

anchors in BNF
(from loki at niteshade . net)

Cleanup for release:

remove some unneeded escaping of spaces "\ "
indent by 6 spaces in a few places to match the rest of the file
fix a few lines that were improperly wrapped or not wrapped to the next line
update sample rule expansion to match current state of pfctl output
fix spacing in a few places
fix a small typo found by jmc@
updated a few example rules so that they parse with current pfctl

ok henning@ jmc@

replace some .Pp inside .Bd -literal block with empty line
remove an uneeded .Pp
kill whitespace at eol

ok jmc@

and bandwidth is bits per second

bits not bytes; fk@spoiled.org

fair amount of clarifications, extensions, and corrections
from joel knight <enabled at myrealbox.com>, some tweaks by me, some by jmc@

ok dhartmei@ mcbride@ cedric@

small changes to mike's random-id section;
ok frantzen@

use Pa for paths more

few minor tweaks

removal of .Ic for examples.
this was messing the postscript output.

- document that scrub 'no-df' is sometimes necessary for "certain" OS's NFS
- suggest 'random-id' with 'no-df' since "certain" OSes set ip->ip_id to zero
ok deraadt@ henning@

date should be written formally: .Dd Month day, year
also fixes a few misspellings of the month
ok henning@ jmc@

Add a paragraph explaining possible unwanted side-effects of redirecting
to the loopback address.

more oops

oops

wrap Ic in Xo/Xc until fixed

leave my cave to clarify the caveats of state modulation
mdoc incantations from jmc@
ok henning@ deraadt@

show example of string concat in macro assign

fix .Bl width, pt out by theo

Fix limit BNF part, since we don't quote token literals, use limit-item,
and limit-list is already a list (due to the recursive definition) which
can also consist of just one entry, so no need for {}.
Found by Maik Kuendig

update BNF for 'queue ( q_def, q_pri )' and similar in filteropts

ok henning@

other.single was missing in the BNF section, from Maik Kuendig

format nicer

lies

make the label example actually work... (missing quotes)

fix .Bl width in translation section

fix width in set block-policy list

pfctl -T create is no more

remove lies about queueing and finally take into account that we have more
than one scheduler, explain a bit more how that works etc etc
english(4) police passed in persona jmc@, ok pb@

we mean: macros are not expanded inside quotes

cbq control keyword is gone

The (optional) priority queue is also used for TCP ACKs without data
payload now.

note that default and control queue must not be identical

typo; Mr. Manpagebeauty Krause. Thanks!

add PRIQ scheduler to BNF

henning@ ok

more krause tweaks

be consistent when listing the different rule type for order requirement

krause

grammar; krause

ok jmc@

new sentence, new line

typos;

setextattr(8): example markus@
spamd(8): someone else found some of these on bugs/misc, but for the life
of me i can't find out who
pf.conf(5): from openbsd@davidkrause.com
raidctl(8): from ian@darwinsys.com

Fix BNF for rdr and nat to match merge of rdr and nat parsing.

queuing -> queueing for consistency

from openbsd@davidkrause.com via henning@

Add random-id to BNF syntax, clean up superflous []
Reported by Dries Schellekens

Add scrub option 'random-id', which replaces IP IDs with random values
for outgoing packets that are not fragmented (after reassembly), to
compensate for predictable IDs generated by some hosts, and defeat
fingerprinting and NAT detection as described in the Bellovin paper
http://www.research.att.com/~smb/papers/fnat.pdf. ok theo@

Add blank space inside '.Xr Ic'.
Spotted by xvenient@free.fr via henning@.

millert@

typo in anchor section
From: Eduardo Augusto Alvarenga <eduardo at thrx.dyndns.org>

nicer indentation in the queue example
inspired by a mail to tech@ from
Eduardo Augusto Alvarenga <eduardo at thrx.dyndns.org>

The network interface is not mandatory for translation rules.

ok dhartmei@

document :network and :broadcast modifiers
help jmc@

Make pf.conf reflect all changes that occured in the last 2 weeks.

s -> z; thanks naddy@

ok deraadt@

Changed: - Am. Eng. -> Br. Eng.
eg. normalization -> normalisation
- examples/commands in white bold face
- .Pa macros -> .Ar
- ordered SEE ALSO
- removed double quotes from GRAMMAR section
- some grammar typos

ok deraadt@

- rework Tables section in the introduction (pointed out by Theo)
- Macros and Tables can appear anywhere in pf.conf
- Since tables are no longer just a rule option, move the section up
appropriately.

ok dhartmei@

Cleanup of TABLES section.

Help with english language jmc@

ok dhartmei@ cedric@

typos;
ok deraadt@

at least mention the PRIQ scheduler.
more to come...

Tipo in tabledef grammar. Found by Rukh <openbsd@rukh.net>

Add support for active/inactive tablesets in the kernel.
Add table definition/initialisation construct in pfctl parser.
Add and fix documentation for pf.4 and pf.conf.5.
Tested on i386 and sparc64 by myself, macppc by Daniel.
ok dhartmei@

Match changes to pfctl and /etc/protocols. ipv6-icmp-type becomes icmp6-type;
"proto ipv6-icmp" still works, but prefer icmp6, since we have icmp6(4),
not ipv6-icmp(4).

ok dhartmei@ henning@

Remove stray 'hosts' on the nat-rule production in BNF, found by
Benjamin M.A. Robson.

More direct explanation of where the port number and protocol number to name
mappings come from.

ok dhartmei@ henning@

More cleanup.

- s/Em/Pa/ where appropriate
- get rid of references to spews and Tomcat
- more simplification by removal of direction
- timeout values are no longer a pfctl(8) thing

yes! henning@

do not mention optimization default, as "set optimization default" is not
parseable. "normal" is exactly the same, so use that.
good catch by David Krause (again).

Fix typo, pointed out by Dries Schellekens

A nudge towards reality:
- direction is now optional
- better way of specifying drop return rules
- wrap some lines which are too long.

ok dhartmei@ henning@

consistency; grange@

how the heck did such a stupid mistake end up in here

nat after queue, good catch by marc@

minor glitch in the queue example

document extended queue syntax
help theo

More nitpicking.
Correct placement of .Pp.
(Europeans do use nroff -mandoc)

deraadt@ henning@ ok

More coherency: rule set(s) -> ruleset(s)

deraadt@ henning@ ok

show user & group correctly

ARRHGHGHGHGHGHGH

document the "all" keyword; Theo