In the single machine setup, life is relatively simple. Traffic created on it should either pass out to the rest of the world or not, and the administrator decides what to let in from elsewhere.

On a gateway, the perspective changes from “me versus the network out there” to “I am the one who decides what to pass to or from all the networks I am connected to”. The machine has at least two network interfaces, each connected to a separate net.

It is very reasonable to think that for traffic to pass from the network connected to xl1 to hosts on the network connected to xl0, a rule like this is needed:

This rule keeps track of states as well.

However, one of the most common and most complained-about mistakes in firewall configuration is not realizing that the “to” keyword does not in itself guarantee passage all the way there. The rule we just wrote only lets the traffic pass in to the gateway on the internal interface. To let the packets get a bit further, a matching rule is needed which says

These rules will work, but they will not necessarily achieve the desired effect.

Rules this specific are rarely needed. For the basic gateway configurations we will be dealing with here, a better rule says

This provides local net access to the Internet and leaves the detective work to the antispoof and scrub code. They are both pretty good these days, and we will get back to them later. For now we just accept the fact that for simple setups, interface-bound rules with in/out rules tend to add more clutter than they are worth to rule sets.

For a busy network admin, a readable rule set is a safer rule set.

For the remainder of this section, with some exceptions, we will keep the rules as simple as possible for readability.

Above, we introduced the interface:network notation. That is a nice piece of shorthand, but the rule set can be made even more readable and maintainable by taking the macro use a tiny bit further.

For example, a $localnet macro could be defined as the network directly attached to your internal interface ($xl1:network in the examples above).

Alternatively, the definition of $localnet could be changed to an IP address/netmask notation to denote a network, such as 192.168.100.1/24 for a subnet of private addresses.

If required, $localnet could even be defined as a list of networks. Whatever the specific needs, a sensible $localnet definition and a typical pass rule of the type

could end up saving you a few headaches. We will stick to that convention from here on.

We assume that the machine has acquired another network card or at any rate there is a network connection from the local network, via PPP or other means. We will not consider the specific interface configurations.

For the discussion and examples below, only the interface names will differ between a PPP setup and an Ethernet one, and we will do our best to get rid of the actual interface names as quickly as possible.

First, we need to turn on gatewaying in order to let the machine forward the network traffic it receives on one interface to other networks via a separate interface. Initially we will do this on the command line with sysctl(8), for traditional IP version four.

If we need to forward IP version six traffic, the command is

In order for this to continue working after the computer has been restarted at some time in the future, enter these settings into /etc/rc.conf:

Use ifconfig -a, or ifconfig interface_name to find out if both of the interfaces to be used are up and running.

If all traffic initiated by machines on the inside is to be allowed, /etc/pf.conf could look roughly like this ^[9]:

Note the use of macros to assign logical names to the network interfaces. Here 3Com cards are used, but this is the last time during this tutorial we will find this of any interest whatsoever. In truly simple setups like this one, we may not gain very much by using macros like these, but once the rule sets grow somewhat larger, you will learn to appreciate the readability this provides.

Also note the nat rule. This is where we handle the network address translation from the non-routable address inside the local net to the sole official address we assume has been assigned.

The parentheses surrounding the last part of the nat rule ($ext_if) are there to compensate for the possibility that the IP address of the external interface may be dynamically assigned. This detail will ensure that network traffic runs without serious interruptions even if the external IP address changes.

On the other hand, this rule set probably allows more traffic to pass out of the network than actually desired. One reasonable setup could contain the macro

and the main pass rule

This may be a somewhat peculiar selection of ports, but it is based on a real life example. Individual needs probably differ at least in some specifics, but this should cover at least some of the more useful services.

In addition, we have a few other pass rules. We will be returning to some of the more interesting ones rather soon. One pass rule which is useful to those of us who want the ability to administer our machines from elsewhere is

or for that matter

whichever is preferred. Lastly we need to make the name service work for our clients:

This is supplemented with a rule which passes the traffic we want through our firewall:

Note the quick keyword in this rule. We have started writing rule sets which consist of several rules, and it is time to take a look at the relationships between the rules in a rule set. The rules are evaluated from top to bottom, in the sequence they are written in the configuration file. For each packet or connection evaluated by PF, the last matching rule in the rule set is the one which is applied. The quick keyword offers an escape from the ordinary sequence. When a packet matches a quick rule, the packet is treated according to the present rule. The rule processing stops without considering any further rules which might have matched the packet. This is very useful when a few isolated exceptions to the general rules are needed.

This rule also takes care of NTP, which is used for time synchronization. One thing common to both protocols is that they may under certain circumstances communicate alternately over TCP and UDP.

Enabling FTP transfers through your gateway is amazingly simple, thanks to the FTP proxy program (called ftp-proxy(8)) included in the base system on FreeBSD and other systems which offer PF.

The FTP protocol being what it is, the proxy needs to dynamically insert rules in your rule set. ftp-proxy(8) interacts with your configuration via a set of anchors where the proxy inserts and deletes the rules it constructs to handle your FTP traffic.

To enable ftp-proxy(8), add this line to /etc/rc.conf:

Starting the proxy manually by running /usr/sbin/ftp-proxy allows testing of the PF configuration changes we are about to make.

For a basic configuration, only three elements need to be added to /etc/pf.conf. First, the anchors:

The proxy will insert the rules it generates for the FTP sessions here. A pass rule is needed to let FTP traffic in to the proxy.

Now for the actual redirection. Redirection rules and NAT rules fall into the same rule class. These rules may be referenced directly by other rules, and filtering rules may depend on these rules. Logically, rdr and nat rules need to be defined before the filtering rules.

We insert our rdr rule immediately after the nat rule in /etc/pf.conf

In addition, the redirected traffic must be allowed to pass. We achieve this with

where $proxy expands to the address the proxy daemon is bound to.

Save pf.conf, then load the new rules with

At this point, users will probably begin noticing that FTP works before they have been told.

This example covers a basic setup where the clients in the local net need to contact FTP servers elsewhere. The basic configuration here should work well with most combinations of FTP clients and servers. As shown in the man page, the proxy's behavior can be changed in various ways by adding options to the ftpproxy_flags= line. Some clients or servers may have specific quirks that must be compensated for in the configuration, or there may be a need to integrate the proxy in specific ways such as assigning FTP traffic to a specific queue. For these and other finer points of ftp-proxy(8) configuration, start by studying the man page.

For ways to run an FTP server protected by PF and ftp-proxy(8), look into running a separate ftp-proxy in reverse mode (using -R), on a separate port with its own redirecting pass rule.

The obvious question then becomes, if ICMP is such a good and useful thing, should we not let it all through, all the time? The answer is “It depends”.

Letting diagnostic traffic pass unconditionally of course makes debugging easier, but also makes it relatively easy for others to extract information about your network. That means that a rule like

might not be optimal if the internal workings of the local network should be cloaked in a bit of mystery. In all fairness it should also be said that some ICMP traffic might be found quite harmlessly riding piggyback on keep state rules.

The easiest solution could very well be to let all ICMP traffic from the local net through and stop probes from elsewhere at the gateway:

Stopping probes at the gateway might be an attractive option anyway, but let us have a look at a few other options which will show some of PF's flexibility.

The rule set we have developed so far has one clear disadvantage: common troubleshooting commands such as ping(8) and traceroute(8) will not work. That may not matter too much to end users, and since it was ping which scared people into filtering or blocking ICMP traffic in the first place, there are apparently some people who feel we are better off without it. If you are in my perceived target audience, you will be rather fond of having those troubleshooting tools avalable. With a couple of small additions to the rule set, they will be. ping(8) uses ICMP, and in order to keep our rule set tidy, we start by defining another macro:

and a rule which uses the definition,

More or other types of ICMP packets may need to go through, and icmp_types can be expanded to a list of those packet types that are allowed.

traceroute(8) is another command which is quite useful when users claim that the Internet is not working. By default, Unix traceroute uses UDP connections according to a set formula based on destination. The rule below works with traceroute on all unixes I've had access to, including GNU/Linux:

Experience so far indicates that traceroute implementations on other operating systems work roughly the same. Except, of course, on Microsoft Windows. On that platform, TRACERT.EXE uses ICMP ECHO for this purpose. So to let Windows traceroutes through, only the first rule is needed. Unix traceroute can be instructed to use other protocols as well, and will behave remarkably like its Microsoft counterpart if -I is used. Check the traceroute(8) man page (or its source code, for that matter) for all the details.

Under any circumstances, this solution was lifted from an openbsd-misc post. I've found that list, and the searchable list archives (accessible among other places from http://marc.theaimsgroup.com/), to be a very valuable resource whenever you need OpenBSD or PF related information.

Internet protocols are designed to be device independent, and one consequence of device independence is that the optimal packet size for a given connection cannot always be predicted reliably. The main constraint on packet size is called the Maximum Transmission Unit, or MTU, which sets the upper limit on the packet size for an interface. ifconfig(8) shows the MTU for the network interfaces.

Modern TCP/IP implementations expect to be able to determine the right packet size for a connection through a process which, simply put, involves sending packets of varying sizes with the “Do not fragment” flag set, expecting an ICMP return packet indicating “type 3, code 4” when the upper limit has been reached. Now do not dive for the RFCs right away. Type 3 means “destination unreachable”, while code 4 is short for “fragmentation needed, but the do-not-fragment flag is set”. So if connections to networks which may have other MTUs than the local network seem sub-optimal, and there is no need to be that specific, the list of ICMP types can be changed slightly to let the “destination unreachable” packets through, too:

As we can see, this means we do not need to change the pass rule itself:

PF allows filtering on all variations of ICMP types and codes. For those who want to delve into what to pass (or not) of ICMP traffic, the list of possible types and codes are documented in the icmp(4) and icmp6(4) man pages. The background information is available in the RFCs ^[10].

At this point, we have tables which will be filled by our overload rules, and since we could reasonably expect our gateways to have months of uptime, the tables will grow incrementally, taking up more memory as time goes by.

Sometimes an IP address that was blocked last week due to a brute force attack was in fact a dynamically assigned one, which is now assigned to a different ISP customer who has a legitimate reason to try communicating with hosts in the local network.

Situations like these were what caused Henning Brauer to add to pfctl the ability to expire table entries not referenced in a specified number of seconds (in OpenBSD 4.1). For example, the command

will remove <bruteforce> table entries which have not been referenced for 86400 seconds.

Before pfctl acquired the ability to expire table entries, Henrik Gustafsson had written expiretable, which removes table entries which have not been accessed for a specified period of time.

One useful example is to use the expiretable program as a way of removing outdated <bruteforce> table entries.

For example, let expiretable remove <bruteforce> table entries older than 24 hours by adding an entry containing the following to /etc/rc.local:

expiretable is in the Ports Collection on FreeBSD as security/expiretable.

Can Erkin Acar's pftop makes it possible to keep an eye on what passes into and out of the network. pftop is available through the ports system as sysutils/pftop. The name is a strong hint at what it does - pftop shows a running snapshot of traffic in a format which is strongly inspired by top(1).

Not to be confused with the spamd daemon which comes bundled with spamassassin, the PF companion spamd was designed to run on a PF gateway to form part of the outer defense against spam. spamd hooks into the PF configuration via a set of redirections.

The main point underlying the spamd design is the fact that spammers send a large number of messages, and the probability that you are the first person receiving a particular message is incredibly small. In addition, spam is mainly sent via a few spammer friendly networks and a large number of hijacked machines. Both the individual messages and the machines will be reported to blacklists fairly quickly, and this is the kind of data spamd can use to our advantage with blacklists.

What spamd does to SMTP connections from addresses in the blacklist is to present its banner and immediately switch to a mode where it answers SMTP traffic one byte at the time. This technique, which is intended to waste as much time as possible on the sending end while costing the receiver pretty much nothing, is called tarpitting. The specific implementation with one byte SMTP replies is often referred to as stuttering.

Our gateway does not feel quite complete without a few more items in the configuration which will make it behave a bit more sanely towards hosts on the wide net and our local network.