pgl-Technical

How pgl works

This page is about the internal working of pgl, intended for developers and advanced users. The more general documentation for end-users is here.

pgl consists of three components: pgld, pglcmd and pglgui. The core of pgl is the daemon pgld. Based on blocklists with IP ranges pgld checks packets (internet traffic), which are sent to the iptables NFQUEUE (or the deprecated QUEUE) target. iptables is part of the netfilter packet filtering framework inside the Linux kernel. pglcmd takes care of setting up a correct iptables environment. If the necessary netfilter support is not built in the kernel directly, pglcmd tries to load the kernel modules.

If a packet matches the blocklist, pgld can DROP or MARK it. If pgld marks a packet, further iptables rules that match this MARK decide what happens with them. Per default marking is on: allowed packets (IP is not in the blocklist) get the MARK "20" (shown as 0x14 by iptables) and blocked packets (IP is in the blocklist) get the MARK "10" (0xa).

Marked packets repeat the hook function (NF_REPEAT). So they are sent back to the head of the iptables chain again. A packet may only bear one mark, so there mustn't be any other applications / iptables rules that mark packets. Otherwise the setup will not work and packets will loop forever.

Per default "Marked block" outgoing packets will be REJECTED, "Marked block" incoming and forwarded packets will be DROPped. "Marked accept" packets will be ignored by pgl's iptables setup, so other iptables rules decide what happens to them.

WARNING: Users with other firewalls (iptables rules)

pgl doesn't conflict with other firewalls (iptables rules). But if you use them, you have to take special care to avoid severe conflicts. Make sure the following three conditions hold:

1. pgl marks non-matched (IP is not in the blocklist) packets. The marking feature is on per default.
2. Other firewalls must not mark packets.
3. pgl is started after other firewalls. If other firewalls are started/reloaded after pgl, then you may need to restart pgl again. You will be fine, if the iptables rules which send traffic to the iptables chains (pgl_in, pgl_fwd and pgl_out) stand before all other iptables rules which ACCEPT traffic. To help you achieve this, a very simple watchdog restarts pgl if it detects any problems. Nevertheless a manual restart is still recommended, whenever another application changed the iptables setup.