README for pgl                                      Thu Oct 31 23:32:11 CET 2013

================================================================================

Table of Contents:

1.) Description
2.) Features pglcmd
3.) Usage pglcmd
4.) Options pglcmd
5.) Configuration pglcmd
6.) pglgui

See also pgl/INSTALL for installation instruction and requirements.

================================================================================

1.) Description:

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
feature.


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
  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 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
  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.
- 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 if necessary 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 occurrences 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