README for pgl Fri Aug 12 19:00:06 CEST 2011
================================================================================
Table of Contents:
1.) Description
2.) Features pglcmd
3.) Usage pglcmd
4.) Options pglcmd
5.) Configuration pglcmd
6.) pglgui
See also pgl/README for installation instruction and requirements.
================================================================================
1.) Description:
PeerGuardian Linux (pgl) is a privacy oriented firewall application. It blocks
connections to and from hosts specified in huge blocklists (thousands or
millions of IP ranges). 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
feature.
WARNING: Users with firewall (iptables rules)
pgl does not conflict with other firewalls (iptables rules) as long as you make
sure the following three conditions hold:
- pgl marks non-matched (IP is not in the blocklist) packets. (The marking
feature is on per default in pglcmd.)
- Other firewalls do not mark packets.
- pgl is started after other firewalls. If other firewalls are
started/reloaded after pgl, then you 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
ACCEPT traffic.
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.
Technical note:
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
started.
If a packet matches the blocklist, then pgld DROPs it directly. If configured
pgld MARKs the packet instead. Per default the MARKing feature is on if you use
pglcmd. So blocked packets get the MARK "10", which is shown as "0xa" by
iptables.
If a packet doesn't match the blocklist, then pgld ACCEPTs it directly. If
configured pgld MARKs the packet instead. Per default the MARKing feature is on
if you use pglcmd. So 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.
It is strongly recommended to use the MARKing feature, because this allows to
integrate pgl with other firewalls.
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 init do this automatically.
- 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
blocklists.
- Examine your selected blocklists by searching the single blocklists for
keywords.
- 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
rules.
- 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.
- Provides LSB 3.1 compatible init script.
- Daily rotation of the logfiles.
================================================================================
3.) Usage pglcmd:
pglcmd OPTION
pglcmd search PATTERN
================================================================================
4.) Options pglcmd:
start
inserts iptables rules, starts pgld and the watchdog. If the blocklist
configuration changed, rebuilds the master blocklist.
stop
deletes iptables rules and stops pgld.
start_wd
starts the watchdog.
stop_wd
stops the watchdog.
restart
restarts pgld.
reload
rebuilds the master blocklist and reloads pgld if it is running.
update
updates the blocklists, rebuilds the master blocklist and reloads pgld if it
is running.
force-restart
like restart, but forces to rebuild blocklist
force-reload
like reload, but forces to rebuild blocklist
force-update
like update, but forces to download blocklists again
status
gives the iptables settings and the status of pgld and the watchdog.
test
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
answered).
search
outputs the occurences of a keyword and the names of the single blocklists.
stats
reports pgld's statistics.
reset_stats
resets pgld's statistics.
show_config
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.
================================================================================
6.) pglgui
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
