README for pgl Thu Oct 31 23:32:11 CET 2013
Table of Contents:
2.) Features pglcmd
3.) Usage pglcmd
4.) Options pglcmd
5.) Configuration pglcmd
See also pgl/INSTALL for installation instruction and requirements.
PeerGuardian is a privacy oriented firewall application. It blocks connections
to and from hosts specified in huge blocklists (thousands or millions of IP
ranges). Its origins lie in targeting aggressive IPs while you use P2P.
pgl is based on the Linux kernel netfilter framework and iptables.
You can get it at http://sourceforge.net/projects/peerguardian/
WARNING: pgl may block your complete network/internet access! Using too many
and/or inappropriate lists may seriously degrade your internet service.
pgl starts automatically at system boot per default. Some preconfigured
blocklists are used and will be updated once a day. These blocklists may block
much more than what you want. This may result in a strongly limited network
availability - including your own LAN, gateway and DNS server, many webpages,
services like eMail, instant messaging or the "weather applet" and your
machine's accessibility from the internet.
There are many configuration options to prevent this. Per default pglcmd
already takes care of allowing (whitelisting) LAN traffic, DNS server and
loopback device. If you are on a public LAN, you probably want to disable this
WARNING: Users with firewall (iptables rules)
pgl does not conflict with other firewalls (iptables rules) as long as you make
sure the following two conditions hold:
- Other firewalls must not MARK packets.
- 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_out and pgl_fwd) stand before all other iptables rules which
To help you achieve this, pglcmd.wd restarts pgl if it detects any problems.
But it's still recommended to restart pgl manually, whenever another
application changed the iptables setup.
pgld checks traffic (packets) that is sent to the iptables NFQUEUE target. If
the necessary netfilter support is not built in the kernel directly, pglcmd will
load the necessary kernel modules. If they are not available, pgld can not be
If a packet matches the blocklist, then pgld MARKs the packet. Blocked packets
get the MARK "10", which is shown as "0xa" by iptables.
If a packet doesn't match the blocklist, then pgld MARKs the packet. Allowed
packets get the MARK "20", which is shown as "0x14" by iptables.
A MARKed packet repeats the hook function (NF_REPEAT). So it is sent back to
the head of the iptables chain again. This means it enters the chain INPUT,
OUTPUT or FORWARD again, but this time bearing a MARK. Then further iptables
rules that match the MARK decide what happens with the packets.
Per default pglcmd sets iptables rules to REJECT outgoing packets, and to DROP
incoming and forwarded packets, if they were "marked block". If they were
"marked allow", pglcmd's iptables setup just ignores them, so other iptables
rules decide what happens to them.
A packet may only bear one MARK, so there mustn't be any other applications or
iptables rules that MARK packets. Otherwise the setup will not work and the
packet will loop forever.
2.) Features pglcmd:
- Start and stop pgl. Or let either SysV init or systemd do this for you.
- Update your blocklists from online sources. Or let cron do this automatically.
Backups will be used if a problem occurs. Additionally you may use your local
- Examine your selected blocklists by searching the single blocklists for
- Remove lines by keyword from the blocklists.
- Handle your iptables rules: use a default setup, easily allow all traffic on
specific ports and use an allow list, or add your own sophisticated iptables
- Allow all LAN traffic and the DNS server automatically. If you are on a public
LAN, you probably want to disable this feature.
- Check the status and test the IP block daemon.
- A watchdog monitors pgl and restarts it if necessary.
- Detects if kernel modules are needed and loads them if necessary.
- Set verbosity and logging options.
- Daily rotation of the logfiles.
3.) Usage pglcmd:
pglcmd search PATTERN
4.) Options pglcmd:
inserts iptables rules, starts pgld and the watchdog. If the blocklist
configuration changed, rebuilds the master blocklist.
deletes iptables rules and stops pgld.
starts the watchdog.
stops the watchdog.
rebuilds the master blocklist if necessary and reloads pgld if it is running.
updates the blocklists, rebuilds the master blocklist and reloads pgld if it
like restart, but forces to rebuild blocklist
like reload, but forces to rebuild blocklist
like update, but forces to download blocklists again
gives the iptables settings and the status of pgld and the watchdog.
does a simple test to check if pgl is working (pings a random IP from the
blocklist, checks if this IP was logged in the logfile, and if the IP
outputs the occurences of a keyword and the names of the single blocklists.
reports pgld's statistics.
resets pgld's statistics.
shows the current configuration settings.
Note for blocklist operations: When the master blocklist is built, missing
single blocklists are downloaded. If any blocklist fails to download, and if
there is no old version available, the operation aborts. If a downloaded
blocklist fails to extract, it is deleted and the operation aborts.
5.) Configuration pglcmd:
Remote blocklists are configured in BLOCKLISTS_LIST (/etc/pgl/blocklists.list).
Local blocklists are placed in LOCAL_BLOCKLIST_DIR (/etc/pgl/blocklists.local/).
Most things are done in pglcmd.conf (/etc/pgl/pglcmd.conf). Refer to
pglcmd.defaults (/usr/lib/pgl/pglcmd.defaults) for the complete set of possible
configuration variables with comments.
The allow list for IP ranges is allow.p2p (/etc/pgl/allow.p2p). Per default, the
allowlist is used for incoming and outgoing connections. If desired different
allow lists for incoming, outgoing and forward connections may be used.
pglgui works on top of pgld and pglcmd. It requires dbus.
Start it with "pglgui --tray" to dock it directly in the system tray.
The pglgui configuration is in ~/.config/pgl/pglgui.conf